@zhanla/sdk-ts 0.1.0 → 0.2.0

package/README.md

@@ -14,6 +14,8 @@ Requires Node `>=18`.
 
 Provider packages such as `@anthropic-ai/sdk`, `openai`, and `@google/genai` are optional. Install them only if you use `Runner` with those clients.
 
+Every component requires an explicit stable `key`. Use a lowercase, hyphenated identifier such as `support-agent`.
+
 ## Quick Start
 
 ```ts
@@ -27,6 +29,7 @@ const runner = new Runner({
 export const supportAgent = new Agent({
   name: "support_agent",
   description: "Respond to support requests.",
+  key: "support-agent",
   instructions: 'Answer clearly. Return JSON: {"answer": "..."}',
   model: "claude-sonnet-4-6",
   runner,
@@ -42,6 +45,7 @@ export const supportAgent = new Agent({
 export const supportEval = new CodeEval({
   name: "support_eval",
   description: "Check whether an answer was returned.",
+  key: "support-eval",
   fn: (kwargs: unknown) => {
     const { model_response } = kwargs as { model_response?: string };
     const parsed = model_response ? JSON.parse(model_response) : {};
@@ -53,7 +57,7 @@ export const supportEval = new CodeEval({
 Run it with the CLI:
 
 ```bash
-bench run components.ts:support_agent --dataset tickets.json --eval components.ts:support_eval
+zhanla run components.ts:support_agent --dataset tickets.json --eval components.ts:support_eval
 ```
 
 ## Public API
@@ -92,6 +96,7 @@ Use a `Tool` for deterministic TypeScript logic.
 export const lookupCustomer = new Tool({
   name: "lookup_customer",
   description: "Fetch a customer record by ID.",
+  key: "lookup-customer",
   inputSchema: { type: "object", properties: {} },
   fn: (kwargs: unknown) => {
     const { customerId } = kwargs as { customerId: string };
@@ -122,6 +127,7 @@ Use a `Skill` for reusable instructions and tool access.
 export const summarizeSkill = new Skill({
   name: "summarize_skill",
   description: "Reusable summarization instructions.",
+  key: "summarize-skill",
   instructions: "Summarize the provided text in one short paragraph.",
   tools: [lookupCustomer],
 });
@@ -144,6 +150,7 @@ const runner = new Runner({
 export const supportAgent = new Agent({
   name: "support_agent",
   description: "Respond to support requests.",
+  key: "support-agent",
   instructions: 'Answer clearly. Return JSON: {"answer": "..."}',
   model: "gpt-4.1-mini",
   runner,
@@ -174,6 +181,7 @@ const runner = new Runner({
 export const intentClassifier = new LLMProcessor({
   name: "intent_classifier",
   description: "Classify intent.",
+  key: "intent-classifier",
   instructions: 'Return JSON: {"intent": "billing|technical|other"}',
   model: "claude-haiku-4-5",
   runner,
@@ -195,6 +203,7 @@ Use an `LLMEval` for LLM-backed evaluation logic.
 export const toneEval = new LLMEval({
   name: "tone_eval",
   description: "Evaluate tone.",
+  key: "tone-eval",
   instructions: 'Return JSON: {"score": 0.0, "reason": "..."}',
   model: "gpt-4.1-mini",
   runner,
@@ -217,8 +226,13 @@ Use an `Orchestration` to compose steps into a DAG.
 export const supportPipeline = new Orchestration({
   name: "support_pipeline",
   description: "Classify intent, then draft a reply.",
+  key: "support-pipeline",
   steps: [
-    new Step({ name: "classify", component: intentClassifier, next: ["reply"] }),
+    new Step({
+      name: "classify",
+      component: intentClassifier,
+      next: ["reply"],
+    }),
     new Step({ name: "reply", component: supportAgent }),
   ],
 });
@@ -260,7 +274,7 @@ const runner = new Runner({
 
 - `constructor({ client })` wraps the client internally with `wrap(...)`
 - `buildMessages(component, row)` defaults to `[system instructions, user JSON row]`
-- `callLlm({ messages, model, tools, outputSchema })` supports Anthropic, OpenAI-compatible chat clients, and Gemini
+- `callLlm({ messages, model, tools, outputSchema, temperature, topK })` supports Anthropic, OpenAI-compatible chat clients, and Gemini
 
 Current local execution behavior:
 
@@ -268,7 +282,7 @@ Current local execution behavior:
 - `model` must be set explicitly
 - response text is parsed as JSON when possible, otherwise wrapped as `{ result: text }`
 - `outputSchema` is used for validation
-- returned tool calls raise a not-implemented error for now
+- returned tool calls are exposed as `_toolCalls` on the local execution output
 
 ## Observability
 
@@ -303,7 +317,7 @@ if (ctx) {
 TypeScript discovery loads your module and collects exported component instances.
 
 ```bash
-bench run workflow.ts:support_pipeline --dataset tickets.json --eval evals.ts:answer_quality
+zhanla run workflow.ts:support_pipeline --dataset tickets.json --eval evals.ts:answer_quality
 ```
 
 The package also ships a helper CLI:

package/bin/discover.js

@@ -1,16 +1,201 @@
 #!/usr/bin/env node
 /**
- * zhanla-sdk-ts discover <file.ts>
+ * zhanla-sdk-ts discover <file.ts[:ExportName]>
+ *
+ * Loads a TypeScript module via tsx, walks the transitive closure from a
+ * named root (or all exported roots if no name given), and emits the full
+ * closure as a JSON array to stdout (leaf-first order).
  *
- * Loads a TypeScript module via tsx, collects exported BaseComponent instances,
- * emits their manifests as a JSON array to stdout.
  * Exits non-zero if no components are found or the file fails to load.
  */
 
 import { pathToFileURL } from "url";
 import { resolve } from "path";
 
-export async function runDiscover(filePath) {
+function isComponentLike(value) {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    typeof value.componentType === "string" &&
+    typeof value.name === "string" &&
+    typeof value.key === "string"
+  );
+}
+
+function isConditionalLike(value) {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    typeof value.condition === "function" &&
+    typeof value.ifTrue === "string" &&
+    typeof value.ifFalse === "string"
+  );
+}
+
+function getBranchChildren(node) {
+  if (!node) return [];
+  const children = [];
+  if (node.eval && isComponentLike(node.eval)) children.push(node.eval);
+  for (const edge of [...(node.ifPass || []), ...(node.ifFail || [])]) {
+    if (edge && edge.node) children.push(...getBranchChildren(edge.node));
+  }
+  return children;
+}
+
+function getChildren(comp) {
+  const children = [];
+  for (const attr of ["tools", "skills", "agents", "evals"]) {
+    if (Array.isArray(comp[attr])) {
+      children.push(...comp[attr].filter(isComponentLike));
+    }
+  }
+  if (comp.componentType === "orchestration" && Array.isArray(comp.steps)) {
+    for (const step of comp.steps) {
+      if (step.component && !isConditionalLike(step.component) && isComponentLike(step.component)) {
+        children.push(step.component);
+      }
+    }
+  }
+  if (comp.componentType === "eval_tree" && comp.root) {
+    children.push(...getBranchChildren(comp.root));
+  }
+  return children;
+}
+
+function stableSerialize(value) {
+  if (Array.isArray(value)) {
+    return `[${value.map((entry) => stableSerialize(entry)).join(",")}]`;
+  }
+  if (value != null && typeof value === "object") {
+    const entries = Object.entries(value)
+      .filter(([, entry]) => entry !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries
+      .map(([key, entry]) => `${JSON.stringify(key)}:${stableSerialize(entry)}`)
+      .join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+
+function sortRefsByKey(refs) {
+  return [...refs].sort((left, right) => left.key.localeCompare(right.key));
+}
+
+function behaviorFields(manifest) {
+  const fields = {
+    component_type: manifest.component_type,
+    execution_mode: manifest.execution_mode,
+  };
+
+  if (manifest.instructions != null) fields.instructions = manifest.instructions;
+  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.weights != null) fields.weights = manifest.weights;
+  if (manifest.root != null) fields.root = 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;
+  }
+  if (manifest.fn_present != null) fields.fn_present = manifest.fn_present;
+  if (manifest.is_async != null) fields.is_async = manifest.is_async;
+
+  return fields;
+}
+
+function manifestBehaviorSignature(manifest) {
+  return stableSerialize(behaviorFields(manifest));
+}
+
+function getManifestOptions(comp, filePath, symbolByComponent, fallbackToName = false) {
+  const symbolName = symbolByComponent.get(comp);
+  return {
+    filePath,
+    symbolName: symbolName ?? (fallbackToName ? comp.name : undefined),
+  };
+}
+
+export function collectClosureManifests(roots, toManifest, filePath, symbolByComponent) {
+  const seen = new Map();
+  const signaturesByKey = new Map();
+  const order = [];
+
+  function visit(comp) {
+    const closureKey = `${comp.componentType}:${comp.key}`;
+    const existing = seen.get(closureKey);
+    if (existing) {
+      if (existing !== comp) {
+        const signature = manifestBehaviorSignature(
+          toManifest(comp, getManifestOptions(comp, filePath, symbolByComponent))
+        );
+        if (signaturesByKey.get(closureKey) !== signature) {
+          throw new Error(
+            `Conflict: two different ${comp.componentType} objects claim key '${comp.key}' but have different behavior.`
+          );
+        }
+      }
+      return;
+    }
+
+    seen.set(closureKey, comp);
+    const manifest = toManifest(comp, getManifestOptions(comp, filePath, symbolByComponent));
+    signaturesByKey.set(closureKey, manifestBehaviorSignature(manifest));
+
+    for (const child of getChildren(comp)) {
+      visit(child);
+    }
+    order.push(comp);
+  }
+
+  for (const root of roots) {
+    visit(root);
+  }
+
+  return order.map((comp) =>
+    toManifest(comp, {
+      filePath,
+      symbolName: symbolByComponent.get(comp) ?? comp.name,
+    })
+  );
+}
+
+export function buildDiscoveredManifests({
+  allComponents,
+  symbolByComponent,
+  symbolName,
+  toManifest,
+  filePath,
+}) {
+  if (symbolName) {
+    const root = allComponents.find(
+      (c) => symbolByComponent.get(c) === symbolName || c.name === symbolName
+    );
+    if (!root) {
+      const available = allComponents.map((c) => symbolByComponent.get(c) ?? c.name).join(", ");
+      throw new Error(`Component '${symbolName}' not found in ${filePath}. Available: ${available}`);
+    }
+    return collectClosureManifests([root], toManifest, filePath, symbolByComponent);
+  }
+
+  return collectClosureManifests(allComponents, toManifest, filePath, symbolByComponent);
+}
+
+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 absolutePath = resolve(filePath);
   const fileUrl = pathToFileURL(absolutePath).href;
 
@@ -22,26 +207,25 @@ export async function runDiscover(filePath) {
     process.exit(1);
   }
 
-  // Dynamically import from the built SDK (or tsx will resolve from node_modules)
   let collectExportedComponents, toManifest;
   try {
     const sdk = await import("@zhanla/sdk-ts");
     collectExportedComponents = sdk.collectExportedComponents;
     toManifest = sdk.toManifest;
   } catch {
-    // Fallback: try loading from relative path (dev mode)
     const sdk = await import(new URL("../dist/index.js", import.meta.url).href);
     collectExportedComponents = sdk.collectExportedComponents;
     toManifest = sdk.toManifest;
   }
 
-  const components = collectExportedComponents(moduleExports);
+  const allComponents = collectExportedComponents(moduleExports);
 
-  if (components.length === 0) {
+  if (allComponents.length === 0) {
     console.error(`No zhanla components found in ${filePath}`);
     process.exit(1);
   }
 
+  // Build symbol name map for exported components
   const symbolByComponent = new Map();
   const namespaces = [moduleExports];
   if (
@@ -59,12 +243,19 @@ export async function runDiscover(filePath) {
     }
   }
 
-  const manifests = components.map((comp) =>
-    toManifest(comp, {
+  let manifests;
+  try {
+    manifests = buildDiscoveredManifests({
+      allComponents,
+      symbolByComponent,
+      symbolName,
+      toManifest,
       filePath: absolutePath,
-      symbolName: symbolByComponent.get(comp) ?? comp.name,
-    })
-  );
+    });
+  } catch (err) {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+  }
 
   process.stdout.write(JSON.stringify(manifests) + "\n");
 }

package/dist/executor.js

@@ -213,6 +213,8 @@ function validateSchemaValue(value, schema, path = "$") {
             return typeof value === "string" ? [] : [`${path} must be a string`];
         case "number":
             return typeof value === "number" ? [] : [`${path} must be a number`];
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value) ? [] : [`${path} must be an integer`];
         case "boolean":
             return typeof value === "boolean" ? [] : [`${path} must be a boolean`];
         case "null":
@@ -241,6 +243,8 @@ async function runRunnerComponent(comp, kwargs) {
         tools: "tools" in comp ? comp.tools : [],
         outputSchema: comp.outputSchema,
         jsonRepair: comp.jsonRepair,
+        temperature: "temperature" in comp ? comp.temperature : undefined,
+        topK: "topK" in comp ? comp.topK : undefined,
     });
     const hasTextOutput = response.text.trim() !== "";
     const hasToolCalls = response.toolCalls.length > 0;

package/dist/manifest.d.ts

@@ -2,10 +2,10 @@
  * 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";
+import { BaseComponent, ComponentRef, JsonSchema } from "./types.js";
 export interface StepManifest {
     name: string;
-    component: string;
+    component_ref?: ComponentRef;
     next: string[];
     is_conditional?: boolean;
     if_true?: string;
@@ -17,11 +17,11 @@ export interface EdgeManifest {
 }
 export interface LeafManifest {
     type: "leaf";
-    eval: string;
+    eval_ref: ComponentRef;
 }
 export interface BranchManifest {
     type: "branch";
-    eval: string;
+    eval_ref: ComponentRef;
     threshold: number;
     if_pass: EdgeManifest[];
     if_fail: EdgeManifest[];
@@ -30,19 +30,28 @@ export interface ComponentManifest {
     name: string;
     description: string;
     component_type: string;
+    /** Stable component identity — explicit if dev provided key, otherwise slugified from name. */
+    key: string;
+    /** "explicit" | "implicit" */
+    key_source: string;
     language: "typescript";
     is_runnable: boolean;
     is_eval: boolean;
-    version_hash: string;
+    execution_mode: string;
     instructions?: string;
     model?: string;
+    temperature?: number;
     fn_present?: boolean;
     is_async?: boolean;
-    tools?: string[];
-    skills?: string[];
-    agents?: string[];
+    /** Typed tool references. */
+    tool_refs?: ComponentRef[];
+    /** Typed skill references. */
+    skill_refs?: ComponentRef[];
+    /** Typed agent references. */
+    agent_refs?: ComponentRef[];
     steps?: StepManifest[];
-    evals?: string[];
+    /** Typed eval references for Checklist. */
+    eval_refs?: ComponentRef[];
     weights?: number[];
     root?: BranchManifest;
     output_schema?: JsonSchema;

package/dist/manifest.js

@@ -12,7 +12,8 @@ function isComponentLike(value) {
         typeof value.componentType === "string" &&
         typeof value.name === "string" &&
         typeof value.description === "string" &&
-        typeof value.versionHash === "function");
+        typeof value.isRunnable === "boolean" &&
+        typeof value.isEval === "boolean");
 }
 function isConditionalLike(value) {
     return (value != null &&
@@ -27,18 +28,27 @@ function isLeafLike(value) {
         "eval" in value &&
         !("threshold" in value));
 }
+function resolveComponentRef(component) {
+    return {
+        key: component.key,
+        component_type: component.componentType,
+        name: component.name,
+        language: "typescript",
+        execution_mode: EXECUTION_MODES[component.componentType] ?? "unknown",
+    };
+}
 function serializeEdge(edge) {
     return {
         weight: edge.weight,
         node: isLeafLike(edge.node)
-            ? { type: "leaf", eval: edge.node.eval.name }
+            ? { type: "leaf", eval_ref: resolveComponentRef(edge.node.eval) }
             : serializeBranch(edge.node),
     };
 }
 function serializeBranch(branch) {
     return {
         type: "branch",
-        eval: branch.eval.name,
+        eval_ref: resolveComponentRef(branch.eval),
         threshold: branch.threshold,
         if_pass: branch.ifPass.map(serializeEdge),
         if_fail: branch.ifFail.map(serializeEdge),
@@ -128,16 +138,32 @@ function extractExportedComponentSource(filePath, symbolName) {
 // ---------------------------------------------------------------------------
 // to_manifest
 // ---------------------------------------------------------------------------
+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",
+};
 export function toManifest(component, opts = {}) {
     const componentSource = extractExportedComponentSource(opts.filePath, opts.symbolName);
+    const key = component.key;
+    const keySource = "explicit";
+    const executionMode = EXECUTION_MODES[component.componentType] ?? "unknown";
     const base = {
         name: component.name,
         description: component.description,
         component_type: component.componentType,
+        key,
+        key_source: keySource,
         language: "typescript",
         is_runnable: component.isRunnable,
         is_eval: component.isEval,
-        version_hash: component.versionHash(),
+        execution_mode: executionMode,
         file_path: opts.filePath,
         symbol_name: opts.symbolName,
     };
@@ -173,7 +199,7 @@ export function toManifest(component, opts = {}) {
                 instructions: skill.instructions,
                 fn_present: skill.fn != null,
                 is_async: skill.isAsync,
-                tools: skill.tools.map((t) => t.name),
+                tool_refs: skill.tools.length > 0 ? skill.tools.map(resolveComponentRef) : undefined,
                 output_schema: skill.outputSchema,
                 source_code: componentSource || skill.fn?.toString(),
                 source_language: "typescript",
@@ -186,9 +212,10 @@ export function toManifest(component, opts = {}) {
                 ...base,
                 instructions: agent.instructions,
                 model: agent.model,
-                tools: agent.tools.map((t) => t.name),
-                skills: agent.skills.map((s) => s.name),
-                agents: agent.agents.map((a) => a.name),
+                temperature: agent.temperature,
+                tool_refs: agent.tools.length > 0 ? agent.tools.map(resolveComponentRef) : undefined,
+                skill_refs: agent.skills.length > 0 ? agent.skills.map(resolveComponentRef) : undefined,
+                agent_refs: agent.agents.length > 0 ? agent.agents.map(resolveComponentRef) : undefined,
                 output_schema: agent.outputSchema,
             };
         }
@@ -198,6 +225,7 @@ export function toManifest(component, opts = {}) {
                 ...base,
                 instructions: llmProcessor.instructions,
                 model: llmProcessor.model,
+                temperature: llmProcessor.temperature,
                 output_schema: llmProcessor.outputSchema,
             };
         }
@@ -207,6 +235,7 @@ export function toManifest(component, opts = {}) {
                 ...base,
                 instructions: llmEval.instructions,
                 model: llmEval.model,
+                temperature: llmEval.temperature,
                 output_schema: llmEval.outputSchema,
             };
         }
@@ -216,16 +245,15 @@ export function toManifest(component, opts = {}) {
                 if (isConditionalLike(s.component)) {
                     return {
                         name: s.name,
-                        component: "conditional",
-                        next: s.next,
                         is_conditional: true,
                         if_true: s.component.ifTrue,
                         if_false: s.component.ifFalse,
+                        next: s.next,
                     };
                 }
                 return {
                     name: s.name,
-                    component: s.component.name,
+                    component_ref: resolveComponentRef(s.component),
                     next: s.next,
                 };
             });
@@ -235,7 +263,7 @@ export function toManifest(component, opts = {}) {
             const checklist = component;
             return {
                 ...base,
-                evals: checklist.evals.map((e) => e.name),
+                eval_refs: checklist.evals.length > 0 ? checklist.evals.map(resolveComponentRef) : undefined,
                 weights: checklist.weights,
             };
         }

package/dist/types.d.ts

@@ -3,7 +3,7 @@
  * Mirrors the Python SDK's class-based component model.
  */
 export type JsonSchemaScalar = {
-    type: "string" | "number" | "boolean" | "null";
+    type: "string" | "number" | "integer" | "boolean" | "null";
 };
 export type JsonSchemaObject = {
     type: "object";
@@ -17,8 +17,19 @@ export type JsonSchemaArray = {
 };
 export type JsonSchema = JsonSchemaScalar | JsonSchemaObject | JsonSchemaArray | Record<string, unknown>;
 export type ComponentType = "tool" | "code_eval" | "skill" | "agent" | "llm_processor" | "llm_eval" | "orchestration" | "checklist" | "eval_tree";
+export interface ComponentRef {
+    key: string;
+    component_type: string;
+    name: string;
+    language: string;
+    execution_mode: string;
+}
 export declare const RUNNABLE_TYPES: Set<ComponentType>;
 export declare const EVAL_TYPES: Set<ComponentType>;
+/** Slugify a component name into a key-safe string (implicit key derivation). */
+export declare function slugifyKey(name: string): string;
+/** Throw if `key` does not meet the component key format requirements. */
+export declare function validateKey(key: string, componentName: string): void;
 export interface ToolCall {
     name: string;
     input: Record<string, unknown>;
@@ -40,6 +51,8 @@ export interface RunnerCallOptions {
     tools?: Tool[];
     outputSchema?: JsonSchema;
     jsonRepair?: boolean;
+    temperature?: number;
+    topK?: number;
 }
 export interface RunnerOptions {
     client: unknown;
@@ -65,9 +78,9 @@ export declare abstract class BaseComponent {
     abstract readonly componentType: ComponentType;
     abstract readonly name: string;
     abstract readonly description: string;
+    abstract readonly key: string;
     get isRunnable(): boolean;
     get isEval(): boolean;
-    abstract versionHash(): string;
 }
 export interface ToolOptions {
     name: string;
@@ -75,6 +88,7 @@ export interface ToolOptions {
     fn: (...args: unknown[]) => unknown;
     inputSchema: JsonSchema;
     outputSchema?: JsonSchema;
+    key: string;
 }
 export declare class Tool extends BaseComponent {
     readonly componentType: "tool";
@@ -84,14 +98,15 @@ export declare class Tool extends BaseComponent {
     readonly inputSchema: JsonSchema;
     readonly outputSchema?: JsonSchema;
     readonly isAsync: boolean;
+    readonly key: string;
     constructor(opts: ToolOptions);
-    versionHash(): string;
 }
 export interface CodeEvalOptions {
     name: string;
     description: string;
     fn: (...args: unknown[]) => unknown;
     modelResponseFormat?: "JSON" | "TEXT" | "YAML";
+    key: string;
 }
 export declare class CodeEval extends BaseComponent {
     readonly componentType: "code_eval";
@@ -100,8 +115,8 @@ export declare class CodeEval extends BaseComponent {
     readonly fn: (...args: unknown[]) => unknown;
     readonly isAsync: boolean;
     readonly modelResponseFormat: "JSON" | "TEXT" | "YAML";
+    readonly key: string;
     constructor(opts: CodeEvalOptions);
-    versionHash(): string;
 }
 export interface SkillOptions {
     name: string;
@@ -110,6 +125,7 @@ export interface SkillOptions {
     tools?: Tool[];
     fn?: (...args: unknown[]) => unknown;
     outputSchema?: JsonSchema;
+    key: string;
 }
 export declare class Skill extends BaseComponent {
     readonly componentType: "skill";
@@ -120,8 +136,8 @@ export declare class Skill extends BaseComponent {
     readonly fn?: (...args: unknown[]) => unknown;
     readonly outputSchema?: JsonSchema;
     readonly isAsync: boolean;
+    readonly key: string;
     constructor(opts: SkillOptions);
-    versionHash(): string;
 }
 export interface AgentOptions {
     name: string;
@@ -134,6 +150,9 @@ export interface AgentOptions {
     agents?: Agent[];
     outputSchema?: JsonSchema;
     jsonRepair?: boolean;
+    temperature?: number;
+    topK?: number;
+    key: string;
 }
 export declare class Agent extends BaseComponent {
     readonly componentType: "agent";
@@ -147,8 +166,10 @@ export declare class Agent extends BaseComponent {
     readonly agents: Agent[];
     readonly outputSchema?: JsonSchema;
     readonly jsonRepair: boolean;
+    readonly temperature?: number;
+    readonly topK?: number;
+    readonly key: string;
     constructor(opts: AgentOptions);
-    versionHash(): string;
 }
 export interface LLMProcessorOptions {
     name: string;
@@ -158,6 +179,9 @@ export interface LLMProcessorOptions {
     runner?: Runner;
     outputSchema?: JsonSchema;
     jsonRepair?: boolean;
+    temperature?: number;
+    topK?: number;
+    key: string;
 }
 export declare class LLMProcessor extends BaseComponent {
     readonly componentType: "llm_processor";
@@ -168,8 +192,10 @@ export declare class LLMProcessor extends BaseComponent {
     readonly runner?: Runner;
     readonly outputSchema?: JsonSchema;
     readonly jsonRepair: boolean;
+    readonly temperature?: number;
+    readonly topK?: number;
+    readonly key: string;
     constructor(opts: LLMProcessorOptions);
-    versionHash(): string;
 }
 export interface LLMEvalOptions {
     name: string;
@@ -179,6 +205,9 @@ export interface LLMEvalOptions {
     runner?: Runner;
     outputSchema?: JsonSchema;
     jsonRepair?: boolean;
+    temperature?: number;
+    topK?: number;
+    key: string;
 }
 export declare class LLMEval extends BaseComponent {
     readonly componentType: "llm_eval";
@@ -189,8 +218,10 @@ export declare class LLMEval extends BaseComponent {
     readonly runner?: Runner;
     readonly outputSchema?: JsonSchema;
     readonly jsonRepair: boolean;
+    readonly temperature?: number;
+    readonly topK?: number;
+    readonly key: string;
     constructor(opts: LLMEvalOptions);
-    versionHash(): string;
 }
 export interface ConditionalOptions {
     condition: (ctx: Record<string, unknown>) => boolean;
@@ -218,14 +249,15 @@ export interface OrchestrationOptions {
     name: string;
     description: string;
     steps: Step[];
+    key: string;
 }
 export declare class Orchestration extends BaseComponent {
     readonly componentType: "orchestration";
     readonly name: string;
     readonly description: string;
     readonly steps: Step[];
+    readonly key: string;
     constructor(opts: OrchestrationOptions);
-    versionHash(): string;
 }
 export declare class Leaf {
     readonly eval: BaseComponent;
@@ -258,6 +290,7 @@ export interface ChecklistOptions {
     description: string;
     evals: BaseComponent[];
     weights?: number[];
+    key: string;
 }
 export declare class Checklist extends BaseComponent {
     readonly componentType: "checklist";
@@ -265,19 +298,20 @@ export declare class Checklist extends BaseComponent {
     readonly description: string;
     readonly evals: BaseComponent[];
     readonly weights?: number[];
+    readonly key: string;
     constructor(opts: ChecklistOptions);
-    versionHash(): string;
 }
 export interface EvalTreeOptions {
     name: string;
     description: string;
     root: Branch;
+    key: string;
 }
 export declare class EvalTree extends BaseComponent {
     readonly componentType: "eval_tree";
     readonly name: string;
     readonly description: string;
     readonly root: Branch;
+    readonly key: string;
     constructor(opts: EvalTreeOptions);
-    versionHash(): string;
 }

package/dist/types.js

@@ -2,7 +2,6 @@
  * Core types for the bench TypeScript SDK.
  * Mirrors the Python SDK's class-based component model.
  */
-import { createHash } from "crypto";
 import { parseJsonResponse } from "./json.js";
 import { isAnthropicClient, isGeminiClient, isOpenAIClient, wrap } from "./wrap.js";
 export const RUNNABLE_TYPES = new Set([
@@ -18,30 +17,29 @@ export const EVAL_TYPES = new Set([
     "eval_tree",
 ]);
 // ---------------------------------------------------------------------------
-// Hashing utilities
+// Key validation
 // ---------------------------------------------------------------------------
-function hashFields(...parts) {
-    const h = createHash("sha256");
-    for (const p of parts) {
-        h.update(p, "utf8");
-    }
-    return h.digest("hex");
+const KEY_PATTERN = /^[a-z0-9-]+$/;
+const KEY_MAX_LEN = 64;
+/** Slugify a component name into a key-safe string (implicit key derivation). */
+export function slugifyKey(name) {
+    let slug = name.toLowerCase().trim();
+    slug = slug.replace(/[^\w\s-]/g, "");
+    slug = slug.replace(/[\s_]+/g, "-");
+    slug = slug.replace(/-+/g, "-").replace(/^-|-$/g, "");
+    return slug.slice(0, KEY_MAX_LEN);
 }
-function sortedStringify(value) {
-    if (value === null || typeof value !== "object") {
-        return JSON.stringify(value);
+/** Throw if `key` does not meet the component key format requirements. */
+export function validateKey(key, componentName) {
+    if (!key) {
+        throw new Error(`Component '${componentName}': key must not be empty`);
     }
-    if (Array.isArray(value)) {
-        return "[" + value.map(sortedStringify).join(",") + "]";
+    if (!KEY_PATTERN.test(key)) {
+        throw new Error(`Component '${componentName}': key '${key}' must contain only lowercase letters, digits, and hyphens ([a-z0-9-])`);
+    }
+    if (key.length > KEY_MAX_LEN) {
+        throw new Error(`Component '${componentName}': key '${key}' is too long (max ${KEY_MAX_LEN} chars, got ${key.length})`);
     }
-    const keys = Object.keys(value).sort();
-    const parts = keys.map((k) => `${JSON.stringify(k)}:${sortedStringify(value[k])}`);
-    return "{" + parts.join(",") + "}";
-}
-function normalizeSchema(schema) {
-    if (schema == null)
-        return "";
-    return sortedStringify(schema);
 }
 function isPlainRecord(value) {
     return value != null && typeof value === "object" && !Array.isArray(value);
@@ -84,11 +82,6 @@ function previewText(text, limit = 160) {
     const normalized = text.replace(/\s+/g, " ").trim();
     return normalized.length <= limit ? normalized : `${normalized.slice(0, limit)}...`;
 }
-function fnSource(fn) {
-    if (fn == null)
-        return "";
-    return fn.toString();
-}
 function contentPartToText(part) {
     if (typeof part === "string") {
         return part;
@@ -289,6 +282,8 @@ export class Runner {
                     description: tool.description,
                     input_schema: withClosedAdditionalProperties(tool.inputSchema),
                 })),
+                ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+                ...(opts.topK !== undefined ? { top_k: opts.topK } : {}),
             });
             const content = Array.isArray(response.content)
                 ? response.content
@@ -335,6 +330,7 @@ export class Runner {
                         parameters: withClosedAdditionalProperties(tool.inputSchema),
                     },
                 })),
+                ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
             });
             const choice = Array.isArray(response.choices)
                 ? response.choices[0]
@@ -385,6 +381,8 @@ export class Runner {
                                 parameters: toGeminiSchema(tool.inputSchema),
                             }],
                     })),
+                    ...(opts.temperature !== undefined ? { temperature: opts.temperature } : {}),
+                    ...(opts.topK !== undefined ? { topK: opts.topK } : {}),
                 },
             });
             const candidates = Array.isArray(response.candidates)
@@ -444,6 +442,7 @@ export class Tool extends BaseComponent {
     inputSchema;
     outputSchema;
     isAsync;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
@@ -452,9 +451,8 @@ export class Tool extends BaseComponent {
         this.inputSchema = validateToolInputSchema(opts.inputSchema);
         this.outputSchema = opts.outputSchema;
         this.isAsync = opts.fn.constructor.name === "AsyncFunction";
-    }
-    versionHash() {
-        return hashFields(this.componentType, fnSource(this.fn), normalizeSchema(this.inputSchema), normalizeSchema(this.outputSchema));
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }
 export class CodeEval extends BaseComponent {
@@ -464,6 +462,7 @@ export class CodeEval extends BaseComponent {
     fn;
     isAsync;
     modelResponseFormat;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
@@ -471,9 +470,8 @@ export class CodeEval extends BaseComponent {
         this.fn = opts.fn;
         this.isAsync = opts.fn.constructor.name === "AsyncFunction";
         this.modelResponseFormat = opts.modelResponseFormat ?? "JSON";
-    }
-    versionHash() {
-        return hashFields(this.componentType, fnSource(this.fn), this.modelResponseFormat);
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }
 export class Skill extends BaseComponent {
@@ -485,6 +483,7 @@ export class Skill extends BaseComponent {
     fn;
     outputSchema;
     isAsync;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
@@ -494,10 +493,8 @@ export class Skill extends BaseComponent {
         this.fn = opts.fn;
         this.outputSchema = opts.outputSchema;
         this.isAsync = opts.fn?.constructor.name === "AsyncFunction";
-    }
-    versionHash() {
-        const toolRefs = [...this.tools.map((t) => t.name)].sort().join(",");
-        return hashFields(this.componentType, this.instructions, toolRefs, fnSource(this.fn));
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }
 export class Agent extends BaseComponent {
@@ -512,6 +509,9 @@ export class Agent extends BaseComponent {
     agents;
     outputSchema;
     jsonRepair;
+    temperature;
+    topK;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
@@ -524,12 +524,10 @@ export class Agent extends BaseComponent {
         this.agents = opts.agents ?? [];
         this.outputSchema = opts.outputSchema;
         this.jsonRepair = opts.jsonRepair ?? false;
-    }
-    versionHash() {
-        const toolRefs = [...this.tools.map((t) => t.name)].sort().join(",");
-        const skillRefs = [...this.skills.map((s) => s.name)].sort().join(",");
-        const agentRefs = [...this.agents.map((a) => a.name)].sort().join(",");
-        return hashFields(this.componentType, this.instructions, this.model, toolRefs, skillRefs, agentRefs, normalizeSchema(this.outputSchema));
+        this.temperature = opts.temperature;
+        this.topK = opts.topK;
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }
 export class LLMProcessor extends BaseComponent {
@@ -541,6 +539,9 @@ export class LLMProcessor extends BaseComponent {
     runner;
     outputSchema;
     jsonRepair;
+    temperature;
+    topK;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
@@ -550,9 +551,10 @@ export class LLMProcessor extends BaseComponent {
         this.runner = opts.runner;
         this.outputSchema = opts.outputSchema;
         this.jsonRepair = opts.jsonRepair ?? false;
-    }
-    versionHash() {
-        return hashFields(this.componentType, this.instructions, this.model, normalizeSchema(this.outputSchema));
+        this.temperature = opts.temperature;
+        this.topK = opts.topK;
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }
 export class LLMEval extends BaseComponent {
@@ -564,6 +566,9 @@ export class LLMEval extends BaseComponent {
     runner;
     outputSchema;
     jsonRepair;
+    temperature;
+    topK;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
@@ -573,9 +578,10 @@ export class LLMEval extends BaseComponent {
         this.runner = opts.runner;
         this.outputSchema = opts.outputSchema;
         this.jsonRepair = opts.jsonRepair ?? false;
-    }
-    versionHash() {
-        return hashFields(this.componentType, this.instructions, this.model, normalizeSchema(this.outputSchema));
+        this.temperature = opts.temperature;
+        this.topK = opts.topK;
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }
 export class Conditional {
@@ -603,18 +609,14 @@ export class Orchestration extends BaseComponent {
     name;
     description;
     steps;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
         this.description = opts.description;
         this.steps = opts.steps;
-    }
-    versionHash() {
-        const stepParts = this.steps.map((s) => {
-            const compRef = s.component instanceof Conditional ? "conditional" : s.component.name;
-            return `${s.name}:${compRef}:${s.next.join(",")}`;
-        });
-        return hashFields(this.componentType, stepParts.join("|"));
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }
 // ---------------------------------------------------------------------------
@@ -652,46 +654,29 @@ export class Checklist extends BaseComponent {
     description;
     evals;
     weights;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
         this.description = opts.description;
         this.evals = opts.evals;
         this.weights = opts.weights;
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
-    versionHash() {
-        const evalRefs = this.evals.map((e) => e.name).join(",");
-        const w = this.weights ? this.weights.join(",") : "";
-        return hashFields(this.componentType, evalRefs, w);
-    }
-}
-// ---------------------------------------------------------------------------
-// EvalTree
-// ---------------------------------------------------------------------------
-function treeHashParts(node) {
-    if (node instanceof Leaf) {
-        return `leaf:${node.eval.name}`;
-    }
-    if (node instanceof Edge) {
-        return `edge:${node.weight}:${treeHashParts(node.node)}`;
-    }
-    // Branch
-    const passParts = node.ifPass.map(treeHashParts).join("|");
-    const failParts = node.ifFail.map(treeHashParts).join("|");
-    return `branch:${node.eval.name}:${node.threshold}:[${passParts}]:[${failParts}]`;
 }
 export class EvalTree extends BaseComponent {
     componentType = "eval_tree";
     name;
     description;
     root;
+    key;
     constructor(opts) {
         super();
         this.name = opts.name;
         this.description = opts.description;
         this.root = opts.root;
-    }
-    versionHash() {
-        return hashFields(this.componentType, treeHashParts(this.root));
+        validateKey(opts.key, opts.name);
+        this.key = opts.key;
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhanla/sdk-ts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript SDK for the zhanla CLI — define and run AI components locally",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,6 @@
     "dist",
     "bin"
   ],
-
   "devDependencies": {
     "typescript": "^5.4.0",
     "vitest": "^1.4.0",