agentfootprint 1.0.0

package/dist/concepts/Parallel.js

@@ -0,0 +1,254 @@
+"use strict";
+/**
+ * Parallel — concurrent agent execution with fan-out/fan-in.
+ *
+ * Runs N agents in parallel, each as an isolated subflow. Merges results
+ * via LLM call (default) or custom function.
+ *
+ * Flowchart:
+ *   Seed → [fork]
+ *            ├── agent-A (isolated subflow)
+ *            ├── agent-B (isolated subflow)
+ *            └── agent-C (isolated subflow)
+ *          Merge → Finalize
+ *
+ * Each branch gets its own ExecutionRuntime (isolated scope).
+ * Results flow back through outputMapper (delta pattern).
+ *
+ * Usage:
+ *   const parallel = Parallel.create({ provider })
+ *     .agent('research', researchAgent, 'Research the topic')
+ *     .agent('writing', writingAgent, 'Draft content')
+ *     .mergeWithLLM('Synthesize into a coherent report')
+ *     .build();
+ *   const result = await parallel.run('Write about AI safety');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ParallelRunner = exports.Parallel = void 0;
+const footprintjs_1 = require("footprintjs");
+const types_1 = require("../types");
+const RecorderBridge_1 = require("../recorders/v2/RecorderBridge");
+const createProvider_1 = require("../adapters/createProvider");
+const narrative_1 = require("../lib/narrative");
+const specIcons_1 = require("./specIcons");
+const callLLM_1 = require("../stages/callLLM");
+const MAX_BRANCHES = 10;
+// ── Builder ──────────────────────────────────────────────────
+class Parallel {
+    provider;
+    parallelName;
+    branches = [];
+    mergePrompt;
+    mergeFn;
+    recorders = [];
+    streamingEnabled = false;
+    constructor(options) {
+        this.provider = (0, createProvider_1.resolveProvider)(options.provider);
+        this.parallelName = options.name ?? 'parallel';
+    }
+    static create(options) {
+        return new Parallel(options);
+    }
+    /** Add an agent branch to run in parallel. */
+    agent(id, runner, description) {
+        if (this.branches.length >= MAX_BRANCHES) {
+            throw new Error(`Parallel: maximum ${MAX_BRANCHES} branches. Got ${this.branches.length + 1}.`);
+        }
+        if (this.branches.some((b) => b.id === id)) {
+            throw new Error(`Parallel: duplicate branch ID '${id}'.`);
+        }
+        this.branches.push({ id, description, runner });
+        return this;
+    }
+    /**
+     * Merge results using an LLM call (default strategy).
+     * The LLM receives all branch results as context and generates a unified response.
+     */
+    mergeWithLLM(prompt) {
+        this.mergePrompt = prompt;
+        this.mergeFn = undefined;
+        return this;
+    }
+    /**
+     * Merge results using a custom function (escape hatch for structured data).
+     */
+    merge(fn) {
+        this.mergeFn = fn;
+        this.mergePrompt = undefined;
+        return this;
+    }
+    streaming(enabled) {
+        this.streamingEnabled = enabled;
+        return this;
+    }
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    build() {
+        if (this.branches.length < 2) {
+            throw new Error('Parallel requires at least 2 branches.');
+        }
+        if (!this.mergePrompt && !this.mergeFn) {
+            throw new Error('Parallel requires a merge strategy. Call .mergeWithLLM(prompt) or .merge(fn).');
+        }
+        return new ParallelRunner({
+            provider: this.provider,
+            name: this.parallelName,
+            branches: [...this.branches],
+            mergePrompt: this.mergePrompt,
+            mergeFn: this.mergeFn,
+            streaming: this.streamingEnabled,
+            recorders: [...this.recorders],
+        });
+    }
+}
+exports.Parallel = Parallel;
+class ParallelRunner {
+    opts;
+    lastExecutor;
+    lastSpec;
+    narrativeRenderer = (0, narrative_1.createAgentRenderer)();
+    constructor(options) {
+        this.opts = options;
+    }
+    get name() {
+        return this.opts.name;
+    }
+    /** Build the parallel flowchart. */
+    buildChart(message) {
+        const { provider, branches, mergePrompt, mergeFn } = this.opts;
+        // Seed: initialize message
+        let builder = (0, footprintjs_1.flowChart)('Seed', (scope) => {
+            scope.message = message;
+            scope.branchResults = {};
+            scope.messages = [];
+        }, 'seed', undefined, 'Initialize parallel execution');
+        // Mount each branch as a parallel subflow (fork children with isolated ExecutionRuntime)
+        for (const branch of branches) {
+            const branchChart = this.buildBranchChart(branch);
+            builder = builder.addSubFlowChart(branch.id, branchChart, branch.description, {
+                inputMapper: (parent) => ({
+                    message: parent.message ?? '',
+                }),
+                // applyOutputMapping merges nested keys — return only the new branch delta
+                outputMapper: (sfOutput) => {
+                    const content = String(sfOutput.result ?? sfOutput.content ?? '');
+                    return {
+                        branchResults: {
+                            [branch.id]: { id: branch.id, status: 'fulfilled', content },
+                        },
+                    };
+                },
+            });
+        }
+        // Merge stage — after all branches complete
+        if (mergePrompt) {
+            // LLM merge: feed all branch results to LLM
+            const callLLM = (0, callLLM_1.createCallLLMStage)(provider);
+            builder = builder
+                .addFunction('FormatMerge', (scope) => {
+                const results = scope.branchResults ?? {};
+                // Format branch results as XML-tagged sections for the LLM
+                // Escape XML special chars to prevent prompt injection via branch content
+                const escapeXml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+                const sections = Object.values(results)
+                    .map((r) => `<branch id="${escapeXml(r.id)}">\n${escapeXml(r.content)}\n</branch>`)
+                    .join('\n\n');
+                scope.messages = [
+                    (0, types_1.systemMessage)(`${mergePrompt}\n\nMerge the following parallel results into a coherent response:`),
+                    (0, types_1.userMessage)(sections),
+                ];
+            }, 'format-merge', 'Format branch results for LLM merge')
+                .addFunction('MergeLLM', callLLM, 'merge-llm', 'LLM synthesizes branch results')
+                .addFunction('ExtractMerge', (scope) => {
+                const raw = scope.$getValue('adapterRawResponse');
+                scope.result = raw?.content ?? '';
+            }, 'extract-merge', 'Extract merged result from LLM response');
+        }
+        else if (mergeFn) {
+            // Function merge
+            const fn = mergeFn;
+            builder = builder.addFunction('Merge', (scope) => {
+                const results = scope.branchResults ?? {};
+                scope.result = fn(results);
+            }, 'merge', 'Merge branch results with custom function');
+        }
+        this.lastSpec = (0, specIcons_1.annotateSpecIcons)(builder.toSpec());
+        return builder.build();
+    }
+    /** Build a single branch's flowchart. */
+    buildBranchChart(branch) {
+        // Check if runner has its own flowchart (for BTS drill-down)
+        const runner = branch.runner;
+        if (typeof runner.toFlowChart === 'function') {
+            return runner.toFlowChart();
+        }
+        // Fallback: wrap runner.run() in a single-stage flowchart with error capture
+        return (0, footprintjs_1.flowChart)(branch.id, async (scope) => {
+            try {
+                const res = await branch.runner.run(scope.message ?? '');
+                scope.result = res.content;
+            }
+            catch (err) {
+                scope.branchError = err instanceof Error ? err.message : String(err);
+                scope.result = `[Error: ${scope.branchError}]`;
+            }
+        }, `${branch.id}-run`, undefined, branch.description).build();
+    }
+    async run(message, options) {
+        const chart = this.buildChart(message);
+        const bridge = this.opts.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge(this.opts.recorders) : null;
+        bridge?.dispatchTurnStart(message);
+        const executorOpts = { enrichSnapshots: true };
+        if (options?.onToken && this.opts.streaming) {
+            executorOpts.streamHandlers = {
+                onToken: (_id, token) => options.onToken(token),
+                onStart: () => { },
+                onEnd: () => { },
+            };
+        }
+        const executor = new footprintjs_1.FlowChartExecutor(chart, executorOpts);
+        executor.enableNarrative({ renderer: this.narrativeRenderer });
+        executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        try {
+            await executor.run({
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            this.lastExecutor = executor;
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        const state = executor.getSnapshot()?.sharedState ?? {};
+        const result = state.result ?? '';
+        const branchResults = (state.branchResults ?? {});
+        const messages = state.messages ?? [];
+        bridge?.dispatchTurnComplete(result, messages.length);
+        return {
+            content: result,
+            branches: Object.values(branchResults),
+            messages,
+        };
+    }
+    getNarrative() {
+        return this.lastExecutor?.getNarrative() ?? [];
+    }
+    getNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
+    getSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+    getSpec() {
+        if (!this.lastSpec) {
+            this.buildChart('');
+        }
+        return this.lastSpec;
+    }
+}
+exports.ParallelRunner = ParallelRunner;
+//# sourceMappingURL=Parallel.js.map

package/dist/concepts/Parallel.js.map

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

package/dist/concepts/RAG.js

@@ -0,0 +1,198 @@
+"use strict";
+/**
+ * RAG — Retrieve-Augment-Generate concept.
+ *
+ * Flowchart: Seed → Retrieve → AugmentPrompt → CallLLM → ParseResponse → Finalize
+ *
+ * Usage:
+ *   const rag = RAG.create({ provider: mock([...]), retriever: mockRetriever([...]) })
+ *     .system('You are helpful.')
+ *     .topK(5)
+ *     .build();
+ *   const result = await rag.run('What is X?');
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RAGRunner = exports.RAG = void 0;
+const footprintjs_1 = require("footprintjs");
+const specIcons_1 = require("./specIcons");
+const content_1 = require("../types/content");
+const types_1 = require("../types");
+const RecorderBridge_1 = require("../recorders/v2/RecorderBridge");
+const createProvider_1 = require("../adapters/createProvider");
+const retrieve_1 = require("../stages/retrieve");
+const augmentPrompt_1 = require("../stages/augmentPrompt");
+const callLLM_1 = require("../stages/callLLM");
+const parseResponse_1 = require("../stages/parseResponse");
+const finalize_1 = require("../stages/finalize");
+const memory_1 = require("../memory");
+class RAG {
+    provider;
+    retriever;
+    sysPrompt;
+    retrieveOptions = {};
+    recorders = [];
+    enableStreaming = false;
+    constructor(options) {
+        this.provider = (0, createProvider_1.resolveProvider)(options.provider);
+        this.retriever = options.retriever;
+    }
+    static create(options) {
+        return new RAG(options);
+    }
+    /** Set system prompt. */
+    system(prompt) {
+        this.sysPrompt = prompt;
+        return this;
+    }
+    /** Set number of chunks to retrieve. */
+    topK(n) {
+        this.retrieveOptions = { ...this.retrieveOptions, topK: n };
+        return this;
+    }
+    /** Set minimum relevance score threshold. */
+    minScore(score) {
+        this.retrieveOptions = { ...this.retrieveOptions, minScore: score };
+        return this;
+    }
+    /** Enable token-by-token streaming for the LLM call. */
+    streaming(enabled) {
+        this.enableStreaming = enabled;
+        return this;
+    }
+    /** Attach an AgentRecorder to observe execution events. */
+    recorder(rec) {
+        this.recorders.push(rec);
+        return this;
+    }
+    /** Build the RAG pipeline and return a runner. */
+    build() {
+        return new RAGRunner(this.provider, this.retriever, this.sysPrompt, this.retrieveOptions, [...this.recorders], this.enableStreaming);
+    }
+}
+exports.RAG = RAG;
+class RAGRunner {
+    provider;
+    retriever;
+    sysPrompt;
+    retrieveOptions;
+    recorders;
+    lastExecutor;
+    lastSpec;
+    streamingEnabled;
+    constructor(provider, retriever, sysPrompt, retrieveOptions, recorders = [], streaming = false) {
+        this.provider = provider;
+        this.retriever = retriever;
+        this.sysPrompt = sysPrompt;
+        this.retrieveOptions = retrieveOptions;
+        this.recorders = recorders;
+        this.streamingEnabled = streaming;
+    }
+    /** Expose the internal flowChart for subflow composition. */
+    toFlowChart() {
+        return this.buildChart('');
+    }
+    async run(message, options) {
+        const chart = this.buildChart(message);
+        const bridge = this.recorders.length > 0 ? new RecorderBridge_1.RecorderBridge(this.recorders) : null;
+        bridge?.dispatchTurnStart(message);
+        const executorOpts = { enrichSnapshots: true };
+        if (options?.onToken && this.streamingEnabled) {
+            executorOpts.streamHandlers = {
+                onToken: (_streamId, token) => options.onToken(token),
+                onStart: () => { },
+                onEnd: () => { },
+            };
+        }
+        const executor = new footprintjs_1.FlowChartExecutor(chart, executorOpts);
+        executor.enableNarrative();
+        executor.attachRecorder(new footprintjs_1.MetricRecorder('metrics'));
+        const startMs = Date.now();
+        try {
+            await executor.run({
+                input: { message },
+                signal: options?.signal,
+                timeoutMs: options?.timeoutMs,
+            });
+        }
+        catch (err) {
+            bridge?.dispatchError('llm', err);
+            throw err;
+        }
+        this.lastExecutor = executor;
+        const snapshot = executor.getSnapshot();
+        const state = snapshot?.sharedState ?? {};
+        const messages = state.messages ?? [];
+        const lastAsst = (0, memory_1.lastAssistantMessage)(messages);
+        const content = state.result ?? (lastAsst ? (0, content_1.getTextContent)(lastAsst.content) : '');
+        const retrievalResult = state.retrievalResult;
+        if (bridge) {
+            const response = state.adapterRawResponse;
+            if (response) {
+                bridge.dispatchLLMCall(response, Date.now() - startMs);
+            }
+            bridge.dispatchTurnComplete(content, messages.length);
+        }
+        return {
+            content,
+            messages,
+            chunks: retrievalResult?.chunks ?? [],
+            query: retrievalResult?.query ?? message,
+        };
+    }
+    buildChart(message) {
+        const sysPrompt = this.sysPrompt;
+        // API slot: SystemPrompt — set the system instruction
+        const systemPromptStage = (scope) => {
+            if (sysPrompt) {
+                scope.systemPrompt = sysPrompt;
+            }
+        };
+        // API slot: Messages — prepare the conversation messages
+        const messagesStage = (scope) => {
+            const msgs = [];
+            const sp = scope.systemPrompt;
+            if (sp)
+                msgs.push((0, types_1.systemMessage)(sp));
+            msgs.push((0, types_1.userMessage)(message));
+            scope.messages = msgs;
+        };
+        const retrieve = (0, retrieve_1.createRetrieveStage)(this.retriever, this.retrieveOptions);
+        const callLLM = (0, callLLM_1.createCallLLMStage)(this.provider);
+        let builder = (0, footprintjs_1.flowChart)('SystemPrompt', systemPromptStage, 'system-prompt')
+            .addFunction('Messages', messagesStage, 'messages')
+            .addFunction('Retrieve', retrieve, 'retrieve')
+            .addFunction('AugmentPrompt', augmentPrompt_1.augmentPromptStage, 'augment-prompt');
+        if (this.streamingEnabled) {
+            builder = builder.addStreamingFunction('CallLLM', callLLM, 'call-llm', 'llm-stream');
+        }
+        else {
+            builder = builder.addFunction('CallLLM', callLLM, 'call-llm');
+        }
+        builder = builder
+            .addFunction('ParseResponse', parseResponse_1.parseResponseStage, 'parse-response')
+            .addFunction('Finalize', finalize_1.finalizeStage, 'finalize');
+        this.lastSpec = (0, specIcons_1.annotateSpecIcons)(builder.toSpec());
+        return builder.build();
+    }
+    /** Get the flowchart spec (stage graph metadata). */
+    getSpec() {
+        if (!this.lastSpec) {
+            this.buildChart('');
+        }
+        return this.lastSpec;
+    }
+    /** Get the narrative from the last run. */
+    getNarrative() {
+        return this.lastExecutor?.getNarrative() ?? [];
+    }
+    /** Get structured narrative entries from the last run. */
+    getNarrativeEntries() {
+        return this.lastExecutor?.getNarrativeEntries() ?? [];
+    }
+    /** Get the full execution snapshot from the last run. */
+    getSnapshot() {
+        return this.lastExecutor?.getSnapshot();
+    }
+}
+exports.RAGRunner = RAGRunner;
+//# sourceMappingURL=RAG.js.map

package/dist/concepts/RAG.js.map

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