gauss-ts 2.0.0 → 2.0.2

package/README.md

@@ -2,497 +2,248 @@
 
 # 🔮 gauss-ts
 
-**The AI Agent SDK for TypeScript — powered by Rust**
+### Rust-powered AI Agent SDK for TypeScript
 
 [![CI](https://github.com/giulio-leone/gauss/actions/workflows/ci.yml/badge.svg)](https://github.com/giulio-leone/gauss/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/gauss-ts.svg)](https://www.npmjs.com/package/gauss-ts)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-**Multi-provider • Teams • Tools • MCP • Graphs • Workflows • Memory • RAG**
+**Rust-powered • Multi-provider • Enterprise-grade • Plug-and-play DX**
 
 </div>
 
+Gauss gives you a beautiful TypeScript API over a high-performance Rust core.
+Build single agents, hierarchical teams, DAG pipelines, MCP/A2A systems, and enterprise guardrailed workflows in a few lines.
+
 ---
 
-## Quick Start
+## Install
 
 ```bash
 npm install gauss-ts
 ```
 
-### One-liner
+Set one provider key (auto-detection is built in):
 
-```typescript
-import { gauss } from "gauss-ts";
-
-const answer = await gauss("Explain quantum computing in 3 sentences");
+```bash
+export OPENAI_API_KEY=sk-...
+# or ANTHROPIC_API_KEY / GOOGLE_API_KEY / OPENROUTER_API_KEY / ...
 ```
 
-Auto-detects your API key from environment variables. That's it.
+---
 
-### Full control
+## Quick Start
 
-```typescript
-import { Agent, OPENAI_DEFAULT } from "gauss-ts";
+### One-liner
 
-const agent = new Agent({
-  name: "assistant",
-  model: OPENAI_DEFAULT, // "gpt-5.2"
-  instructions: "You are a helpful assistant.",
-});
+```ts
+import { gauss } from "gauss-ts";
 
-const result = await agent.run("What is quantum computing?");
-console.log(result.text);
+const text = await gauss("Explain retrieval-augmented generation in 3 bullets.");
+console.log(text);
 ```
 
----
-
-## Features
-
-### 🤖 Agents
+### Full control
 
-```typescript
+```ts
 import { Agent, OPENAI_DEFAULT } from "gauss-ts";
 
 const agent = new Agent({
-  name: "researcher",
+  name: "assistant",
   model: OPENAI_DEFAULT, // "gpt-5.2"
-  instructions: "You are a research assistant.",
-  temperature: 0.7,
-  maxSteps: 5,
-  tools: [searchTool, calculateTool],
+  instructions: "You are a concise senior engineer.",
+  temperature: 0.2,
 });
 
-// Run
-const result = await agent.run("Find the population of Tokyo");
+const result = await agent.run("Design a clean API for a weather service.");
 console.log(result.text);
-console.log(`Steps: ${result.steps}, Tokens: ${result.inputTokens + result.outputTokens}`);
-
-// Stream
-for await (const event of agent.streamIter("Tell me a story")) {
-  if (event.type === "text_delta") process.stdout.write(event.delta);
-}
+agent.destroy();
 ```
 
-### 🛠️ Tools
-
-```typescript
-const weatherTool = {
-  name: "get_weather",
-  description: "Get current weather for a location",
-  parameters: {
-    type: "object",
-    properties: {
-      city: { type: "string", description: "City name" },
-    },
-    required: ["city"],
-  },
-  execute: async (args: { city: string }) => {
-    return { temperature: 22, condition: "sunny" };
-  },
-};
+---
 
-const agent = new Agent({
-  name: "weather-bot",
-  model: OPENAI_DEFAULT,
-  tools: [weatherTool],
-});
-```
+## Multi-Agent in a Few Lines
 
-### 👥 Teams
+### 1) Team.quick() (hierarchical team bootstrap)
 
-```typescript
-import { Agent, Team } from "gauss-ts";
+```ts
+import { Team } from "gauss-ts";
 
-const team = new Team({
-  name: "research-team",
-  agents: [
-    new Agent({ name: "researcher", model: "gpt-5.2", instructions: "Research topics deeply." }),
-    new Agent({ name: "writer", model: "claude-sonnet-4-20250514", instructions: "Write clear summaries." }),
-    new Agent({ name: "critic", model: "gemini-2.5-flash", instructions: "Review and critique." }),
-  ],
-  strategy: "round-robin",
-});
+const team = Team.quick("architecture-team", "parallel", [
+  { name: "planner", instructions: "Break work into milestones." },
+  { name: "implementer", instructions: "Produce production-ready code." },
+  { name: "reviewer", instructions: "Find defects and risks." },
+]);
 
-const result = await team.run("Analyze the impact of AI on healthcare");
+const out = await team.run("Implement a resilient webhook ingestion service.");
+console.log(out.finalText);
+team.destroy();
 ```
 
-### 📊 Graph Pipelines
+### 2) Graph.pipeline() (2-line DAG)
 
-```typescript
+```ts
 import { Agent, Graph } from "gauss-ts";
 
-const researcher = new Agent({ name: "researcher", instructions: "Research thoroughly" });
-const writer = new Agent({ name: "writer", instructions: "Write clearly" });
-
-const pipeline = new Graph()
-  .addNode("research", researcher)
-  .addNode("write", writer)
-  .addEdge("research", "write");
-
-const result = await pipeline.run("Explain quantum computing");
-```
-
-### 🔄 Workflows
-
-```typescript
-import { Agent, Workflow } from "gauss-ts";
-
-const planner = new Agent({ name: "planner" });
-const executor = new Agent({ name: "executor" });
-
-const wf = new Workflow()
-  .addStep("plan", planner)
-  .addStep("execute", executor)
-  .addDependency("execute", "plan");
-
-const result = await wf.run("Build a REST API");
-```
-
-### 🌐 Multi-Agent Network
-
-```typescript
-import { Agent, Network } from "gauss-ts";
-
-const analyst = new Agent({ name: "analyst" });
-const coder = new Agent({ name: "coder" });
-
-const net = new Network()
-  .addAgent(analyst)
-  .addAgent(coder)
-  .setSupervisor("analyst");
-
-const result = await net.delegate("coder", "Implement a sorting algorithm");
-```
-
-### 🧠 Memory
-
-```typescript
-import { Agent, Memory } from "gauss-ts";
-
-const memory = new Memory();
-const agent = new Agent({
-  name: "assistant",
-  model: OPENAI_DEFAULT,
-  memory,
-});
-
-// Memory persists across conversations
-await agent.run("My name is Alice and I love hiking.");
-const result = await agent.run("What do you know about me?");
-// → "You're Alice, and you enjoy hiking!"
-```
-
-### 📚 RAG / Vector Store
-
-```typescript
-import { VectorStore } from "gauss-ts";
-
-const store = new VectorStore();
-await store.add("TypeScript is a typed superset of JavaScript.");
-await store.add("Rust is a systems programming language.");
+const graph = Graph.pipeline([
+  { nodeId: "analyze", agent: new Agent({ instructions: "Analyze requirements" }) },
+  { nodeId: "build", agent: new Agent({ instructions: "Implement solution" }) },
+  { nodeId: "verify", agent: new Agent({ instructions: "Validate outputs" }) },
+]);
 
-const results = await store.search("What is TypeScript?");
+const out = await graph.run("Build a typed SDK wrapper around a REST API.");
+console.log(out.finalText);
+graph.destroy();
 ```
 
-### 🔗 MCP Server
-
-```typescript
-import { McpServer } from "gauss-ts";
-
-const server = new McpServer("my-tools", "1.0.0");
-
-server.addTool({
-  name: "calculate",
-  description: "Evaluate a math expression",
-  parameters: { type: "object", properties: { expr: { type: "string" } } },
-  execute: async ({ expr }) => ({ result: eval(expr) }),
-});
+---
 
-const response = await server.handle(requestMessage);
-```
+## Agent DX
 
-### 🎯 Structured Output
+### Inline tools with `withTool()`
 
-```typescript
-import { Agent, structured } from "gauss-ts";
+```ts
+import { Agent } from "gauss-ts";
 
-const agent = new Agent({ model: OPENAI_DEFAULT });
+const agent = new Agent({ instructions: "Use tools when useful." })
+  .withTool(
+    "sum",
+    "Sum two numbers",
+    ({ a, b }: { a: number; b: number }) => ({ result: a + b }),
+    {
+      type: "object",
+      properties: { a: { type: "number" }, b: { type: "number" } },
+      required: ["a", "b"],
+    }
+  );
 
-const { data } = await structured(agent, "List 3 programming languages", {
-  schema: {
-    type: "object",
-    properties: {
-      languages: { type: "array", items: { type: "string" } },
-    },
-    required: ["languages"],
-  },
-  maxParseRetries: 2,
-});
-
-console.log(data.languages); // ["TypeScript", "Rust", "Python"]
+const out = await agent.run("What is 12 + 30?");
+console.log(out.text);
+agent.destroy();
 ```
 
-### 💭 Reasoning
-
-```typescript
-import { Agent, OPENAI_REASONING, ANTHROPIC_PREMIUM } from "gauss-ts";
+### Streaming helpers
 
-// OpenAI reasoning models (o4-mini)
-const reasoner = new Agent({
-  name: "solver",
-  model: OPENAI_REASONING,
-  reasoningEffort: "high",
-});
+```ts
+// Low-level async iterable events
+const stream = agent.streamIter("Write a short release note");
+for await (const event of stream) {
+  if (event.type === "text_delta") process.stdout.write(event.text ?? "");
+}
 
-// Anthropic extended thinking
-const thinker = new Agent({
-  name: "analyst",
-  model: ANTHROPIC_PREMIUM,
-  thinkingBudget: 10000,
+// High-level DX helper: returns final text + optional delta callback
+const finalText = await agent.streamText("Write a changelog", (delta) => {
+  process.stdout.write(delta);
 });
-
-const result = await thinker.run("Analyze this complex problem...");
-console.log(result.thinking); // Internal reasoning process
-```
-
-### 📝 Prompt Templates
-
-```typescript
-import { template, summarize, translate, codeReview } from "gauss-ts";
-
-// Custom template
-const greet = template("Hello {{name}}, you are a {{role}}.");
-console.log(greet({ name: "Alice", role: "developer" }));
-
-// Built-in templates
-const prompt = summarize({ format: "article", style: "bullet points", text: "..." });
-const translated = translate({ language: "French", text: "Hello world" });
-const review = codeReview({ language: "typescript", code: "const x = 1;" });
 ```
 
-### ⚡ Batch Processing
+### Config helpers
 
-```typescript
-import { batch } from "gauss-ts";
-
-const results = await batch(
-  ["Translate: Hello", "Translate: World", "Translate: Goodbye"],
-  { concurrency: 2, provider: "openai" },
-);
-results.forEach((r) => console.log(r.result?.text ?? r.error?.message));
-```
-
-### 🔁 Retry with Backoff
-
-```typescript
-import { withRetry, retryable } from "gauss-ts";
-
-const data = await withRetry(() => agent.run("Summarize this"), {
-  maxRetries: 3,
-  backoff: "exponential", // "fixed" | "linear" | "exponential"
-  baseDelayMs: 1000,
-  jitter: 0.1,
-  onRetry: (err, attempt, delay) => console.log(`Retry ${attempt} in ${delay}ms`),
-});
+```ts
+// Explicit env-intent constructor
+const a = Agent.fromEnv({ instructions: "Be precise." });
 
-// Or wrap an agent
-const resilientRun = retryable(agent, { maxRetries: 5 });
-const result = await resilientRun("Hello");
+// Clone with a different model
+const b = a.withModel("gpt-4.1");
 ```
 
-### 🛡️ Resilience
-
-```typescript
-import { createFallbackProvider, createCircuitBreaker, createResilientAgent } from "gauss-ts";
+---
 
-const fallback = createFallbackProvider([
-  { provider: "openai", model: "gpt-5.2" },
-  { provider: "anthropic", model: "claude-sonnet-4-20250514" },
-]);
+## Core Features
+
+- **Agents**: `Agent`, `gauss()`
+- **Teams**: `Team`, `Team.quick()`
+- **Graphs**: `Graph`, `Graph.pipeline()`, `addConditionalEdge()`
+- **Workflows / Networks**: `Workflow`, `Network`
+- **Typed tools**: `tool()`, `createToolExecutor()`, `withTool()`
+- **MCP**: `McpServer`, `McpClient`
+- **A2A**: `A2aClient`
+- **Memory + RAG**: `Memory`, `VectorStore`, `TextSplitter`, `loadText/loadMarkdown/loadJson`
+- **Guardrails + Middleware**: `GuardrailChain`, `MiddlewareChain`
+- **Reliability**: retry, circuit breaker, fallback providers
+- **Observability & quality**: `Telemetry`, `EvalRunner`
+- **Enterprise preset**: `enterprisePreset()`, `enterpriseRun()`
 
-const breaker = createCircuitBreaker({ failureThreshold: 5, resetTimeoutMs: 30000 });
-const agent = createResilientAgent({ fallback, circuitBreaker: breaker });
-```
-
-### 🔀 Pipeline & Async Helpers
+---
 
-```typescript
-import { pipe, mapAsync, filterAsync, reduceAsync, compose } from "gauss-ts";
+## Errors (typed hierarchy)
 
-const result = await pipe(
-  "Explain AI",
-  (prompt) => agent.run(prompt),
-  (result) => result.text.toUpperCase(),
-);
+```ts
+import {
+  GaussError,
+  DisposedError,
+  ProviderError,
+  ToolExecutionError,
+  ValidationError,
+} from "gauss-ts";
 
-const descriptions = await mapAsync(
-  ["apple", "banana", "cherry"],
-  (fruit) => agent.run(`Describe ${fruit}`),
-  { concurrency: 2 },
-);
+try {
+  await agent.run("hello");
+} catch (err) {
+  if (err instanceof DisposedError) {
+    // resource already destroyed
+  }
+}
 ```
 
 ---
 
-## 📐 Model Constants
+## Model Constants
 
-Import model constants as the single source of truth:
-
-```typescript
+```ts
 import {
-  // OpenAI
-  OPENAI_DEFAULT,      // "gpt-5.2"
-  OPENAI_FAST,         // "gpt-4.1"
-  OPENAI_REASONING,    // "o4-mini"
-  OPENAI_IMAGE,        // "gpt-image-1"
-
-  // Anthropic
-  ANTHROPIC_DEFAULT,   // "claude-sonnet-4-20250514"
-  ANTHROPIC_PREMIUM,   // "claude-opus-4-20250414"
-  ANTHROPIC_FAST,      // "claude-haiku-4-20250414"
-
-  // Google
-  GOOGLE_DEFAULT,      // "gemini-2.5-flash"
-  GOOGLE_PREMIUM,      // "gemini-2.5-pro"
-  GOOGLE_IMAGE,        // "gemini-2.0-flash"
-
-  // OpenRouter
-  OPENROUTER_DEFAULT,  // "openai/gpt-5.2"
-
-  // DeepSeek
-  DEEPSEEK_DEFAULT,    // "deepseek-chat"
-  DEEPSEEK_REASONING,  // "deepseek-reasoner"
-
-  // Helpers
-  PROVIDER_DEFAULTS,   // Record<string, string>
-  defaultModel,        // (provider: string) => string
+  OPENAI_DEFAULT, OPENAI_FAST, OPENAI_REASONING,
+  ANTHROPIC_DEFAULT, ANTHROPIC_FAST, ANTHROPIC_PREMIUM,
+  GOOGLE_DEFAULT, GOOGLE_PREMIUM,
+  DEEPSEEK_DEFAULT, DEEPSEEK_REASONING,
+  PROVIDER_DEFAULTS, defaultModel,
 } from "gauss-ts";
 ```
 
 ---
 
-## 🌐 Providers
+## Providers
 
-| Provider | Env Variable | Default Model |
-|----------|-------------|---------------|
+| Provider | Env Variable | Example Default |
+|---|---|---|
 | OpenAI | `OPENAI_API_KEY` | `gpt-5.2` |
 | Anthropic | `ANTHROPIC_API_KEY` | `claude-sonnet-4-20250514` |
 | Google | `GOOGLE_API_KEY` | `gemini-2.5-flash` |
 | DeepSeek | `DEEPSEEK_API_KEY` | `deepseek-chat` |
-| Groq | `GROQ_API_KEY` | `llama-3.3-70b-versatile` |
-| Ollama | — (local) | `llama3.2` |
+| Groq | `GROQ_API_KEY` | provider-dependent |
+| Ollama | local runtime | `llama3.2` |
 | OpenRouter | `OPENROUTER_API_KEY` | `openai/gpt-5.2` |
-
-Set one environment variable and Gauss auto-detects the provider:
-
-```bash
-export OPENAI_API_KEY=sk-...
-# or
-export ANTHROPIC_API_KEY=sk-ant-...
-# or
-export GOOGLE_API_KEY=AIza...
-```
-
----
-
-## 🧩 All Features
-
-| Feature | Module | Description |
-|---------|--------|-------------|
-| **Agent** | `Agent`, `gauss()` | LLM agent with tools, structured output, streaming |
-| **Streaming** | `AgentStream` | Async iterable streaming with `for await` |
-| **Batch** | `batch()` | Parallel prompt execution with concurrency control |
-| **Graph** | `Graph` | DAG-based multi-agent pipeline |
-| **Workflow** | `Workflow` | Step-based execution with dependencies |
-| **Team** | `Team` | Multi-agent team with strategy (round-robin, etc.) |
-| **Network** | `Network` | Multi-agent delegation with supervisor |
-| **Memory** | `Memory` | Persistent conversation memory |
-| **VectorStore** | `VectorStore` | Embedding storage and semantic search (RAG) |
-| **MCP** | `McpServer` | Model Context Protocol server |
-| **Middleware** | `MiddlewareChain` | Request/response processing pipeline |
-| **Guardrails** | `GuardrailChain` | Content moderation, PII, token limits, regex |
-| **Retry** | `withRetry`, `retryable` | Exponential/linear/fixed backoff with jitter |
-| **Resilience** | `createResilientAgent` | Fallback providers + circuit breaker |
-| **Structured** | `structured()` | Typed JSON extraction with auto-retry |
-| **Templates** | `template()` | Composable prompt templates with built-ins |
-| **Pipeline** | `pipe`, `mapAsync`, `compose` | Async data flow composition |
-| **Evaluation** | `EvalRunner` | Agent quality scoring with datasets |
-| **Telemetry** | `Telemetry` | Spans, metrics, and export |
-| **Approval** | `ApprovalManager` | Human-in-the-loop approval flow |
-| **Checkpoint** | `CheckpointStore` | Save/restore agent state |
-| **Tokens** | `countTokens` | Token counting and context window info |
-| **Plugins** | `PluginRegistry` | Extensible plugin system |
-| **Config** | `parseAgentConfig` | JSON config parsing with env resolution |
-| **A2A** | `A2aClient` | Agent-to-Agent protocol client |
-| **Tool Registry** | `ToolRegistry` | Searchable tool catalog with examples |
-| **Spec Parsers** | `AgentSpec`, `SkillSpec` | AGENTS.MD & SKILL.MD discovery and parsing |
+| Together | `TOGETHER_API_KEY` | provider-dependent |
+| Fireworks | `FIREWORKS_API_KEY` | provider-dependent |
+| Mistral | `MISTRAL_API_KEY` | provider-dependent |
+| Perplexity | `PERPLEXITY_API_KEY` | provider-dependent |
+| xAI | `XAI_API_KEY` | provider-dependent |
 
 ---
 
-## 🏗️ Architecture
+## Architecture
 
-Gauss-TS is a thin SDK wrapping **[gauss-core](https://github.com/giulio-leone/gauss-core)** (Rust) via NAPI bindings. All heavy lifting — agent loops, tool execution, middleware, graph/workflow orchestration — runs at native speed in Rust.
-
-```
-TypeScript SDK (30+ modules)
-       │
-       ▼
-  NAPI Bindings (80+ functions)
-       │
-       ▼
-  gauss-core (Rust engine)
+```text
+gauss-ts (TypeScript SDK)
+        │
+        ▼
+gauss-napi (NAPI bindings)
+        │
+        ▼
+gauss-core (Rust engine)
 ```
 
----
-
-## 📁 Examples
-
-See the [`examples/`](examples/) directory for **23 complete examples** covering every feature:
-
-| # | Example | Feature |
-|---|---------|---------|
-| 01 | Basic Agent | Agent creation, run, stream |
-| 02 | Planning Agent | Multi-step planning |
-| 03 | Sub-agent Orchestration | Agent delegation |
-| 04 | MCP Integration | Model Context Protocol |
-| 05 | Persistent Memory | Conversation memory |
-| 06 | Full-Featured | All features combined |
-| 07 | Plugin System | Custom plugins |
-| 08 | A2A Server | Agent-to-Agent protocol |
-| 09 | CLI & REST | HTTP + CLI interfaces |
-| 10 | Team Coordination | Multi-agent teams |
-| 11 | Voice Pipeline | Audio/voice processing |
-| 12 | Workflow DSL | Declarative workflows |
-| 13 | Multimodal Vision | Image understanding |
-| 14 | Video Processing | Video analysis |
-| 15 | Universal Provider | Cross-provider usage |
-| 16 | LLM Recording | Record & replay |
-| 17 | Zero Config | Auto-detect everything |
-| 18 | Tool Registry | Searchable tools |
-| 19 | Graph Pipeline | DAG pipelines |
-| 20 | Network Delegation | Supervisor networks |
-| 21 | Structured Output | JSON extraction |
-| 22 | DX Utilities | Developer experience helpers |
-| 23 | Reasoning | o4-mini, extended thinking |
+All heavy orchestration and runtime logic is executed in Rust.
 
 ---
 
-## 🔗 Ecosystem
-
-| Package | Language | Description |
-|---------|----------|-------------|
-| [`gauss-core`](https://github.com/giulio-leone/gauss-core) | Rust | Core engine — NAPI + PyO3 + WASM |
-| [`gauss-ts`](https://github.com/giulio-leone/gauss) | TypeScript | This SDK (NAPI bindings) |
-| [`gauss-py`](https://github.com/giulio-leone/gauss-py) | Python | Python SDK (PyO3 bindings) |
-
-## API Reference
-
-```bash
-npm run docs
-```
+## Ecosystem
 
-Generates HTML docs in `docs/api/` from JSDoc comments in the source.
+| Package | Language | Repo |
+|---|---|---|
+| `gauss-core` | Rust | https://github.com/giulio-leone/gauss-core |
+| `gauss-ts` | TypeScript | https://github.com/giulio-leone/gauss |
+| `gauss-py` | Python | https://github.com/giulio-leone/gauss-py |
 
 ## License