torus-ai 0.2.0 → 0.3.0

package/src/pack.ts

@@ -0,0 +1,155 @@
+import { existsSync } from "node:fs";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { builtinTools } from "./builtins.ts";
+import { runLoop } from "./loop.ts";
+import { matchesAllow, PermissionEngine } from "./permissions.ts";
+import { createCatalogServer, type CatalogItem } from "./packkit.ts";
+import { createDefaultProvider } from "./providers/cascade.ts";
+import { ToolRegistry } from "./tools.ts";
+import type {
+  AgentEvent,
+  CanUseTool,
+  ContentBlock,
+  Message,
+  ModelProvider,
+  SdkMcpServer,
+} from "./types.ts";
+
+// Specialize the generic engine to a product by loading a *pack* (an adapter):
+// persona + sales playbook + policy + domain tools + catalog grounding + guardrails.
+// One engine, many packs — don't fork the SDK per vertical.
+
+export interface PackKnowledge {
+  /** Product catalog — auto-wired into a `search_catalog` tool for grounding. */
+  catalog?: CatalogItem[];
+  /** Short reference text (policies, FAQs) appended to the system prompt. */
+  faqs?: string;
+}
+
+export interface PackGuardrails {
+  /** Allowlist of tool names the agent may call (namespaced, wildcards ok). */
+  allowedTools?: string[];
+  /** Tools that require explicit confirmation before running (namespaced names). */
+  confirm?: string[];
+  /** Extra custom gate, evaluated after allow/confirm. */
+  canUseTool?: CanUseTool;
+  /** Rules text (discount authority, no-overpromise, escalation) added to the prompt. */
+  policy?: string;
+}
+
+export interface AgentPack {
+  name: string;
+  persona: string; // who it is + voice (system prompt core)
+  playbook?: string; // sales stages + goal
+  tools?: SdkMcpServer[]; // domain actions (quote, reserve, invoice, handoff, ...)
+  knowledge?: PackKnowledge;
+  guardrails?: PackGuardrails;
+  model?: ModelProvider; // defaults to the free-first cascade
+}
+
+export interface SpecializeOptions {
+  provider?: ModelProvider;
+  /** Called when a `confirm` tool wants to run; return true to allow. */
+  onConfirm?: (toolName: string, input: Record<string, unknown>) => boolean | Promise<boolean>;
+  /** Allow built-in file tools (read/write/list). Off by default for packs. */
+  includeBuiltins?: boolean;
+  maxTurns?: number;
+}
+
+export interface SpecializedAgent {
+  pack: AgentPack;
+  system: string;
+  servers: SdkMcpServer[];
+  query(prompt: string | ContentBlock[], extra?: { maxTurns?: number }): AsyncGenerator<AgentEvent>;
+}
+
+/** Build a ready-to-run specialized agent from a pack. */
+export function createSpecializedAgent(pack: AgentPack, opts: SpecializeOptions = {}): SpecializedAgent {
+  // Assemble the system prompt from persona + playbook + policy + grounding + faqs.
+  const servers: SdkMcpServer[] = [...(pack.tools ?? [])];
+  if (pack.knowledge?.catalog?.length) servers.unshift(createCatalogServer(pack.knowledge.catalog));
+
+  const parts = [pack.persona.trim()];
+  if (pack.playbook) parts.push(`## Playbook\n${pack.playbook.trim()}`);
+  if (pack.guardrails?.policy) parts.push(`## Policy\n${pack.guardrails.policy.trim()}`);
+  if (servers.some((s) => s.tools.some((t) => t.name === "search_catalog"))) {
+    parts.push(
+      "Use the `search_catalog` tool for every product, price, or availability question. Never invent a price or claim availability you did not look up.",
+    );
+  }
+  if (pack.knowledge?.faqs) parts.push(`## Reference\n${pack.knowledge.faqs.trim()}`);
+  const system = parts.join("\n\n");
+
+  const confirmTools = pack.guardrails?.confirm ?? [];
+  const allow = pack.guardrails?.allowedTools;
+  const base = pack.guardrails?.canUseTool;
+
+  const canUseTool: CanUseTool = async (name, input) => {
+    if (confirmTools.includes(name)) {
+      const ok = opts.onConfirm ? await opts.onConfirm(name, input) : false;
+      if (!ok) return { behavior: "deny", message: `${name} requires confirmation and it was not granted.` };
+    }
+    if (allow && !matchesAllow(name, allow)) {
+      return { behavior: "deny", message: `${name} is not allowed by this pack's guardrails.` };
+    }
+    return base ? base(name, input) : { behavior: "allow" };
+  };
+
+  const provider = opts.provider ?? pack.model ?? createDefaultProvider();
+  const includeBuiltins = opts.includeBuiltins ?? false;
+
+  return {
+    pack,
+    system,
+    servers,
+    async *query(prompt, extra) {
+      const registry = new ToolRegistry();
+      if (includeBuiltins) registry.addBuiltins(builtinTools);
+      for (const s of servers) registry.addServer(s);
+
+      const content: ContentBlock[] =
+        typeof prompt === "string" ? [{ type: "text", text: prompt }] : prompt;
+      const messages: Message[] = [{ role: "user", content }];
+
+      const result = yield* runLoop({
+        provider,
+        registry,
+        permissions: new PermissionEngine({ canUseTool }),
+        system,
+        messages,
+        toolContext: { workspaceDir: process.cwd() },
+        maxTurns: extra?.maxTurns ?? opts.maxTurns,
+      });
+      yield { type: "result", finalText: result.finalText, turns: result.turns };
+    },
+  };
+}
+
+/**
+ * Load a pack's content from a folder (so non-devs can edit it):
+ *   persona.md · playbook.md · policy.md · catalog.json · faqs.md
+ * Code tools (quote/reserve/invoice/...) are passed via `opts.tools`.
+ */
+export async function loadPack(
+  dir: string,
+  opts: { tools?: SdkMcpServer[] } = {},
+): Promise<AgentPack> {
+  const read = async (f: string): Promise<string | undefined> => {
+    const p = join(dir, f);
+    return existsSync(p) ? await readFile(p, "utf8") : undefined;
+  };
+  const catalogRaw = await read("catalog.json");
+  const policy = await read("policy.md");
+  return {
+    name: dir.split(/[\\/]/).filter(Boolean).pop() ?? "pack",
+    persona: (await read("persona.md")) ?? "",
+    playbook: await read("playbook.md"),
+    knowledge: {
+      catalog: catalogRaw ? (JSON.parse(catalogRaw) as CatalogItem[]) : undefined,
+      faqs: await read("faqs.md"),
+    },
+    guardrails: policy ? { policy } : undefined,
+    tools: opts.tools,
+  };
+}

package/src/packkit.ts

@@ -0,0 +1,147 @@
+import { createSdkMcpServer, tool } from "./tools.ts";
+import type { SdkMcpServer } from "./types.ts";
+
+// Reusable tool patterns for specializing an agent to a vertical (a "pack").
+// Compose these into a pack's `tools`. They are deliberately backend-agnostic —
+// swap the in-memory stubs for real catalog/CRM/payment integrations later.
+
+export type CatalogItem = Record<string, unknown> & {
+  id?: string;
+  name?: string;
+  price?: number;
+  tags?: string[];
+  available?: boolean;
+};
+
+/** A `search_catalog` tool over an in-memory product list (text + price + tags). */
+export function createCatalogServer(
+  items: CatalogItem[],
+  opts: { serverName?: string } = {},
+): SdkMcpServer {
+  const search = tool(
+    "search_catalog",
+    "Search the product catalog by text, max price, and tags. Returns matching items with prices and availability. Use this for every product/price/availability question — never guess.",
+    {
+      type: "object",
+      properties: {
+        query: { type: "string" },
+        maxPrice: { type: "number" },
+        tags: { type: "array", items: { type: "string" } },
+        limit: { type: "number" },
+      },
+    },
+    (input: { query?: string; maxPrice?: number; tags?: string[]; limit?: number }) => {
+      let res = items.filter((it) => it.available !== false);
+      if (input.query) {
+        const words = input.query.toLowerCase().split(/\s+/).filter(Boolean);
+        res = res.filter((it) => {
+          const hay = JSON.stringify(it).toLowerCase();
+          return words.every((w) => hay.includes(w));
+        });
+      }
+      if (typeof input.maxPrice === "number") {
+        res = res.filter((it) => typeof it.price !== "number" || it.price <= input.maxPrice!);
+      }
+      if (Array.isArray(input.tags) && input.tags.length) {
+        res = res.filter((it) => Array.isArray(it.tags) && input.tags!.some((t) => it.tags!.includes(t)));
+      }
+      const out = res.slice(0, input.limit ?? 5);
+      return { content: out.length ? JSON.stringify(out, null, 2) : "No matching items." };
+    },
+  );
+  return createSdkMcpServer({ name: opts.serverName ?? "catalog", tools: [search] });
+}
+
+/** `get_lead` / `update_lead` over an in-memory customer profile (the funnel state). */
+export function createLeadMemoryServer(
+  initial: Record<string, unknown> = {},
+): SdkMcpServer & { lead: Record<string, unknown> } {
+  const lead: Record<string, unknown> = { ...initial };
+  const get = tool(
+    "get_lead",
+    "Get what we know about the current customer (name, date, budget, stage, items seen).",
+    { type: "object", properties: {} },
+    () => ({ content: JSON.stringify(lead, null, 2) }),
+  );
+  const update = tool(
+    "update_lead",
+    "Merge fields into the customer profile, e.g. { budget: 2000, stage: 'recommend' }.",
+    { type: "object", properties: { fields: { type: "object" } }, required: ["fields"] },
+    (input: { fields: Record<string, unknown> }) => {
+      Object.assign(lead, input.fields ?? {});
+      return { content: `updated: ${Object.keys(input.fields ?? {}).join(", ") || "(none)"}` };
+    },
+  );
+  return Object.assign(createSdkMcpServer({ name: "lead", tools: [get, update] }), { lead });
+}
+
+export interface Invoice {
+  id: string;
+  amount: number;
+  currency: string;
+  items?: unknown;
+  customer?: unknown;
+  status: "pending";
+}
+
+/**
+ * A generic `create_invoice` settle tool: records an order + amount as pending
+ * and returns an invoice id. Provider-agnostic — wire your processor via
+ * `onCreate` (e.g. create a real payment link, then confirm via webhook).
+ */
+export function createInvoiceServer(
+  opts: { onCreate?: (inv: Invoice) => void } = {},
+): SdkMcpServer & { invoices: Invoice[] } {
+  const invoices: Invoice[] = [];
+  let n = 0;
+  const create = tool(
+    "create_invoice",
+    "Record an order and amount as a pending invoice to settle, returning an invoice id. Call this only after the customer has agreed to buy.",
+    {
+      type: "object",
+      properties: {
+        amount: { type: "number" },
+        currency: { type: "string" },
+        items: {},
+        customer: {},
+      },
+      required: ["amount"],
+    },
+    (input: { amount: number; currency?: string; items?: unknown; customer?: unknown }) => {
+      const inv: Invoice = {
+        id: `inv_${++n}`,
+        amount: input.amount,
+        currency: input.currency ?? "USD",
+        items: input.items,
+        customer: input.customer,
+        status: "pending",
+      };
+      invoices.push(inv);
+      opts.onCreate?.(inv);
+      return {
+        content: JSON.stringify({ invoiceId: inv.id, status: inv.status, amount: inv.amount, currency: inv.currency }),
+      };
+    },
+  );
+  return Object.assign(createSdkMcpServer({ name: "billing", tools: [create] }), { invoices });
+}
+
+/** A `handoff_human` escalation tool. Wire `onHandoff` to notify a real agent. */
+export function createHandoffServer(
+  opts: { onHandoff?: (info: { reason: string; summary: string }) => void } = {},
+): SdkMcpServer {
+  const handoff = tool(
+    "handoff_human",
+    "Escalate to a human agent with a reason and a short summary of the conversation so far. Use when you're stuck, the request is high-value, or the customer asks for a person.",
+    {
+      type: "object",
+      properties: { reason: { type: "string" }, summary: { type: "string" } },
+      required: ["reason"],
+    },
+    (input: { reason: string; summary?: string }) => {
+      opts.onHandoff?.({ reason: input.reason, summary: input.summary ?? "" });
+      return { content: "Escalated to a human; they will take over shortly." };
+    },
+  );
+  return createSdkMcpServer({ name: "support", tools: [handoff] });
+}

package/src/providers/cascade.ts

@@ -1,17 +1,17 @@
-import { hasMedia } from "../types.ts";
 import type { ModelProvider, ModelRequest, ModelResponse } from "../types.ts";
-import { DEEPSEEK_V4_PRO, KIMI_K2_6, NvidiaProvider } from "./nvidia.ts";
+import { DEEPSEEK_V4_PRO, KIMI_K2_6, LLAMA_VISION, NvidiaProvider } from "./nvidia.ts";
 import { GeminiProvider } from "./gemini.ts";
 
 // Orchestration: try a prioritized list of (provider, model) steps, falling
 // through to the next on failure (rate limit, error, or capability mismatch).
-// Capability-aware: requests that carry image/video are only sent to steps that
-// support vision — text-only models (e.g. DeepSeek) are skipped for those.
+// Capability-aware: image requests only go to vision steps; video requests only
+// to video steps — text-only models (Kimi, DeepSeek) are skipped for those.
 
 export interface CascadeStep {
   provider: ModelProvider;
   label: string; // e.g. "nvidia:kimi-k2.6"
-  vision: boolean; // does this step's model accept image/video input?
+  vision: boolean; // accepts image input?
+  video?: boolean; // accepts video input? (default false)
 }
 
 export interface CascadeOptions {
@@ -32,11 +32,22 @@ export class CascadeProvider implements ModelProvider {
   }
 
   async generate(req: ModelRequest): Promise<ModelResponse> {
-    const needsVision = hasMedia(req.messages);
-    const eligible = this.steps.filter((s) => !needsVision || s.vision);
+    const has = (t: "image" | "video") =>
+      req.messages.some((m) => m.content.some((b) => b.type === t));
+    const needsVideo = has("video");
+    const needsImage = has("image");
+    const needsVision = needsImage || needsVideo;
+
+    const eligible = needsVideo
+      ? this.steps.filter((s) => s.video)
+      : needsImage
+        ? this.steps.filter((s) => s.vision)
+        : this.steps;
 
     if (!eligible.length) {
-      throw new Error("Cascade: request needs vision but no step supports image/video input.");
+      throw new Error(
+        `Cascade: request needs ${needsVideo ? "video" : "image"} input but no step supports it.`,
+      );
     }
 
     let lastErr: unknown;
@@ -63,6 +74,8 @@ export interface DefaultProviderOptions {
   mainModel?: string;
   /** Override the secondary NVIDIA model (default DeepSeek V4 Pro). */
   secondaryModel?: string;
+  /** NVIDIA vision model for image requests (default llama-3.2-90b-vision). */
+  visionModel?: string;
   /** Gemini model used as the final fallback option (default gemini-2.5-flash). */
   geminiModel?: string;
   onFallback?: CascadeOptions["onFallback"];
@@ -70,16 +83,20 @@ export interface DefaultProviderOptions {
 
 /**
  * The SDK's recommended default: free NVIDIA endpoints first, Google as one
- * fallback option.
+ * fallback option. Capability-aware — image/video requests skip the text-only
+ * steps automatically.
  *
- *   1. NVIDIA Kimi K2.6        — main; agentic + multimodal (image/video)
- *   2. NVIDIA DeepSeek V4 Pro  — text-only; skipped for image/video requests
- *   3. Gemini 2.5 Flash        — final fallback; multimodal
+ *   1. NVIDIA Kimi K2.6                  — main; agentic + tools (text)
+ *   2. NVIDIA DeepSeek V4 Pro            — 1M-ctx text; skipped for media
+ *   3. NVIDIA Llama-3.2-90B-Vision       — image requests
+ *   4. Gemini 2.5 Flash                  — final fallback; image + video
  */
 export function createDefaultProvider(opts: DefaultProviderOptions = {}): CascadeProvider {
   const main = opts.mainModel ?? KIMI_K2_6;
   const secondary = opts.secondaryModel ?? DEEPSEEK_V4_PRO;
+  const vision = opts.visionModel ?? LLAMA_VISION;
   const gemini = opts.geminiModel ?? "gemini-2.5-flash";
+  const nv = (model: string) => new NvidiaProvider({ model, apiKey: opts.nvidiaApiKey });
 
   return new CascadeProvider({
     onFallback:
@@ -87,20 +104,14 @@ export function createDefaultProvider(opts: DefaultProviderOptions = {}): Cascad
       ((info) =>
         console.warn(`[cascade] ${info.from} failed (${info.reason}); trying next`)),
     steps: [
-      {
-        provider: new NvidiaProvider({ model: main, apiKey: opts.nvidiaApiKey }),
-        label: `nvidia:${main}`,
-        vision: true, // Kimi K2.6 accepts image + video
-      },
-      {
-        provider: new NvidiaProvider({ model: secondary, apiKey: opts.nvidiaApiKey }),
-        label: `nvidia:${secondary}`,
-        vision: false, // DeepSeek V4 is text-only
-      },
+      { provider: nv(main), label: `nvidia:${main}`, vision: false, video: false },
+      { provider: nv(secondary), label: `nvidia:${secondary}`, vision: false, video: false },
+      { provider: nv(vision), label: `nvidia:${vision}`, vision: true, video: false },
       {
         provider: new GeminiProvider({ model: gemini, apiKey: opts.googleApiKey }),
         label: `gemini:${gemini}`,
         vision: true,
+        video: true,
       },
     ],
   });

package/src/providers/nvidia.ts

@@ -13,9 +13,10 @@ import type {
 export const NVIDIA_BASE_URL = "https://integrate.api.nvidia.com/v1";
 
 // Exact IDs confirmed against GET /v1/models.
-export const KIMI_K2_6 = "moonshotai/kimi-k2.6"; // 256K ctx, tools, vision (image+video)
+export const KIMI_K2_6 = "moonshotai/kimi-k2.6"; // 256K ctx, tools, agentic — text-only on NIM (verified)
 export const DEEPSEEK_V4_PRO = "deepseek-ai/deepseek-v4-pro"; // 1M ctx, tools, text-only
 export const DEEPSEEK_V4_FLASH = "deepseek-ai/deepseek-v4-flash"; // faster/cheaper, text-only
+export const LLAMA_VISION = "meta/llama-3.2-90b-vision-instruct"; // free NVIDIA vision model (image), verified
 
 export interface NvidiaOptions {
   model?: string;
@@ -38,7 +39,7 @@ export class NvidiaProvider implements ModelProvider {
     this.apiKey = opts.apiKey ?? process.env.NVIDIA_API_KEY;
     this.baseURL = opts.baseURL ?? NVIDIA_BASE_URL;
     this.maxTokens = opts.maxTokens ?? 2048;
-    this.temperature = opts.temperature ?? 0.6;
+    this.temperature = opts.temperature ?? 0.2; // low default for deterministic agent behavior
   }
 
   async generate(req: ModelRequest): Promise<ModelResponse> {