agentic-api 2.0.636 → 2.0.642

package/README.md

@@ -1,490 +1,454 @@
 # @agentic-api
 
-Comprehensive framework for intelligent agent orchestration, document processing, and enterprise workflow management. (inspired from [OpenAI Swarm](https://github.com/openai/openai-realtime-agents)) (01/2025)
+Comprehensive framework for intelligent agent orchestration, document processing, and enterprise workflow management. Inspired by [OpenAI Swarm](https://github.com/openai/openai-realtime-agents).
 
-> **Design Philosophy**:  
-> This project is not meant to be better than Vercel or LangChain. It's simply less generic and optimized for a specific set of enterprise problems.
-> It focuses on specific features that required too many dependencies with other frameworks.
+> **Design Philosophy**: This project is optimized for specific enterprise problems rather than being a generic framework. It follows a minimalist approach with the OpenAI SDK as the only core dependency. It focuses on features that required too many dependencies with other frameworks like Vercel AI or LangChain.
 
-## 🚀 Core Capabilities
+---
 
-### 🤖 Agent Orchestration
-- Multi-agent conversations with automatic transfers
-- State machine-driven workflows for complex processes
-- Confidence-based escalation between specialized agents
+## Core Capabilities
+
+### Agent Orchestration
+- Multi-agent conversations with automatic transfers and confidence-based escalation
 - **StateGraph Architecture**: Modern conversation state management with automatic persistence
+- **Context Injection**: Profile, instructions, and context-trail for coordination
+- **Multi-Provider LLM**: Support for OpenAI and xAI providers
 
-### 📄 Document Processing
+### Document Processing
 - **MapLLM**: Advanced map-reduce pattern for large document analysis
 - **Structured Outputs**: OpenAI JSON schema validation support
 - **Flexible Loaders**: File and string content processing with chunking strategies
-- **Callback-Driven**: User-defined logic for accumulation and flow control
 
-### 🧪 Testing & Validation
+### RAG (Retrieval-Augmented Generation)
+- **Multi-RAG Architecture**: Multiple indexes for different contexts (stable, draft, user emails, user projects)
+- **Incremental Fork**: 80-90% performance gain by building RAG only on document diff (SHA-based)
+- **Reactive Updates**: Auto-reload after modifications
+- **Semantic Search**: Vector-based search with HNSW indexing
+
+### Testing & Validation
 - **Agent Simulator**: Comprehensive testing framework with scenario-based simulations
-- **Realistic Personas**: Authentic user behavior simulation for thorough testing
-- **Automatic Validation**: Built-in success/failure detection and reporting
+- **Built-in Personas**: Authentic user behavior simulation (patient, rushed, frustrated)
+- **Tool Validation**: Ensures tools are used correctly with `equal`, `gte`, `lte` constraints
 
-### 📋 Enterprise Workflow
+### Enterprise Workflow
+A virtuous cycle for company procedures and guidelines: when a result is incorrect, users can correct it and create a validation request to the responsible person.
 - **Rules Management**: Git-based workflow for business rules and procedures
 - **Pull Request Validation**: Structured review and approval processes
-- **Multi-File Operations**: Atomic operations across related documents
-- **Search Integration**: Full-text search with RAG embeddings
-
-## 🎯 Key Advantages
-
-1. **Enterprise-Ready**
-   - Production-grade document workflows
-   - Comprehensive testing capabilities
-   - Git-based version control integration
-
-2. **Developer-Friendly**
-   - Minimal configuration required
-   - TypeScript-first with full type safety
-   - Modular architecture for easy extension
-
-3. **Performance-Optimized**
-   - Efficient chunking strategies
-   - Intelligent caching systems
-   - Parallel processing support
-
-### Recommended Use Cases
-
-- **Enterprise Document Management**: Rules, procedures, and knowledge base management
-- **Agent Development & Testing**: Comprehensive agent behavior validation
-- **Large Document Processing**: Analysis and synthesis of complex documents
-- **Conversational AI Systems**: Multi-agent workflows with state management
+- **Stable IDs**: Unique document identifiers that persist across branches and renames
 
+---
 
-[![](https://mermaid.ink/img/pako:eNpVkcluwjAQhl_FGgmJSoDIQoAcKhEQ7aGXNkiVmqDKTYYkUmJHxu5GeZaq575cH6EmC8sc7PnG_4xn7B1EPEZwYZPztyilQpLVImREmy81dYNqW1_VsVlwIxAlinXNi24Qwt_37w-5VQVlIbTCet2ql0TQMiU-itcswudZgkxuSdAwqbkpdrA4ExjJjDNy93CKekbg0xzPhZ4ZzNVW8gIF8VVZct3k2akV3CsujxnI4pDV7jx4XC3XLVXTkX7_msyaCSvwjAsyL8hqkzsdsuQi0h3QPEsYFnoYknKRfXImaV6LPIP0B2dFPLNhq2Gr5kVbtUn4WtIsVwK_yLxp_HD7KXrUQw_0IxQ0i_U37g6xEGSqmwnB1W6MG6pyGULI9lpKleT-B4vAlUJhDwRXSQruhuZbTaqMqcRFRvW3Fa2kpOyJ8yMm4nBTk60fFsWcKybBHVVScHfwrmFiDgzTGJvToWFY2nrwAe54OBg5pu1Yjj21Dcd29j34rGoPB5OxPT23_T90g8Qf?type=png)](https://mermaid.live/edit#pako:eNpVkcluwjAQhl_FGgmJSoDIQoAcKhEQ7aGXNkiVmqDKTYYkUmJHxu5GeZaq575cH6EmC8sc7PnG_4xn7B1EPEZwYZPztyilQpLVImREmy81dYNqW1_VsVlwIxAlinXNi24Qwt_37w-5VQVlIbTCet2ql0TQMiU-itcswudZgkxuSdAwqbkpdrA4ExjJjDNy93CKekbg0xzPhZ4ZzNVW8gIF8VVZct3k2akV3CsujxnI4pDV7jx4XC3XLVXTkX7_msyaCSvwjAsyL8hqkzsdsuQi0h3QPEsYFnoYknKRfXImaV6LPIP0B2dFPLNhq2Gr5kVbtUn4WtIsVwK_yLxp_HD7KXrUQw_0IxQ0i_U37g6xEGSqmwnB1W6MG6pyGULI9lpKleT-B4vAlUJhDwRXSQruhuZbTaqMqcRFRvW3Fa2kpOyJ8yMm4nBTk60fFsWcKybBHVVScHfwrmFiDgzTGJvToWFY2nrwAe54OBg5pu1Yjj21Dcd29j34rGoPB5OxPT23_T90g8Qf)
-
-## 📦 Installation
+## Installation
 
 ```bash
 npm install @agentic-api
 ```
 
-## 💡 Quick Start
+---
+
+## Quick Start
 
 ### Configuration `.env`
 
 ```bash
-# Provider LLM (openai | xai)
+# LLM Provider (openai | xai)
 LLM_PROVIDER=openai
 
-# Clés API
-OPENAI_API_KEY=sk-...    # Requis pour OpenAI + embeddings + whisper
-XAI_API_KEY=xai-...      # Requis si LLM_PROVIDER=xai
+# API Keys
+OPENAI_API_KEY=sk-...    # Required for OpenAI + embeddings + whisper
+XAI_API_KEY=xai-...      # Required if LLM_PROVIDER=xai
 ```
 
-### Usage
+### Basic Usage
 
 ```typescript
-import { llmInstance, executeAgentSet, AgenticContext, AgentStateGraph } from '@agentic-api';
+import { llmInstance, executeAgentSet, AgenticContext } from '@agentic-api';
 
-// Initialiser le LLM (utilise LLM_PROVIDER depuis .env)
+// Initialize LLM (uses LLM_PROVIDER from .env)
 llmInstance();
 
 // Create context with user information
 const context: AgenticContext = {
-  user: {
-    id: "user123",
-    role: "user"
-  },
-  credential: "your-api-key"
+  user: { id: "user123", role: "user" },
+  credential: "msal-or-google-delegation-token"  // MSAL or Google delegation token
 };
 
 // Execute agent with StateGraph (automatically managed)
 const stream = await executeAgentSet(agents, context, {
   query: "Hello, what can you do?",
-  home: "welcome", // Starting agent
+  home: "welcome",
   verbose: true,
-  enrichWithMemory: async (role) => {
-    // Memory enrichment logic
+  enrichWithMemory: async (role, agent, context) => {
+    // Injects user profile, global/session instructions, and history
+    // See "Context Injection" section below for details
     return "";
   }
 });
 ```
 
-## 🤖 Custom Agent Creation
+---
+
+## Model Levels
+
+The framework supports multiple LLM providers with unified model levels:
+
+| Level | OpenAI | xAI | Usage |
+|-------|--------|-----|-------|
+| **LOW** | gpt-5-nano | grok-4-fast-non-reasoning | Simple tasks, economical |
+| **LOW-fast** | gpt-5-nano | grok-code-fast-1 | Ultra fast |
+| **MEDIUM** | gpt-5-mini | grok-4-fast-reasoning | Balanced performance/cost |
+| **HIGH** | gpt-5.1 | grok-4 | Advanced reasoning |
+| **SEARCH** | gpt-5-mini + web_search | grok-4-fast-reasoning + web_search | Web search |
+| **VISION** | gpt-5-mini | grok-4 | Image analysis |
+| **EMBEDDING-small** | text-embedding-3-small | OpenAI only | Embeddings |
+| **WHISPER** | whisper-1 | OpenAI only | Audio transcription |
 
 ```typescript
-import { AgentConfig, modelConfig } from '@agentic-api';
+import { modelConfig, llmInstance } from '@agentic-api';
+
+// Initialize with explicit configuration
+// Note: provider could be a user preference instead of server-side config
+const openai = llmInstance({ provider: 'openai', apiKey: process.env.OPENAI_API_KEY });
+const xai = llmInstance({ provider: 'xai', apiKey: process.env.XAI_API_KEY });
 
-// Example specialized agent with thinking tool
+// Get model config for specific provider
+const config = modelConfig("MEDIUM", { provider: 'openai' });
+const xaiConfig = modelConfig("HIGH", { provider: 'xai' });
+const embedConfig = modelConfig("EMBEDDING-small", { provider: 'openai' });
+```
+
+---
+
+## Custom Agent Creation
+
+```typescript
+import { AgentConfig, injectTransferTools } from '@agentic-api';
+
+// Specialized agent
 const haiku: AgentConfig = {
   name: "haiku",
   publicDescription: "Agent that writes haikus.",
   instructions: "Ask the user for a subject, then respond with a haiku.",
-  model: modelConfig("LOW"),
+  model: 'LOW',  // String alias, converted at runtime
   tools: [],
-  maxSteps: 3 // Limit thinking steps
+  maxSteps: 3
 };
 
-// Welcome agent with transfer
+// Router agent with transfers
 const welcome: AgentConfig = {
   name: "welcome",
   publicDescription: "Agent that welcomes users.",
-  instructions: "Welcome the user and suggest options.",
-  model: modelConfig("LOW"),
+  instructions: "Welcome the user and route to appropriate specialist.",
+  model: 'LOW',
   tools: [],
   downstreamAgents: [haiku]
 };
 
-// Inject transfer and thinking tools
-import { injectTransferTools } from '@agentic-api';
-const myAgents = injectTransferTools([welcome, haiku]);
+// Inject transfer tools automatically
+const agents = injectTransferTools([welcome, haiku]);
 ```
 
-## 🧠 StateGraph Memory Management
-
-The new StateGraph architecture provides automatic conversation state management:
-
-```typescript
-import { AgentStateGraph, sessionStateGraphGet, sessionStateGraphSet } from '@agentic-api';
+---
 
-// StateGraph is automatically managed during executeAgentSet
-// But you can also work with it directly:
+## Agent Transfer System
 
-function setupStateGraph(req: Request) {
-  // Get existing StateGraph from session (with automatic migration)
-  let stateGraph = sessionStateGraphGet(req);
-  if (!stateGraph) {
-    stateGraph = new AgentStateGraph();
-  }
-  
-  // Create or restore discussion for specific agent
-  const discussion = stateGraph.createOrRestore("welcome");
-  
-  // Add messages to discussion
-  stateGraph.push("welcome", {
-    role: "user",
-    content: "Hello!"
-  });
-  
-  // Update token usage
-  stateGraph.updateTokens("welcome", {
-    prompt: 10,
-    completion: 20,
-    total: 30,
-    cost: 0.001
-  });
-  
-  // Save back to session with gzip compression
-  sessionStateGraphSet(req, stateGraph);
-  
-  return stateGraph;
-}
+The multi-agent transfer system enables specialized agents to collaborate:
 
-// Client-safe view (filters system messages and tools)
-const clientDiscussion = stateGraph.toClientView("welcome");
+```
+┌─────────────────┐
+│  Router Agent   │ ─── Qualifies and routes
+└────────┬────────┘
+         │
+    ┌────┴────┬────────────┐
+    ▼         ▼            ▼
+┌────────┐ ┌────────┐ ┌────────┐
+│  Info  │ │ Action │ │ Admin  │
+└────────┘ └────────┘ └────────┘
 ```
 
-## 🧠 Legacy Memory Management (MemoriesLite)
+**Key Features:**
+- Confidence threshold (0.7) for transfer decisions
+- Automatic context preservation via `<context-trail>`
+- Specialized agent tracking for return after temporary transfers
 
 ```typescript
-import { MemoriesLite } from '@memories-lite';
-
-const memory = new MemoriesLite({
-  // Memory configuration
-});
-
-async function chatWithMemories(message: string, userId = "default_user") {
-  // Semantic memory search
-  const relevantMemories = await memory.retrieve(message, userId, {
-    limit: 5,
-    filters: { type: "conversation" }
-  });
-  
-  const systemPrompt = `You are a helpful AI. Answer based on query and memories.
-User Memories:
-${relevantMemories.results.map(entry => `- ${entry.memory}`).join("\n")}`;
-
-  const messages = [
-    { role: "system", content: systemPrompt },
-    { role: "user", content: message },
-  ];
-
-  // Capture new conversation
-  await memory.capture(messages, userId, {
-    metadata: { type: "conversation" }
-  });
+// Transfer tool schema (auto-generated)
+{
+  rationale_for_transfer: string,  // Why this transfer
+  conversation_context: string,    // Context for destination
+  destination_agent: string,       // Target agent name
+  confidence: number               // >= 0.7 required
 }
 ```
 
-## ⚙️ Model Levels
+**Documentation:** [Agent Transfer](./docs/11.AGENT-TRANSFER.md)
 
-- **LOW**: gpt-4o-mini (simple tasks)
-- **MEDIUM**: gpt-4o (balanced performance/cost)
-- **HIGH**: gpt-4o (advanced reasoning)
-- **SEARCH**: gpt-4o-mini-search-preview (web search with localization)
+---
 
-## 🔄 Agent Transfer
+## Context Injection
 
-Agent transfer is automatically managed with:
-- **Temporary transfers**: Agents transfer for single transactions and return to specialized agent
-- Confidence threshold (0.7) for transfer  
-- Transfer justification
-- Conversation context preservation
-- Automatic system instruction updates
-- **Specialized agent tracking**: Each discussion remembers its starting agent
+Architecture based on OpenAI best practices for profile and memory injection:
+
+| Priority | Tag | Location | Description |
+|----------|-----|----------|-------------|
+| 2 (Required) | Agent instructions | System | Non-modifiable by user |
+| 1 (High) | `<profile>`, `<instructions>`, `<context>` | System/User | User context |
+| 0 (Low) | `<history>` | System | Informational only |
+| Auto | `<context-trail>` | System | Tool calls and transfers tracking |
 
 ```typescript
-// Transfer logic (handled automatically)
-// 1. Agent A processes user message
-// 2. If tool calls indicate transfer to Agent B
-// 3. Agent B handles the specific task
-// 4. Control returns to Agent A (specialized agent)
+import { renderContextInjection, renderUserContextInjection } from '@agentic-api';
+
+// System message injection (profile + instructions)
+const systemInjection = renderContextInjection(
+  'date: 24/01/2026\nname: John',  // userProfile
+  '- Prefers French',               // globalInstructions
+  '- Budget max 50k',               // sessionInstructions
+  'Previous discussion summary'     // history (optional)
+);
+
+// User message injection (attached assets)
+const userMessage = renderUserContextInjection(assets) + userQuery;
 ```
 
-## 🔄 StateGraph Features
+---
 
-### **Core Operations**
-```typescript
-// Create or restore agent discussion
-const discussion = stateGraph.createOrRestore("agentName");
-
-// Add messages with auto-generated ID and timestamp
-stateGraph.push("agentName", {
-  role: "assistant", 
-  content: "Hello!",
-  name: "functionName" // For OpenAI tool calls
-});
+## StateGraph Memory Management
 
-// Set system message (overwrites existing)
-stateGraph.set("agentName", "You are a helpful assistant");
+StateGraph manages conversation state across multiple discussions. It enables switching between agent discussions, serializing the state, and exporting a client-safe view:
 
-// Update token usage (cumulative)
-stateGraph.updateTokens("agentName", { 
-  prompt: 10, 
-  completion: 20, 
-  cost: 0.001 
-});
+```typescript
+import { AgentStateGraph, sessionStateGraphGet, sessionStateGraphSet } from '@agentic-api';
 
-// Clear discussion (keeps system message)
-stateGraph.clearDiscussion("agentName");
-```
+// Get or create StateGraph
+let stateGraph = sessionStateGraphGet(req) || new AgentStateGraph();
 
-### **Utility Functions**
-```typescript
-// Get specialized (starting) agent for discussion
-import { getSpecializedAgent } from '@agentic-api';
-const specializedAgent = getSpecializedAgent(discussion);
+// Create or restore discussion
+const discussion = stateGraph.createOrRestore("welcome");
 
-// Find discussion by ID
-const discussion = stateGraph.findDiscussionById("discussion-123");
+// Add messages
+stateGraph.push("welcome", { role: "user", content: "Hello!" });
 
-// Rename discussion
-stateGraph.renameDiscussion("agentName", "New Name", "Description");
+// Track token usage
+stateGraph.updateTokens("welcome", {
+  prompt: 10, completion: 20, total: 30, cost: 0.001
+});
+
+// Save with gzip compression
+sessionStateGraphSet(req, stateGraph);
 
-// Delete discussion
-stateGraph.deleteDiscussion("agentName");
+// Client-safe view (filters system messages and tools)
+const clientView = stateGraph.toClientView("welcome");
 ```
 
-## 🗂️ MapLLM Document Processing
+**Documentation:** [StateGraph](./docs/13.STATEGRAPH.md)
 
-Modern map-reduce pattern for processing large documents with flexible content handling and OpenAI structured outputs.
+---
 
-- **Flexible Loaders**: `FileNativeLoader` and `StringNativeLoader` with configurable chunking strategies
-- **Callback-Driven**: User-defined logic for accumulation, termination, and flow control
-- **Structured Outputs**: Optional JSON schema validation via OpenAI structured outputs
-- **Robust EOF Handling**: Proper chunk boundary detection and clean termination
+## RAG System
 
-📖 **[Complete MapLLM Documentation →](./docs/README-AGENT-REDUCE.md)**
+Multi-RAG architecture with semantic search:
 
 ```typescript
-import { MapLLM, FileNativeLoader, modelConfig } from '@agentic-api';
-
-// Basic text processing
-const config = {
-  digestPrompt: "Analyze this chunk for key information.",
-  reducePrompt: "Merge analysis with previous results."
-};
-
-const loader = new FileNativeLoader('document.pdf', { type: 'pages', size: 1 });
-const mapper = new MapLLM(loader);
+import { RAGManager } from '@agentic-api';
 
-const callback = (result, currentValue) => {
-  result.acc = result.acc + `\n${currentValue}\n`;
-  
-  // Stop conditions
-  if (result.acc.length > 5000) {
-    result.continue = true;
-  }
-  if (result.metadata.iterations > 20) {
-    result.maxIterations = true;
-  }
-  
-  return result;
-};
+// Singleton pattern per baseDir
+const ragManager = RAGManager.get({
+  baseDir: './rag-data',
+  maxArchives: 5
+});
 
-const init = {
-  acc: "",
-  model: modelConfig("LOW-fast"),
-  verbose: true
-};
+// Create RAG
+await ragManager.create('procedures', { description: 'Validated procedures' });
 
-const result = await mapper.reduce(config, callback, init);
-console.log('Final result:', result.acc);
-
-// Structured output processing with JSON schema
-const myJsonSchema = {
-  type: "object",
-  properties: {
-    summary: { type: "string" },
-    key_points: { type: "array", items: { type: "string" } }
-  },
-  required: ["summary", "key_points"]
-};
+// Incremental fork (80-90% performance gain)
+await ragManager.create('procedures-v2', {
+  fork: 'procedures',
+  exclude: ['modified-1.md', 'modified-2.md']
+});
 
-const structuredCallback = (result, currentValue) => {
-  // Set structured output format
-  result.format = {
-    name: "analysis",
-    schema: myJsonSchema,
-    strict: true
-  };
-  
-  // For structured output, accumulate as object or merged object
-  result.acc = { ...result.acc, ...currentValue };
-  
-  if (result.metadata.iterations > 5) {
-    result.maxIterations = true;
-  }
-  
-  return result;
-};
+// Build and search
+await ragManager.build('procedures');
+const embeddings = ragManager.load('procedures');
 
-const structuredResult = await mapper.reduce(config, structuredCallback, { 
-  acc: {}, 
-  verbose: true 
-});
-// structuredResult.acc is validated JSON matching the schema
+if (embeddings.isReady()) {
+  const results = await embeddings.semanticSearch('How to validate budget?', {
+    neighbors: 5
+  });
+}
 ```
 
-## 🤖 Agent Simulator
+**Documentation:** [RAG Overview](./docs/30.RAG-OVERVIEW.md) | [RAG Manager](./docs/31.RAG-MANAGER.md)
 
-Advanced testing framework for agent behavior validation with scenario-based simulations.
+---
 
-- **Clean API**: Separated `scenario` (context) and `testCase` (test parameters)
-- **Oneshot by Default**: `maxExchanges=1` for simple single-response tests
-- **Automatic Tool Validation**: Built-in validation with `expectedTools`
-- **Exchange Limiting**: Control simulation length with configurable exchange limits
+## Agent Simulator
 
-📖 **[Complete Agent Simulator Documentation →](./docs/README-AGENT-SIMULATOR.md)**
+Testing framework with scenario-based simulations:
 
 ```typescript
 import { AgentSimulator, PERSONA_PATIENT } from '@agentic-api';
 
-// Configure simulator
 const simulator = new AgentSimulator({
-  agents: [haikuAgent, welcomeAgent],
+  agents: [welcomeAgent, specialistAgent],
   start: "welcome",
   verbose: true
 });
 
-// Define test scenario (context)
+// Define scenario (context)
 const scenario = {
-  goals: "Verify that the agent can help with haiku creation. Agent provides a complete haiku poem.",
+  goals: "Verify agent handles requests correctly and transfers when needed.",
   persona: PERSONA_PATIENT
-  // result defaults to '{"success": boolean, "explain": string, "error": string}'
 };
 
 // Run test case
 const result = await simulator.testCase(scenario, {
-  query: "I want to write a haiku about nature. Can you help me?",
+  query: "I need help with my heating issue",
   maxExchanges: 5,  // defaults to 1 (oneshot)
-  expectedTools: { 'transferAgents': { gte: 1 } }  // defaults to {}
+  expectedTools: { 'transferAgents': { gte: 1 } }
 });
 
-// Validate results
 console.log('Success:', result.success);
-console.log('Summary:', result.message);
 console.log('Exchanges:', result.exchangeCount);
+console.log('Messages:', result.messages.length);
+```
 
-if (!result.success) {
-  console.error('Error:', result.error);
-}
+**Built-in Personas:**
+- `PERSONA_PATIENT` - Patient, polite user
+- `PERSONA_PRESSE` - Rushed user wanting quick solutions
+- `PERSONA_ENERVE` - Frustrated user, 3rd call for same problem
+
+**Documentation:** [Agent Simulator](./docs/10.AGENT.SIMULATOR.md)
+
+---
+
+## MapLLM Document Processing
+
+True map-reduce pattern for large documents with structured outputs and callback-driven accumulation:
+
+```typescript
+import { MapLLM, FileNativeLoader, StringNativeLoader } from '@agentic-api';
+
+// Chunking strategies: lines, pages, paragraphs, overlap
+const loader = new FileNativeLoader('document.pdf', { type: 'pages', size: 1 });
+const mapper = new MapLLM(loader);
+
+const config = {
+  digestPrompt: "Analyze this chunk and extract key points.",
+  reducePrompt: "Merge this analysis with previous results.",
+  reduceModulo: 5  // Optional: reduce every N chunks
+};
+
+// Callback controls accumulation and termination
+const result = await mapper.reduce(config, (result, currentValue) => {
+  // Structured output support
+  result.format = { name: "analysis", schema: myJsonSchema, strict: true };
+  result.acc = { ...result.acc, ...currentValue };
+  
+  // Stop conditions
+  if (result.metadata.iterations > 20) result.maxIterations = true;
+  return result;
+}, { acc: {}, model: 'LOW', verbose: true });
 ```
 
-### Simulation Features
+**Documentation:** [MapLLM](./docs/10.AGENTS.MAPLLM.md)
 
-- **Separated Concerns**: `scenario` for context, `testCase` for test parameters
-- **Sensible Defaults**: `maxExchanges=1`, `expectedTools={}`, default result format
-- **Persona Simulation**: Built-in personas (PERSONA_PATIENT, PERSONA_PRESSE, PERSONA_ENERVE)
-- **Tool Validation**: Automatic validation with `equal`, `gte`, `lte` constraints
-- **Execution Metadata**: Access to token usage, actions, and performance metrics
+---
 
-## 📋 Rules Management System
+## JobRunner (Plan → Execute → Reduce)
 
-Enterprise-grade Git-based workflow for managing business rules, procedures, and documentation.
+Sequential task execution engine for complex multi-objective requests:
 
-- **Git-Based Workflow**: Complete version control with branch-based status management
-- **Pull Request Validation**: Structured validation process with reviewer assignment
-- **Multi-File Operations**: Atomic operations across multiple related documents
-- **Content Management**: Rich metadata support with front-matter parsing
-- **Search Integration**: Full-text search with RAG embeddings support
+```typescript
+import { JobRunner, jobPlannerPrompt } from '@agentic-api';
+
+// JobRunner workflow:
+// 1. Planner: userRequest → JobPlan (list of TaskSpec)
+// 2. Executor: TaskSpec + memory → TaskResult
+// 3. Reducer: (prevMemory, task, result) → ReducedJobMemory (via MapLLM)
+
+// Features:
+// - Strict contracts (structured outputs / schema validation)
+// - Context reduction after each task via MapLLM reducer
+// - Error policy: 2 attempts max per task, then thrown → synthesis
+// - Sequential deterministic execution (V1)
+```
+
+**Key Contracts:**
+- `JobPlan`: jobId, goal, tasks[]
+- `TaskSpec`: id, title, type, dependsOn[], acceptance[]
+- `TaskResult`: taskId, ok, summary, data, artifacts[], error
+- `ReducedJobMemory`: memory (short canonical), index (stable refs)
+
+**Documentation:** [JobRunner](./docs/10.AGENTS.JOB.md)
+
+---
 
-📖 **[Complete Rules System Documentation →](./docs/README-RULES-SYSTEM.md)**
+## Rules Management System
+
+Git-based workflow for business documents:
 
 ```typescript
 import { RulesWorkflow, gitLoad, RuleStatus } from '@agentic-api';
 
-// Initialize workflow
-const config = gitLoad(); // Loads from environment variables
-const workflow = new RulesWorkflow(config);
+const workflow = new RulesWorkflow(gitLoad());
 
-// Create a new rule
-const newRule = await workflow.createRule('procedures/finance/budget.md', {
+// Create rule with auto-generated ID
+const rule = await workflow.createRule('procedures/budget.md', {
   title: 'Budget Validation Process',
-  slugs: ['budget-validation'],
   tags: ['finance', 'validation'],
   role: 'rule'
-}, 'Initial budget validation procedure');
+}, 'Initial content...');
 
-// Create validation request (PR)
+// Create PR for validation
 const prBranch = await workflow.createPullRequest(
-  ['procedure-a.md', 'procedure-b.md'], 
-  'Update financial procedures'
+  ['procedures/budget.md'],
+  'New budget procedure'
 );
 
-// Search rules by content
-const searchResults = await workflow.searchRules('budget validation', {
-  branch: 'main',
-  tags: ['finance'],
-  limit: 10
-});
-
-// Get rules by status
-const draftRules = await workflow.getRulesByStatus(RuleStatus.EDITING);
+// Search and filter
+const results = await workflow.searchRules('budget', { tags: ['finance'] });
+const drafts = await workflow.getRulesByStatus(RuleStatus.EDITING);
 ```
 
-## 🧪 Testing
+**Branch-Based Status:**
+| Branch | Status |
+|--------|--------|
+| `main` | PUBLISHED |
+| `rule-editor` | EDITING |
+| `rule-validation-*` | PULLREQUEST |
+
+**Documentation:** [Rules Overview](./docs/40.RULES-OVERVIEW.md)
+
+---
+
+## Documentation
+
+Complete documentation available in `./docs/`:
+
+- [Agent Configuration](./docs/10.AGENTS.md)
+- [Agent Transfer](./docs/11.AGENT-TRANSFER.md)
+- [StateGraph](./docs/13.STATEGRAPH.md)
+- [RAG Overview](./docs/30.RAG-OVERVIEW.md)
+- [Rules Overview](./docs/40.RULES-OVERVIEW.md)
+- [Troubleshooting](./docs/90.TROUBLESHOOTING.md)
+
+---
+
+## Testing
 
 ```bash
 npm test
 ```
 
-## 📄 License
+---
 
-MIT License
+## License
 
-Copyright (c) 2024 Pilet & Renaud SA
+MIT License - Copyright (c) 2024-2026 olivier@evaletolab.ch
 
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-api",
-  "version": "2.0.636",
+  "version": "2.0.642",
   "description": "API pour l'orchestration d'agents intelligents avec séquences et escalades automatiques",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",