support for Magma AI Proxy

.agent/rules/plan-execution.md

@@ -0,0 +1,12 @@
+# Plan & Development Execution Rules
+
+## 1. Interactive Pair-Programming (Default Mode)
+During standard interactive conversations, code discussions, and step-by-step refactoring:
+- **ALWAYS use native file editing tools (`replace_file_content` and `write_to_file`)** for creating and modifying files.
+- This provides visual line-by-line diff previews and interactive approval checkboxes directly in the user's IDE UI.
+
+## 2. Autonomous Background Execution (AFK / `/ok` Mode)
+When the user explicitly approves an implementation plan for autonomous background execution (e.g. by typing `/ok` or clicking "Ok to proceed"):
+- Validate approval state, verify the identity of the currently approved implementation plan, and validate command scope prior to enabling `SafeToAutoRun` or invoking `run_command`.
+- Destructive commands or actions with external side effects must remain interactive unless explicitly authorized in the approved plan.
+- For non-destructive operations covered by the approved plan, set `SafeToAutoRun: true` and use terminal shell operations (`run_command`) or file tools for unblocked execution.

.agent/workflows/ok.md

@@ -0,0 +1,6 @@
+---
+description: Ok to proceed with your Plan
+---
+// turbo-all
+
+Verify active approval state and validate command scope against the approved plan before invoking execution. Ok to proceed with the approved plan.

.github/ISSUE_TEMPLATE/bug_report_ai.yml

@@ -0,0 +1,74 @@
+name: "🐛 Bug Report: parseAI Plugin"
+description: Report an issue or unexpected date parsing result with the parseAI plugin
+title: "[parseAI]: "
+labels: ["bug", "plugin:ai", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for helping refine `@magmacomputing/tempo-plugin-ai`! Since this plugin is currently experimental, detailed reproduction details help us stabilize context resolution and prompt engineering.
+
+  - type: input
+    id: environment
+    attributes:
+      label: Version & Environment
+      placeholder: "e.g., tempo-plugin-ai v0.2.0, tempo v3.11.0, Node.js v20.11"
+    validations:
+      required: true
+
+  - type: dropdown
+    id: provider
+    attributes:
+      label: AI Provider
+      options:
+        - OpenAI (gpt-4o / gpt-4o-mini / gpt-5.4-mini)
+        - Azure OpenAI
+        - Custom LLM Proxy
+        - Native Fallback
+    validations:
+      required: true
+
+  - type: textarea
+    id: input_query
+    attributes:
+      label: Natural Language Input Phrase
+      description: What string was passed to parseAI()?
+      placeholder: 'e.g. "The penultimate Tuesday before Thanksgiving in 2026"'
+    validations:
+      required: true
+
+  - type: textarea
+    id: context
+    attributes:
+      label: Context & Options
+      description: Provide relevant options (timeZone, locale, calendar, anchor date, etc.).
+      placeholder: '{ timeZone: "America/New_York", anchor: "2026-11-01" }'
+    validations:
+      required: false
+
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Expected vs. Actual Result
+      placeholder: |
+        Expected: 2026-11-17T00:00:00-05:00
+        Actual: 2026-11-24T00:00:00-05:00 (or TempoAiError)
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Minimal Reproduction Code
+      description: Include a snippet showing initAI() and parseAI() invocations. DO NOT include real API keys or private endpoints!
+      render: typescript
+      placeholder: |
+        import { Tempo } from '@magmacomputing/tempo';
+        import { parseAI, initAI } from '@magmacomputing/tempo-plugin-ai';
+
+        // DO NOT INCLUDE REAL API KEYS OR PRIVATE ENDPOINTS BELOW
+        initAI({
+          providers: [{ id: 'openai', key: 'YOUR_API_KEY_HERE' }]
+        });
+
+        const res = await parseAI("The penultimate Tuesday before Thanksgiving in 2026");

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempo-monorepo",
-  "version": "3.10.2",
+  "version": "3.11.0",
   "private": true,
   "engines": {
     "node": ">=20.0.0"
@@ -36,10 +36,10 @@
   "devDependencies": {
     "@js-temporal/polyfill": "^0.5.1",
     "@rollup/plugin-node-resolve": "^16.0.3",
-    "@types/google.maps": "^3.65.2",
+    "@types/google.maps": "^3.65.3",
     "@types/hammerjs": "^2.0.46",
     "@types/jquery": "^4.0.0",
-    "@types/node": "^26.0.1",
+    "@types/node": "^26.1.2",
     "@vitest/browser": "^4.1.8",
     "@vitest/browser-playwright": "^4.1.8",
     "@vitest/browser-webdriverio": "^4.1.8",
@@ -63,9 +63,9 @@
   "allowScripts": {
     "edgedriver@6.3.0": true,
     "geckodriver@6.1.0": true,
-    "@swc/core@1.15.41": true,
     "esbuild@0.28.1": true,
-    "esbuild@0.21.5": true
+    "esbuild@0.21.5": true,
+    "@swc/core@1.15.43": true
   },
   "dependencies": {
     "typescript-7": "npm:typescript@^7.0.2"

packages/library/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/library",
-  "version": "3.10.2",
+  "version": "3.11.0",
   "description": "Shared utility library for Tempo",
   "author": "Magma Computing Solutions",
   "license": "MIT",

packages/plugins/ai/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+All notable changes to the `@magmacomputing/tempo-plugin-ai` project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-07-30
+
+### Added
+- **Parallel Array Batching & Index Locking**: Concurrently processes array prompt inputs via `Promise.all` (or `Promise.allSettled` when `softErrors: true`) with guaranteed index-locked alignment between inputs and output arrays.
+- **Multi-Stream Provider Execution Modes (`AiMode`)**: Added `mode` options (`AiMode.Fallback`, `AiMode.Race`, `AiMode.Consensus`) for fine-grained control over provider routing, speculative racing, and multi-LLM consensus verification with confidence boosting.
+- **Runtime Configuration Module (`parseAI.config.ts`)**: Extracted `AiMode`, `RESERVED_PROVIDER_IDS`, and `DEFAULT_PROVIDERS` into a runtime module adhering to Tempo's monorepo `as const` object map and `Object.freeze()` immutability standards.
+- **Secured `.ai` Metadata Interceptor**: Proxy-based `.ai` metadata injection for frozen `Tempo` instances, preserving private class field access while exposing provider resolution lineage, ambiguity metrics, and PII-isolated debugging fields (`debug: true`).
+- **Semantic LLM Failure & Soft Error Handling**: Opt-in `softErrors: true` for returning `TempoAiError` objects directly within batch output arrays without throwing, and graceful mapping of LLM `"INVALID"` responses to `isValid = false` `Tempo` instances.
+- **Centralized Caching Integration**: Powered by core Tempo's centralized `BoundedCache` singleton (`Tempo.cache`) enforcing memory safety, capacity-bounded LRU eviction (`maxSize`), time-to-live expiration (`ttl`), and static immortal glossary isolation.
+- **Multi-Provider Fallback Routing**: Robust failover loop across configured LLM providers (`groq`, `openai`, `gemini`, `mistral`, or custom endpoints). Supports custom `tokenParam` mappings (`max_tokens` vs `max_completion_tokens`) and request timeout control via `AbortController`.
+- **Rate Limit Tracking (`getAiRateLimits`)**: Inspects provider HTTP response headers (`x-ratelimit-remaining-requests`, `x-ratelimit-remaining-tokens`, `x-ratelimit-reset-tokens`) and exposes real-time quota status via `getAiRateLimits()`, including a `resetAt` `Tempo` timestamp.
+- **Structured Error Handling (`TempoAiError`)**: Custom error class providing HTTP status codes (`code`) and optional `retryAt` `Tempo` timestamps. Features a circuit-breaker that immediately stops provider failovers when an LLM returns an explicit `INVALID` parse result (422 status).
+- **Documentation & Spec Suite**: Complete architectural guides (`architecture.md`, `context.md`, `rate-limits.md`, `index.md`) and a full Vitest test suite (`test/index.spec.ts`) covering live and mocked provider workflows.
+
+### Changed & Performance
+- **Centralized Caching Architecture**: Delegated all cache capacity and TTL parameters directly to core `Tempo.init()`, allowing `initAI` to focus strictly on LLM provider registration.
+- **Non-Destructive Glossary Appending**: Custom glossaries provided via `initAI({ cache })` are safely appended to `Tempo.cache` as static immortal terms without destructive overrides.
+- **Silent Native Pre-Parsing & Cache Controls**: `parseAI` attempts fast, zero-latency native `Tempo` resolution and checks `Tempo.cache` before initiating LLM network calls. Supports `cache: false` to bypass cache lookups and `force: true` to force a fresh LLM API request.
+- **Anchor Instance Reuse & Cache Salting**: Reuses anchor `Tempo` instances to minimize memory allocations and salts cache keys with the anchor's date and system context (`timeZone`, `calendar`, `locale`, `sphere`), preventing stale cache hits across midnight boundaries or context shifts.
+- **Resilient Cache Invalidation**: Normalized cache key input (whitespace trimming and case insensitivity) for `clearAiCache` and internal lookups.
+
+## [0.1.0] - 2026-07-26
+
+### Added
+- Initial scaffolding of the AI natural language parsing plugin.
+- Functional exports for `parseAI`, `initAI`, and `clearAiCache`.
+- Initial provider fallback-routing engine supporting HTTP requests to configured LLM provider endpoints.

packages/plugins/ai/README.md

@@ -0,0 +1,46 @@
+![Tempo Plugin](https://raw.githubusercontent.com/magmacomputing/magma/main/packages/tempo/public/plugin-logo.svg)
+
+# @magmacomputing/tempo-plugin-ai
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@magmacomputing/tempo-plugin-ai"><img src="https://img.shields.io/npm/v/@magmacomputing/tempo-plugin-ai?style=flat-square" alt="npm version" style="display: inline-block; margin: 0 4px;"></a> <a href="https://www.npmjs.com/package/@magmacomputing/tempo"><img src="https://img.shields.io/npm/dependency-version/@magmacomputing/tempo-plugin-ai/peer/@magmacomputing/tempo?style=flat-square" alt="npm peer dependency version" style="display: inline-block; margin: 0 4px;"></a> <a href="https://www.npmjs.com/package/@magmacomputing/tempo-plugin-ai"><img src="https://img.shields.io/npm/l/@magmacomputing/tempo-plugin-ai?style=flat-square" alt="License" style="display: inline-block; margin: 0 4px;"></a> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-Ready-blue?logo=typescript&style=flat-square" alt="TypeScript Ready" style="display: inline-block; margin: 0 4px;"></a> <a href="https://magmacomputing.github.io/magma/doc/9-plugins/ai.index.html"><img src="https://img.shields.io/badge/Docs-VitePress-brightgreen?logo=vitepress&style=flat-square" alt="Documentation" style="display: inline-block; margin: 0 4px;"></a>
+</p>
+
+Tempo community plugin for LLM-powered natural language parsing.
+
+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 complex natural language expressions into `Tempo` instances.
+
+> **CRITICAL SECURITY WARNING**: Raw LLM API keys must **never** be exposed in a client-side browser bundle. BYOK (Bring Your Own Key) is only secure on backend servers (Node, edge workers). For public frontend applications, you must use a proxy service.
+>
+> **LLM Output Disclaimer**: Large Language Models are probabilistic text generators, not deterministic calculators. Magma Computing Solutions and Tempo core maintainers provide `@magmacomputing/tempo-plugin-ai` "as-is". Developers and organizations are solely responsible for validating AI-generated date and time outputs before relying on them in financial, legal, medical, or time-critical production systems.
+
+## Installation
+
+```bash
+npm install @magmacomputing/tempo-plugin-ai
+```
+
+## Setup & Usage
+
+```typescript
+import { parseAI, initAI, clearAiCache } from '@magmacomputing/tempo-plugin-ai';
+
+// Initialize with your BYOK API Key (ensuring non-undefined string key)
+initAI({
+  providers: [
+    ...(process.env.GROQ_API_KEY ? [{ id: 'groq', key: process.env.GROQ_API_KEY }] : []),
+  ]
+});
+
+// Parse a complex natural language string!
+const dt = await parseAI("The penultimate Tuesday before Thanksgiving in 2026");
+
+// Evict bad parses from the cache
+clearAiCache("The penultimate Tuesday before Thanksgiving in 2026");
+```
+
+Full documentation is available at [https://magmacomputing.github.io/magma/doc/9-plugins/ai.index.html](https://magmacomputing.github.io/magma/doc/9-plugins/ai.index.html).
+
+## Licensing
+
+This is a **Community** plugin. It is completely free and open-source for personal and commercial use. No license token is required.