@zhanla/sdk-ts 0.2.0 → 0.3.1

package/bin/discover.js

@@ -11,6 +11,7 @@
 
 import { pathToFileURL } from "url";
 import { resolve } from "path";
+import { loadDotenvLocal, splitFileSpec } from "./env.js";
 
 function isComponentLike(value) {
   return (
@@ -77,8 +78,34 @@ function stableSerialize(value) {
   return JSON.stringify(value);
 }
 
-function sortRefsByKey(refs) {
-  return [...refs].sort((left, right) => left.key.localeCompare(right.key));
+function projectRefForHash(ref) {
+  return { key: ref.key, component_type: ref.component_type };
+}
+
+function sortAndProjectRefs(refs) {
+  return [...refs].map(projectRefForHash).sort((a, b) => a.key.localeCompare(b.key));
+}
+
+function normalizeStepForHash(step) {
+  if (step.is_conditional) return step;
+  const ref = step.component_ref;
+  if (ref == null) return step;
+  return { ...step, component_ref: projectRefForHash(ref) };
+}
+
+function normalizeEvalNodeForHash(node) {
+  if (node == null || typeof node !== "object") return node;
+  const result = { ...node };
+  if (result.eval_ref != null) result.eval_ref = projectRefForHash(result.eval_ref);
+  for (const branch of ["if_pass", "if_fail"]) {
+    if (Array.isArray(result[branch])) {
+      result[branch] = result[branch].map((edge) => {
+        if (edge == null || typeof edge !== "object" || edge.node == null) return edge;
+        return { ...edge, node: normalizeEvalNodeForHash(edge.node) };
+      });
+    }
+  }
+  return result;
 }
 
 function behaviorFields(manifest) {
@@ -91,13 +118,13 @@ function behaviorFields(manifest) {
   if (manifest.model != null) fields.model = manifest.model;
   if (manifest.temperature != null) fields.temperature = manifest.temperature;
   if (manifest.output_schema != null) fields.output_schema = manifest.output_schema;
-  if (manifest.tool_refs != null) fields.tool_refs = sortRefsByKey(manifest.tool_refs);
-  if (manifest.skill_refs != null) fields.skill_refs = sortRefsByKey(manifest.skill_refs);
-  if (manifest.agent_refs != null) fields.agent_refs = sortRefsByKey(manifest.agent_refs);
-  if (manifest.steps != null) fields.steps = manifest.steps;
-  if (manifest.eval_refs != null) fields.eval_refs = sortRefsByKey(manifest.eval_refs);
+  if (manifest.tool_refs != null) fields.tool_refs = sortAndProjectRefs(manifest.tool_refs);
+  if (manifest.skill_refs != null) fields.skill_refs = sortAndProjectRefs(manifest.skill_refs);
+  if (manifest.agent_refs != null) fields.agent_refs = sortAndProjectRefs(manifest.agent_refs);
+  if (manifest.steps != null) fields.steps = manifest.steps.map(normalizeStepForHash);
+  if (manifest.eval_refs != null) fields.eval_refs = sortAndProjectRefs(manifest.eval_refs);
   if (manifest.weights != null) fields.weights = manifest.weights;
-  if (manifest.root != null) fields.root = manifest.root;
+  if (manifest.root != null) fields.root = normalizeEvalNodeForHash(manifest.root);
   if (manifest.source_code != null) fields.source_code = manifest.source_code;
   if (manifest.model_response_format != null) {
     fields.model_response_format = manifest.model_response_format;
@@ -186,17 +213,10 @@ export function buildDiscoveredManifests({
 }
 
 export async function runDiscover(fileSpec) {
-  let filePath = fileSpec;
-  let symbolName = null;
-
-  const colonIndex = fileSpec.lastIndexOf(":");
-  // Handle Windows drive letters (e.g. C:\...) — only split if colon is not at position 1
-  if (colonIndex > 1) {
-    filePath = fileSpec.slice(0, colonIndex);
-    symbolName = fileSpec.slice(colonIndex + 1) || null;
-  }
+  const { filePath, symbolName } = splitFileSpec(fileSpec);
 
   const absolutePath = resolve(filePath);
+  loadDotenvLocal(absolutePath);
   const fileUrl = pathToFileURL(absolutePath).href;
 
   let moduleExports;

package/bin/env.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, statSync } from "fs";
+import { dirname, join, resolve } from "path";
+
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function splitFileSpec(fileSpec) {
+  const colonIndex = fileSpec.lastIndexOf(":");
+  // Preserve Windows drive letters (e.g. C:\...) by only splitting on later colons.
+  if (colonIndex > 1) {
+    return {
+      filePath: fileSpec.slice(0, colonIndex),
+      symbolName: fileSpec.slice(colonIndex + 1) || null,
+    };
+  }
+  return { filePath: fileSpec, symbolName: null };
+}
+
+export function findDotenvLocal(startPath) {
+  let current = resolve(startPath);
+  if (!isDirectory(current)) {
+    current = dirname(current);
+  }
+
+  while (true) {
+    const candidate = join(current, ".env.local");
+    if (existsSync(candidate)) {
+      return candidate;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+export function loadDotenvLocal(startPath) {
+  const envPath = findDotenvLocal(startPath);
+  if (!envPath) {
+    return null;
+  }
+
+  const source = readFileSync(envPath, "utf8");
+  for (const line of source.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith("#")) continue;
+    const equalsIndex = trimmed.indexOf("=");
+    if (equalsIndex === -1) continue;
+
+    const key = trimmed.slice(0, equalsIndex).trim();
+    let value = trimmed.slice(equalsIndex + 1).trim();
+    if (
+      (value.startsWith('"') && value.endsWith('"'))
+      || (value.startsWith("'") && value.endsWith("'"))
+    ) {
+      value = value.slice(1, -1);
+    }
+    if (key && process.env[key] === undefined) {
+      process.env[key] = value;
+    }
+  }
+
+  return envPath;
+}

package/bin/run.js

@@ -11,6 +11,7 @@
 import { pathToFileURL } from "url";
 import { resolve } from "path";
 import readline from "readline";
+import { loadDotenvLocal } from "./env.js";
 
 function redirectConsoleToStderr() {
   const stringifyArg = (arg) => {
@@ -54,6 +55,7 @@ async function loadTargetComponent(target, collectExportedComponents) {
   const { filePath, symbolName } = parseTarget(target);
 
   const absolutePath = resolve(filePath);
+  loadDotenvLocal(absolutePath);
   const fileUrl = pathToFileURL(absolutePath).href;
 
   let moduleExports;

package/dist/executor.d.ts

@@ -2,12 +2,12 @@
  * Local execution engine for TypeScript SDK components.
  * Mirrors the Python CLI executor's component-type dispatch semantics.
  */
-import { BaseComponent } from "./types.js";
+import { ZhanlaComponent } from "./types.js";
 export interface RowResult {
     status: "ok" | "error";
     output?: Record<string, unknown>;
     error?: string;
     pathTaken?: Record<string, unknown>;
 }
-export declare function executeComponent(comp: BaseComponent, kwargs: Record<string, unknown>): Promise<Record<string, unknown>>;
-export declare function executeRow(component: BaseComponent, evalComponent: BaseComponent | null, row: Record<string, unknown>): Promise<RowResult>;
+export declare function executeComponent(comp: ZhanlaComponent, kwargs: Record<string, unknown>): Promise<Record<string, unknown>>;
+export declare function executeRow(component: ZhanlaComponent, evalComponent: ZhanlaComponent | null, row: Record<string, unknown>): Promise<RowResult>;

package/dist/executor.js

@@ -13,6 +13,17 @@ const JSON_OUTPUT_ERROR_MARKERS = [
     "extra data",
     "unexpected token",
 ];
+const EXECUTION_MODES = {
+    tool: "code",
+    code_eval: "code",
+    skill: "prompt",
+    agent: "prompt",
+    llm_processor: "prompt",
+    llm_eval: "prompt",
+    orchestration: "dag",
+    checklist: "composite",
+    eval_tree: "composite",
+};
 function buildComponentFailureOutput(error) {
     return { [COMPONENT_ERROR_KEY]: error };
 }
@@ -58,12 +69,6 @@ function stringifyValue(value) {
         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"]);
@@ -151,7 +156,14 @@ async function runTool(comp, kwargs) {
     return { result };
 }
 async function runCodeEval(comp, kwargs) {
-    const { value: result, logs } = await captureConsoleLogs(async () => executeFn(comp.fn, kwargs, comp.isAsync));
+    const modelResponse = kwargs["model_response"];
+    const expectedResponse = kwargs["expected_response"] ?? null;
+    const { value: result, logs } = await captureConsoleLogs(async () => {
+        if (comp.isAsync) {
+            return await comp.fn(modelResponse, expectedResponse);
+        }
+        return comp.fn(modelResponse, expectedResponse);
+    });
     if (result !== null && typeof result === "object" && !Array.isArray(result)) {
         return logs.length > 0
             ? { ...result, logs }
@@ -289,6 +301,32 @@ async function runLLMProcessor(comp, kwargs) {
 async function runLLMEval(comp, kwargs) {
     return runRunnerComponent(comp, kwargs);
 }
+function componentExecutionMode(component) {
+    return EXECUTION_MODES[component.componentType];
+}
+function componentSourceLanguage(component) {
+    switch (component.componentType) {
+        case "tool":
+        case "agent":
+        case "llm_processor":
+        case "llm_eval":
+            return "typescript";
+        default:
+            return undefined;
+    }
+}
+function componentPrompt(component) {
+    if ("instructions" in component && typeof component.instructions === "string" && component.instructions !== "") {
+        return component.instructions;
+    }
+    return undefined;
+}
+function componentSourceCode(component) {
+    if ("fn" in component && typeof component.fn === "function") {
+        return component.fn.toString();
+    }
+    return undefined;
+}
 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.
@@ -331,14 +369,45 @@ async function runOrchestration(comp, inputData, executedSteps) {
             continue;
         }
         const stepInput = { ...accumulated };
-        const stepOutput = await executeComponent(component, accumulated);
+        let stepOutput;
+        let nestedTrace;
+        if (component.componentType === "orchestration") {
+            const nestedSteps = [];
+            stepOutput = await runOrchestration(component, accumulated, nestedSteps);
+            nestedTrace = { kind: "orchestration", steps: nestedSteps };
+        }
+        else {
+            stepOutput = await executeComponent(component, accumulated);
+        }
         if (executedSteps) {
-            executedSteps.push({
+            const stepRecord = {
                 name: step.name,
                 type: component.componentType,
+                component_type: component.componentType,
+                component_key: component.key,
                 input: stepInput,
                 output: stepOutput,
-            });
+            };
+            const executionMode = componentExecutionMode(component);
+            if (executionMode !== undefined) {
+                stepRecord.execution_mode = executionMode;
+            }
+            const sourceLanguage = componentSourceLanguage(component);
+            if (sourceLanguage !== undefined) {
+                stepRecord.source_language = sourceLanguage;
+            }
+            const prompt = componentPrompt(component);
+            if (prompt !== undefined) {
+                stepRecord.prompt = prompt;
+            }
+            const sourceCode = componentSourceCode(component);
+            if (sourceCode !== undefined) {
+                stepRecord.source_code = sourceCode;
+            }
+            if (nestedTrace !== undefined) {
+                stepRecord.trace = nestedTrace;
+            }
+            executedSteps.push(stepRecord);
         }
         // Merge step output at top level for convenient access in downstream steps
         Object.assign(accumulated, stepOutput);
@@ -490,9 +559,8 @@ export async function executeRow(component, evalComponent, row) {
             };
         }
         const evalKwargs = {
-            model_input: deriveModelInput(row),
             model_response: deriveModelResponse(output),
-            expected_output: deriveExpectedOutput(row),
+            expected_response: deriveExpectedOutput(row) || null,
         };
         try {
             const evalOutput = await executeComponent(evalComponent, evalKwargs);

package/dist/index.d.ts

@@ -2,8 +2,8 @@
  * 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 { Tool, CodeEval, Skill, Agent, LLMProcessor, LLMEval, Runner, Conditional, Step, Orchestration, Leaf, Edge, Branch, Checklist, EvalTree, ZhanlaComponent, RUNNABLE_TYPES, EVAL_TYPES, } from "./types.js";
+export type { ComponentValue, 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";

package/dist/index.js

@@ -2,7 +2,7 @@
  * 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 { Tool, CodeEval, Skill, Agent, LLMProcessor, LLMEval, Runner, Conditional, Step, Orchestration, Leaf, Edge, Branch, Checklist, EvalTree, ZhanlaComponent, RUNNABLE_TYPES, EVAL_TYPES, } from "./types.js";
 export { toManifest, collectExportedComponents } from "./manifest.js";
 export { executeComponent, executeRow } from "./executor.js";
 export { wrap } from "./wrap.js";

package/dist/manifest.d.ts

@@ -2,7 +2,7 @@
  * Manifest emission — serialize SDK component instances into ComponentManifest objects.
  * The manifest shape mirrors the Python CLI's ComponentManifest dataclass.
  */
-import { BaseComponent, ComponentRef, JsonSchema } from "./types.js";
+import { ZhanlaComponent, ComponentRef, JsonSchema } from "./types.js";
 export interface StepManifest {
     name: string;
     component_ref?: ComponentRef;
@@ -62,8 +62,8 @@ export interface ComponentManifest {
     source_format?: string;
     model_response_format?: string;
 }
-export declare function toManifest(component: BaseComponent, opts?: {
+export declare function toManifest(component: ZhanlaComponent, opts?: {
     filePath?: string;
     symbolName?: string;
 }): ComponentManifest;
-export declare function collectExportedComponents(moduleExports: Record<string, unknown>): BaseComponent[];
+export declare function collectExportedComponents(moduleExports: Record<string, unknown>): ZhanlaComponent[];

package/dist/types.d.ts

@@ -16,6 +16,7 @@ export type JsonSchemaArray = {
     items: JsonSchema;
 };
 export type JsonSchema = JsonSchemaScalar | JsonSchemaObject | JsonSchemaArray | Record<string, unknown>;
+export type ComponentValue = string | number | Record<string, unknown> | unknown[];
 export type ComponentType = "tool" | "code_eval" | "skill" | "agent" | "llm_processor" | "llm_eval" | "orchestration" | "checklist" | "eval_tree";
 export interface ComponentRef {
     key: string;
@@ -60,7 +61,7 @@ export interface RunnerOptions {
 export declare class Runner {
     readonly client: unknown;
     constructor(opts: RunnerOptions);
-    buildMessages(component: Pick<BaseComponent, "description"> & {
+    buildMessages(component: Pick<ZhanlaComponent, "description"> & {
         instructions?: string;
     }, row: Record<string, unknown>): RunnerMessage[];
     private providerName;
@@ -72,9 +73,10 @@ export declare class Runner {
         jsonRepair?: boolean;
         text: string;
     }): Promise<string>;
+    private warnModelProviderMismatch;
     callLlm(opts: RunnerCallOptions): Promise<LLMResponse>;
 }
-export declare abstract class BaseComponent {
+export declare abstract class ZhanlaComponent {
     abstract readonly componentType: ComponentType;
     abstract readonly name: string;
     abstract readonly description: string;
@@ -90,7 +92,7 @@ export interface ToolOptions {
     outputSchema?: JsonSchema;
     key: string;
 }
-export declare class Tool extends BaseComponent {
+export declare class Tool extends ZhanlaComponent {
     readonly componentType: "tool";
     readonly name: string;
     readonly description: string;
@@ -104,15 +106,15 @@ export declare class Tool extends BaseComponent {
 export interface CodeEvalOptions {
     name: string;
     description: string;
-    fn: (...args: unknown[]) => unknown;
+    fn: (modelResponse: ComponentValue, expectedResponse: ComponentValue | null) => unknown;
     modelResponseFormat?: "JSON" | "TEXT" | "YAML";
     key: string;
 }
-export declare class CodeEval extends BaseComponent {
+export declare class CodeEval extends ZhanlaComponent {
     readonly componentType: "code_eval";
     readonly name: string;
     readonly description: string;
-    readonly fn: (...args: unknown[]) => unknown;
+    readonly fn: (modelResponse: ComponentValue, expectedResponse: ComponentValue | null) => unknown;
     readonly isAsync: boolean;
     readonly modelResponseFormat: "JSON" | "TEXT" | "YAML";
     readonly key: string;
@@ -127,7 +129,7 @@ export interface SkillOptions {
     outputSchema?: JsonSchema;
     key: string;
 }
-export declare class Skill extends BaseComponent {
+export declare class Skill extends ZhanlaComponent {
     readonly componentType: "skill";
     readonly name: string;
     readonly description: string;
@@ -144,6 +146,7 @@ export interface AgentOptions {
     description: string;
     instructions: string;
     model: string;
+    client?: unknown;
     runner?: Runner;
     tools?: Tool[];
     skills?: Skill[];
@@ -154,7 +157,7 @@ export interface AgentOptions {
     topK?: number;
     key: string;
 }
-export declare class Agent extends BaseComponent {
+export declare class Agent extends ZhanlaComponent {
     readonly componentType: "agent";
     readonly name: string;
     readonly description: string;
@@ -176,6 +179,7 @@ export interface LLMProcessorOptions {
     description: string;
     instructions: string;
     model: string;
+    client?: unknown;
     runner?: Runner;
     outputSchema?: JsonSchema;
     jsonRepair?: boolean;
@@ -183,7 +187,7 @@ export interface LLMProcessorOptions {
     topK?: number;
     key: string;
 }
-export declare class LLMProcessor extends BaseComponent {
+export declare class LLMProcessor extends ZhanlaComponent {
     readonly componentType: "llm_processor";
     readonly name: string;
     readonly description: string;
@@ -202,6 +206,7 @@ export interface LLMEvalOptions {
     description: string;
     instructions: string;
     model: string;
+    client?: unknown;
     runner?: Runner;
     outputSchema?: JsonSchema;
     jsonRepair?: boolean;
@@ -209,7 +214,7 @@ export interface LLMEvalOptions {
     topK?: number;
     key: string;
 }
-export declare class LLMEval extends BaseComponent {
+export declare class LLMEval extends ZhanlaComponent {
     readonly componentType: "llm_eval";
     readonly name: string;
     readonly description: string;
@@ -236,12 +241,12 @@ export declare class Conditional {
 }
 export interface StepOptions {
     name: string;
-    component: BaseComponent | Conditional;
+    component: ZhanlaComponent | Conditional;
     next?: string[];
 }
 export declare class Step {
     readonly name: string;
-    readonly component: BaseComponent | Conditional;
+    readonly component: ZhanlaComponent | Conditional;
     readonly next: string[];
     constructor(opts: StepOptions);
 }
@@ -251,7 +256,7 @@ export interface OrchestrationOptions {
     steps: Step[];
     key: string;
 }
-export declare class Orchestration extends BaseComponent {
+export declare class Orchestration extends ZhanlaComponent {
     readonly componentType: "orchestration";
     readonly name: string;
     readonly description: string;
@@ -260,9 +265,9 @@ export declare class Orchestration extends BaseComponent {
     constructor(opts: OrchestrationOptions);
 }
 export declare class Leaf {
-    readonly eval: BaseComponent;
+    readonly eval: ZhanlaComponent;
     constructor(opts: {
-        eval: BaseComponent;
+        eval: ZhanlaComponent;
     });
 }
 export declare class Edge {
@@ -274,12 +279,12 @@ export declare class Edge {
     });
 }
 export declare class Branch {
-    readonly eval: BaseComponent;
+    readonly eval: ZhanlaComponent;
     readonly threshold: number;
     readonly ifPass: Edge[];
     readonly ifFail: Edge[];
     constructor(opts: {
-        eval: BaseComponent;
+        eval: ZhanlaComponent;
         threshold: number;
         ifPass: Edge[];
         ifFail: Edge[];
@@ -288,15 +293,15 @@ export declare class Branch {
 export interface ChecklistOptions {
     name: string;
     description: string;
-    evals: BaseComponent[];
+    evals: ZhanlaComponent[];
     weights?: number[];
     key: string;
 }
-export declare class Checklist extends BaseComponent {
+export declare class Checklist extends ZhanlaComponent {
     readonly componentType: "checklist";
     readonly name: string;
     readonly description: string;
-    readonly evals: BaseComponent[];
+    readonly evals: ZhanlaComponent[];
     readonly weights?: number[];
     readonly key: string;
     constructor(opts: ChecklistOptions);
@@ -307,7 +312,7 @@ export interface EvalTreeOptions {
     root: Branch;
     key: string;
 }
-export declare class EvalTree extends BaseComponent {
+export declare class EvalTree extends ZhanlaComponent {
     readonly componentType: "eval_tree";
     readonly name: string;
     readonly description: string;

package/dist/types.js

@@ -263,7 +263,22 @@ export class Runner {
             }
         }
     }
+    warnModelProviderMismatch(model) {
+        const provider = this.providerName();
+        let expected;
+        if (model.startsWith("claude-"))
+            expected = "anthropic";
+        else if (model.startsWith("gemini-"))
+            expected = "gemini";
+        else if (/^(gpt-|o1-|o3-|o4-)/.test(model))
+            expected = "openai";
+        if (expected !== undefined && provider !== expected) {
+            console.warn(`[zhanla] Model '${model}' looks like an ${expected} model but the runner client is ${provider}. ` +
+                "Check that your client matches your model.");
+        }
+    }
     async callLlm(opts) {
+        this.warnModelProviderMismatch(opts.model);
         if (isAnthropicClient(this.client)) {
             const systemMessage = opts.messages.find((message) => message.role === "system")?.content ?? "";
             const chatMessages = opts.messages
@@ -426,7 +441,7 @@ export class Runner {
 // ---------------------------------------------------------------------------
 // Base component class
 // ---------------------------------------------------------------------------
-export class BaseComponent {
+export class ZhanlaComponent {
     get isRunnable() {
         return RUNNABLE_TYPES.has(this.componentType);
     }
@@ -434,7 +449,7 @@ export class BaseComponent {
         return EVAL_TYPES.has(this.componentType);
     }
 }
-export class Tool extends BaseComponent {
+export class Tool extends ZhanlaComponent {
     componentType = "tool";
     name;
     description;
@@ -455,7 +470,7 @@ export class Tool extends BaseComponent {
         this.key = opts.key;
     }
 }
-export class CodeEval extends BaseComponent {
+export class CodeEval extends ZhanlaComponent {
     componentType = "code_eval";
     name;
     description;
@@ -474,7 +489,7 @@ export class CodeEval extends BaseComponent {
         this.key = opts.key;
     }
 }
-export class Skill extends BaseComponent {
+export class Skill extends ZhanlaComponent {
     componentType = "skill";
     name;
     description;
@@ -497,7 +512,7 @@ export class Skill extends BaseComponent {
         this.key = opts.key;
     }
 }
-export class Agent extends BaseComponent {
+export class Agent extends ZhanlaComponent {
     componentType = "agent";
     name;
     description;
@@ -514,11 +529,14 @@ export class Agent extends BaseComponent {
     key;
     constructor(opts) {
         super();
+        if (opts.client !== undefined && opts.runner !== undefined) {
+            throw new Error("Specify client or runner, not both.");
+        }
         this.name = opts.name;
         this.description = opts.description;
         this.instructions = opts.instructions;
         this.model = opts.model;
-        this.runner = opts.runner;
+        this.runner = opts.client !== undefined ? new Runner({ client: opts.client }) : opts.runner;
         this.tools = opts.tools ?? [];
         this.skills = opts.skills ?? [];
         this.agents = opts.agents ?? [];
@@ -530,7 +548,7 @@ export class Agent extends BaseComponent {
         this.key = opts.key;
     }
 }
-export class LLMProcessor extends BaseComponent {
+export class LLMProcessor extends ZhanlaComponent {
     componentType = "llm_processor";
     name;
     description;
@@ -544,11 +562,14 @@ export class LLMProcessor extends BaseComponent {
     key;
     constructor(opts) {
         super();
+        if (opts.client !== undefined && opts.runner !== undefined) {
+            throw new Error("Specify client or runner, not both.");
+        }
         this.name = opts.name;
         this.description = opts.description;
         this.instructions = opts.instructions;
         this.model = opts.model;
-        this.runner = opts.runner;
+        this.runner = opts.client !== undefined ? new Runner({ client: opts.client }) : opts.runner;
         this.outputSchema = opts.outputSchema;
         this.jsonRepair = opts.jsonRepair ?? false;
         this.temperature = opts.temperature;
@@ -557,7 +578,7 @@ export class LLMProcessor extends BaseComponent {
         this.key = opts.key;
     }
 }
-export class LLMEval extends BaseComponent {
+export class LLMEval extends ZhanlaComponent {
     componentType = "llm_eval";
     name;
     description;
@@ -571,11 +592,14 @@ export class LLMEval extends BaseComponent {
     key;
     constructor(opts) {
         super();
+        if (opts.client !== undefined && opts.runner !== undefined) {
+            throw new Error("Specify client or runner, not both.");
+        }
         this.name = opts.name;
         this.description = opts.description;
         this.instructions = opts.instructions;
         this.model = opts.model;
-        this.runner = opts.runner;
+        this.runner = opts.client !== undefined ? new Runner({ client: opts.client }) : opts.runner;
         this.outputSchema = opts.outputSchema;
         this.jsonRepair = opts.jsonRepair ?? false;
         this.temperature = opts.temperature;
@@ -604,7 +628,7 @@ export class Step {
         this.next = opts.next ?? [];
     }
 }
-export class Orchestration extends BaseComponent {
+export class Orchestration extends ZhanlaComponent {
     componentType = "orchestration";
     name;
     description;
@@ -648,7 +672,7 @@ export class Branch {
         this.ifFail = opts.ifFail;
     }
 }
-export class Checklist extends BaseComponent {
+export class Checklist extends ZhanlaComponent {
     componentType = "checklist";
     name;
     description;
@@ -665,7 +689,7 @@ export class Checklist extends BaseComponent {
         this.key = opts.key;
     }
 }
-export class EvalTree extends BaseComponent {
+export class EvalTree extends ZhanlaComponent {
     componentType = "eval_tree";
     name;
     description;

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@zhanla/sdk-ts",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "TypeScript SDK for the zhanla CLI — define and run AI components locally",
+  "homepage": "https://benchmark-black.vercel.app/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/zhanla-ai"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
   "bin": {
-    "zhanla-sdk-ts": "./bin/cli.js"
+    "zhanla-sdk-ts": "bin/cli.js"
   },
   "scripts": {
     "build": "tsc",