agentfootprint 1.7.1 → 1.9.0

package/dist/esm/patterns/mapReduce.js

@@ -0,0 +1,60 @@
+/**
+ * mapReduce — fan-out map over N pre-bound mappers, then reduce.
+ *
+ * Each mapper is a runner with its own input already bound (prepare them with
+ * the slice they should process). `Parallel.mergeWithLLM` or a custom reduce
+ * function combines the results. Under the hood: a single `Parallel` with N
+ * branches and one merge strategy.
+ *
+ * Why: map-reduce is a common shape — summarize N documents, compare N
+ * candidates, evaluate a prompt against N rubrics. Keeping it as a named
+ * pattern teaches the shape; each mapper / reducer is still a regular runner.
+ *
+ * @example
+ * ```ts
+ * import { LLMCall, anthropic } from 'agentfootprint';
+ * import { mapReduce } from 'agentfootprint/patterns';
+ *
+ * const documents = [doc1, doc2, doc3];
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const pipeline = mapReduce({
+ *   provider,
+ *   mappers: documents.map((doc, i) => ({
+ *     id: `doc-${i}`,
+ *     description: `Summarize doc ${i}`,
+ *     runner: LLMCall.create({ provider })
+ *       .system(`Summarize this document:\n\n${doc}`)
+ *       .build(),
+ *   })),
+ *   reduce: { mode: 'llm', prompt: 'Combine the summaries into a single report.' },
+ * });
+ *
+ * const result = await pipeline.run('Produce the report');
+ * ```
+ */
+import { Parallel } from '../concepts/Parallel';
+/**
+ * Build a map-reduce pipeline. Returns a `ParallelRunner` — plug it into
+ * `FlowChart`, `Conditional`, or `Agent.route()` like any other runner.
+ */
+export function mapReduce(options) {
+    if (options.mappers.length < 2) {
+        throw new Error('mapReduce requires at least 2 mappers. Use a single runner directly if you only have one.');
+    }
+    const builder = Parallel.create({
+        provider: options.provider,
+        name: options.name ?? 'mapReduce',
+    });
+    for (const m of options.mappers) {
+        builder.agent(m.id, m.runner, m.description);
+    }
+    if (options.reduce.mode === 'llm') {
+        builder.mergeWithLLM(options.reduce.prompt);
+    }
+    else {
+        builder.merge(options.reduce.fn);
+    }
+    return builder.build();
+}
+//# 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":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,QAAQ,EAA0C,MAAM,sBAAsB,CAAC;AAwBxF;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW;KAClC,CAAC,CAAC;IACH,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/esm/patterns/planExecute.js

@@ -0,0 +1,43 @@
+/**
+ * planExecute — Planner → Executor composition.
+ *
+ * Two runners chained sequentially: the planner takes the user request and
+ * produces a plan; the executor takes that plan (as the planner's output) and
+ * carries it out. Pure composition over `FlowChart` — no new primitives,
+ * readable as a teaching example.
+ *
+ * Why: separating planning from execution is often cheaper (small model
+ * plans, capable model executes) and safer (plan visible in narrative before
+ * any tool fires).
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { planExecute } from 'agentfootprint/patterns';
+ *
+ * const planner = Agent.create({ provider: anthropic('claude-haiku-4-5') })
+ *   .system('Produce a numbered plan. Do not execute.')
+ *   .build();
+ *
+ * const executor = Agent.create({ provider: anthropic('claude-sonnet-4') })
+ *   .system('Execute the given plan step by step.')
+ *   .tools([...])
+ *   .build();
+ *
+ * const runner = planExecute({ planner, executor });
+ * const result = await runner.run('Research competitors and draft a brief.');
+ * ```
+ */
+import { FlowChart } from '../concepts/FlowChart';
+/**
+ * Build a planner → executor pipeline. Returns a `FlowChartRunner` — plug it
+ * into `Parallel`, `FlowChart`, `Conditional`, or `Agent.route()` like any
+ * other runner.
+ */
+export function planExecute(options) {
+    return FlowChart.create()
+        .agent('plan', options.planName ?? 'Plan', options.planner)
+        .agent('execute', options.executeName ?? 'Execute', options.executor)
+        .build();
+}
+//# sourceMappingURL=planExecute.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"planExecute.js","sourceRoot":"","sources":["../../../src/patterns/planExecute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,SAAS,EAAwB,MAAM,uBAAuB,CAAC;AAcxE;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAA2B;IACrD,OAAO,SAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC;SAC1D,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC;SACpE,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns/reflexion.js

@@ -0,0 +1,58 @@
+/**
+ * reflexion — Solve → Critique → Improve (single-pass).
+ *
+ * Three runners chained sequentially: a solver produces a draft, a critic
+ * reviews it, an improver integrates the critique. Shinn et al. 2023's
+ * Reflexion pattern has a quality-gated loop; this is the simplest form —
+ * one reflection pass. For multi-iteration Reflexion, wrap this pattern
+ * inside `Conditional` to rerun while a quality predicate fails.
+ *
+ * Why: a single self-review pass catches a surprising number of errors in
+ * reasoning / code / plans. Exposing the three runners individually lets
+ * users pick cheap models for critic/improver while keeping a strong solver.
+ *
+ * Under the hood:
+ *   FlowChart[ solver, critic, improver ]
+ *
+ * Each runner receives the previous runner's output as its input message.
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { reflexion } from 'agentfootprint/patterns';
+ *
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const reviewer = reflexion({
+ *   solver: Agent.create({ provider }).system('Draft an answer.').build(),
+ *   critic: Agent.create({ provider }).system('List weaknesses in the draft.').build(),
+ *   improver: Agent.create({ provider })
+ *     .system('Apply the critique to improve the draft.')
+ *     .build(),
+ * });
+ *
+ * const result = await reviewer.run('Explain monads in plain English.');
+ * ```
+ *
+ * For multi-iteration Reflexion (loop until quality gate passes), compose
+ * with `Conditional`:
+ * ```ts
+ * import { Conditional } from 'agentfootprint';
+ * const iterative = Conditional.create()
+ *   .when((s) => qualityOf(s) < 0.8, reviewer)
+ *   .otherwise(doneRunner)
+ *   .build();
+ * ```
+ */
+import { FlowChart } from '../concepts/FlowChart';
+/**
+ * Build a Solve → Critique → Improve pipeline. Returns a `FlowChartRunner`.
+ */
+export function reflexion(options) {
+    return FlowChart.create()
+        .agent('solve', options.solveName ?? 'Solve', options.solver)
+        .agent('critique', options.critiqueName ?? 'Critique', options.critic)
+        .agent('improve', options.improveName ?? 'Improve', options.improver)
+        .build();
+}
+//# sourceMappingURL=reflexion.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reflexion.js","sourceRoot":"","sources":["../../../src/patterns/reflexion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAE,SAAS,EAAwB,MAAM,uBAAuB,CAAC;AAgBxE;;GAEG;AACH,MAAM,UAAU,SAAS,CAAC,OAAyB;IACjD,OAAO,SAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,IAAI,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC;SAC5D,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,IAAI,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC;SACrE,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC;SACpE,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns/treeOfThoughts.js

@@ -0,0 +1,71 @@
+/**
+ * treeOfThoughts — N parallel thinkers → one judge picks best.
+ *
+ * Fan out N parallel thinkers (each a runner, typically same prompt + higher
+ * temperature variance), format their outputs as context, then hand to a
+ * judge runner that picks or synthesizes the best answer.
+ *
+ * Why: for problems where one-shot answers are often wrong, generating
+ * multiple independent attempts and judging them catches errors that a
+ * single chain-of-thought would miss. Tree-of-Thoughts (Yao et al. 2023)
+ * formalized this pattern.
+ *
+ * Under the hood:
+ *   FlowChart[ Parallel({ t0, t1, ..., tN-1, merge: labelled-concat }),
+ *              judge ]
+ *
+ * The merge step concatenates each thinker's output under its id so the
+ * judge sees them as labeled candidates. The judge receives that
+ * concatenation as its input string.
+ *
+ * @example
+ * ```ts
+ * import { Agent, LLMCall, anthropic } from 'agentfootprint';
+ * import { treeOfThoughts } from 'agentfootprint/patterns';
+ *
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const tot = treeOfThoughts({
+ *   provider,
+ *   branches: 3,
+ *   thinker: (i) =>
+ *     LLMCall.create({ provider }).system(`Thinker ${i + 1}: propose a different solution.`).build(),
+ *   judge: Agent.create({ provider })
+ *     .system('Pick the single best answer and explain why.')
+ *     .build(),
+ * });
+ *
+ * const result = await tot.run('What is the fastest sort for nearly-sorted data?');
+ * ```
+ */
+import { FlowChart } from '../concepts/FlowChart';
+import { Parallel } from '../concepts/Parallel';
+/**
+ * Build a Tree-of-Thoughts pipeline. Returns a `FlowChartRunner`.
+ *
+ * Throws if `branches < 2` — use a single runner directly when you don't need
+ * multiple candidates. Throws if `branches > 10` (Parallel's cap).
+ */
+export function treeOfThoughts(options) {
+    if (options.branches < 2) {
+        throw new Error(`treeOfThoughts requires at least 2 branches (got ${options.branches}). Use a single runner for 1-candidate flows.`);
+    }
+    const parallel = Parallel.create({
+        provider: options.provider,
+        name: `${options.name ?? 'treeOfThoughts'}:thinkers`,
+    });
+    for (let i = 0; i < options.branches; i++) {
+        parallel.agent(`thinker-${i}`, options.thinker(i), `Thinker ${i + 1}`);
+    }
+    // Merge: label each thought so the judge can reference them by id.
+    // Kept as a pure function so the merge itself uses no LLM call — the judge
+    // is the only decision-maker and should be budgeted as such.
+    parallel.merge((results) => Object.entries(results)
+        .map(([id, r]) => `=== ${id} ===\n${r.content}`)
+        .join('\n\n'));
+    return FlowChart.create()
+        .agent('thinkers', 'Think', parallel.build())
+        .agent('judge', 'Judge', options.judge)
+        .build();
+}
+//# sourceMappingURL=treeOfThoughts.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"treeOfThoughts.js","sourceRoot":"","sources":["../../../src/patterns/treeOfThoughts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,SAAS,EAAwB,MAAM,uBAAuB,CAAC;AACxE,OAAO,EAAE,QAAQ,EAAqB,MAAM,sBAAsB,CAAC;AAmBnE;;;;;GAKG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,IAAI,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,oDAAoD,OAAO,CAAC,QAAQ,+CAA+C,CACpH,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,WAAW;KACrD,CAAC,CAAC;IACH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,mEAAmE;IACnE,2EAA2E;IAC3E,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAqC,EAAE,EAAE,CACvD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,IAAI,CAAC,MAAM,CAAC,CAChB,CAAC;IAEF,OAAO,SAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;SAC5C,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC;SACtC,KAAK,EAAE,CAAC;AACb,CAAC"}

package/dist/esm/patterns.barrel.js

@@ -0,0 +1,8 @@
+/**
+ * agentfootprint/patterns — canonical composition patterns.
+ *
+ * See `src/patterns/index.ts` for the patterns themselves. This file is the
+ * subpath barrel used by package.json `exports['./patterns']`.
+ */
+export * from './patterns/index';
+//# sourceMappingURL=patterns.barrel.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.barrel.js","sourceRoot":"","sources":["../../src/patterns.barrel.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -13,7 +13,8 @@
  *   agentfootprint/stream        → Real-time lifecycle events
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.CostRecorder = exports.TurnRecorder = exports.ToolUsageRecorder = exports.TokenRecorder = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.postgresStore = exports.dynamoStore = exports.redisStore = exports.InMemoryStore = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
+exports.ToolUsageRecorder = exports.TokenRecorder = exports.quickBind = exports.AgentPattern = exports.defineInstruction = exports.agentLoop = exports.LLMError = exports.urlImage = exports.base64Image = exports.imageBlock = exports.textBlock = exports.toolResultMessage = exports.assistantMessage = exports.userMessage = exports.systemMessage = exports.postgresStore = exports.dynamoStore = exports.redisStore = exports.InMemoryStore = exports.BrowserOpenAIAdapter = exports.BrowserAnthropicAdapter = exports.BedrockAdapter = exports.OpenAIAdapter = exports.AnthropicAdapter = exports.bedrock = exports.ollama = exports.openai = exports.anthropic = exports.createProvider = exports.MockRetriever = exports.mockRetriever = exports.MockAdapter = exports.mock = exports.ToolRegistry = exports.askHuman = exports.defineTool = exports.ConditionalRunner = exports.Conditional = exports.ParallelRunner = exports.Parallel = exports.SwarmRunner = exports.Swarm = exports.FlowChartRunner = exports.FlowChart = exports.RAGRunner = exports.RAG = exports.LLMCallRunner = exports.LLMCall = exports.AgentRunner = exports.Agent = void 0;
+exports.CostRecorder = exports.TurnRecorder = void 0;
 // ── Concepts (Builders + Runners) ───────────────────────────
 var concepts_1 = require("./concepts");
 Object.defineProperty(exports, "Agent", { enumerable: true, get: function () { return concepts_1.Agent; } });
@@ -28,6 +29,8 @@ Object.defineProperty(exports, "Swarm", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "SwarmRunner", { enumerable: true, get: function () { return concepts_1.SwarmRunner; } });
 Object.defineProperty(exports, "Parallel", { enumerable: true, get: function () { return concepts_1.Parallel; } });
 Object.defineProperty(exports, "ParallelRunner", { enumerable: true, get: function () { return concepts_1.ParallelRunner; } });
+Object.defineProperty(exports, "Conditional", { enumerable: true, get: function () { return concepts_1.Conditional; } });
+Object.defineProperty(exports, "ConditionalRunner", { enumerable: true, get: function () { return concepts_1.ConditionalRunner; } });
 // ── Tools ───────────────────────────────────────────────────
 var tools_1 = require("./tools");
 Object.defineProperty(exports, "defineTool", { enumerable: true, get: function () { return tools_1.defineTool; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,+DAA+D;AAC/D,uCAaoB;AAZlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AAIhB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AACtD,uDAA2D;AAAlD,yGAAA,aAAa,OAAA;AACtB,mDAAkF;AAAzE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAuB/C,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;;AAEH,+DAA+D;AAC/D,uCAeoB;AAdlB,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,mGAAA,OAAO,OAAA;AACP,yGAAA,aAAa,OAAA;AACb,+FAAA,GAAG,OAAA;AACH,qGAAA,SAAS,OAAA;AACT,qGAAA,SAAS,OAAA;AACT,2GAAA,eAAe,OAAA;AACf,iGAAA,KAAK,OAAA;AACL,uGAAA,WAAW,OAAA;AACX,oGAAA,QAAQ,OAAA;AACR,0GAAA,cAAc,OAAA;AACd,uGAAA,WAAW,OAAA;AACX,6GAAA,iBAAiB,OAAA;AASnB,+DAA+D;AAC/D,iCAA6D;AAApD,mGAAA,UAAU,OAAA;AAAE,iGAAA,QAAQ,OAAA;AAAE,qGAAA,YAAY,OAAA;AAE3C,iEAAiE;AACjE,uCAA6F;AAApF,gGAAA,IAAI,OAAA;AAAE,uGAAA,WAAW,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxE,mCAA8D;AAArD,mGAAA,SAAS,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,gGAAA,MAAM,OAAA;AAAE,iGAAA,OAAO,OAAA;AAC3C,uCAA6E;AAApE,4GAAA,gBAAgB,OAAA;AAAE,yGAAA,aAAa,OAAA;AAAE,0GAAA,cAAc,OAAA;AACxD,uCAA2E;AAAlE,mHAAA,uBAAuB,OAAA;AAAE,gHAAA,oBAAoB,OAAA;AACtD,uDAA2D;AAAlD,yGAAA,aAAa,OAAA;AACtB,mDAAkF;AAAzE,oGAAA,UAAU,OAAA;AAAE,qGAAA,WAAW,OAAA;AAAE,uGAAA,aAAa,OAAA;AAuB/C,+DAA+D;AAC/D,iCASiB;AARf,sGAAA,aAAa,OAAA;AACb,oGAAA,WAAW,OAAA;AACX,yGAAA,gBAAgB,OAAA;AAChB,0GAAA,iBAAiB,OAAA;AACjB,kGAAA,SAAS,OAAA;AACT,mGAAA,UAAU,OAAA;AACV,oGAAA,WAAW,OAAA;AACX,iGAAA,QAAQ,OAAA;AAGV,+DAA+D;AAC/D,iCAAmC;AAA1B,iGAAA,QAAQ,OAAA;AA0BjB,8DAA8D;AAC9D,uCAAuC;AAA9B,qGAAA,SAAS,OAAA;AAGlB,uEAAuE;AACvE,6DAAmF;AAA1E,wHAAA,iBAAiB,OAAA;AAAE,mHAAA,YAAY,OAAA;AAAE,gHAAA,SAAS,OAAA;AAGnD,+DAA+D;AAC/D,mDAAgG;AAAvF,+GAAA,aAAa,OAAA;AAAE,mHAAA,iBAAiB,OAAA;AAAE,8GAAA,YAAY,OAAA;AAAE,8GAAA,YAAY,OAAA"}

package/dist/patterns/index.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * agentfootprint/patterns — canonical agent composition patterns.
+ *
+ * Each pattern is a thin factory over the existing concepts (`FlowChart`,
+ * `Parallel`, `Conditional`, `Agent`, `LLMCall`, `RAG`, `Swarm`). No new
+ * primitives. The source of each file shows the composition — read it to
+ * learn how to build your own.
+ *
+ * @example
+ * ```ts
+ * import { treeOfThoughts, reflexion, planExecute, mapReduce } from 'agentfootprint/patterns';
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reflexion = exports.treeOfThoughts = exports.mapReduce = exports.planExecute = void 0;
+var planExecute_1 = require("./planExecute");
+Object.defineProperty(exports, "planExecute", { enumerable: true, get: function () { return planExecute_1.planExecute; } });
+var mapReduce_1 = require("./mapReduce");
+Object.defineProperty(exports, "mapReduce", { enumerable: true, get: function () { return mapReduce_1.mapReduce; } });
+var treeOfThoughts_1 = require("./treeOfThoughts");
+Object.defineProperty(exports, "treeOfThoughts", { enumerable: true, get: function () { return treeOfThoughts_1.treeOfThoughts; } });
+var reflexion_1 = require("./reflexion");
+Object.defineProperty(exports, "reflexion", { enumerable: true, get: function () { return reflexion_1.reflexion; } });
+//# sourceMappingURL=index.js.map

package/dist/patterns/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/patterns/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAEH,6CAA4C;AAAnC,0GAAA,WAAW,OAAA;AAGpB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA;AAGlB,mDAAkD;AAAzC,gHAAA,cAAc,OAAA;AAGvB,yCAAwC;AAA/B,sGAAA,SAAS,OAAA"}

package/dist/patterns/mapReduce.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * mapReduce — fan-out map over N pre-bound mappers, then reduce.
+ *
+ * Each mapper is a runner with its own input already bound (prepare them with
+ * the slice they should process). `Parallel.mergeWithLLM` or a custom reduce
+ * function combines the results. Under the hood: a single `Parallel` with N
+ * branches and one merge strategy.
+ *
+ * Why: map-reduce is a common shape — summarize N documents, compare N
+ * candidates, evaluate a prompt against N rubrics. Keeping it as a named
+ * pattern teaches the shape; each mapper / reducer is still a regular runner.
+ *
+ * @example
+ * ```ts
+ * import { LLMCall, anthropic } from 'agentfootprint';
+ * import { mapReduce } from 'agentfootprint/patterns';
+ *
+ * const documents = [doc1, doc2, doc3];
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const pipeline = mapReduce({
+ *   provider,
+ *   mappers: documents.map((doc, i) => ({
+ *     id: `doc-${i}`,
+ *     description: `Summarize doc ${i}`,
+ *     runner: LLMCall.create({ provider })
+ *       .system(`Summarize this document:\n\n${doc}`)
+ *       .build(),
+ *   })),
+ *   reduce: { mode: 'llm', prompt: 'Combine the summaries into a single report.' },
+ * });
+ *
+ * const result = await pipeline.run('Produce the report');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mapReduce = void 0;
+const Parallel_1 = require("../concepts/Parallel");
+/**
+ * Build a map-reduce pipeline. Returns a `ParallelRunner` — plug it into
+ * `FlowChart`, `Conditional`, or `Agent.route()` like any other runner.
+ */
+function mapReduce(options) {
+    if (options.mappers.length < 2) {
+        throw new Error('mapReduce requires at least 2 mappers. Use a single runner directly if you only have one.');
+    }
+    const builder = Parallel_1.Parallel.create({
+        provider: options.provider,
+        name: options.name ?? 'mapReduce',
+    });
+    for (const m of options.mappers) {
+        builder.agent(m.id, m.runner, m.description);
+    }
+    if (options.reduce.mode === 'llm') {
+        builder.mergeWithLLM(options.reduce.prompt);
+    }
+    else {
+        builder.merge(options.reduce.fn);
+    }
+    return builder.build();
+}
+exports.mapReduce = mapReduce;
+//# sourceMappingURL=mapReduce.js.map

package/dist/patterns/mapReduce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapReduce.js","sourceRoot":"","sources":["../../src/patterns/mapReduce.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;AAEH,mDAAwF;AAwBxF;;;GAGG;AACH,SAAgB,SAAS,CAAC,OAAyB;IACjD,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,2FAA2F,CAC5F,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,mBAAQ,CAAC,MAAM,CAAC;QAC9B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,WAAW;KAClC,CAAC,CAAC;IACH,KAAK,MAAM,CAAC,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC;IAC/C,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QAClC,OAAO,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACnC,CAAC;IACD,OAAO,OAAO,CAAC,KAAK,EAAE,CAAC;AACzB,CAAC;AAnBD,8BAmBC"}

package/dist/patterns/planExecute.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * planExecute — Planner → Executor composition.
+ *
+ * Two runners chained sequentially: the planner takes the user request and
+ * produces a plan; the executor takes that plan (as the planner's output) and
+ * carries it out. Pure composition over `FlowChart` — no new primitives,
+ * readable as a teaching example.
+ *
+ * Why: separating planning from execution is often cheaper (small model
+ * plans, capable model executes) and safer (plan visible in narrative before
+ * any tool fires).
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { planExecute } from 'agentfootprint/patterns';
+ *
+ * const planner = Agent.create({ provider: anthropic('claude-haiku-4-5') })
+ *   .system('Produce a numbered plan. Do not execute.')
+ *   .build();
+ *
+ * const executor = Agent.create({ provider: anthropic('claude-sonnet-4') })
+ *   .system('Execute the given plan step by step.')
+ *   .tools([...])
+ *   .build();
+ *
+ * const runner = planExecute({ planner, executor });
+ * const result = await runner.run('Research competitors and draft a brief.');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.planExecute = void 0;
+const FlowChart_1 = require("../concepts/FlowChart");
+/**
+ * Build a planner → executor pipeline. Returns a `FlowChartRunner` — plug it
+ * into `Parallel`, `FlowChart`, `Conditional`, or `Agent.route()` like any
+ * other runner.
+ */
+function planExecute(options) {
+    return FlowChart_1.FlowChart.create()
+        .agent('plan', options.planName ?? 'Plan', options.planner)
+        .agent('execute', options.executeName ?? 'Execute', options.executor)
+        .build();
+}
+exports.planExecute = planExecute;
+//# sourceMappingURL=planExecute.js.map

package/dist/patterns/planExecute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planExecute.js","sourceRoot":"","sources":["../../src/patterns/planExecute.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;;;AAEH,qDAAwE;AAcxE;;;;GAIG;AACH,SAAgB,WAAW,CAAC,OAA2B;IACrD,OAAO,qBAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,MAAM,EAAE,OAAO,CAAC,QAAQ,IAAI,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC;SAC1D,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC;SACpE,KAAK,EAAE,CAAC;AACb,CAAC;AALD,kCAKC"}

package/dist/patterns/reflexion.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * reflexion — Solve → Critique → Improve (single-pass).
+ *
+ * Three runners chained sequentially: a solver produces a draft, a critic
+ * reviews it, an improver integrates the critique. Shinn et al. 2023's
+ * Reflexion pattern has a quality-gated loop; this is the simplest form —
+ * one reflection pass. For multi-iteration Reflexion, wrap this pattern
+ * inside `Conditional` to rerun while a quality predicate fails.
+ *
+ * Why: a single self-review pass catches a surprising number of errors in
+ * reasoning / code / plans. Exposing the three runners individually lets
+ * users pick cheap models for critic/improver while keeping a strong solver.
+ *
+ * Under the hood:
+ *   FlowChart[ solver, critic, improver ]
+ *
+ * Each runner receives the previous runner's output as its input message.
+ *
+ * @example
+ * ```ts
+ * import { Agent, anthropic } from 'agentfootprint';
+ * import { reflexion } from 'agentfootprint/patterns';
+ *
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const reviewer = reflexion({
+ *   solver: Agent.create({ provider }).system('Draft an answer.').build(),
+ *   critic: Agent.create({ provider }).system('List weaknesses in the draft.').build(),
+ *   improver: Agent.create({ provider })
+ *     .system('Apply the critique to improve the draft.')
+ *     .build(),
+ * });
+ *
+ * const result = await reviewer.run('Explain monads in plain English.');
+ * ```
+ *
+ * For multi-iteration Reflexion (loop until quality gate passes), compose
+ * with `Conditional`:
+ * ```ts
+ * import { Conditional } from 'agentfootprint';
+ * const iterative = Conditional.create()
+ *   .when((s) => qualityOf(s) < 0.8, reviewer)
+ *   .otherwise(doneRunner)
+ *   .build();
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reflexion = void 0;
+const FlowChart_1 = require("../concepts/FlowChart");
+/**
+ * Build a Solve → Critique → Improve pipeline. Returns a `FlowChartRunner`.
+ */
+function reflexion(options) {
+    return FlowChart_1.FlowChart.create()
+        .agent('solve', options.solveName ?? 'Solve', options.solver)
+        .agent('critique', options.critiqueName ?? 'Critique', options.critic)
+        .agent('improve', options.improveName ?? 'Improve', options.improver)
+        .build();
+}
+exports.reflexion = reflexion;
+//# sourceMappingURL=reflexion.js.map

package/dist/patterns/reflexion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflexion.js","sourceRoot":"","sources":["../../src/patterns/reflexion.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;;;AAEH,qDAAwE;AAgBxE;;GAEG;AACH,SAAgB,SAAS,CAAC,OAAyB;IACjD,OAAO,qBAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,SAAS,IAAI,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC;SAC5D,KAAK,CAAC,UAAU,EAAE,OAAO,CAAC,YAAY,IAAI,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC;SACrE,KAAK,CAAC,SAAS,EAAE,OAAO,CAAC,WAAW,IAAI,SAAS,EAAE,OAAO,CAAC,QAAQ,CAAC;SACpE,KAAK,EAAE,CAAC;AACb,CAAC;AAND,8BAMC"}

package/dist/patterns/treeOfThoughts.js

@@ -0,0 +1,75 @@
+"use strict";
+/**
+ * treeOfThoughts — N parallel thinkers → one judge picks best.
+ *
+ * Fan out N parallel thinkers (each a runner, typically same prompt + higher
+ * temperature variance), format their outputs as context, then hand to a
+ * judge runner that picks or synthesizes the best answer.
+ *
+ * Why: for problems where one-shot answers are often wrong, generating
+ * multiple independent attempts and judging them catches errors that a
+ * single chain-of-thought would miss. Tree-of-Thoughts (Yao et al. 2023)
+ * formalized this pattern.
+ *
+ * Under the hood:
+ *   FlowChart[ Parallel({ t0, t1, ..., tN-1, merge: labelled-concat }),
+ *              judge ]
+ *
+ * The merge step concatenates each thinker's output under its id so the
+ * judge sees them as labeled candidates. The judge receives that
+ * concatenation as its input string.
+ *
+ * @example
+ * ```ts
+ * import { Agent, LLMCall, anthropic } from 'agentfootprint';
+ * import { treeOfThoughts } from 'agentfootprint/patterns';
+ *
+ * const provider = anthropic('claude-sonnet-4');
+ *
+ * const tot = treeOfThoughts({
+ *   provider,
+ *   branches: 3,
+ *   thinker: (i) =>
+ *     LLMCall.create({ provider }).system(`Thinker ${i + 1}: propose a different solution.`).build(),
+ *   judge: Agent.create({ provider })
+ *     .system('Pick the single best answer and explain why.')
+ *     .build(),
+ * });
+ *
+ * const result = await tot.run('What is the fastest sort for nearly-sorted data?');
+ * ```
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.treeOfThoughts = void 0;
+const FlowChart_1 = require("../concepts/FlowChart");
+const Parallel_1 = require("../concepts/Parallel");
+/**
+ * Build a Tree-of-Thoughts pipeline. Returns a `FlowChartRunner`.
+ *
+ * Throws if `branches < 2` — use a single runner directly when you don't need
+ * multiple candidates. Throws if `branches > 10` (Parallel's cap).
+ */
+function treeOfThoughts(options) {
+    if (options.branches < 2) {
+        throw new Error(`treeOfThoughts requires at least 2 branches (got ${options.branches}). Use a single runner for 1-candidate flows.`);
+    }
+    const parallel = Parallel_1.Parallel.create({
+        provider: options.provider,
+        name: `${options.name ?? 'treeOfThoughts'}:thinkers`,
+    });
+    for (let i = 0; i < options.branches; i++) {
+        parallel.agent(`thinker-${i}`, options.thinker(i), `Thinker ${i + 1}`);
+    }
+    // Merge: label each thought so the judge can reference them by id.
+    // Kept as a pure function so the merge itself uses no LLM call — the judge
+    // is the only decision-maker and should be budgeted as such.
+    parallel.merge((results) => Object.entries(results)
+        .map(([id, r]) => `=== ${id} ===\n${r.content}`)
+        .join('\n\n'));
+    return FlowChart_1.FlowChart.create()
+        .agent('thinkers', 'Think', parallel.build())
+        .agent('judge', 'Judge', options.judge)
+        .build();
+}
+exports.treeOfThoughts = treeOfThoughts;
+//# sourceMappingURL=treeOfThoughts.js.map

package/dist/patterns/treeOfThoughts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeOfThoughts.js","sourceRoot":"","sources":["../../src/patterns/treeOfThoughts.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;;;AAEH,qDAAwE;AACxE,mDAAmE;AAmBnE;;;;;GAKG;AACH,SAAgB,cAAc,CAAC,OAA8B;IAC3D,IAAI,OAAO,CAAC,QAAQ,GAAG,CAAC,EAAE,CAAC;QACzB,MAAM,IAAI,KAAK,CACb,oDAAoD,OAAO,CAAC,QAAQ,+CAA+C,CACpH,CAAC;IACJ,CAAC;IAED,MAAM,QAAQ,GAAG,mBAAQ,CAAC,MAAM,CAAC;QAC/B,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,IAAI,EAAE,GAAG,OAAO,CAAC,IAAI,IAAI,gBAAgB,WAAW;KACrD,CAAC,CAAC;IACH,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QAC1C,QAAQ,CAAC,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACzE,CAAC;IACD,mEAAmE;IACnE,2EAA2E;IAC3E,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,CAAC,OAAqC,EAAE,EAAE,CACvD,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC;SACpB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;SAC/C,IAAI,CAAC,MAAM,CAAC,CAChB,CAAC;IAEF,OAAO,qBAAS,CAAC,MAAM,EAAE;SACtB,KAAK,CAAC,UAAU,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC;SAC5C,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC;SACtC,KAAK,EAAE,CAAC;AACb,CAAC;AA3BD,wCA2BC"}

package/dist/patterns.barrel.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * agentfootprint/patterns — canonical composition patterns.
+ *
+ * See `src/patterns/index.ts` for the patterns themselves. This file is the
+ * subpath barrel used by package.json `exports['./patterns']`.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./patterns/index"), exports);
+//# sourceMappingURL=patterns.barrel.js.map

package/dist/patterns.barrel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"patterns.barrel.js","sourceRoot":"","sources":["../src/patterns.barrel.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;;;;;;;;;AAEH,mDAAiC"}