@zhanla/sdk-ts 0.1.0

package/dist/executor.js

@@ -0,0 +1,564 @@
+/**
+ * Local execution engine for TypeScript SDK components.
+ * Mirrors the Python CLI executor's component-type dispatch semantics.
+ */
+import { parseJsonResponse } from "./json.js";
+const COMPONENT_ERROR_KEY = "_component_error";
+const OUTPUT_SCHEMA_MISMATCH_REASON = "Model response doesn't match the requested output schema.";
+const JSON_OUTPUT_ERROR_MARKERS = [
+    "unterminated string in json",
+    "unexpected end of json input",
+    "jsondecodeerror",
+    "expecting value",
+    "extra data",
+    "unexpected token",
+];
+function buildComponentFailureOutput(error) {
+    return { [COMPONENT_ERROR_KEY]: error };
+}
+function isOutputSchemaMismatchError(error) {
+    const normalized = error.toLowerCase();
+    return normalized.includes("output doesn't match declared output_schema")
+        || JSON_OUTPUT_ERROR_MARKERS.some((marker) => normalized.includes(marker));
+}
+function buildSchemaMismatchEvalOutput(error) {
+    return {
+        score: 0.0,
+        passed: false,
+        reason: OUTPUT_SCHEMA_MISMATCH_REASON,
+        output_schema_error: error,
+    };
+}
+// ---------------------------------------------------------------------------
+// Eval-input contract helpers
+// ---------------------------------------------------------------------------
+function stableStringify(value) {
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(",")}]`;
+    }
+    const obj = value;
+    const keys = Object.keys(obj).sort();
+    const parts = keys.map((key) => `${JSON.stringify(key)}:${stableStringify(obj[key])}`);
+    return `{${parts.join(",")}}`;
+}
+function stringifyValue(value) {
+    if (value == null) {
+        return "";
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    try {
+        return stableStringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+function deriveModelInput(row) {
+    if ("input" in row) {
+        return stringifyValue(row["input"]);
+    }
+    return stringifyValue(row);
+}
+function deriveExpectedOutput(row) {
+    if ("expected_output" in row) {
+        return stringifyValue(row["expected_output"]);
+    }
+    if ("output" in row) {
+        return stringifyValue(row["output"]);
+    }
+    return "";
+}
+function deriveModelResponse(output) {
+    const keys = Object.keys(output);
+    if (keys.length === 1 && keys[0] === "result") {
+        return stringifyValue(output["result"]);
+    }
+    if (keys.length === 1 && keys[0] === "output") {
+        return stringifyValue(output["output"]);
+    }
+    return stringifyValue(output);
+}
+// ---------------------------------------------------------------------------
+// Component execution dispatch
+// ---------------------------------------------------------------------------
+function isConditionalLike(value) {
+    return (value != null &&
+        typeof value === "object" &&
+        typeof value.condition === "function" &&
+        typeof value.ifTrue === "string" &&
+        typeof value.ifFalse === "string");
+}
+function isLeafLike(value) {
+    return (value != null &&
+        typeof value === "object" &&
+        "eval" in value &&
+        !("threshold" in value));
+}
+async function executeFn(fn, kwargs, isAsync) {
+    if (isAsync) {
+        return await fn(kwargs);
+    }
+    return fn(kwargs);
+}
+function stringifyLogValue(value) {
+    if (typeof value === "string")
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+async function captureConsoleLogs(fn) {
+    const logs = [];
+    const originals = {
+        log: console.log,
+        info: console.info,
+        warn: console.warn,
+        error: console.error,
+    };
+    const makeCapture = (stream) => (...args) => {
+        logs.push({
+            stream,
+            message: args.map(stringifyLogValue).join(" "),
+        });
+    };
+    console.log = makeCapture("stdout");
+    console.info = makeCapture("stdout");
+    console.warn = makeCapture("stderr");
+    console.error = makeCapture("stderr");
+    try {
+        return { value: await fn(), logs };
+    }
+    finally {
+        console.log = originals.log;
+        console.info = originals.info;
+        console.warn = originals.warn;
+        console.error = originals.error;
+    }
+}
+async function runTool(comp, kwargs) {
+    const result = await executeFn(comp.fn, kwargs, comp.isAsync);
+    if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+        return result;
+    }
+    return { result };
+}
+async function runCodeEval(comp, kwargs) {
+    const { value: result, logs } = await captureConsoleLogs(async () => executeFn(comp.fn, kwargs, comp.isAsync));
+    if (result !== null && typeof result === "object" && !Array.isArray(result)) {
+        return logs.length > 0
+            ? { ...result, logs }
+            : result;
+    }
+    return logs.length > 0 ? { score: result, logs } : { score: result };
+}
+async function runSkill(comp, _kwargs) {
+    throw new Error(`Skill '${comp.name}' is a non-executable configuration component and cannot execute locally.`);
+}
+function isJsonSchemaObject(schema) {
+    return schema != null && typeof schema === "object" && schema.type === "object";
+}
+function isJsonSchemaArray(schema) {
+    return schema != null && typeof schema === "object" && schema.type === "array";
+}
+function validateSchemaValue(value, schema, path = "$") {
+    if (schema == null || typeof schema !== "object") {
+        return [];
+    }
+    if (isJsonSchemaObject(schema)) {
+        if (value == null || typeof value !== "object" || Array.isArray(value)) {
+            return [`${path} must be an object`];
+        }
+        const obj = value;
+        const errors = [];
+        for (const key of schema.required ?? []) {
+            if (!(key in obj)) {
+                errors.push(`${path}.${key} is required`);
+            }
+        }
+        const properties = schema.properties ?? {};
+        for (const [key, propertySchema] of Object.entries(properties)) {
+            if (key in obj) {
+                errors.push(...validateSchemaValue(obj[key], propertySchema, `${path}.${key}`));
+            }
+        }
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(obj)) {
+                if (!(key in properties)) {
+                    errors.push(`${path}.${key} is not allowed`);
+                }
+            }
+        }
+        return errors;
+    }
+    if (isJsonSchemaArray(schema)) {
+        if (!Array.isArray(value)) {
+            return [`${path} must be an array`];
+        }
+        return value.flatMap((item, index) => validateSchemaValue(item, schema.items, `${path}[${index}]`));
+    }
+    const expectedType = schema.type;
+    if (typeof expectedType !== "string") {
+        return [];
+    }
+    switch (expectedType) {
+        case "string":
+            return typeof value === "string" ? [] : [`${path} must be a string`];
+        case "number":
+            return typeof value === "number" ? [] : [`${path} must be a number`];
+        case "boolean":
+            return typeof value === "boolean" ? [] : [`${path} must be a boolean`];
+        case "null":
+            return value === null ? [] : [`${path} must be null`];
+        default:
+            return [];
+    }
+}
+function validateOutputSchema(componentName, output, schema) {
+    const errors = validateSchemaValue(output, schema);
+    if (errors.length > 0) {
+        throw new Error(`Output for component '${componentName}' failed schema validation: ${errors.join("; ")}`);
+    }
+}
+async function runRunnerComponent(comp, kwargs) {
+    if (comp.runner == null) {
+        throw new Error(`${comp.constructor.name} '${comp.name}' requires a runner to execute locally. Provide one when constructing the ${comp.constructor.name}.`);
+    }
+    if (!comp.model || comp.model.trim() === "") {
+        throw new Error(`Model is required for component '${comp.name}'. Set component.model explicitly.`);
+    }
+    const messages = comp.runner.buildMessages(comp, kwargs);
+    const response = await comp.runner.callLlm({
+        messages,
+        model: comp.model,
+        tools: "tools" in comp ? comp.tools : [],
+        outputSchema: comp.outputSchema,
+        jsonRepair: comp.jsonRepair,
+    });
+    const hasTextOutput = response.text.trim() !== "";
+    const hasToolCalls = response.toolCalls.length > 0;
+    let output;
+    if (!hasTextOutput) {
+        output = {};
+    }
+    else {
+        let parsed;
+        try {
+            parsed = parseJsonResponse(response.text);
+        }
+        catch {
+            parsed = { result: response.text };
+        }
+        output = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : { result: parsed };
+    }
+    if (!hasToolCalls && hasTextOutput) {
+        validateOutputSchema(comp.name, output, comp.outputSchema);
+    }
+    if (hasToolCalls) {
+        output._toolCalls = response.toolCalls.map((toolCall) => ({
+            name: toolCall.name,
+            input: toolCall.input,
+            id: toolCall.id,
+            ...(toolCall._parseError ? { _parseError: toolCall._parseError } : {}),
+        }));
+    }
+    if (response.stopReason != null) {
+        output._stopReason = response.stopReason;
+    }
+    return output;
+}
+async function runAgent(comp, kwargs) {
+    return runRunnerComponent(comp, kwargs);
+}
+async function runLLMProcessor(comp, kwargs) {
+    return runRunnerComponent(comp, kwargs);
+}
+async function runLLMEval(comp, kwargs) {
+    return runRunnerComponent(comp, kwargs);
+}
+async function runOrchestration(comp, inputData, executedSteps) {
+    // Flatten input into accumulated so steps can access row fields directly.
+    // Each step's output is also merged at the top level AND stored at step.name.
+    const accumulated = { ...inputData };
+    const steps = new Map(comp.steps.map((s) => [s.name, s]));
+    // Find the first step (not referenced as a next target by any other step)
+    const allNextTargets = new Set();
+    for (const s of comp.steps) {
+        if (isConditionalLike(s.component)) {
+            allNextTargets.add(s.component.ifTrue);
+            allNextTargets.add(s.component.ifFalse);
+        }
+        for (const n of s.next) {
+            allNextTargets.add(n);
+        }
+    }
+    const startCandidates = comp.steps.filter((s) => !allNextTargets.has(s.name));
+    let currentStepName = startCandidates.length > 0
+        ? startCandidates[0].name
+        : comp.steps[0]?.name ?? "";
+    let lastOutput = {};
+    const visited = new Set();
+    while (currentStepName && !visited.has(currentStepName)) {
+        visited.add(currentStepName);
+        const step = steps.get(currentStepName);
+        if (!step)
+            break;
+        const component = step.component;
+        if (isConditionalLike(component)) {
+            const result = component.condition(accumulated);
+            if (executedSteps) {
+                executedSteps.push({
+                    name: step.name,
+                    type: "conditional",
+                    input: { ...accumulated },
+                    output: { branch: result ? "if_true" : "if_false" },
+                });
+            }
+            currentStepName = result ? component.ifTrue : component.ifFalse;
+            continue;
+        }
+        const stepInput = { ...accumulated };
+        const stepOutput = await executeComponent(component, accumulated);
+        if (executedSteps) {
+            executedSteps.push({
+                name: step.name,
+                type: component.componentType,
+                input: stepInput,
+                output: stepOutput,
+            });
+        }
+        // Merge step output at top level for convenient access in downstream steps
+        Object.assign(accumulated, stepOutput);
+        // Also store under the step name for named access
+        accumulated[step.name] = stepOutput;
+        lastOutput = stepOutput;
+        currentStepName = step.next[0] ?? "";
+    }
+    return lastOutput;
+}
+async function runChecklist(comp, kwargs) {
+    const scores = [];
+    const weights = comp.weights ?? comp.evals.map(() => 1.0);
+    const details = [];
+    for (const evalComp of comp.evals) {
+        const result = await executeComponent(evalComp, kwargs);
+        const score = Number(result.score ?? 0);
+        scores.push(score);
+        details.push({ name: evalComp.name, score, ...result });
+    }
+    const weightedSum = scores.reduce((sum, s, i) => sum + s * weights[i], 0);
+    const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+    const finalScore = totalWeight > 0 ? weightedSum / totalWeight : 0;
+    return { score: finalScore, details };
+}
+async function evalBranch(branch, kwargs) {
+    const branchResult = await executeComponent(branch.eval, kwargs);
+    const branchScore = Number(branchResult.score ?? 0);
+    const tookPass = branchScore >= branch.threshold;
+    const edges = tookPass ? branch.ifPass : branch.ifFail;
+    const leafScores = [];
+    const details = [];
+    const children = [];
+    details.push({
+        type: "branch",
+        name: branch.eval.name,
+        score: branchScore,
+        threshold: branch.threshold,
+        selected_branch: tookPass ? "if_pass" : "if_fail",
+        result: branchResult,
+    });
+    for (const edge of edges) {
+        if (isLeafLike(edge.node)) {
+            const result = await executeComponent(edge.node.eval, kwargs);
+            const score = Number(result.score ?? 0);
+            leafScores.push([score, edge.weight]);
+            const leafNode = {
+                type: "leaf",
+                name: edge.node.eval.name,
+                score,
+                weight: edge.weight,
+                result,
+            };
+            details.push(leafNode);
+            children.push(leafNode);
+        }
+        else {
+            const [subScore, subDetails, subTree] = await evalBranch(edge.node, kwargs);
+            leafScores.push([subScore, edge.weight]);
+            details.push(...subDetails);
+            children.push({
+                ...subTree,
+                weight: edge.weight,
+            });
+        }
+    }
+    const weightedSum = leafScores.reduce((sum, [s, w]) => sum + s * w, 0);
+    const totalWeight = leafScores.reduce((sum, [, w]) => sum + w, 0);
+    const finalScore = totalWeight > 0 ? weightedSum / totalWeight : 0;
+    return [
+        finalScore,
+        details,
+        {
+            type: "branch",
+            name: branch.eval.name,
+            score: finalScore,
+            threshold: branch.threshold,
+            routing_score: branchScore,
+            selected_branch: tookPass ? "if_pass" : "if_fail",
+            routing_result: branchResult,
+            children,
+        },
+    ];
+}
+async function runEvalTree(comp, kwargs) {
+    const [score, details, result] = await evalBranch(comp.root, kwargs);
+    return { score, details, result };
+}
+export async function executeComponent(comp, kwargs) {
+    switch (comp.componentType) {
+        case "tool":
+            return runTool(comp, kwargs);
+        case "code_eval":
+            return runCodeEval(comp, kwargs);
+        case "skill":
+            return runSkill(comp, kwargs);
+        case "agent":
+            return runAgent(comp, kwargs);
+        case "llm_processor":
+            return runLLMProcessor(comp, kwargs);
+        case "llm_eval":
+            return runLLMEval(comp, kwargs);
+        case "orchestration":
+            return runOrchestration(comp, kwargs);
+        case "checklist":
+            return runChecklist(comp, kwargs);
+        case "eval_tree":
+            return runEvalTree(comp, kwargs);
+        default:
+            throw new Error(`Unsupported component type: ${comp.componentType}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Row execution (component + optional eval)
+// ---------------------------------------------------------------------------
+export async function executeRow(component, evalComponent, row) {
+    let output;
+    let error;
+    let demotedError;
+    let orchestrationSteps;
+    try {
+        if (component.componentType === "orchestration") {
+            orchestrationSteps = [];
+            output = await runOrchestration(component, row, orchestrationSteps);
+        }
+        else {
+            output = await executeComponent(component, row);
+        }
+    }
+    catch (err) {
+        error = err instanceof Error ? err.message : String(err);
+        if (evalComponent != null) {
+            demotedError = error;
+            output = buildComponentFailureOutput(error);
+            error = undefined;
+        }
+        else {
+            return { status: "error", error, pathTaken: buildPathTaken(component, row, undefined, error, orchestrationSteps) };
+        }
+    }
+    if (evalComponent != null) {
+        if (output != null
+            && typeof output[COMPONENT_ERROR_KEY] === "string"
+            && isOutputSchemaMismatchError(String(output[COMPONENT_ERROR_KEY]))) {
+            return {
+                status: "ok",
+                output: { ...output, _eval: buildSchemaMismatchEvalOutput(String(output[COMPONENT_ERROR_KEY])) },
+                pathTaken: buildPathTaken(component, row, output, demotedError, orchestrationSteps),
+            };
+        }
+        const evalKwargs = {
+            model_input: deriveModelInput(row),
+            model_response: deriveModelResponse(output),
+            expected_output: deriveExpectedOutput(row),
+        };
+        try {
+            const evalOutput = await executeComponent(evalComponent, evalKwargs);
+            return {
+                status: "ok",
+                output: { ...output, _eval: evalOutput },
+                pathTaken: buildPathTaken(component, row, output, demotedError, orchestrationSteps),
+            };
+        }
+        catch (err) {
+            const evalError = err instanceof Error ? err.message : String(err);
+            return {
+                status: "ok",
+                output,
+                error: evalError,
+                pathTaken: buildPathTaken(component, row, output, demotedError, orchestrationSteps),
+            };
+        }
+    }
+    return {
+        status: "ok",
+        output,
+        pathTaken: buildPathTaken(component, row, output, demotedError, orchestrationSteps),
+    };
+}
+function buildPathTaken(component, inputData, output, error, orchestrationSteps) {
+    switch (component.componentType) {
+        case "tool": {
+            const result = {
+                kind: "tool",
+                function_definition: {
+                    name: component.name,
+                    description: component.description,
+                },
+                input: inputData,
+            };
+            if (output !== undefined)
+                result.output = output;
+            if (error !== undefined)
+                result.error = error;
+            return result;
+        }
+        case "skill": {
+            const result = {
+                kind: "skill",
+                prompt: component.instructions ?? "",
+            };
+            if (error !== undefined)
+                result.error = error;
+            return result;
+        }
+        case "agent": {
+            const result = {
+                kind: "agent",
+                messages: [],
+            };
+            if (error !== undefined)
+                result.error = error;
+            return result;
+        }
+        case "orchestration": {
+            const result = {
+                kind: "orchestration",
+                steps: orchestrationSteps ?? [],
+            };
+            if (error !== undefined)
+                result.error = error;
+            return result;
+        }
+        default:
+            return undefined;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * zhanla-sdk-ts public API.
+ * Import component classes to define zhanla components in TypeScript.
+ */
+export { Tool, CodeEval, Skill, Agent, LLMProcessor, LLMEval, Runner, Conditional, Step, Orchestration, Leaf, Edge, Branch, Checklist, EvalTree, BaseComponent, RUNNABLE_TYPES, EVAL_TYPES, } from "./types.js";
+export type { ToolOptions, CodeEvalOptions, SkillOptions, AgentOptions, LLMProcessorOptions, LLMEvalOptions, OrchestrationOptions, ChecklistOptions, EvalTreeOptions, StepOptions, ComponentType, JsonSchema, JsonSchemaObject, JsonSchemaArray, JsonSchemaScalar, ToolCall, LLMResponse, RunnerOptions, RunnerCallOptions, RunnerMessage, } from "./types.js";
+export { toManifest, collectExportedComponents } from "./manifest.js";
+export type { ComponentManifest, StepManifest, BranchManifest, EdgeManifest, LeafManifest } from "./manifest.js";
+export { executeComponent, executeRow } from "./executor.js";
+export type { RowResult } from "./executor.js";
+export { wrap } from "./wrap.js";
+export { parseJsonResponse } from "./json.js";
+export { TraceContext, traceStorage } from "./trace_store.js";
+export type { LLMCall } from "./trace_store.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * zhanla-sdk-ts public API.
+ * Import component classes to define zhanla components in TypeScript.
+ */
+export { Tool, CodeEval, Skill, Agent, LLMProcessor, LLMEval, Runner, Conditional, Step, Orchestration, Leaf, Edge, Branch, Checklist, EvalTree, BaseComponent, RUNNABLE_TYPES, EVAL_TYPES, } from "./types.js";
+export { toManifest, collectExportedComponents } from "./manifest.js";
+export { executeComponent, executeRow } from "./executor.js";
+export { wrap } from "./wrap.js";
+export { parseJsonResponse } from "./json.js";
+export { TraceContext, traceStorage } from "./trace_store.js";

package/dist/json.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Helpers for extracting JSON payloads from model text responses.
+ */
+export declare function parseJsonResponse(text: string): unknown;

package/dist/json.js

@@ -0,0 +1,43 @@
+/**
+ * Helpers for extracting JSON payloads from model text responses.
+ */
+function previewText(text, limit = 200) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length <= limit) {
+        return normalized;
+    }
+    return `${normalized.slice(0, limit)}...`;
+}
+function extractMalformedComponentError(normalized) {
+    const startMatch = normalized.match(/^\{\s*"_component_error"\s*:\s*"/);
+    const endMatch = /"\s*\}$/.exec(normalized);
+    if (!startMatch || !endMatch || endMatch.index < startMatch[0].length) {
+        return null;
+    }
+    return {
+        _component_error: normalized.slice(startMatch[0].length, endMatch.index),
+    };
+}
+export function parseJsonResponse(text) {
+    let normalized = text.trim();
+    if (normalized.startsWith("```")) {
+        const lines = normalized.split(/\r?\n/);
+        if (lines.length >= 3 && lines[0].startsWith("```") && lines[lines.length - 1].trim() === "```") {
+            normalized = lines.slice(1, -1).join("\n").trim();
+            if (normalized.toLowerCase().startsWith("json")) {
+                normalized = normalized.slice(4).trimStart();
+            }
+        }
+    }
+    try {
+        return JSON.parse(normalized);
+    }
+    catch (error) {
+        const recovered = extractMalformedComponentError(normalized);
+        if (recovered != null) {
+            return recovered;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new SyntaxError(`Failed to parse JSON response: ${detail}. Response preview: ${previewText(normalized)}`);
+    }
+}

package/dist/manifest.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Manifest emission — serialize SDK component instances into ComponentManifest objects.
+ * The manifest shape mirrors the Python CLI's ComponentManifest dataclass.
+ */
+import { BaseComponent, JsonSchema } from "./types.js";
+export interface StepManifest {
+    name: string;
+    component: string;
+    next: string[];
+    is_conditional?: boolean;
+    if_true?: string;
+    if_false?: string;
+}
+export interface EdgeManifest {
+    weight: number;
+    node: LeafManifest | BranchManifest;
+}
+export interface LeafManifest {
+    type: "leaf";
+    eval: string;
+}
+export interface BranchManifest {
+    type: "branch";
+    eval: string;
+    threshold: number;
+    if_pass: EdgeManifest[];
+    if_fail: EdgeManifest[];
+}
+export interface ComponentManifest {
+    name: string;
+    description: string;
+    component_type: string;
+    language: "typescript";
+    is_runnable: boolean;
+    is_eval: boolean;
+    version_hash: string;
+    instructions?: string;
+    model?: string;
+    fn_present?: boolean;
+    is_async?: boolean;
+    tools?: string[];
+    skills?: string[];
+    agents?: string[];
+    steps?: StepManifest[];
+    evals?: string[];
+    weights?: number[];
+    root?: BranchManifest;
+    output_schema?: JsonSchema;
+    file_path?: string;
+    symbol_name?: string;
+    source_code?: string;
+    source_language?: string;
+    source_format?: string;
+    model_response_format?: string;
+}
+export declare function toManifest(component: BaseComponent, opts?: {
+    filePath?: string;
+    symbolName?: string;
+}): ComponentManifest;
+export declare function collectExportedComponents(moduleExports: Record<string, unknown>): BaseComponent[];