@inkdropapp/ai 0.1.0

package/src/internal/map-ai-sdk-error.ts

@@ -0,0 +1,96 @@
+import { APICallError, AISDKError, LoadAPIKeyError } from '@ai-sdk/provider'
+import {
+  AIError,
+  AuthenticationError,
+  NoApiKey,
+  PromptTooLarge,
+  RateLimitExceeded,
+  ServerOverloaded,
+  UpstreamError
+} from '../errors.js'
+
+const parseRetryAfter = (header: string | undefined): number | undefined => {
+  if (!header) return undefined
+  const seconds = Number(header)
+  if (Number.isFinite(seconds) && seconds >= 0) return seconds
+  const epochMs = Date.parse(header)
+  if (!Number.isNaN(epochMs)) {
+    const delta = Math.max(0, Math.round((epochMs - Date.now()) / 1000))
+    return delta
+  }
+  return undefined
+}
+
+const looksLikeContextLength = (message: string | undefined): boolean => {
+  if (!message) return false
+  return /context length|too long|too many tokens|maximum.*tokens/i.test(
+    message
+  )
+}
+
+/**
+ * Reduces an arbitrary unknown error coming out of the AI SDK to one of our
+ * {@link AIError} variants.
+ *
+ * Mapping rules:
+ * - Existing `AIError` → returned unchanged.
+ * - `LoadAPIKeyError` → `NoApiKey`.
+ * - `APICallError` with status:
+ *   - 401 / 403 → `AuthenticationError`
+ *   - 429 → `RateLimitExceeded` (with `retryAfter` parsed from header)
+ *   - 503 / 529 → `ServerOverloaded` (with `retryAfter`)
+ *   - 413, or any message that "looks like" a context-length overflow → `PromptTooLarge`
+ *   - anything else → `UpstreamError` carrying status + cause
+ * - Other `AISDKError` / `Error` instances → `UpstreamError` (or `PromptTooLarge`
+ *   if the message matches).
+ *
+ * @param providerId - Used to attribute the error in messages and downstream
+ * routing decisions.
+ */
+export const mapAiSdkError = (error: unknown, providerId: string): AIError => {
+  if (error instanceof AIError) return error
+
+  if (LoadAPIKeyError.isInstance(error)) {
+    return new NoApiKey(providerId, null)
+  }
+
+  if (APICallError.isInstance(error)) {
+    const status = error.statusCode
+    const headers = error.responseHeaders
+    const retryAfter = parseRetryAfter(headers?.['retry-after'])
+    const message = error.message
+
+    if (status === 401 || status === 403) {
+      return new AuthenticationError(providerId, message)
+    }
+    if (status === 429) {
+      return new RateLimitExceeded(providerId, retryAfter, message)
+    }
+    if (status === 503 || status === 529) {
+      return new ServerOverloaded(providerId, retryAfter, message)
+    }
+    if (status === 413 || looksLikeContextLength(message)) {
+      return new PromptTooLarge(providerId, undefined, undefined, message)
+    }
+    return new UpstreamError(providerId, message, status, { cause: error })
+  }
+
+  if (AISDKError.isInstance(error)) {
+    return new UpstreamError(providerId, error.message, undefined, {
+      cause: error
+    })
+  }
+
+  if (error instanceof Error) {
+    if (looksLikeContextLength(error.message)) {
+      return new PromptTooLarge(providerId, undefined, undefined, error.message)
+    }
+    return new UpstreamError(providerId, error.message, undefined, {
+      cause: error
+    })
+  }
+
+  return new UpstreamError(providerId, 'Unknown upstream error', undefined, {
+    cause: error
+  })
+}

package/src/internal/map-ai-sdk-stream.ts

@@ -0,0 +1,111 @@
+import type {
+  LanguageModelUsage,
+  StreamTextResult,
+  TextStreamPart,
+  ToolSet
+} from 'ai'
+import type { FinishReason, StreamEvent, Usage } from '../stream-events.js'
+import { mapAiSdkError } from './map-ai-sdk-error.js'
+
+const mapUsage = (usage: LanguageModelUsage | undefined): Usage => {
+  if (!usage) return {}
+  return {
+    inputTokens: usage.inputTokens,
+    outputTokens: usage.outputTokens,
+    totalTokens: usage.totalTokens,
+    cacheReadInputTokens: usage.inputTokenDetails?.cacheReadTokens,
+    cacheCreationInputTokens: usage.inputTokenDetails?.cacheWriteTokens,
+    reasoningTokens: usage.outputTokenDetails?.reasoningTokens
+  }
+}
+
+const SDK_FINISH_REASONS: ReadonlySet<FinishReason> = new Set([
+  'stop',
+  'length',
+  'content-filter',
+  'tool-calls',
+  'error',
+  'other'
+])
+
+const mapFinishReason = (raw: string | undefined): FinishReason => {
+  if (raw && (SDK_FINISH_REASONS as ReadonlySet<string>).has(raw)) {
+    return raw as FinishReason
+  }
+  return 'other'
+}
+
+/**
+ * Adapts the AI SDK's `streamText().fullStream` into the library's
+ * provider-agnostic {@link StreamEvent} stream.
+ *
+ * Three contracts that downstream code relies on:
+ *
+ * 1. **No throwing.** Errors thrown by the iterator (e.g. mid-stream HTTP
+ *    failure) are caught and re-emitted as `{ kind: 'error', error }`.
+ *    The iterator always terminates cleanly, so consumers that pump events
+ *    over IPC don't need to wrap iteration in try/catch.
+ * 2. **Errors are terminal.** When an `error` event from the SDK is observed
+ *    the iterator returns immediately — any subsequent SDK chunks are dropped.
+ * 3. **Unknown SDK part types are silently ignored.** Forward-compat with
+ *    new AI SDK chunk variants without a library bump.
+ *
+ * Emits in this order over the lifetime of one completion:
+ * `text-delta*` → `usage-update?` → `finish | error`.
+ *
+ * @param result - The object returned by `streamText()`.
+ *                 Only its `fullStream` is consumed.
+ * @param providerId - Provider id used to attribute any wrapped errors.
+ */
+export async function* mapAiSdkStream(
+  result: Pick<StreamTextResult<ToolSet, never, never>, 'fullStream'>,
+  providerId: string
+): AsyncIterable<StreamEvent> {
+  try {
+    for await (const part of result.fullStream as AsyncIterable<
+      TextStreamPart<ToolSet>
+    >) {
+      switch (part.type) {
+        case 'text-delta':
+          if (part.text.length > 0)
+            yield { kind: 'text-delta', delta: part.text }
+          break
+        case 'tool-call':
+          yield {
+            kind: 'tool-call',
+            id: part.toolCallId,
+            name: part.toolName,
+            input: part.input
+          }
+          break
+        case 'tool-result': {
+          const output = (part as unknown as { output?: unknown }).output
+          yield {
+            kind: 'tool-result',
+            id: part.toolCallId,
+            name: part.toolName,
+            result: output
+          }
+          break
+        }
+        case 'finish-step':
+          yield { kind: 'usage-update', usage: mapUsage(part.usage) }
+          break
+        case 'finish':
+          yield {
+            kind: 'finish',
+            finishReason: mapFinishReason(part.finishReason),
+            usage: mapUsage(part.totalUsage)
+          }
+          break
+        case 'error':
+          yield { kind: 'error', error: mapAiSdkError(part.error, providerId) }
+          return
+        default:
+          break
+      }
+    }
+  } catch (error) {
+    yield { kind: 'error', error: mapAiSdkError(error, providerId) }
+  }
+}

package/src/key-store.ts

@@ -0,0 +1,116 @@
+import { AsyncEntry } from '@napi-rs/keyring'
+import { UpstreamError } from './errors.js'
+import { normalizeBaseURL } from './url.js'
+
+const DEFAULT_SERVICE = 'inkdrop.ai'
+
+export type KeyStoreOptions = {
+  /** Keyring service name. Defaults to `inkdrop.ai`. Override in tests. */
+  service?: string
+}
+
+/**
+ * URL-keyed credential storage. The keyring entry's account is the *normalised*
+ * baseURL, not the provider id — so two endpoints to the same provider (e.g.
+ * staging + prod, or two Ollama hosts) get separate entries.
+ *
+ * Resolution order in {@link KeyStore.getKey}:
+ *   1. The provider's environment variable (if a name is given and the var is non-empty).
+ *   2. The system keyring (`@napi-rs/keyring`) under `service` + normalised `baseURL`.
+ *
+ * The cache is keyed on normalised `baseURL` to avoid repeated keyring round-trips.
+ * Cache reads do not check the env var — env-var changes mid-process are not
+ * reflected unless {@link KeyStore.invalidate} is called.
+ */
+export class KeyStore {
+  readonly service: string
+  private readonly cache = new Map<string, string>()
+
+  constructor(options: KeyStoreOptions = {}) {
+    this.service = options.service ?? DEFAULT_SERVICE
+  }
+
+  /**
+   * Resolves the API key for a given `baseURL`.
+   *
+   * @param envVarName - Provider's env-var name, or `null` to skip env lookup.
+   * @param baseURL - The endpoint URL. Normalised before keying.
+   * @returns The key, or `null` if neither env nor keyring has one.
+   */
+  async getKey(
+    envVarName: string | null,
+    baseURL: string
+  ): Promise<string | null> {
+    const account = normalizeBaseURL(baseURL)
+
+    if (envVarName) {
+      const fromEnv = process.env[envVarName]
+      if (fromEnv && fromEnv.length > 0) return fromEnv
+    }
+
+    const cached = this.cache.get(account)
+    if (cached !== undefined) return cached
+
+    try {
+      const entry = new AsyncEntry(this.service, account)
+      const value = await entry.getPassword()
+      if (value === undefined || value === null) return null
+      this.cache.set(account, value)
+      return value
+    } catch (cause) {
+      throw new UpstreamError(
+        '<keystore>',
+        `Failed to read credential for ${account} from system keyring`,
+        undefined,
+        { cause }
+      )
+    }
+  }
+
+  /** Stores `key` for `baseURL` in the system keyring and the in-memory cache. */
+  async setKey(baseURL: string, key: string): Promise<void> {
+    const account = normalizeBaseURL(baseURL)
+    try {
+      const entry = new AsyncEntry(this.service, account)
+      await entry.setPassword(key)
+      this.cache.set(account, key)
+    } catch (cause) {
+      throw new UpstreamError(
+        '<keystore>',
+        `Failed to write credential for ${account} to system keyring`,
+        undefined,
+        { cause }
+      )
+    }
+  }
+
+  /**
+   * Removes the keyring entry for `baseURL` and drops it from the cache.
+   * No-ops if the entry doesn't exist.
+   */
+  async deleteKey(baseURL: string): Promise<void> {
+    const account = normalizeBaseURL(baseURL)
+    this.cache.delete(account)
+    try {
+      const entry = new AsyncEntry(this.service, account)
+      await entry.deleteCredential()
+    } catch {
+      // No entry → nothing to delete. Don't surface a "not found" as an error.
+    }
+  }
+
+  /**
+   * Drops cached entries.
+   *
+   * @param baseURL - When provided, only that URL's cached key is dropped;
+   * when omitted, the entire cache is cleared. Call this when the user
+   * changes a provider's `baseURL` so the next request re-resolves the key.
+   */
+  invalidate(baseURL?: string): void {
+    if (baseURL === undefined) {
+      this.cache.clear()
+      return
+    }
+    this.cache.delete(normalizeBaseURL(baseURL))
+  }
+}

package/src/provider.ts

@@ -0,0 +1,86 @@
+import type {
+  CacheConfiguration,
+  ModelCapabilities
+} from '@inkdropapp/ai-catalog'
+import type { ModelMessage } from 'ai'
+import type { StreamEvent } from './stream-events.js'
+
+/**
+ * Inputs for a single one-shot streaming completion.
+ *
+ * `messages` reuses the AI SDK's `ModelMessage` type so callers can construct
+ * messages with the same shape the underlying SDK expects.
+ */
+export type CompletionRequest = {
+  messages: ModelMessage[]
+  temperature?: number
+  maxOutputTokens?: number
+  /** Forwarded to the underlying SDK call; aborts in-flight HTTP and ends the stream. */
+  abortSignal?: AbortSignal
+}
+
+/**
+ * A single configured model belonging to a provider.
+ *
+ * `capabilities` are the source of truth for whether a feature (tools, images,
+ * thinking) is available — UI gating and request-construction logic should
+ * branch on these flags rather than on `provider.id`.
+ */
+export interface AIModel {
+  /** Stable model id as the provider expects it on the wire. */
+  readonly id: string
+  /** Human-readable label for menus / picker UIs. */
+  readonly displayName: string
+  /** Back-reference to the owning provider. */
+  readonly provider: AIProvider
+  readonly capabilities: ModelCapabilities
+  /** Present when the provider supports prompt caching for this model (Anthropic). */
+  readonly cacheConfiguration?: CacheConfiguration
+
+  /**
+   * Streams a completion. The returned iterable always terminates — either
+   * with a `'finish'` event on success, or with an `'error'` event on failure.
+   * Consumers do not need to wrap iteration in try/catch.
+   */
+  streamCompletion(request: CompletionRequest): AsyncIterable<StreamEvent>
+}
+
+/**
+ * One AI integration (one auth identity + one base URL) exposing a list of
+ * `AIModel` instances. Multiple instances of the same provider class can
+ * coexist as long as their `id`s differ — that's how the long-tail
+ * OpenAI-compatible providers (OpenRouter, Together, Ollama, …) are modelled.
+ */
+export interface AIProvider {
+  /** Stable provider id; appears in `AISettings.slots[*].providerId`. */
+  readonly id: string
+  /** Human-readable label. */
+  readonly name: string
+  /** Resolved base URL for HTTP calls; doubles as the keyring account key. */
+  readonly baseURL: string
+  /**
+   * Environment variable consulted before the keyring during auth resolution.
+   * `null` for providers that cannot have an env-var convention.
+   */
+  readonly envVarName: string | null
+
+  listModels(): AIModel[]
+  getModel(id: string): AIModel | undefined
+
+  /** "Best" model for long-form / general chat tasks. */
+  defaultModel(): AIModel | undefined
+  /** Cheap / low-latency model for autocomplete-style features. */
+  defaultFastModel(): AIModel | undefined
+
+  /**
+   * `true` iff a key is currently resolvable via env var or system keyring.
+   * Does not perform a network round-trip.
+   */
+  isAuthenticated(): Promise<boolean>
+
+  /** Persists `key` to the system keyring under this provider's `baseURL`. */
+  setApiKey(key: string): Promise<void>
+
+  /** Removes the keyring entry for this provider's `baseURL`. */
+  clearApiKey(): Promise<void>
+}

package/src/providers/anthropic.ts

@@ -0,0 +1,175 @@
+import {
+  createAnthropic,
+  type AnthropicProvider as SdkAnthropicProvider
+} from '@ai-sdk/anthropic'
+import {
+  ANTHROPIC_DEFAULT_FAST_MODEL_ID,
+  ANTHROPIC_DEFAULT_MODEL_ID,
+  ANTHROPIC_MODELS,
+  DEFAULT_ANTHROPIC_CACHE_CONFIG,
+  DEFAULT_ANTHROPIC_CAPABILITIES,
+  type AnthropicCatalog,
+  type AnthropicModelDescriptor,
+  type CacheConfiguration,
+  type 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 {
+  AnthropicModelConfig,
+  AnthropicProviderConfig
+} from '../settings.js'
+import type { StreamEvent } from '../stream-events.js'
+
+const PROVIDER_ID = 'anthropic'
+const PROVIDER_NAME = 'Anthropic'
+const ENV_VAR = 'ANTHROPIC_API_KEY'
+const DEFAULT_BASE_URL = 'https://api.anthropic.com'
+
+/**
+ * The Anthropic (Claude) provider.
+ *
+ * Wraps `@ai-sdk/anthropic`. Loads its model catalogue from one of:
+ *   1. The {@link AnthropicCatalog} passed at construction time (server-distributed).
+ *   2. The compiled-in {@link ANTHROPIC_MODELS} list as a fallback.
+ *
+ * User-declared `config.models` are layered on top, overriding entries with
+ * matching ids regardless of source.
+ *
+ * Lazily constructs the SDK client on first stream and caches it across
+ * requests. The cached client is invalidated whenever `setApiKey` /
+ * `clearApiKey` is called or the resolved API key changes.
+ */
+export class AnthropicProvider implements AIProvider {
+  readonly id = PROVIDER_ID
+  readonly name = PROVIDER_NAME
+  readonly envVarName = ENV_VAR
+  readonly baseURL: string
+
+  private readonly keyStore: KeyStore
+  private readonly modelsById: Map<string, AnthropicAIModel>
+  private readonly defaultId: string
+  private readonly defaultFastId: string
+
+  private sdkClient: SdkAnthropicProvider | undefined
+  private sdkClientApiKey: string | undefined
+
+  constructor(
+    keyStore: KeyStore,
+    config: AnthropicProviderConfig = {},
+    catalog?: AnthropicCatalog
+  ) {
+    this.keyStore = keyStore
+    this.baseURL = config.baseURL ?? DEFAULT_BASE_URL
+
+    const baseModels = catalog?.models ?? ANTHROPIC_MODELS
+    this.defaultId = catalog?.defaultModelId ?? ANTHROPIC_DEFAULT_MODEL_ID
+    this.defaultFastId =
+      catalog?.defaultFastModelId ?? ANTHROPIC_DEFAULT_FAST_MODEL_ID
+
+    const map = new Map<string, AnthropicAIModel>()
+    for (const d of baseModels) {
+      map.set(d.id, new AnthropicAIModel(this, d))
+    }
+    for (const m of config.models ?? []) {
+      map.set(m.id, new AnthropicAIModel(this, descriptorFromUserConfig(m)))
+    }
+    this.modelsById = map
+  }
+
+  listModels(): AIModel[] {
+    return Array.from(this.modelsById.values())
+  }
+
+  getModel(id: string): AIModel | undefined {
+    return this.modelsById.get(id)
+  }
+
+  defaultModel(): AIModel | undefined {
+    return this.modelsById.get(this.defaultId)
+  }
+
+  defaultFastModel(): AIModel | undefined {
+    return this.modelsById.get(this.defaultFastId)
+  }
+
+  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 AnthropicAIModel to resolve the SDK client lazily. */
+  async getSdkClient(): Promise<SdkAnthropicProvider> {
+    const apiKey = await this.keyStore.getKey(this.envVarName, this.baseURL)
+    if (apiKey === null || apiKey.length === 0) {
+      throw new NoApiKey(this.id, this.envVarName)
+    }
+    if (this.sdkClient && this.sdkClientApiKey === apiKey) return this.sdkClient
+    this.sdkClient = createAnthropic({ apiKey, baseURL: this.baseURL })
+    this.sdkClientApiKey = apiKey
+    return this.sdkClient
+  }
+}
+
+const descriptorFromUserConfig = (
+  m: AnthropicModelConfig
+): AnthropicModelDescriptor => ({
+  id: m.id,
+  displayName: m.displayName ?? m.id,
+  capabilities: { ...DEFAULT_ANTHROPIC_CAPABILITIES, ...m.capabilities },
+  cacheConfiguration: m.cacheConfiguration ?? DEFAULT_ANTHROPIC_CACHE_CONFIG
+})
+
+class AnthropicAIModel implements AIModel {
+  readonly id: string
+  readonly displayName: string
+  readonly capabilities: ModelCapabilities
+  readonly cacheConfiguration: CacheConfiguration
+
+  constructor(
+    readonly provider: AnthropicProvider,
+    descriptor: AnthropicModelDescriptor
+  ) {
+    this.id = descriptor.id
+    this.displayName = descriptor.displayName
+    this.capabilities = descriptor.capabilities
+    this.cacheConfiguration = descriptor.cacheConfiguration
+  }
+
+  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)
+  }
+}