@limo-labs/deity 0.1.0-alpha.0

package/dist/src/runtime.js

@@ -0,0 +1,436 @@
+import { parseOutput } from "./parser.js";
+import { hashPrompt } from "./json-store.js";
+import { InMemoryConversationStore } from "./conversation/in-memory-conversation-store.js";
+/**
+ * Error thrown when a stage fails permanently (exhausts all retries).
+ */
+export class StageFailedError extends Error {
+    stageId;
+    errors;
+    constructor(stageId, errors) {
+        super(`Stage "${stageId}" failed: ${errors.join("; ")}`);
+        this.stageId = stageId;
+        this.errors = errors;
+        this.name = "StageFailedError";
+    }
+}
+/**
+ * Error thrown when a stage attempts to access another stage's output
+ * that is not in its declared scope.
+ *
+ * @since 2.0.0
+ */
+export class ScopeViolationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ScopeViolationError";
+    }
+}
+export { defineWorkflow } from "./workflow.js";
+/**
+ * Get the list of visible stages for a component based on its scope declaration.
+ * Returns "*" for wildcard access or an array of accessible stage IDs.
+ * Supports dynamic scopes that are computed based on inputs.
+ *
+ * @param component - The agent component to check
+ * @param inputs - The inputs to the current stage (for dynamic scopes)
+ * @returns "*" for full access, or string[] for limited visibility
+ * @since 2.0.0
+ */
+function getVisibleStages(component, inputs) {
+    // No scope = full access (backward compatibility)
+    if (!component.scope) {
+        return "*";
+    }
+    // Isolated = no dependencies
+    if (component.scope.isolated) {
+        return [];
+    }
+    // Use visibility if explicitly set
+    if (component.scope.visibility !== undefined) {
+        const visibility = component.scope.visibility;
+        // If visibility is a function, call it with inputs
+        if (typeof visibility === "function") {
+            return visibility(inputs);
+        }
+        return visibility;
+    }
+    // Default to full access
+    return "*";
+}
+/**
+ * Check if a stage ID is accessible based on visibility rules.
+ *
+ * @param stageId - The stage ID to check access for
+ * @param visibleStages - Visibility rules ("*" or string[])
+ * @returns true if accessible, false otherwise
+ * @since 2.0.0
+ */
+function isStageAccessible(stageId, visibleStages) {
+    if (visibleStages === "*") {
+        return true;
+    }
+    return visibleStages.includes(stageId);
+}
+/**
+ * Define a pipeline from config and stages.
+ *
+ * Creates a pipeline configuration that can be executed with runPipeline().
+ * Pipelines define a sequence of agent components (stages) that process data
+ * with automatic checkpointing, retry logic, and validation.
+ *
+ * @deprecated Use `defineWorkflow()` instead. This function will be removed in v3.0.0.
+ * See TERMINOLOGY.md for migration guide.
+ *
+ * @param options - Pipeline configuration and stages
+ * @returns Pipeline definition ready for execution
+ *
+ * @since 1.0.0
+ */
+export function definePipeline(options) {
+    const { stages, ...config } = options;
+    return { config, stages };
+}
+/**
+ * Execute multiple promises with concurrency limit.
+ *
+ * @param items - Array of items to process
+ * @param limit - Maximum number of concurrent executions
+ * @param fn - Async function to execute for each item
+ * @returns Array of results in the same order as items
+ */
+async function mapWithConcurrency(items, limit, fn) {
+    const results = new Array(items.length);
+    let currentIndex = 0;
+    const executeNext = async () => {
+        const index = currentIndex++;
+        if (index >= items.length) {
+            return;
+        }
+        results[index] = await fn(items[index]);
+        await executeNext();
+    };
+    const workers = Array.from({ length: Math.min(limit, items.length) }, () => executeNext());
+    await Promise.all(workers);
+    return results;
+}
+/**
+ * Execute multiple tool calls with concurrency control.
+ *
+ * All tool calls are considered independent and executed in parallel up to
+ * the concurrency limit.
+ *
+ * @param toolCalls - Tool calls to execute
+ * @param tools - Available tools
+ * @param stageId - Current stage ID for logging
+ * @param trace - Trace logger
+ * @param conversation - Conversation manager
+ * @param concurrencyLimit - Maximum concurrent executions
+ * @returns Array of tool result messages
+ */
+async function executeToolCalls(toolCalls, tools, stageId, trace, conversation, concurrencyLimit) {
+    return mapWithConcurrency(toolCalls, concurrencyLimit, async (toolCall) => {
+        const tool = tools?.find((t) => t.name === toolCall.toolName);
+        if (!tool) {
+            trace.log({
+                stageId,
+                event: "tool_call",
+                data: { toolName: toolCall.toolName, error: "Tool not found" },
+            });
+            const toolMessage = {
+                role: "tool",
+                content: JSON.stringify({ error: `Tool "${toolCall.toolName}" not found` }),
+                toolCallId: toolCall.id,
+            };
+            await conversation.addMessage(toolMessage, { stageId });
+            return { toolCall, message: toolMessage };
+        }
+        trace.log({
+            stageId,
+            event: "tool_call",
+            data: { toolName: toolCall.toolName, arguments: toolCall.arguments },
+        });
+        try {
+            const startTime = Date.now();
+            const result = await tool.execute(toolCall.arguments);
+            const duration = Date.now() - startTime;
+            trace.log({
+                stageId,
+                event: "tool_result",
+                data: { toolName: toolCall.toolName, result, toolDuration: duration },
+            });
+            const toolMessage = {
+                role: "tool",
+                content: JSON.stringify(result),
+                toolCallId: toolCall.id,
+            };
+            await conversation.addMessage(toolMessage, { stageId });
+            return { toolCall, message: toolMessage };
+        }
+        catch (err) {
+            const errorMsg = err instanceof Error ? err.message : String(err);
+            trace.log({
+                stageId,
+                event: "tool_result",
+                data: { toolName: toolCall.toolName, error: errorMsg },
+            });
+            const toolMessage = {
+                role: "tool",
+                content: JSON.stringify({ error: errorMsg }),
+                toolCallId: toolCall.id,
+            };
+            await conversation.addMessage(toolMessage, { stageId });
+            return { toolCall, message: toolMessage };
+        }
+    });
+}
+/**
+ * Run the tool calling loop for a single stage execution.
+ * Manages the cycle: LLM request → tool calls → results → back to LLM.
+ * Automatically records all messages to the conversation manager.
+ *
+ * @since 2.0.0 (conversation parameter added)
+ */
+async function runToolLoop(adapter, messages, tools, config, maxRounds, trace, stageId, conversation, concurrencyLimit = Infinity) {
+    let currentMessages = [...messages];
+    let response;
+    // Record initial user/system messages from buildPrompt
+    // (only on first round, these are the prompt messages)
+    for (const msg of messages) {
+        await conversation.addMessage(msg, { stageId });
+    }
+    for (let round = 0; round < maxRounds; round++) {
+        trace.log({
+            stageId,
+            event: "llm_request",
+            data: { round, messageCount: currentMessages.length },
+        });
+        response = await adapter.generate(currentMessages, tools, config);
+        trace.log({
+            stageId,
+            event: "llm_response",
+            data: {
+                round,
+                contentLength: response.content.length,
+                toolCallCount: response.toolCalls?.length ?? 0,
+            },
+        });
+        // Record assistant response to conversation
+        await conversation.addMessage({
+            role: "assistant",
+            content: response.content,
+        }, { stageId });
+        // If no tool calls, we're done
+        if (!response.toolCalls || response.toolCalls.length === 0) {
+            return response;
+        }
+        // Execute tool calls in parallel with concurrency limit
+        const toolResults = await executeToolCalls(response.toolCalls, tools, stageId, trace, conversation, concurrencyLimit);
+        // Append tool result messages to conversation
+        for (const { message } of toolResults) {
+            currentMessages.push(message);
+        }
+        // Add assistant message with tool calls for conversation context
+        currentMessages.push({
+            role: "assistant",
+            content: response.content || "",
+        });
+    }
+    // If we exhausted rounds, return the last response
+    return response;
+}
+/**
+ * Execute a complete workflow.
+ * This is the core runtime loop that drives the entire framework.
+ *
+ * A workflow represents a single agent's deterministic execution through
+ * a sequence of steps, with automatic checkpointing, retry logic, and validation.
+ *
+ * @param workflow - Workflow definition with configuration and steps
+ * @param inputs - Input data for the workflow
+ * @param store - State storage for checkpoints
+ * @param trace - Trace logger for execution history
+ * @param conversation - Optional conversation manager (defaults to in-memory store)
+ * @param adapterOverride - Optional LLM adapter override
+ * @returns Record of all step outputs
+ *
+ * @since 2.0.0
+ *
+ * @example
+ * ```typescript
+ * import { runWorkflow, defineWorkflow } from '@limo-labs/deity';
+ *
+ * const workflow = defineWorkflow({
+ *   name: "research-workflow",
+ *   defaultModel: { adapter: llm },
+ *   steps: [ResearchStep, AnalysisStep, ReportStep]
+ * });
+ *
+ * const result = await runWorkflow(
+ *   workflow,
+ *   { topic: "AI agents" },
+ *   store,
+ *   trace
+ * );
+ * ```
+ */
+export async function runWorkflow(workflow, inputs, store, trace, conversation, adapterOverride) {
+    const adapter = adapterOverride ?? workflow.config.defaultModel?.adapter;
+    if (!adapter) {
+        throw new Error("No LLM adapter provided. Set defaultModel in workflow config or pass adapterOverride.");
+    }
+    const defaultConfig = workflow.config.defaultModel?.config;
+    const maxToolRounds = workflow.config.maxToolRounds ?? 10;
+    const onFailure = workflow.config.onStageFailure ?? "abort";
+    const parallelToolConcurrency = workflow.config.parallelToolConcurrency ?? Infinity;
+    // Create default conversation manager if not provided
+    const conversationManager = conversation ?? new InMemoryConversationStore();
+    const outputs = {};
+    // Load existing completed outputs for resume
+    const existingRecords = await store.loadAll();
+    for (const [id, record] of Object.entries(existingRecords)) {
+        if (record.status === "completed") {
+            outputs[id] = record.output;
+        }
+    }
+    for (const stage of workflow.steps) {
+        // Determine visibility based on component scope declaration (supports dynamic scopes)
+        const visibleStages = getVisibleStages(stage, inputs);
+        // Build prompt to compute hash (needed for cache invalidation check)
+        const ctx = {
+            inputs,
+            previousOutputs: { ...outputs },
+            store,
+            trace,
+            conversation: conversationManager,
+            getOutput(stageId) {
+                // Check scope permissions before allowing access
+                if (!isStageAccessible(stageId, visibleStages)) {
+                    throw new ScopeViolationError(`Stage "${stage.id}" cannot access output from "${stageId}". ` +
+                        `Visible stages: ${visibleStages === "*" ? "all" : visibleStages.join(", ")}`);
+                }
+                if (!(stageId in outputs)) {
+                    throw new Error(`Stage "${stageId}" has not completed yet.`);
+                }
+                return outputs[stageId];
+            },
+        };
+        const promptMessages = await Promise.resolve(stage.buildPrompt(ctx));
+        const currentPromptHash = hashPrompt(promptMessages);
+        // Check for valid checkpoint (skip if completed with same prompt hash)
+        if (await store.hasValidCheckpoint(stage.id, currentPromptHash)) {
+            const cached = await store.load(stage.id);
+            outputs[stage.id] = cached;
+            trace.log({
+                stageId: stage.id,
+                event: "stage_complete",
+                data: { cached: true },
+            });
+            continue;
+        }
+        // Clear any stale checkpoint
+        await store.clear(stage.id);
+        trace.log({ stageId: stage.id, event: "stage_start" });
+        const maxAttempts = stage.retry?.maxAttempts ?? 0;
+        let lastErrors = [];
+        let stageCompleted = false;
+        const allToolCalls = [];
+        for (let attempt = 0; attempt <= maxAttempts; attempt++) {
+            const messages = [...promptMessages];
+            // On retry, inject validation errors for self-correction
+            if (attempt > 0 && stage.retry?.feedbackOnError !== false) {
+                trace.log({
+                    stageId: stage.id,
+                    event: "retry",
+                    data: { attempt, errors: lastErrors },
+                });
+                messages.push({
+                    role: "user",
+                    content: `Previous attempt failed validation:\n${lastErrors.join("\n")}\nPlease correct your output.`,
+                });
+            }
+            // Run tool calling loop
+            const raw = await runToolLoop(adapter, messages, stage.tools, defaultConfig, maxToolRounds, trace, stage.id, conversationManager, parallelToolConcurrency);
+            // Parse output
+            const parsed = parseOutput(raw, stage.outputSchema);
+            if (!parsed.success) {
+                trace.log({
+                    stageId: stage.id,
+                    event: "parse_error",
+                    data: { error: parsed.error, attempt },
+                });
+                lastErrors = [parsed.error];
+                continue;
+            }
+            // Validate output (semantic validation)
+            const validation = stage.validate(parsed.data, ctx);
+            if (validation.valid) {
+                trace.log({
+                    stageId: stage.id,
+                    event: "validation_pass",
+                    data: { attempt },
+                });
+                await store.save(stage.id, parsed.data, {
+                    promptHash: currentPromptHash,
+                    modelName: undefined,
+                    generationConfig: defaultConfig,
+                    toolCalls: allToolCalls.length > 0 ? allToolCalls : undefined,
+                });
+                outputs[stage.id] = parsed.data;
+                stageCompleted = true;
+                trace.log({
+                    stageId: stage.id,
+                    event: "stage_complete",
+                    data: { cached: false, attempts: attempt + 1 },
+                });
+                break;
+            }
+            trace.log({
+                stageId: stage.id,
+                event: "validation_fail",
+                data: { errors: validation.errors, attempt },
+            });
+            lastErrors = validation.errors ?? ["Unknown validation error"];
+        }
+        if (!stageCompleted) {
+            await store.markFailed(stage.id, lastErrors, {
+                promptHash: currentPromptHash,
+            });
+            trace.log({
+                stageId: stage.id,
+                event: "stage_failed",
+                data: { errors: lastErrors },
+            });
+            if (onFailure === "abort") {
+                throw new StageFailedError(stage.id, lastErrors);
+            }
+            // "skip": continue to next stage
+        }
+    }
+    return outputs;
+}
+/**
+ * Execute a complete pipeline.
+ *
+ * @deprecated Use `runWorkflow()` instead. This function will be removed in v3.0.0.
+ * See TERMINOLOGY.md for migration guide.
+ *
+ * @param pipeline - Pipeline configuration
+ * @param inputs - Input data for the pipeline
+ * @param store - State storage for checkpoints
+ * @param trace - Trace logger for execution history
+ * @param conversation - Optional conversation manager
+ * @param adapterOverride - Optional LLM adapter override
+ * @returns Record of all stage outputs
+ *
+ * @since 1.0.0
+ */
+export async function runPipeline(pipeline, inputs, store, trace, conversation, adapterOverride) {
+    // Convert Pipeline to Workflow format
+    const workflow = {
+        config: pipeline.config,
+        steps: pipeline.stages,
+    };
+    return runWorkflow(workflow, inputs, store, trace, conversation, adapterOverride);
+}
+//# sourceMappingURL=runtime.js.map

package/dist/src/runtime.js.map

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

package/dist/src/schema-utils.d.ts

@@ -0,0 +1,7 @@
+import type { ZodSchema } from "zod";
+/**
+ * Convert a Zod schema to JSON Schema for LLM tool definitions.
+ * Uses Zod's built-in method if available, otherwise returns a minimal schema.
+ */
+export declare function zodToJsonSchema(schema: ZodSchema<any>): Record<string, unknown>;
+//# sourceMappingURL=schema-utils.d.ts.map

package/dist/src/schema-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-utils.d.ts","sourceRoot":"","sources":["../../src/schema-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AAErC;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAK/E"}

package/dist/src/schema-utils.js

@@ -0,0 +1,71 @@
+/**
+ * Convert a Zod schema to JSON Schema for LLM tool definitions.
+ * Uses Zod's built-in method if available, otherwise returns a minimal schema.
+ */
+export function zodToJsonSchema(schema) {
+    // Zod v3 doesn't have built-in JSON schema conversion,
+    // but the schema description can be extracted from _def.
+    // For MVP, we use a simple recursive converter.
+    return convertZodDef(schema._def);
+}
+function convertZodDef(def) {
+    if (!def)
+        return { type: "object" };
+    const typeName = def.typeName;
+    switch (typeName) {
+        case "ZodString":
+            return { type: "string" };
+        case "ZodNumber":
+            return { type: "number" };
+        case "ZodBoolean":
+            return { type: "boolean" };
+        case "ZodArray":
+            return {
+                type: "array",
+                items: convertZodDef(def.type?._def),
+            };
+        case "ZodObject": {
+            const properties = {};
+            const required = [];
+            const shape = def.shape?.();
+            if (shape) {
+                for (const [key, value] of Object.entries(shape)) {
+                    const fieldDef = value?._def;
+                    if (fieldDef?.typeName === "ZodOptional") {
+                        properties[key] = convertZodDef(fieldDef.innerType?._def);
+                    }
+                    else {
+                        properties[key] = convertZodDef(fieldDef);
+                        required.push(key);
+                    }
+                }
+            }
+            const result = { type: "object", properties };
+            if (required.length > 0)
+                result.required = required;
+            return result;
+        }
+        case "ZodOptional":
+            return convertZodDef(def.innerType?._def);
+        case "ZodEnum":
+            return { type: "string", enum: def.values };
+        case "ZodLiteral":
+            return { type: typeof def.value, const: def.value };
+        case "ZodRecord":
+            return {
+                type: "object",
+                additionalProperties: convertZodDef(def.valueType?._def),
+            };
+        case "ZodUnion": {
+            const options = def.options?.map((opt) => convertZodDef(opt._def));
+            return { oneOf: options ?? [] };
+        }
+        case "ZodNullable": {
+            const inner = convertZodDef(def.innerType?._def);
+            return { ...inner, nullable: true };
+        }
+        default:
+            return { type: "object" };
+    }
+}
+//# sourceMappingURL=schema-utils.js.map

package/dist/src/schema-utils.js.map

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

package/dist/src/stage.d.ts

@@ -0,0 +1,139 @@
+import type { ZodSchema } from "zod";
+import type { Message, ValidationResult } from "./component.js";
+import type { StateStore } from "./store.js";
+import type { TraceLogger } from "./trace.js";
+import type { Tool } from "./tool.js";
+import type { ConversationManager } from "./conversation/conversation-manager.js";
+/**
+ * Execution context passed to each component during stage execution.
+ *
+ * Provides access to inputs, stage outputs, storage, tracing, and conversation history.
+ *
+ * @since 1.0.0 (conversation field added in 2.0.0)
+ */
+export interface ExecutionContext<I = unknown> {
+    inputs: I;
+    previousOutputs: Record<string, unknown>;
+    store: StateStore;
+    trace: TraceLogger;
+    /**
+     * Conversation history manager.
+     *
+     * Provides access to the full conversation history for this pipeline execution.
+     * Components can use this to query past messages, add context-specific messages,
+     * or implement conversational logic.
+     *
+     * @since 2.0.0
+     *
+     * @example
+     * ```typescript
+     * buildPrompt(ctx: ExecutionContext<I>) {
+     *   // Get recent conversation history
+     *   const recent = await ctx.conversation.getRecent(10);
+     *
+     *   // Search for specific messages
+     *   const systemMessages = await ctx.conversation.search({
+     *     role: "system"
+     *   });
+     *
+     *   return [
+     *     ...systemMessages.map(m => m.message),
+     *     { role: "user", content: "Continue the conversation..." }
+     *   ];
+     * }
+     * ```
+     */
+    conversation: ConversationManager;
+    /**
+     * Type-safe accessor for a specific stage's output.
+     * Throws if the requested stage has not completed yet.
+     */
+    getOutput<T>(stageId: string): T;
+}
+/**
+ * AgentComponent is the atomic unit of work in the framework.
+ * Each component co-locates prompt, schema, validation, and retry policy.
+ */
+export interface AgentComponent<I = unknown, O = unknown> {
+    id: string;
+    inputSchema: ZodSchema<I>;
+    outputSchema: ZodSchema<O>;
+    buildPrompt(ctx: ExecutionContext<I>): Message[] | Promise<Message[]>;
+    tools?: Tool[];
+    validate(output: O, ctx: ExecutionContext<I>): ValidationResult;
+    retry?: {
+        maxAttempts: number;
+        /**
+         * When true (default), runtime automatically appends validation errors
+         * to the prompt on retry so the LLM can self-correct.
+         */
+        feedbackOnError?: boolean;
+    };
+    /**
+     * Optional scope declaration for access control.
+     * Controls which stage outputs this component can access.
+     *
+     * @since 2.0.0
+     *
+     * @example
+     * ```typescript
+     * // Full access (default when undefined)
+     * scope: undefined
+     *
+     * // Limited visibility - can only access Stage1 and Stage2
+     * scope: {
+     *   visibility: ["Stage1", "Stage2"]
+     * }
+     *
+     * // Read-only access - can see all but cannot modify
+     * scope: {
+     *   visibility: "*",
+     *   readonly: true
+     * }
+     *
+     * // Completely isolated - no dependencies
+     * scope: {
+     *   isolated: true
+     * }
+     *
+     * // Dynamic visibility based on inputs
+     * scope: {
+     *   visibility: (inputs) => inputs.useCache ? ["Stage1"] : ["Stage2"]
+     * }
+     *
+     * // Dynamic readonly based on inputs
+     * scope: {
+     *   visibility: "*",
+     *   readonly: (inputs) => inputs.mode === "readonly"
+     * }
+     * ```
+     */
+    scope?: {
+        /**
+         * Stage IDs this component can access.
+         * - `"*"`: Can access all stages (default behavior)
+         * - `string[]`: Can only access listed stages
+         * - `[]`: Isolated - no stage dependencies
+         * - `(inputs: I) => string[] | "*"`: Dynamic visibility based on inputs
+         *
+         * @default "*" (when undefined)
+         */
+        visibility?: string[] | "*" | ((inputs: I) => string[] | "*");
+        /**
+         * Whether this component can only read, not write.
+         * Useful for validation or analysis stages.
+         * Can be a boolean or a function that computes the readonly state based on inputs.
+         *
+         * @default false
+         */
+        readonly?: boolean | ((inputs: I) => boolean);
+        /**
+         * Whether this component is completely isolated (no dependencies).
+         * Equivalent to `visibility: []`.
+         *
+         * @default false
+         */
+        isolated?: boolean;
+    };
+}
+//# sourceMappingURL=stage.d.ts.map