@noetic-tools/core 5.3.0 → 5.4.0

package/dist/patterns/interview.js

@@ -1,113 +0,0 @@
-import { frameworkCast } from '@noetic-tools/types';
-import { z } from 'zod';
-import { loop } from '../builders/loop-builder.js';
-import { step } from '../builders/step-builders.js';
-import { any } from '../until/combinators.js';
-import { until } from '../until/predicates.js';
-//#endregion
-//#region Helpers
-const DEFAULT_MAX_QUESTIONS = 8;
-function defaultFormatAnswer(answer) {
-    return JSON.stringify({
-        questionId: answer.questionId,
-        question: answer.question,
-        answer: answer.answer,
-        notes: answer.notes,
-    });
-}
-function isCompleteIterState(value) {
-    if (typeof value !== 'object' || value === null) {
-        return false;
-    }
-    if (!('status' in value)) {
-        return false;
-    }
-    return value.status === 'complete';
-}
-function buildEnvelopeSchema(questionSchema, completeSchema) {
-    const schema = z.discriminatedUnion('type', [
-        z.object({
-            type: z.literal('question'),
-            data: questionSchema,
-        }),
-        z.object({
-            type: z.literal('complete'),
-            data: completeSchema,
-        }),
-    ]);
-    // ZodDiscriminatedUnion narrows to a non-generic ZodType<Envelope> shape, but
-    // step.llm's `output` field is typed as ZodType<O> for the generic O.
-    return frameworkCast(schema);
-}
-//#endregion
-//#region Public API
-/**
- * Creates a host-callback-driven structured interview pattern. Internally a loop over a single
- * body step that delegates to `step.llm` (with `output: discriminatedUnion('type', [...])`) and
- * then hands the envelope to the host. `askQuestion` renders questions and returns answers fed
- * back as the next user message; `onComplete` fires once when the model emits `complete`.
- * Termination via `until.verified(complete) || until.maxSteps(maxQuestions)`.
- *
- * @public
- * @param opts - System prompt, model, question/complete schemas, host callbacks, optional caps.
- * @returns A `Step` whose output is `InterviewResult<Q, C>` — either the completion envelope or
- *          `maxQuestions` when the budget is exhausted before the model emits `complete`.
- */
-export function interview(opts) {
-    const maxQuestions = opts.maxQuestions ?? DEFAULT_MAX_QUESTIONS;
-    const formatAnswer = opts.formatAnswer ?? defaultFormatAnswer;
-    const envelopeSchema = buildEnvelopeSchema(opts.questionSchema, opts.completeSchema);
-    const llmStep = step.llm({
-        id: 'interview-llm',
-        model: opts.model,
-        instructions: opts.systemPrompt,
-        output: envelopeSchema,
-    });
-    const turnStep = step.run({
-        id: 'interview-turn',
-        execute: async (input, ctx) => {
-            const envelope = await ctx.harness.run(llmStep, input, ctx);
-            if (envelope.type === 'complete') {
-                await opts.onComplete(envelope.data);
-                return {
-                    status: 'complete',
-                    envelope: envelope.data,
-                    nextInput: '',
-                };
-            }
-            const answer = await opts.askQuestion(envelope.data);
-            return {
-                status: 'inProgress',
-                lastQuestion: envelope.data,
-                nextInput: formatAnswer(answer),
-            };
-        },
-    });
-    const loopStep = loop({
-        id: 'interview-loop',
-        steps: [
-            turnStep,
-        ],
-        until: any(until.verified(async (out) => ({
-            pass: isCompleteIterState(out),
-        })), until.maxSteps(maxQuestions)),
-        prepareNext: (output) => output.nextInput,
-    });
-    return step.run({
-        id: 'interview',
-        execute: async (input, ctx) => {
-            const final = await ctx.harness.run(loopStep, input, ctx);
-            if (final.status === 'complete') {
-                return {
-                    status: 'complete',
-                    envelope: final.envelope,
-                };
-            }
-            return {
-                status: 'maxQuestions',
-                lastQuestion: final.lastQuestion,
-            };
-        },
-    });
-}
-//#endregion

package/dist/patterns/plans.d.ts

@@ -1,44 +0,0 @@
-import type { ContextData } from '@noetic-tools/context';
-import type { Context, ExecuteStepFn, Step } from '@noetic-tools/types';
-import { z } from 'zod';
-export interface PlanNode {
-    id: string;
-    description: string;
-    assignee: string;
-    execution: 'sequential' | 'parallel';
-    children?: PlanNode[];
-}
-/** @public Zod schema for recursive `PlanNode` validation. */
-export declare const PlanNodeSchema: z.ZodType<PlanNode>;
-export interface PlanConstraints {
-    toolAllowlist?: Record<string, string[]>;
-    maxStepsPerNode?: number;
-    requireApproval?: string[];
-    validate?: (taskId: string, input: unknown, ctx: Context) => Promise<boolean>;
-}
-/**
- * Compiles a `PlanNode` tree into an executable step graph using the provided agent factories.
- *
- * @public
- * @param plan - Root plan node describing the task tree.
- * @param agents - Map of agent names to factory functions producing steps.
- * @param constraints - Optional constraints for tool allowlists and approval.
- * @param executeStep - Optional step executor for non-run step kinds.
- * @returns A compiled `Step` ready for execution.
- */
-export declare function compilePlan<O, A = unknown>(plan: PlanNode, agents: Record<string, (prompt: string) => Step<ContextData, string, A>>, constraints?: PlanConstraints, executeStep?: ExecuteStepFn): Step<ContextData, string, O>;
-/**
- * Creates a step that dynamically generates a plan via a planner step and executes it,
- * retrying with error feedback up to `maxRevisions` times on failure.
- *
- * @public
- * @param opts - Planner step, agent factories, optional constraints, max revision count, and step executor.
- * @returns A `Step` that adaptively plans and executes.
- */
-export declare function adaptivePlan<O, A = unknown>(opts: {
-    planner: Step<ContextData, string, PlanNode>;
-    agents: Record<string, (prompt: string) => Step<ContextData, string, A>>;
-    constraints?: PlanConstraints;
-    maxRevisions: number;
-    executeStep?: ExecuteStepFn;
-}): Step<ContextData, string, O>;

package/dist/patterns/plans.js

@@ -1,125 +0,0 @@
-import { frameworkCast } from '@noetic-tools/types';
-import { z } from 'zod';
-import { fork } from '../builders/control-flow-builders.js';
-// PlanNode schema — the variable annotation provides the recursive type;
-// z.lazy() returns a compatible type that TypeScript checks against it.
-/** @public Zod schema for recursive `PlanNode` validation. */
-export const PlanNodeSchema = z.lazy(() => z.object({
-    id: z.string(),
-    description: z.string(),
-    assignee: z.string(),
-    execution: z.enum([
-        'sequential',
-        'parallel',
-    ]),
-    children: z.array(PlanNodeSchema).optional(),
-}));
-/**
- * Compiles a `PlanNode` tree into an executable step graph using the provided agent factories.
- *
- * @public
- * @param plan - Root plan node describing the task tree.
- * @param agents - Map of agent names to factory functions producing steps.
- * @param constraints - Optional constraints for tool allowlists and approval.
- * @param executeStep - Optional step executor for non-run step kinds.
- * @returns A compiled `Step` ready for execution.
- */
-export function compilePlan(plan, agents, constraints, executeStep) {
-    return frameworkCast(compileNode(plan, {
-        agents,
-        constraints,
-        executeStep,
-    }));
-}
-function compileNode(node, opts) {
-    const agentFactory = opts.agents[node.assignee];
-    if (!agentFactory) {
-        throw new Error(`Unknown agent: ${node.assignee}`);
-    }
-    // Leaf node - return the step directly from the factory
-    if (!node.children || node.children.length === 0) {
-        return agentFactory(node.description);
-    }
-    // Has children - compile them
-    const childSteps = node.children.map((child) => compileNode(child, opts));
-    if (node.execution === 'parallel') {
-        return fork({
-            id: `plan-fork-${node.id}`,
-            mode: 'all',
-            paths: () => childSteps,
-            merge: (results) => frameworkCast(results[results.length - 1]),
-        });
-    }
-    // Sequential - chain steps via a run step that uses executeStep
-    return {
-        kind: 'run',
-        id: `plan-seq-${node.id}`,
-        execute: async (input, ctx) => {
-            let currentOutput = input;
-            for (const child of childSteps) {
-                const childInput = typeof currentOutput === 'string' ? currentOutput : JSON.stringify(currentOutput);
-                if (opts.executeStep) {
-                    currentOutput = await opts.executeStep(child, childInput, ctx);
-                }
-                else if (child.kind === 'run') {
-                    currentOutput = await child.execute(childInput, ctx);
-                }
-                else {
-                    throw new Error(`No executeStep provided and child step kind '${child.kind}' cannot be executed directly`);
-                }
-            }
-            return frameworkCast(currentOutput);
-        },
-    };
-}
-/**
- * Creates a step that dynamically generates a plan via a planner step and executes it,
- * retrying with error feedback up to `maxRevisions` times on failure.
- *
- * @public
- * @param opts - Planner step, agent factories, optional constraints, max revision count, and step executor.
- * @returns A `Step` that adaptively plans and executes.
- */
-export function adaptivePlan(opts) {
-    return {
-        kind: 'run',
-        id: 'adaptive-plan',
-        execute: async (input, ctx) => {
-            let lastError = null;
-            for (let revision = 0; revision < opts.maxRevisions; revision++) {
-                // Generate plan
-                const planInput = lastError
-                    ? `${input}\n\nPrevious plan failed: ${lastError.message}`
-                    : input;
-                let plan;
-                if (opts.executeStep) {
-                    plan = PlanNodeSchema.parse(await opts.executeStep(opts.planner, planInput, ctx));
-                }
-                else if (opts.planner.kind === 'run') {
-                    plan = PlanNodeSchema.parse(await opts.planner.execute(planInput, ctx));
-                }
-                else {
-                    throw new Error('Planner must be a run step when no executeStep provided');
-                }
-                // Compile and execute
-                try {
-                    const compiled = compilePlan(plan, opts.agents, opts.constraints, opts.executeStep);
-                    if (opts.executeStep) {
-                        return frameworkCast(await opts.executeStep(compiled, input, ctx));
-                    }
-                    if (compiled.kind === 'run') {
-                        return frameworkCast(await compiled.execute(input, ctx));
-                    }
-                    throw new Error(`No executeStep provided and compiled plan kind '${compiled.kind}' cannot be executed directly`);
-                }
-                catch (e) {
-                    lastError = e instanceof Error ? e : new Error(String(e));
-                    if (revision === opts.maxRevisions - 1) {
-                        throw lastError;
-                    }
-                }
-            }
-            throw lastError;
-        },
-    };
-}

package/dist/patterns/ralph-wiggum.d.ts

@@ -1,19 +0,0 @@
-import type { ContextData } from '@noetic-tools/context';
-import type { StepLoop, Tool } from '@noetic-tools/types';
-import type { VerifyFn } from '../until/predicates.js';
-/**
- * Creates a retry-with-feedback loop wrapping a ReAct agent. Each iteration spawns an inner agent
- * and retries with verification feedback until the verifier passes or max iterations is reached.
- *
- * @public
- * @param opts - Model, tools, instructions, verify function, and optional iteration/step limits.
- * @returns A `StepLoop` that retries the inner agent with feedback.
- */
-export declare function ralphWiggum(opts: {
-    model: string;
-    instructions: string;
-    tools: Tool[];
-    verify: VerifyFn;
-    maxIterations?: number;
-    innerMaxSteps?: number;
-}): StepLoop<ContextData, string, string>;

package/dist/patterns/ralph-wiggum.js

@@ -1,37 +0,0 @@
-import { loop } from '../builders/loop-builder.js';
-import { spawn } from '../builders/spawn-builder.js';
-import { any } from '../until/combinators.js';
-import { until } from '../until/predicates.js';
-import { react } from './react.js';
-/**
- * Creates a retry-with-feedback loop wrapping a ReAct agent. Each iteration spawns an inner agent
- * and retries with verification feedback until the verifier passes or max iterations is reached.
- *
- * @public
- * @param opts - Model, tools, instructions, verify function, and optional iteration/step limits.
- * @returns A `StepLoop` that retries the inner agent with feedback.
- */
-export function ralphWiggum(opts) {
-    const inner = react({
-        model: opts.model,
-        instructions: opts.instructions,
-        tools: opts.tools,
-        maxSteps: opts.innerMaxSteps ?? 20,
-    });
-    return loop({
-        id: 'ralph-wiggum-loop',
-        steps: [
-            spawn({
-                id: 'ralph-iteration',
-                child: inner,
-            }),
-        ],
-        until: any(until.verified(opts.verify), until.maxSteps(opts.maxIterations ?? 50)),
-        prepareNext: (_output, verdict) => {
-            if (verdict.feedback) {
-                return `Previous attempt feedback: ${verdict.feedback}\nContinue working.`;
-            }
-            return 'Continue working on the task.';
-        },
-    });
-}

package/dist/patterns/react.d.ts

@@ -1,19 +0,0 @@
-import type { ContextConfig, ContextData, ContextLayer } from '@noetic-tools/context';
-import type { StepLoop, StepSpawn, Tool } from '@noetic-tools/types';
-/**
- * Creates a ReAct (Reason + Act) agent loop: an LLM step with tools iterated until no tool calls or limits are hit.
- *
- * @public
- * @param opts - Model, tools, optional instructions, step/cost limits, and context layers.
- * @returns A `StepLoop` (no context layers) or `StepSpawn` wrapping a loop (with them).
- */
-export declare function react(opts: {
-    model: string;
-    instructions?: string;
-    tools: Tool[];
-    maxSteps?: number;
-    maxCost?: number;
-    context?: ContextConfig | ContextLayer[];
-    /** @deprecated Renamed to `context`. */
-    memory?: ContextConfig | ContextLayer[];
-}): StepLoop<ContextData, string, string> | StepSpawn<ContextData, string, string>;

package/dist/patterns/react.js

@@ -1,41 +0,0 @@
-import { resolveContextOption } from '../builders/context-option.js';
-import { loop } from '../builders/loop-builder.js';
-import { spawn } from '../builders/spawn-builder.js';
-import { step } from '../builders/step-builders.js';
-import { any } from '../until/combinators.js';
-import { until } from '../until/predicates.js';
-/**
- * Creates a ReAct (Reason + Act) agent loop: an LLM step with tools iterated until no tool calls or limits are hit.
- *
- * @public
- * @param opts - Model, tools, optional instructions, step/cost limits, and context layers.
- * @returns A `StepLoop` (no context layers) or `StepSpawn` wrapping a loop (with them).
- */
-export function react(opts) {
-    const llmStep = step.llm({
-        id: 'react-step',
-        model: opts.model,
-        instructions: opts.instructions,
-        tools: opts.tools,
-    });
-    const loopStep = loop({
-        id: 'react-loop',
-        steps: [
-            llmStep,
-        ],
-        until: any(until.noToolCalls(), until.maxSteps(opts.maxSteps ?? 10), ...(opts.maxCost
-            ? [
-                until.maxCost(opts.maxCost),
-            ]
-            : [])),
-    });
-    const layers = resolveContextOption(opts);
-    if (!layers) {
-        return loopStep;
-    }
-    return spawn({
-        id: 'react-agent',
-        child: loopStep,
-        context: layers,
-    });
-}