@vextlabs/theron-agent-sdk 0.3.0

package/examples/meeting-prep-bot.ts

@@ -0,0 +1,172 @@
+/**
+ * Sample agent: meeting-prep-bot
+ *
+ * Generates a one-page prep brief for an upcoming meeting from a calendar
+ * event + linked docs. Demonstrates how to wire Memory (prior notes about
+ * the attendees) into an agent loop.
+ *
+ * Ships with mock calendar + docs tools so it runs offline. Swap in a real
+ * Google Calendar / Outlook adapter and a real docs source for production.
+ *
+ * Run:
+ *   OPENROUTER_API_KEY=sk-or-... npx tsx examples/meeting-prep-bot.ts
+ *
+ * What this demonstrates:
+ *   - Tool composition (calendar.list_events + docs.fetch + memory.lookup)
+ *   - Memory primitive: prior knowledge of attendees informs the brief
+ *   - Receipts: every external read carries a cap that names the surface
+ */
+
+import {
+  Agent,
+  Runner,
+  defineTool,
+  zod as z,
+  VerifierKernels,
+  InMemoryStore,
+  ReceiptEmitter,
+  InMemoryReceiptSink,
+} from "../src/index.js";
+import { openrouterAdapter } from "./adapters/openrouter.js";
+
+// --- Memory (seeded with prior context about an attendee) ------------------
+
+const memory = new InMemoryStore();
+await memory.set({
+  key: "person:dana",
+  value:
+    "Dana runs platform infra. Cares about p99 latency, hates flaky tests, " +
+    "previously asked for a SLO dashboard in our last 1:1.",
+  tags: ["person", "platform"],
+  created_at: Date.now(),
+  last_accessed_at: Date.now(),
+});
+
+// --- Tools ------------------------------------------------------------------
+
+const listEvents = defineTool({
+  name: "calendar_list_events",
+  description: "List upcoming calendar events for the next N hours.",
+  input: z.object({ hours_ahead: z.number() }),
+  async execute({ hours_ahead }) {
+    return {
+      events: [
+        {
+          id: "evt_001",
+          title: "Q3 planning sync",
+          start: new Date(Date.now() + 3_600_000).toISOString(),
+          end: new Date(Date.now() + 5_400_000).toISOString(),
+          attendees: ["dana@example.com", "anna@example.com"],
+          linked_docs: ["doc_42"],
+          horizon_hours: hours_ahead,
+        },
+      ],
+    };
+  },
+});
+
+const fetchDoc = defineTool({
+  name: "docs_fetch",
+  description: "Fetch the body text of a linked doc.",
+  input: z.object({ doc_id: z.string() }),
+  async execute({ doc_id }) {
+    return {
+      doc_id,
+      title: "Q3 platform roadmap (draft)",
+      body:
+        "Three bets: (a) SLO dashboards, (b) flake-detection in CI, " +
+        "(c) cost-per-tenant reporting. Open question: do we own (c) or " +
+        "punt to finance.",
+    };
+  },
+});
+
+const recallPerson = defineTool({
+  name: "memory_recall_person",
+  description: "Look up prior notes about a person by email or handle.",
+  input: z.object({ handle: z.string() }),
+  async execute({ handle }) {
+    const key = `person:${handle.split("@")[0]}`;
+    const hits = await memory.query({ key });
+    return { handle, notes: hits.map((h) => h.value) };
+  },
+});
+
+// --- Agent ------------------------------------------------------------------
+
+const prepBot = new Agent({
+  name: "meeting-prep-bot",
+  instruction: `You write a one-page prep brief for an upcoming meeting.
+
+Workflow:
+  1. calendar_list_events for the next 4 hours
+  2. For each event, docs_fetch every linked doc
+  3. For each attendee, memory_recall_person
+  4. Produce a brief:
+     ## Meeting
+     ## Attendees (one line each: role + recent context from memory)
+     ## Docs (3-bullet TLDR per doc)
+     ## Questions to raise (3 max, prioritized)
+     ## Decisions to push for (1-3)
+
+Rules:
+  - One page max.
+  - No filler. No em-dashes or AI-isms.`,
+  tools: [listEvents, fetchDoc, recallPerson],
+  verifiers: [VerifierKernels.emDash, VerifierKernels.aiIsm],
+});
+
+// --- Main -------------------------------------------------------------------
+
+async function main() {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    console.error("Set OPENROUTER_API_KEY (https://openrouter.ai/keys) and rerun.");
+    process.exit(1);
+  }
+
+  const runner = new Runner({
+    model: openrouterAdapter({ apiKey }),
+    default_model: "openai/gpt-4o-mini",
+  });
+
+  const sink = new InMemoryReceiptSink();
+  const receipts = new ReceiptEmitter({
+    sinks: [sink],
+    issuer: "did:web:local",
+    actor: prepBot.name,
+  });
+
+  runner.on(async (event) => {
+    if (event.type === "tool_call_done") {
+      // Cap names are reverse-DNS-ish so receipts cluster cleanly per surface.
+      const cap =
+        event.tool === "calendar_list_events"
+          ? "vext.calendar.list_events"
+          : event.tool === "docs_fetch"
+            ? "vext.docs.fetch"
+            : "vext.memory.recall";
+      await receipts.emit({
+        cap,
+        input: { tool: event.tool },
+        output: event.output,
+      });
+    }
+    if (event.type === "agent_output") {
+      await receipts.emit({
+        cap: "agent.run",
+        input: { agent: event.agent },
+        output: event.output,
+      });
+    }
+  });
+
+  const result = await runner.run(prepBot, "Prep me for everything in the next 4 hours.");
+  console.log("\n=== Brief ===\n" + result.output);
+  console.log(`\n=== Receipts: ${sink.list().length} ===`);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/reasoning-patterns.ts

@@ -0,0 +1,125 @@
+/**
+ * Sample: Reasoning patterns
+ *
+ * Demonstrates the framework-agnostic reasoning-pattern primitives — the
+ * SDK-side counterparts of Theron's server Hive loops. No API key needed: this
+ * example uses a deterministic mock "model" so it runs offline and its output is
+ * stable. Swap the mock for any provider call (OpenRouter, Anthropic, OpenAI,
+ * a local model) and the patterns are unchanged.
+ *
+ * Run:
+ *   npx tsx examples/reasoning-patterns.ts
+ *
+ * What this demonstrates:
+ *   - selfConsistency  — sample N paths, take the majority answer
+ *   - bestOfN          — verifier-guided best-of-N
+ *   - selfRefine       — draft → critique → revise (early-exit when clean)
+ *   - treeOfThoughts   — best-first branch/score/expand search
+ *   - chainOfVerification — draft → verify claims independently → revise
+ */
+
+import {
+  selfConsistency,
+  bestOfN,
+  selfRefine,
+  treeOfThoughts,
+  chainOfVerification,
+  mixtureOfAgents,
+  reflexion,
+  measureLift,
+} from "../src/index.js";
+
+// A stand-in "model". Replace with a real provider call in production.
+async function mockModel(prompt: string): Promise<string> {
+  if (prompt.includes("critique")) return prompt.includes("v2") ? "no issues" : "flaw: be more specific";
+  if (prompt.includes("verify:")) return "supported";
+  // A slightly noisy answerer so self-consistency has a majority to find.
+  const answers = ["42", "42", "41", "42"];
+  return answers[prompt.length % answers.length];
+}
+
+async function main() {
+  // 1) Self-consistency — majority vote across samples (3 of 4 agree on "42").
+  const sampled = ["42", "42", "41", "42"];
+  const sc = await selfConsistency({
+    samples: 4,
+    generate: (i) => sampled[i],
+  });
+  console.log(`selfConsistency → "${sc.answer}" (agreement ${sc.consistency})`);
+
+  // 2) Best-of-N — pick the highest-scored candidate (score = your verifier).
+  const bo = await bestOfN({
+    n: 3,
+    generate: (i) => `candidate ${i}`,
+    score: (_v, i) => i / 10, // stand-in verifier confidence
+  });
+  console.log(`bestOfN → "${bo.best}" (score ${bo.score})`);
+
+  // 3) Self-refine — iterate until the critique is clean.
+  const sr = await selfRefine<string>({
+    draft: () => "v1 draft",
+    critique: (v) => mockModel(`critique ${v}`),
+    revise: () => "v2 draft",
+    maxIters: 3,
+  });
+  console.log(`selfRefine → "${sr.answer}" (${sr.revised} revision(s))`);
+
+  // 4) Tree-of-thoughts — best-first search over reasoning branches.
+  const tot = await treeOfThoughts<number>({
+    breadth: 3,
+    depth: 2,
+    expand: (_path, b) => b,
+    score: (cand) => cand,
+    synthesize: (path) => path.reduce((a, b) => a + b, 0),
+  });
+  console.log(`treeOfThoughts → ${tot.answer} (path ${tot.path.map((p) => p.thought).join("→")})`);
+
+  // 5) Chain-of-verification — verify the draft's claims, then revise.
+  const cov = await chainOfVerification<string>({
+    draft: () => "the draft answer",
+    planChecks: () => ["verify: claim A", "verify: claim B"],
+    answerCheck: (q) => mockModel(q),
+    revise: (_d, checks) => `revised after ${checks.length} checks`,
+  });
+  console.log(`chainOfVerification → "${cov.answer}"`);
+
+  // 5b) Mixture-of-agents — layered multi-agent propose → refine → aggregate.
+  const moa = await mixtureOfAgents({
+    agents: 3,
+    layers: 2,
+    propose: (a) => `agent${a}'s take`,
+    refine: (a, others) => `agent${a} refined (saw ${others.length} peers)`,
+    aggregate: (final) => `consensus of ${final.length}`,
+  });
+  console.log(`mixtureOfAgents → "${moa.answer}" (${moa.layerOutputs.length} layers)`);
+
+  // 5c) Reflexion — retry with accumulated reflections until success.
+  const refl = await reflexion<string>({
+    maxAttempts: 4,
+    attempt: (reflections) => `attempt with ${reflections.length} reflection(s)`,
+    evaluate: (r) => ({ success: r.includes("2 reflection"), feedback: "not yet" }),
+    reflect: (_r, fb, i) => `lesson ${i}: ${fb}`,
+  });
+  console.log(`reflexion → "${refl.answer}" (succeeded ${refl.succeeded} in ${refl.attempts} attempts)`);
+
+  // 6) measureLift — prove a pattern beats single-shot on a task set.
+  //    Baseline: one noisy sample. Treatment: self-consistency over 5 samples.
+  //    Scorer: 1.0 if the answer is the correct "42", else 0.
+  const tasks = [0, 1, 2, 3, 4, 5]; // 6 tasks (seeds)
+  const noisy = (seed: number) => (["42", "42", "41", "42", "40", "42"][seed % 6]);
+  const lift = await measureLift<number>({
+    tasks,
+    baseline: (t) => noisy(t), // single shot
+    treatment: async (t) => (await selfConsistency({ samples: 5, generate: (i) => noisy(t + i) })).answer,
+    score: (_t, out) => (out === "42" ? 1 : 0),
+  });
+  console.log(
+    `measureLift → baseline ${lift.baselineMean} vs treatment ${lift.treatmentMean} ` +
+      `(lift ${lift.lift >= 0 ? "+" : ""}${lift.lift}, win-rate ${lift.winRate})`,
+  );
+}
+
+main().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});

package/examples/support-triage-bot.ts

@@ -0,0 +1,181 @@
+/**
+ * Sample agent: support-triage-bot
+ *
+ * Triages an inbound support ticket: classifies it (bug / feature-request /
+ * billing / how-to), pulls related past tickets, decides routing (engineering
+ * queue / billing queue / docs queue), and writes a one-paragraph reply
+ * draft. Demonstrates a Council pattern — three specialists (classifier,
+ * retriever, writer) deliberate to produce the final routing decision.
+ *
+ * Ships with mock ticket + KB stores so it runs offline.
+ *
+ * Run:
+ *   OPENROUTER_API_KEY=sk-or-... npx tsx examples/support-triage-bot.ts
+ *
+ * What this demonstrates:
+ *   - Council primitive used for routing (not just deliberation)
+ *   - Verifier kernels enforcing the response style
+ *   - Receipts: the routing decision is signed so a downstream router can
+ *     prove an agent (not a human) made the call
+ */
+
+import {
+  Agent,
+  Council,
+  Runner,
+  defineTool,
+  zod as z,
+  VerifierKernels,
+  ReceiptEmitter,
+  InMemoryReceiptSink,
+} from "../src/index.js";
+import { openrouterAdapter } from "./adapters/openrouter.js";
+
+// --- Tools (ticket + KB) ----------------------------------------------------
+
+const fetchTicket = defineTool({
+  name: "fetch_ticket",
+  description: "Fetch a support ticket by id.",
+  input: z.object({ ticket_id: z.string() }),
+  async execute({ ticket_id }) {
+    return {
+      ticket_id,
+      subject: "Login redirects to /404 after upgrade",
+      body:
+        "Upgraded to v0.4.2 last night. Login works, but the post-login " +
+        "redirect lands on /404. Worked fine on v0.4.1. Three of my " +
+        "teammates hit it too.",
+      reporter: "u_8821",
+      plan: "team",
+    };
+  },
+});
+
+const similarTickets = defineTool({
+  name: "similar_tickets",
+  description: "Find past tickets with similar symptoms.",
+  input: z.object({ query: z.string() }),
+  async execute({ query }) {
+    return {
+      query,
+      hits: [
+        {
+          id: "t_771",
+          subject: "Redirect breaks after v0.4 upgrade",
+          status: "resolved",
+          resolution: "Fix shipped in v0.4.3; ask user to upgrade.",
+        },
+      ],
+    };
+  },
+});
+
+const kbLookup = defineTool({
+  name: "kb_lookup",
+  description: "Search the support knowledge base.",
+  input: z.object({ topic: z.string() }),
+  async execute({ topic }) {
+    return {
+      topic,
+      articles: [
+        {
+          title: "Login redirect troubleshooting",
+          url: "https://docs.example.com/kb/login-redirect",
+        },
+      ],
+    };
+  },
+});
+
+// --- Specialists ------------------------------------------------------------
+
+const classifier = new Agent({
+  name: "classifier",
+  instruction: `You classify a support ticket into one of: bug, feature-request, billing, how-to.
+Output a single JSON object: {"class": "...", "confidence": 0-1, "rationale": "..."}.
+Do not use em-dashes or AI-isms.`,
+  tools: [fetchTicket],
+});
+
+const retriever = new Agent({
+  name: "retriever",
+  instruction: `You find prior context for a support ticket. Call similar_tickets and kb_lookup.
+Output a single JSON object: {"similar_ticket_ids": [...], "kb_urls": [...], "notes": "..."}.
+Do not use em-dashes or AI-isms.`,
+  tools: [fetchTicket, similarTickets, kbLookup],
+});
+
+const writer = new Agent({
+  name: "writer",
+  instruction: `You write a one-paragraph reply draft for the ticket reporter.
+Be direct. Lead with what they should do. End with what we will do.
+Do not use em-dashes or AI-isms. Length: 60-100 words.`,
+  tools: [fetchTicket],
+  verifiers: [VerifierKernels.emDash, VerifierKernels.aiIsm],
+});
+
+const triageCouncil = new Council({
+  name: "support-triage",
+  specialists: [classifier, retriever, writer],
+  verifiers: [VerifierKernels.emDash, VerifierKernels.aiIsm],
+  specialist_timeout_ms: 25_000,
+});
+
+// --- Main -------------------------------------------------------------------
+
+async function main() {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    console.error("Set OPENROUTER_API_KEY (https://openrouter.ai/keys) and rerun.");
+    process.exit(1);
+  }
+
+  const runner = new Runner({
+    model: openrouterAdapter({ apiKey }),
+    default_model: "openai/gpt-4o-mini",
+  });
+
+  const sink = new InMemoryReceiptSink();
+  const receipts = new ReceiptEmitter({
+    sinks: [sink],
+    issuer: "did:web:local",
+    actor: triageCouncil.name,
+  });
+
+  runner.on(async (event) => {
+    if (event.type === "council_done") {
+      // The routing decision is the headline event — sign it so the queue
+      // router downstream can prove an agent made the call.
+      await receipts.emit({
+        cap: "support.triage.route",
+        input: { council: event.council },
+        output: {
+          answer: event.output.answer,
+          consensus: event.output.consensus,
+          specialists: event.output.specialists.map((s) => s.specialist),
+        },
+        metadata: {
+          total_cost_usd: event.output.total_cost_usd,
+          total_latency_ms: event.output.total_latency_ms,
+        },
+      });
+    }
+  });
+
+  const out = await runner.runCouncil(
+    triageCouncil,
+    "Triage ticket t_902 and produce a routing decision + reply draft.",
+  );
+
+  console.log("\n=== Consensus ===", out.consensus);
+  console.log("\n=== Answer ===\n" + out.answer);
+  console.log(`\n=== Receipts: ${sink.list().length} ===`);
+  for (const r of sink.list()) {
+    console.log(`  ${r.cap} → ${r.content_hash.slice(0, 12)}…`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/examples/verifier-kernel.ts

@@ -0,0 +1,108 @@
+/**
+ * verifier-kernel — define a custom verifier, attach it to an agent,
+ * watch the refutation flow.
+ *
+ * The custom kernel here flags any claim of the form "X happened in YEAR"
+ * where YEAR < 1900 or YEAR > current year. Cheap, deterministic, and runs
+ * in milliseconds. Verifiers do NOT call another LLM — they're the answer
+ * to "LLM-judge is slow, expensive, and hallucinates."
+ *
+ * Run:
+ *   OPENROUTER_API_KEY=sk-or-... npx tsx examples/verifier-kernel.ts
+ *
+ * What this shows:
+ *   - defineVerifier — the factory for custom kernels
+ *   - Attaching a verifier to an Agent (vs a Council)
+ *   - The "issues" payload that surfaces on refutation
+ *   - That a failed verifier does NOT throw — callers decide policy
+ */
+import {
+  Agent,
+  Runner,
+  defineVerifier,
+  VerifierKernels,
+} from "../src/index.js";
+import { openrouterAdapter } from "./adapters/openrouter.js";
+
+const currentYear = new Date().getFullYear();
+
+const plausibleYear = defineVerifier({
+  name: "plausible_year",
+  description:
+    "Flag claims with year numbers outside [1900, current year]. " +
+    "Catches hallucinated historical dates and future-dated claims.",
+  check: async (output) => {
+    const pattern = /\b(\d{4})\b/g;
+    const issues = [];
+    for (const m of output.matchAll(pattern)) {
+      const y = parseInt(m[1], 10);
+      if (y < 1900 || y > currentYear) {
+        issues.push({
+          kernel: "plausible_year",
+          severity: "error" as const,
+          message: `Year ${y} is implausible (expected 1900..${currentYear}).`,
+          span: { start: m.index!, end: m.index! + m[1].length },
+        });
+      }
+    }
+    return { pass: issues.length === 0, issues };
+  },
+});
+
+const historian = new Agent({
+  name: "historian",
+  instruction:
+    "You answer history questions in 2-3 sentences. Always include the " +
+    "year a key event happened. Be concise.",
+  verifiers: [
+    plausibleYear,
+    VerifierKernels.emDash,
+    VerifierKernels.aiIsm,
+  ],
+});
+
+async function main() {
+  const apiKey = process.env.OPENROUTER_API_KEY;
+  if (!apiKey) {
+    console.error("Set OPENROUTER_API_KEY (https://openrouter.ai/keys) and rerun.");
+    process.exit(1);
+  }
+
+  const runner = new Runner({
+    model: openrouterAdapter({ apiKey }),
+    default_model: "openai/gpt-4o-mini",
+  });
+
+  runner.on((event) => {
+    if (event.type === "agent_thinking") process.stdout.write(event.delta);
+    if (event.type === "verifier_run") {
+      const { kernel, result } = event;
+      const tag = result.pass ? "PASS" : "FAIL";
+      console.log(`\n[${tag}] ${kernel} (${result.ms}ms)`);
+      for (const issue of result.issues) {
+        console.log(`  - ${issue.severity}: ${issue.message}`);
+      }
+    }
+  });
+
+  const result = await runner.run(
+    historian,
+    "When did the first programmable digital computer come online? Answer with a year.",
+  );
+
+  console.log("\n--- Final output ---");
+  console.log(result.output);
+
+  const failed = result.verifier_results.filter((v) => !v.pass);
+  if (failed.length > 0) {
+    console.log(`\nRefutations: ${failed.map((v) => v.kernel).join(", ")}`);
+    process.exitCode = 1;
+  } else {
+    console.log("\nAll verifier kernels passed.");
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});