footprintjs 0.2.1 → 0.2.3

package/README.md

@@ -21,9 +21,48 @@ FootPrint is a runtime for building **flowchart pipelines** where each node is j
 npm install footprintjs
 ```
 
+## Quick Start
+
+```typescript
+import { flowChart, FlowChartExecutor, ScopeFacade, toScopeFactory } from 'footprintjs';
+
+const chart = flowChart('Greet', (scope) => {
+    scope.setValue('name', 'Alice');
+  })
+  .addFunction('Personalize', (scope) => {
+    const name = scope.getValue('name');
+    scope.setValue('message', `Hello, ${name}!`);
+  })
+  .setEnableNarrative()
+  .build();
+
+const executor = new FlowChartExecutor(chart, toScopeFactory(ScopeFacade));
+const result = await executor.run();
+
+console.log(executor.getNarrative());
+// Stage 1: The process began with Greet.
+//   Step 1: Write name = "Alice"
+// Stage 2: Next, it moved on to Personalize.
+//   Step 1: Read name = "Alice"
+//   Step 2: Write message = "Hello, Alice!"
+```
+
+> **[Try it in the browser](https://footprintjs.github.io/footprint-playground/)** — no install needed
+>
+> **[Browse 20+ examples](https://github.com/footprintjs/footPrint-samples)** — features, flowchart patterns, and a full loan underwriting demo
+
 ---
 
-## Why causal traces?
+## Why FootPrint?
+
+| | Without FootPrint | With FootPrint |
+|---|---|---|
+| **LLM explains a decision** | Reconstruct from scattered logs; expensive, slow, hallucination-prone | Read the causal trace; cheap model, fewer tokens, zero hallucination |
+| **Tool descriptions** | Write and maintain them by hand | Auto-generated from the flowchart structure |
+| **Debugging** | `console.log` + guesswork | Time-travel replay to any stage |
+| **State management** | Global/manual, race-prone | Transactional scope with atomic commits |
+
+### Example: Loan rejection
 
 A loan application pipeline rejects Bob. The user asks: **"Why was I rejected?"**
 
@@ -69,67 +108,81 @@ No one wrote those trace sentences. Stage functions just read and write scope &m
 
 ```typescript
 import {
-  FlowChartBuilder, FlowChartExecutor, ScopeFacade, toScopeFactory,
+  flowChart, FlowChartExecutor, ScopeFacade, toScopeFactory,
 } from 'footprintjs';
 
-// ── Stage functions: just do the work, no descriptions needed ──────────
-
-const receiveApplication = async (scope: ScopeFacade) => {
-  scope.setValue('app', app);                         // objects, arrays, nested — all supported
+// ── Stage functions: just read and write scope ─────────────────────────
+
+const receiveApplication = (scope: ScopeFacade) => {
+  scope.setValue('app', {
+    applicantName: 'Bob',
+    annualIncome: 42_000,
+    monthlyDebts: 2_100,
+    creditScore: 580,
+    employmentType: 'self-employed',
+    employmentYears: 1,
+  });
 };
 
-const pullCreditReport = async (scope: ScopeFacade) => {
+const pullCreditReport = (scope: ScopeFacade) => {
   const { creditScore } = scope.getValue('app') as any;
-  const tier = creditScore >= 740 ? 'excellent' : creditScore >= 670 ? 'good'
-             : creditScore >= 580 ? 'fair' : 'poor';
+  const tier = creditScore >= 740 ? 'excellent'
+    : creditScore >= 670 ? 'good'
+    : creditScore >= 580 ? 'fair' : 'poor';
+
   scope.setValue('creditTier', tier);
   scope.setValue('creditFlags', tier === 'fair' ? ['below-average credit'] : []);
 };
 
-const calculateDTI = async (scope: ScopeFacade) => {
+const calculateDTI = (scope: ScopeFacade) => {
   const { annualIncome, monthlyDebts } = scope.getValue('app') as any;
-  const dtiRatio = Math.round((monthlyDebts / (annualIncome / 12)) * 100) / 100;
-  scope.setValue('dtiRatio', dtiRatio);
-  scope.setValue('dtiPercent', Math.round(dtiRatio * 100));
-  scope.setValue('dtiStatus', dtiRatio > 0.43 ? 'excessive' : 'healthy');
-  scope.setValue('dtiFlags',
-    dtiRatio > 0.43 ? [`DTI at ${Math.round(dtiRatio * 100)}% exceeds 43%`] : []);
+  const ratio = Math.round((monthlyDebts / (annualIncome / 12)) * 100) / 100;
+
+  scope.setValue('dtiRatio', ratio);
+  scope.setValue('dtiFlags', ratio > 0.43 ? [`DTI at ${Math.round(ratio * 100)}% exceeds 43%`] : []);
 };
 
-const assessRisk = async (scope: ScopeFacade) => {
-  const creditTier = scope.getValue('creditTier') as string;
-  const dtiStatus = scope.getValue('dtiStatus') as string;
+const verifyEmployment = (scope: ScopeFacade) => {
+  const { employmentType, employmentYears } = scope.getValue('app') as any;
+  const verified = employmentType !== 'self-employed' || employmentYears >= 2;
+
+  scope.setValue('employmentVerified', verified);
+  scope.setValue('employmentFlags', !verified
+    ? [`${employmentType}, ${employmentYears}yr < 2yr minimum`] : []);
+};
+
+const assessRisk = (scope: ScopeFacade) => {
+  const tier = scope.getValue('creditTier') as string;
+  const ratio = scope.getValue('dtiRatio') as number;
   const verified = scope.getValue('employmentVerified') as boolean;
-  const riskTier = (!verified || dtiStatus === 'excessive' || creditTier === 'poor')
-    ? 'high' : 'low';
-  scope.setValue('riskTier', riskTier);
-  scope.setValue('riskFactors', [/* collected flags */]);
+
+  scope.setValue('riskTier', (!verified || ratio > 0.43 || tier === 'poor') ? 'high' : 'low');
 };
 
+// Deciders return a branch ID — the only stage that needs a return value
 const loanDecider = (scope: ScopeFacade): string => {
   const tier = scope.getValue('riskTier') as string;
-  return tier === 'low' ? 'approved' : tier === 'high' ? 'rejected' : 'manual-review';
+  if (tier === 'low') return 'approved';
+  if (tier === 'high') return 'rejected';
+  return 'manual-review';
 };
 
-// ── Build the flow ─────────────────────────────────────────────────────
+// ── Build → Run → Narrative (D3-style chaining) ──────────────────────
 
-const chart = new FlowChartBuilder()
+const chart = flowChart('ReceiveApplication', receiveApplication)
   .setEnableNarrative()
-  .start('ReceiveApplication', receiveApplication)
   .addFunction('PullCreditReport', pullCreditReport)
   .addFunction('CalculateDTI', calculateDTI)
   .addFunction('VerifyEmployment', verifyEmployment)
   .addFunction('AssessRisk', assessRisk)
   .addDeciderFunction('LoanDecision', loanDecider as any)
-    .addFunctionBranch('approved', 'ApproveApplication', approveFn)
-    .addFunctionBranch('rejected', 'RejectApplication', rejectFn)
-    .addFunctionBranch('manual-review', 'ManualReview', reviewFn)
+    .addFunctionBranch('approved', 'Approve', () => {})
+    .addFunctionBranch('rejected', 'Reject', () => {})
+    .addFunctionBranch('manual-review', 'ManualReview', () => {})
     .setDefault('manual-review')
     .end()
   .build();
 
-// ── Run and get the narrative ──────────────────────────────────────────
-
 const executor = new FlowChartExecutor(chart, toScopeFactory(ScopeFacade));
 await executor.run();