@magmacomputing/tempo-plugin-ai

Tempo community plugin for LLM-powered natural language date, schedule, and context processing.

This plugin bridges deterministic date math and unstructured NLP inputs, leveraging LLMs (Gemini, Groq, OpenAI, Ollama) to asynchronously parse complex natural language expressions into type-safe Tempo instances.

🔒 Security Notice: Raw LLM API keys must never be exposed in client-side browser bundles or client storage (localStorage, sessionStorage, IndexedDB). BYOK is only safe on backend servers or edge runtime proxies.

⚡ Quick Start

📦 Installation

npm install @magmacomputing/tempo-plugin-ai

🎯 Usage

import { parseAI, initAI } from '@magmacomputing/tempo-plugin-ai';

// Initialize with your API keys
await initAI({
  providers: [
    { id: 'groq', key: process.env.GROQ_API_KEY! }
  ]
});

// Parse natural language into a standard Tempo instance!
const dt = await parseAI("The penultimate Tuesday before Thanksgiving in 2026");

console.log(dt.format('{yyyy}-{mm}-{dd}')); // 2026-11-17
console.log(dt.ai?.provider);               // 'groq'
console.log(dt.ai?.confidence);             // 0.98

📚 AI Endpoint Catalog

| Endpoint | Description | Doc | | :--- | :--- | :---: | | parseAI | Parse relative/point-in-time dates (e.g. "next Friday at 4pm") | | | formatAI | Format contextual narrative dates & relative countdowns | | | extractAI | Extract embedded temporal entities & calendar events from prose | | | recurrenceAI | Convert repeating patterns (e.g. "every 2 weeks on Friday") to RRULEs | | | scheduleAI | Book appointment slots around busy calendar event bounds | | | diffAI | Calculate natural language difference & business days between dates | | | contextAI | Infer timezone, locale, and calendar from user profiles/bios | |

✨ Features & Architecture

• 🤖 Multi-Provider Routing: Native support for Groq, OpenAI, Gemini, Mistral, and local Ollama nodes with automatic fallback.
• 🌐 Dynamic Provider Manifest: Model IDs and endpoints are lazily updated via hosted JSON manifests with 1500ms fail-open air-gapped fallbacks.
• ⚡ Two-Tier Caching: Combines fast local in-memory LRU caching (BoundedCache) with optional async storage adapters (AiCacheAdapter for Redis / Cloudflare KV).
• ⏱️ Cascading TTL Policies: Granular TTL control at call-site, provider, or global levels for TTL-enforcing storage adapters.
• 🛡️ Fail-Safe Confidence Bounds: Configurable minConfidence thresholds and array batch processing with soft-error handling.

📚 Complete Guides

For complete API references, architecture guides, and advanced examples: 📖 Read the Official AI Plugin Documentation

⚖️ Licensing

This is a Community plugin. It is completely free and open-source for personal and commercial use under the MIT license.