@inkdropapp/ai 0.1.0

package/src/providers/openai-compatible.ts

@@ -0,0 +1,205 @@
+import {
+  createOpenAICompatible,
+  type OpenAICompatibleProvider as SdkOpenAICompatibleProvider
+} from '@ai-sdk/openai-compatible'
+import type {
+  CacheConfiguration,
+  ModelCapabilities
+} from '@inkdropapp/ai-catalog'
+import { streamText } from 'ai'
+import { NoApiKey } from '../errors.js'
+import type { KeyStore } from '../key-store.js'
+import { mapAiSdkError } from '../internal/map-ai-sdk-error.js'
+import { mapAiSdkStream } from '../internal/map-ai-sdk-stream.js'
+import type { AIModel, AIProvider, CompletionRequest } from '../provider.js'
+import type {
+  OpenAICompatibleModelConfig,
+  OpenAICompatibleProviderConfig
+} from '../settings.js'
+import type { StreamEvent } from '../stream-events.js'
+
+const DEFAULT_CAPABILITIES: ModelCapabilities = {
+  supportsTools: true,
+  supportsImages: false,
+  supportsThinking: false,
+  supportsStreamingTools: false,
+  maxTokens: 32_000
+}
+
+/**
+ * Derives the env-var name for a user-named provider entry.
+ *
+ * Rules: replace any non-alphanumeric character with `_`, collapse runs of `_`,
+ * uppercase, append `_API_KEY`.
+ *
+ * Examples:
+ *   `openrouter`     → `OPENROUTER_API_KEY`
+ *   `together_ai`    → `TOGETHER_AI_API_KEY`
+ *   `ollama-local`   → `OLLAMA_LOCAL_API_KEY`
+ *   `my.proxy`       → `MY_PROXY_API_KEY`
+ */
+export const deriveEnvVarName = (id: string): string => {
+  const sanitized = id
+    .replace(/[^a-zA-Z0-9]+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toUpperCase()
+  return `${sanitized}_API_KEY`
+}
+
+const mergeCapabilities = (
+  override: Partial<ModelCapabilities> | undefined
+): ModelCapabilities => ({
+  ...DEFAULT_CAPABILITIES,
+  ...override
+})
+
+/**
+ * Provider for any OpenAI-compatible chat-completions endpoint
+ * (OpenRouter, Together, Fireworks, Groq, vLLM, Ollama via `/v1`, LiteLLM, …).
+ *
+ * Each user-named entry in `AISettings.providers.openaiCompatible[]`
+ * becomes one instance. The env-var name is derived from the entry's `id`
+ * via {@link deriveEnvVarName}; the keyring account is the resolved `baseURL`.
+ *
+ * Capability flags are user-declared per model (with sensible defaults of
+ * `tools: true`, `images: false`, `thinking: false`); the host UI keys off
+ * those flags exactly the same as for Anthropic.
+ *
+ * Some endpoints (Ollama, vLLM, …) require no API key. The provider
+ * accommodates this by passing `apiKey: undefined` to the SDK rather than
+ * proactively throwing `NoApiKey` — auth failures only surface if the
+ * upstream actually returns 401.
+ */
+export class OpenAICompatibleProvider implements AIProvider {
+  readonly id: string
+  readonly name: string
+  readonly baseURL: string
+  readonly envVarName: string
+
+  private readonly config: OpenAICompatibleProviderConfig
+  private readonly keyStore: KeyStore
+  private readonly modelsById: Map<string, OpenAICompatibleAIModel>
+
+  private sdkClient: SdkOpenAICompatibleProvider | undefined
+  private sdkClientApiKey: string | undefined
+
+  constructor(keyStore: KeyStore, config: OpenAICompatibleProviderConfig) {
+    this.config = config
+    this.keyStore = keyStore
+    this.id = config.id
+    this.name = config.displayName ?? config.id
+    this.baseURL = config.baseURL
+    this.envVarName = deriveEnvVarName(config.id)
+    this.modelsById = new Map(
+      config.models.map(m => [m.id, new OpenAICompatibleAIModel(this, m)])
+    )
+  }
+
+  listModels(): AIModel[] {
+    return Array.from(this.modelsById.values())
+  }
+
+  getModel(id: string): AIModel | undefined {
+    return this.modelsById.get(id)
+  }
+
+  defaultModel(): AIModel | undefined {
+    if (this.config.defaultModelId) {
+      const explicit = this.modelsById.get(this.config.defaultModelId)
+      if (explicit) return explicit
+    }
+    const first = this.config.models[0]
+    return first ? this.modelsById.get(first.id) : undefined
+  }
+
+  defaultFastModel(): AIModel | undefined {
+    if (this.config.defaultFastModelId) {
+      const explicit = this.modelsById.get(this.config.defaultFastModelId)
+      if (explicit) return explicit
+    }
+    return this.defaultModel()
+  }
+
+  async isAuthenticated(): Promise<boolean> {
+    const key = await this.keyStore.getKey(this.envVarName, this.baseURL)
+    return key !== null && key.length > 0
+  }
+
+  async setApiKey(key: string): Promise<void> {
+    await this.keyStore.setKey(this.baseURL, key)
+    this.sdkClient = undefined
+    this.sdkClientApiKey = undefined
+  }
+
+  async clearApiKey(): Promise<void> {
+    await this.keyStore.deleteKey(this.baseURL)
+    this.sdkClient = undefined
+    this.sdkClientApiKey = undefined
+  }
+
+  /** Internal — used by OpenAICompatibleAIModel to resolve the SDK client lazily. */
+  async getSdkClient(): Promise<SdkOpenAICompatibleProvider> {
+    const apiKey = await this.keyStore.getKey(this.envVarName, this.baseURL)
+    // OpenAI-compatible endpoints (Ollama, vLLM…) often need no API key.
+    // We pass `apiKey: undefined` and let the upstream return 401 if it does.
+    if (this.sdkClient && this.sdkClientApiKey === (apiKey ?? ''))
+      return this.sdkClient
+    this.sdkClient = createOpenAICompatible({
+      name: this.id,
+      baseURL: this.baseURL,
+      apiKey: apiKey ?? undefined
+    })
+    this.sdkClientApiKey = apiKey ?? ''
+    return this.sdkClient
+  }
+
+  /** Internal — exposed for tests / 401 handling: did the user configure an explicit auth value? */
+  async hasConfiguredKey(): Promise<boolean> {
+    const key = await this.keyStore.getKey(this.envVarName, this.baseURL)
+    return key !== null && key.length > 0
+  }
+
+  /** Internal — used by the model when upstream returns 401: surface a NoApiKey if the user never configured one. */
+  async ensureAuthenticatedOrThrow(): Promise<void> {
+    if (!(await this.hasConfiguredKey()))
+      throw new NoApiKey(this.id, this.envVarName)
+  }
+}
+
+class OpenAICompatibleAIModel implements AIModel {
+  readonly id: string
+  readonly displayName: string
+  readonly capabilities: ModelCapabilities
+  readonly cacheConfiguration: CacheConfiguration | undefined
+
+  constructor(
+    readonly provider: OpenAICompatibleProvider,
+    config: OpenAICompatibleModelConfig
+  ) {
+    this.id = config.id
+    this.displayName = config.displayName ?? config.id
+    this.capabilities = mergeCapabilities(config.capabilities)
+    this.cacheConfiguration = undefined
+  }
+
+  async *streamCompletion(
+    request: CompletionRequest
+  ): AsyncIterable<StreamEvent> {
+    let result
+    try {
+      const sdk = await this.provider.getSdkClient()
+      result = streamText({
+        model: sdk(this.id),
+        messages: request.messages,
+        temperature: request.temperature,
+        maxOutputTokens: request.maxOutputTokens,
+        abortSignal: request.abortSignal
+      })
+    } catch (error) {
+      yield { kind: 'error', error: mapAiSdkError(error, this.provider.id) }
+      return
+    }
+
+    yield* mapAiSdkStream(result, this.provider.id)
+  }
+}

package/src/registry.ts

@@ -0,0 +1,190 @@
+import type { AIModelCatalog } from '@inkdropapp/ai-catalog'
+import { NoApiKey } from './errors.js'
+import { KeyStore } from './key-store.js'
+import type { AIModel, AIProvider, CompletionRequest } from './provider.js'
+import { AnthropicProvider } from './providers/anthropic.js'
+import { OpenAICompatibleProvider } from './providers/openai-compatible.js'
+import type { AISettings, SlotConfig, SlotName } from './settings.js'
+import type { StreamEvent } from './stream-events.js'
+
+/** Result of resolving a slot to a concrete `(provider, model)` pair. */
+export type ResolvedSlot = {
+  provider: AIProvider
+  model: AIModel
+}
+
+export type RegistryOptions = {
+  settings: AISettings
+  /**
+   * Optional server-distributed catalogue of supported models per provider.
+   * When omitted, each provider uses its compiled-in defaults (e.g. `ANTHROPIC_MODELS`).
+   * The host typically fetches this from an API and either passes it at
+   * construction time or swaps it in later via {@link Registry.updateCatalog}.
+   */
+  catalog?: AIModelCatalog
+  /** Pass an existing `KeyStore` to share its in-memory cache across registries. */
+  keyStore?: KeyStore
+}
+
+/**
+ * Top-level entrypoint to the library.
+ *
+ * Owns one instance of every configured provider, resolves task slots with
+ * fallback, and is the only place feature code calls to start a completion.
+ *
+ * The `Registry` is stateless beyond its provider list — it doesn't observe
+ * settings on its own. Call {@link Registry.updateSettings} when settings
+ * change to rebuild providers.
+ *
+ * @example
+ * ```ts
+ * const registry = new Registry({ settings })
+ * const events = await registry.streamCompletion('default', { messages })
+ * for await (const event of events) {
+ *   if (event.kind === 'text-delta') process.stdout.write(event.delta)
+ * }
+ * ```
+ */
+export class Registry {
+  readonly keyStore: KeyStore
+  private providers: Map<string, AIProvider> = new Map()
+  private settings: AISettings
+  private catalog: AIModelCatalog | undefined
+
+  constructor(options: RegistryOptions) {
+    this.keyStore = options.keyStore ?? new KeyStore()
+    this.settings = options.settings
+    this.catalog = options.catalog
+    this.rebuildProviders()
+  }
+
+  /** All configured providers, sorted alphabetically by id. */
+  listProviders(): AIProvider[] {
+    return Array.from(this.providers.values())
+  }
+
+  getProvider(id: string): AIProvider | undefined {
+    return this.providers.get(id)
+  }
+
+  /** Flat list of every model across every provider. Useful for picker UIs. */
+  listAllModels(): { provider: AIProvider; model: AIModel }[] {
+    const out: { provider: AIProvider; model: AIModel }[] = []
+    for (const provider of this.providers.values()) {
+      for (const model of provider.listModels()) {
+        out.push({ provider, model })
+      }
+    }
+    return out
+  }
+
+  /**
+   * Resolves a slot to a concrete `(provider, model)` pair.
+   *
+   * Order:
+   *   1. Explicit binding `settings.slots[slot]`, if both provider and model resolve.
+   *   2. For `'fast'` only: fall back to `settings.slots.default`.
+   *   3. First authenticated provider in alphabetical id order, taking that
+   *      provider's `defaultModel()` (or `defaultFastModel()` for the fast slot).
+   *      Mirrors Zed's `available_fallback_model` without the Zed-Cloud preference.
+   *   4. `undefined` if no provider can satisfy the slot.
+   *
+   * Async because the third step calls `provider.isAuthenticated()`, which may
+   * touch the keyring.
+   */
+  async resolveSlot(slot: SlotName): Promise<ResolvedSlot | undefined> {
+    const direct = this.tryBinding(this.settings.slots?.[slot])
+    if (direct) return direct
+
+    if (slot === 'fast') {
+      const fallback = this.tryBinding(this.settings.slots?.default)
+      if (fallback) return fallback
+    }
+
+    for (const provider of this.providers.values()) {
+      if (!(await provider.isAuthenticated())) continue
+      const model =
+        slot === 'fast' ? provider.defaultFastModel() : provider.defaultModel()
+      if (model) return { provider, model }
+    }
+
+    return undefined
+  }
+
+  private tryBinding(
+    binding: SlotConfig | undefined
+  ): ResolvedSlot | undefined {
+    if (!binding) return undefined
+    const provider = this.providers.get(binding.providerId)
+    const model = provider?.getModel(binding.modelId)
+    if (provider && model) return { provider, model }
+    return undefined
+  }
+
+  /**
+   * Streams a completion for a task slot.
+   *
+   * Resolves the slot via {@link Registry.resolveSlot}; throws {@link NoApiKey}
+   * if no provider can satisfy it (no slot binding, and no authenticated
+   * provider available for the implicit fallback). Otherwise returns the
+   * model's stream — note that *upstream* errors (auth, rate limit, etc.)
+   * arrive as `'error'` events inside the iterable, not as thrown exceptions.
+   */
+  async streamCompletion(
+    slot: SlotName,
+    request: CompletionRequest
+  ): Promise<AsyncIterable<StreamEvent>> {
+    const resolved = await this.resolveSlot(slot)
+    if (!resolved) {
+      throw new NoApiKey('<registry>', null)
+    }
+    return resolved.model.streamCompletion(request)
+  }
+
+  /**
+   * Replaces the active settings and rebuilds the provider list.
+   * The shared `KeyStore` cache is preserved.
+   */
+  updateSettings(next: AISettings): void {
+    this.settings = next
+    this.rebuildProviders()
+  }
+
+  /**
+   * Replaces the active model catalogue and rebuilds providers.
+   *
+   * Pass `undefined` to revert to providers' compiled-in defaults. Typical
+   * usage: app starts with no catalogue, fetches one from the server, then
+   * calls `updateCatalog(catalog)` once the response lands.
+   *
+   * The shared `KeyStore` cache and authentication state are preserved.
+   */
+  updateCatalog(next: AIModelCatalog | undefined): void {
+    this.catalog = next
+    this.rebuildProviders()
+  }
+
+  private rebuildProviders(): void {
+    const built: AIProvider[] = []
+
+    if (this.settings.providers.anthropic) {
+      built.push(
+        new AnthropicProvider(
+          this.keyStore,
+          this.settings.providers.anthropic,
+          this.catalog?.anthropic
+        )
+      )
+    }
+
+    for (const config of this.settings.providers.openaiCompatible ?? []) {
+      built.push(new OpenAICompatibleProvider(this.keyStore, config))
+    }
+
+    // Sort once at build time so `Map` iteration (insertion order) is
+    // alphabetical by id — the iteration order Zed uses for fallback resolution.
+    built.sort((a, b) => a.id.localeCompare(b.id))
+
+    this.providers = new Map(built.map(p => [p.id, p]))
+  }
+}

package/src/settings.ts

@@ -0,0 +1,105 @@
+import type {
+  CacheConfiguration,
+  ModelCapabilities
+} from '@inkdropapp/ai-catalog'
+
+/**
+ * Task-routing slot names.
+ *
+ * - `default` — long-form generation; the user's "main" model.
+ * - `fast` — latency-sensitive features (NES, quick rewrite, title suggest).
+ */
+export type SlotName = 'default' | 'fast'
+
+/** Explicit binding of a slot to a `(provider, model)` pair. */
+export type SlotConfig = {
+  providerId: string
+  modelId: string
+}
+
+/**
+ * Fields every provider config carries. Per-provider configs extend this
+ * to add provider-specific knobs (and may narrow `baseURL` to required when
+ * there's no sensible default).
+ */
+export type CommonProviderConfig = {
+  /** Endpoint root. Falls back to a provider-specific default when omitted. */
+  baseURL?: string
+}
+
+/**
+ * One entry under an OpenAI-compatible provider's `models[]`. Capability flags
+ * are user-declared (a partial — sensible defaults are applied for fields the
+ * user omits).
+ */
+export type OpenAICompatibleModelConfig = {
+  id: string
+  displayName?: string
+  capabilities?: Partial<ModelCapabilities>
+}
+
+/**
+ * One user-named OpenAI-compatible provider entry (e.g. `openrouter`,
+ * `together_ai`, `ollama_local`). Each becomes a separate `AIProvider`
+ * instance at runtime with its own keyring entry.
+ *
+ * `baseURL` is required here — there's no sensible default when the user is
+ * pointing at an arbitrary endpoint.
+ */
+export type OpenAICompatibleProviderConfig = CommonProviderConfig & {
+  id: string
+  displayName?: string
+  /** Endpoint root, e.g. `https://openrouter.ai/api/v1`. */
+  baseURL: string
+  models: OpenAICompatibleModelConfig[]
+  /** Defaults to `models[0]` when omitted. */
+  defaultModelId?: string
+  /** Defaults to `defaultModel()` when omitted. */
+  defaultFastModelId?: string
+}
+
+/**
+ * One user-declared Anthropic model on top of the built-in Claude catalogue.
+ * Useful when Anthropic ships a new model id before this library does.
+ *
+ * If `id` matches a built-in model, this entry overrides it. Otherwise it's
+ * added to the catalogue.
+ */
+export type AnthropicModelConfig = {
+  id: string
+  displayName?: string
+  capabilities?: Partial<ModelCapabilities>
+  cacheConfiguration?: CacheConfiguration
+}
+
+/**
+ * Anthropic provider config.
+ *
+ * - `baseURL` is only needed for proxy / staging endpoints.
+ * - `models` adds (or overrides) Claude entries on top of the built-in
+ *   {@link ANTHROPIC_MODELS} catalogue.
+ *
+ * Default-model selection is *not* configured here — use `slots` at the top
+ * of `AISettings` to bind features to specific models.
+ */
+export type AnthropicProviderConfig = CommonProviderConfig & {
+  models?: AnthropicModelConfig[]
+}
+
+/**
+ * Top-level AI configuration. The host (Inkdrop main process) constructs this
+ * from whichever persistence layer it uses and passes it to `Registry`.
+ *
+ * The library never reads or writes settings to disk itself.
+ */
+export type AISettings = {
+  providers: {
+    anthropic?: AnthropicProviderConfig
+    openaiCompatible?: OpenAICompatibleProviderConfig[]
+  }
+  /**
+   * Per-slot model overrides. Unset slots fall back to the first registered
+   * provider's `defaultModel` / `defaultFastModel`.
+   */
+  slots?: Partial<Record<SlotName, SlotConfig>>
+}

package/src/stream-events.ts

@@ -0,0 +1,53 @@
+import type { AIError } from './errors.js'
+
+/**
+ * Why a completion stream stopped producing output.
+ *
+ * Mirrors the AI SDK's `FinishReason`. Unknown / provider-specific values are
+ * normalised to `'other'` rather than silently passed through.
+ */
+export type FinishReason =
+  | 'stop'
+  | 'length'
+  | 'content-filter'
+  | 'tool-calls'
+  | 'error'
+  | 'other'
+
+/**
+ * Token usage for a single completion. Every field is optional because
+ * not every provider reports every counter.
+ */
+export type Usage = {
+  /** Tokens consumed from the prompt. */
+  inputTokens?: number
+  /** Tokens generated in the response. */
+  outputTokens?: number
+  /** `inputTokens + outputTokens` as reported by the provider. */
+  totalTokens?: number
+  /** Of `inputTokens`, how many were a cache hit (Anthropic prompt-cache reads). */
+  cacheReadInputTokens?: number
+  /** Of `inputTokens`, how many were written to the prompt cache for future reads. */
+  cacheCreationInputTokens?: number
+  /** Subset of `outputTokens` spent on reasoning / thinking content. */
+  reasoningTokens?: number
+}
+
+/**
+ * Provider-agnostic streaming events. Every concrete provider's stream is
+ * reduced to this discriminated union so consumers never branch on provider id.
+ *
+ * Errors arrive as `{ kind: 'error', ... }` events, not as thrown exceptions —
+ * this lets the host pump events across an Electron IPC boundary one at a time
+ * without needing try/catch around the iterator.
+ *
+ * `tool-call` and `tool-result` are typed but never produced in the current
+ * version (one-shot text completions only). They're reserved for forward compat.
+ */
+export type StreamEvent =
+  | { kind: 'text-delta'; delta: string }
+  | { kind: 'tool-call'; id: string; name: string; input: unknown }
+  | { kind: 'tool-result'; id: string; name: string; result: unknown }
+  | { kind: 'usage-update'; usage: Usage }
+  | { kind: 'finish'; finishReason: FinishReason; usage: Usage }
+  | { kind: 'error'; error: AIError }

package/src/url.ts

@@ -0,0 +1,41 @@
+/**
+ * Conservative baseURL normalisation for keying credential entries.
+ *
+ * Rules:
+ * - lowercase scheme + host
+ * - drop default port (`:443` for https, `:80` for http) for the matching scheme
+ * - strip a single trailing `/` from the path
+ *
+ * Path case, query, and fragment are preserved verbatim. Under-normalising
+ * splits keyring entries that should share a key; over-normalising merges
+ * entries that should be separate. The rules above are intentionally minimal.
+ *
+ * @throws if `input` is not a parseable absolute URL.
+ */
+export const normalizeBaseURL = (input: string): string => {
+  let url: URL
+  try {
+    url = new URL(input)
+  } catch {
+    throw new Error(`Invalid baseURL: ${input}`)
+  }
+
+  url.protocol = url.protocol.toLowerCase()
+  url.hostname = url.hostname.toLowerCase()
+
+  if (
+    (url.protocol === 'https:' && url.port === '443') ||
+    (url.protocol === 'http:' && url.port === '80')
+  ) {
+    url.port = ''
+  }
+
+  let result = url.toString()
+  if (
+    result.endsWith('/') &&
+    (url.pathname === '/' || url.pathname.length > 1)
+  ) {
+    result = result.slice(0, -1)
+  }
+  return result
+}

package/types/capabilities.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Per-model capability flags. The host UI keys off these to enable / disable
+ * features (image attachments, tool calls, extended thinking, etc.) without
+ * having to know which provider the model belongs to.
+ */
+export type ModelCapabilities = {
+    /** Model supports function-calling / tool-use. */
+    supportsTools: boolean;
+    /** Model accepts image content parts in user messages. */
+    supportsImages: boolean;
+    /** Model can produce explicit reasoning / thinking output. */
+    supportsThinking: boolean;
+    /** Tool-call arguments stream incrementally rather than arriving in one chunk. */
+    supportsStreamingTools: boolean;
+    /** Maximum total tokens (input + output) the model can handle in a single request. */
+    maxTokens: number;
+    /**
+     * Maximum tokens the model can produce in a single response.
+     * Falls back to `maxTokens` semantics when omitted.
+     */
+    maxOutputTokens?: number;
+};
+/**
+ * Prompt-cache thresholds, currently only meaningful for Anthropic models.
+ * Drives whether and where to insert cache breakpoints in the request.
+ */
+export type CacheConfiguration = {
+    /** Don't cache anything unless the request totals at least this many tokens. */
+    minTotalTokens: number;
+    /** Minimum tokens that must be cacheable in a span before a breakpoint is worthwhile. */
+    minCachedTokens: number;
+    /**
+     * Whether to opportunistically cache the *most recent* user turn even if a future
+     * cache hit isn't certain — trades a small write cost for a likely future read.
+     */
+    shouldSpeculate: boolean;
+};

package/types/catalog.d.ts

@@ -0,0 +1,32 @@
+import type { AnthropicModelDescriptor } from './providers/anthropic-models.js';
+/**
+ * Per-provider catalogue entry.
+ *
+ * `models` replaces the built-in compiled-in list (e.g. `ANTHROPIC_MODELS`)
+ * for that provider. `defaultModelId` / `defaultFastModelId` override the
+ * provider's hard-coded defaults.
+ *
+ * User-declared `config.models` (under `AISettings.providers.<name>.models`)
+ * still override entries here — the user's local config always wins over a
+ * catalogue, regardless of where the catalogue came from.
+ */
+export type AnthropicCatalog = {
+    models: readonly AnthropicModelDescriptor[];
+    defaultModelId?: string;
+    defaultFastModelId?: string;
+};
+/**
+ * Catalogue of built-in models for each provider, designed to be distributed
+ * by a server endpoint and swapped in at runtime.
+ *
+ * The motivation is to decouple model releases from app releases — when
+ * Anthropic ships a new Claude version, the host can publish an updated
+ * catalogue without forcing every Inkdrop user to update.
+ *
+ * Without a catalogue, each provider falls back to its compiled-in defaults.
+ * Each provider entry is independent and optional; the host can ship
+ * `{ anthropic: ... }` and leave other providers on their built-in catalogues.
+ */
+export type AIModelCatalog = {
+    anthropic?: AnthropicCatalog;
+};