@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, OPFS). We recommend zero browser storage for API credentials; 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

⚡ Try this live in the interactive Tempo Sandbox ↗

📚 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

🔒 Security, Privacy & Transparency

• 🌐 Direct Provider Communication: By default, requests are dispatched directly from your application runtime to official provider endpoints (OpenAI, Google Gemini, Anthropic, Groq, or local Ollama). When custom endpoint URLs or AI Gateways are configured, requests route directly to your specified destination. There are no hidden intermediary services, no third-party telemetry, and zero tracking.
• 🛡️ Zero Data Retention: Prompts, input expressions, and temporal context are processed ephemerally and are never stored, logged, or retained outside of your own runtime memory or explicitly configured cache adapters.
• 🔑 Scoped Environment Lookups: Auto-discovery only reads standard, documented provider variables (OPENAI_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY, TEMPO_AI_KEY). No other system environment variables are inspected.
• 📦 Client-Side Safety: BYOK API keys are designed exclusively for server, edge runtime, or secure container environments and should never be exposed in client-side browser bundles.

⚖️ Licensing

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