@inkdropapp/ai 0.1.0 → 0.1.2

package/README.md

@@ -4,7 +4,7 @@ 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.
+- **AIRegistry 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.
@@ -31,7 +31,7 @@ The package is **ESM-only**. Use `import`, not `require`.
 ## Quickstart
 
 ```ts
-import { Registry, type AISettings } from '@inkdropapp/ai'
+import { AIRegistry, type AISettings } from '@inkdropapp/ai'
 
 const settings: AISettings = {
   providers: {
@@ -44,13 +44,11 @@ const settings: AISettings = {
       }
     ]
   },
-  slots: {
-    default: { providerId: 'anthropic', modelId: 'claude-sonnet-4-6' },
-    fast: { providerId: 'anthropic', modelId: 'claude-haiku-4-5' }
-  }
+  // Pick one provider — slot models come from its catalogue defaults.
+  providerId: 'anthropic'
 }
 
-const registry = new Registry({ settings })
+const registry = new AIRegistry({ settings })
 
 // Configure once — keys go to the system keyring (or env var).
 const anthropic = registry.getProvider('anthropic')!
@@ -102,13 +100,18 @@ Inkdrop's AI features map onto two slots:
 
 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.
+1. Explicit binding from `settings.slots[slot]`, if both the provider id and model id resolve. *(Advanced — pin a specific model per slot or mix providers across slots.)*
+2. For `'fast'` only: fall back to `settings.slots.default` if that resolves.
+3. Preferred provider from `settings.providerId`, if configured — takes its `defaultModel()` (for `default`) or `defaultFastModel()` (for `fast`). *(The simple UI knob — one provider dropdown drives every slot.)*
+4. First **authenticated** registered provider in alphabetical id order, taking its `defaultModel()` / `defaultFastModel()`.
+5. `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.
+Steps 1 and 3 do **not** check authentication — the user picked those
+explicitly, so auth errors surface inline as `'error'` events at stream time
+rather than silently swapping providers. Step 4 is a courtesy fallback for
+hosts that don't wire any preference at all; it skips unauthenticated
+providers. `streamCompletion` throws `NoApiKey` only when resolution returns
+`undefined` (i.e. no provider is configured at all).
 
 ### Credential resolution
 
@@ -139,7 +142,7 @@ 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'
+import { AIRegistry, type AIModelCatalog } from '@inkdropapp/ai'
 
 const catalog: AIModelCatalog = {
   anthropic: {
@@ -167,14 +170,14 @@ const catalog: AIModelCatalog = {
   }
 }
 
-const registry = new Registry({ settings, catalog })
+const registry = new AIRegistry({ 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.
+2. **The catalogue passed to `AIRegistry`** — 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
@@ -191,7 +194,7 @@ 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 })
+const registry = new AIRegistry({ settings })
 
 fetch('https://config.inkdrop.app/ai-catalog.json')
   .then(r => r.json() as Promise<AIModelCatalog>)
@@ -266,10 +269,10 @@ hosts that want to predict the name (e.g. for an onboarding hint).
 
 ## API reference
 
-### `Registry`
+### `AIRegistry`
 
 ```ts
-new Registry({
+new AIRegistry({
   settings: AISettings,
   catalog?: AIModelCatalog,   // server-distributed model lists; see "Model catalogues"
   keyStore?: KeyStore
@@ -299,8 +302,8 @@ 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
+You generally don't construct a `KeyStore` yourself — `AIRegistry` creates one.
+Pass an existing instance via `AIRegistryOptions.keyStore` if you want to share
 its cache across registries.
 
 ### `AIProvider`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inkdropapp/ai",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "AI integration common module",
   "type": "module",
   "main": "src/index.ts",
@@ -18,12 +18,14 @@
   ],
   "author": "Takuya Matsuyama <t@inkdrop.app>",
   "license": "UNLICENSED",
+  "packageManager": "pnpm@11.1.1",
   "dependencies": {
-    "@ai-sdk/anthropic": "^4.0.0-beta.40",
-    "@ai-sdk/openai-compatible": "^3.0.0-beta.33",
+    "@ai-sdk/anthropic": "4.0.0-beta.42",
+    "@ai-sdk/openai-compatible": "3.0.0-beta.36",
+    "@ai-sdk/provider": "4.0.0-beta.14",
     "@inkdropapp/ai-catalog": "^0.1.0",
     "@napi-rs/keyring": "^1.2.0",
-    "ai": "^7.0.0-beta.113"
+    "ai": "7.0.0-beta.116"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",

package/src/index.ts

@@ -42,7 +42,7 @@ export {
   deriveEnvVarName
 } from './providers/openai-compatible.js'
 export {
-  Registry,
-  type RegistryOptions,
+  AIRegistry,
+  type AIRegistryOptions,
   type ResolvedSlot
 } from './registry.js'

package/src/provider.ts

@@ -52,7 +52,10 @@ export interface AIModel {
  * OpenAI-compatible providers (OpenRouter, Together, Ollama, …) are modelled.
  */
 export interface AIProvider {
-  /** Stable provider id; appears in `AISettings.slots[*].providerId`. */
+  /**
+   * Stable provider id; appears in both `AISettings.providerId` and
+   * `AISettings.slots[*].providerId`.
+   */
   readonly id: string
   /** Human-readable label. */
   readonly name: string

package/src/registry.ts

@@ -13,13 +13,13 @@ export type ResolvedSlot = {
   model: AIModel
 }
 
-export type RegistryOptions = {
+export type AIRegistryOptions = {
   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}.
+   * construction time or swaps it in later via {@link AIRegistry.updateCatalog}.
    */
   catalog?: AIModelCatalog
   /** Pass an existing `KeyStore` to share its in-memory cache across registries. */
@@ -32,26 +32,26 @@ export type RegistryOptions = {
  * 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
+ * The `AIRegistry` is stateless beyond its provider list — it doesn't observe
+ * settings on its own. Call {@link AIRegistry.updateSettings} when settings
  * change to rebuild providers.
  *
  * @example
  * ```ts
- * const registry = new Registry({ settings })
+ * const registry = new AIRegistry({ 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 {
+export class AIRegistry {
   readonly keyStore: KeyStore
   private providers: Map<string, AIProvider> = new Map()
   private settings: AISettings
   private catalog: AIModelCatalog | undefined
 
-  constructor(options: RegistryOptions) {
+  constructor(options: AIRegistryOptions) {
     this.keyStore = options.keyStore ?? new KeyStore()
     this.settings = options.settings
     this.catalog = options.catalog
@@ -84,12 +84,17 @@ export class Registry {
    * 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
+   *   3. Preferred provider `settings.providerId`, if that provider is configured,
+   *      taking its `defaultModel()` (or `defaultFastModel()` for the fast slot).
+   *      Authentication is not gated here — the user explicitly picked this
+   *      provider; auth errors surface at stream time rather than silently
+   *      swapping providers.
+   *   4. 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.
+   *   5. `undefined` if no provider can satisfy the slot.
    *
-   * Async because the third step calls `provider.isAuthenticated()`, which may
+   * Async because the fourth step calls `provider.isAuthenticated()`, which may
    * touch the keyring.
    */
   async resolveSlot(slot: SlotName): Promise<ResolvedSlot | undefined> {
@@ -101,6 +106,17 @@ export class Registry {
       if (fallback) return fallback
     }
 
+    if (this.settings.providerId) {
+      const provider = this.providers.get(this.settings.providerId)
+      if (provider) {
+        const model =
+          slot === 'fast'
+            ? provider.defaultFastModel()
+            : provider.defaultModel()
+        if (model) return { provider, model }
+      }
+    }
+
     for (const provider of this.providers.values()) {
       if (!(await provider.isAuthenticated())) continue
       const model =
@@ -124,7 +140,7 @@ export class Registry {
   /**
    * Streams a completion for a task slot.
    *
-   * Resolves the slot via {@link Registry.resolveSlot}; throws {@link NoApiKey}
+   * Resolves the slot via {@link AIRegistry.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.)

package/src/settings.ts

@@ -88,7 +88,7 @@ export type AnthropicProviderConfig = CommonProviderConfig & {
 
 /**
  * Top-level AI configuration. The host (Inkdrop main process) constructs this
- * from whichever persistence layer it uses and passes it to `Registry`.
+ * from whichever persistence layer it uses and passes it to `AIRegistry`.
  *
  * The library never reads or writes settings to disk itself.
  */
@@ -98,8 +98,17 @@ export type AISettings = {
     openaiCompatible?: OpenAICompatibleProviderConfig[]
   }
   /**
-   * Per-slot model overrides. Unset slots fall back to the first registered
-   * provider's `defaultModel` / `defaultFastModel`.
+   * Preferred provider for every task slot. When set (and the per-slot
+   * `slots[slot]` override isn't), each slot resolves to this provider's
+   * `defaultModel` / `defaultFastModel`. This is the simple UI knob — bind it
+   * to a single "AI provider" dropdown.
+   */
+  providerId?: string
+  /**
+   * Per-slot `(provider, model)` overrides. Wins over `providerId` when set.
+   * Useful for advanced configurations that pin a specific model per slot or
+   * mix providers across slots (e.g. Claude for `default`, a local model for
+   * `fast`).
    */
   slots?: Partial<Record<SlotName, SlotConfig>>
 }