agentfootprint 1.8.0 → 1.9.0

package/dist/esm/patterns/index.js

@@ -0,0 +1,18 @@
+/**
+ * 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';
+ * ```
+ */
+export { planExecute } from './planExecute';
+export { mapReduce } from './mapReduce';
+export { treeOfThoughts } from './treeOfThoughts';
+export { reflexion } from './reflexion';
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAGxC,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAGlD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC"}

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/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"}

package/dist/types/patterns/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * 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';
+ * ```
+ */
+export { planExecute } from './planExecute';
+export type { PlanExecuteOptions } from './planExecute';
+export { mapReduce } from './mapReduce';
+export type { MapReduceOptions, MapReduceMapper, MapReduceReduceConfig } from './mapReduce';
+export { treeOfThoughts } from './treeOfThoughts';
+export type { TreeOfThoughtsOptions } from './treeOfThoughts';
+export { reflexion } from './reflexion';
+export type { ReflexionOptions } from './reflexion';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/patterns/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/patterns/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,YAAY,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAE5F,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAC;AAE9D,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,YAAY,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC"}

package/dist/types/patterns/mapReduce.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { type ParallelRunner, type BranchResult } from '../concepts/Parallel';
+import type { RunnerLike, LLMProvider } from '../types';
+export interface MapReduceMapper {
+    readonly id: string;
+    readonly description: string;
+    readonly runner: RunnerLike;
+}
+export type MapReduceReduceConfig = {
+    readonly mode: 'llm';
+    readonly prompt: string;
+} | {
+    readonly mode: 'fn';
+    readonly fn: (results: Record<string, BranchResult>) => string;
+};
+export interface MapReduceOptions {
+    /** Provider used for the reduce step (only needed when `reduce.mode === 'llm'`). */
+    readonly provider: LLMProvider;
+    /** Pre-bound mappers — each runner already has its slice of work baked in. */
+    readonly mappers: readonly MapReduceMapper[];
+    /** Reduce strategy — LLM-synthesized or custom function. */
+    readonly reduce: MapReduceReduceConfig;
+    /** Name in narrative (default `'mapReduce'`). */
+    readonly name?: string;
+}
+/**
+ * Build a map-reduce pipeline. Returns a `ParallelRunner` — plug it into
+ * `FlowChart`, `Conditional`, or `Agent.route()` like any other runner.
+ */
+export declare function mapReduce(options: MapReduceOptions): ParallelRunner;
+//# sourceMappingURL=mapReduce.d.ts.map

package/dist/types/patterns/mapReduce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mapReduce.d.ts","sourceRoot":"","sources":["../../../src/patterns/mapReduce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAY,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACxF,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;CAC7B;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,KAAK,MAAM,CAAA;CAAE,CAAC;AAE5F,MAAM,WAAW,gBAAgB;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,8EAA8E;IAC9E,QAAQ,CAAC,OAAO,EAAE,SAAS,eAAe,EAAE,CAAC;IAC7C,4DAA4D;IAC5D,QAAQ,CAAC,MAAM,EAAE,qBAAqB,CAAC;IACvC,iDAAiD;IACjD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,cAAc,CAmBnE"}

package/dist/types/patterns/planExecute.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 { type FlowChartRunner } from '../concepts/FlowChart';
+import type { RunnerLike } from '../types';
+export interface PlanExecuteOptions {
+    /** Runner that produces a plan from the user's request. */
+    readonly planner: RunnerLike;
+    /** Runner that executes the plan produced by `planner`. */
+    readonly executor: RunnerLike;
+    /** Stage name for the planner step in narrative (default `'Plan'`). */
+    readonly planName?: string;
+    /** Stage name for the executor step in narrative (default `'Execute'`). */
+    readonly executeName?: string;
+}
+/**
+ * Build a planner → executor pipeline. Returns a `FlowChartRunner` — plug it
+ * into `Parallel`, `FlowChart`, `Conditional`, or `Agent.route()` like any
+ * other runner.
+ */
+export declare function planExecute(options: PlanExecuteOptions): FlowChartRunner;
+//# sourceMappingURL=planExecute.d.ts.map

package/dist/types/patterns/planExecute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planExecute.d.ts","sourceRoot":"","sources":["../../../src/patterns/planExecute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,2EAA2E;IAC3E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,kBAAkB,GAAG,eAAe,CAKxE"}

package/dist/types/patterns/reflexion.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { type FlowChartRunner } from '../concepts/FlowChart';
+import type { RunnerLike } from '../types';
+export interface ReflexionOptions {
+    /** Produces the first draft. */
+    readonly solver: RunnerLike;
+    /** Reviews the draft, outputs critique. */
+    readonly critic: RunnerLike;
+    /** Integrates the critique to produce the final answer. */
+    readonly improver: RunnerLike;
+    /** Stage names for narrative (defaults: `'Solve'`, `'Critique'`, `'Improve'`). */
+    readonly solveName?: string;
+    readonly critiqueName?: string;
+    readonly improveName?: string;
+}
+/**
+ * Build a Solve → Critique → Improve pipeline. Returns a `FlowChartRunner`.
+ */
+export declare function reflexion(options: ReflexionOptions): FlowChartRunner;
+//# sourceMappingURL=reflexion.d.ts.map

package/dist/types/patterns/reflexion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reflexion.d.ts","sourceRoot":"","sources":["../../../src/patterns/reflexion.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AAEH,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAE3C,MAAM,WAAW,gBAAgB;IAC/B,gCAAgC;IAChC,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,2CAA2C;IAC3C,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,QAAQ,EAAE,UAAU,CAAC;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;GAEG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,eAAe,CAMpE"}

package/dist/types/patterns/treeOfThoughts.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { type FlowChartRunner } from '../concepts/FlowChart';
+import type { RunnerLike, LLMProvider } from '../types';
+export interface TreeOfThoughtsOptions {
+    /** Provider for the Parallel merge step. */
+    readonly provider: LLMProvider;
+    /** Number of parallel thinkers (2–10). */
+    readonly branches: number;
+    /**
+     * Factory producing one thinker per index. Called once per branch at
+     * build time; each should return a built Runner.
+     */
+    readonly thinker: (index: number) => RunnerLike;
+    /** Judge runner — receives all thinker outputs labeled by id, returns the best answer. */
+    readonly judge: RunnerLike;
+    /** Narrative name (default `'treeOfThoughts'`). */
+    readonly name?: string;
+}
+/**
+ * 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 declare function treeOfThoughts(options: TreeOfThoughtsOptions): FlowChartRunner;
+//# sourceMappingURL=treeOfThoughts.d.ts.map

package/dist/types/patterns/treeOfThoughts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"treeOfThoughts.d.ts","sourceRoot":"","sources":["../../../src/patterns/treeOfThoughts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAa,KAAK,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAExE,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAExD,MAAM,WAAW,qBAAqB;IACpC,4CAA4C;IAC5C,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC;IAC/B,0CAA0C;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,UAAU,CAAC;IAChD,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,mDAAmD;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CA2B9E"}

package/dist/types/patterns.barrel.d.ts

@@ -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.d.ts.map

package/dist/types/patterns.barrel.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentfootprint",
-  "version": "1.8.0",
+  "version": "1.9.0",
   "description": "The explainable agent framework — build AI agents you can explain, audit, and trust. Built on footprintjs.",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -117,6 +117,11 @@
       "types": "./dist/types/stream.barrel.d.ts",
       "import": "./dist/esm/stream.barrel.js",
       "require": "./dist/stream.barrel.js"
+    },
+    "./patterns": {
+      "types": "./dist/types/patterns.barrel.d.ts",
+      "import": "./dist/esm/patterns.barrel.js",
+      "require": "./dist/patterns.barrel.js"
     }
   },
   "typesVersions": {
@@ -141,6 +146,9 @@
       ],
       "stream": [
         "dist/types/stream.barrel.d.ts"
+      ],
+      "patterns": [
+        "dist/types/patterns.barrel.d.ts"
       ]
     }
   },