footprintjs | Blog

Backward Causal Chain: Error Stack Traces for Data Quality

Mon, 13 Apr 2026 00:00:00 GMT

April 2026 · Sanjay Krishna Anbalagan

The problem: “Why is the answer bad?”

Your loan pipeline runs 5 stages. The final decision is rejected, but the quality score is 0.2 — something went wrong. Which stage caused it?

You could read the narrative top to bottom. But in an agent loop with 15 iterations, 3 tool calls each, that’s 45 stages of output. You need a stack trace for quality — not for crashes, but for data quality degradation.

Quality Trace (score: 0.20 at reject#4):
  at reject#4                  score=0.20  — rejection decision
  at eval-risk#2               score=0.40 (via riskTier)  — high risk assigned
  at seed#0                    score=1.00 (via creditScore)  — input data

Root cause: quality dropped at reject#4 (0.40 → 0.20, Δ0.20)

This is causalChain() — backward program slicing on the commit log.

The algorithm

Every stage in footprintjs writes through a transactional buffer. The commit log records what each stage wrote. Every recorder tracks what each stage read. Together, they form an implicit dependency graph:

Seed wrote creditScore, dti
  ↓ (EvalRisk reads creditScore, dti)
EvalRisk wrote riskTier
  ↓ (Route reads riskTier)
Route → chose reject branch
  ↓ (Reject reads riskTier)
Reject wrote decision

causalChain() walks this graph backward from any starting point. The algorithm is BFS backward thin-slicing — a simplified form of program slicing (Weiser 1984, Sridharan et al. 2007):

Start at the target step (e.g., reject#4)
Get what it read via the getKeysRead callback
For each key read, find who last wrote it (findLastWriter)
Create a parent node, enqueue it
Repeat until no more dependencies

The output is a DAG (not a linked list). If a stage reads creditScore AND dti from different writers, it has two parents:

       Seed
      /    \
  EvalRisk  (also writes dti)
      \
     Route
      |
    Reject

Staged optimization: the query optimizer trick

For small pipelines (≤ 256 commits), findLastWriter scans the log backward — O(N) per lookup, zero setup cost. Fast enough.

For agent loops with 500+ iterations, that’s expensive. So causalChain() automatically switches to a reverse index: a prebuilt Map<key, sortedWriterIndices[]> that enables O(log N) binary search per lookup.

The consumer never sees this. It’s chosen internally — like a database query optimizer selecting between sequential scan and index scan based on table size.

Pipeline Size	Strategy	Per-Lookup Cost
≤ 256 commits	Linear scan	O(N) — zero setup
> 256 commits	Reverse index + binary search	O(log N) — O(N×U) setup amortized

Built on recorder operations

This is where the recorder operations become the foundation:

import { causalChain, flattenCausalDAG, formatCausalChain } from 'footprintjs/trace';
import { QualityRecorder, qualityTrace, formatQualityTrace } from 'footprintjs/trace';

// 1. Collect quality scores during traversal (Translate pattern)
const quality = new QualityRecorder((id, ctx) => {
  if (ctx.keysWritten.includes('decision')) return { score: 0.2, factors: ['rejection'] };
  if (ctx.keysWritten.includes('riskTier')) return { score: 0.4, factors: ['high risk'] };
  return { score: 1.0 };
});

executor.attachRecorder(quality);
await executor.run();

// 2. Find the lowest-scoring step (Aggregate pattern)
const lowest = quality.getLowest();

// 3. Backtrack through the causal chain
const trace = qualityTrace(
  executor.getSnapshot().commitLog,
  quality,
  lowest.runtimeStageId,
);

console.log(formatQualityTrace(trace));

The QualityRecorder uses Translate (per-step scores), Accumulate (progressive quality up to slider), and Aggregate (overall score). The causalChain() utility reads from the commit log — which was built during the same traversal, zero post-processing.

Everything is collected during the single DFS pass. The backtracking is a post-execution query over data that was already captured.

The ROI

Time saved

Scenario	Without causal chain	With causal chain
Debug low-quality agent response	30 min reading logs	10 seconds reading trace
Root cause analysis	Senior eng required	Any engineer (or the LLM itself)
SLA investigation	”We’ll look into it”	Immediate root cause ID

At 5 quality incidents per week, 20 minutes saved each: ~8.7 hours/month of senior eng time returned.

Cost saved

The causal chain is LLM context — instead of the LLM reasoning across scattered data, it reads the pre-computed dependency graph:

Approach	Tokens	Model Required	Cost/1M
LLM reasons across logs	~2,500	Reasoning model	$15.00
LLM reads causal chain	~200	Any model	$0.25

At 10,000 queries/day: $2,190/day savings.

Quality improvement

When you can see exactly where quality dropped, you fix the right thing:

System prompt too vague? → Fix the prompt, not the model
Tool returned bad data? → Fix the tool, not the agent loop
Context window too large? → Trim the right messages

Without the causal chain, teams throw money at bigger models hoping it fixes quality. With it, they make targeted fixes.

The dependency DAG

memory/backtrack.ts    → causalChain() — pure algorithm, leaf node
                         depends on: memory/types, memory/commitLogUtils

recorder/QualityRecorder.ts → scoring during traversal
                              depends on: recorder/KeyedRecorder

recorder/qualityTrace.ts → decorates causalChain with quality scores
                           depends on: memory/backtrack + recorder/QualityRecorder

Clean lib-of-libs layering. The backtracking algorithm knows nothing about quality. The quality layer knows nothing about how the DAG is built. They compose.

Try it

npx tsx examples/post-execution/causal-chain/05-diamond.ts
npx tsx examples/post-execution/quality-trace/02-root-cause.ts

Or explore in the interactive playground.

Three Operations on Auto-Collected Data: The Recorder Pattern That Saves You $15/1M Tokens

Mon, 13 Apr 2026 00:00:00 GMT

April 2026 · Sanjay Krishna Anbalagan

The $15 question

A user asks: “Why was my loan rejected?”

Your agent has the data. Credit score, DTI ratio, employment history — all computed across 8 pipeline stages. The LLM needs to answer.

Without recorder operations: The LLM retrieves scattered logs. Makes 4 tool calls. Spends 4 reasoning steps connecting disconnected data points. Total: ~2,500 tokens, requires an expensive reasoning model ($15/1M tokens).

With recorder operations: The recorder already has the causal chain. One read. The LLM sees the connected trace. Total: ~200 tokens, any lightweight model works ($0.25/1M tokens).

That’s 60x cost reduction per question. At 10,000 questions/day, that’s $2,190/day in savings.

The three operations

Every recorder in footprintjs collects data during the single DFS traversal — no post-processing, never stale. The consumer chooses how to read that data at query time:

1. Translate — “What happened at this step?”

Per-step raw value. O(1) lookup by runtimeStageId.

import { QualityRecorder } from 'footprintjs/trace';

// What was the quality score at step call-llm#5?
const entry = quality.getByKey('call-llm#5');
// → { score: 0.3, factors: ['response hallucinated'], keysRead: ['systemPrompt'] }

Use case: Time-travel debugger. Click a stage in the UI → see its data. The explainable-ui slider calls getByKey() at each position.

ROI: Developer debugging time drops from “read 500 log lines” to “click the stage.” At $150/hr senior eng rate, even 10 minutes saved per debug session × 5 sessions/day = $125/day.

2. Accumulate — “What happened up to this point?”

Progressive running total filtered by a set of visible keys. For time-travel sliders where you scrub forward/backward.

// Quality score up to the slider position
const visibleKeys = new Set(['seed#0', 'classify#1', 'call-llm#2']);
const scoreUpTo = quality.accumulate(
  (sum, entry) => sum + entry.score,
  0,
  visibleKeys,
);
// → 2.1 (sum of scores for first 3 steps)

Use case: Progressive metrics in the UI. As the slider moves, the dashboard updates: “Duration so far: 120ms, Reads: 5, Writes: 3, Quality: 0.7.”

ROI: Users understand performance characteristics without reading code. Support tickets drop because the UI shows what happened instead of requiring a human to explain it.

3. Aggregate — “What’s the grand total?”

Reduce all entries to a single value. For dashboards, SLA checks, billing.

// Overall pipeline quality
const overallScore = quality.aggregate(
  (sum, entry) => sum + entry.score,
  0,
) / quality.size;
// → 0.65

// Total cost across all LLM calls
const totalCost = costRecorder.aggregate(
  (sum, entry) => sum + entry.cost,
  0,
);
// → $0.0042

Use case: SLA monitoring. “Average quality this hour: 0.82. Cost per request: $0.004.” These numbers go to Grafana/Datadog dashboards.

ROI: You catch quality degradation before users report it. One prevented outage saves more than a year of infrastructure cost.

The foundation for everything

These three operations aren’t just a nice API. They’re the foundation for the backward causal chain — footprintjs’s answer to “why did quality drop?”

When qualityTrace() backtracks from a low-scoring step:

It uses Translate to read the quality at each step
It uses Accumulate to compute progressive quality up to the drop point
It uses Aggregate to compute the overall pipeline score

The KeyedRecorder<T> base class provides all three operations. Every built-in recorder (MetricRecorder, QualityRecorder, TokenRecorder, CostRecorder) inherits them. Your custom recorders get them for free.

// All three operations on auto-collected data:
metric.getByKey('call-llm#5');                           // Translate
metric.accumulate((sum, m) => sum + m.duration, 0, keys); // Accumulate
metric.aggregate((sum, m) => sum + m.duration, 0);         // Aggregate

One interface. Three operations. Collected during traversal. Never stale.

In the next post, we’ll show how these operations power the backward causal chain — an algorithm that answers “why did quality drop at step 5?” by walking the dependency graph backward.

Pause/Resume: Human-in-the-Loop for Backend Pipelines

Fri, 03 Apr 2026 00:00:00 GMT

April 2026 · Sanjay Krishna Anbalagan

The problem

Your pipeline needs a human decision in the middle.

A refund over $500 requires manager approval. An AI-generated report needs editorial review before publishing. A deployment pipeline pauses for a security sign-off.

Traditional approaches:

Approach	Problem
Polling loop	Wastes compute, ties up a process
WebSocket + in-memory state	Loses state on server restart
Split into two pipelines	Business logic scattered across endpoints
Background job + callback	Complex coordination, race conditions

What if the pipeline could just… pause? Save its state. Shut down. And pick up exactly where it left off — hours later, on a different server — when the human responds?

How it works

1. Define a pausable stage

A pausable stage has two phases: execute (first run) and resume (when the human responds).

import { flowChart, FlowChartExecutor } from 'footprintjs';
import type { PausableHandler } from 'footprintjs';

interface RefundState {
  orderId: string;
  amount: number;
  riskLevel?: string;
  approved?: boolean;
  approver?: string;
}

const approvalGate: PausableHandler<RefundState> = {
  execute: async (scope) => {
    // Classify risk
    scope.riskLevel = scope.amount > 500 ? 'high' : 'low';

    // Return data = pause. Return nothing = continue.
    return {
      question: `Approve $${scope.amount} refund?`,
      riskLevel: scope.riskLevel,
    };
  },
  resume: async (scope, input) => {
    scope.approved = input.approved;
    scope.approver = input.approver;
  },
};

2. Build the pipeline

const chart = flowChart<RefundState>(
  'ReceiveRequest', async (scope) => {
    scope.orderId = 'ORD-2024-7891';
    scope.amount = 299;
  }, 'receive')
  .addPausableFunction('ManagerApproval', approvalGate, 'approve',
    'Pause for manager review')
  .addFunction('ProcessRefund', async (scope) => {
    if (scope.approved) {
      console.log(`Refund approved by ${scope.approver}`);
    }
  }, 'process')
  .build();

3. Run, pause, checkpoint

const executor = new FlowChartExecutor(chart);
await executor.run();

if (executor.isPaused()) {
  const checkpoint = executor.getCheckpoint();
  // checkpoint is JSON-safe — store anywhere
  await redis.set(`refund:${orderId}`, JSON.stringify(checkpoint));
}

The checkpoint contains:

sharedState — full scope at the pause point
pausedStageId — which stage paused
pauseData — the data you returned from execute
executionTree — the traversal path for visualization

4. Resume (hours later, any server)

const checkpoint = JSON.parse(await redis.get(`refund:${orderId}`));

const executor = new FlowChartExecutor(chart); // same chart, fresh executor
await executor.resume(checkpoint, {
  approved: true,
  approver: 'Manager Kim',
});
// Pipeline continues: ProcessRefund → NotifyCustomer → done

What makes this different

No timeouts. The pipeline doesn’t sit in memory waiting. It checkpoints and exits. The process can shut down.

No WebSockets. The checkpoint is a plain JSON object. Store it in Redis, Postgres, S3, localStorage — anywhere. Resume from any server, any process.

Continuous execution tree. After resume, getSnapshot() returns the full traversal path — pre-pause stages + resume + continuation. The narrative accumulates. Metrics accumulate. No gaps.

Conditional pause. Return data to pause, return nothing to continue. One handler handles both paths:

execute: async (scope) => {
  if (scope.amount > 500) {
    return { reason: 'High-value — needs approval' }; // pauses
  }
  // under $500 — auto-approved, no pause
}

Multi-pause. Chain multiple pausable stages. Each resume continues to the next pause point or to completion:

receive → approve(pause) → resume → review(pause) → resume → process → done

Try it live

Open the Pause/Resume sample in the playground. Click Run — the pipeline pauses at ManagerApproval. Edit the resume JSON and click Resume to continue.

The API surface

Consumers touch exactly 4 things:

What	Purpose
`PausableHandler<TScope, TInput>`	Type for `{ execute, resume }`
`.addPausableFunction(name, handler, id)`	Builder method
`executor.isPaused()` / `executor.getCheckpoint()`	Check pause state
`executor.resume(checkpoint, input)`	Continue execution

Everything else is internal — PauseSignal, isPauseResult, checkpoint validation, execution tree grafting — the consumer never sees it.

What’s next

This is the foundation for ask_human in agentfootprint — a tool that pauses an AI agent loop, sends a question to the frontend, and resumes with the human’s answer. The agent’s full reasoning chain (narrative, decisions, tool calls) is preserved across the pause.

Pause/Resume ships in footprintjs v4.1.0.

Automated Decision Explainability: How Causal Traces Solve GDPR Article 22 and Audit Requirements

Sat, 28 Mar 2026 00:00:00 GMT

April 2026 · Sanjay Krishna Anbalagan

The regulatory reality

If your software makes automated decisions about people — loan approvals, insurance claims, hiring screens, fraud flags — regulators increasingly require you to explain why.

GDPR Article 22 gives EU citizens the right to not be subject to decisions based solely on automated processing, and the right to obtain “meaningful information about the logic involved.” CCPA requires disclosure of the “logic involved in such decision-making.” The EU AI Act mandates transparency and explainability for high-risk AI systems. SOX requires auditability of financial decision processes. ECOA/FCRA in the US require specific adverse action notices explaining credit decisions.

The common thread: you must be able to explain, after the fact, exactly why your system made a specific decision for a specific person.

Most teams solve this with one of two approaches, both flawed:

Approach 1: Post-hoc logging. Scatter console.log or structured log statements throughout the code. After a decision, reconstruct the reasoning from log entries. Problem: logs are incomplete, disconnected, and require manual interpretation. Auditors can’t verify that the logs faithfully represent the actual execution path.

Approach 2: LLM explanation. Feed the code and context to an LLM and ask it to explain the decision. Problem: the LLM hallucinates causal connections. It generates plausible-sounding explanations that may not reflect what actually happened. An auditor can’t trust it.

Causal traces: the structural solution

FootPrintJS takes a different approach. Your business logic is structured as a flowchart — a graph of typed functions with transactional state. The runtime automatically captures a causal trace of every read, write, and decision during execution.

This isn’t logging you add manually. It’s a structural property of the execution model. If the code reads a variable, the trace records it. If the code writes a variable, the trace records it. If the code makes a branching decision, the trace records the operator, the threshold, the actual value, and whether it passed or failed.

import { flowChart, decide, narrative } from 'footprintjs';

interface UnderwritingState {
  applicantId: string;
  creditScore: number;
  dtiRatio: number;
  employmentMonths: number;
  riskTier: string;
  riskFactors: string[];
  decision: string;
  adverseReasons: string[];
}

const underwriting = flowChart<UnderwritingState>('ReceiveApplication', async (scope) => {
    scope.applicantId = 'APP-2026-1847';
    scope.creditScore = 580;
    scope.dtiRatio = 0.6;
    scope.employmentMonths = 12;
  }, 'receive')
  .addFunction('AssessCredit', async (scope) => {
    scope.riskFactors = [];
    if (scope.creditScore < 620) scope.riskFactors.push('Below-average credit score');
    if (scope.dtiRatio > 0.43) scope.riskFactors.push('DTI exceeds 43% threshold');
    if (scope.employmentMonths < 24) scope.riskFactors.push('Employment tenure under 2 years');
    scope.riskTier = scope.riskFactors.length >= 2 ? 'high' : 'standard';
  }, 'assess')
  .addDeciderFunction('Route', (scope) => {
    return decide(scope, [
      { when: { riskTier: { eq: 'high' } }, then: 'reject', label: 'High risk applicant' },
    ], 'approve');
  }, 'route', 'Route based on risk assessment')
    .addFunctionBranch('reject', 'GenerateAdverseAction', async (scope) => {
      scope.decision = 'REJECTED';
      scope.adverseReasons = scope.riskFactors;
    })
    .addFunctionBranch('approve', 'Approve', async (scope) => {
      scope.decision = 'APPROVED';
    })
    .setDefault('approve')
    .end()
  .build();

const result = await underwriting.recorder(narrative()).run();

The runtime generates this trace automatically:

Stage 1: The process began with ReceiveApplication.
  Step 1: Write applicantId = "APP-2026-1847"
  Step 2: Write creditScore = 580
  Step 3: Write dtiRatio = 0.6
  Step 4: Write employmentMonths = 12
Stage 2: Next, it moved on to AssessCredit.
  Step 1: Write riskFactors = (0 items)
  Step 2: Read creditScore = 580
  Step 3: Write riskFactors = (1 items)
  Step 4: Read dtiRatio = 0.6
  Step 5: Write riskFactors = (2 items)
  Step 6: Read employmentMonths = 12
  Step 7: Write riskFactors = (3 items)
  Step 8: Read riskFactors = (3 items)
  Step 9: Write riskTier = "high"
Stage 3: Next step: Route based on risk assessment.
  Step 1: Read riskTier = "high"
[Condition]: It evaluated "High risk applicant": riskTier "high" eq "high" ✓, and chose GenerateAdverseAction.
Stage 4: Next, it moved on to GenerateAdverseAction.
  Step 1: Write decision = "REJECTED"
  Step 2: Read riskFactors = (3 items)
  Step 3: Write adverseReasons = (3 items)

What auditors see

An auditor reviewing this trace can verify:

Data provenance. What data was used? The trace shows exactly which fields were read at each stage. creditScore = 580 was read at Stage 2, Step 2. Not inferred, not logged — captured by the runtime.
Decision logic. Why was this branch chosen? The [Condition] entry shows the operator (eq), the actual value ("high"), the expected value ("high"), and the result (✓). The auditor can verify the rule without reading source code.
Causal chain. The auditor backtracks: decision = "REJECTED" ← riskTier = "high" ← riskFactors.length >= 2 ← creditScore < 620 AND dtiRatio > 0.43 AND employmentMonths < 24. Every link in the chain is in the trace.
Completeness. Every read and write is captured. There are no hidden side effects, no unlogged decisions. The trace is a complete record of the execution.

Decision evidence with `decide()`

The decide() function captures structured evidence for every rule evaluation:

const result = decide(scope, [
  { when: { creditScore: { gte: 700 }, dtiRatio: { lte: 0.35 } }, then: 'premium', label: 'Prime borrower' },
  { when: { creditScore: { gte: 620 } }, then: 'standard', label: 'Standard borrower' },
], 'subprime');

The evidence object includes:

{
  "chosenBranch": "subprime",
  "chosenLabel": "Default",
  "rules": [
    {
      "label": "Prime borrower",
      "passed": false,
      "conditions": [
        { "field": "creditScore", "operator": "gte", "expected": 700, "actual": 580, "passed": false },
        { "field": "dtiRatio", "operator": "lte", "expected": 0.35, "actual": 0.6, "passed": false }
      ]
    },
    {
      "label": "Standard borrower",
      "passed": false,
      "conditions": [
        { "field": "creditScore", "operator": "gte", "expected": 620, "actual": 580, "passed": false }
      ]
    }
  ]
}

Every rule that was evaluated, whether it passed or failed, with the exact values compared. This is the structured evidence an ECOA adverse action notice needs.

Compliance properties

FootPrintJS’s execution model provides several properties that compliance teams care about:

Deterministic replay. Given the same initial state, the flowchart produces the same trace. You can re-run a historical decision and verify the trace matches.

Transactional state. State changes are atomic — committed per stage with copy-on-write semantics. There are no partial updates, no race conditions, no state corruption. Each stage sees a consistent snapshot.

Tamper-evident. The trace is generated by the runtime, not by the application code. Application code cannot modify the trace without changing the execution model itself. The trace is a faithful record of what the runtime observed.

PII redaction. Built-in RedactionPolicy for per-key or declarative redaction with audit trail. Redacted fields appear in the trace as [REDACTED] while maintaining the causal structure.

const result = await chart
  .recorder(narrative({ redactionPolicy: { keys: ['ssn', 'dateOfBirth'] } }))
  .run();
// Trace shows: Write ssn = [REDACTED], Read dateOfBirth = [REDACTED]
// Causal chain is preserved. PII is not exposed.

Time-travel debugging. Snapshots capture the full state at each stage boundary. Compliance teams can inspect the exact state the system saw when it made a decision — not the state 5 minutes later after other processes modified it.

Real-world application

Here’s how teams use this in practice:

Loan underwriting. The flowchart evaluates credit, DTI, employment, collateral. The trace generates ECOA-compliant adverse action reasons automatically. When a borrower appeals, the operations team pulls the trace — not a log file, not an LLM explanation — and sees exactly what happened.

Insurance claims. The flowchart triages claims by severity, checks policy coverage, applies deductibles. The trace documents every coverage check, every exclusion evaluation. When a regulator audits, the trace is the evidence.

Fraud detection. The flowchart evaluates risk signals: IP geolocation, velocity checks, device fingerprint. The trace documents which signals triggered the flag. When a legitimate transaction is blocked, support can explain exactly which rule fired and why.

Getting started

npm install footprintjs

import { flowChart, decide, narrative } from 'footprintjs';

// Define your decision logic as a flowchart
const chart = flowChart<YourState>('FirstStage', handler, 'id')
  // ... add stages, decisions, branches
  .build();

// Run with narrative recording
const result = await chart.recorder(narrative()).run();

// result.narrative — human-readable causal trace
// result.state — final state with all decisions

The trace is generated automatically. No logging code to write. No post-hoc reconstruction. No LLM hallucination.

Interactive Playground — try the loan underwriting demo
Documentation — full API reference
GitHub — MIT licensed, zero dependencies, npm provenance

Auto-Generate MCP Tools from Your Backend Code in One Line

Wed, 25 Mar 2026 00:00:00 GMT

April 2026 · Sanjay Krishna Anbalagan

The tool description problem

Every MCP tool needs three things: a name, a description, and an input schema. If you’re building tools by hand, you’re writing and maintaining all three separately from the code that actually runs.

// You write this by hand...
const tool = {
  name: 'assess_credit_risk',
  description: 'Evaluates credit risk by checking credit score, DTI ratio, and employment status. Returns risk tier and decision.',
  inputSchema: {
    type: 'object',
    properties: {
      creditScore: { type: 'number' },
      dtiRatio: { type: 'number' },
      employmentYears: { type: 'number' },
    },
    required: ['creditScore', 'dtiRatio', 'employmentYears'],
  },
};

// ...and separately maintain the code that does the work
function assessCreditRisk(input) {
  // 200 lines of business logic
}

The description drifts from the code. You add a new stage but forget to update the tool description. You rename a field but the schema still says the old name. The LLM gets confused because the tool it’s calling doesn’t match what it was told.

FootPrintJS solves this with self-describing graphs. The flowchart is the tool. The name, description, and schema are generated from the graph structure — always in sync with the code that runs.

One line: `.toMCPTool()`

import { flowChart, decide, narrative } from 'footprintjs';

interface CreditState {
  creditScore: number;
  dtiRatio: number;
  employmentYears: number;
  riskTier: string;
  decision: string;
  reasons: string[];
}

const chart = flowChart<CreditState>('ReceiveApplication', async (scope) => {
    // Input is already on scope from the caller
  }, 'receive')
  .addFunction('CheckCredit', async (scope) => {
    scope.riskTier = scope.creditScore >= 700 ? 'low' :
                     scope.creditScore >= 620 ? 'medium' : 'high';
  }, 'check-credit')
  .addFunction('CheckDTI', async (scope) => {
    if (scope.dtiRatio > 0.43) {
      scope.reasons = [...(scope.reasons || []), 'DTI exceeds 43%'];
    }
  }, 'check-dti')
  .addDeciderFunction('Route', (scope) => {
    return decide(scope, [
      { when: { riskTier: { eq: 'high' } }, then: 'reject', label: 'High risk' },
    ], 'approve');
  }, 'route', 'Route based on overall risk assessment')
    .addFunctionBranch('reject', 'Reject', async (scope) => {
      scope.decision = 'REJECTED';
    })
    .addFunctionBranch('approve', 'Approve', async (scope) => {
      scope.decision = 'APPROVED';
    })
    .setDefault('approve')
    .end()
  .build();

// One line — tool descriptor generated from the graph
const tool = chart.toMCPTool();

tool now contains:

{
  "name": "receivecreditapplication",
  "description": "1. ReceiveApplication\n2. CheckCredit\n3. CheckDTI\n4. Route based on overall risk assessment\n   → Reject\n   → Approve",
  "inputSchema": {
    "type": "object",
    "properties": {
      "creditScore": { "type": "number" },
      "dtiRatio": { "type": "number" },
      "employmentYears": { "type": "number" }
    }
  }
}

The description is auto-generated from the graph stages. The input schema comes from the contract (or can be inferred). If you add a new stage to the flowchart, the tool description updates automatically.

Register with any MCP server

The output of .toMCPTool() is a standard MCP tool descriptor. Register it with any MCP server implementation:

// With the Anthropic SDK directly
const anthropicTool = {
  name: tool.name,
  description: tool.description,
  input_schema: tool.inputSchema,
};

// Pass to Claude
const response = await anthropic.messages.create({
  model: 'claude-sonnet-4-20250514',
  tools: [anthropicTool],
  messages: [{ role: 'user', content: 'Assess credit risk for score 580, DTI 0.6, 1yr employment' }],
});

When Claude calls the tool, execute the flowchart and return the result with the causal trace:

// Handle the tool call
const toolInput = response.content[0].input; // { creditScore: 580, dtiRatio: 0.6, employmentYears: 1 }

const result = await chart
  .initialState(toolInput)
  .recorder(narrative())
  .run();

// Return to Claude: the decision + why
const toolResult = {
  decision: result.state.decision,       // "REJECTED"
  reasons: result.state.reasons,          // ["DTI exceeds 43%"]
  trace: result.narrative.join('\n'),     // Full causal trace
};

Claude now has the structured trace. When the user asks “why was I rejected?”, Claude reads the trace and gives a precise, non-hallucinated explanation.

Also: `.toOpenAPI()`

Same graph, different output format. Generate an OpenAPI 3.1 spec for REST API documentation:

const spec = chart.toOpenAPI({
  title: 'Credit Risk Assessment',
  version: '1.0.0',
  description: 'Automated credit risk evaluation pipeline',
});

// spec is a full OpenAPI 3.1 document
// Import into Swagger UI, Postman, or any API documentation tool

One flowchart, two output formats — MCP for AI agents, OpenAPI for humans and API consumers.

With agentfootprint: full agent integration

If you’re using agentfootprint (the agent framework), the integration is even tighter:

import { Agent, createProvider, anthropic, defineTool } from 'agentfootprint';

// Turn the flowchart into an agent tool
const creditTool = defineTool({
  id: tool.name,
  description: tool.description,
  inputSchema: tool.inputSchema,
  handler: async (input) => {
    const result = await chart
      .initialState(input)
      .recorder(narrative())
      .run();
    return {
      content: JSON.stringify({
        decision: result.state.decision,
        trace: result.narrative,
      }),
    };
  },
});

// Build an agent that uses it
const agent = Agent.create({
  provider: createProvider(anthropic('claude-sonnet-4-20250514')),
})
  .system('You are a loan officer assistant. Use the credit assessment tool to evaluate applications and explain decisions clearly.')
  .tool(creditTool)
  .build();

const response = await agent.run(
  'Evaluate this application: credit score 580, DTI 60%, 1 year employment'
);
// Agent calls the tool, gets the trace, explains the decision

Why this matters

For AI engineers: Your tools stay in sync with your code. Add a stage, the tool description updates. Rename a field, the schema updates. No drift.

For compliance teams: The causal trace is auto-generated, not hand-written. It’s a faithful record of what the code actually did — auditable, reproducible, tamper-evident.

For product teams: LLMs give better explanations because they have structured traces instead of scattered logs. User trust increases because the explanations are accurate.

Try the live demo

We have a live demo where Claude calls a credit-decision flowchart as an MCP tool. Enter your API key, ask a question, and watch the tool call happen in real time:

Live MCP Demo — see .toMCPTool() in action

npm install footprintjs        # the engine
npm install agentfootprint     # the agent framework (optional)

Interactive Playground — 37+ samples
Documentation — full API reference
GitHub — MIT licensed, zero dependencies

Testing AI Agents for $0: The Adapter-Swap Pattern

Fri, 20 Mar 2026 00:00:00 GMT

April 2026 · Sanjay Krishna Anbalagan

The $47 test suite

We ran our agent test suite. Fifty-three tests. Each one called Claude with real prompts, real tools, real multi-turn conversations. Every test passed. The bill: $47.12.

The next day, two tests failed. Same code, same prompts. Different responses — because LLMs are non-deterministic. We re-ran. They passed. We re-ran again. One failed. Another $14.

This is the testing problem nobody talks about in the AI agent space: your tests are expensive, slow, flaky, and non-deterministic. Every run costs money. Every assertion is probabilistic. CI pipelines become unreliable. Developers stop writing tests because the feedback loop is broken.

We fixed this with a pattern we call adapter swapping.

The pattern: mock() → anthropic()

The idea is simple: your agent code doesn’t know (or care) which LLM provider is behind it. In tests, you use mock(). In production, you use anthropic() or openai(). The agent code is identical.

import { Agent, defineTool, mock } from 'agentfootprint';
import { createProvider, anthropic } from 'agentfootprint';

// The tool — same in tests and production
const calculator = defineTool({
  id: 'calculator',
  description: 'Evaluate a math expression',
  inputSchema: {
    type: 'object',
    properties: { expression: { type: 'string' } },
    required: ['expression'],
  },
  handler: async (input) => ({
    content: String(eval(input.expression)),
  }),
});

// ── Test code ────────────────────────────────────────
const testProvider = mock([
  {
    content: 'Let me calculate that.',
    toolCalls: [{
      id: 'tc1',
      name: 'calculator',
      arguments: { expression: '42 * 17' },
    }],
  },
  { content: 'The answer is 714.' },
]);

// ── Production code ──────────────────────────────────
const prodProvider = createProvider(anthropic('claude-sonnet-4-20250514'));

// ── Agent code — IDENTICAL in both cases ─────────────
function buildAgent(provider) {
  return Agent.create({ provider })
    .system('You are a helpful calculator assistant.')
    .tool(calculator)
    .maxIterations(5)
    .build();
}

// Test: $0, instant, deterministic
const testAgent = buildAgent(testProvider);
const result = await testAgent.run('What is 42 times 17?');
assert(result.content.includes('714'));

// Production: real LLM, real cost
const prodAgent = buildAgent(prodProvider);

The mock provider returns exactly the responses you specify. Tool calls happen deterministically. The agent’s ReAct loop executes the same way — calling tools, processing results, generating the next turn — but without any API calls.

What you can test for $0

This isn’t just “mock the HTTP call.” The mock adapter participates in the full agent lifecycle:

Tool call orchestration. The mock returns a tool call → the agent executes the real tool handler → the result goes back to the mock → the mock returns the next response. Your tool handlers run for real. Your error handling runs for real. Only the LLM is mocked.

const provider = mock([
  // Turn 1: LLM decides to search
  {
    content: 'Searching for information...',
    toolCalls: [{ id: 'tc1', name: 'search', arguments: { query: 'AI trends' } }],
  },
  // Turn 2: LLM processes search results and responds
  { content: 'Based on my research, here are the top AI trends...' },
]);

const agent = Agent.create({ provider })
  .tool(searchTool)  // Real tool — actually executes
  .build();

const result = await agent.run('What are the AI trends?');
// searchTool.handler() was called with { query: 'AI trends' }
// The full ReAct loop ran — mock → tool → mock → response

Multi-turn conversations. Each entry in the mock array is one LLM turn. The agent processes them in sequence, exactly like it would with a real provider.

Recorder verification. Attach TokenRecorder, CostRecorder, TurnRecorder to mock runs. Verify that your observability pipeline captures the right data.

const tokens = new TokenRecorder();
const turns = new TurnRecorder();

const agent = Agent.create({ provider: mock([...]) })
  .recorder(tokens)
  .recorder(turns)
  .build();

await agent.run('Hello');

assert(turns.getCompletedCount() === 2); // Two LLM turns
assert(tokens.getStats().totalCalls === 2);

FlowChart pipelines. Mock individual agents within a pipeline. Test the orchestration logic without any API calls.

const pipeline = FlowChart.create()
  .agent('research', 'Research phase', mockResearchAgent)
  .agent('write', 'Writing phase', mockWriterAgent)
  .build();

const result = await pipeline.run('Write about AI safety');
// Both agents ran with mocks — pipeline orchestration tested for $0

Error handling. Mock providers can simulate errors to test your resilience patterns:

import { withRetry, withFallback } from 'agentfootprint';

// Simulate API failure on first call, success on retry
const flakyProvider = mock([
  { error: { code: 'rate_limit', message: 'Too many requests' } },
  { content: 'Success on retry!' },
]);

const resilientAgent = withRetry(
  Agent.create({ provider: flakyProvider }).build(),
  { maxRetries: 3, backoffMs: 100 },
);

const result = await resilientAgent.run('Hello');
assert(result.content === 'Success on retry!');

The concept ladder makes this natural

agentfootprint has five concepts that compose together: LLMCall → Agent → RAG → FlowChart → Swarm. Each one accepts a provider. Every one works with mock().

Concept	What it adds	Testing pattern
LLMCall	Single invocation	Mock one response
Agent	Tool use loop	Mock response sequence with tool calls
RAG	Retrieval + generation	Mock retriever + LLM response
FlowChart	Sequential pipeline	Mock each agent in the pipeline
Swarm	Dynamic routing	Mock router decisions + specialist responses

You start simple (test an LLMCall), compose up (test an Agent with tools), and eventually test full Swarm orchestrations — all at $0.

When you still need real LLM tests

Mock tests verify your orchestration logic, tool integrations, and error handling. They don’t verify prompt quality or response appropriateness. For that, you still need real LLM calls — but far fewer.

Our recommended split:

90% mock tests — orchestration, tools, error handling, recorders, pipelines
10% real LLM tests — prompt quality, response format, edge cases

The mock tests run in CI on every commit (fast, free, deterministic). The real LLM tests run nightly or before release (slow, costly, but necessary).

Try it

npm install agentfootprint

import { Agent, mock, defineTool } from 'agentfootprint';

const agent = Agent.create({
  provider: mock([{ content: 'Hello! How can I help?' }]),
})
  .system('You are a helpful assistant.')
  .build();

const result = await agent.run('Hi there');
console.log(result.content); // "Hello! How can I help?"

Zero API calls. Zero cost. Deterministic. Your CI pipeline will thank you.

Agent Playground — 23 interactive samples
GitHub — agentfootprint — MIT licensed
GitHub — footprintjs — the engine underneath

Why We Built FootPrint: The Missing Pattern for Explainable Backend Code

Sun, 15 Mar 2026 00:00:00 GMT

April 2026 · Sanjay Krishna Anbalagan

The moment that started everything

A user asked: “Why was my loan rejected?”

Our LLM had all the context. It had the code, the logs, the application data. It generated a confident, detailed explanation — citing the user’s credit score, debt-to-income ratio, and employment history.

The explanation was wrong.

Not slightly wrong. Structurally wrong. The LLM had reconstructed a plausible-sounding narrative from scattered signals — a console.log here, a database write there — and hallucinated the causal chain that connected them. The user’s actual rejection reason was a completely different risk factor that the LLM never surfaced.

That’s when we realized: the problem isn’t the LLM. The problem is the code.

The structural problem

Traditional backend code scatters business logic across controllers, services, and middleware. When something happens — a loan gets rejected, a claim gets denied, an order gets flagged — the why is implicit. It lives in the execution path the code took, the variables it read, the branches it chose. But none of that is captured in a structured way.

So when an LLM needs to explain a decision, it does what any intelligent system would: it guesses. It reconstructs reasoning from whatever artifacts it can find — log lines, database states, API responses. And it hallucinates the connections between them.

	Traditional	What we needed
Decision reasoning	Implicit in code paths	Explicit causal trace
LLM explanation	Reconstructed from logs	Read directly from execution
State management	Global, scattered	Transactional, observable
Tool descriptions	Written by hand	Generated from the code

We didn’t need better prompts. We needed a different pattern.

The flowchart pattern

We looked at how humans explain decisions. When a loan officer explains a rejection, they walk through a flowchart: first we checked this, then we evaluated that, and based on this threshold, we made this decision. Every step is traceable.

What if backend code worked the same way?

That’s FootPrint. Your business logic is a graph of typed functions with transactional state. The runtime captures every read, write, and decision as a causal trace. When an LLM needs to explain what happened, it reads the trace — it doesn’t guess.

import { flowChart, decide, narrative } from 'footprintjs';

const chart = flowChart<State>('ReceiveApplication', async (scope) => {
    scope.creditScore = 580;
    scope.dti = 0.6;
  }, 'receive')
  .addFunction('EvaluateRisk', async (scope) => {
    scope.riskTier = scope.creditScore < 620 ? 'high' : 'low';
  }, 'evaluate')
  .addDeciderFunction('Route', (scope) => {
    return decide(scope, [
      { when: { riskTier: { eq: 'high' } }, then: 'reject', label: 'High risk' },
    ], 'approve');
  }, 'route', 'Route based on risk tier')
    .addFunctionBranch('reject', 'RejectApplication', async (scope) => {
      scope.decision = 'REJECTED';
    })
    .addFunctionBranch('approve', 'ApproveApplication', async (scope) => {
      scope.decision = 'APPROVED';
    })
    .setDefault('approve')
    .end()
  .build();

const result = await chart.recorder(narrative()).run();

The runtime auto-generates this trace:

Stage 1: The process began with ReceiveApplication.
  Step 1: Write creditScore = 580
  Step 2: Write dti = 0.6
Stage 2: Next, it moved on to EvaluateRisk.
  Step 1: Read creditScore = 580
  Step 2: Write riskTier = "high"
Stage 3: Next step: Route based on risk tier.
  Step 1: Read riskTier = "high"
[Condition]: It evaluated "High risk": riskTier "high" eq "high" ✓, and chose RejectApplication.
Stage 4: Next, it moved on to RejectApplication.
  Step 1: Write decision = "REJECTED"

The LLM backtracks: decision=REJECTED ← riskTier="high" ← creditScore=580. Every variable links to its cause. No hallucination.

The ecosystem

FootPrint isn’t one library — it’s an ecosystem of two packages that work together:

footprintjs is the engine. The flowchart pattern with typed state, causal traces, decision evidence, and self-describing APIs. Zero runtime dependencies. This is the foundation.

agentfootprint is the AI agent framework built on top. Five concepts — LLMCall, Agent, RAG, FlowChart, Swarm — that compose together. Adapter-swap testing (mock() in tests, anthropic() in production), agent-level tool gating, built-in cost and token tracking.

Together, they give you explainable backend logic + explainable AI agents. Same causal trace model all the way through.

What we got wrong (and fixed)

Building this taught us a few things the hard way:

We started with too many dependencies. The first version used lodash. Every enterprise conversation hit the same wall: “how many transitive deps?” By v4.0, we removed everything. dependencies: {} in package.json. That single change unlocked more adoption conversations than any feature we shipped.

We built docs before a playground. The docs are good — 14 pages, 108+ code examples. But the interactive playground with 37+ runnable samples and a live LLM demo converts 10x better. If you’re building a developer tool, build the playground first.

We underestimated how important decide() would be. We originally had decisions as plain if/else. But without structured evidence capture, the trace just said “chose branch A” with no why. Adding decide() with declarative rules — { when: { score: { gt: 700 } }, then: 'approved' } — made the traces actually useful for explanation.

Try it

The fastest way to understand FootPrint is to see it run:

Interactive Playground — 37+ samples, zero install, runs in your browser
Live LLM Demo — watch Claude call a credit-decision flowchart as an MCP tool
GitHub — MIT licensed, zero dependencies, npm provenance signed

npm install footprintjs        # the engine
npm install agentfootprint     # the agent framework

We built the pattern we wished existed when our LLM lied to a user. If you’re building systems where AI needs to explain decisions — fintech, healthcare, compliance, insurance — we think this is the right foundation.

footprintjs | Blog

Backward Causal Chain: Error Stack Traces for Data Quality

The problem: “Why is the answer bad?”

The algorithm

Staged optimization: the query optimizer trick

Built on recorder operations

The ROI

Time saved

Cost saved

Quality improvement

The dependency DAG

Try it

Three Operations on Auto-Collected Data: The Recorder Pattern That Saves You $15/1M Tokens

The $15 question

The three operations

1. Translate — “What happened at this step?”

2. Accumulate — “What happened up to this point?”

3. Aggregate — “What’s the grand total?”

The foundation for everything

Pause/Resume: Human-in-the-Loop for Backend Pipelines

The problem

How it works

1. Define a pausable stage

2. Build the pipeline

3. Run, pause, checkpoint

4. Resume (hours later, any server)

What makes this different

Try it live

The API surface

What’s next

Automated Decision Explainability: How Causal Traces Solve GDPR Article 22 and Audit Requirements

The regulatory reality

Causal traces: the structural solution

What auditors see

Decision evidence with decide()

Compliance properties

Real-world application

Getting started

Auto-Generate MCP Tools from Your Backend Code in One Line

The tool description problem

One line: .toMCPTool()

Register with any MCP server

Also: .toOpenAPI()

With agentfootprint: full agent integration

Why this matters

Try the live demo

Testing AI Agents for $0: The Adapter-Swap Pattern

The $47 test suite

The pattern: mock() → anthropic()

What you can test for $0

The concept ladder makes this natural

When you still need real LLM tests

Try it

Why We Built FootPrint: The Missing Pattern for Explainable Backend Code

The moment that started everything

The structural problem

The flowchart pattern

The ecosystem

What we got wrong (and fixed)

Try it

Decision evidence with `decide()`

One line: `.toMCPTool()`

Also: `.toOpenAPI()`