@jacobbd/relay-ai 0.6.3 → 0.7.1

package/README.md

@@ -53,6 +53,7 @@ Pick your backend:
 | `relay-ai antigravity-ide` | Launch Antigravity IDE with Relay models, macOS ([warning + guide](docs/ANTIGRAVITY.md)) |
 | `relay-ai providers auth <id>` | Authenticate an OAuth provider (GitHub Copilot, xAI, OpenAI) |
 | `relay-ai --ai` | Full agent reference for scripts and alef-agent ([guide](docs/AI-AGENTS.md)) |
+| `@jacobbd/relay-ai/core` | Embed Relay AI in a Node app in-process — no CLI/UI/server ([guide](docs/CORE.md)) |
 
 ## Features
 
@@ -406,6 +407,31 @@ export ANTHROPIC_API_KEY="anything"
 unset CLAUDE_CODE_USE_VERTEX ANTHROPIC_VERTEX_PROJECT_ID CLOUD_ML_REGION
 ```
 
+## Embedded usage (`@jacobbd/relay-ai/core`)
+
+Node.js applications can embed Relay AI in-process — no CLI, UI, or server — to list the configured model catalog and obtain ready [Vercel AI SDK](https://sdk.vercel.ai) `LanguageModel` instances:
+
+```ts
+import { listRelayModels, createRelayModel, isRelayCoreError } from '@jacobbd/relay-ai/core';
+import { streamText } from 'ai';
+
+const models = listRelayModels();          // credential-free catalog
+const model = await createRelayModel(models[0].routeId);
+const result = await streamText({ model, prompt: 'Hello!' });
+```
+
+**Route ids** are unconditionally scoped: `` `${providerId}::${modelId}` `` (split on the first `::`; model ids may contain `/` and `:`, e.g. `openrouter::vendor/model:free`). Because they are never bare, a route id persisted by your app stays valid even when a second provider later exposes the same model id.
+
+**Ownership boundary:** Relay AI keeps sole ownership of provider registration, credentials, the OS keyring, and OAuth login/refresh. `createRelayModel()` resolves credentials (refreshing expiring OAuth tokens) at call time and returns only the SDK model — your app never receives or stores credential material. Re-authentication always happens through Relay (`relay-ai ui`), never through the consumer.
+
+**No server required:** the Core API reads the same registry and config as the CLI (`~/.relay-ai`, overridable with `RELAY_AI_HOME`) and never starts a server, opens a browser, or writes to disk. `createRelayModel()` re-reads state on every call, so provider changes take effect without restarting your app. Errors are thrown as `RelayCoreError` with a machine-readable `code` (see `isRelayCoreError`) and never contain credential material.
+
+**Schema compatibility:** Core supports registry schema v1. A registry written by a newer Relay version fails fast with `UNSUPPORTED_REGISTRY_VERSION` — upgrade relay-ai rather than downgrading the file.
+
+**Capability detection:** `capabilities.tools` and `capabilities.vision` are always `'unknown'` today — the cached model catalog carries no tools/vision metadata, and Core deliberately never guesses from a model's name. Don't filter on `=== true` for these two fields; use `capabilities.reasoning` (`'none' | 'fixed' | 'adjustable' | 'unknown'`), which is derived from real provider metadata.
+
+**Full guide:** prerequisites, the complete API and error-code reference, and troubleshooting — see **[docs/CORE.md](docs/CORE.md)**.
+
 ## Antigravity CLI, app, and IDE support
 
 Relay AI can launch the Antigravity CLI, standalone Antigravity app, and Antigravity IDE through a local Cloud Code gateway. This lets Antigravity's native model picker show Relay models from your configured providers.