@noetic-tools/core 0.0.1

package/dist/builders/memory-builder.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryConfig, MemoryLayer } from '../types/memory';
+/**
+ * Creates a type-safe memory configuration from a tuple of memory layers.
+ * The returned config preserves literal layer types for compile-time inference
+ * via `InferMemory<typeof config>`.
+ *
+ * @public
+ * @param layers - Tuple of memory layers to include in the configuration.
+ * @returns A `MemoryConfig` carrying the inferred memory shape as a phantom type.
+ */
+export declare function memory<const T extends readonly MemoryLayer[]>(layers: T): MemoryConfig<T>;

package/dist/builders/memory-builder.js

@@ -0,0 +1,15 @@
+import { frameworkCast } from '../interpreter/framework-cast';
+/**
+ * Creates a type-safe memory configuration from a tuple of memory layers.
+ * The returned config preserves literal layer types for compile-time inference
+ * via `InferMemory<typeof config>`.
+ *
+ * @public
+ * @param layers - Tuple of memory layers to include in the configuration.
+ * @returns A `MemoryConfig` carrying the inferred memory shape as a phantom type.
+ */
+export function memory(layers) {
+    return frameworkCast({
+        layers,
+    });
+}

package/dist/builders/provide-builder.d.ts

@@ -0,0 +1,20 @@
+import type { ContextMemory, MemoryConfig, MemoryLayer } from '../types/memory';
+import type { Step, StepProvide } from '../types/step';
+/**
+ * Creates a provide step that attaches memory layers to its child without creating an isolated context.
+ * Like React's Context.Provider — layers are available to all descendant steps.
+ * Spawn and detachedSpawn break the inheritance chain.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.child - Step to execute with the provided layers.
+ * @param opts.memory - Memory layers to provide to descendant steps.
+ * @returns A `StepProvide` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ */
+export declare function provide<TMemory = ContextMemory, I = unknown, O = unknown>(opts: {
+    id: string;
+    child: Step<TMemory, I, O>;
+    memory: MemoryConfig | MemoryLayer[];
+}): StepProvide<TMemory, I, O>;

package/dist/builders/provide-builder.js

@@ -0,0 +1,34 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+/**
+ * Creates a provide step that attaches memory layers to its child without creating an isolated context.
+ * Like React's Context.Provider — layers are available to all descendant steps.
+ * Spawn and detachedSpawn break the inheritance chain.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.child - Step to execute with the provided layers.
+ * @param opts.memory - Memory layers to provide to descendant steps.
+ * @returns A `StepProvide` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ */
+export function provide(opts) {
+    if (!opts.id?.trim()) {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'provide() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. provide({ id: "my-provider", ... }).',
+        });
+    }
+    if (!opts.child) {
+        throw new NoeticConfigError({
+            code: 'MISSING_CHILD_STEP',
+            message: 'provide() requires a child step.',
+            hint: 'Provide a child step to execute with the provided memory layers.',
+        });
+    }
+    return {
+        kind: 'provide',
+        ...opts,
+    };
+}

package/dist/builders/spawn-builder.d.ts

@@ -0,0 +1,20 @@
+import type { ContextMemory, MemoryConfig, MemoryLayer } from '../types/memory';
+import type { Step, StepSpawn } from '../types/step';
+/**
+ * Creates a spawn step that executes a child step in an isolated context boundary.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.child - Step to execute in the isolated child context.
+ * @param opts.memory - Optional memory config or layers for the child context (replaces parent layers entirely).
+ * @param opts.timeout - Optional execution timeout in ms; the child is aborted if it exceeds this.
+ * @returns A `StepSpawn` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ */
+export declare function spawn<TMemory = ContextMemory, I = unknown, O = unknown>(opts: {
+    id: string;
+    child: Step<TMemory, I, O>;
+    memory?: MemoryConfig | MemoryLayer[];
+    timeout?: number;
+}): StepSpawn<TMemory, I, O>;

package/dist/builders/spawn-builder.js

@@ -0,0 +1,33 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+/**
+ * Creates a spawn step that executes a child step in an isolated context boundary.
+ *
+ * @public
+ * @param opts.id - Unique step identifier used in traces and error messages.
+ * @param opts.child - Step to execute in the isolated child context.
+ * @param opts.memory - Optional memory config or layers for the child context (replaces parent layers entirely).
+ * @param opts.timeout - Optional execution timeout in ms; the child is aborted if it exceeds this.
+ * @returns A `StepSpawn` step.
+ * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+ * @throws `NoeticConfigError` with code `MISSING_CHILD_STEP` if `child` is not provided.
+ */
+export function spawn(opts) {
+    if (!opts.id?.trim()) {
+        throw new NoeticConfigError({
+            code: 'EMPTY_STEP_ID',
+            message: 'spawn() requires a non-empty id.',
+            hint: 'Pass a unique string as the id field, e.g. spawn({ id: "my-spawn", ... }).',
+        });
+    }
+    if (!opts.child) {
+        throw new NoeticConfigError({
+            code: 'MISSING_CHILD_STEP',
+            message: 'spawn() requires a child step.',
+            hint: 'Provide a child step to execute in the isolated child context.',
+        });
+    }
+    return {
+        kind: 'spawn',
+        ...opts,
+    };
+}

package/dist/builders/step-builders.d.ts

@@ -0,0 +1,62 @@
+import type { ZodType } from 'zod';
+import type { ModelParams, RetryPolicy, Tool } from '../types/common';
+import type { Context } from '../types/context';
+import type { ContextMemory } from '../types/memory';
+import type { StepLLM, StepRun, StepTool } from '../types/step';
+export declare const step: {
+    /**
+     * Creates a pure async computation step.
+     *
+     * @public
+     * @param opts.id - Unique step identifier used in traces and error messages.
+     * @param opts.execute - Async function `(input, ctx) => output` that performs the work.
+     * @param opts.retry - Optional retry policy controlling attempts, backoff, and delay.
+     * @returns A `StepRun` that can be composed into larger pipelines.
+     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+     * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
+     */
+    run<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: {
+        id: string;
+        execute: (input: I, ctx: Context<TMemory>) => Promise<O>;
+        retry?: RetryPolicy;
+    }): StepRun<TMemory, I, O>;
+    /**
+     * Creates an LLM model call step with optional tools and structured output.
+     *
+     * @public
+     * @param opts.id - Unique step identifier used in traces and error messages.
+     * @param opts.model - Model identifier string (e.g. `'anthropic/claude-sonnet-4-20250514'`).
+     * @param opts.instructions - Optional system prompt / instructions for the model.
+     * @param opts.tools - Optional tools available to the model during this call.
+     * @param opts.output - Optional Zod schema enabling structured output parsing.
+     * @param opts.params - Optional model parameters (temperature, topP, maxTokens, stopSequences).
+     * @returns A `StepLLM` that can be composed into larger pipelines.
+     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+     * @throws `NoeticConfigError` with code `MISSING_MODEL` if `model` is empty.
+     */
+    llm<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: {
+        id: string;
+        model: string;
+        instructions?: string;
+        tools?: Tool[];
+        output?: ZodType<O>;
+        params?: ModelParams;
+        emit?: boolean | ((eventType: string, data: Record<string, unknown>) => boolean);
+    }): StepLLM<TMemory, I, O>;
+    /**
+     * Creates a tool execution step that invokes a typed tool definition.
+     *
+     * @public
+     * @param opts.id - Unique step identifier used in traces and error messages.
+     * @param opts.tool - The tool definition with typed input/output schemas.
+     * @param opts.args - Optional partial args that override or supplement LLM-provided arguments.
+     * @returns A `StepTool` that can be composed into larger pipelines.
+     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+     * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
+     */
+    tool<TMemory = Readonly<Record<string, Record<string, unknown>>>, I = unknown, O = unknown>(opts: {
+        id: string;
+        tool: Tool<ZodType<I>, ZodType<O>>;
+        args?: Partial<I>;
+    }): StepTool<TMemory, I, O>;
+};

package/dist/builders/step-builders.js

@@ -0,0 +1,99 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+export const step = {
+    /**
+     * Creates a pure async computation step.
+     *
+     * @public
+     * @param opts.id - Unique step identifier used in traces and error messages.
+     * @param opts.execute - Async function `(input, ctx) => output` that performs the work.
+     * @param opts.retry - Optional retry policy controlling attempts, backoff, and delay.
+     * @returns A `StepRun` that can be composed into larger pipelines.
+     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+     * @throws `NoeticConfigError` with code `MISSING_EXECUTE_FUNCTION` if `execute` is not provided.
+     */
+    run(opts) {
+        if (!opts.id || opts.id.trim() === '') {
+            throw new NoeticConfigError({
+                code: 'EMPTY_STEP_ID',
+                message: 'step.run() requires a non-empty id.',
+                hint: 'Pass a unique string as the id field, e.g. step.run({ id: "my-step", ... }).',
+            });
+        }
+        if (!opts.execute) {
+            throw new NoeticConfigError({
+                code: 'MISSING_EXECUTE_FUNCTION',
+                message: 'step.run() requires an execute function.',
+                hint: 'Provide an async execute function, e.g. execute: async (input, ctx) => result.',
+            });
+        }
+        return {
+            kind: 'run',
+            ...opts,
+        };
+    },
+    /**
+     * Creates an LLM model call step with optional tools and structured output.
+     *
+     * @public
+     * @param opts.id - Unique step identifier used in traces and error messages.
+     * @param opts.model - Model identifier string (e.g. `'anthropic/claude-sonnet-4-20250514'`).
+     * @param opts.instructions - Optional system prompt / instructions for the model.
+     * @param opts.tools - Optional tools available to the model during this call.
+     * @param opts.output - Optional Zod schema enabling structured output parsing.
+     * @param opts.params - Optional model parameters (temperature, topP, maxTokens, stopSequences).
+     * @returns A `StepLLM` that can be composed into larger pipelines.
+     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+     * @throws `NoeticConfigError` with code `MISSING_MODEL` if `model` is empty.
+     */
+    llm(opts) {
+        if (!opts.id || opts.id.trim() === '') {
+            throw new NoeticConfigError({
+                code: 'EMPTY_STEP_ID',
+                message: 'step.llm() requires a non-empty id.',
+                hint: 'Pass a unique string as the id field, e.g. step.llm({ id: "my-llm", ... }).',
+            });
+        }
+        if (!opts.model || opts.model.trim() === '') {
+            throw new NoeticConfigError({
+                code: 'MISSING_MODEL',
+                message: 'step.llm() requires a non-empty model.',
+                hint: "Pass a model identifier, e.g. model: 'anthropic/claude-sonnet-4-20250514'.",
+            });
+        }
+        return {
+            kind: 'llm',
+            ...opts,
+        };
+    },
+    /**
+     * Creates a tool execution step that invokes a typed tool definition.
+     *
+     * @public
+     * @param opts.id - Unique step identifier used in traces and error messages.
+     * @param opts.tool - The tool definition with typed input/output schemas.
+     * @param opts.args - Optional partial args that override or supplement LLM-provided arguments.
+     * @returns A `StepTool` that can be composed into larger pipelines.
+     * @throws `NoeticConfigError` with code `EMPTY_STEP_ID` if `id` is empty.
+     * @throws `NoeticConfigError` with code `MISSING_TOOL` if `tool` is not provided.
+     */
+    tool(opts) {
+        if (!opts.id || opts.id.trim() === '') {
+            throw new NoeticConfigError({
+                code: 'EMPTY_STEP_ID',
+                message: 'step.tool() requires a non-empty id.',
+                hint: 'Pass a unique string as the id field, e.g. step.tool({ id: "my-tool", ... }).',
+            });
+        }
+        if (!opts.tool) {
+            throw new NoeticConfigError({
+                code: 'MISSING_TOOL',
+                message: 'step.tool() requires a tool.',
+                hint: 'Provide a tool definition created with the tool() builder.',
+            });
+        }
+        return {
+            kind: 'tool',
+            ...opts,
+        };
+    },
+};

package/dist/builders/tool-builder.d.ts

@@ -0,0 +1,52 @@
+import type { ZodTypeAny, z } from 'zod';
+import type { Tool } from '../types/common';
+import type { FunctionCallItem, FunctionCallOutputItem, Item, ItemSchemaExtensions, ToolResultExtensionItem } from '../types/items';
+import type { ToolExecutionContext } from '../types/tool-context';
+interface ToolConfig<I extends ZodTypeAny, O extends ZodTypeAny> {
+    name: string;
+    description: string;
+    input: I;
+    output: O;
+    itemSchemas?: Pick<ItemSchemaExtensions, 'toolCalls' | 'toolResults' | 'items'>;
+    decorateResultItem?: (params: {
+        baseItem: FunctionCallOutputItem;
+        callItem: FunctionCallItem;
+        args: z.infer<I>;
+        result: z.infer<O> | undefined;
+        output: string;
+        error?: boolean;
+    }) => Item | ToolResultExtensionItem;
+    execute: (args: z.infer<I>, toolCtx: ToolExecutionContext) => Promise<z.infer<O>>;
+    needsApproval?: boolean;
+}
+interface GeneratorToolConfig<I extends ZodTypeAny, E extends ZodTypeAny, O extends ZodTypeAny> {
+    name: string;
+    description: string;
+    input: I;
+    event: E;
+    output: O;
+    itemSchemas?: Pick<ItemSchemaExtensions, 'toolCalls' | 'toolResults' | 'items'>;
+    decorateResultItem?: (params: {
+        baseItem: FunctionCallOutputItem;
+        callItem: FunctionCallItem;
+        args: z.infer<I>;
+        result: z.infer<O> | undefined;
+        output: string;
+        error?: boolean;
+    }) => Item | ToolResultExtensionItem;
+    execute: (args: z.infer<I>, toolCtx: ToolExecutionContext) => AsyncGenerator<z.infer<E>, z.infer<O>>;
+    needsApproval?: boolean;
+}
+/**
+ * Creates a typed Tool with Zod schema inference for input and output.
+ *
+ * @public
+ */
+export declare function tool<I extends ZodTypeAny, O extends ZodTypeAny>(config: ToolConfig<I, O>): Tool<I, O>;
+/**
+ * Creates a typed Tool that can stream progress events before returning a final output.
+ *
+ * @public
+ */
+export declare function toolWithGenerator<I extends ZodTypeAny, E extends ZodTypeAny, O extends ZodTypeAny>(config: GeneratorToolConfig<I, E, O>): Tool<I, O>;
+export {};

package/dist/builders/tool-builder.js

@@ -0,0 +1,59 @@
+import { NoeticConfigError } from '../errors/noetic-config-error';
+//#endregion
+//#region Helpers
+function validateToolConfig(name, execute) {
+    if (!name || name.trim() === '') {
+        throw new NoeticConfigError({
+            code: 'EMPTY_TOOL_NAME',
+            message: 'tool() requires a non-empty name.',
+            hint: "Pass a unique name for the tool, e.g. tool({ name: 'greet', ... }).",
+        });
+    }
+    if (!execute) {
+        throw new NoeticConfigError({
+            code: 'MISSING_EXECUTE_FUNCTION',
+            message: 'tool() requires an execute function.',
+            hint: 'Provide an async execute function, e.g. execute: async (args, toolCtx) => result.',
+        });
+    }
+}
+//#endregion
+//#region Public API
+/**
+ * Creates a typed Tool with Zod schema inference for input and output.
+ *
+ * @public
+ */
+export function tool(config) {
+    validateToolConfig(config.name, config.execute);
+    return {
+        name: config.name,
+        description: config.description,
+        input: config.input,
+        output: config.output,
+        itemSchemas: config.itemSchemas,
+        decorateResultItem: config.decorateResultItem,
+        execute: config.execute,
+        needsApproval: config.needsApproval,
+    };
+}
+/**
+ * Creates a typed Tool that can stream progress events before returning a final output.
+ *
+ * @public
+ */
+export function toolWithGenerator(config) {
+    validateToolConfig(config.name, config.execute);
+    return {
+        name: config.name,
+        description: config.description,
+        input: config.input,
+        event: config.event,
+        output: config.output,
+        itemSchemas: config.itemSchemas,
+        decorateResultItem: config.decorateResultItem,
+        execute: config.execute,
+        needsApproval: config.needsApproval,
+    };
+}
+//#endregion

package/dist/conditions/conditions.d.ts

@@ -0,0 +1,114 @@
+import type { Context } from '../types/context';
+import type { EmbedFn } from '../types/embed';
+import type { ContextMemory, StorageAdapter } from '../types/memory';
+import type { Step } from '../types/step';
+export type Condition<I> = (input: I, ctx: Context) => Promise<boolean>;
+export interface WhenClause<TMemory = ContextMemory, I = unknown, O = unknown> {
+    readonly kind: 'when';
+    readonly condition: Condition<I>;
+    readonly step: Step<TMemory, I, O>;
+}
+export interface OtherwiseClause<TMemory = ContextMemory, I = unknown, O = unknown> {
+    readonly kind: 'otherwise';
+    readonly step: Step<TMemory, I, O>;
+}
+type Clause<TMemory, I, O> = WhenClause<TMemory, I, O> | OtherwiseClause<TMemory, I, O>;
+/**
+ * Creates a conditional clause that routes to the given step when the condition is true.
+ *
+ * @public
+ * @param condition - Async predicate evaluated against the input and context.
+ * @param step - Step to execute when the condition matches.
+ * @returns A `WhenClause` for use in `semanticRoute`.
+ */
+export declare function when<TMemory = ContextMemory, I = unknown, O = unknown>(condition: Condition<I>, step: Step<TMemory, I, O>): WhenClause<TMemory, I, O>;
+/**
+ * Creates a fallback clause that always matches, used as the last clause in `semanticRoute`.
+ *
+ * @public
+ * @param step - Step to execute when no prior `when` clause matches.
+ * @returns An `OtherwiseClause` for use in `semanticRoute`.
+ */
+export declare function otherwise<TMemory = ContextMemory, I = unknown, O = unknown>(step: Step<TMemory, I, O>): OtherwiseClause<TMemory, I, O>;
+/**
+ * Builds a route function from an ordered list of `when`/`otherwise` clauses.
+ * Evaluates clauses sequentially, returning the first matching step or `null`.
+ *
+ * @public
+ * @param clauses - Ordered `WhenClause` and optional trailing `OtherwiseClause`.
+ * @returns A route function suitable for `branch({ route })`.
+ */
+export declare function semanticRoute<TMemory = ContextMemory, I = unknown, O = unknown>(...clauses: Clause<TMemory, I, O>[]): (input: I, ctx: Context) => Promise<Step<TMemory, I, O> | null>;
+interface SemanticSwitchSimple<TMemory, I, O> {
+    embed: EmbedFn;
+    cases: Record<string, Step<TMemory, I, O>>;
+    default?: Step<TMemory, I, O>;
+    threshold?: number;
+    cache?: StorageAdapter;
+}
+interface SemanticSwitchAdvanced<TMemory, I, O> {
+    embed: EmbedFn;
+    cases: {
+        labels: string | string[];
+        step: Step<TMemory, I, O>;
+    }[];
+    default?: Step<TMemory, I, O>;
+    threshold?: number;
+    cache?: StorageAdapter;
+}
+/**
+ * Builds a route function that selects the best-matching case via embedding cosine similarity.
+ *
+ * @public
+ * @param opts - Simple form with `Record<string, Step>` cases, or advanced form with multi-label cases.
+ * @returns A route function suitable for `branch({ route })`.
+ */
+export declare function semanticSwitch<TMemory = ContextMemory, I = unknown, O = unknown>(opts: SemanticSwitchSimple<TMemory, I, O>): (input: I, ctx: Context) => Promise<Step<TMemory, I, O> | null>;
+/** @public */
+export declare function semanticSwitch<TMemory = ContextMemory, I = unknown, O = unknown>(opts: SemanticSwitchAdvanced<TMemory, I, O>): (input: I, ctx: Context) => Promise<Step<TMemory, I, O> | null>;
+/**
+ * Creates a condition that matches when the input embedding is within a cosine similarity threshold of a label.
+ *
+ * @public
+ * @param embed - Embedding function or advanced options object.
+ * @param label - Label string (simple form).
+ * @param threshold - Minimum cosine similarity score to match.
+ * @returns A `Condition` usable in `when()` clauses.
+ */
+export declare function embeddingMatch<I>(embed: EmbedFn, label: string, threshold: number): Condition<I>;
+/** @public */
+export declare function embeddingMatch<I>(opts: {
+    embed: EmbedFn;
+    labels: string[];
+    threshold: number;
+    match?: 'any' | 'all';
+    cache?: StorageAdapter;
+}): Condition<I>;
+/**
+ * Combines conditions with OR semantics; returns true on the first truthy condition.
+ *
+ * @public
+ * @param conditions - Conditions to evaluate.
+ * @returns A `Condition` that short-circuits on the first match.
+ */
+export declare function anyCondition<I>(...conditions: Condition<I>[]): Condition<I>;
+/**
+ * Combines conditions with AND semantics; returns false on the first falsy condition.
+ *
+ * @public
+ * @param conditions - Conditions to evaluate.
+ * @returns A `Condition` that short-circuits on the first non-match.
+ */
+export declare function allCondition<I>(...conditions: Condition<I>[]): Condition<I>;
+/**
+ * Creates a condition that uses an LLM to classify the input as true or false.
+ *
+ * @public
+ * @param opts - Configuration with model identifier and classification prompt.
+ * @returns A `Condition` that delegates boolean classification to the model.
+ */
+export declare function aiCondition<I>(opts: {
+    model: string;
+    prompt: string;
+}): Condition<I>;
+export {};