@magmacomputing/tempo-plugin-ai

Tempo community plugin for LLM-powered natural language date parsing, schedule compilation, and temporal processing.

This plugin bridges the gap between deterministic date-math and unstructured NLP inputs, utilizing large language models (like Gemini, Groq, or OpenAI) to safely and asynchronously parse, format, and process complex natural language temporal expressions into Tempo instances.

🔒 Security Notice

Raw LLM API keys must never be exposed in client-side browser bundles or stored in browser storage (localStorage, sessionStorage, IndexedDB, or browser cache). BYOK (Bring Your Own Key) is only secure on backend servers (Node, edge workers). For public frontend applications, route requests through a secure backend proxy service.

Installation & Quickstart

npm install @magmacomputing/tempo-plugin-ai

1. Tempo.ai Cohesive Namespace

Installing AiPlugin mounts the frozen Tempo.ai static action namespace onto Tempo:

import { Tempo } from '@magmacomputing/tempo';
import { AiPlugin } from '@magmacomputing/tempo-plugin-ai';

Tempo.use(AiPlugin);

// Tempo.ai is immediately available:
const event = await Tempo.ai.parse("next Tuesday around 2:30pm");

Auto-Installation (Side-Effect Import)

import { Tempo } from '@magmacomputing/tempo';
import '@magmacomputing/tempo-plugin-ai/install';

const event = await Tempo.ai.parse("next Tuesday around 2:30pm");

2. Zero-Config Mode (Instant Execution)

If you have standard provider keys in your environment (GROQ_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY), simply call any AI function directly with zero boilerplate:

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

// Automatically discovers GROQ_API_KEY / OPENAI_API_KEY from the environment
const dt = await parseAI("The penultimate Tuesday before Thanksgiving in 2026");
console.log(dt.format('{yyyy}-{mm}-{dd}')); // 2026-11-17

3. Explicit Provider Farm Configuration

For custom models, custom SLAs, or multi-provider execution strategies:

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

// Explicitly configure provider farm & fallback strategy
await initAI({
  mode: AiMode.Fallback,
  providers: [
    { id: 'groq', key: process.env.GROQ_API_KEY },
    { id: 'openai', key: process.env.OPENAI_API_KEY, model: 'gpt-4o' }
  ],
  timeout: 5000
});

const dt = await parseAI("The penultimate Tuesday before Thanksgiving in 2026");
console.log(dt.format('{yyyy}-{mm}-{dd}')); // 2026-11-17

AI Function Catalog

All AI functions return a standard ES Promise wrapped object.

Function	Input	Returns (Promise<...>)	Description	Doc
parseAI	Natural language text string(s)	Tempo | Tempo[] | (Tempo | TempoAiError)[]	Single point-in-time Tempo instance (or batch array)
formatAI	Date-time + prompt / style	TempoAiFormatResult | TempoAiFormatResult[] | (TempoAiFormatResult | TempoAiError)[]	Contextual narrative date formatting (formatted, confidence, provider, reasoning)
extractAI	Unstructured text string(s)	TempoAiExtractResult | TempoAiExtractResult[] | (TempoAiExtractResult | TempoAiError)[]	Extracted temporal entities & calendar events (events: TempoExtractedEvent[], confidence, reasoning)
recurrenceAI	Natural language pattern or RRULE string	TempoRecurrenceResult	Iterable series of Tempo dates (with .take(n), [Symbol.iterator], & RRULE string)
scheduleAI	Booking prompt + busy constraints	TempoScheduleResult	Resolved appointment slot (start, end, slot, alternatives, ai.conflictBumped)
diffAI	Start & End dates + prompt	TempoAiDiffResult | TempoAiDiffResult[] | (TempoAiDiffResult | TempoAiError)[]	Narrative time delta & business days (formatted, businessDays, days, hours, holidays)
contextAI	Context text string(s)	TempoContext | TempoContext[] | (TempoContext | TempoAiError)[]	Inferred regional context (timeZone, locale, calendar, sphere)
initAI	Provider config & API keys	void	Configured AI provider farm

Summary of Distinct Return Contracts

To streamline error handling and data consumption, return shapes across the AI plugin follow three distinct contracts:

Category	Functions	Return Type	Single Query Low-Confidence / Failure	Batch Array softErrors: true Contract
Point-in-Time Date	parseAI	Tempo (with .ai)	Throws TempoAiError (or returns invalid Tempo if minConfidence threshold unmet)	Returns invalid Tempo (isValid === false) in array position
Structured AI Objects	formatAI extractAI diffAI contextAI	TempoAiFormatResult TempoAiExtractResult TempoAiDiffResult TempoContext	Throws TempoAiError (422 for low confidence, 429 for quota, 500 for network)	Returns typed TempoAiError object directly in array position
Intervals & Generators	scheduleAI recurrenceAI	TempoScheduleResult (Proxied Interval<Tempo>) TempoRecurrenceResult (.take(n))	Throws TempoAiError (Single item query only)	N/A (Single query operations)

Architecture & Infrastructure Guides

IMPORTANT

Production Recommendation: Due to the complexities of LLM APIs, including caching gotchas, context injection, rate limits, and calendar math hallucinations, we politely but strongly recommend reading the dedicated guides below before deploying this plugin in a production environment.

• Security & Privacy Architecture (Smart Debug Telemetry, PII Masking, HTTPS & Proxy Introspection)
• Multi-Provider Execution Modes (Hedged, RoundRobin, Adaptive, Race, Consensus, Fallback)
• Provider Architecture & Security (BYOK vs Proxy patterns, Browser Security, TLS 1.3 & Privacy Guarantees)
• Grounding & Natural Language Parsing (How Timezone and Locale are injected)
• Rate Limits & Cache Management (Tracking API quotas, handling 429 errors, and custom Redis caches)

Community Feedback & Production Notice

NOTE

Community Feedback & Prompt Engineering While @magmacomputing/tempo-plugin-ai utilizes deterministic grounding, schema enforcement, and confidence validation, LLM outputs can vary across models and prompt styles. We actively welcome community feedback and prompt optimizations—please report any edge cases or suggestions on the Magma GitHub Issue Tracker.

Production Notice & "As-Is" Disclaimer: Magma Computing Solutions and the Tempo core maintainers provide @magmacomputing/tempo-plugin-ai "as-is" without warranty of any kind. Large Language Models operate probabilistically; developers and system architects are responsible for validating AI-generated temporal outputs before committing them to financial, legal, medical, or life-critical applications.

Licensing

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