nexus-ai-pro 1.3.0 → 1.5.0

package/API_STABILITY.md

@@ -26,7 +26,48 @@ Source files, `dist` file paths, examples, test helpers that are not exported, a
 - Security fixes may tighten validation or blocking behavior in a patch release when preserving the old behavior would leave users exposed.
 - Provider behavior can change when an upstream API changes; Nexus will preserve its normalized request and response contracts where possible.
 
-The package is ESM-only and supports Node.js 22 or newer. CommonJS `require()` and deep imports into `dist` or `src` are not supported.
+## Module formats
+
+Since 1.2.0 the package ships parallel ESM and CommonJS builds and supports Node.js 22 or newer.
+Both are covered by this policy:
+
+- every export subpath carries `import` and `require` conditions, each resolving to its own build and
+  its own declarations, so a CommonJS consumer never lands on ESM declarations;
+- `typesVersions` maps each subpath to its CommonJS declarations, so subpath types resolve under
+  `moduleResolution: "node10"` without a consumer migrating its `tsconfig.json`;
+- dropping either build, or removing a subpath from either condition, requires a major release.
+
+Deep imports into `dist`, `dist-cjs`, or `src` are not supported. Import only from `nexus-ai-pro` or
+one of its explicit subpaths.
+
+## Capability negotiation stage
+
+`negotiateCompletionRequest()`, `NexusCapabilityError`, `CapabilityPolicy`, `CapabilityWarning`, and
+the `nexus-ai-pro/capabilities` subpath are public and follow the 1.x rules.
+
+Which options a given model accepts is registry data, not a compatibility guarantee. A model's
+declared capabilities, cache lifetimes, reasoning effort levels, and prices can change in a minor
+release when a provider changes its lineup, and new normalized warning entries may be added. What is
+guaranteed is the behavior of each policy: `strict` throws before the provider call, `warn` records a
+warning and continues, `off` sends the request unchanged, and an option a model does not mention is
+always passed through rather than refused.
+
+`ResponseMeta.usage` and `ResponseMeta.cost` are public normalized shapes. Reported token counts and
+prices originate with the provider or with bundled defaults and are not compatibility guarantees;
+`cost.basis` distinguishes the two. `ResponseMeta.estimatedCost` is deprecated in favor of
+`cost.amount` and will be removed in the next major release.
+
+## Telephony API stage
+
+The `nexus-ai-pro/telephony`, `telephony/twilio`, and `telephony/realtime-bridge` subpaths are public
+and follow the 1.x rules. This covers `TelephonyManager`, the `TelephonyProvider` contract, the
+normalized call, media-stream, status-callback, and phone-number types, the TwiML helpers, and the
+realtime bridge.
+
+Provider payloads under `raw`, TwiML markup details beyond the documented helper options, webhook
+signature formats, upstream call-status vocabularies, and carrier behavior are controlled by the
+provider and are not normalized guarantees. `TelephonyProvider` methods are optional by design, so a
+provider adapter may implement any subset; adding a new optional method is a minor change.
 
 ## Realtime API stage
 
@@ -65,6 +106,31 @@ exactly-once provider execution. Those capabilities will use additive adapters a
 `MemoryAssetStore` is likewise process-local and does not promise cross-process durability or shared
 tenant state.
 
+## Embeddings API stage
+
+The `nexus-ai-pro/embeddings` family is public and follows the 1.x rules, including the explicit
+`embeddings/adapters`, `embeddings/mock`, and `embeddings/models` subpaths. This covers
+`EmbeddingManager`, `ai.embed()` and `ai.embedOne()`, the `EmbeddingsProvider` contract, the
+normalized request, embedding, and meta shapes, the error subclasses, and `toEmbeddingFunction()`.
+
+`EmbeddingsProvider` is a distinct contract from the pre-existing `EmbeddingProvider` function type
+used by `MemoryVectorStore`, the semantic cache, and RAG ingestion. That function type is unchanged
+and remains supported; `toEmbeddingFunction()` converts one into the other.
+
+Two behaviors are guaranteed and differ deliberately from completions. Vectors are returned in input
+order regardless of how the request was split, deduplicated, or served from cache. And an option the
+target model or adapter declares it cannot honor is **refused**, not dropped, because a vector built
+with different dimensions or a different input type is silently incompatible with vectors already in
+a store. An option nothing in the registry describes is still passed through, on the same
+absence-means-unknown rule the completion path uses.
+
+Embedding model entries are registry data, not compatibility guarantees. Bundled dimensions, input
+limits, batch limits, and prices can change in a minor release when a provider changes its lineup,
+and are overridable through `embeddings.models.registry`. Which concrete model an alias such as
+`embed-quality` resolves to can also change in a minor release: the vectors two targets produce are
+not interchangeable, so pin a concrete model whenever a stored index must stay valid across
+upgrades. Provider payloads under `raw` and reported token counts are controlled by the provider.
+
 ## Deprecation process
 
 Deprecated APIs are marked with `@deprecated` in declarations and described in the changelog. Removals

package/CHANGELOG.md

@@ -4,6 +4,152 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 
 ## [Unreleased]
 
+## [1.5.0] - 2026-08-31
+
+Embeddings become a first-class operation. `ai.embed()` gets the routing, caching, batching, budget,
+retry, audit, and metrics that until now only completions had, so embedding spend is visible next to
+completion spend instead of leaving the platform entirely. Everything here is additive.
+
+### Added
+
+- **`ai.embed()` and `ai.embedOne()`.** A provider-neutral embeddings operation family behind
+  `EmbeddingManager`, reached through `ai.embeddings` or the new `nexus-ai-pro/embeddings` subpath.
+  The manager is built on first access, so a runtime that never embeds pays nothing for it.
+- **Adapters for OpenAI, Google, Cohere, Mistral, and Ollama**, plus any OpenAI-compatible
+  `/embeddings` server through `OpenAIEmbeddingProvider`'s `baseUrl` and `providerName`. They are
+  registered automatically from the provider credentials already in `providers`, so a configured
+  chat provider makes `ai.embedOne('text')` work with no embedding-specific configuration. Explicit
+  registration through `registerEmbeddingProvider()` always wins, and auto-registration can be
+  turned off with `embeddings.autoRegisterProviders: false`.
+- **Batching, deduplication, and per-input caching.** A batch larger than the model's limit is split
+  and run with bounded concurrency, and the vectors still come back in input order. Repeated texts
+  within one request are answered by a single provider call, and caching is keyed per input, so a
+  partially repeated batch only sends the texts it has not seen. `meta.batches`, `meta.cachedInputs`,
+  and `meta.deduplicatedInputs` report what actually happened.
+- **Structured usage and numeric cost for embeddings.** `meta.usage` and `meta.cost` reuse the same
+  `TokenUsage` and `ResponseCost` shapes as completions, priced from a new embedding model registry.
+  When a provider reports no token counts — Google's `batchEmbedContents` does not — tokens are
+  estimated locally rather than reported as zero, so a call is never priced at nothing.
+- **An embedding model registry** with dimensions, supported truncation sizes, input limits, batch
+  limits, and prices for eleven models across five providers, with aliases (`auto`, `embed-fast`,
+  `embed-quality`, `embed-multilingual`, `embed-local`) and full override through
+  `embeddings.models.registry`. It is deliberately separate from `KNOWN_MODELS`, because completion
+  routing scores models on context window, output price, and tool support, none of which an
+  embedding model has.
+- **Capability refusal.** An unsupported `dimensions`, `inputType`, `encodingFormat`, or `truncate`
+  value throws `EmbeddingCapabilityError` before the provider call. Embeddings refuse rather than
+  drop: a vector built with different dimensions is silently incompatible with the vectors already
+  in a store, and the mismatch only surfaces later as unexplained retrieval quality loss. An option
+  the registry says nothing about is still passed through, and `providerOptions` reaches the
+  provider body untouched.
+- **`toEmbeddingFunction()`**, which adapts the family to the plain `EmbeddingProvider` function that
+  `MemoryVectorStore`, the semantic cache, and RAG ingestion already accept. An existing vector store
+  gains routing, caching, retry, and metrics without changing its own contract.
+- **`normalize`** for unit-length vectors, applied locally when the provider does not already return
+  them, and reapplied after a locally truncated vector loses its length.
+- **A deterministic `MockEmbeddingProvider`** and `runEmbeddingProviderConformance()`, which checks
+  one vector per input, input order, consistent width, optional determinism, and an honored abort.
+- New subpaths `nexus-ai-pro/embeddings`, `embeddings/adapters`, `embeddings/mock`, and
+  `embeddings/models`.
+
+### Changed
+
+- `RateLimiter.check()` accepts the new structural `RateLimitedRequest` instead of a
+  `CompletionRequest`, so one limiter instance and one budget cover every operation family.
+  `CompletionRequest` still satisfies it, so no call site changes.
+- Coverage rose from 82.6% lines / 68.9% branches / 78.2% functions to 85.7% / 70.9% / 80.8%, with
+  65 new tests. `embeddings/providers.ts`, previously the weakest file in the package at 37% lines,
+  is now at 99%.
+
+### Notes
+
+- Bundled embedding dimensions and prices are defaults, not financial truth; override them through
+  `embeddings.models.registry` when exact numbers matter.
+- Which concrete model an embedding alias resolves to can change in a minor release. Two targets do
+  not produce interchangeable vectors, so pin a concrete model when a stored index must stay valid
+  across upgrades.
+
+## [1.4.0] - 2026-08-25
+
+Request parity and cost truth: the completion request can now express what current models actually
+do, and the response reports what the call really cost. Every addition is an optional field or a new
+union member, so existing code is unaffected.
+
+### Added
+
+- **Provider prompt caching.** `CompletionRequest.cache` selects `off`, `auto`, or `explicit` mode
+  with a `5m` or `1h` lifetime, and `Message.cache` / `ToolDefinition.cache` mark the end of a
+  cacheable prefix. The Anthropic adapter translates marks into `cache_control` breakpoints,
+  respecting the four-breakpoint limit by keeping the deepest marks, and every adapter reports what
+  the provider actually reused.
+- **Reasoning controls.** `CompletionRequest.reasoning` carries `effort`, `maxTokens`, and `summary`.
+  These map to OpenAI `reasoning_effort` and the Responses `reasoning` field, Anthropic extended
+  thinking with a token budget, and Gemini `thinkingConfig`. A new `'reasoning'` `StreamChunk`
+  variant carries reasoning summaries, kept separate from `'text'` so existing consumers that switch
+  on chunk type see no change.
+- **Tool and sampling controls.** `toolChoice`, `parallelToolCalls`, `seed`, `topK`,
+  `frequencyPenalty`, and `presencePenalty` on `CompletionRequest`, mapped per provider.
+- **Structured usage and numeric cost.** `ResponseMeta.usage` reports input, output, cached-read,
+  cached-write, and reasoning tokens; `ResponseMeta.cost` reports a numeric amount with a currency
+  and an `estimated` or `reported` basis. Cached reads and cache writes are priced at their own
+  rates, with a long-lived write costing more than a short-lived one. `models.cachePricing`
+  overrides the bundled multipliers.
+- **Capability negotiation.** `negotiateCompletionRequest()` reconciles a request against the routed
+  model under a `strict`, `warn`, or `off` policy, set through `capabilities.policy` or per request
+  through `capabilityPolicy`. Refused options are reported on `ResponseMeta.capabilityWarnings` and
+  in `plan()` warnings. An option the registry does not mention is passed through: absence means
+  unknown, not unsupported, so an application-registered model is never restricted by fields it does
+  not declare, and `off` guarantees a newer provider feature is never blocked by stale metadata.
+- **Registry provenance.** Model entries accept `verifiedAt` and `source`; `MODEL_ALIAS_METADATA`
+  reports each alias's stage and whether its target floats between releases. `describeModel()`,
+  `checkRegistryFreshness()`, and `assertRegistryFreshness()` make drift visible instead of silent.
+- **Streamed usage on OpenAI.** `stream_options.include_usage` is requested for OpenAI and Azure, so
+  a streamed response reports real tokens and cost rather than zeros. Other OpenAI-compatible
+  servers opt in with the new `streamUsage` provider option.
+- A `nexus-ai-pro/capabilities` subpath for the negotiation API.
+
+### Fixed
+
+- Claude 5 models were declared as non-reasoning. The registry decided extended-thinking support by
+  looking for a `4` in the family name, which is absent from `claude-sonnet-5.0`, `claude-haiku-5.0`,
+  and `claude-fable-5.0`. Support is now derived from the family version, so every release from 3.7
+  onward is reported correctly, together with the thinking budget each model can accept.
+- The Anthropic adapter priced every completion at a hardcoded $0.003/$0.015 per 1k tokens instead of
+  using the model registry, so cost was wrong for every Claude model except one. All adapters now
+  share one pricing path.
+- Streamed Anthropic and Google responses reported zero tokens and `$0.00`. Both now carry the
+  provider's own usage totals on the final chunk.
+- Google reasoning summaries could be concatenated into visible output. Parts marked `thought` are
+  excluded from content and emitted as `'reasoning'` chunks instead.
+- A chat stream that ended without a finish reason produced no `done` chunk, leaving consumers
+  without terminal metadata.
+
+### Changed
+
+- `ResponseMeta.estimatedCost` is deprecated in favor of the numeric `cost` object. It is still
+  populated and stays until the next major release. The metrics path no longer parses money out of
+  its own display string.
+- `ResponseMeta.tokensInput` keeps its original meaning of every prompt token; the uncached share
+  billed at the standard rate is `usage.inputTokens`. Adapters whose provider folds cached tokens
+  into one prompt total subtract them so no token is priced twice.
+- `resolveModel()` no longer merges the bundled and application registries into a new object on each
+  call. It reads both maps directly, which removes a per-request allocation from the hot path;
+  `getModelRegistry()` and `getModelAliases()` are unchanged as the merged views.
+- Coverage gates raised from 70/60/60 to 82% lines, 67% branches, and 73% functions, with new tests
+  for the agent loop, the rules router, the evaluation metric library, and the Google, Ollama, and
+  Cohere adapters. The gates sit a couple of points below the lowest figure the supported Node
+  versions report, because Node 22 and Node 24 do not count functions identically: the same suite
+  measures 78.7% on Node 22 and 75.9% on Node 24. A gate set from one version alone fails on the
+  other.
+
+### Notes
+
+Image operations keep their existing strict capability behavior. An unsupported image option changes
+the artifact that comes back, so silently dropping one is worse than refusing the request; the
+shared policy vocabulary is in place for a future release that revisits this.
+
+## [1.3.0] - 2026-08-17
+
 ### Added
 
 - SMS routing on `updatePhoneNumber`. `UpdatePhoneNumberRequest` now carries `smsUrl`, `smsMethod`,
@@ -120,6 +266,12 @@ Notable changes to this project are recorded here. The format follows [Keep a Ch
 - URL fetching rejects unsafe private-network targets and limits response reads.
 - CLI and audit findings no longer disclose detected secret values.
 
-[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.5.0...HEAD
+[1.5.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.3.0...v1.4.0
+[1.3.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.2.1...v1.3.0
+[1.2.1]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.2.0...v1.2.1
+[1.2.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/releases/tag/v1.0.0
 [0.9.0]: https://github.com/mkhitar-abrahamyan/nexus-ai/releases/tag/v0.9.0

package/README.md

@@ -83,6 +83,7 @@ You can still pass a plain `NexusAIConfig` to `new NexusAI(...)` when you want f
 - estimate tokens and cost before provider calls
 - cache exact or semantically similar prompts
 - add tools, agents, RAG context, evals, batch jobs, and queues
+- embed text through the same routing, caching, batching, budget, retry, and metrics as a completion
 - build persistent realtime voice agents with interruption, live tools, and normalized conversation state
 - keep TypeScript types around every request and response
 
@@ -239,7 +240,112 @@ console.log(plan.fitsContext);
 console.log(plan.warnings);
 ```
 
-`plan()` does not call a provider. It estimates route, token use, context fit, cost, guardrail findings, and warnings.
+`plan()` does not call a provider. It estimates route, token use, context fit, cost, guardrail findings, and warnings, including any option the routed model cannot honor.
+
+### Reasoning
+
+```ts
+const response = await ai.complete({
+  model: 'auto',
+  messages: [{ role: 'user', content: 'Find the bug in this migration plan.' }],
+  reasoning: { effort: 'high', summary: 'auto' },
+});
+
+console.log(response.meta.usage?.reasoningTokens);
+```
+
+`effort` is the portable control. It maps to OpenAI `reasoning_effort` and the Responses `reasoning`
+field, Anthropic extended thinking, and Gemini `thinkingConfig`. Use `reasoning.maxTokens` when you
+want to set a thinking budget directly instead of by level.
+
+Requesting a summary emits `reasoning` stream chunks, which stay separate from visible output:
+
+```ts
+for await (const chunk of ai.stream({ model: 'auto', messages, reasoning: { summary: 'auto' } })) {
+  if (chunk.type === 'reasoning') process.stderr.write(chunk.content ?? '');
+  if (chunk.type === 'text') process.stdout.write(chunk.content ?? '');
+}
+```
+
+### Prompt Caching
+
+Providers charge far less for a prompt prefix they have already processed. `mode: 'auto'` is the
+default and reports whatever the provider reused on its own. `mode: 'explicit'` sends caller-placed
+breakpoints to providers that accept them, such as Anthropic:
+
+```ts
+const response = await ai.complete({
+  model: 'anthropic/best',
+  cache: { mode: 'explicit', ttl: '1h' },
+  messages: [
+    { role: 'system', content: longPolicyDocument, cache: true },
+    { role: 'user', content: 'Does clause 14 apply here?' },
+  ],
+});
+
+console.log(response.meta.usage?.cachedReadTokens);
+console.log(response.meta.cost?.amount);
+```
+
+Mark the end of the stable prefix, not every message. A provider caps how many breakpoints it
+accepts (Anthropic allows four); when there are more marks than slots, the deepest ones are kept,
+because a deeper breakpoint caches strictly more of the prompt.
+
+### Usage and Cost
+
+Every response carries a numeric cost and a full token breakdown:
+
+```ts
+const { usage, cost } = response.meta;
+
+console.log(usage?.inputTokens);        // billed at the standard input rate
+console.log(usage?.cachedReadTokens);   // served from the provider cache
+console.log(usage?.cachedWriteTokens);  // written into the provider cache
+console.log(usage?.reasoningTokens);    // share of output spent on reasoning
+console.log(cost?.amount, cost?.currency, cost?.basis);
+```
+
+`meta.tokensInput` keeps its original meaning of every prompt token, cached or not.
+`meta.estimatedCost` is deprecated in favor of `cost.amount`. Bundled prices are defaults, not
+financial truth; override them with `models.registry`, or adjust cache rates with
+`models.cachePricing`.
+
+### Capability Negotiation
+
+Requests are reconciled against the routed model before the provider is called:
+
+```ts
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  capabilities: { policy: 'warn' }, // 'strict' | 'warn' (default) | 'off'
+});
+
+const response = await ai.complete({ model: 'auto', messages, seed: 7 });
+console.log(response.meta.capabilityWarnings);
+```
+
+- `strict` throws a `NexusCapabilityError` before spending anything.
+- `warn` drops or clamps the option and records it on `meta.capabilityWarnings`.
+- `off` sends the request exactly as written.
+
+An option a model does not declare is always passed through — absence means the registry does not
+know, not that the provider refuses — so a model you register yourself is never restricted by fields
+it omits. Set `capabilityPolicy: 'off'` on a single request to reach a provider feature that is
+newer than the bundled registry.
+
+Registry provenance is inspectable, and a release check can fail on stale data:
+
+```ts
+import { describeModel, assertRegistryFreshness } from 'nexus-ai-pro';
+
+console.log(describeModel('anthropic/best'));
+// { model: 'claude-opus-4-8', verifiedAt: '…', alias: { stage: 'stable', floating: true }, … }
+
+assertRegistryFreshness({ maxAgeDays: 120 });
+```
+
+A `floating` alias resolves by intent rather than to a pinned model, so its target can change between
+releases. Pin the resolved model when a run has to be reproducible.
 
 ### Streaming
 
@@ -254,7 +360,9 @@ for await (const chunk of stream) {
 }
 ```
 
-All providers normalize streaming chunks to `text`, `tool_call`, `done`, or `error`.
+All providers normalize streaming chunks to `text`, `reasoning`, `tool_call`, `done`, or `error`.
+Reasoning summaries only arrive when the request asks for them, so a consumer that switches on
+`chunk.type` keeps receiving visible output only.
 
 When security is enabled, output streams are correctness-first: Nexus buffers and validates the
 complete output before yielding any chunk, up to 1 MiB or 100,000 chunks. This prevents secrets,
@@ -309,6 +417,98 @@ const response = await ai.completeVerified(
 );
 ```
 
+## Embeddings
+
+`ai.embed()` is a first-class operation, not a helper: it gets the same routing, caching, batching,
+budget, retry, audit, and metrics as a completion, so embedding spend shows up next to completion
+spend instead of being invisible.
+
+The smallest call is one line, and needs no embedding-specific configuration — adapters are derived
+from the provider credentials already in `providers`:
+
+```ts
+import { NexusAI } from 'nexus-ai-pro';
+
+const ai = new NexusAI({ providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } } });
+
+const vector = await ai.embedOne('Provider-neutral embeddings.');
+```
+
+A batch returns vectors in input order regardless of how many provider calls the model's batch
+limit required, and reports what the call cost:
+
+```ts
+const response = await ai.embed({
+  input: documents.map((document) => document.text),
+  model: 'embed-quality',
+  inputType: 'document',
+  normalize: true,
+});
+
+response.vectors;                  // number[][], in input order
+response.meta.batches;             // provider calls the split required
+response.meta.usage.inputTokens;   // reported by the provider, or estimated when it reports none
+response.meta.cost.amount;         // numeric, priced from the embedding registry
+response.meta.cachedInputs;        // inputs answered from cache
+response.meta.deduplicatedInputs;  // repeated inputs answered from one call
+```
+
+Caching is per input rather than per request, so a partially repeated batch only sends the texts it
+has not seen. Repeated texts inside one batch are collapsed into a single provider call:
+
+```ts
+const ai = new NexusAI({
+  providers: { openai: { apiKey: process.env.OPENAI_API_KEY! } },
+  embeddings: {
+    cache: { enabled: true, ttlSeconds: 86_400 },
+    costBudget: { enabled: true, maxEstimatedCost: 5 },
+    retry: { enabled: true, maxRetries: 2 },
+    fallback: [{ provider: 'cohere', model: 'embed-v4.0' }],
+  },
+});
+```
+
+Unlike a completion, an unsupported embedding option is **refused rather than dropped**. A vector
+built with different dimensions or a different input type is silently incompatible with the vectors
+already in a store, and the mismatch only surfaces later as unexplained retrieval quality loss:
+
+```ts
+await ai.embed({ input: 'x', model: 'embed-english-v3.0', dimensions: 512 });
+// EmbeddingCapabilityError: model has a fixed size of 1024 dimensions
+```
+
+An option the registry says nothing about is still passed through, because an undeclared capability
+means unknown rather than unsupported, and `providerOptions` reaches the provider body untouched for
+anything the neutral contract does not model yet.
+
+Existing vector stores keep their contract. `toEmbeddingFunction()` adapts the family to the plain
+function `MemoryVectorStore`, the semantic cache, and RAG ingestion already accept:
+
+```ts
+import { MemoryVectorStore, toEmbeddingFunction } from 'nexus-ai-pro';
+
+const store = new MemoryVectorStore(toEmbeddingFunction(ai, { inputType: 'document' }));
+```
+
+Bundled adapters cover OpenAI (and any OpenAI-compatible `/embeddings` server), Google, Cohere,
+Mistral, and Ollama. A custom adapter implements `EmbeddingsProvider` and is checked against the
+neutral contract by `runEmbeddingProviderConformance()`:
+
+```ts
+import { OpenAIEmbeddingProvider } from 'nexus-ai-pro/embeddings/adapters';
+import { MockEmbeddingProvider } from 'nexus-ai-pro/embeddings/mock';
+
+ai.registerEmbeddingProvider('gateway', new OpenAIEmbeddingProvider({
+  apiKey: process.env.GATEWAY_KEY!,
+  baseUrl: 'https://gateway.internal/v1',
+  providerName: 'gateway',
+}));
+ai.registerEmbeddingProvider('mock', new MockEmbeddingProvider());
+```
+
+Bundled embedding dimensions and prices are defaults, not financial truth. Override them through
+`embeddings.models.registry` when exact numbers matter.
+
 ## Image Generation and Editing (Experimental)
 
 Image operations use a separate provider-neutral manager because generated assets have different
@@ -1022,9 +1222,14 @@ import { NexusAI } from 'nexus-ai-pro/core';
 import { createNexusConfig } from 'nexus-ai-pro/config';
 import { TokenOptimizer } from 'nexus-ai-pro/optimizer';
 import { ContextWindowManager } from 'nexus-ai-pro/context';
+import { negotiateCompletionRequest } from 'nexus-ai-pro/capabilities';
 import { guardrailPolicy } from 'nexus-ai-pro/security';
 import { RedisCacheAdapter } from 'nexus-ai-pro/cache';
 import { DeepSeekProvider } from 'nexus-ai-pro/providers/deepseek';
+import { EmbeddingManager } from 'nexus-ai-pro/embeddings';
+import { OpenAIEmbeddingProvider } from 'nexus-ai-pro/embeddings/adapters';
+import { MockEmbeddingProvider } from 'nexus-ai-pro/embeddings/mock';
+import { KNOWN_EMBEDDING_MODELS } from 'nexus-ai-pro/embeddings/models';
 import { ImageManager } from 'nexus-ai-pro/images';
 import { MemoryAssetStore } from 'nexus-ai-pro/images/assets';
 import { MockImageProvider } from 'nexus-ai-pro/images/mock';
@@ -1086,10 +1291,12 @@ npm run test:conformance:real
 
 ## Roadmap
 
-The experimental image foundation now includes portable asset types, `ImageManager`, provider
-capability negotiation, local operation handles, visual-safety hooks, deterministic conformance, and an
-opt-in OpenAI adapter. Durable operations, production asset storage, additional providers, and
-media-specific evaluations remain planned in [ROADMAP.md](./ROADMAP.md).
+1.4.0 closed the completion-request gap: prompt caching, reasoning controls, tool and sampling
+controls, structured usage with numeric cost, and capability negotiation with registry provenance.
+
+Next is durable execution — an operation state machine, provider batch APIs, distributed rate
+limiting and circuit breaking, first-class embeddings, and filesystem/S3 asset stores — followed by
+image portability and promotion out of experimental. See [ROADMAP.md](./ROADMAP.md).
 
 ## Production Notes