avantgate 1.1.0 → 1.1.1

package/README.md

@@ -7,6 +7,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-Strict-blue?logo=typescript)](https://www.typescriptlang.org/)
 [![Zod Native](https://img.shields.io/badge/Schema-Zod%20Native-orange)](https://zod.dev/)
 [![Zero Infra](https://img.shields.io/badge/Infrastructure-Zero%20Servers-emerald)](#why-avantgate)
+[![avantGate Cloud](https://img.shields.io/badge/avantGate%20Cloud-Coming%20Soon-8A2BE2)](#-avantgate-cloud-coming-soon)
 
 ---
 
@@ -33,6 +34,14 @@ flowchart LR
 
 ---
 
+## ☁️ AvantGate Cloud *(Coming Soon)*
+
+For engineering teams running autonomous agents in production, **AvantGate Cloud** will provide an optional centralized control plane (remote telemetry ingestion, team-wide cost visibility, and human-in-the-loop approval workflows) that connects directly to the open-source SDK with zero friction.
+
+> 🚀 **Interested in private preview or enterprise VPC deployment?** Contact us at [contact@lextalk.fr](mailto:contact@lextalk.fr) for early access.
+
+---
+
 ## 🚀 Key Features
 
 - 💰 **Pre-Flight Token Budgeting**: Rejects or truncates requests exceeding budget *before* invoking external APIs.
@@ -40,6 +49,8 @@ flowchart LR
 - 🛡️ **Active Security & PII Redaction**: In-flight masking of emails, phone numbers, and French/EU identifiers before sending to cloud providers. Blocks prompt injection & jailbreaks.
 - 🔀 **Zero-Downtime Multi-Model Failover**: If DeepSeek or Mistral returns HTTP 429/500, seamlessly failover to a backup provider (or local Ollama) in milliseconds.
 - 🔧 **Self-Repairing Structured Outputs**: Strict Zod runtime validation with automated markdown/JSON repair if the LLM hallucinates formatting.
+- 🤖 **Durable Agent Harness & PII Shield (`avantgate/agent`)**: Serverless memoized step execution (`step.run()`), native Human-in-the-Loop approval (`step.waitForApproval()`), and Dual-Channel tool data isolation without Temporal or Redis.
+- 📡 **Zero-Dependency Telemetry Bridge (`HttpTelemetryExporter`, `PlatformStorageAdapter`)**: Mirror in-process executions and hierarchical tool traces asynchronously to any HTTP sink or observability endpoint with $0 external npm dependencies.
 - 📦 **100% Framework Agnostic**: Works in Next.js, Express, Fastify, NestJS, Cloudflare Workers, AWS Lambda, or CLI scripts.
 
 ---
@@ -54,7 +65,11 @@ flowchart LR
 | **In-Flight PII Redaction** | ❌ Logs all raw data | ✅ **Automatic local masking** before API dispatch |
 | **Multi-Provider Failover** | ❌ No | ✅ **Built-in Fallback Router & Exponential Retry** |
 | **Zod Schema Auto-Repair** | ❌ No | ✅ **Built-in JSON Heuristic Repair** |
+| **Durable Workflow & HITL** | Requires Temporal / Inngest | ✅ **Built-in In-Process Step Runner & HITL** |
+| **Tool PII & Dual-Channel** | ❌ No | ✅ **Built-in `createIsolatedTool`** |
 | **Telemetry Network Latency** | ❌ +50ms - 200ms per trace call | ✅ **0 ms** (In-process memory accounting) |
+| **Central Web Dashboard** | Heavy self-hosted web app | ✅ **Optional Remote Sink** (Plug any HTTP endpoint via `PlatformStorageAdapter`) |
+| **Hierarchical Session Replay** | ❌ Flat span waterfall | ✅ **Causality Tree + Dual-Channel Isolation** |
 
 ---
 
@@ -68,6 +83,14 @@ pnpm add avantgate zod
 yarn add avantgate zod
 ```
 
+### 🧩 Subpath Exports
+
+| Import Path | Description |
+|---|---|
+| `avantgate` | Core control plane: token budgets, cost ledger, prompt guards, multi-model failover & Zod repair. |
+| `avantgate/finance` | Financial data normalizer (accounting parentheses, EU/US/UK/CH currencies & magnitudes). |
+| `avantgate/agent` | *(Preview / Experimental)* Durable step runner, Human-in-the-Loop, dual-channel PII tool isolation & storage adapters. |
+
 ---
 
 ## 🛠️ Quickstart
@@ -206,7 +229,70 @@ try {
 
 ---
 
-### 4. In-Process Prompt Engine (`PromptTemplate`, `PromptBuilder`, `PromptRegistry`)
+### 5. Pre-Flight Budget Guarding (`maxTokenBudget` & `maxCostUSD`)
+
+AvantGate enforces financial and resource limits **before** making external API calls. If a prompt or estimated cost exceeds your budget, it fails immediately with a `BudgetExceededError`, avoiding wasted spend:
+
+```typescript
+import { createAvantGate, BudgetExceededError } from "avantgate";
+
+const control = createAvantGate({
+  primary: { provider: "deepseek", model: "deepseek-chat", apiKey: process.env.DEEPSEEK_API_KEY! },
+  maxTokenBudget: 500, // Maximum allowed tokens for request + completion
+  maxCostUSD: 0.005,    // Block if estimated input cost exceeds half a cent
+});
+
+try {
+  await control.execute({
+    userQuery: "Exhaustive contract legal analysis...",
+  });
+} catch (error) {
+  if (error instanceof BudgetExceededError) {
+    console.warn("Blocked by AvantGate Pre-Flight Budget Guard:", error.message);
+  }
+}
+```
+
+---
+
+### 6. Decoupled Token Pricing & Database Adapter (`PricingAdapter`, `PricingRegistry`)
+
+Token prices vary across distributors (`openrouter`, `mistral`, `deepseek`, `azure`). AvantGate eliminates hardcoded pricing: you can dynamically plug your own database (Prisma, PostgreSQL, etc.) with in-memory TTL caching for **0 ms overhead**:
+
+```typescript
+import { createAvantGate, type PricingAdapter, PricingRegistry } from "avantgate";
+import { prisma } from "@/lib/prisma";
+
+// 1. Connect your database with automatic in-memory TTL caching (5 minutes)
+const control = createAvantGate({
+  primary: { provider: "deepseek", model: "deepseek-chat", apiKey: process.env.DEEPSEEK_API_KEY! },
+  pricingAdapter: {
+    async fetchPrice(model, provider) {
+      const dbPrice = await prisma.modelPricing.findFirst({
+        where: { model, distributor: provider, isActive: true },
+      });
+      if (!dbPrice) return undefined; // Falls back to default registry
+      return {
+        promptUSDPerMillion: Number(dbPrice.promptPriceUSDPerM),
+        completionUSDPerMillion: Number(dbPrice.completionPriceUSDPerM),
+      };
+    },
+  },
+  pricingCacheTtlMs: 5 * 60 * 1000,
+});
+
+// 2. Or override distributor prices globally at runtime
+PricingRegistry.registerPrice("openrouter/deepseek/deepseek-chat", {
+  promptUSDPerMillion: 0.18,
+  completionUSDPerMillion: 0.35,
+});
+```
+
+> 📖 **Deep Dive & Production DB Setup** : Consultez le guide complet [docs/pricing.md](docs/pricing.md) pour les schémas Prisma, Drizzle, invalidation de cache à chaud, et scripts de seed.
+
+---
+
+### 7. In-Process Prompt Engine (`PromptTemplate`, `PromptBuilder`, `PromptRegistry`)
 
 Assemble prompts systematically with strict token slots, KV-cache prefix hits, automated Zod output contracts, and jailbreak guardrails.
 
@@ -248,7 +334,7 @@ const messages = builder.toMessages();
 
 ---
 
-### 5. Modular Financial Normalizer & Accounting Strategies (`avantgate/finance`)
+### 8. Modular Financial Normalizer & Accounting Strategies (`avantgate/finance`)
 
 Opt-in, zero-overhead financial accounting module. Automatically normalizes negative parentheses `(150 000)` ➔ `-150000`, magnitudes (`1 850 k€` ➔ `1850000`), European decimal commas, and currency symbols across jurisdictions (**FR PCG / Cerfa**, **US GAAP**, **UK IFRS**, **Swiss CO**).
 
@@ -283,7 +369,7 @@ const data = validateWithZod(rawLLMText, schema, { financialNormalizer: true, ju
 
 ---
 
-### 6. Unified `generateStructuredOutput` with Multi-Provider Failover
+### 9. Unified `generateStructuredOutput` with Multi-Provider Failover
 
 Extract type-safe data with zero boilerplate. Automatically handles failover, retries, cost tracking, and financial repair:
 
@@ -303,6 +389,107 @@ console.log(result.modelUsed);  // Final provider model that succeeded
 
 ---
 
+### 10. Durable Agent Harness & Dual-Channel Tool Isolation (`avantgate/agent`)
+
+> [!WARNING]
+> **NOT USED IN PRODUCTION / EXPERIMENTAL PREVIEW**  
+> The `avantgate/agent` submodule is currently in developer preview and is **NOT intended for production workloads**. Internal APIs, causality tracing, and storage contracts are subject to breaking changes. For production environments, use the core control plane (`avantgate`) and financial normalizers (`avantgate/finance`).
+
+Deploy stateful TypeScript agents without spinning up Temporal, Inngest, or Redis queues:
+
+```typescript
+import { createIsolatedTool, createStepRunner, StepSuspendedError } from "avantgate/agent";
+import { z } from "zod";
+
+// 1. Dual-Channel Isolated Tool (Automatic PII redaction + direct UI client streaming)
+const fetchClientDataTool = createIsolatedTool({
+  name: "fetch_client_data",
+  description: "Fetches corporate client dossier",
+  parameters: z.object({ clientId: z.string() }),
+  async execute({ clientId }) {
+    return {
+      clientId,
+      ssn: "1 85 12 75 108 123 45", // Auto-redacted before reaching LLM!
+      email: "finance@corp.fr",
+      turnover: 1500000,
+    };
+  },
+  // Rich data sent directly to the client UI (out-of-band)
+  toClientData(data) {
+    uiSocket.emit("client_dossier", data);
+  },
+  // Safe minimal summary for LLM context window (saves tokens and protects privacy)
+  toLLMSummary(data) {
+    return { clientId: data.clientId, note: "Dossier dispatched to UI" };
+  },
+});
+
+// 2. Serverless Durable Step Execution & Human-in-the-Loop (HITL)
+const runner = createStepRunner({ workflowId: "wf-deal-42" });
+
+try {
+  // Idempotent execution: memoized and skipped on re-run if already completed
+  const scoring = await runner.run("risk-assessment", async () => {
+    return await computeRiskScore();
+  });
+
+  // Suspends execution cleanly until human validation
+  const approval = await runner.waitForApproval("director-signature", {
+    metadata: { dealAmount: 250000 },
+  });
+
+  // Continues seamlessly after approval
+  await runner.run("finalize-deal", async () => {
+    return await commitContract(approval);
+  });
+} catch (error) {
+  if (error instanceof StepSuspendedError) {
+    console.log(`Workflow paused at step [${error.stepId}] awaiting human validation.`);
+  }
+}
+```
+
+> 📖 **Full Agent Documentation & Storage Adapters (Memory, Custom, Key-Value, Prisma, SQLite)**: [docs/agent.md](docs/agent.md)
+
+---
+
+### 11. Streaming Telemetry to an External Sink (Observability & Replay)
+
+Connect your agents to an external observability sink or custom webhook in 2 lines of code. It persists locally first, and streams telemetry in the background with **zero performance impact**:
+
+```typescript
+import {
+  PlatformStorageAdapter,
+  SQLiteStorageAdapter,
+  HttpTelemetryExporter,
+  createStepRunner,
+} from "avantgate/agent";
+import Database from "better-sqlite3";
+
+// 1. Configure the non-blocking background telemetry exporter
+const exporter = new HttpTelemetryExporter({
+  apiKey: process.env.AVANTGATE_API_KEY,
+  endpoint: "https://telemetry.your-domain.com/api/v1/events",
+  agentName: "prospect-qualifier",
+  batchIntervalMs: 5000,
+});
+
+// 2. Hybrid Hexagonal Adapter: SQLite local durability + Remote mirror
+const storage = new PlatformStorageAdapter({
+  primaryStorage: new SQLiteStorageAdapter(new Database("agent.db")),
+  exporter,
+});
+
+// 3. StepRunner with unified runId for FinOps & Session Replay
+const runner = createStepRunner({
+  workflowId: "deal-pipeline-42",
+  runId: "run-2026-09-13-alpha",
+  storage,
+});
+```
+
+---
+
 ## 🏗️ Architecture & Extensibility
 
 AvantGate is built around clean **Ports and Adapters**:
@@ -365,17 +552,26 @@ npm test
 
 ## 🙏 Acknowledgements & Credits
 
-AvantGate builds upon foundational ideas and inspirations from the open source AI engineering community:
+AvantGate builds upon foundational ideas and inspirations from the open source AI engineering and durable execution communities:
+
+### 🛡️ In-Process Control & Production Layers
 - Special credit to [**Emmimal/control-layer**](https://github.com/Emmimal/control-layer) for pioneering the in-process control layer architecture.
 - Valuable insights and launch safety principles inspired by [**ShipYourAI.com**](https://shipyourai.com).
-
-### 📚 Related Series — Production Layers for LLM Systems (by Emmimal)
-AvantGate is inspired by and designed to compose with the production layers series:
 - **[context-engine](https://github.com/Emmimal/context-engine)** — Retrieval, re-ranking, memory decay, and token budget control for RAG systems. *The control layer handles what the model returns. The context engine handles what it receives. They compose.*
 - **[RAG Is Blind to Time — Temporal Layer](https://github.com/Emmimal/temporal-layer)** — Temporal awareness layer for RAG systems that treats time as a first-class retrieval signal.
 - **[LLM Evals Are Based on Vibes — Evaluation Layer](https://github.com/Emmimal/eval-layer)** — Evaluation layer that replaces gut-feel shipping decisions with measurable output quality gates.
 - **[PyTorch NaNs Are Silent Killers — NaN Catch Hook](https://github.com/Emmimal/nan-hook)** — Lightweight hook that catches NaN propagation at the exact layer it originates, in under 3ms overhead.
 
+### 📊 FinOps & Observability Platforms
+- **[Helicone](https://github.com/Helicone/helicone)** — Pioneering LLM request caching, granular cost estimation, and developer-first proxy design that inspired our FinOps engine and semantic tool caching patterns.
+- **[AgentOps](https://github.com/AgentOps-AI/agentops)** — State-of-the-art agent tracking, session replay visualization, and recursive loop detection that inspired our Session Replay and Infinite Loop Shield.
+
+### 🤖 Durable Workflows & Agent Architecture (`avantgate/agent`)
+- **[Inngest](https://www.inngest.com)** & **[Temporal](https://temporal.io)** — The developer experience of durable step memoization (`step.run()`) and human validation pauses (`step.waitForApproval()`), reimagined here as a **$0-infrastructure, serverless in-process harness** without requiring external worker queues or Redis clusters.
+- **[Vercel AI SDK (`ai`)](https://sdk.vercel.ai)** — Standardized TypeScript tool schema contracts (`parameters`, `execute`) natively embraced and augmented by `createIsolatedTool`.
+- **Least-Privilege & Dual-Channel Isolation** — Security patterns separating sensitive payload data (streamed out-of-band directly to trusted user interfaces) from LLM prompts (receiving sanitized summaries), preventing context pollution and PII leakage.
+- **Alistair Cockburn's Ports & Adapters (Hexagonal Architecture)** — Pure domain isolation enabling developers to plug any database (Prisma, SQLite, Drizzle, Kysely, Mongo, Redis) with zero hard framework dependencies.
+
 ---
 
 ## 📜 License