@hasna/knowledge 0.2.9 → 0.2.11

package/src/cli.ts

@@ -5,15 +5,10 @@
  * Licensed under the Apache License, Version 2.0
  */
 import { defaultStorePath, loadStore, saveStore, withLock, makeId, makeShortId, ensureStore, type KnowledgeItem } from './store';
-import { ensureKnowledgeWorkspace, readKnowledgeConfig, resolveScopedWorkspace } from './workspace';
-import { getKnowledgeDbStats, migrateKnowledgeDb, openKnowledgeDb } from './knowledge-db';
-import { createArtifactStore } from './artifact-store';
-import { initializeWikiLayout } from './wiki-layout';
-import { ingestOpenFilesManifest } from './manifest-ingest';
-import { ingestSourceRef } from './source-ingest';
-import { consumeOpenFilesOutbox } from './outbox-consume';
-import { resolveOpenFilesSource } from './source-resolver';
-import { approvalStatus, assertS3ReadAllowed, assertWebSearchAllowed, createApprovalGate, recordAuditEvent, recordRedactionFindings, redactSecrets, resolveSafetyPolicy } from './safety';
+import { openKnowledgeDb } from './knowledge-db';
+import { createKnowledgeService } from './service';
+import { assertProviderCredentials, parseModelRef, resolveModelRef, type AiProviderId } from './providers';
+import { approvalStatus, assertS3ReadAllowed, assertWebSearchAllowed, createApprovalGate, recordAuditEvent, recordRedactionFindings, redactSecrets } from './safety';
 import pkg from '../package.json' with { type: 'json' };
 
 type LogLevel = 'debug' | 'info' | 'warn' | 'error';
@@ -65,7 +60,7 @@ interface ParseResult {
   flags: Flags;
 }
 
-const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'db', 'wiki', 'source', 'ingest', 'reindex', 'safety', 'help'];
+const COMMANDS = ['add', 'list', 'get', 'delete', 'update', 'archive', 'restore', 'upsert', 'untag', 'export', 'prune', 'dedupe', 'stats', 'paths', 'db', 'wiki', 'source', 'ingest', 'reindex', 'providers', 'safety', 'help'];
 const COMMAND_ALIASES: Record<string, string> = {
   ls: 'list',
   rm: 'delete',
@@ -173,6 +168,7 @@ Commands:
   ingest manifest <file|s3://> Ingest an open-files manifest into knowledge.db
   ingest source <source-ref>   Ingest a read-only source ref into knowledge.db
   reindex outbox <file|s3://>  Consume open-files change events and invalidate chunks
+  providers status|models|check Inspect AI SDK provider config and credentials
   safety status|check|approve|audit|redact
   help [command]               Show help
 
@@ -239,6 +235,7 @@ function printCommandHelp(command: string): void {
   if (command === 'source') { console.log('Usage: open-knowledge source resolve <source-ref> [--purpose knowledge_answer|knowledge_index] [--limit <n>] [--scope local|global|project] [--json]'); return; }
   if (command === 'ingest') { console.log('Usage: open-knowledge ingest manifest <file|s3://bucket/key> | source <source-ref> [--purpose knowledge_index] [--scope local|global|project] [--json]'); return; }
   if (command === 'reindex') { console.log('Usage: open-knowledge reindex outbox <file|s3://bucket/key> [--scope local|global|project] [--json]'); return; }
+  if (command === 'providers') { console.log('Usage: open-knowledge providers status|models|check [provider|model-alias] [--scope local|global|project] [--json]'); return; }
   if (command === 'safety') { console.log('Usage: open-knowledge safety status|check|approve|audit|redact [args] [--scope local|global|project] [--json]'); return; }
   printGlobalHelp();
 }
@@ -284,11 +281,11 @@ async function run(argv: string[]): Promise<void> {
   if (flags.completions) {
     const shell = flags.completions;
     if (shell === 'bash') {
-      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
+      console.log(`_open_knowledge() { local cur; cur="${"$"}{COMP_WORDS[COMP_CWORD]}"; COMPREPLY=($(compgen -W "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex providers safety help ls rm edit unarchive --json --yes --help --version --desc --page --limit --search --sort --id --store --title --content --url --tag --format --completions --purpose --no-color --scope --archived --include-archived" -- "$cur")); }; complete -F _open_knowledge open-knowledge`);
     } else if (shell === 'zsh') {
-      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
+      console.log(`#compdef open-knowledge\n_open_knowledge() { _arguments -C "1: :(add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex providers safety help ls rm edit unarchive)" "(--json)--json" "(--yes)-y" "(--help)--help" "(--version)--version" "(--desc)--desc" "(--archived)--archived" "(--include-archived)--include-archived" "(-p --page)"{-p,--page}"[page number]:number:" "(-l --limit)"{-l,--limit}"[items per page]:number:" "(-s --search)"{-s,--search}"[search text]:text:" "(--sort)--sort"\{created,title\}:" "(--id)--id[item id]:id:" "(--store)--store[store path]:path:" "(--title)--title[new title]:" "(--content)--content[new content]:" "(--url)--url[source url]:" "(-t --tag)"{-t,--tag}"[tag]:tag:" "(--format)--format[json|jsonl]:" "(--completions)--completions[output completions]:shell:(bash zsh fish):" "(--purpose)--purpose[purpose]:" "(--no-color)--no-color[disable color]" "(--scope)--scope"\{local,global,project\}:" }; _open_knowledge`);
     } else if (shell === 'fish') {
-      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
+      console.log(`complete -c open-knowledge -f; complete -c open-knowledge -a "add list get update archive restore upsert untag delete export prune dedupe stats paths db wiki source ingest reindex providers safety help ls rm edit unarchive"; complete -c open-knowledge -l json; complete -c open-knowledge -l yes -s y; complete -c open-knowledge -l help -s h; complete -c open-knowledge -l version -s v; complete -c open-knowledge -l desc; complete -c open-knowledge -l archived; complete -c open-knowledge -l include-archived; complete -c open-knowledge -s p -l page; complete -c open-knowledge -s l -l limit; complete -c open-knowledge -s s -l search; complete -c open-knowledge -l sort; complete -c open-knowledge -l id; complete -c open-knowledge -l store; complete -c open-knowledge -l title; complete -c open-knowledge -l content; complete -c open-knowledge -l url; complete -c open-knowledge -s t -l tag; complete -c open-knowledge -l format; complete -c open-knowledge -l completions; complete -c open-knowledge -l purpose; complete -c open-knowledge -l no-color; complete -c open-knowledge -l scope -a "local global project"`);
     } else {
       throw new Error("Invalid --completions value. Use 'bash', 'zsh', or 'fish'.");
     }
@@ -299,71 +296,49 @@ async function run(argv: string[]): Promise<void> {
 
   if (!command || flags.help || command === 'help') { printCommandHelp(positional[1]); return; }
 
-  const workspace = resolveScopedWorkspace(flags.scope);
+  const service = createKnowledgeService({ scope: flags.scope });
   let storePath = flags.store;
   if (!storePath) {
     if (flags.scope === 'project' || flags.scope === 'local') {
-      storePath = ensureKnowledgeWorkspace(workspace.home).jsonStorePath;
+      storePath = service.jsonStorePath();
     } else {
       storePath = defaultStorePath();
     }
   }
 
   if (command === 'paths') {
-    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
-    output({
-      ok: true,
-      scope: flags.scope ?? 'global',
-      home: resolvedWorkspace.home,
-      config_path: resolvedWorkspace.configPath,
-      json_store_path: resolvedWorkspace.jsonStorePath,
-      knowledge_db_path: resolvedWorkspace.knowledgeDbPath,
-      artifacts_dir: resolvedWorkspace.artifactsDir,
-      indexes_dir: resolvedWorkspace.indexesDir,
-      logs_dir: resolvedWorkspace.logsDir,
-      runs_dir: resolvedWorkspace.runsDir,
-      schemas_dir: resolvedWorkspace.schemasDir,
-      wiki_dir: resolvedWorkspace.wikiDir,
-      config: readKnowledgeConfig(resolvedWorkspace.configPath),
-      message: resolvedWorkspace.home,
-    }, flags.json);
+    output(service.paths(), flags.json);
     return;
   }
 
   if (command === 'db') {
     const action = positional[1] ?? 'init';
-    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
     if (action !== 'init' && action !== 'stats') {
       throw new Error("Invalid db action. Use 'init' or 'stats'.");
     }
     if (action === 'init') {
-      const result = migrateKnowledgeDb(resolvedWorkspace.knowledgeDbPath);
+      const result = service.initDb();
       output({ ok: true, ...result, message: `Initialized ${result.path}` }, flags.json);
       return;
     }
-    migrateKnowledgeDb(resolvedWorkspace.knowledgeDbPath);
-    const stats = getKnowledgeDbStats(resolvedWorkspace.knowledgeDbPath);
-    output({ ok: true, path: resolvedWorkspace.knowledgeDbPath, ...stats, message: `knowledge.db schema v${stats.schema_version}` }, flags.json);
+    const stats = service.dbStats();
+    output({ ok: true, path: service.workspace.knowledgeDbPath, ...stats, message: `knowledge.db schema v${stats.schema_version}` }, flags.json);
     return;
   }
 
   if (command === 'wiki') {
     const action = positional[1] ?? 'init';
     if (action !== 'init') throw new Error("Invalid wiki action. Use 'init'.");
-    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
-    const config = readKnowledgeConfig(resolvedWorkspace.configPath);
-    const artifactStore = createArtifactStore(config, resolvedWorkspace);
-    const result = await initializeWikiLayout(artifactStore);
-    output({ ok: true, ...result, message: `Initialized wiki layout in ${resolvedWorkspace.home}` }, flags.json);
+    const result = await service.initWiki();
+    output({ ok: true, ...result, message: `Initialized wiki layout in ${service.workspace.home}` }, flags.json);
     return;
   }
 
   if (command === 'safety') {
     const action = positional[1] ?? 'status';
-    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
-    const config = readKnowledgeConfig(resolvedWorkspace.configPath);
-    const policy = resolveSafetyPolicy(config, resolvedWorkspace);
-    migrateKnowledgeDb(resolvedWorkspace.knowledgeDbPath);
+    const resolvedWorkspace = service.ensureWorkspace();
+    const policy = service.safetyPolicy();
+    service.initDb();
     const db = openKnowledgeDb(resolvedWorkspace.knowledgeDbPath);
     try {
       if (action === 'status') {
@@ -489,15 +464,9 @@ async function run(argv: string[]): Promise<void> {
     if (action !== 'resolve') throw new Error("Invalid source action. Use 'resolve'.");
     const sourceRef = positional[2];
     if (!sourceRef) throw new Error('Usage: open-knowledge source resolve <source-ref>');
-    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
-    const config = readKnowledgeConfig(resolvedWorkspace.configPath);
-    const safetyPolicy = resolveSafetyPolicy(config, resolvedWorkspace);
-    const result = await resolveOpenFilesSource({
-      dbPath: resolvedWorkspace.knowledgeDbPath,
-      sourceRef,
+    const result = await service.resolveSource(sourceRef, {
       purpose: flags.purpose,
       limit: flags.limit,
-      safetyPolicy,
     });
     output({
       ok: true,
@@ -511,31 +480,17 @@ async function run(argv: string[]): Promise<void> {
 
   if (command === 'ingest') {
     const action = positional[1] ?? '';
-    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
-    const config = readKnowledgeConfig(resolvedWorkspace.configPath);
-    const safetyPolicy = resolveSafetyPolicy(config, resolvedWorkspace);
     if (action === 'manifest') {
       const input = positional[2];
       if (!input) throw new Error('Usage: open-knowledge ingest manifest <file|s3://bucket/key>');
-      const result = await ingestOpenFilesManifest({
-        dbPath: resolvedWorkspace.knowledgeDbPath,
-        input,
-        config,
-        safetyPolicy,
-      });
+      const result = await service.ingestManifest(input);
       output({ ok: true, ...result, message: `Ingested ${result.items_seen} manifest item(s)` }, flags.json);
       return;
     }
     if (action === 'source') {
       const sourceRef = positional[2];
       if (!sourceRef) throw new Error('Usage: open-knowledge ingest source <source-ref>');
-      const result = await ingestSourceRef({
-        dbPath: resolvedWorkspace.knowledgeDbPath,
-        sourceRef,
-        purpose: flags.purpose,
-        config,
-        safetyPolicy,
-      });
+      const result = await service.ingestSource(sourceRef, flags.purpose);
       output({ ok: true, ...result, message: `Ingested source ${result.source_ref} (${result.chunks_inserted} chunks)` }, flags.json);
       return;
     }
@@ -547,19 +502,35 @@ async function run(argv: string[]): Promise<void> {
     if (action !== 'outbox') throw new Error("Invalid reindex action. Use 'outbox'.");
     const input = positional[2];
     if (!input) throw new Error('Usage: open-knowledge reindex outbox <file|s3://bucket/key>');
-    const resolvedWorkspace = ensureKnowledgeWorkspace(workspace.home);
-    const config = readKnowledgeConfig(resolvedWorkspace.configPath);
-    const safetyPolicy = resolveSafetyPolicy(config, resolvedWorkspace);
-    const result = await consumeOpenFilesOutbox({
-      dbPath: resolvedWorkspace.knowledgeDbPath,
-      input,
-      config,
-      safetyPolicy,
-    });
+    const result = await service.consumeOutbox(input);
     output({ ok: true, ...result, message: `Consumed ${result.events_seen} outbox event(s)` }, flags.json);
     return;
   }
 
+  if (command === 'providers') {
+    const action = positional[1] ?? 'status';
+    if (action === 'status') {
+      const status = service.providerStatus();
+      const configured = status.providers.filter((entry) => entry.configured).length;
+      output({ ok: true, ...status, message: `${configured}/${status.providers.length} provider credential(s) configured` }, flags.json);
+      return;
+    }
+    if (action === 'models') {
+      const models = service.modelRegistry();
+      output({ ok: true, models, message: `${models.length} model alias(es)` }, flags.json);
+      return;
+    }
+    if (action === 'check') {
+      const target = positional[2] ?? 'default';
+      const modelRef = resolveModelRef(target, service.config());
+      const parsed = parseModelRef(modelRef);
+      const credential = assertProviderCredentials(parsed.provider as AiProviderId, service.config());
+      output({ ok: true, target, model_ref: modelRef, provider: parsed.provider, model: parsed.model, credential, message: `${parsed.provider} credentials configured` }, flags.json);
+      return;
+    }
+    throw new Error("Invalid providers action. Use 'status', 'models', or 'check'.");
+  }
+
   ensureStore(storePath);
 
   if (command === 'add') {

package/src/mcp.js

@@ -5,10 +5,8 @@ import { z } from 'zod';
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import pkg from '../package.json' with { type: 'json' };
 import { defaultStorePath, loadStore, saveStore, makeId, withLock } from './store.ts';
-import { ensureKnowledgeWorkspace, readKnowledgeConfig, resolveScopedWorkspace } from './workspace.ts';
 import { parseSourceRef } from './source-ref.ts';
-import { resolveOpenFilesSource } from './source-resolver.ts';
-import { resolveSafetyPolicy } from './safety.ts';
+import { createKnowledgeService } from './service.ts';
 
 const storePathField = z.string().optional().describe('Path to the JSON store file');
 const scopeField = z.enum(['local', 'global', 'project']).optional().describe('Workspace scope');
@@ -28,7 +26,7 @@ function shortIdFor(id) {
 function resolveStorePath(storePath, scope) {
   if (storePath) return storePath;
   if (scope === 'project' || scope === 'local') {
-    return ensureKnowledgeWorkspace(resolveScopedWorkspace(scope).home).jsonStorePath;
+    return createKnowledgeService({ scope }).jsonStorePath();
   }
   return defaultStorePath();
 }
@@ -76,22 +74,7 @@ export function buildServer() {
   registerTool(server, 'ok_paths', 'Knowledge workspace paths', 'Show resolved workspace and store paths', {
     scope: scopeField,
   }, async ({ scope }) => {
-    const workspace = ensureKnowledgeWorkspace(resolveScopedWorkspace(scope).home);
-    return jsonText({
-      ok: true,
-      scope: scope ?? 'global',
-      home: workspace.home,
-      config_path: workspace.configPath,
-      json_store_path: workspace.jsonStorePath,
-      knowledge_db_path: workspace.knowledgeDbPath,
-      artifacts_dir: workspace.artifactsDir,
-      indexes_dir: workspace.indexesDir,
-      logs_dir: workspace.logsDir,
-      runs_dir: workspace.runsDir,
-      schemas_dir: workspace.schemasDir,
-      wiki_dir: workspace.wikiDir,
-      config: readKnowledgeConfig(workspace.configPath),
-    });
+    return jsonText(createKnowledgeService({ scope }).paths());
   });
 
   registerTool(server, 'ok_parse_source_ref', 'Parse source reference', 'Parse and validate an open-files, S3, file, or web source ref', {
@@ -110,16 +93,11 @@ export function buildServer() {
     limit: z.number().optional().describe('Maximum chunks to return, default 10'),
     scope: scopeField,
   }, async ({ source_ref, purpose, limit, scope }) => {
-    const workspace = ensureKnowledgeWorkspace(resolveScopedWorkspace(scope).home);
-    const config = readKnowledgeConfig(workspace.configPath);
-    const safetyPolicy = resolveSafetyPolicy(config, workspace);
+    const service = createKnowledgeService({ scope });
     try {
-      const result = await resolveOpenFilesSource({
-        dbPath: workspace.knowledgeDbPath,
-        sourceRef: source_ref,
+      const result = await service.resolveSource(source_ref, {
         purpose,
         limit,
-        safetyPolicy,
       });
       return jsonText({ ok: true, ...result });
     } catch (error) {
@@ -127,6 +105,20 @@ export function buildServer() {
     }
   });
 
+  registerTool(server, 'ok_provider_status', 'AI provider status', 'Inspect configured AI SDK providers, model aliases, and BYOK credential availability', {
+    scope: scopeField,
+  }, async ({ scope }) => {
+    const service = createKnowledgeService({ scope });
+    return jsonText({ ok: true, ...service.providerStatus() });
+  });
+
+  registerTool(server, 'ok_provider_models', 'AI provider models', 'List AI SDK model aliases and capability metadata', {
+    scope: scopeField,
+  }, async ({ scope }) => {
+    const service = createKnowledgeService({ scope });
+    return jsonText({ ok: true, models: service.modelRegistry() });
+  });
+
   registerTool(server, 'ok_add', 'Add a knowledge item', 'Add a new item to the knowledge store', {
     title: z.string().describe('Item title'),
     content: z.string().describe('Item content/body'),

package/src/providers.ts

@@ -0,0 +1,308 @@
+import { randomUUID } from 'node:crypto';
+import type { Database } from 'bun:sqlite';
+import type { KnowledgeConfig } from './workspace';
+
+export type AiProviderId = 'openai' | 'anthropic' | 'deepseek';
+
+export interface AiProviderSettings {
+  api_key_env: string;
+  base_url?: string;
+  default_model: string;
+}
+
+export interface AiProvidersConfig {
+  default_model?: string;
+  aliases?: Record<string, string>;
+  openai?: Partial<AiProviderSettings>;
+  anthropic?: Partial<AiProviderSettings>;
+  deepseek?: Partial<AiProviderSettings>;
+}
+
+export interface ModelCapabilities {
+  text_generation: boolean;
+  structured_output: boolean;
+  tool_usage: boolean;
+  tool_streaming: boolean;
+  image_input: boolean;
+  native_web_search: boolean;
+  reasoning: boolean;
+  embeddings: boolean;
+}
+
+export interface ModelRegistryEntry {
+  alias: string;
+  model_ref: string;
+  provider: AiProviderId;
+  model: string;
+  default: boolean;
+  capabilities: ModelCapabilities;
+}
+
+export interface ProviderCredentialStatus {
+  provider: AiProviderId;
+  api_key_env: string;
+  configured: boolean;
+  source: 'env' | 'missing';
+  base_url: string | null;
+  default_model: string;
+}
+
+export interface ProviderStatusResult {
+  default_model: string;
+  providers: ProviderCredentialStatus[];
+  models: ModelRegistryEntry[];
+}
+
+export interface NormalizedProviderUsage {
+  provider: string;
+  model: string;
+  input_tokens: number;
+  output_tokens: number;
+  cost_usd: number;
+  metadata: Record<string, unknown>;
+}
+
+type ProviderFactory = (settings: { apiKey: string; baseURL?: string }) => unknown;
+
+export interface AiProviderRuntimeOptions {
+  config?: KnowledgeConfig;
+  env?: Record<string, string | undefined>;
+  factories?: Partial<Record<AiProviderId, ProviderFactory>>;
+}
+
+const DEFAULT_PROVIDER_SETTINGS: Record<AiProviderId, AiProviderSettings> = {
+  openai: {
+    api_key_env: 'OPENAI_API_KEY',
+    default_model: 'gpt-5.2',
+  },
+  anthropic: {
+    api_key_env: 'ANTHROPIC_API_KEY',
+    default_model: 'claude-sonnet-4-6',
+  },
+  deepseek: {
+    api_key_env: 'DEEPSEEK_API_KEY',
+    default_model: 'deepseek-chat',
+  },
+};
+
+const PROVIDER_CAPABILITIES: Record<AiProviderId, ModelCapabilities> = {
+  openai: {
+    text_generation: true,
+    structured_output: true,
+    tool_usage: true,
+    tool_streaming: true,
+    image_input: true,
+    native_web_search: true,
+    reasoning: true,
+    embeddings: true,
+  },
+  anthropic: {
+    text_generation: true,
+    structured_output: true,
+    tool_usage: true,
+    tool_streaming: true,
+    image_input: true,
+    native_web_search: false,
+    reasoning: true,
+    embeddings: false,
+  },
+  deepseek: {
+    text_generation: true,
+    structured_output: true,
+    tool_usage: true,
+    tool_streaming: true,
+    image_input: false,
+    native_web_search: false,
+    reasoning: true,
+    embeddings: false,
+  },
+};
+
+const BUILTIN_ALIASES: Record<string, string> = {
+  default: 'openai:gpt-5.2',
+  fast: 'openai:gpt-5-mini',
+  reasoning: 'anthropic:claude-opus-4-6',
+  sonnet: 'anthropic:claude-sonnet-4-6',
+  deepseek: 'deepseek:deepseek-chat',
+  'deepseek-reasoning': 'deepseek:deepseek-reasoner',
+};
+
+function providerConfig(config?: KnowledgeConfig): AiProvidersConfig {
+  return (config as KnowledgeConfig & { providers?: AiProvidersConfig }).providers ?? {};
+}
+
+export function providerSettings(config: KnowledgeConfig | undefined, provider: AiProviderId): AiProviderSettings {
+  const configured = providerConfig(config)[provider] ?? {};
+  return {
+    ...DEFAULT_PROVIDER_SETTINGS[provider],
+    ...configured,
+  };
+}
+
+export function modelAliases(config?: KnowledgeConfig): Record<string, string> {
+  const configured = providerConfig(config);
+  return {
+    ...BUILTIN_ALIASES,
+    ...(configured.default_model ? { default: configured.default_model } : {}),
+    ...(configured.aliases ?? {}),
+  };
+}
+
+export function parseModelRef(modelRef: string): { provider: AiProviderId; model: string } {
+  const [provider, ...rest] = modelRef.split(':');
+  const model = rest.join(':');
+  if (provider !== 'openai' && provider !== 'anthropic' && provider !== 'deepseek') {
+    throw new Error(`Unsupported AI provider: ${provider}`);
+  }
+  if (!model) throw new Error(`Invalid model ref: ${modelRef}. Expected provider:model.`);
+  return { provider, model };
+}
+
+export function resolveModelRef(aliasOrRef: string, config?: KnowledgeConfig): string {
+  const aliases = modelAliases(config);
+  return aliases[aliasOrRef] ?? aliasOrRef;
+}
+
+export function listModelRegistry(config?: KnowledgeConfig): ModelRegistryEntry[] {
+  const aliases = modelAliases(config);
+  return Object.entries(aliases).map(([alias, modelRef]) => {
+    const parsed = parseModelRef(modelRef);
+    return {
+      alias,
+      model_ref: modelRef,
+      provider: parsed.provider,
+      model: parsed.model,
+      default: alias === 'default',
+      capabilities: PROVIDER_CAPABILITIES[parsed.provider],
+    };
+  });
+}
+
+export function providerCredentialStatus(config: KnowledgeConfig | undefined, env: Record<string, string | undefined> = process.env): ProviderCredentialStatus[] {
+  return (Object.keys(DEFAULT_PROVIDER_SETTINGS) as AiProviderId[]).map((provider) => {
+    const settings = providerSettings(config, provider);
+    const configured = Boolean(env[settings.api_key_env]);
+    return {
+      provider,
+      api_key_env: settings.api_key_env,
+      configured,
+      source: configured ? 'env' : 'missing',
+      base_url: settings.base_url ?? null,
+      default_model: settings.default_model,
+    };
+  });
+}
+
+export function providerStatus(config?: KnowledgeConfig, env: Record<string, string | undefined> = process.env): ProviderStatusResult {
+  return {
+    default_model: resolveModelRef('default', config),
+    providers: providerCredentialStatus(config, env),
+    models: listModelRegistry(config),
+  };
+}
+
+export function assertProviderCredentials(provider: AiProviderId, config?: KnowledgeConfig, env: Record<string, string | undefined> = process.env): ProviderCredentialStatus {
+  const status = providerCredentialStatus(config, env).find((entry) => entry.provider === provider);
+  if (!status) throw new Error(`Unsupported AI provider: ${provider}`);
+  if (!status.configured) throw new Error(`Missing ${status.api_key_env} for ${provider}. Set the env var to use this provider.`);
+  return status;
+}
+
+async function defaultFactory(provider: AiProviderId): Promise<ProviderFactory> {
+  if (provider === 'openai') {
+    const { createOpenAI } = await import('@ai-sdk/openai');
+    return createOpenAI as ProviderFactory;
+  }
+  if (provider === 'anthropic') {
+    const { createAnthropic } = await import('@ai-sdk/anthropic');
+    return createAnthropic as ProviderFactory;
+  }
+  const { createDeepSeek } = await import('@ai-sdk/deepseek');
+  return createDeepSeek as ProviderFactory;
+}
+
+export async function createAiSdkProviderRegistry(options: AiProviderRuntimeOptions = {}) {
+  const { createProviderRegistry } = await import('ai');
+  const env = options.env ?? process.env;
+  const providers: Record<string, unknown> = {};
+  for (const provider of Object.keys(DEFAULT_PROVIDER_SETTINGS) as AiProviderId[]) {
+    const settings = providerSettings(options.config, provider);
+    const apiKey = env[settings.api_key_env];
+    if (!apiKey) continue;
+    const factory = options.factories?.[provider] ?? await defaultFactory(provider);
+    providers[provider] = factory({ apiKey, baseURL: settings.base_url });
+  }
+  return createProviderRegistry(providers as never);
+}
+
+export async function languageModelFor(aliasOrRef: string, options: AiProviderRuntimeOptions = {}) {
+  const modelRef = resolveModelRef(aliasOrRef, options.config);
+  const parsed = parseModelRef(modelRef);
+  assertProviderCredentials(parsed.provider, options.config, options.env);
+  const registry = await createAiSdkProviderRegistry(options);
+  return registry.languageModel(modelRef as `${string}:${string}`);
+}
+
+function usageNumber(usage: Record<string, unknown>, keys: string[]): number {
+  for (const key of keys) {
+    const value = usage[key];
+    if (typeof value === 'number' && Number.isFinite(value)) return value;
+  }
+  return 0;
+}
+
+export function normalizeAiSdkUsage(input: {
+  provider: string;
+  model: string;
+  usage?: Record<string, unknown> | null;
+  providerMetadata?: Record<string, unknown> | null;
+  costUsd?: number;
+}): NormalizedProviderUsage {
+  const usage = input.usage ?? {};
+  return {
+    provider: input.provider,
+    model: input.model,
+    input_tokens: usageNumber(usage, ['inputTokens', 'promptTokens', 'input_tokens', 'prompt_tokens']),
+    output_tokens: usageNumber(usage, ['outputTokens', 'completionTokens', 'output_tokens', 'completion_tokens']),
+    cost_usd: input.costUsd ?? 0,
+    metadata: {
+      usage,
+      provider_metadata: input.providerMetadata ?? {},
+    },
+  };
+}
+
+export function recordProviderUsage(db: Database, input: NormalizedProviderUsage & { run_id?: string | null; created_at?: string }): string {
+  const id = `usage_${randomUUID()}`;
+  db.run(
+    `INSERT INTO provider_usage (id, run_id, provider, model, input_tokens, output_tokens, cost_usd, metadata_json, created_at)
+     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+    [
+      id,
+      input.run_id ?? null,
+      input.provider,
+      input.model,
+      input.input_tokens,
+      input.output_tokens,
+      input.cost_usd,
+      JSON.stringify(input.metadata),
+      input.created_at ?? new Date().toISOString(),
+    ],
+  );
+  return id;
+}
+
+export function createDeterministicFakeProvider(provider: AiProviderId): ProviderFactory {
+  return () => ({
+    languageModel: (modelId: string) => ({
+      provider,
+      modelId,
+      specificationVersion: 'v3',
+    }),
+    chat: (modelId: string) => ({
+      provider,
+      modelId,
+      specificationVersion: 'v3',
+    }),
+  });
+}