@inkdropapp/ai 0.1.0

package/README.md

@@ -0,0 +1,472 @@
+# @inkdropapp/ai
+
+Headless TypeScript library for multi-provider AI integration. Designed to run
+in the Inkdrop Electron main process.
+
+- **Two-interface design** — `AIProvider` (auth + model catalogue) is separate from `AIModel` (capabilities + streaming).
+- **Registry with task-slot routing** — slot binding plus fallback to per-provider defaults, so a single AI feature gets a sensible model without any user setup.
+- **Two providers ship out of the box**:
+  - `AnthropicProvider` (Claude 4.x) — built-in model catalogue, prompt-cache configuration.
+  - `OpenAICompatibleProvider` — instantiated per user-named entry; covers OpenRouter, Together, Fireworks, Groq, vLLM, Ollama (`/v1`), LiteLLM, etc. with a single class.
+- **Swappable model catalogues** — providers' built-in model lists can be replaced at runtime with an `AIModelCatalog` (e.g. fetched from a server), so new model releases ship without an app update.
+- **URL-keyed credential storage** via `@napi-rs/keyring`. Two endpoints to the same provider get separate keyring entries automatically.
+- **Single streaming event type** — every provider's stream is reduced to a `StreamEvent` discriminated union.
+- **Retry-aware error type** — `RateLimitExceeded` / `ServerOverloaded` carry `retryAfter` (seconds) parsed from the response header.
+- **No tools, no agents, no UI, no persistence in v0.1** — see [Out of scope](#out-of-scope-deferred).
+
+---
+
+## Install
+
+```sh
+npm install @inkdropapp/ai
+```
+
+Required peers (already declared as dependencies): `ai@beta`, `@ai-sdk/anthropic@beta`, `@ai-sdk/openai-compatible@beta`, `@napi-rs/keyring`.
+
+The package is **ESM-only**. Use `import`, not `require`.
+
+---
+
+## Quickstart
+
+```ts
+import { Registry, type AISettings } from '@inkdropapp/ai'
+
+const settings: AISettings = {
+  providers: {
+    anthropic: {},
+    openaiCompatible: [
+      {
+        id: 'openrouter',
+        baseURL: 'https://openrouter.ai/api/v1',
+        models: [{ id: 'meta/llama-3-70b' }]
+      }
+    ]
+  },
+  slots: {
+    default: { providerId: 'anthropic', modelId: 'claude-sonnet-4-6' },
+    fast: { providerId: 'anthropic', modelId: 'claude-haiku-4-5' }
+  }
+}
+
+const registry = new Registry({ settings })
+
+// Configure once — keys go to the system keyring (or env var).
+const anthropic = registry.getProvider('anthropic')!
+if (!(await anthropic.isAuthenticated())) {
+  await anthropic.setApiKey('sk-ant-...')
+}
+
+const events = await registry.streamCompletion('default', {
+  messages: [{ role: 'user', content: 'Summarise this note in one sentence.' }]
+})
+
+for await (const event of events) {
+  switch (event.kind) {
+    case 'text-delta':
+      process.stdout.write(event.delta)
+      break
+    case 'finish':
+      console.log('\n[done]', event.usage)
+      break
+    case 'error':
+      console.error('[error]', event.error.kind, event.error.message)
+      break
+  }
+}
+```
+
+---
+
+## Concepts
+
+### Provider vs Model
+
+An `AIProvider` is one authenticated integration (one API key + one `baseURL`).
+It exposes a list of `AIModel` instances. The model carries the capability flags
+(`supportsTools`, `supportsImages`, `supportsThinking`, `maxTokens`, …) and the
+streaming entrypoint.
+
+UI gating and request-construction logic should branch on **model capabilities**,
+not on `provider.id`. That keeps the host code provider-agnostic.
+
+### Slots
+
+Inkdrop's AI features map onto two slots:
+
+| Slot      | Used for                                                                           |
+| --------- | ---------------------------------------------------------------------------------- |
+| `default` | Long-form generation. The user's "main" model.                                     |
+| `fast`    | Latency-sensitive tasks: Next-Edit Suggestions, quick rewrites, title suggestions. |
+
+A slot resolves to `(provider, model)` via:
+
+1. Explicit binding from `settings.slots[slot]`, if both the provider id and model id resolve.
+2. The first registered provider's `defaultModel()` (for `default`) or `defaultFastModel()` (for `fast`).
+3. `undefined` if no provider can satisfy the slot.
+
+Authentication is **not** checked during slot resolution — that's
+`streamCompletion`'s job, which throws `NoApiKey` if no provider is configured
+at all and surfaces upstream auth failures inline as `'error'` events.
+
+### Credential resolution
+
+`KeyStore` resolves an API key in this order:
+
+1. The provider's environment variable (e.g. `ANTHROPIC_API_KEY`, or
+   `<UPPER_SNAKE_ID>_API_KEY` for an OpenAI-compatible entry — see
+   [`deriveEnvVarName`](#environment-variable-naming)).
+2. System keyring entry under the service `inkdrop.ai` and account = the
+   _normalised_ `baseURL`.
+
+The keyring account is the URL, not the provider id, so two endpoints to the
+same provider get **separate** entries (e.g. staging + prod, or Ollama at home
+
+- at work). The host never has to model that distinction.
+
+The cache is in-memory, keyed on normalised `baseURL`. Env-var changes mid-process
+are not reflected until you call `keyStore.invalidate()`. `setApiKey` /
+`clearApiKey` invalidate automatically.
+
+### Model catalogues
+
+Each provider has a compiled-in list of models (e.g. `ANTHROPIC_MODELS`). That
+list is fine until a new Claude version ships and you don't want to wait for an
+Inkdrop release to use it.
+
+An `AIModelCatalog` is a per-provider override of that list, designed to be
+distributed by a server endpoint and swapped in at runtime:
+
+```ts
+import { Registry, type AIModelCatalog } from '@inkdropapp/ai'
+
+const catalog: AIModelCatalog = {
+  anthropic: {
+    models: [
+      {
+        id: 'claude-sonnet-4-7',
+        displayName: 'Claude Sonnet 4.7',
+        capabilities: {
+          supportsTools: true,
+          supportsImages: true,
+          supportsThinking: true,
+          supportsStreamingTools: true,
+          maxTokens: 200_000,
+          maxOutputTokens: 64_000
+        },
+        cacheConfiguration: {
+          minTotalTokens: 2048,
+          minCachedTokens: 1024,
+          shouldSpeculate: true
+        }
+      }
+    ],
+    defaultModelId: 'claude-sonnet-4-7',
+    defaultFastModelId: 'claude-haiku-4-5'
+  }
+}
+
+const registry = new Registry({ settings, catalog })
+```
+
+Resolution order, from highest to lowest priority:
+
+1. **User-declared `config.models`** (`settings.providers.<name>.models`) — the
+   user's local overrides always win, regardless of where the catalogue came from.
+2. **The catalogue passed to `Registry`** — overrides the provider's built-in list.
+3. **The provider's compiled-in catalogue** (`ANTHROPIC_MODELS`, …) — fallback.
+
+`defaultModelId` / `defaultFastModelId` override the provider's hard-coded
+defaults the same way.
+
+Each provider entry on `AIModelCatalog` is independent and optional — you can
+ship `{ anthropic: ... }` and leave other providers on their built-in
+catalogues. Today `anthropic` is the only entry; other providers will be added
+as they need it.
+
+#### Updating the catalogue at runtime
+
+Typical flow: app starts with no catalogue (built-in defaults apply), fetches
+one from the server in the background, then swaps it in:
+
+```ts
+const registry = new Registry({ settings })
+
+fetch('https://config.inkdrop.app/ai-catalog.json')
+  .then(r => r.json() as Promise<AIModelCatalog>)
+  .then(catalog => registry.updateCatalog(catalog))
+  .catch(err => console.warn('Catalog fetch failed; using built-ins', err))
+```
+
+`updateCatalog(undefined)` reverts to the providers' compiled-in catalogues.
+The shared `KeyStore` cache and authentication state are preserved across the swap.
+
+### Streaming events
+
+Every provider's stream collapses into the same discriminated union:
+
+```ts
+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 }
+```
+
+Three contracts you can rely on:
+
+1. **Errors are events, not exceptions.** Mid-stream failures arrive as
+   `{ kind: 'error', ... }` and the iterator returns. No try/catch around the
+   `for await` loop is needed.
+2. **The iterator always terminates.** Every successful stream ends with a
+   `'finish'` event; every failed one ends with an `'error'` event.
+3. **Unknown SDK chunk types are silently dropped.** Forward-compat with future
+   AI SDK chunk variants without a library bump.
+
+The library is currently text-only — `tool-call` / `tool-result` variants are
+typed for forward compat but never produced.
+
+### Errors
+
+`AIError` is the base class. Variants:
+
+| Class                 | Kind                  | When                                                                       |
+| --------------------- | --------------------- | -------------------------------------------------------------------------- |
+| `NoApiKey`            | `no-api-key`          | The provider has no key configured (env var or keyring).                   |
+| `AuthenticationError` | `authentication`      | Upstream returned 401/403.                                                 |
+| `RateLimitExceeded`   | `rate-limit-exceeded` | Upstream returned 429. Carries `retryAfter` (seconds).                     |
+| `ServerOverloaded`    | `server-overloaded`   | Upstream returned 503/529. Carries `retryAfter`.                           |
+| `PromptTooLarge`      | `prompt-too-large`    | Upstream returned 413, or the message indicates a context-length overflow. |
+| `UpstreamError`       | `upstream`            | Anything else; preserves `status` and `cause`.                             |
+
+Switch on `error.kind` rather than on `instanceof`. Use `isAIError(value)` if
+you need a type guard for the union.
+
+### Environment variable naming
+
+For Anthropic the env-var name is fixed: `ANTHROPIC_API_KEY`.
+
+For OpenAI-compatible entries it's derived from the entry's `id`:
+
+| Entry id       | Env var                |
+| -------------- | ---------------------- |
+| `openrouter`   | `OPENROUTER_API_KEY`   |
+| `together_ai`  | `TOGETHER_AI_API_KEY`  |
+| `ollama-local` | `OLLAMA_LOCAL_API_KEY` |
+| `my.proxy`     | `MY_PROXY_API_KEY`     |
+
+The transform: replace any non-alphanumeric character with `_`, collapse runs
+of `_`, uppercase, append `_API_KEY`. Exposed as `deriveEnvVarName(id)` for
+hosts that want to predict the name (e.g. for an onboarding hint).
+
+---
+
+## API reference
+
+### `Registry`
+
+```ts
+new Registry({
+  settings: AISettings,
+  catalog?: AIModelCatalog,   // server-distributed model lists; see "Model catalogues"
+  keyStore?: KeyStore
+})
+
+registry.listProviders(): AIProvider[]
+registry.getProvider(id: string): AIProvider | undefined
+registry.listAllModels(): { provider: AIProvider; model: AIModel }[]
+registry.resolveSlot(slot: SlotName): ResolvedSlot | undefined
+registry.streamCompletion(slot: SlotName, request: CompletionRequest): Promise<AsyncIterable<StreamEvent>>
+registry.updateSettings(next: AISettings): void
+registry.updateCatalog(next: AIModelCatalog | undefined): void
+```
+
+`updateSettings` and `updateCatalog` both rebuild providers but preserve the
+`KeyStore` cache. Pass `undefined` to `updateCatalog` to revert to providers'
+compiled-in catalogues.
+
+### `KeyStore`
+
+```ts
+new KeyStore({ service?: string })  // service defaults to 'inkdrop.ai'
+
+store.getKey(envVarName: string | null, baseURL: string): Promise<string | null>
+store.setKey(baseURL: string, key: string): Promise<void>
+store.deleteKey(baseURL: string): Promise<void>  // no-op if absent
+store.invalidate(baseURL?: string): void          // omit url to clear all
+```
+
+You generally don't construct a `KeyStore` yourself — `Registry` creates one.
+Pass an existing instance via `RegistryOptions.keyStore` if you want to share
+its cache across registries.
+
+### `AIProvider`
+
+```ts
+provider.id              // stable id, appears in slot config
+provider.name            // human label
+provider.baseURL         // doubles as keyring account
+provider.envVarName      // string | null
+
+provider.listModels(): AIModel[]
+provider.getModel(id: string): AIModel | undefined
+provider.defaultModel(): AIModel | undefined
+provider.defaultFastModel(): AIModel | undefined
+
+provider.isAuthenticated(): Promise<boolean>
+provider.setApiKey(key: string): Promise<void>
+provider.clearApiKey(): Promise<void>
+```
+
+### `AIModel`
+
+```ts
+model.id
+model.displayName
+model.provider                          // back-reference
+model.capabilities                       // ModelCapabilities
+model.cacheConfiguration?               // CacheConfiguration | undefined
+
+model.streamCompletion(request: CompletionRequest): AsyncIterable<StreamEvent>
+```
+
+---
+
+## Examples
+
+### Multiple OpenAI-compatible providers
+
+```ts
+const settings: AISettings = {
+  providers: {
+    openaiCompatible: [
+      {
+        id: 'openrouter',
+        baseURL: 'https://openrouter.ai/api/v1',
+        models: [{ id: 'meta/llama-3-70b' }]
+      },
+      {
+        id: 'ollama_local',
+        baseURL: 'http://localhost:11434/v1',
+        models: [
+          {
+            id: 'llama3.2',
+            displayName: 'Llama 3.2',
+            capabilities: { supportsImages: false, maxTokens: 128_000 }
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`openrouter` looks up `OPENROUTER_API_KEY`; `ollama_local` looks up
+`OLLAMA_LOCAL_API_KEY`. Each gets its own keyring entry under its `baseURL`.
+
+### Mixing slots across providers
+
+```ts
+const settings: AISettings = {
+  providers: {
+    anthropic: {},
+    openaiCompatible: [
+      {
+        id: 'ollama_local',
+        baseURL: 'http://localhost:11434/v1',
+        models: [{ id: 'llama3.2' }]
+      }
+    ]
+  },
+  slots: {
+    default: { providerId: 'anthropic', modelId: 'claude-sonnet-4-6' },
+    fast: { providerId: 'ollama_local', modelId: 'llama3.2' }
+  }
+}
+```
+
+### Custom Anthropic baseURL (proxy / staging)
+
+```ts
+const settings: AISettings = {
+  providers: {
+    anthropic: { baseURL: 'https://anthropic-proxy.internal/v1' }
+  }
+}
+```
+
+The keyring entry for the proxy is separate from the one for
+`https://api.anthropic.com`, so you can switch back and forth without
+re-entering the key.
+
+### Aborting a stream
+
+```ts
+const controller = new AbortController()
+const events = await registry.streamCompletion('default', {
+  messages: [{ role: 'user', content: 'Long task...' }],
+  abortSignal: controller.signal
+})
+
+// Later:
+controller.abort()
+```
+
+### Handling rate limits
+
+```ts
+for await (const event of events) {
+  if (event.kind === 'error') {
+    if (event.error.kind === 'rate-limit-exceeded') {
+      const retry = event.error.retryAfter ?? 5
+      console.warn(`Rate limited; retrying in ${retry}s`)
+      // schedule retry…
+    }
+    break
+  }
+}
+```
+
+### Listing every model for a picker UI
+
+```ts
+for (const { provider, model } of registry.listAllModels()) {
+  console.log(`${provider.name} / ${model.displayName}`, model.capabilities)
+}
+```
+
+---
+
+## Out of scope (deferred)
+
+- Tools / agentic loops / MCP integration.
+- Embedding models.
+- Auto-discovery (e.g. Ollama `/api/tags`).
+- Settings file persistence — pass `AISettings` in as plain data; the host owns its config layer.
+- Reactivity / observable settings — the host's React app should re-create the registry (or call `updateSettings`) when settings change.
+- React / UI components.
+
+---
+
+## Development
+
+```sh
+npm install
+npm test          # runs all 82 tests against the real system keyring
+npm run lint
+npm run gen       # emits .d.ts files into types/
+```
+
+Tests use a unique per-run keyring service name (`inkdrop.ai.test.<hex>`) so they
+never touch production entries on a dev machine, and an `afterEach` hook deletes
+every entry created during the test.
+
+CI runs the same suite on macOS, Windows, and Ubuntu (with gnome-keyring +
+dbus-run-session for the keyring).
+
+## License
+
+UNLICENSED — internal Inkdrop module.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@inkdropapp/ai",
+  "version": "0.1.0",
+  "description": "AI integration common module",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "types/index.d.ts",
+  "scripts": {
+    "lint": "eslint src __tests__",
+    "test": "node --experimental-vm-modules --no-warnings=ExperimentalWarning node_modules/jest/bin/jest.js --config jest.config.cjs --runInBand",
+    "gen": "tsc --declaration --emitDeclarationOnly",
+    "format": "prettier --write .",
+    "prepublishOnly": "npm-run-all lint test gen"
+  },
+  "keywords": [
+    "ai",
+    "inkdrop"
+  ],
+  "author": "Takuya Matsuyama <t@inkdrop.app>",
+  "license": "UNLICENSED",
+  "dependencies": {
+    "@ai-sdk/anthropic": "^4.0.0-beta.40",
+    "@ai-sdk/openai-compatible": "^3.0.0-beta.33",
+    "@inkdropapp/ai-catalog": "^0.1.0",
+    "@napi-rs/keyring": "^1.2.0",
+    "ai": "^7.0.0-beta.113"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^25.7.0",
+    "eslint": "^10.3.0",
+    "eslint-config-prettier": "^10.1.8",
+    "jest": "^30.4.2",
+    "npm-run-all": "^4.1.5",
+    "prettier": "^3.8.3",
+    "ts-jest": "^29.4.9",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.3"
+  },
+  "files": [
+    "src",
+    "types"
+  ]
+}

package/src/errors.ts

@@ -0,0 +1,117 @@
+/** Discriminant for {@link AIError} subclasses. */
+export type AIErrorKind =
+  | 'no-api-key'
+  | 'rate-limit-exceeded'
+  | 'server-overloaded'
+  | 'authentication'
+  | 'prompt-too-large'
+  | 'upstream'
+
+/**
+ * Base class for every error this library surfaces. Concrete subclasses are
+ * tagged with `kind` so consumers can switch on it without instanceof chains.
+ *
+ * Errors are emitted as `{ kind: 'error', error }` events inside completion
+ * streams rather than thrown — consumers that iterate the stream do not need
+ * try/catch.
+ */
+export abstract class AIError extends Error {
+  abstract readonly kind: AIErrorKind
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options)
+    this.name = new.target.name
+  }
+}
+
+/**
+ * Thrown / emitted when a provider has no resolvable API key — neither in its
+ * environment variable nor in the system keyring.
+ */
+export class NoApiKey extends AIError {
+  readonly kind = 'no-api-key' as const
+
+  constructor(
+    public readonly providerId: string,
+    public readonly envVarName: string | null
+  ) {
+    const hint = envVarName
+      ? ` Set ${envVarName} or store the key in the system keychain.`
+      : ' Store the key in the system keychain.'
+    super(`Provider "${providerId}" has no API key configured.${hint}`)
+  }
+}
+
+/** Upstream returned 401 / 403 — the configured key was rejected. */
+export class AuthenticationError extends AIError {
+  readonly kind = 'authentication' as const
+
+  constructor(
+    public readonly providerId: string,
+    message?: string
+  ) {
+    super(message ?? `Authentication failed for provider "${providerId}".`)
+  }
+}
+
+/** Upstream returned 429. `retryAfter` is in seconds, parsed from the response header. */
+export class RateLimitExceeded extends AIError {
+  readonly kind = 'rate-limit-exceeded' as const
+
+  constructor(
+    public readonly providerId: string,
+    public readonly retryAfter: number | undefined,
+    message?: string
+  ) {
+    super(message ?? `Rate limit exceeded on provider "${providerId}".`)
+  }
+}
+
+/** Upstream returned 503 / 529. `retryAfter` is in seconds, parsed from the response header. */
+export class ServerOverloaded extends AIError {
+  readonly kind = 'server-overloaded' as const
+
+  constructor(
+    public readonly providerId: string,
+    public readonly retryAfter: number | undefined,
+    message?: string
+  ) {
+    super(message ?? `Provider "${providerId}" is overloaded.`)
+  }
+}
+
+/** Prompt exceeds the model's context window (HTTP 413, or message says so). */
+export class PromptTooLarge extends AIError {
+  readonly kind = 'prompt-too-large' as const
+
+  constructor(
+    public readonly providerId: string,
+    public readonly tokenCount: number | undefined,
+    public readonly maxTokens: number | undefined,
+    message?: string
+  ) {
+    super(message ?? `Prompt exceeds the model's context window.`)
+  }
+}
+
+/**
+ * Catch-all for upstream failures that don't map to a more specific variant.
+ * `status` is the HTTP status code when known; `cause` preserves the original
+ * AI SDK error for debugging.
+ */
+export class UpstreamError extends AIError {
+  readonly kind = 'upstream' as const
+
+  constructor(
+    public readonly providerId: string,
+    message: string,
+    public readonly status?: number,
+    options?: { cause?: unknown }
+  ) {
+    super(message, options)
+  }
+}
+
+/** Type guard for {@link AIError} and any of its subclasses. */
+export const isAIError = (error: unknown): error is AIError =>
+  error instanceof AIError

package/src/index.ts

@@ -0,0 +1,48 @@
+export type { AIProvider, AIModel, CompletionRequest } from './provider.js'
+export type { StreamEvent, Usage, FinishReason } from './stream-events.js'
+export type {
+  AISettings,
+  SlotName,
+  SlotConfig,
+  CommonProviderConfig,
+  AnthropicProviderConfig,
+  AnthropicModelConfig,
+  OpenAICompatibleProviderConfig,
+  OpenAICompatibleModelConfig
+} from './settings.js'
+export {
+  ANTHROPIC_MODELS,
+  ANTHROPIC_DEFAULT_MODEL_ID,
+  ANTHROPIC_DEFAULT_FAST_MODEL_ID,
+  DEFAULT_ANTHROPIC_CACHE_CONFIG,
+  DEFAULT_ANTHROPIC_CAPABILITIES,
+  BUILT_IN_CATALOG,
+  type AIModelCatalog,
+  type AnthropicCatalog,
+  type AnthropicModelDescriptor,
+  type CacheConfiguration,
+  type ModelCapabilities
+} from '@inkdropapp/ai-catalog'
+export {
+  AIError,
+  NoApiKey,
+  AuthenticationError,
+  RateLimitExceeded,
+  ServerOverloaded,
+  PromptTooLarge,
+  UpstreamError,
+  isAIError,
+  type AIErrorKind
+} from './errors.js'
+export { KeyStore, type KeyStoreOptions } from './key-store.js'
+export { normalizeBaseURL } from './url.js'
+export { AnthropicProvider } from './providers/anthropic.js'
+export {
+  OpenAICompatibleProvider,
+  deriveEnvVarName
+} from './providers/openai-compatible.js'
+export {
+  Registry,
+  type RegistryOptions,
+  type ResolvedSlot
+} from './registry.js'