theorum 0.1.2 → 0.1.4

package/docs/SECRETS.md

@@ -9,39 +9,44 @@ Host applications own credentials, runtime configuration, and secret storage. Th
 - Do not create `.env` files in this repository.
 - Do not commit key templates to this repository.
 - Do not teach Theorum to discover keys from the shell or process environment.
-- Business applications pass credentials into provider constructors or transport objects.
+- Business applications pass credentials into `createProvider`.
 
-## 2. OpenRouter
+## 2. Single door: `createProvider`
 
 ```ts
-import { createOpenRouterProvider } from 'theorum/openrouter';
-
-const provider = createOpenRouterProvider({
-  apiKey: hostResolvedOpenRouterKey,
-});
-```
-
-## 3. Google Interactions
-
-```ts
-import { createInteractionsProvider } from 'theorum/providers';
-
-const provider = createInteractionsProvider({
-  vault: {
-    freeA: hostResolvedFreeAKey,
-    freeB: hostResolvedFreeBKey,
-    freeC: hostResolvedFreeCKey,
-    paid: hostResolvedPaidKey,
+import { createProvider, runTurn } from 'theorum';
+
+const provider = createProvider(profile, {
+  // geminiInteractions / google
+  gemini: {
+    vault: {
+      freeA: hostResolvedFreeAKey,
+      freeB: hostResolvedFreeBKey,
+      freeC: hostResolvedFreeCKey,
+      paid: hostResolvedPaidKey,
+    },
+  },
+  // openAi / openrouter (chat or speech role — same credentials)
+  openRouter: {
+    apiKey: hostResolvedOpenRouterKey,
   },
 });
+
+for await (const event of runTurn({ profile: profile.id, input: { text: '…' } }, provider)) {
+  // …
+}
 ```
 
-## 4. Tracing
+`createProvider` picks the transport from `profile.model.protocol` / `provider` (and whether the profile is a speech role). Hosts do not choose a separate speech constructor.
+
+## 3. Tracing
 
 Tracing is silent by default. Hosts opt in by passing a sink to `runTurn`.
 
 ```ts
-import { jsonlSink, runTurn } from 'theorum';
+import { createProvider, jsonlSink, runTurn } from 'theorum';
+
+const provider = createProvider(profile, { openRouter: { apiKey: hostResolvedOpenRouterKey } });
 
 for await (const event of runTurn(request, provider, jsonlSink(hostTraceDir))) {
   // stream events

package/mod.ts

@@ -0,0 +1,95 @@
+/**
+ * THEORUM public API.
+ *
+ * Import this entrypoint when an application wants the complete kernel surface:
+ * profile registration, turn execution, provider constructors, guardrails,
+ * observability sinks, and public type contracts.
+ *
+ * @example
+ * ```ts
+ * import { defineProfile, registerProfile, runTurn } from "jsr:@theorum/core";
+ *
+ * const profile = defineProfile({
+ *   id: "assistant.basic",
+ *   model: {
+ *     allow: ["gemini35FlashLite"],
+ *     config: {
+ *       gemini35FlashLite: {
+ *         apiId: "gemini-3.5-flash-lite",
+ *         thinking: { on: "high", off: "minimal" },
+ *         thinkingLevels: ["minimal", "low", "medium", "high"],
+ *         summaries: { on: "auto", off: "none" },
+ *         maxOutputTokens: 8192,
+ *         temperature: 1,
+ *         keyBuiltins: [],
+ *       },
+ *     },
+ *   },
+ *   tools: { allow: [] },
+ *   inputs: { text: true },
+ *   outputs: {},
+ *   guardrails: { quota: { perDay: 100 } },
+ * });
+ *
+ * registerProfile(profile);
+ * ```
+ *
+ * @module
+ */
+
+export { publicError, TheorumError } from './src/guardrails/error.ts';
+export type { QuotaSlotStatus } from './src/guardrails/quota.ts';
+export {
+  clientIp,
+  quotaMessage,
+  releaseSlot,
+  resetSlots,
+  skipQuota,
+  takeSlot,
+} from './src/guardrails/quota.ts';
+export {
+  PROJECT_ID_MAX,
+  sanitizeProjectId,
+  sanitizeText,
+  sanitizeTurnRequest,
+} from './src/guardrails/sanitize.ts';
+export { runTurn } from './src/kernel/engine/runner.ts';
+export {
+  CATALOG,
+  clampThinkingLevel,
+  clampThinkingLevelForApiId,
+  geminiKindForMime,
+  getTool,
+  listBuiltinIds,
+  mimeAllowed,
+  mimeEssence,
+  modelEntryByApiId,
+  registerTools,
+  requireModelSpec,
+  resetTools,
+} from './src/kernel/registry/catalog.ts';
+export type { ProfileDefinition } from './src/kernel/registry/profiles.ts';
+export {
+  clearProfiles,
+  defineProfile,
+  getProfile,
+  hasProfile,
+  listProfiles,
+  registerProfile,
+  registerProfiles,
+} from './src/kernel/registry/profiles.ts';
+export { projectProfile, resolveTurn } from './src/kernel/registry/resolve.ts';
+export { getStructured, registerStructured } from './src/kernel/registry/schemas.ts';
+export { executeTool } from './src/kernel/registry/tools.ts';
+export type * from './src/kernel/types.ts';
+export {
+  jsonlSink,
+  memorySink,
+  noopSink,
+  resolveTraceDir,
+  sinkFromDir,
+  writeTrace,
+} from './src/observability/trace.ts';
+export type { TraceRecord } from './src/observability/trace-record.ts';
+export type { CreateProviderOptions, GeminiTransport, GeminiVault } from './src/providers/mod.ts';
+export { createProvider } from './src/providers/mod.ts';

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "theorum",
-  "version": "0.1.2",
+  "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",
+  "type": "module",
   "keywords": [
     "agent",
     "ai",
@@ -13,36 +15,42 @@
     "openrouter",
     "gemini"
   ],
-  "license": "MIT",
-  "module": "./esm/mod.js",
   "exports": {
-    ".": {
-      "import": "./esm/mod.js"
-    },
-    "./kernel": {
-      "import": "./esm/src/kernel/mod.js"
-    },
-    "./providers": {
-      "import": "./esm/src/providers/mod.js"
-    },
-    "./openrouter": {
-      "import": "./esm/src/providers/openrouter.js"
-    },
-    "./guardrails": {
-      "import": "./esm/src/guardrails/mod.js"
-    },
-    "./observability": {
-      "import": "./esm/src/observability/mod.js"
-    }
+    ".": "./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"
   },
-  "scripts": {},
-  "type": "module",
-  "sideEffects": false,
+  "files": [
+    "README.md",
+    "deno.json",
+    "deno.lock",
+    "docs/",
+    "mod.ts",
+    "src/"
+  ],
   "dependencies": {
-    "@deno/shim-deno": "~0.18.0"
+    "@openrouter/ai-sdk-provider": "1.5.4",
+    "ai": "5.0.244"
   },
-  "devDependencies": {
-    "@types/node": "^20.9.0"
+  "scripts": {
+    "build:npm": "deno run --allow-read --allow-write --allow-env --allow-net --allow-run=npm scripts/build-npm.ts",
+    "test": "deno test --allow-read --allow-write --allow-net",
+    "coverage": "rm -rf coverage && deno test --allow-read --allow-write --allow-net --coverage=coverage tests/ && deno coverage coverage --lcov --output=coverage/lcov.info && node scripts/lcov-to-istanbul.mjs",
+    "lint:biome": "biome check .",
+    "lint:ast-grep": "ast-grep scan",
+    "lint:fallow": "npm run coverage && fallow audit && fallow health && fallow dupes && fallow dead-code",
+    "lint": "npm run lint:biome && npm run lint:ast-grep && npm run lint:fallow"
   },
-  "_generatedBy": "dnt@0.43.2"
-}
+  "devDependencies": {
+    "@biomejs/biome": "^2.5.8",
+    "@ast-grep/cli": "^0.41.0",
+    "fallow": "3.17.0"
+  }
+}

package/src/cli/commands/profile.ts

@@ -0,0 +1,57 @@
+import { getProfile, listProfiles } from '../../kernel/registry/profiles.ts';
+import type { Profile } from '../../kernel/types.ts';
+
+function formatProfileInputs(p: Profile): string {
+  const inputs: string[] = [];
+  if (p.inputs.text !== false) inputs.push('text');
+  if (p.inputs.voice) inputs.push('voice');
+  if (p.inputs.attachments) inputs.push(`attachments [${p.inputs.attachments.accept?.join(', ')}]`);
+  return inputs.join(' | ');
+}
+
+function printProfileCard(p: Profile): void {
+  const tools = p.tools.allow?.length ? p.tools.allow.join(', ') : 'none';
+  const models = p.model.allow?.join(', ') || 'default';
+  const structured =
+    typeof p.outputs.structured === 'string'
+      ? p.outputs.structured
+      : p.outputs.structured
+        ? 'custom'
+        : 'none';
+
+  console.log(` • Profile: ${p.id.padEnd(16)} (handle: ${p.identity.handle})`);
+  console.log(`   - Models:     ${models}`);
+  console.log(`   - Inputs:     ${formatProfileInputs(p)}`);
+  console.log(`   - Tools:      ${tools}`);
+  console.log(`   - Structured: ${structured}`);
+  console.log(`   - Key Bucket: ${p.model.key ?? 'freeA'}`);
+  console.log('-'.repeat(70));
+}
+
+export function listProfilesCommand(): void {
+  const profiles = listProfiles();
+  console.log('\n Registered Theorum Profiles:');
+  console.log('='.repeat(70));
+  if (profiles.length === 0) {
+    console.log('  (No profiles registered in runtime)');
+    console.log(`${'='.repeat(70)}\n`);
+    return;
+  }
+
+  for (const p of profiles) {
+    printProfileCard(p);
+  }
+  console.log(`Total: ${profiles.length} profiles registered.\n`);
+}
+
+export function showProfileCommand(profileId: string): void {
+  try {
+    const profile = getProfile(profileId);
+    console.log(`\n Profile Details: ${profileId}`);
+    console.log('='.repeat(70));
+    console.log(JSON.stringify(profile, null, 2));
+    console.log(`${'='.repeat(70)}\n`);
+  } catch (err) {
+    console.error(`\n Error: ${err instanceof Error ? err.message : String(err)}\n`);
+  }
+}

package/src/cli/commands/run.ts

@@ -0,0 +1,66 @@
+import { runTurn } from '../../kernel/engine/runner.ts';
+import { getProfile } from '../../kernel/registry/profiles.ts';
+import type { ModelProvider, TurnEvent, TurnRequest } from '../../kernel/types.ts';
+
+export interface RunOptions {
+  profile: string;
+  prompt?: string;
+  mode?: string;
+  search?: boolean;
+  map?: boolean;
+  provider?: ModelProvider;
+}
+
+function handleRunEvent(event: TurnEvent): void {
+  if (event.type === 'thought' && event.text) {
+    Deno.stdout.write(new TextEncoder().encode(`\x1b[2m${event.text}\x1b[0m`));
+  } else if (event.type === 'text' && event.text) {
+    Deno.stdout.write(new TextEncoder().encode(event.text));
+  } else if (event.type === 'tool' && event.tool) {
+    console.log(`\n\x1b[33m⚡ [Tool Call] ${event.tool.name}\x1b[0m:`, event.tool.arguments);
+  } else if (event.type === 'structured' && event.structured) {
+    console.log('\n\x1b[32m✓ [Structured Output]\x1b[0m:');
+    console.log(JSON.stringify(event.structured, null, 2));
+  } else if (event.type === 'media' && event.media) {
+    console.log(`\n\x1b[34m🖼 [Media Output]\x1b[0m (${event.media.mimeType})`);
+  } else if (event.type === 'error' && event.error) {
+    console.error(`\n\x1b[31m✗ Error\x1b[0m: ${event.error}`);
+  }
+}
+
+export async function runCommand(options: RunOptions): Promise<void> {
+  getProfile(options.profile);
+  const provider = options.provider;
+  if (!provider) {
+    console.error(
+      '\n\x1b[31mExecution Failed\x1b[0m: Theorum CLI does not create providers or read keys. Run turns from a host app with an explicit ModelProvider.\n',
+    );
+    return;
+  }
+
+  const prompt = options.prompt || 'Hello! Please introduce your capabilities.';
+  const tools: Record<string, boolean> = {};
+  if (options.search) tools.googleSearch = true;
+  if (options.map) tools.googleMaps = true;
+
+  const req: TurnRequest = {
+    profile: options.profile,
+    select: options.mode,
+    tools: Object.keys(tools).length > 0 ? tools : undefined,
+    input: { text: prompt },
+  };
+
+  console.log(`\n▶ [RUNNING TURN] Profile: ${options.profile} (${options.mode ?? 'default'})`);
+  console.log(`Prompt: "${prompt}"\n`);
+
+  try {
+    for await (const event of runTurn(req, provider)) {
+      handleRunEvent(event);
+    }
+    console.log('\n');
+  } catch (err) {
+    console.error(
+      `\n\x1b[31mExecution Failed\x1b[0m: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+  }
+}

package/src/cli/commands/test.ts

@@ -0,0 +1,195 @@
+import { runTurn } from '../../kernel/engine/runner.ts';
+import { getProfile, listProfiles } from '../../kernel/registry/profiles.ts';
+import type { ModelProvider, Profile, TurnEvent, TurnRequest } from '../../kernel/types.ts';
+import {
+  buildCustomTurnRequest,
+  type MatrixOptions,
+  synthesizeMatrixCombos,
+} from '../matrix/synthesizer.ts';
+
+export interface TestRunResult {
+  passed: boolean;
+  name: string;
+  durationSec: number;
+  tokensTotal?: number;
+  error?: string;
+}
+
+interface TestExecutionAccumulator {
+  totalTokens: number;
+  hasError: boolean;
+  errorMessage: string;
+}
+
+function printTestHeader(req: TurnRequest, testName: string): void {
+  const activeTools = Object.entries(req.tools ?? {})
+    .filter(([, v]) => Boolean(v))
+    .map(([k]) => k)
+    .join(', ');
+
+  console.log(`\n▶ [THEORUM TEST] ${testName}`);
+  console.log(`  Profile:     ${req.profile} (Mode: ${req.select ?? 'default'})`);
+  console.log(`  Tools:       ${activeTools || 'none'}`);
+  console.log(
+    `  Attachments: ${req.input?.attachments?.length ?? 0} file(s) | Voice: ${req.input?.voice?.length ? 'yes' : 'no'}`,
+  );
+  console.log(`  ${'-'.repeat(60)}`);
+}
+
+function processTestEvent(event: TurnEvent, acc: TestExecutionAccumulator): void {
+  if (event.type === 'thought' && event.text) {
+    Deno.stdout.write(new TextEncoder().encode('.'));
+  } else if (event.type === 'tool' && event.tool) {
+    console.log(
+      `\n  ⚡ [Tool Dispatched] ${event.tool.name}(${JSON.stringify(event.tool.arguments ?? {})})`,
+    );
+  } else if (event.type === 'structured') {
+    console.log(`\n  ✓ [Structured Schema Validated]`);
+  } else if (event.type === 'media') {
+    console.log(`\n  ✓ [Media Generated] (${event.media?.mimeType})`);
+  } else if (event.type === 'tokens' && event.tokens) {
+    acc.totalTokens = event.tokens.total;
+  } else if (event.type === 'error' && event.error) {
+    acc.hasError = true;
+    acc.errorMessage = event.error;
+    console.error(`\n  [Test Error Detail]: ${event.error}`);
+  }
+}
+
+function printTestResult(
+  passed: boolean,
+  durationSec: number,
+  acc: TestExecutionAccumulator,
+): void {
+  if (passed) {
+    console.log(
+      `\n  ✓ STATUS: PASSED (took ${durationSec.toFixed(2)}s, ${acc.totalTokens ? `${acc.totalTokens} tokens` : 'ok'})`,
+    );
+  } else {
+    console.log(`\n  ✗ STATUS: FAILED: ${acc.errorMessage} (${durationSec.toFixed(2)}s)`);
+  }
+}
+
+export async function executeSingleTest(
+  req: TurnRequest,
+  testName: string,
+  provider?: ModelProvider,
+): Promise<TestRunResult> {
+  const start = Date.now();
+  getProfile(req.profile);
+  printTestHeader(req, testName);
+
+  const acc: TestExecutionAccumulator = {
+    totalTokens: 0,
+    hasError: false,
+    errorMessage: '',
+  };
+
+  try {
+    if (!provider) {
+      throw new Error(
+        'Theorum CLI does not create providers or read keys. Pass an explicit ModelProvider from the host app.',
+      );
+    }
+    for await (const event of runTurn(req, provider)) {
+      processTestEvent(event, acc);
+    }
+  } catch (err) {
+    acc.hasError = true;
+    acc.errorMessage = err instanceof Error ? err.message : String(err);
+  }
+
+  const durationSec = (Date.now() - start) / 1000;
+  const passed = !acc.hasError;
+  printTestResult(passed, durationSec, acc);
+
+  return {
+    passed,
+    name: testName,
+    durationSec,
+    tokensTotal: acc.totalTokens,
+    error: acc.errorMessage,
+  };
+}
+
+function resolveTargetProfiles(
+  profileId: string | undefined,
+  all: boolean | undefined,
+): Profile[] | null {
+  if (all) {
+    return listProfiles();
+  }
+  if (profileId) {
+    try {
+      return [getProfile(profileId)];
+    } catch (err) {
+      console.error(`\n Error: ${err instanceof Error ? err.message : String(err)}\n`);
+      return null;
+    }
+  }
+  console.error(
+    'Error: Please specify a profile ID (e.g. `theorum test --profile your-profile`) or `--all`.',
+  );
+  return null;
+}
+
+async function runProfileMatrix(
+  profile: Profile,
+  provider?: ModelProvider,
+): Promise<TestRunResult[]> {
+  const results: TestRunResult[] = [];
+  const combos = synthesizeMatrixCombos(profile);
+  for (const combo of combos) {
+    const res = await executeSingleTest(combo.req, `${profile.id} [${combo.name}]`, provider);
+    results.push(res);
+  }
+  return results;
+}
+
+async function runProfileSingle(
+  profile: Profile,
+  options: MatrixOptions,
+  provider?: ModelProvider,
+): Promise<TestRunResult> {
+  const req = buildCustomTurnRequest(profile, options);
+  const testName = options.lite ? `${profile.id} [Lite]` : `${profile.id} [Stress Combo]`;
+  return await executeSingleTest(req, testName, provider);
+}
+
+function printSummaryReport(results: TestRunResult[]): boolean {
+  console.log(`\n${'='.repeat(70)}`);
+  console.log(' TEST SUMMARY:');
+  console.log('='.repeat(70));
+  let allPassed = true;
+  for (const r of results) {
+    const status = r.passed ? '✓ PASSED' : '✗ FAILED';
+    console.log(`  ${status.padEnd(10)} ${r.name.padEnd(45)} (${r.durationSec.toFixed(2)}s)`);
+    if (!r.passed) {
+      allPassed = false;
+      if (r.error) console.log(`             Reason: ${r.error}`);
+    }
+  }
+  console.log(`${'='.repeat(70)}\n`);
+  return allPassed;
+}
+
+export async function testProfileCommand(
+  profileId?: string,
+  options: MatrixOptions & { all?: boolean; matrix?: boolean; provider?: ModelProvider } = {},
+): Promise<boolean> {
+  const targetProfiles = resolveTargetProfiles(profileId, options.all);
+  if (!targetProfiles || targetProfiles.length === 0) {
+    return false;
+  }
+
+  const results: TestRunResult[] = [];
+  for (const profile of targetProfiles) {
+    if (options.matrix) {
+      results.push(...(await runProfileMatrix(profile, options.provider)));
+    } else {
+      results.push(await runProfileSingle(profile, options, options.provider));
+    }
+  }
+
+  return printSummaryReport(results);
+}