@hasna/knowledge 0.2.10 → 0.2.11

package/src/cli.ts

@@ -7,6 +7,7 @@
 import { defaultStorePath, loadStore, saveStore, withLock, makeId, makeShortId, ensureStore, type KnowledgeItem } from './store';
 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' };
 
@@ -59,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',
@@ -167,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
 
@@ -233,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();
 }
@@ -278,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'.");
     }
@@ -504,6 +507,30 @@ async function run(argv: string[]): Promise<void> {
     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

@@ -105,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',
+    }),
+  });
+}

package/src/service.ts

@@ -4,6 +4,7 @@ import { getKnowledgeDbStats, migrateKnowledgeDb } from './knowledge-db';
 import { ingestOpenFilesManifest } from './manifest-ingest';
 import { ingestSourceRef } from './source-ingest';
 import { resolveOpenFilesSource } from './source-resolver';
+import { providerStatus, listModelRegistry, type ProviderStatusResult, type ModelRegistryEntry } from './providers';
 import { resolveSafetyPolicy } from './safety';
 import { initializeWikiLayout } from './wiki-layout';
 import {
@@ -150,6 +151,14 @@ export class KnowledgeService {
       safetyPolicy: this.safetyPolicy(),
     });
   }
+
+  providerStatus(env: Record<string, string | undefined> = process.env): ProviderStatusResult {
+    return providerStatus(this.config(), env);
+  }
+
+  modelRegistry(): ModelRegistryEntry[] {
+    return listModelRegistry(this.config());
+  }
 }
 
 export function createKnowledgeService(options: KnowledgeServiceOptions = {}): KnowledgeService {

package/src/workspace.ts

@@ -39,6 +39,25 @@ export interface KnowledgeConfig {
     preferred_ref: 'open-files';
     allowed_schemes: string[];
   };
+  providers?: {
+    default_model?: string;
+    aliases?: Record<string, string>;
+    openai?: {
+      api_key_env?: string;
+      base_url?: string;
+      default_model?: string;
+    };
+    anthropic?: {
+      api_key_env?: string;
+      base_url?: string;
+      default_model?: string;
+    };
+    deepseek?: {
+      api_key_env?: string;
+      base_url?: string;
+      default_model?: string;
+    };
+  };
   safety?: {
     network?: {
       web_search_enabled?: boolean;
@@ -95,6 +114,28 @@ export function defaultKnowledgeConfig(): KnowledgeConfig {
       preferred_ref: 'open-files',
       allowed_schemes: ['open-files', 's3', 'file', 'https', 'http'],
     },
+    providers: {
+      default_model: 'openai:gpt-5.2',
+      aliases: {
+        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',
+      },
+      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',
+      },
+    },
     safety: {
       network: {
         web_search_enabled: false,