theorum 0.1.2 → 0.1.4

package/README.md

@@ -16,6 +16,8 @@ THEORUM is a compact TypeScript agent kernel for apps that need deterministic ag
 
 The package is intentionally **not** an agent product. It ships no app profiles, no prompts, no secrets, no database policy, no business rules, and no channel-specific UX. Those belong in the host application.
 
+OpenRouter chat transport is powered by Vercel AI SDK Core under the adapter. THEORUM keeps the runner contract, guardrails, tool permissions, egress, media buffering, and trace event shape; AI SDK handles the OpenRouter request/stream/tool-call normalization layer.
+
 ---
 
 ## Core Principles
@@ -24,7 +26,7 @@ The package is intentionally **not** an agent product. It ships no app profiles,
 [kernel_contract]
 profiles = "Host-owned declarations for model, inputs, outputs, tools, and guardrails"
 runner = "Single deterministic execution path for one agent turn"
-providers = "Adapters for OpenRouter-compatible chat and Google Interactions"
+providers = "createProvider routes protocol/provider; adapters stay internal"
 tools = "Profile allowlist ceiling plus per-turn dynamic declarations"
 egress = "Typed host hook for outbound disclosure checks and repair loops"
 traces = "Host-injected sinks; no environment variables or bundled destinations"
@@ -62,9 +64,9 @@ flowchart TD
     end
 
     subgraph Providers["Provider adapters"]
-        OR["OpenRouter"]
+        OR["OpenRouter chat via Vercel AI SDK Core"]
         GI["Google Interactions"]
-        TTS["OpenRouter TTS"]
+        Speech["Speech (Interactions or /audio/speech)"]
     end
 
     Profile --> Resolve
@@ -80,6 +82,8 @@ flowchart TD
     Runner --> TraceSink
 ```
 
+Hosts bind transports with `createProvider(profile, { gemini, openRouter })`. One door; protocol/provider (and speech role) pick the adapter.
+
 ### Turn Lifecycle
 
 ```mermaid
@@ -147,7 +151,19 @@ const profile = defineProfile({
   model: {
     protocol: "openAi",
     provider: "openrouter",
-    allow: ["gemini35FlashLite"],
+    allow: ["hostFastModel"],
+    config: {
+      hostFastModel: {
+        apiId: "perplexity/sonar",
+        openRouterId: "perplexity/sonar",
+        thinking: { on: "high", off: "minimal" },
+        thinkingLevels: ["minimal", "low", "medium", "high"],
+        summaries: { on: "auto", off: "none" },
+        maxOutputTokens: 8192,
+        temperature: 1,
+        keyBuiltins: [],
+      },
+    },
     thinking: "minimal",
     maxSteps: 1,
   },
@@ -221,7 +237,21 @@ Inbound and outbound safety are generic kernel hooks.
 ```ts
 const guardedProfile = defineProfile({
   id: "assistant.guarded",
-  model: { allow: ["gemini35FlashLite"] },
+  model: {
+    allow: ["hostFastModel"],
+    config: {
+      hostFastModel: {
+        apiId: "perplexity/sonar",
+        openRouterId: "perplexity/sonar",
+        thinking: { on: "high", off: "minimal" },
+        thinkingLevels: ["minimal", "low", "medium", "high"],
+        summaries: { on: "auto", off: "none" },
+        maxOutputTokens: 8192,
+        temperature: 1,
+        keyBuiltins: [],
+      },
+    },
+  },
   guardrails: {
     egress: {
       onBlock: "reject_to_agent",
@@ -250,33 +280,32 @@ Quota is optional. If a profile omits `guardrails.quota`, the quota helper retur
 
 ## Provider Adapters
 
-THEORUM includes provider adapters but does not own credentials.
+THEORUM includes provider adapters but does not own credentials. Bind them with one door:
 
 ```ts
-import { createOpenRouterProvider } from "jsr:@theorum/core/openrouter";
+import { createProvider, runTurn } from "jsr:@theorum/core";
 
-const provider = createOpenRouterProvider({
-  apiKey: hostSecrets.openRouterApiKey,
-  siteName: "Your app",
-  siteUrl: "https://example.com",
+const provider = createProvider(profile, {
+  gemini: { vault: hostGeminiKeyVault, fetch },
+  openRouter: { apiKey: hostSecrets.openRouterApiKey },
 });
+
+for await (const event of runTurn({ profile: profile.id, input: { text: "…" } }, provider)) {
+  // …
+}
 ```
 
-```ts
-import { createInteractionsProvider } from "jsr:@theorum/core/providers";
+`createProvider` routes from `profile.model.protocol` / `provider`. Speech roles use the same call — Interactions when Google, `/audio/speech` when openAi/openrouter (same `openRouter` credentials).
 
-const provider = createInteractionsProvider({
-  keys: hostGeminiKeyVault,
-  fetch,
-});
-```
+| Profile | Transport |
+| :--- | :--- |
+| `geminiInteractions` + `google` | Google Interactions (chat, image, speech) |
+| `openAi` + `openrouter` (chat) | OpenRouter chat completions |
+| `openAi` + `openrouter` (speech role) | OpenRouter `/audio/speech` |
 
-Provider support is intentionally split by wire protocol:
+OpenRouter uses Vercel AI SDK Core inside THEORUM's provider adapter. The adapter still emits THEORUM `TurnEvent` values and preserves raw provider evidence for citations/provenance where the normalized SDK stream does not expose enough detail.
 
-| Provider | Protocol | Use |
-| :--- | :--- | :--- |
-| OpenRouter | `openAi` | Chat completions, reasoning streams, tool calls, structured output, TTS gateway. |
-| Google Interactions | `geminiInteractions` | Native Google Interactions streaming, image response format, interaction continuity, grounding metadata. |
+Advanced OpenRouter exports live under `theorum/openrouter` (`createOpenRouterProvider`, `toOpenRouterPayload`, …). Prefer `createProvider` for turns unless the host needs to wire the OpenRouter adapter directly.
 
 ---
 
@@ -285,11 +314,15 @@ Provider support is intentionally split by wire protocol:
 | Entrypoint | Purpose |
 | :--- | :--- |
 | `jsr:@theorum/core` / `theorum` | Main kernel API: profiles, schemas, runner, core types, provider constructors. |
-| `jsr:@theorum/core/kernel` / `theorum/kernel` | Profile, turn, event, tool, egress, provider, and schema types. |
-| `jsr:@theorum/core/providers` / `theorum/providers` | Provider constructors and provider utility types. |
-| `jsr:@theorum/core/openrouter` / `theorum/openrouter` | OpenRouter payload and streaming adapter. |
+| `jsr:@theorum/core/kernel` / `theorum/kernel` | Profile/turn types, tool catalog, `requireModelSpec`, thinking clamps over host model maps. |
+| `jsr:@theorum/core/providers` / `theorum/providers` | `createProvider` + Gemini vault types. |
+| `jsr:@theorum/core/openrouter` / `theorum/openrouter` | Direct OpenRouter provider adapter and payload helpers (advanced). |
 | `jsr:@theorum/core/guardrails` / `theorum/guardrails` | Sanitization, public error mapping, inbound injection/sensitive-data primitives. |
 | `jsr:@theorum/core/observability` / `theorum/observability` | Trace sinks and trace record helpers. |
+| `jsr:@theorum/core/host` / `theorum/host` | Optional Deno HTTP helpers (`json`, status mapping, cutout mint flush). |
+| `jsr:@theorum/core/cli` / `theorum/cli` | Profile inspection and stress-test CLI (`theorum` binary on npm). |
+| `jsr:@theorum/core/presets` / `theorum/presets` | Optional convenience packs (`registerGooglePreset`, …). |
+| `jsr:@theorum/core/presets/google` / `theorum/presets/google` | Google builtins (search/maps/urlContext) + Interactions/OpenRouter wire metadata. |
 
 Internal files remain present in source for maintainability, but package consumers should use the public entrypoints above.
 
@@ -304,7 +337,15 @@ npm run lint
 deno publish --dry-run --allow-dirty
 ```
 
-Build the npm package from the Deno source:
+Run the packaged CLI locally:
+
+```bash
+deno task theorum --help
+# or after npm install -g / npx:
+# npx theorum --help
+```
+
+Build the npm package from the Deno source (publish only from `npm/`):
 
 ```bash
 npm run build:npm
@@ -312,6 +353,21 @@ cd npm
 npm pack
 ```
 
+Run a live OpenRouter smoke test with a host-resolved key. The key is passed as an argument and is never read from a Theorum `.env` file.
+
+```bash
+deno run --allow-net scripts/verify-live.ts --api-key "$OPENROUTER_API_KEY"
+```
+
+The default live verifier uses `perplexity/sonar` because it is broadly available on OpenRouter. Hosts can override both the profile-facing model id and provider-native id:
+
+```bash
+deno run --allow-net scripts/verify-live.ts \
+  --api-key "$OPENROUTER_API_KEY" \
+  --model hostFastModel \
+  --api-id perplexity/sonar
+```
+
 ---
 
 ## Package Boundary

package/deno.json

@@ -0,0 +1,57 @@
+{
+  "name": "@theorum/core",
+  "version": "0.1.4",
+  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, dynamic tools, provider adapters, guardrails, and host-injected traces.",
+  "license": "MIT",
+  "keywords": [
+    "agent",
+    "ai",
+    "kernel",
+    "llm",
+    "typescript",
+    "deno",
+    "node",
+    "openrouter",
+    "gemini"
+  ],
+  "exports": {
+    ".": "./mod.ts",
+    "./kernel": "./src/kernel/mod.ts",
+    "./providers": "./src/providers/mod.ts",
+    "./openrouter": "./src/providers/openrouter-mod.ts",
+    "./guardrails": "./src/guardrails/mod.ts",
+    "./observability": "./src/observability/mod.ts",
+    "./host": "./src/host/mod.ts",
+    "./cli": "./src/cli/index.ts",
+    "./presets": "./src/presets/mod.ts",
+    "./presets/google": "./src/presets/google.ts"
+  },
+  "publish": {
+    "exclude": [
+      ".fallow/",
+      ".fallowrc.jsonc",
+      ".github/",
+      "ast-grep-rules/",
+      "biome.json",
+      "coverage/",
+      "node_modules/",
+      "npm/",
+      "package-lock.json",
+      "scripts/",
+      "sgconfig.yml",
+      "tests/"
+    ]
+  },
+  "imports": {
+    "@openrouter/ai-sdk-provider": "npm:@openrouter/ai-sdk-provider@1.5.4",
+    "ai": "npm:ai@5.0.244",
+    "@std/assert": "jsr:@std/assert@^1.0.0"
+  },
+  "tasks": {
+    "theorum": "deno run --allow-read --allow-write --allow-net src/cli/index.ts",
+    "test": "deno test --allow-read --allow-write --allow-net tests/",
+    "check": "deno check mod.ts",
+    "lint": "npm run lint",
+    "verify:live": "deno run --allow-net scripts/verify-live.ts"
+  }
+}