nexus-ai-pro 1.4.0 → 1.5.0

package/API_STABILITY.md

@@ -106,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,71 @@ 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
@@ -201,7 +266,8 @@ shared policy vocabulary is in place for a future release that revisits this.
 - 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.4.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

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
 
@@ -416,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
@@ -1133,6 +1226,10 @@ 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';

package/ROADMAP.md

@@ -3,10 +3,11 @@
 This roadmap is a design proposal, not a compatibility promise. Stable and experimental
 surfaces are defined in [API_STABILITY.md](./API_STABILITY.md).
 
-Status baseline: **1.4.0**. 55 export subpaths, 12 completion providers, 99 registry models plus 63
-aliases. 163 unit tests pass; coverage sits at **82.6% lines / 68.9% branches / 78.2% functions**
-against gates of 80/68/75. CI verifies lint, format, build, tests, coverage, mock conformance,
-packed-package smoke, API contract, consumer type resolution, and clean install on Node 22 and 24.
+Status baseline: **1.5.0**. 59 export subpaths, 12 completion providers, 5 embedding providers, 99
+completion registry models plus 63 aliases, and 11 embedding models plus 5 aliases. 234 unit tests
+pass; coverage sits at **85.7% lines / 70.9% branches / 80.8% functions** against gates of
+82/67/73. CI verifies lint, format, build, tests, coverage, mock conformance, packed-package smoke,
+API contract, consumer type resolution, and clean install on Node 22 and 24.
 
 ---
 
@@ -91,7 +92,17 @@ parallel-tool-call, seed, top-k, and penalty controls; structured `usage` with c
 cached-write, and reasoning token counts; numeric `cost` priced per token class; and capability
 negotiation under a `strict`, `warn`, or `off` policy with registry provenance and a freshness check.
 
-### 1.8 Operations, evaluation, and packaging
+### 1.8 Embeddings
+
+Delivered in 1.5.0. `ai.embed()` and `ai.embedOne()` over a provider-neutral `EmbeddingsProvider`
+contract with adapters for OpenAI (and any OpenAI-compatible server), Google, Cohere, Mistral, and
+Ollama, auto-registered from existing provider credentials. Around them: model-registry routing with
+aliases and per-provider fallback, batch splitting with bounded concurrency, within-request
+deduplication, per-input caching, cost budgets, retry, structured usage and numeric cost, capability
+refusal rather than silent option dropping, `toEmbeddingFunction()` for existing vector stores, a
+deterministic mock, and a conformance harness.
+
+### 1.9 Operations, evaluation, and packaging
 
 Rate limiting, audit logging, in-memory and OpenTelemetry metrics sinks, Prometheus export, an
 OpenTelemetry trace exporter, provider health monitoring, `EvalRunner` with LLM-as-judge and a
@@ -107,21 +118,27 @@ trusted publishing with provenance.
 
 Ordered by how much each one costs a consumer today.
 
-### 2.1 Only completions get the platform
+### 2.1 Media families still do not get the platform
+
+Narrowed in 1.5.0: `EmbeddingManager` shares the runtime's rate limiter, audit log, and metrics
+collector, and `RateLimiter` now buckets on a structural request rather than a `CompletionRequest`,
+so a family no longer has to be a completion to be governed. `ImageManager`, `VoiceManager`,
+`TelephonyManager`, and `RealtimeSession` still emit nothing to `MetricsCollector` and pass through
+no rate limit or audit stage, so an application running phone agents and image generation has
+observability for only part of its spend.
 
-The pipeline, rate limiter, audit log, metrics collector, and cost budget are wired into
-`complete()` and `stream()` only. `ImageManager`, `VoiceManager`, `TelephonyManager`, and
-`RealtimeSession` emit nothing to `MetricsCollector` and pass through no rate limit or audit stage.
-An application running phone agents and image generation has observability for the smallest part of
-its spend. `PipelineContext` is also typed strictly around `CompletionRequest`/`NexusResponse`, so
-other families cannot reuse it without a refactor, and `PipelineStepName` ends in `| string`, which
-erases the union it defines.
+The traced pipeline itself remains completion-only. `PipelineContext` is typed strictly around
+`CompletionRequest`/`NexusResponse`, so other families cannot reuse it without a refactor, and
+`PipelineStepName` ends in `| string`, which erases the union it defines. Embeddings therefore share
+the observability primitives but not the step trace.
 
-### 2.2 No first-class embeddings operation
+### 2.2 Embeddings beyond text retrieval
 
-`src/embeddings/providers.ts` exports OpenAI/Gemini/Cohere factory functions used only by the
-semantic cache and vector store. There is no `ai.embed()`, so embeddings get no routing, caching,
-budget, retry, audit, or metrics — and no provider-neutral batch contract.
+Closed for text in 1.5.0: `ai.embed()` is an operation family with routing, per-input caching,
+batching, deduplication, budget, retry, audit, and metrics, over five adapters and its own model
+registry. What remains is everything the family does not yet cover: a provider batch-API tier for
+large asynchronous ingestion jobs, image and multimodal embeddings, a distributed cache adapter for
+vectors shared across processes, and reranking as a sibling operation.
 
 ### 2.3 The model registry is still hand-maintained
 
@@ -160,14 +177,14 @@ local estimate, and a published latency benchmark methodology remain follow-on w
 ### 2.7 Test coverage weak spots
 
 1.4.0 closed the worst of these: the agent loop went from 40% to 95% line coverage, the rules router
-from 34% to 91%, and the evaluation metric library from 40% (5% of functions) to 99%. What is still
-thin:
+from 34% to 91%, and the evaluation metric library from 40% (5% of functions) to 99%. 1.5.0 took
+`embeddings/providers.ts` from 37% to 99% and landed the new embeddings family at 95–100% across its
+seven files. What is still thin:
 
 | Area | Lines | Note |
 | --- | --- | --- |
 | `hallucination/rag.ts`, `verification.ts` | 38% / 47% | Grounding claims deserve tests. |
 | `workflow/chains.ts`, `domain.ts` | 51% / 50% | |
-| `embeddings/providers.ts` | 37% | Should be covered as part of the embeddings operation family. |
 | `security/pii-detector.ts`, `semantic-injection-classifier.ts` | 49% / 49% | Security-relevant. |
 | `jobs/queue.ts`, `batch.ts` | 47% / 53% | |
 | `rag/file-ingestion.ts` | 43% | |
@@ -219,7 +236,18 @@ policy vocabulary is in place for a later release that revisits this.
 
 ---
 
-## 4. Next release: 1.5.0 — durable operations and batch economics
+## 4. Shipped in 1.5.0 — embeddings as an operation family
+
+`ai.embed()` with routing, per-input caching, batching, deduplication, budget, retry, audit, and
+metrics; the existing factory functions became one adapter shape behind it, and
+`toEmbeddingFunction()` keeps `MemoryVectorStore`, the semantic cache, and RAG ingestion working
+unchanged. Embeddings refuse an unsupported option rather than dropping it, because a mis-sized
+vector is silently incompatible with a populated store rather than merely different.
+
+Deliberately deferred: the provider batch-API tier, which belongs with the durable operation handle
+below rather than with the synchronous path.
+
+## 5. Next release: 1.6.0 — durable operations and batch economics
 
 The theme is work that outlives a process.
 
@@ -235,19 +263,17 @@ The theme is work that outlives a process.
 - **Distributed rate limiting and circuit breaking.** Redis-backed limiter adapter, plus a breaker
   that consumes existing `ProviderHealthMonitor` signals and trips routing away from a failing
   provider.
-- **Embeddings as an operation family.** `ai.embed()` with routing, caching, batching, budget, retry,
-  audit, and metrics; existing factories become adapters behind it.
 - **Filesystem and S3-compatible asset stores** implementing the existing `AssetStore` interface,
   with retention, tenant ownership, checksums, streaming, and signing. Provider URLs remain temporary
   delivery locations, never durable storage.
 - **Generated model registry** from versioned provider data, consuming the 1.4.0 provenance fields.
 - **Cross-family observability.** Route image, voice, telephony, and realtime operations through the
-  rate limiter, audit log, and metrics collector, closing gap 2.3 without waiting for the full
+  rate limiter, audit log, and metrics collector, closing gap 2.1 without waiting for the full
   lifecycle refactor.
 
 ---
 
-## 5. 1.6.0 — image portability, then promotion
+## 6. 1.7.0 — image portability, then promotion
 
 Images cannot leave experimental until the neutral contract survives a second wire protocol.
 
@@ -275,7 +301,7 @@ label come off.
 
 ---
 
-## 6. 2.0 candidate — one lifecycle for every operation
+## 7. 2.0 candidate — one lifecycle for every operation
 
 Create an internal typed lifecycle and adapt every family to it:
 
@@ -298,7 +324,7 @@ Also in the 2.0 window, because each requires a breaking change:
 
 ---
 
-## 7. Longer-term backlog
+## 8. Longer-term backlog
 
 1. MCP client and server adapters with asset and tool interoperability.
 2. Video generation through the same asynchronous operation, job, and asset contracts.
@@ -323,7 +349,7 @@ Also in the 2.0 window, because each requires a breaking change:
 
 ---
 
-## 8. Design notes carried forward
+## 9. Design notes carried forward
 
 These decisions predate this revision and still hold.
 
@@ -375,7 +401,7 @@ await ai.images.edit({
 
 ---
 
-## 9. How an item graduates
+## 10. How an item graduates
 
 1. Provider-neutral types and a deterministic mock land first.
 2. One real adapter proves the contract; conformance fixtures cover it.

package/dist/core/nexus.d.ts

@@ -5,11 +5,13 @@ import type { NexusResponse, NexusStream } from '../types/response.js';
 import type { AgentConfig, AgentResult } from '../types/agent.js';
 import type { SpeechRequest, SpeechResponse, TranscriptionRequest, TranscriptionResponse, VoiceProvider, VoiceSessionConfig, VoiceTurnRequest, VoiceTurnResponse } from '../types/voice.js';
 import type { ImageProvider } from '../types/images.js';
+import type { EmbeddingRequest, EmbeddingResponse, EmbeddingsProvider } from '../types/embeddings.js';
 import type { CreateCallRequest, CreateCallResponse, EndCallRequest, GetCallRequest, ListPhoneNumbersRequest, TelephonyCallDetails, TelephonyMediaStreamEvent, TelephonyOutboundAudioMessage, TelephonyPhoneNumber, TelephonyProvider, TelephonyResponseRequest, TelephonyStatusCallback, TelephonyWebhookResponse, TelephonyWebhookValidationRequest, UpdatePhoneNumberRequest } from '../types/telephony.js';
 import type { PipelineStep } from '../pipeline/types.js';
 import type { BaseProvider } from '../providers/base.js';
 import { type VoiceSession } from '../voice/index.js';
 import { ImageManager } from '../images/manager.js';
+import { EmbeddingManager } from '../embeddings/manager.js';
 import { type VerificationOptions } from '../hallucination/verification.js';
 import { type SelfConsistencyOptions } from '../hallucination/consistency.js';
 import { type BatchOptions, type BatchItemResult } from '../jobs/batch.js';
@@ -25,6 +27,7 @@ export declare class NexusAI {
     /** Provider-neutral image generation and editing operations. */
     readonly images: ImageManager;
     private config;
+    private embeddingManager?;
     private providers;
     private router;
     private failover;
@@ -129,6 +132,23 @@ export declare class NexusAI {
      * Points a phone number at a voice webhook and/or status callback.
      */
     updatePhoneNumber(request: UpdatePhoneNumberRequest): Promise<TelephonyPhoneNumber>;
+    /**
+     * Provider-neutral embeddings, sharing this runtime's metrics, audit log, and rate limiter.
+     *
+     * Built on first access, so a runtime that never embeds pays nothing for the family. Adapters are
+     * derived from the provider credentials already in `providers`, which makes `ai.embed('text')`
+     * work without any embedding-specific configuration.
+     */
+    get embeddings(): EmbeddingManager;
+    /**
+     * Embeds one text or a batch through the configured embedding provider.
+     *
+     * `vectors[0]` is the answer for the single-string form; a batch comes back in input order no
+     * matter how many provider calls the model's batch limit required.
+     */
+    embed(request: EmbeddingRequest): Promise<EmbeddingResponse>;
+    /** Embeds one text and returns the vector alone. */
+    embedOne(text: string, options?: Omit<EmbeddingRequest, 'input'>): Promise<number[]>;
     /**
      * Registers a custom text provider at runtime.
      */
@@ -145,10 +165,15 @@ export declare class NexusAI {
      * Registers a custom telephony provider at runtime.
      */
     registerTelephonyProvider(name: string, provider: TelephonyProvider): this;
+    /**
+     * Registers a custom embedding provider at runtime.
+     */
+    registerEmbeddingProvider(name: string, provider: EmbeddingsProvider): this;
     hasProvider(name: string): boolean;
     hasVoiceProvider(name: string): boolean;
     hasImageProvider(name: string): boolean;
     hasTelephonyProvider(name: string): boolean;
+    hasEmbeddingProvider(name: string): boolean;
     /**
      * Lists configured text providers.
      */
@@ -156,6 +181,7 @@ export declare class NexusAI {
     listVoiceProviders(): string[];
     listImageProviders(): string[];
     listTelephonyProviders(): string[];
+    listEmbeddingProviders(): string[];
     /**
      * Adds a custom pipeline step.
      */

package/dist/core/nexus.js

@@ -16,6 +16,7 @@ import { SecurityPipeline } from '../security/index.js';
 import { ContextWindowManager } from '../context/index.js';
 import { VoiceManager } from '../voice/index.js';
 import { ImageManager } from '../images/manager.js';
+import { EmbeddingManager } from '../embeddings/manager.js';
 import { TelephonyManager } from '../telephony/index.js';
 import { TokenOptimizer } from '../optimizer/index.js';
 import { AgentLoop } from '../agent/loop.js';
@@ -47,6 +48,7 @@ export class NexusAI {
     /** Provider-neutral image generation and editing operations. */
     images;
     config;
+    embeddingManager;
     providers = new Map();
     router = new Router();
     failover = new FailoverExecutor();
@@ -506,6 +508,37 @@ export class NexusAI {
     async updatePhoneNumber(request) {
         return this.telephonyManager.updatePhoneNumber(request);
     }
+    /**
+     * Provider-neutral embeddings, sharing this runtime's metrics, audit log, and rate limiter.
+     *
+     * Built on first access, so a runtime that never embeds pays nothing for the family. Adapters are
+     * derived from the provider credentials already in `providers`, which makes `ai.embed('text')`
+     * work without any embedding-specific configuration.
+     */
+    get embeddings() {
+        if (!this.embeddingManager) {
+            this.embeddingManager = new EmbeddingManager(this.config.embeddings || {}, {
+                metrics: this.metrics,
+                auditLogger: this.auditLogger,
+                rateLimiter: this.rateLimiter,
+                providers: this.config.providers,
+            });
+        }
+        return this.embeddingManager;
+    }
+    /**
+     * Embeds one text or a batch through the configured embedding provider.
+     *
+     * `vectors[0]` is the answer for the single-string form; a batch comes back in input order no
+     * matter how many provider calls the model's batch limit required.
+     */
+    embed(request) {
+        return this.embeddings.embed(request);
+    }
+    /** Embeds one text and returns the vector alone. */
+    embedOne(text, options = {}) {
+        return this.embeddings.embedOne(text, options);
+    }
     /**
      * Registers a custom text provider at runtime.
      */
@@ -534,6 +567,13 @@ export class NexusAI {
         this.telephonyManager.registerProvider(name, provider);
         return this;
     }
+    /**
+     * Registers a custom embedding provider at runtime.
+     */
+    registerEmbeddingProvider(name, provider) {
+        this.embeddings.registerEmbeddingProvider(name, provider);
+        return this;
+    }
     hasProvider(name) {
         return this.providers.has(name);
     }
@@ -546,6 +586,9 @@ export class NexusAI {
     hasTelephonyProvider(name) {
         return this.telephonyManager.hasProvider(name);
     }
+    hasEmbeddingProvider(name) {
+        return this.embeddings.hasEmbeddingProvider(name);
+    }
     /**
      * Lists configured text providers.
      */
@@ -561,6 +604,9 @@ export class NexusAI {
     listTelephonyProviders() {
         return this.telephonyManager.listProviders();
     }
+    listEmbeddingProviders() {
+        return this.embeddings.listEmbeddingProviders();
+    }
     /**
      * Adds a custom pipeline step.
      */

package/dist/embeddings/adapters.d.ts

@@ -0,0 +1,66 @@
+import type { EmbeddingProviderCallContext, EmbeddingProviderCapabilities, EmbeddingProviderInfo, EmbeddingProviderRequest, EmbeddingProviderResult, EmbeddingsProvider } from '../types/embeddings.js';
+/**
+ * Hosted embedding adapters.
+ *
+ * They share one file because each is a single request/response mapping over `fetch` with no SDK
+ * and no shared state; splitting them would repeat the HTTP and decoding helpers five times.
+ */
+export interface EmbeddingAdapterOptions {
+    apiKey?: string;
+    baseUrl?: string;
+    model?: string;
+    headers?: Record<string, string>;
+    /** Replaces the global `fetch`, for proxying or tests. */
+    fetch?: typeof fetch;
+}
+/** Options for any server that speaks the OpenAI `/embeddings` protocol. */
+export interface OpenAICompatibleEmbeddingOptions extends EmbeddingAdapterOptions {
+    /** Name this adapter reports and registers under. */
+    providerName?: string;
+    /** Replaces the declared capabilities, for a compatible server with different limits. */
+    capabilities?: Partial<EmbeddingProviderCapabilities>;
+}
+declare abstract class HttpEmbeddingProvider implements EmbeddingsProvider {
+    protected readonly options: EmbeddingAdapterOptions;
+    abstract readonly info: EmbeddingProviderInfo;
+    constructor(options?: EmbeddingAdapterOptions);
+    abstract embed(request: EmbeddingProviderRequest, context: EmbeddingProviderCallContext): Promise<EmbeddingProviderResult>;
+    protected post(url: string, body: unknown, model: string, signal: AbortSignal): Promise<unknown>;
+    protected authHeaders(): Record<string, string>;
+    protected baseUrl(fallback: string): string;
+}
+/**
+ * OpenAI and any OpenAI-compatible `/embeddings` endpoint.
+ *
+ * `baseUrl` points it at Azure OpenAI, a gateway, or a self-hosted server; `model` sets the default
+ * when the request names none.
+ */
+export declare class OpenAIEmbeddingProvider extends HttpEmbeddingProvider {
+    readonly info: EmbeddingProviderInfo;
+    constructor(options?: OpenAICompatibleEmbeddingOptions);
+    embed(request: EmbeddingProviderRequest, context: EmbeddingProviderCallContext): Promise<EmbeddingProviderResult>;
+}
+/** Google Generative Language `batchEmbedContents`. */
+export declare class GoogleEmbeddingProvider extends HttpEmbeddingProvider {
+    readonly info: EmbeddingProviderInfo;
+    constructor(options?: EmbeddingAdapterOptions);
+    protected authHeaders(): Record<string, string>;
+    embed(request: EmbeddingProviderRequest, context: EmbeddingProviderCallContext): Promise<EmbeddingProviderResult>;
+}
+/** Cohere v2 `/embed`. */
+export declare class CohereEmbeddingProvider extends HttpEmbeddingProvider {
+    readonly info: EmbeddingProviderInfo;
+    constructor(options?: EmbeddingAdapterOptions);
+    embed(request: EmbeddingProviderRequest, context: EmbeddingProviderCallContext): Promise<EmbeddingProviderResult>;
+}
+/** Mistral `/v1/embeddings`, which follows the OpenAI request and response shape. */
+export declare class MistralEmbeddingProvider extends OpenAIEmbeddingProvider {
+    constructor(options?: EmbeddingAdapterOptions);
+}
+/** Local Ollama `/api/embed`. */
+export declare class OllamaEmbeddingProvider extends HttpEmbeddingProvider {
+    readonly info: EmbeddingProviderInfo;
+    constructor(options?: EmbeddingAdapterOptions);
+    embed(request: EmbeddingProviderRequest, context: EmbeddingProviderCallContext): Promise<EmbeddingProviderResult>;
+}
+export {};