agentfootprint 1.22.0 → 2.0.1

package/dist/esm/memory/stages/formatDefault.js

@@ -15,25 +15,7 @@ function defaultRenderEntry(entry) {
     const msg = entry.value;
     const turnAttr = entry.source?.turn !== undefined ? ` turn="${entry.source.turn}"` : '';
     const updatedAttr = entry.updatedAt !== undefined ? ` updated="${new Date(entry.updatedAt).toISOString()}"` : '';
-    // Content extraction — handle both string and content-block variants.
-    let text;
-    if (typeof msg.content === 'string') {
-        text = msg.content;
-    }
-    else if (Array.isArray(msg.content)) {
-        const parts = [];
-        for (const block of msg.content) {
-            if (typeof block === 'object' && block !== null) {
-                const b = block;
-                if (b.type === 'text' && typeof b.text === 'string')
-                    parts.push(b.text);
-            }
-        }
-        text = parts.join(' ');
-    }
-    else {
-        text = '';
-    }
+    const text = msg.content ?? '';
     const role = msg.role ?? 'unknown';
     return `<memory role="${role}"${turnAttr}${updatedAttr}>\n${escapeMemoryTag(text)}\n</memory>`;
 }

package/dist/esm/memory/stages/formatDefault.js.map

@@ -1 +1 @@
-{"version":3,"file":"formatDefault.js","sourceRoot":"","sources":["../../../../src/memory/stages/formatDefault.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"formatDefault.js","sourceRoot":"","sources":["../../../../src/memory/stages/formatDefault.ts"],"names":[],"mappings":"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"}

package/dist/esm/memory/stages/tokenize.js

@@ -40,26 +40,6 @@ export const approximateTokenCounter = (text) => {
  * reflect their structural cost.
  */
 export function countMessageTokens(message, counter = approximateTokenCounter) {
-    if (typeof message.content === 'string') {
-        return counter(message.content);
-    }
-    if (Array.isArray(message.content)) {
-        let total = 0;
-        for (const block of message.content) {
-            if (typeof block === 'object' && block !== null) {
-                const b = block;
-                if (b.type === 'text' && typeof b.text === 'string') {
-                    total += counter(b.text);
-                }
-                else {
-                    // Tool calls, images, etc. Conservative fixed cost so budget
-                    // stays bounded even when block shapes are unknown.
-                    total += 10;
-                }
-            }
-        }
-        return total;
-    }
-    return 0;
+    return counter(message.content ?? '');
 }
 //# sourceMappingURL=tokenize.js.map

package/dist/esm/memory/stages/tokenize.js.map

@@ -1 +1 @@
-{"version":3,"file":"tokenize.js","sourceRoot":"","sources":["../../../../src/memory/stages/tokenize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAiB,CAAC,IAAY,EAAU,EAAE;IAC5E,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAgB,EAChB,UAAwB,uBAAuB;IAE/C,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAClC,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,CAAC;QACnC,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;YACpC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBAChD,MAAM,CAAC,GAAG,KAAyC,CAAC;gBACpD,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBACpD,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;gBAC3B,CAAC;qBAAM,CAAC;oBACN,6DAA6D;oBAC7D,oDAAoD;oBACpD,KAAK,IAAI,EAAE,CAAC;gBACd,CAAC;YACH,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"tokenize.js","sourceRoot":"","sources":["../../../../src/memory/stages/tokenize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAOH;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAiB,CAAC,IAAY,EAAU,EAAE;IAC5E,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AACpC,CAAC,CAAC;AAEF;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,OAAgB,EAChB,UAAwB,uBAAuB;IAE/C,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC;AACxC,CAAC"}

package/dist/esm/observe.js

@@ -0,0 +1,51 @@
+/**
+ * agentfootprint/observe — observability recorders.
+ *
+ * Pattern: Observer (GoF) — pluggable, fire-and-forget event listeners
+ *          for the agent's typed event stream.
+ * Role:    Outer ring (Hexagonal). Attach via `runner.attachRecorder()`;
+ *          the runner emits events, recorders accumulate state.
+ *
+ * Three tiers (progressive disclosure):
+ *
+ *   Tier 1 — context + stream                                (the core)
+ *     • ContextRecorder      — every slot composition
+ *     • StreamRecorder       — token-level LLM streaming
+ *
+ *   Tier 2 — composition + agent                       (structural nav)
+ *     • CompositionRecorder  — Sequence/Parallel/Conditional/Loop entries
+ *     • AgentRecorder        — agent-loop iterations, tool calls
+ *     • BoundaryRecorder     — domain-tagged subflow entry/exit
+ *     • FlowchartRecorder    — StepGraph projection (Lens-friendly)
+ *
+ *   Tier 3 — domain dashboards                              (attach on demand)
+ *     • CostRecorder         — token/USD spend
+ *     • EvalRecorder         — eval scores from `runner.emit('eval.*', ...)`
+ *     • MemoryRecorder       — memory injections + writes
+ *     • PermissionRecorder   — permission decisions + denials
+ *     • SkillRecorder        — skill activations
+ *     • LoggingRecorder      — structured log lines per event
+ *     • ThinkingRecorder     — chat-bubble first-person status
+ *
+ * Domain-flavored consumers (Lens, Grafana, Datadog) compose Tier 1+2
+ * directly; Tier 3 dashboards are opt-in.
+ */
+// Tier 1 — context + stream
+export { ContextRecorder } from './recorders/core/ContextRecorder.js';
+export { streamRecorder } from './recorders/core/StreamRecorder.js';
+// Tier 2 — composition + agent
+export { compositionRecorder, } from './recorders/core/CompositionRecorder.js';
+export { agentRecorder } from './recorders/core/AgentRecorder.js';
+export { boundaryRecorder, BoundaryRecorder, } from './recorders/observability/BoundaryRecorder.js';
+export { attachFlowchart, buildStepGraph, } from './recorders/observability/FlowchartRecorder.js';
+// Tier 3 — domain dashboards
+export { costRecorder } from './recorders/core/CostRecorder.js';
+export { evalRecorder } from './recorders/core/EvalRecorder.js';
+export { memoryRecorder } from './recorders/core/MemoryRecorder.js';
+export { permissionRecorder, } from './recorders/core/PermissionRecorder.js';
+export { skillRecorder } from './recorders/core/SkillRecorder.js';
+export { attachLogging, LoggingDomains, } from './recorders/observability/LoggingRecorder.js';
+export { attachThinking, } from './recorders/observability/ThinkingRecorder.js';
+// Emit primitive — used by every Tier-3 source-domain.
+export { typedEmit } from './recorders/core/typedEmit.js';
+//# sourceMappingURL=observe.js.map

package/dist/esm/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,4BAA4B;AAC5B,OAAO,EAAE,eAAe,EAA+B,MAAM,qCAAqC,CAAC;AACnG,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAEhG,+BAA+B;AAC/B,OAAO,EACL,mBAAmB,GAEpB,MAAM,yCAAyC,CAAC;AACjD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,gBAAgB,EAChB,gBAAgB,GAQjB,MAAM,+CAA+C,CAAC;AACvD,OAAO,EACL,eAAe,EACf,cAAc,GAQf,MAAM,gDAAgD,CAAC;AAExD,6BAA6B;AAC7B,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,YAAY,EAA4B,MAAM,kCAAkC,CAAC;AAC1F,OAAO,EAAE,cAAc,EAA8B,MAAM,oCAAoC,CAAC;AAChG,OAAO,EACL,kBAAkB,GAEnB,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,aAAa,EAA6B,MAAM,mCAAmC,CAAC;AAC7F,OAAO,EACL,aAAa,EACb,cAAc,GAIf,MAAM,8CAA8C,CAAC;AACtD,OAAO,EACL,cAAc,GAGf,MAAM,+CAA+C,CAAC;AAEvD,uDAAuD;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/esm/patterns/Debate.js

@@ -0,0 +1,61 @@
+/**
+ * Debate — two agents alternate proposing + critiquing, a judge decides.
+ *
+ * Paper: "Improving Factuality and Reasoning in Language Models through
+ *        Multiagent Debate" — Du et al., 2023
+ *        (https://arxiv.org/abs/2305.14325).
+ *
+ * Pattern: Factory → produces a `Runner` built from
+ *          `Sequence(Proposer → Critic → Judge)` by default, or an
+ *          iterated `Loop(Sequence(…))` when `rounds > 1`.
+ * Role:    patterns/ layer.
+ * Emits:   Everything Sequence + Loop + LLMCall emit.
+ */
+import { LLMCall } from '../core/LLMCall.js';
+import { Loop } from '../core-flow/Loop.js';
+import { Sequence } from '../core-flow/Sequence.js';
+/**
+ * Build a Debate Runner. One debate "round" = Proposer → Critic. After
+ * N rounds, the Judge sees the final exchange and renders the verdict.
+ * The Judge's output is the Runner's return value.
+ */
+export function debate(opts) {
+    const rounds = opts.rounds ?? 1;
+    if (rounds < 1) {
+        throw new Error('Debate: rounds must be >= 1');
+    }
+    const makeCall = (systemPrompt) => LLMCall.create({
+        provider: opts.provider,
+        model: opts.model,
+        ...(opts.temperature !== undefined && { temperature: opts.temperature }),
+        ...(opts.maxTokens !== undefined && { maxTokens: opts.maxTokens }),
+    })
+        .system(systemPrompt)
+        .build();
+    // A debate round: Proposer → pipeVia(transcript-to-critic) → Critic.
+    // The round's output is the critic's response; the next layer (Loop
+    // or the outer Sequence) decides how to frame it for the next
+    // consumer (another round or the Judge).
+    const buildRound = () => Sequence.create({ id: 'debate-round' })
+        .step('proposer', makeCall(opts.proposerPrompt))
+        .pipeVia((proposalMsg) => ({
+        message: `A proposer argued:\n\n${proposalMsg}\n\nCritique this argument.`,
+    }))
+        .step('critic', makeCall(opts.criticPrompt))
+        .build();
+    // A full debate is: N rounds (via Loop) → Judge.
+    const roundsRunner = rounds === 1
+        ? buildRound()
+        : Loop.create({ id: 'debate-rounds' }).repeat(buildRound()).times(rounds).build();
+    return Sequence.create({
+        name: opts.name ?? 'Debate',
+        id: opts.id ?? 'debate',
+    })
+        .step('rounds', roundsRunner)
+        .pipeVia((transcript) => ({
+        message: `Full debate transcript:\n\n${transcript}\n\nGive your verdict.`,
+    }))
+        .step('judge', makeCall(opts.judgePrompt))
+        .build();
+}
+//# sourceMappingURL=Debate.js.map

package/dist/esm/patterns/Debate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Debate.js","sourceRoot":"","sources":["../../../src/patterns/Debate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAmBpD;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,IAAmB;IACxC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,CAAC,CAAC;IAChC,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CAAC,6BAA6B,CAAC,CAAC;IACjD,CAAC;IAED,MAAM,QAAQ,GAAG,CAAC,YAAoB,EAAE,EAAE,CACxC,OAAO,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QACxE,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;KACnE,CAAC;SACC,MAAM,CAAC,YAAY,CAAC;SACpB,KAAK,EAAE,CAAC;IAEb,qEAAqE;IACrE,oEAAoE;IACpE,8DAA8D;IAC9D,yCAAyC;IACzC,MAAM,UAAU,GAAG,GAAG,EAAE,CACtB,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,cAAc,EAAE,CAAC;SACpC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;SAC/C,OAAO,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC;QACzB,OAAO,EAAE,yBAAyB,WAAW,6BAA6B;KAC3E,CAAC,CAAC;SACF,IAAI,CAAC,QAAQ,EAAE,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;SAC3C,KAAK,EAAE,CAAC;IAEb,iDAAiD;IACjD,MAAM,YAAY,GAChB,MAAM,KAAK,CAAC;QACV,CAAC,CAAC,UAAU,EAAE;QACd,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,eAAe,EAAE,CAAC,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;IAEtF,OAAO,QAAQ,CAAC,MAAM,CAAC;QACrB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,QAAQ;QAC3B,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,QAAQ;KACxB,CAAC;SACC,IAAI,CAAC,QAAQ,EAAE,YAAY,CAAC;SAC5B,OAAO,CAAC,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;QACxB,OAAO,EAAE,8BAA8B,UAAU,wBAAwB;KAC1E,CAAC,CAAC;SACF,IAAI,CAAC,OAAO,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;SACzC,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns/MapReduce.js

@@ -0,0 +1,162 @@
+/**
+ * MapReduce — fan-out N LLMCalls over deterministic input shards, reduce.
+ *
+ * Origin: classic map-reduce (Dean & Ghemawat, 2004) applied to
+ *         LLM context-window constraints. Seen in long-document
+ *         summarization: split → summarize each → combine.
+ *
+ * Pattern: Factory → produces a Runner composing `Parallel` of N
+ *          shard-aware branches. Each branch is an LLMCall wrapped so it
+ *          extracts its shard index from the input by position.
+ * Role:    patterns/ layer. Pure composition over existing primitives.
+ *
+ * Shard count is fixed at build time — consumer supplies `shardCount`
+ * and a `split(input, shardCount)` function that MUST return exactly
+ * `shardCount` strings. The extracted strings are packed into one
+ * `message` at run time (delimiter `\u001F`) so each branch can pick
+ * its own index. For run-time-variable shard counts, factor MapReduce
+ * inside a wrapping Runner that rebuilds the Parallel per call.
+ */
+import { flowChart, FlowChartExecutor } from 'footprintjs';
+import { LLMCall } from '../core/LLMCall.js';
+import { RunnerBase } from '../core/RunnerBase.js';
+import { Parallel } from '../core-flow/Parallel.js';
+import { Sequence } from '../core-flow/Sequence.js';
+const SHARD_DELIMITER = '\u001F'; // ASCII Unit Separator — unlikely in real text.
+/**
+ * Build a MapReduce Runner. At run time:
+ *   1. The splitter runs the consumer's `split(input, shardCount)` and
+ *      packs the resulting N shards into a delimited string.
+ *   2. Parallel fans out to N branches. Each branch's wrapper extracts
+ *      its own shard from the packed input and feeds it to the shared
+ *      LLMCall.
+ *   3. The reducer combines the N branch outputs into the final string.
+ */
+export function mapReduce(opts) {
+    if (opts.shardCount < 2) {
+        throw new Error('MapReduce: shardCount must be >= 2 (use LLMCall for 1 shard)');
+    }
+    const shardCount = opts.shardCount;
+    // Step 1: split stage — takes the original input, runs split(), packs
+    // the shards into a delimited string. Exposed as a Runner so it can
+    // be the first step of a Sequence.
+    const splitRunner = new ShardSplitRunner(opts.split, shardCount);
+    // Step 2: per-branch wrappers + Parallel. Each branch's wrapper reads
+    // the packed message, splits on the delimiter, picks index i, and
+    // runs the shared LLMCall with just that shard.
+    let par = Parallel.create({
+        id: opts.id ? `${opts.id}-map` : 'mapreduce-map',
+        name: `${opts.name ?? 'MapReduce'}-Map`,
+    });
+    for (let i = 0; i < shardCount; i++) {
+        const branchRunner = new ShardBranchRunner(i, LLMCall.create({
+            provider: opts.provider,
+            model: opts.model,
+            ...(opts.temperature !== undefined && { temperature: opts.temperature }),
+            ...(opts.maxTokens !== undefined && { maxTokens: opts.maxTokens }),
+        })
+            .system(opts.mapPrompt)
+            .build());
+        par = par.branch(`shard-${i}`, branchRunner);
+    }
+    const mapRunner = opts.reduce.kind === 'fn'
+        ? par.mergeWithFn(opts.reduce.fn).build()
+        : par.mergeWithLLM(opts.reduce.opts).build();
+    // Step 3: full pipeline — Sequence(split → Parallel+reduce).
+    return Sequence.create({
+        id: opts.id ?? 'mapreduce',
+        name: opts.name ?? 'MapReduce',
+    })
+        .step('split', splitRunner)
+        .step('map-reduce', mapRunner)
+        .build();
+}
+/**
+ * Runner that runs the consumer's `split()` and returns a packed string.
+ * Implemented as a thin Runner (rather than inline Sequence step) so it
+ * plugs into the existing Sequence.step API.
+ */
+class ShardSplitRunner extends RunnerBase {
+    name = 'ShardSplit';
+    id = 'shard-split';
+    splitFn;
+    shardCount;
+    constructor(splitFn, shardCount) {
+        super();
+        this.splitFn = splitFn;
+        this.shardCount = shardCount;
+    }
+    toFlowChart() {
+        const splitFn = this.splitFn;
+        const shardCount = this.shardCount;
+        return flowChart('Split', (scope) => {
+            const args = scope.$getArgs();
+            const shards = splitFn(args.message, shardCount);
+            const normalized = [];
+            for (let i = 0; i < shardCount; i++)
+                normalized.push(shards[i] ?? '');
+            scope.packed = normalized.join(SHARD_DELIMITER);
+        }, 'split')
+            .addFunction('Return', (scope) => scope.packed, 'return')
+            .build();
+    }
+    async run(input) {
+        const executor = new FlowChartExecutor(this.toFlowChart());
+        const result = await executor.run({ input: { message: input.message } });
+        if (typeof result === 'string')
+            return result;
+        throw new Error('ShardSplit: unexpected result shape');
+    }
+    async resume() {
+        throw new Error('ShardSplit does not support pause/resume');
+    }
+}
+/**
+ * Runner that extracts shard `i` from the packed message and runs the
+ * wrapped LLMCall with just that shard.
+ */
+class ShardBranchRunner extends RunnerBase {
+    name;
+    id;
+    shardIndex;
+    inner;
+    constructor(shardIndex, inner) {
+        super();
+        this.shardIndex = shardIndex;
+        this.inner = inner;
+        this.id = `shard-branch-${shardIndex}`;
+        this.name = `Shard ${shardIndex}`;
+    }
+    toFlowChart() {
+        // Build a wrapper chart that unpacks the shard and invokes the
+        // inner chart. The inner LLMCall's chart runs as a subflow whose
+        // input is the extracted shard.
+        const shardIndex = this.shardIndex;
+        const innerChart = this.inner.toFlowChart();
+        return flowChart('Unpack', (scope) => {
+            const args = scope.$getArgs();
+            const parts = (args.message ?? '').split(SHARD_DELIMITER);
+            scope.shard = parts[shardIndex] ?? '';
+            scope.result = '';
+        }, 'unpack')
+            .addSubFlowChartNext('inner', innerChart, 'InnerCall', {
+            inputMapper: (parent) => ({ message: parent.shard ?? '' }),
+            outputMapper: (sfOutput) => ({
+                result: typeof sfOutput === 'string' ? sfOutput : '',
+            }),
+        })
+            .addFunction('Return', (scope) => scope.result, 'return')
+            .build();
+    }
+    async run(input) {
+        const executor = new FlowChartExecutor(this.toFlowChart());
+        const result = await executor.run({ input: { message: input.message } });
+        if (typeof result === 'string')
+            return result;
+        throw new Error('ShardBranch: unexpected result shape');
+    }
+    async resume() {
+        throw new Error('ShardBranch does not support pause/resume');
+    }
+}
+//# sourceMappingURL=MapReduce.js.map

package/dist/esm/patterns/MapReduce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MapReduce.js","sourceRoot":"","sources":["../../../src/patterns/MapReduce.ts"],"names":[],"mappings":"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"}

package/dist/esm/patterns/Reflection.js

@@ -0,0 +1,64 @@
+/**
+ * Reflection — iterative self-refinement via critic + revise.
+ *
+ * Paper: "Self-Refine: Iterative Refinement with Self-Feedback" —
+ *        Madaan et al., 2023 (https://arxiv.org/abs/2303.17651).
+ *
+ * Pattern: Factory (GoF) → produces a `Runner` built from a `Loop`
+ *          whose body is `Sequence(Propose → Critique → Revise)`.
+ * Role:    patterns/ layer. Pure composition — no new abstractions.
+ * Emits:   Loop's composition.iteration_start / iteration_exit plus
+ *          every inner LLMCall's stream.llm_start/end.
+ */
+import { LLMCall } from '../core/LLMCall.js';
+import { Loop } from '../core-flow/Loop.js';
+import { Sequence } from '../core-flow/Sequence.js';
+/**
+ * Build a Reflection Runner. Each iteration:
+ *   1. Propose — LLMCall writes a candidate answer based on the input
+ *   2. Critique — LLMCall judges the candidate; exit marker stops loop
+ *   3. Revise — next iteration's propose sees the previous critique
+ *
+ * Each iteration's output (the candidate proposal) becomes the next
+ * iteration's input. The final iteration's proposal is returned.
+ */
+export function reflection(opts) {
+    const stopMarker = opts.untilCritiqueContains ?? 'DONE';
+    const maxIterations = opts.maxIterations ?? 3;
+    // Each iteration body: Propose → Critique → Revise. The Sequence's
+    // `current` carries whatever the final step returned.
+    const body = Sequence.create({ id: 'refine-body' })
+        .step('propose', LLMCall.create({
+        provider: opts.provider,
+        model: opts.model,
+        ...(opts.temperature !== undefined && { temperature: opts.temperature }),
+        ...(opts.maxTokens !== undefined && { maxTokens: opts.maxTokens }),
+    })
+        .system(opts.proposerPrompt)
+        .build())
+        .pipeVia((proposal) => ({
+        message: `Proposal to critique:\n${proposal}\n\nRespond with critique. When the proposal is good enough, include the marker "${stopMarker}".`,
+    }))
+        .step('critique', LLMCall.create({
+        provider: opts.provider,
+        model: opts.model,
+        ...(opts.temperature !== undefined && { temperature: opts.temperature }),
+        ...(opts.maxTokens !== undefined && { maxTokens: opts.maxTokens }),
+    })
+        .system(opts.criticPrompt)
+        .build())
+        .build();
+    // Loop body returns the critic's output; we wrap it so the next
+    // iteration's input gets the ORIGINAL proposal + critique combined,
+    // asking the revisor to improve. The Loop until-guard inspects the
+    // critic response for the stop marker.
+    return Loop.create({
+        name: opts.name ?? 'Reflection',
+        id: opts.id ?? 'reflection',
+    })
+        .repeat(body)
+        .times(maxIterations)
+        .until(({ latestOutput }) => latestOutput.includes(stopMarker))
+        .build();
+}
+//# sourceMappingURL=Reflection.js.map

package/dist/esm/patterns/Reflection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Reflection.js","sourceRoot":"","sources":["../../../src/patterns/Reflection.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AA4BpD;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,MAAM,UAAU,GAAG,IAAI,CAAC,qBAAqB,IAAI,MAAM,CAAC;IACxD,MAAM,aAAa,GAAG,IAAI,CAAC,aAAa,IAAI,CAAC,CAAC;IAE9C,mEAAmE;IACnE,sDAAsD;IACtD,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,EAAE,EAAE,EAAE,aAAa,EAAE,CAAC;SAChD,IAAI,CACH,SAAS,EACT,OAAO,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QACxE,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;KACnE,CAAC;SACC,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC;SAC3B,KAAK,EAAE,CACX;SACA,OAAO,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;QACtB,OAAO,EAAE,0BAA0B,QAAQ,oFAAoF,UAAU,IAAI;KAC9I,CAAC,CAAC;SACF,IAAI,CACH,UAAU,EACV,OAAO,CAAC,MAAM,CAAC;QACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC;QACxE,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;KACnE,CAAC;SACC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;SACzB,KAAK,EAAE,CACX;SACA,KAAK,EAAE,CAAC;IAEX,gEAAgE;IAChE,oEAAoE;IACpE,mEAAmE;IACnE,uCAAuC;IACvC,OAAO,IAAI,CAAC,MAAM,CAAC;QACjB,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,YAAY;QAC/B,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,YAAY;KAC5B,CAAC;SACC,MAAM,CAAC,IAAI,CAAC;SACZ,KAAK,CAAC,aAAa,CAAC;SACpB,KAAK,CAAC,CAAC,EAAE,YAAY,EAAE,EAAE,EAAE,CAAC,YAAY,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;SAC9D,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns/SelfConsistency.js

@@ -0,0 +1,71 @@
+/**
+ * SelfConsistency — sample N answers, pick the majority.
+ *
+ * Paper: "Self-Consistency Improves Chain of Thought Reasoning in
+ * Language Models" — Wang et al., 2022 (https://arxiv.org/abs/2203.11171).
+ *
+ * Pattern: Factory (GoF) → produces a `Runner` that composes `Parallel`
+ *          of N `LLMCall` branches with a majority-vote merge function.
+ * Role:    patterns/ layer. Pure composition of core primitives +
+ *          core-flow compositions — no new abstractions.
+ * Emits:   Everything `Parallel` + `LLMCall` emit (stream / composition /
+ *          context). No pattern-specific event domain needed; consumers
+ *          observe via the standard typed listeners.
+ */
+import { LLMCall } from '../core/LLMCall.js';
+import { Parallel } from '../core-flow/Parallel.js';
+/**
+ * Build a SelfConsistency Runner. Given a system prompt, the Runner
+ * runs `samples` parallel LLMCalls with the same input, extracts each
+ * response's vote token, then returns the most-frequent token. Ties
+ * are broken by the first response's extract.
+ */
+export function selfConsistency(opts) {
+    if (opts.samples < 1) {
+        throw new Error('SelfConsistency: samples must be >= 1');
+    }
+    if (opts.samples < 2) {
+        throw new Error('SelfConsistency: samples must be >= 2 to have anything to vote on (use LLMCall for 1 sample)');
+    }
+    const extract = opts.extract ?? ((s) => s.trim());
+    let builder = Parallel.create({
+        name: opts.name ?? 'SelfConsistency',
+        id: opts.id ?? 'self-consistency',
+    });
+    for (let i = 0; i < opts.samples; i++) {
+        const branch = LLMCall.create({
+            provider: opts.provider,
+            model: opts.model,
+            // Higher default temperature for sampling diversity — the whole
+            // point of SelfConsistency is to get DIFFERENT samples.
+            temperature: opts.temperature ?? 0.7,
+            ...(opts.maxTokens !== undefined && { maxTokens: opts.maxTokens }),
+        })
+            .system(opts.systemPrompt)
+            .build();
+        builder = builder.branch(`sample-${i}`, branch);
+    }
+    return builder
+        .mergeWithFn((results) => {
+        const tallies = new Map();
+        const order = [];
+        for (const id of Object.keys(results).sort()) {
+            const vote = extract(results[id]);
+            if (!tallies.has(vote))
+                order.push(vote);
+            tallies.set(vote, (tallies.get(vote) ?? 0) + 1);
+        }
+        let best = order[0];
+        let bestCount = tallies.get(best);
+        for (const vote of order) {
+            const count = tallies.get(vote);
+            if (count > bestCount) {
+                best = vote;
+                bestCount = count;
+            }
+        }
+        return best;
+    })
+        .build();
+}
+//# sourceMappingURL=SelfConsistency.js.map

package/dist/esm/patterns/SelfConsistency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SelfConsistency.js","sourceRoot":"","sources":["../../../src/patterns/SelfConsistency.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAE7C,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAqBpD;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAC;IAC3D,CAAC;IACD,IAAI,IAAI,CAAC,OAAO,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CACb,8FAA8F,CAC/F,CAAC;IACJ,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,CAAC,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAE1D,IAAI,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC5B,IAAI,EAAE,IAAI,CAAC,IAAI,IAAI,iBAAiB;QACpC,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,kBAAkB;KAClC,CAAC,CAAC;IAEH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;YAC5B,QAAQ,EAAE,IAAI,CAAC,QAAQ;YACvB,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,gEAAgE;YAChE,wDAAwD;YACxD,WAAW,EAAE,IAAI,CAAC,WAAW,IAAI,GAAG;YACpC,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;SACnE,CAAC;aACC,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;aACzB,KAAK,EAAE,CAAC;QACX,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAClD,CAAC;IAED,OAAO,OAAO;SACX,WAAW,CAAC,CAAC,OAAO,EAAE,EAAE;QACvB,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC1C,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,MAAM,EAAE,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;YAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,EAAE,CAAE,CAAC,CAAC;YACnC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;gBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACzC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;QAClD,CAAC;QACD,IAAI,IAAI,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;QACrB,IAAI,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QACnC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;YACjC,IAAI,KAAK,GAAG,SAAS,EAAE,CAAC;gBACtB,IAAI,GAAG,IAAI,CAAC;gBACZ,SAAS,GAAG,KAAK,CAAC;YACpB,CAAC;QACH,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC,CAAC;SACD,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns/Swarm.js

@@ -0,0 +1,88 @@
+/**
+ * Swarm — multi-agent handoff. At each step, an LLM-driven routing
+ * decision picks which agent handles the next turn.
+ *
+ * Origin: OpenAI Swarm experiment (2024). Useful for specialist
+ *         routing — each agent has a narrow role + its own tools.
+ *
+ * Pattern: Factory → produces a `Runner` built from
+ *          `Loop(Conditional(route-to-agent))`.
+ * Role:    patterns/ layer. Pure composition over existing primitives.
+ *          Agent roster is FIXED at build time; the routing decision
+ *          is made at runtime by a consumer-supplied `route(input)`
+ *          function (sync — pure over `{ message }`).
+ *
+ * For LLM-driven routing (the classic Swarm style), the consumer
+ * composes a "router" LLMCall as the first step of each iteration and
+ * parses its response in their `route()` function.
+ */
+import { flowChart } from 'footprintjs';
+import { RunnerBase } from '../core/RunnerBase.js';
+import { Conditional } from '../core-flow/Conditional.js';
+import { Loop } from '../core-flow/Loop.js';
+/**
+ * Build a Swarm Runner. Each iteration:
+ *   1. Router evaluates `route(input)` to pick an agent id.
+ *   2. Conditional dispatches to that agent's runner.
+ *   3. Agent's output becomes the next iteration's input.
+ * Loop halts when `route` returns a halt-sentinel id (or unknown id
+ * falling to the `done` branch) OR when `maxHandoffs` is reached.
+ */
+export function swarm(opts) {
+    if (opts.agents.length < 2) {
+        throw new Error('Swarm: must have >= 2 agents (use Agent for 1)');
+    }
+    const routeFn = opts.route;
+    const ids = new Set(opts.agents.map((a) => a.id));
+    if (ids.has('done')) {
+        throw new Error('Swarm: agent id "done" is reserved for the halt branch — rename to avoid collision');
+    }
+    const maxHandoffs = opts.maxHandoffs ?? 10;
+    // Build the routing conditional. One `.when(id, ...)` per agent; the
+    // routing function's return-value drives branch selection.
+    let conditional = Conditional.create({ id: 'route' });
+    for (const agent of opts.agents) {
+        conditional = conditional.when(agent.id, (input) => routeFn(input) === agent.id, agent.runner, agent.name ?? agent.id);
+    }
+    const routing = conditional.otherwise('done', new IdentityRunner()).build();
+    // Wrap in Loop so handoffs iterate. Exit guard: when `route` returns
+    // a halt sentinel, the next `Conditional.when` evaluation fires the
+    // `done` fallback; the body returns the identity output. To stop the
+    // loop at that point we use the `until` guard inspecting whether the
+    // current message was produced by the identity path — heuristically,
+    // we halt when `route(latestOutput)` returns undefined or 'done'.
+    return Loop.create({
+        id: opts.id ?? 'swarm',
+        name: opts.name ?? 'Swarm',
+    })
+        .repeat(routing)
+        .times(maxHandoffs)
+        .until(({ latestOutput }) => {
+        const next = routeFn({ message: latestOutput });
+        return next === undefined || next === 'done' || !ids.has(next);
+    })
+        .build();
+}
+/**
+ * Identity runner — echoes its input message unchanged. Used as the
+ * Swarm's `otherwise` fallback so the loop can exit cleanly when the
+ * router returns a halt sentinel. Not exported (internal-only).
+ */
+class IdentityRunner extends RunnerBase {
+    id = 'done';
+    name = 'Done';
+    toFlowChart() {
+        return flowChart('Done', (scope) => {
+            scope.echoedMessage = scope.$getArgs().message;
+        }, 'done-seed')
+            .addFunction('Return', (scope) => scope.echoedMessage, 'done-return')
+            .build();
+    }
+    async run(input) {
+        return input.message;
+    }
+    async resume() {
+        throw new Error('Swarm IdentityRunner does not support pause/resume');
+    }
+}
+//# sourceMappingURL=Swarm.js.map

package/dist/esm/patterns/Swarm.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Swarm.js","sourceRoot":"","sources":["../../../src/patterns/Swarm.ts"],"names":[],"mappings":"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"}