Magma Library (Internal Reference)
> [!NOTE]
> **Internal Reference Package**: `packages/library` is an internal monorepo utility suite used across Tempo packages. It is **not** published as a standalone package on npm, and is provided in the documentation as a reference guide for internal architectural utilities and shared routines.
@@ -25,6 +25,7 @@ The library is organized into specialized modules, each designed for maximum eff
| **Pledge** | A robust wrapper for native Promises with settled-state tracking and timeout support. |
| **Reflection** | Clean access to own-properties, values, and entries without prototype pollution. |
| **Temporal** | Lightweight helpers and polyfill integration for the native `Temporal` API. |
+| **Recurrence** | Zero-dependency RFC 5545 recurrence rule parsing, expansion, and finiteness evaluation. |
---
diff --git a/packages/library/img/library-logo.svg b/packages/library/img/library-logo.svg
new file mode 100644
index 00000000..ec7fd7c4
--- /dev/null
+++ b/packages/library/img/library-logo.svg
@@ -0,0 +1,34 @@
+
+
+
diff --git a/packages/library/package.json b/packages/library/package.json
index 312b3090..9ecbafb8 100644
--- a/packages/library/package.json
+++ b/packages/library/package.json
@@ -1,6 +1,6 @@
{
"name": "@magmacomputing/library",
- "version": "3.11.0",
+ "version": "3.11.1",
"description": "Shared utility library for Tempo",
"author": "Magma Computing Solutions",
"license": "MIT",
@@ -26,7 +26,8 @@
".": {
"types": "./dist/common.index.d.ts",
"development": "./src/common.index.ts",
- "import": "./dist/common.index.js"
+ "import": "./dist/common.index.js",
+ "default": "./dist/common.index.js"
},
"./browser": {
"types": "./dist/browser.index.d.ts",
diff --git a/packages/library/src/common.index.ts b/packages/library/src/common.index.ts
index 262b00d7..44d73521 100644
--- a/packages/library/src/common.index.ts
+++ b/packages/library/src/common.index.ts
@@ -26,5 +26,7 @@ export * from './common/symbol.library.js';
export * from './common/type.library.js';
export * from './common/temporal.polyfill.js';
export * from './common/temporal.library.js';
+export * from './common/calendar.library.js';
+export * from './common/recurrence.library.js';
export * from './common/utility.library.js';
export * from './common/webtoken.library.js';
diff --git a/packages/library/src/common/assertion.library.ts b/packages/library/src/common/assertion.library.ts
index 0c56d622..8ffab521 100644
--- a/packages/library/src/common/assertion.library.ts
+++ b/packages/library/src/common/assertion.library.ts
@@ -24,6 +24,9 @@ export const isString = (obj: unknown): obj is string => isType
-Tempo community plugin for LLM-powered natural language parsing.
+> **Tempo community plugin for LLM-powered natural language date, schedule, and context 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 complex natural language expressions into `Tempo` instances.
+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.
-> **CRITICAL SECURITY WARNING**: Raw LLM API keys must **never** be exposed in a client-side browser bundle or stored in browser storage (`localStorage`, `sessionStorage`, `IndexedDB`, or browser cache). Client-side storage is vulnerable to XSS attacks, malicious scripts, and browser extension extraction, which can result in API key theft and quota abuse. BYOK (Bring Your Own Key) is only secure on backend servers (Node, edge workers). For public frontend applications, you must route requests through a secure backend 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.
+> 🔒 **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.
-## Installation
+---
+
+## ⚡ Quick Start
+
+### 📦 Installation
```bash
npm install @magmacomputing/tempo-plugin-ai
```
-## Setup & Usage
+### 🎯 Usage
```typescript
-import { parseAI, initAI, clearAiCache } from '@magmacomputing/tempo-plugin-ai';
+import { parseAI, initAI } from '@magmacomputing/tempo-plugin-ai';
-// Initialize with your BYOK API Key (ensuring non-undefined string key)
-initAI({
+// Initialize with your API keys
+await initAI({
providers: [
- ...(process.env.GROQ_API_KEY ? [{ id: 'groq', key: process.env.GROQ_API_KEY }] : []),
+ { id: 'groq', key: process.env.GROQ_API_KEY! }
]
});
-// Parse a complex natural language string!
+// Parse natural language into a standard Tempo instance!
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");
+console.log(dt.format('{yyyy}-{mm}-{dd}')); // 2026-11-17
+console.log(dt.ai?.provider); // 'groq'
+console.log(dt.ai?.confidence); // 0.98
```
-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).
+---
+
+## 📚 AI Endpoint Catalog
+
+| Endpoint | Description | Doc |
+| :--- | :--- | :---: |
+| **`parseAI`** | Parse relative/point-in-time dates (e.g. *"next Friday at 4pm"*) | |
+| **`recurrenceAI`** | Convert repeating patterns (e.g. *"every 2 weeks on Friday"*) to RRULEs | |
+| **`diffAI`** | Calculate natural language difference & business days between dates | |
+| **`scheduleAI`** | Book appointment slots around busy calendar event bounds | |
+| **`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](https://magmacomputing.github.io/magma/doc/9-plugins/ai.index.html)**
+
+---
-## Licensing
+## ⚖️ Licensing
-This is a **Community** plugin. It is completely free and open-source for personal and commercial use. No license token is required.
+This is a **Community** plugin. It is completely free and open-source for personal and commercial use under the MIT license.
diff --git a/packages/plugins/ai/doc/architecture.md b/packages/plugins/ai/doc/architecture.md
index 7a176adb..8f7e7428 100644
--- a/packages/plugins/ai/doc/architecture.md
+++ b/packages/plugins/ai/doc/architecture.md
@@ -40,12 +40,39 @@ initAI({
id: 'local',
key: 'no-key-needed',
url: 'http://localhost:11434/v1/chat/completions',
- model: 'your-local-model'
+ model: 'your-local-model',
+ options: { timeout: 5000 } // Custom provider-level timeout (5s)
}
]
});
```
+### Dynamic Provider Manifests & Remote Endpoint Trust
+
+By default, `@magmacomputing/tempo-plugin-ai` lazily fetches provider defaults (model IDs, endpoints, token parameter keys) from `https://tempo.magmacomputing.com.au/providers.v1.json` once per application lifecycle.
+
+- **Remote Manifest Trust & Endpoint Enforcement**:
+ - `remoteConfigUrl` is restricted to fixed trusted hosts (`tempo.magmacomputing.com.au` or trusted internal HTTPS endpoints).
+ - Any dynamic `provider.url` values received from the manifest or dynamically returned via `fetchDefaults` are strictly validated against an enforced provider host allowlist (or must use verified HTTPS/localhost origins) before `getResolvedProviderDefaults()` merges them into runtime provider configurations. Untrusted or unauthenticated endpoints are rejected and stripped before merging.
+- **Validation on `fetchDefaults` Hook**: The exact same host allowlist and HTTPS origin verification is enforced when resolving custom provider options via the `fetchDefaults` callback. Any dynamic hook attempting to return unauthenticated or disallowed host URLs will have the `url` property safely discarded.
+- **Async Resolution & Promise Lifecycle**: `initAI()` returns a `Promise
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/packages/tempo/public/library-logo.svg b/packages/tempo/public/library-logo.svg
new file mode 100644
index 00000000..ec7fd7c4
--- /dev/null
+++ b/packages/tempo/public/library-logo.svg
@@ -0,0 +1,34 @@
+
+
+
diff --git a/packages/tempo/public/llms.txt b/packages/tempo/public/llms.txt
new file mode 100644
index 00000000..5c80e229
--- /dev/null
+++ b/packages/tempo/public/llms.txt
@@ -0,0 +1,75 @@
+# Tempo: Immutable Date-Time Engine & AI Syntax Rules
+
+> Tempo is a lightweight, immutable JavaScript/TypeScript date-time library built around the native ECMAScript Temporal API proposal. It provides type-safe parsing, formatting, relative time arithmetic, and extensible layout matching across Browser and Node.js environments.
+
+## Core Architectural Rules & Philosophy
+- **Temporal Engine**: Tempo expects native `Temporal` in modern runtimes or uses `@js-temporal/polyfill` when necessary. Never instantiate legacy JavaScript `Date`.
+- **Strict Immutability**: `Tempo` instances are completely frozen. All mutating operations (`add`, `subtract`, `with`, `startOf`, `endOf`) return a brand-new `Tempo` object.
+- **Zero-Cost Getter Proxies**: Properties like `.year`, `.month`, `.day`, `.hour`, `.minute`, `.second`, `.millisecond`, `.microsecond`, `.nanosecond` are live getters proxying the underlying `Temporal` state.
+- **Plugin Architecture**: Core functions can be extended via `Tempo.extend(Plugin)`. License validation occurs via `Tempo.init(...)`.
+
+## Formatting & Parsing Tokens
+| Token | Description | Sample Output |
+| :--- | :--- | :--- |
+| `{yy}` | Year (2 or 4 digits) | `2026`, `26` |
+| `{mon}` | Month name (Full or Abbreviated) | `August`, `Aug` |
+| `{mm}` | Month number (01-12) | `08` |
+| `{dd}` | Day of month (01-31) | `04` |
+| `{hh}` | Hour (00-24) | `15` |
+| `{mi}` | Minute (00-59) | `30` |
+| `{ss}` | Second (00-59) | `00` |
+| `{wkd}` | Weekday name | `Tuesday`, `Tue` |
+| `{tzd}` | Time zone offset / identifier | `Z`, `+10:00`, `Australia/Sydney` |
+| `{yw}` | ISO Week-Year number | `W32` |
+| `{unt}` | Time unit keyword | `day`, `month`, `year` |
+
+## Key Module Links
+- [Full Documentation Concatenation](/llms-full.txt): Complete raw markdown documentation for RAG ingestion.
+- [AI Plugin Capabilities](https://github.com/magmacomputing/magma/tree/main/packages/plugins/ai): Natural language parsing (`parseAI`), slot scheduling (`scheduleAI`), and recurrence rule resolution (`recurrenceAI`).
+- [Layout Patterns & Regex Snippets](https://github.com/magmacomputing/magma/tree/main/packages/tempo/doc/3-extending-tempo/tempo.layout.md): Guide to writing regex layouts and snippets.
+- [Plugin Development](https://github.com/magmacomputing/magma/tree/main/packages/tempo/doc/3-extending-tempo/tempo.plugin.md): Rules for extending Tempo via plugins.
+- [Utility Library](https://github.com/magmacomputing/magma/tree/main/packages/tempo/doc/6-utility-library/tempo.library.md): Type detection, serialization (`stringify`/`objectify`), and `Pledge`.
+
+## Common Code Snippets
+
+### Quick Setup & Basic Usage
+```typescript
+import { Tempo } from '@magmacomputing/tempo';
+
+// Create from current instant or ISO string
+const t = Tempo.from('2026-08-04T15:30:00Z');
+
+// Format using layout tokens
+t.format('{mon} {dd}, {yy}'); // "August 04, 2026"
+
+// Immutably manipulate date
+const nextWeek = t.add({ days: 7 });
+```
+
+### Smart Parsing & Shorthand Expressions
+```typescript
+import { Tempo } from '@magmacomputing/tempo';
+
+// 1. Natural language & relative shorthand expressions
+const t1 = Tempo.from('next friday');
+const t2 = Tempo.from('start of month');
+const t3 = Tempo.from('+3 days');
+
+// 2. Flexible date parsing
+const t4 = Tempo.parse('2026-08-04T15:30:00+10:00');
+```
+
+### Custom Layout Registration & Parsing
+```typescript
+import { Tempo } from '@magmacomputing/tempo';
+
+// Register custom snippet & layout pattern via config
+Tempo.config({
+ layouts: {
+ us_date: '{mm}/{dd}/{yy}'
+ }
+});
+
+// Parse string using registered layout
+const parsed = Tempo.parse('08/04/2026', 'us_date');
+```
diff --git a/packages/tempo/public/providers.v1.json b/packages/tempo/public/providers.v1.json
new file mode 100644
index 00000000..73570985
--- /dev/null
+++ b/packages/tempo/public/providers.v1.json
@@ -0,0 +1,26 @@
+{
+ "version": "1.0",
+ "updatedAt": "2026-08-05T00:00:00Z",
+ "providers": {
+ "groq": {
+ "url": "https://api.groq.com/openai/v1/chat/completions",
+ "model": "openai/gpt-oss-120b",
+ "tokenParam": "max_tokens"
+ },
+ "openai": {
+ "url": "https://api.openai.com/v1/chat/completions",
+ "model": "gpt-5.4-mini",
+ "tokenParam": "max_completion_tokens"
+ },
+ "gemini": {
+ "url": "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions",
+ "model": "gemini-3.6-flash",
+ "tokenParam": "max_tokens"
+ },
+ "mistral": {
+ "url": "https://api.mistral.ai/v1/chat/completions",
+ "model": "mistral-small-latest",
+ "tokenParam": "max_tokens"
+ }
+ }
+}
diff --git a/packages/tempo/public/script.index.html b/packages/tempo/public/script.index.html
index 57f8ddd4..4ca30a7b 100644
--- a/packages/tempo/public/script.index.html
+++ b/packages/tempo/public/script.index.html
@@ -99,6 +99,7 @@
margin-bottom: 5px;
background: linear-gradient(135deg, #fff, #a5b4fc);
-webkit-background-clip: text;
+ background-clip: text;
-webkit-text-fill-color: transparent;
letter-spacing: -0.5px;
}
diff --git a/packages/tempo/src/engine/engine.composer.ts b/packages/tempo/src/engine/engine.composer.ts
index 873e16d7..8586905f 100644
--- a/packages/tempo/src/engine/engine.composer.ts
+++ b/packages/tempo/src/engine/engine.composer.ts
@@ -1,4 +1,4 @@
-import { getTemporalIds } from '#library/temporal.library.js';
+import { getTemporalIds, toZonedDateTime } from '#library/temporal.library.js';
import { isInstant, isZonedDateTime, isPlainDate, isPlainDateTime } from '#library/assertion.library.js';
import type { TemporalObject, TypeValue } from '#library/type.library.js';
@@ -15,7 +15,7 @@ const UNIT_LOOKUP: Record
+
+ Tempo
+esm.sh Smart CDN Test
+
+
+
+
+ import '@js-temporal/polyfill';
+import { Tempo } from '@magmacomputing/tempo';
+
+const t = new Tempo('next friday');
+t.format('{mon} {dd:raw}');
+
+ Result
+
+
+
+ Initializing Temporal...
+