agentfootprint 1.4.1 → 1.4.2

package/README.md

@@ -16,21 +16,17 @@
   <a href="https://footprintjs.github.io/footPrint/"><img src="https://img.shields.io/badge/Built_on-footprintjs-ca8a04?style=flat" alt="Built on footprintjs"></a>
 </p>
 
-<br>
-
-Most agent frameworks give you execution. agentfootprint gives you **connected evidence** — grounded, auditable, LLM-readable. The LLM can explain its own decisions. You can verify it wasn't hallucinating.
+> **Most agent frameworks give you execution. agentfootprint gives you connected evidence** — grounded, auditable, LLM-readable. The LLM can explain its own decisions. You can verify it wasn't hallucinating.
 
 ```bash
 npm install agentfootprint
 ```
 
-Import what you need — each capability is a subpath:
-
 ```typescript
 import { Agent, defineTool } from 'agentfootprint';              // Build agents
 import { mock, anthropic } from 'agentfootprint/providers';      // Connect providers
-import { defineInstruction } from 'agentfootprint/instructions'; // Smart behavior
-import { agentObservability } from 'agentfootprint/observe';     // Monitor execution
+import { defineInstruction } from 'agentfootprint/instructions'; // Conditional behavior
+import { agentObservability } from 'agentfootprint/observe';     // Observability
 import { withRetry } from 'agentfootprint/resilience';           // Reliability
 import { gatedTools } from 'agentfootprint/security';            // Tool safety
 import { ExplainRecorder } from 'agentfootprint/explain';        // Grounding analysis
@@ -41,30 +37,101 @@ import { SSEFormatter } from 'agentfootprint/stream';            // Real-time ev
 
 ## Start Simple, Compose Up
 
-Five concepts. Each adds one capability. No upfront graph DSL — start with a function call and grow.
+Six concepts. Start with a single LLM call, compose up to multi-agent. No upfront graph DSL.
 
 ```typescript
-import { Agent, defineTool, mock } from 'agentfootprint';
+import { Agent, defineTool } from 'agentfootprint';
+import { mock } from 'agentfootprint/providers';
+import { agentObservability } from 'agentfootprint/observe';
 
+const obs = agentObservability();
 const agent = Agent.create({ provider: mock([...]) })
   .system('You are a research assistant.')
   .tool(searchTool)
+  .recorder(obs)
   .build();
 
 const result = await agent.run('Find AI trends');
-console.log(result.content);
-console.log(agent.getNarrative());  // connected execution trace
+console.log(result.content);              // LLM response
+console.log(obs.explain().iterations);    // per-iteration evaluation data ← the differentiator
 ```
 
+**Single LLM** (one agent, one task):
+
 | Concept | What it adds | Use case |
 |---------|-------------|----------|
 | **LLMCall** | Single LLM invocation | Summarization, classification |
 | **Agent** | + Tool use loop (ReAct) | Research, code generation |
 | **RAG** | + Retrieval | Q&A over documents |
-| **FlowChart** | + Sequential pipeline | Approval flows, ETL |
-| **Swarm** | + LLM-driven routing | Customer support, triage |
 
-All five share one interface: `.build()` → `.run()`, `.getNarrative()`, `.getSnapshot()`.
+**Multi-Agent** (compose agents):
+
+| Concept | What it adds | Use case |
+|---------|-------------|----------|
+| **FlowChart** | Sequential pipeline | Approval flows, ETL — output of one feeds the next |
+| **Parallel** | Concurrent execution | Analysis from multiple perspectives — merged by LLM |
+| **Swarm** | LLM-driven routing | Customer support — orchestrator delegates to specialists |
+
+All six share one interface: `.build()` → `.run()`, `.getNarrative()`, `.getSnapshot()`.
+
+---
+
+## Architecture — 5 Layers
+
+```
+Layer 1: BUILD          → concepts/     Single LLM (LLMCall, Agent, RAG)
+                                         Multi-Agent (FlowChart, Parallel, Swarm)
+                          tools/         defineTool, ToolRegistry, askHuman
+
+Layer 2: COMPOSE        → lib/loop/     buildAgentLoop — the ReAct engine
+                          lib/slots/    SystemPrompt, Messages, Tools subflows
+
+Layer 3: EVALUATE       → recorders/    ExplainRecorder — per-iteration evaluation
+                          explain       obs.explain() → { iterations, sources, claims, context }
+
+Layer 4: MONITOR        → recorders/    TokenRecorder, CostRecorder, ToolUsageRecorder
+                          streaming/    AgentStreamEvent, SSEFormatter
+                          narrative     Human-readable execution story (footprintjs)
+
+Layer 5: INFRASTRUCTURE → adapters/     Anthropic, OpenAI, Bedrock, Mock, MCP, A2A
+                          providers/    Prompt, Message, Tool strategies
+                          memory/       Conversation stores (Redis, Postgres, DynamoDB)
+```
+
+Each folder has a README. Start at Layer 1, add layers as you need them.
+
+Built on [footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. One DFS traversal, three observer systems (scope/flow/agent), connected data out.
+
+---
+
+## What's Different
+
+Features no other agent framework provides — and why they matter.
+
+**Quality:**
+
+| Feature | What |
+|---------|------|
+| **Dynamic ReAct** | All 3 slots (prompt, tools, messages) re-evaluate EACH loop iteration. Agent adapts mid-conversation. |
+| **Conditional Behavior** | `defineInstruction({ activeWhen })` — rules activate based on accumulated decision state. |
+| **Tool Result Recency** | Instructions inject into the recency window AFTER tool calls — guidance at the right moment. |
+| **Per-Iteration Evaluation** | `obs.explain().iterations` — context + decisions + sources + claims connected per loop. |
+
+**Safety & Cost:**
+
+| Feature | What |
+|---------|------|
+| **Permission-Gated Tools** | LLM never SEES blocked tools — filtered at resolve time. Can't hallucinate a tool it never saw. |
+| **$0 Testing** | `mock()` adapter — same interface as Anthropic/OpenAI. Full test suite, zero API spend. |
+
+**UX & Debugging:**
+
+| Feature | What |
+|---------|------|
+| **Human-in-the-Loop** | Agent pauses, serializes to JSON, resumes hours later on a different server. `askHuman()`. |
+| **Streaming Events** | 9-event discriminated union. Build React/Next.js real-time UI. SSEFormatter for SSE. |
+| **Narrative Traces** | Human-readable execution story a follow-up LLM can reason about. |
+| **Single Traversal** | 3 observer systems fire during ONE DFS pass → all data connected. No post-processing. |
 
 ---
 
@@ -73,6 +140,8 @@ All five share one interface: `.build()` → `.run()`, `.getNarrative()`, `.getS
 Write tests with `mock()`. Deploy with `anthropic()`. Same code. $0 test runs.
 
 ```typescript
+import { mock, createProvider, anthropic } from 'agentfootprint/providers';
+
 // test — deterministic, free, instant
 const provider = mock([{ content: 'Paris.' }]);
 
@@ -87,12 +156,15 @@ Works with Anthropic, OpenAI, Bedrock, Ollama. No lock-in.
 
 ---
 
-## Instructions — Conditional Context Injection
+## Features
+
+### Conditional Behavior
 
-One concept. Three LLM API positions. Define a rule once — it injects into system prompt, tools, AND tool-result recency window. Driven by accumulated state.
+Define rules that inject into system prompt, tools, AND tool-result recency window. Driven by accumulated state. All 3 slots re-evaluate each iteration in Dynamic mode — progressive tool authorization, context-aware prompts, state-driven behavior.
 
 ```typescript
-import { defineInstruction, Agent, AgentPattern } from 'agentfootprint';
+import { defineInstruction } from 'agentfootprint/instructions';
+import { Agent, AgentPattern } from 'agentfootprint';
 
 const refund = defineInstruction({
   id: 'refund-handling',
@@ -100,103 +172,52 @@ const refund = defineInstruction({
   prompt: 'Handle denied orders with empathy. Follow refund policy.',
   tools: [processRefund],
   onToolResult: [{ id: 'empathy', text: 'Do NOT promise reversal.' }],
+  safety: true,   // fail-closed: fires even when predicate throws
 });
 
 const agent = Agent.create({ provider })
   .tool(lookupOrder)
   .instruction(refund)
   .decision({ orderStatus: null })
-  .pattern(AgentPattern.Dynamic)   // re-evaluate each iteration
+  .pattern(AgentPattern.Dynamic)
   .build();
 ```
 
-Tool results update the decision scope via `decide()`. Next iteration, different instructions activate. Progressive tool authorization, context-aware prompts, state-driven behavior — all declarative.
-
-See [Instructions Guide](docs/guides/instructions.md).
+### Narrative Traces
 
----
-
-## LLM Narrative — Connected Evidence
-
-Not disconnected spans. Not logs. **Connected entries** with key, value, stageId — collected during the single traversal pass. The LLM can read its own trace and answer follow-up questions.
+Connected entries with key, value, stageId — collected during traversal. Feed to a follow-up LLM for debugging.
 
 ```typescript
-const result = await agent.run('Check order ORD-1003');
-
-// Human-readable narrative
 agent.getNarrative();
 // [
 //   "[Seed] Initialized agent state",
 //   "[CallLLM] claude-sonnet-4 (127in / 45out)",
 //   "[ExecuteToolCalls] lookup_order({orderId: 'ORD-1003'})",
-//   "  Tool results: {status: 'denied', amount: 5000}",
-//   "[CallLLM] claude-sonnet-4 (312in / 89out)",
 //   "[Finalize] Your order was denied..."
 // ]
-
-// Structured entries for programmatic access
-agent.getNarrativeEntries();
-// Each entry: { type, text, key, rawValue, stageId, subflowId }
 ```
 
-### Grounding Analysis
+### Human-in-the-Loop
 
-Compare what tools returned vs what the LLM said. Hallucination detection without a separate eval pipeline.
-
-```typescript
-import { ExplainRecorder } from 'agentfootprint/explain';
-
-const explain = new ExplainRecorder();
-const agent = Agent.create({ provider }).tool(orderTool).recorder(explain).build();
-await agent.run('Check order status');
-
-const report = explain.explain();
-report.sources;   // what tools returned (ground truth)
-report.claims;    // what the LLM said (to verify)
-report.decisions; // what tool calls the LLM made
-```
-
----
-
-## Dynamic ReAct
-
-All three slots (system prompt, tools, messages) re-evaluate each iteration. Instructions re-evaluate against updated decision scope. Progressive tool authorization:
-
-```
-Turn 1: basic tools → LLM calls verify_identity → decision.verified = true
-Turn 2: InstructionsToLLM re-evaluates → admin tools unlocked → refund tools available
-Turn 3: LLM sees admin tools → can process refund
-```
-
-The LLM's capabilities change based on what happened — not what you hardcoded.
-
----
-
-## Pausable — Human-in-the-Loop
-
-Long-running agent pauses, serializes state to JSON, resumes hours later on a different server.
+Agent pauses, serializes state to JSON, resumes hours later on a different server.
 
 ```typescript
 import { Agent, askHuman } from 'agentfootprint';
 
 const agent = Agent.create({ provider })
-  .tool(askHuman())   // special tool that pauses execution
+  .tool(askHuman())
   .build();
 
 const result = await agent.run('Process my refund');
 if (result.paused) {
-  // Store checkpoint in Redis/Postgres/anywhere
-  const checkpoint = result.pauseData;
-  // ... hours later, different server ...
-  const final = await agent.resume(humanResponse);
+  const checkpoint = result.pauseData;   // store in Redis/Postgres/anywhere
+  const final = await agent.resume(humanResponse);  // hours later, different server
 }
 ```
 
----
+### Streaming Events
 
-## Streaming Lifecycle Events
-
-9-event discriminated union. Build any UX — CLI, web, mobile. Tool lifecycle fires even without streaming mode.
+9-event discriminated union. Build any UX — CLI, web, mobile.
 
 ```typescript
 await agent.run('Check order', {
@@ -205,7 +226,6 @@ await agent.run('Check order', {
       case 'token':      process.stdout.write(event.content); break;
       case 'tool_start': console.log(`Running ${event.toolName}...`); break;
       case 'tool_end':   console.log(`Done (${event.latencyMs}ms)`); break;
-      case 'llm_end':    console.log(`[${event.model}, ${event.latencyMs}ms]`); break;
     }
   },
 });
@@ -213,47 +233,36 @@ await agent.run('Check order', {
 
 Events: `turn_start` · `llm_start` · `thinking` · `token` · `llm_end` · `tool_start` · `tool_end` · `turn_end` · `error`
 
-SSE for web backends: `res.write(SSEFormatter.format(event))`
-
----
-
-## Recorders — Passive Observation
+### Observability
 
-Observe without shaping behavior. Collect during traversal. One call for everything:
+One call for everything. Collect during traversal, never post-process.
 
 ```typescript
 import { agentObservability } from 'agentfootprint/observe';
 
 const obs = agentObservability();
-const agent = Agent.create({ provider }).tool(searchTool).recorder(obs).build();
+agent.recorder(obs).build();
 await agent.run('Hello');
 
 obs.tokens();   // metrics: { totalCalls, totalInputTokens, totalOutputTokens, calls[] }
 obs.tools();    // metrics: { totalCalls, byTool: { search: { calls, errors, latency } } }
 obs.cost();     // metrics: USD amount
-obs.explain();  // evaluation: { iterations, sources, claims, decisions, context, summary }
+obs.explain();  // evaluation: { iterations, sources, claims, decisions, context }
 ```
 
-### 5 Categories
-
 | Category | Recorders | Audience |
 |----------|-----------|----------|
 | **Evaluation** | `ExplainRecorder` | LLM evaluator — faithfulness, hallucination, grounding |
 | **Metrics** | `TokenRecorder`, `CostRecorder`, `ToolUsageRecorder`, `TurnRecorder` | Ops dashboard, billing |
 | **Safety** | `GuardrailRecorder`, `PermissionRecorder`, `QualityRecorder` | Security, compliance |
 | **Export** | `OTelRecorder` | Datadog, Grafana, any OTel backend |
-| **Composition** | `CompositeRecorder`, `agentObservability()` | Bundle recorders |
-
-`obs.explain()` is the differentiator — per-iteration evaluation units with connected context. See [`recorders/README.md`](src/recorders/README.md).
-
----
 
-## Tool Gating — Defense-in-Depth
+### Tool Gating — Defense-in-Depth
 
-The LLM never sees tools it can't use. Can't hallucinate a tool it never saw.
+The LLM never sees tools it can't use. Two layers: resolve-time filtering + execute-time rejection.
 
 ```typescript
-import { gatedTools, PermissionPolicy } from 'agentfootprint';
+import { gatedTools, PermissionPolicy } from 'agentfootprint/security';
 
 const policy = PermissionPolicy.fromRoles({
   user: ['search', 'calc'],
@@ -264,88 +273,37 @@ const agent = Agent.create({ provider })
   .toolProvider(gatedTools(allTools, policy.checker()))
   .build();
 
-// Upgrade mid-conversation
-policy.setRole('admin');
+policy.setRole('admin');  // upgrade mid-conversation
 ```
 
-Two layers: resolve-time filtering (hidden from LLM) + execute-time rejection (hallucinated names caught).
-
----
-
-## Safety Instructions
-
-```typescript
-defineInstruction({
-  id: 'compliance',
-  safety: true,   // fail-closed: fires even when predicate throws
-  prompt: 'GDPR compliance required.',
-});
-```
-
-Safety instructions: unsuppressable, fail-closed, sorted last (highest LLM attention position).
-
----
-
-## Orchestration
+### Resilience
 
 ```typescript
-import { withRetry, withFallback, withCircuitBreaker, resilientProvider } from 'agentfootprint';
+import { withRetry, withFallback, resilientProvider } from 'agentfootprint/resilience';
 
 const reliable = withRetry(agent, { maxRetries: 3 });
 const resilient = withFallback(primaryAgent, cheapAgent);
-const guarded = withCircuitBreaker(agent, { failureThreshold: 5 });
-
-// Cross-family provider failover: Claude → GPT-4o → local Ollama
 const provider = resilientProvider([anthropicAdapter, openaiAdapter, ollamaAdapter]);
 ```
 
 ---
 
-## 26 Samples
+## Samples
 
 `test/samples/` — runnable with `vitest`:
 
 | # | Sample | What it demonstrates |
 |---|--------|---------------------|
 | 01-16 | Core patterns | LLMCall, Agent, RAG, FlowChart, Swarm, recorders, tools, security, errors, multi-modal |
-| 17 | **Instructions** | defineInstruction, decide(), conditional activation, Decision Scope |
+| 17 | **Conditional Behavior** | defineInstruction, decide(), conditional activation, Decision Scope |
 | 18 | **Streaming Events** | AgentStreamEvent lifecycle, tool events, SSE |
-| 19 | **Security** | gatedTools, PermissionPolicy, role-based tool access |
-| 20 | **Grounding** | ExplainRecorder — sources, claims, decisions |
+| 19 | **Tool Gating** | gatedTools, PermissionPolicy, role-based tool access |
 | 21 | **SSE Server** | Express SSE endpoint with SSEFormatter |
 | 22 | **Resilience** | withRetry, withFallback, provider failover |
 | 23 | **Memory Stores** | redisStore, postgresStore, dynamoStore adapters |
 | 24 | **Structured Output** | outputSchema, Zod auto-convert, zodToJsonSchema |
-| 25 | **OTel Recorder** | OpenTelemetry spans with mock tracer |
-| 26 | **Explain Recorder** | ExplainRecorder: sources, claims, decisions during traversal |
-
----
-
-## Architecture — 5 Layers
-
-```
-Layer 1: BUILD          → concepts/     Single LLM (LLMCall, Agent, RAG)
-                                         Multi-Agent (FlowChart, Parallel, Swarm)
-                          tools/         defineTool, ToolRegistry, askHuman
-
-Layer 2: COMPOSE        → lib/loop/     buildAgentLoop — the ReAct engine
-                          lib/slots/    SystemPrompt, Messages, Tools subflows
-
-Layer 3: EVALUATE       → recorders/    ExplainRecorder — per-iteration evaluation
-                          explain       obs.explain() → { iterations, sources, claims, context }
-
-Layer 4: MONITOR        → recorders/    TokenRecorder, CostRecorder, ToolUsageRecorder
-                          streaming/    AgentStreamEvent, SSEFormatter
-                          narrative     Human-readable execution story (footprintjs)
-
-Layer 5: INFRASTRUCTURE → adapters/     Anthropic, OpenAI, Bedrock, Mock, MCP, A2A
-                          providers/    Prompt, Message, Tool strategies
-                          memory/       Conversation stores (Redis, Postgres, DynamoDB)
-```
-
-Each folder has a README explaining what, when, and how. Start at Layer 1, add layers as you need them.
-
-Built on [footprintjs](https://github.com/footprintjs/footPrint) — the flowchart pattern for backend code. One DFS traversal, three observer systems (scope/flow/agent), connected data out.
+| 25 | **OTel** | OpenTelemetry spans with mock tracer |
+| 26 | **Explain Recorder** | ExplainRecorder: sources, claims, decisions, per-iteration eval |
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",