@vextlabs/theron-agent-sdk 0.3.0

package/dist/agent/index.d.cts

@@ -0,0 +1,84 @@
+import { Tool, ToolSchema } from '../tools/index.cjs';
+import { Verifier } from '../verifiers/index.cjs';
+import 'zod';
+
+interface AgentInstruction {
+    /** System prompt or persona instruction. */
+    system: string;
+    /** Optional few-shot exemplars. */
+    examples?: {
+        user: string;
+        assistant: string;
+    }[];
+}
+interface AgentConfig {
+    /** Display name. Used for logging + routing. */
+    name: string;
+    /** Model identifier. Defaults to whatever the Runner is configured for.
+     *  Examples: "gpt-4o", "claude-3-5-sonnet", "theron-base-v8@cyber". */
+    model?: string;
+    /** Instructions to the model. Either a string (shorthand for {system: ...})
+     *  or a full AgentInstruction object. */
+    instruction: string | AgentInstruction;
+    /** Tools the agent may call. */
+    tools?: Tool[];
+    /** Sub-agents the agent may delegate to. */
+    sub_agents?: Agent[];
+    /** Verifier kernels that run against the final output. Failures are
+     *  reported in AgentResult.verifier_results but do not throw — callers
+     *  decide how to react. Use Council if you want gating + reconciliation. */
+    verifiers?: Verifier[];
+    /** Optional max-turn cap. Defaults to runner default. */
+    max_turns?: number;
+}
+interface AgentResult {
+    agent: string;
+    output: string;
+    tool_calls: Array<{
+        name: string;
+        input: unknown;
+        output: unknown;
+    }>;
+    verifier_results: Array<{
+        kernel: string;
+        pass: boolean;
+        issues: unknown[];
+        ms: number;
+    }>;
+    tokens_used: {
+        input: number;
+        output: number;
+    };
+    cost_usd: number;
+    latency_ms: number;
+}
+/**
+ * The Agent primitive.
+ *
+ * Minimal usage:
+ *   const a = new Agent({ name: "helper", instruction: "You are helpful." });
+ *
+ * With tools + verifiers:
+ *   const a = new Agent({
+ *     name: "researcher",
+ *     instruction: "Answer with citations.",
+ *     tools: [webSearch, fetchUrl],
+ *     verifiers: [VerifierKernels.citationPresence],
+ *   });
+ */
+declare class Agent {
+    readonly name: string;
+    readonly model: string | undefined;
+    readonly instruction: AgentInstruction;
+    readonly tools: Tool[];
+    readonly sub_agents: Agent[];
+    readonly verifiers: Verifier[];
+    readonly max_turns: number;
+    constructor(config: AgentConfig);
+    /** Render the tools as JSON schemas for the model. */
+    toolSchemas(): ToolSchema[];
+    /** True if the agent has any sub-agents (i.e., this is a supervisor). */
+    isSupervisor(): boolean;
+}
+
+export { Agent, type AgentConfig, type AgentInstruction, type AgentResult };

package/dist/agent/index.d.ts

@@ -0,0 +1,84 @@
+import { Tool, ToolSchema } from '../tools/index.js';
+import { Verifier } from '../verifiers/index.js';
+import 'zod';
+
+interface AgentInstruction {
+    /** System prompt or persona instruction. */
+    system: string;
+    /** Optional few-shot exemplars. */
+    examples?: {
+        user: string;
+        assistant: string;
+    }[];
+}
+interface AgentConfig {
+    /** Display name. Used for logging + routing. */
+    name: string;
+    /** Model identifier. Defaults to whatever the Runner is configured for.
+     *  Examples: "gpt-4o", "claude-3-5-sonnet", "theron-base-v8@cyber". */
+    model?: string;
+    /** Instructions to the model. Either a string (shorthand for {system: ...})
+     *  or a full AgentInstruction object. */
+    instruction: string | AgentInstruction;
+    /** Tools the agent may call. */
+    tools?: Tool[];
+    /** Sub-agents the agent may delegate to. */
+    sub_agents?: Agent[];
+    /** Verifier kernels that run against the final output. Failures are
+     *  reported in AgentResult.verifier_results but do not throw — callers
+     *  decide how to react. Use Council if you want gating + reconciliation. */
+    verifiers?: Verifier[];
+    /** Optional max-turn cap. Defaults to runner default. */
+    max_turns?: number;
+}
+interface AgentResult {
+    agent: string;
+    output: string;
+    tool_calls: Array<{
+        name: string;
+        input: unknown;
+        output: unknown;
+    }>;
+    verifier_results: Array<{
+        kernel: string;
+        pass: boolean;
+        issues: unknown[];
+        ms: number;
+    }>;
+    tokens_used: {
+        input: number;
+        output: number;
+    };
+    cost_usd: number;
+    latency_ms: number;
+}
+/**
+ * The Agent primitive.
+ *
+ * Minimal usage:
+ *   const a = new Agent({ name: "helper", instruction: "You are helpful." });
+ *
+ * With tools + verifiers:
+ *   const a = new Agent({
+ *     name: "researcher",
+ *     instruction: "Answer with citations.",
+ *     tools: [webSearch, fetchUrl],
+ *     verifiers: [VerifierKernels.citationPresence],
+ *   });
+ */
+declare class Agent {
+    readonly name: string;
+    readonly model: string | undefined;
+    readonly instruction: AgentInstruction;
+    readonly tools: Tool[];
+    readonly sub_agents: Agent[];
+    readonly verifiers: Verifier[];
+    readonly max_turns: number;
+    constructor(config: AgentConfig);
+    /** Render the tools as JSON schemas for the model. */
+    toolSchemas(): ToolSchema[];
+    /** True if the agent has any sub-agents (i.e., this is a supervisor). */
+    isSupervisor(): boolean;
+}
+
+export { Agent, type AgentConfig, type AgentInstruction, type AgentResult };

package/dist/agent/index.js

@@ -0,0 +1,31 @@
+// src/agent/index.ts
+var Agent = class {
+  name;
+  model;
+  instruction;
+  tools;
+  sub_agents;
+  verifiers;
+  max_turns;
+  constructor(config) {
+    if (!config.name) throw new Error("Agent requires a `name`.");
+    if (!config.instruction) throw new Error(`Agent "${config.name}" requires an \`instruction\`.`);
+    this.name = config.name;
+    this.model = config.model;
+    this.instruction = typeof config.instruction === "string" ? { system: config.instruction } : config.instruction;
+    this.tools = config.tools ?? [];
+    this.sub_agents = config.sub_agents ?? [];
+    this.verifiers = config.verifiers ?? [];
+    this.max_turns = config.max_turns ?? 10;
+  }
+  /** Render the tools as JSON schemas for the model. */
+  toolSchemas() {
+    return this.tools.map((t) => t.schema);
+  }
+  /** True if the agent has any sub-agents (i.e., this is a supervisor). */
+  isSupervisor() {
+    return this.sub_agents.length > 0;
+  }
+};
+
+export { Agent };

package/dist/council/index.cjs

@@ -0,0 +1,68 @@
+'use strict';
+
+// src/council/index.ts
+var Council = class {
+  name;
+  specialists;
+  verifiers;
+  reconciler;
+  specialist_timeout_ms;
+  constructor(config) {
+    if (!config.name) throw new Error("Council requires a `name`.");
+    if (!config.specialists || config.specialists.length === 0) {
+      throw new Error(`Council "${config.name}" requires at least one specialist.`);
+    }
+    this.name = config.name;
+    this.specialists = config.specialists;
+    this.verifiers = config.verifiers ?? [];
+    this.reconciler = config.reconciler ?? deterministicClaimMerge;
+    this.specialist_timeout_ms = config.specialist_timeout_ms ?? 3e4;
+  }
+  /**
+   * Convenience entry point — pointed at the Runner you've already constructed.
+   * Most users will call `runner.runCouncil(council, query)` directly; this
+   * exists for symmetry with `agent.run`-style ergonomics in user code.
+   */
+  async deliberate(_query) {
+    throw new Error(
+      "Council.deliberate() requires a Runner. Use:\n  const runner = new Runner({ ... });\n  const result = await runner.runCouncil(council, query);\nSee: https://github.com/Vext-Labs-Inc/theron-agent-sdk/blob/main/examples/03_council_of_three.ts"
+    );
+  }
+};
+var deterministicClaimMerge = async (specialists) => {
+  if (specialists.length === 0) {
+    return { answer: "(no specialists responded)", consensus: "refuted" };
+  }
+  if (specialists.length === 1) {
+    return { answer: specialists[0].output, consensus: "ratified" };
+  }
+  const claimMap = /* @__PURE__ */ new Map();
+  for (const s of specialists) {
+    for (const c of s.claims) {
+      const key = c.text.toLowerCase().trim();
+      if (!claimMap.has(key)) claimMap.set(key, []);
+      claimMap.get(key).push(s.specialist);
+    }
+  }
+  const ratified = [];
+  const disagreements = [];
+  const majorityThreshold = specialists.length / 2;
+  for (const [claim, voters] of claimMap.entries()) {
+    if (voters.length === specialists.length) {
+      ratified.push(claim);
+    } else if (voters.length > majorityThreshold) {
+      ratified.push(claim);
+    } else {
+      disagreements.push({
+        claim,
+        specialists_for: voters,
+        specialists_against: specialists.map((s) => s.specialist).filter((n) => !voters.includes(n))
+      });
+    }
+  }
+  const answer = ratified.join(" ") || specialists[0].output;
+  const consensus = disagreements.length > 0 ? "split" : ratified.length > 0 ? "ratified" : "refuted";
+  return { answer, consensus, disagreements: disagreements.length > 0 ? disagreements : void 0 };
+};
+
+exports.Council = Council;

package/dist/council/index.d.cts

@@ -0,0 +1,96 @@
+import { Agent } from '../agent/index.cjs';
+import { Verifier, VerifierResult } from '../verifiers/index.cjs';
+import '../tools/index.cjs';
+import 'zod';
+
+/** Output of a single specialist's turn before reconciliation. */
+interface CouncilSpecialistOutput {
+    specialist: string;
+    output: string;
+    claims: Array<{
+        text: string;
+        confidence: number;
+        type: string;
+    }>;
+    verifier_results: VerifierResult[];
+    cost_usd: number;
+    latency_ms: number;
+}
+/** Final synthesized output after reconciliation. */
+interface CouncilOutput {
+    /** The synthesized final answer. */
+    answer: string;
+    /** Per-specialist outputs (visible if you want to surface deliberation). */
+    specialists: CouncilSpecialistOutput[];
+    /** Whether the council reached consensus or surfaced a disagreement. */
+    consensus: "ratified" | "split" | "refuted";
+    /** If split: what the disagreement was about. */
+    disagreements?: Array<{
+        claim: string;
+        specialists_for: string[];
+        specialists_against: string[];
+    }>;
+    /** Aggregated cost + latency. */
+    total_cost_usd: number;
+    total_latency_ms: number;
+}
+/**
+ * A reconciler synthesizes N specialist outputs into one answer.
+ *
+ * Two kinds:
+ *   - Deterministic reconcilers (regex / SMT / voting) — fast, cheap, no LLM
+ *   - LLM reconcilers (Theron-Reconciler-D or another model) — better synthesis,
+ *     more expensive
+ *
+ * The default is a deterministic claim-merging reconciler.
+ */
+type Reconciler = (specialists: CouncilSpecialistOutput[]) => Promise<{
+    answer: string;
+    consensus: "ratified" | "split" | "refuted";
+    disagreements?: CouncilOutput["disagreements"];
+}>;
+interface CouncilConfig {
+    /** Display name for the council. */
+    name: string;
+    /** The specialists that will deliberate. Order doesn't matter. */
+    specialists: Agent[];
+    /** Verifier kernels run against each specialist output before reconciliation. */
+    verifiers?: Verifier[];
+    /** How to synthesize the specialist outputs. Defaults to deterministic claim-merge. */
+    reconciler?: Reconciler;
+    /** Optional timeout per specialist (ms). Slow specialists are dropped. */
+    specialist_timeout_ms?: number;
+}
+/**
+ * The Council primitive.
+ *
+ * Minimal usage:
+ *   const c = new Council({
+ *     name: "engineering-review",
+ *     specialists: [cyberAgent, codeAgent, archAgent],
+ *   });
+ *   const result = await runner.runCouncil(c, "Review this PR for security risks");
+ *
+ * With verifier kernels:
+ *   const c = new Council({
+ *     name: "math-proof",
+ *     specialists: [mathAgent, reasoningAgent, verifierAgent],
+ *     verifiers: [VerifierKernels.arithmetic, VerifierKernels.citationPresence],
+ *   });
+ */
+declare class Council {
+    readonly name: string;
+    readonly specialists: Agent[];
+    readonly verifiers: Verifier[];
+    readonly reconciler: Reconciler;
+    readonly specialist_timeout_ms: number;
+    constructor(config: CouncilConfig);
+    /**
+     * Convenience entry point — pointed at the Runner you've already constructed.
+     * Most users will call `runner.runCouncil(council, query)` directly; this
+     * exists for symmetry with `agent.run`-style ergonomics in user code.
+     */
+    deliberate(_query: string): Promise<CouncilOutput>;
+}
+
+export { Council, type CouncilConfig, type CouncilOutput, type CouncilSpecialistOutput, type Reconciler };

package/dist/council/index.d.ts

@@ -0,0 +1,96 @@
+import { Agent } from '../agent/index.js';
+import { Verifier, VerifierResult } from '../verifiers/index.js';
+import '../tools/index.js';
+import 'zod';
+
+/** Output of a single specialist's turn before reconciliation. */
+interface CouncilSpecialistOutput {
+    specialist: string;
+    output: string;
+    claims: Array<{
+        text: string;
+        confidence: number;
+        type: string;
+    }>;
+    verifier_results: VerifierResult[];
+    cost_usd: number;
+    latency_ms: number;
+}
+/** Final synthesized output after reconciliation. */
+interface CouncilOutput {
+    /** The synthesized final answer. */
+    answer: string;
+    /** Per-specialist outputs (visible if you want to surface deliberation). */
+    specialists: CouncilSpecialistOutput[];
+    /** Whether the council reached consensus or surfaced a disagreement. */
+    consensus: "ratified" | "split" | "refuted";
+    /** If split: what the disagreement was about. */
+    disagreements?: Array<{
+        claim: string;
+        specialists_for: string[];
+        specialists_against: string[];
+    }>;
+    /** Aggregated cost + latency. */
+    total_cost_usd: number;
+    total_latency_ms: number;
+}
+/**
+ * A reconciler synthesizes N specialist outputs into one answer.
+ *
+ * Two kinds:
+ *   - Deterministic reconcilers (regex / SMT / voting) — fast, cheap, no LLM
+ *   - LLM reconcilers (Theron-Reconciler-D or another model) — better synthesis,
+ *     more expensive
+ *
+ * The default is a deterministic claim-merging reconciler.
+ */
+type Reconciler = (specialists: CouncilSpecialistOutput[]) => Promise<{
+    answer: string;
+    consensus: "ratified" | "split" | "refuted";
+    disagreements?: CouncilOutput["disagreements"];
+}>;
+interface CouncilConfig {
+    /** Display name for the council. */
+    name: string;
+    /** The specialists that will deliberate. Order doesn't matter. */
+    specialists: Agent[];
+    /** Verifier kernels run against each specialist output before reconciliation. */
+    verifiers?: Verifier[];
+    /** How to synthesize the specialist outputs. Defaults to deterministic claim-merge. */
+    reconciler?: Reconciler;
+    /** Optional timeout per specialist (ms). Slow specialists are dropped. */
+    specialist_timeout_ms?: number;
+}
+/**
+ * The Council primitive.
+ *
+ * Minimal usage:
+ *   const c = new Council({
+ *     name: "engineering-review",
+ *     specialists: [cyberAgent, codeAgent, archAgent],
+ *   });
+ *   const result = await runner.runCouncil(c, "Review this PR for security risks");
+ *
+ * With verifier kernels:
+ *   const c = new Council({
+ *     name: "math-proof",
+ *     specialists: [mathAgent, reasoningAgent, verifierAgent],
+ *     verifiers: [VerifierKernels.arithmetic, VerifierKernels.citationPresence],
+ *   });
+ */
+declare class Council {
+    readonly name: string;
+    readonly specialists: Agent[];
+    readonly verifiers: Verifier[];
+    readonly reconciler: Reconciler;
+    readonly specialist_timeout_ms: number;
+    constructor(config: CouncilConfig);
+    /**
+     * Convenience entry point — pointed at the Runner you've already constructed.
+     * Most users will call `runner.runCouncil(council, query)` directly; this
+     * exists for symmetry with `agent.run`-style ergonomics in user code.
+     */
+    deliberate(_query: string): Promise<CouncilOutput>;
+}
+
+export { Council, type CouncilConfig, type CouncilOutput, type CouncilSpecialistOutput, type Reconciler };

package/dist/council/index.js

@@ -0,0 +1,66 @@
+// src/council/index.ts
+var Council = class {
+  name;
+  specialists;
+  verifiers;
+  reconciler;
+  specialist_timeout_ms;
+  constructor(config) {
+    if (!config.name) throw new Error("Council requires a `name`.");
+    if (!config.specialists || config.specialists.length === 0) {
+      throw new Error(`Council "${config.name}" requires at least one specialist.`);
+    }
+    this.name = config.name;
+    this.specialists = config.specialists;
+    this.verifiers = config.verifiers ?? [];
+    this.reconciler = config.reconciler ?? deterministicClaimMerge;
+    this.specialist_timeout_ms = config.specialist_timeout_ms ?? 3e4;
+  }
+  /**
+   * Convenience entry point — pointed at the Runner you've already constructed.
+   * Most users will call `runner.runCouncil(council, query)` directly; this
+   * exists for symmetry with `agent.run`-style ergonomics in user code.
+   */
+  async deliberate(_query) {
+    throw new Error(
+      "Council.deliberate() requires a Runner. Use:\n  const runner = new Runner({ ... });\n  const result = await runner.runCouncil(council, query);\nSee: https://github.com/Vext-Labs-Inc/theron-agent-sdk/blob/main/examples/03_council_of_three.ts"
+    );
+  }
+};
+var deterministicClaimMerge = async (specialists) => {
+  if (specialists.length === 0) {
+    return { answer: "(no specialists responded)", consensus: "refuted" };
+  }
+  if (specialists.length === 1) {
+    return { answer: specialists[0].output, consensus: "ratified" };
+  }
+  const claimMap = /* @__PURE__ */ new Map();
+  for (const s of specialists) {
+    for (const c of s.claims) {
+      const key = c.text.toLowerCase().trim();
+      if (!claimMap.has(key)) claimMap.set(key, []);
+      claimMap.get(key).push(s.specialist);
+    }
+  }
+  const ratified = [];
+  const disagreements = [];
+  const majorityThreshold = specialists.length / 2;
+  for (const [claim, voters] of claimMap.entries()) {
+    if (voters.length === specialists.length) {
+      ratified.push(claim);
+    } else if (voters.length > majorityThreshold) {
+      ratified.push(claim);
+    } else {
+      disagreements.push({
+        claim,
+        specialists_for: voters,
+        specialists_against: specialists.map((s) => s.specialist).filter((n) => !voters.includes(n))
+      });
+    }
+  }
+  const answer = ratified.join(" ") || specialists[0].output;
+  const consensus = disagreements.length > 0 ? "split" : ratified.length > 0 ? "ratified" : "refuted";
+  return { answer, consensus, disagreements: disagreements.length > 0 ? disagreements : void 0 };
+};
+
+export { Council };