@nestjs/ai 0.0.1 → 0.0.2

package/README.md

@@ -23,7 +23,7 @@
 
 ## Description
 
-Language models for [Nest](https://github.com/nestjs/nest): named models through dependency injection, model calls with timeouts, retries and fallback models (run on [`@nestjs/resilience`](https://github.com/nestjs/resilience) policies, or your own), budgets and usage events, structured output validated by a schema, the application's own provider methods as agent functions its agents call (through Nest's guards, interceptors, pipes and exception filters, as the user the agent acts for), answers streamed to the browser on Express, Fastify and the Node adapter, and durable agent runs on [`@nestjs/workflows`](https://github.com/nestjs/workflows) (`@nestjs/ai/workflows`) that survive restarts and wait for a person's approval. You write an agent function with `@AgentFunction()`, and the model is offered it as a tool; a method can be an MCP tool too, served by [`@nestjs/mcp`](https://github.com/nestjs/mcp), with its `@Tool()` stacked on it. Comes with a fake model for tests. Built on the [AI SDK](https://ai-sdk.dev) (`ai`) and its provider packages.
+Language models for [Nest](https://github.com/nestjs/nest): named models through dependency injection, model calls with timeouts, retries and fallback models (run on [`@nestjs/resilience`](https://github.com/nestjs/resilience) policies, or your own), budgets and usage events, structured output validated by a schema, the application's own provider methods as agent functions its agents call (through Nest's guards, interceptors, pipes and exception filters, as the user the agent acts for), answers streamed to the browser on Express, Fastify and the Node adapter, and durable agent runs on [`@nestjs/workflows`](https://github.com/nestjs/workflows) (`@nestjs/ai/workflows`) that survive restarts and wait for a person's approval. You write an agent function with `@AgentFunction()`, and the model is offered it as a tool; a method can be an MCP tool too, served by [`@nestjs/mcp`](https://github.com/nestjs/mcp), with its `@Tool()` stacked on it. Embedding models have their own named registry, dependency injection, resilient single and batch calls, and usage events. Comes with fake language and embedding models for tests. Built on the [AI SDK](https://ai-sdk.dev) (`ai`) and its provider packages.
 
 ## Installation
 

package/dist/ai.constants.d.ts

@@ -18,5 +18,13 @@ export declare const AI_PARAMS_METADATA = "__routeArguments__";
 export declare const DEFAULT_MODEL_NAME = "default";
 /** Models that replace configured ones by name, from `@nestjs/ai/testing`'s `overrideModels()`. Internal. */
 export declare const AI_MODEL_OVERRIDES: unique symbol;
+/**
+ * Embedding-model replacements from `@nestjs/ai/testing`'s `overrideEmbeddingModels()`. Internal.
+ */
+export declare const AI_EMBEDDING_MODEL_OVERRIDES: unique symbol;
 /** The injection token of the model called `name`, which `@InjectModel(name)` injects. */
 export declare function getModelToken(name?: string): string;
+/**
+ * The injection token of the embedding model called `name`, independent of language-model names.
+ */
+export declare function getEmbeddingModelToken(name?: string): string;

package/dist/ai.constants.js

@@ -18,7 +18,17 @@ export const AI_PARAMS_METADATA = '__routeArguments__';
 export const DEFAULT_MODEL_NAME = 'default';
 /** Models that replace configured ones by name, from `@nestjs/ai/testing`'s `overrideModels()`. Internal. */
 export const AI_MODEL_OVERRIDES = Symbol('AI_MODEL_OVERRIDES');
+/**
+ * Embedding-model replacements from `@nestjs/ai/testing`'s `overrideEmbeddingModels()`. Internal.
+ */
+export const AI_EMBEDDING_MODEL_OVERRIDES = Symbol('AI_EMBEDDING_MODEL_OVERRIDES');
 /** The injection token of the model called `name`, which `@InjectModel(name)` injects. */
 export function getModelToken(name = DEFAULT_MODEL_NAME) {
     return `nestjs:ai:model:${name}`;
 }
+/**
+ * The injection token of the embedding model called `name`, independent of language-model names.
+ */
+export function getEmbeddingModelToken(name = DEFAULT_MODEL_NAME) {
+    return `nestjs:ai:embedding-model:${name}`;
+}

package/dist/ai.module-definition.d.ts

@@ -6,8 +6,8 @@ export type AiModuleRootOptions = AiModuleOptions & {
     isGlobal?: boolean;
 };
 /**
- * What `forRootAsync()` takes: `modelNames` and `isGlobal` at the top level, and one of `useFactory`, `useClass` or
- * `useExisting` for the options.
+ * What `forRootAsync()` takes: `modelNames`, `embeddingModelNames` and `isGlobal` at the top level, and one of
+ * `useFactory`, `useClass` or `useExisting` for the options.
  */
 export type AiModuleAsyncOptions = ConfigurableModuleAsyncOptions<AiModuleOptions, 'createAiOptions'> & AiModuleStructure & {
     isGlobal?: boolean;

package/dist/ai.module-definition.js

@@ -1,8 +1,9 @@
 import { ConfigurableModuleBuilder, Scope } from '@nestjs/common';
 import { INQUIRER } from '@nestjs/core';
-import { AI_MODULE_OPTIONS, getModelToken } from './ai.constants.js';
+import { AI_MODULE_OPTIONS, getEmbeddingModelToken, getModelToken } from './ai.constants.js';
 import { AiModels } from './models/ai-models.service.js';
-import { requestedModelNames } from './models/model-requests.js';
+import { AiEmbeddingModels } from './models/ai-embedding-models.service.js';
+import { requestedEmbeddingModelNames, requestedModelNames } from './models/model-requests.js';
 export { AI_MODULE_OPTIONS };
 export const { ConfigurableModuleClass, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder({
     moduleName: 'Ai',
@@ -10,7 +11,7 @@ export const { ConfigurableModuleClass, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new
 })
     .setClassMethodName('forRoot')
     .setFactoryMethodName('createAiOptions')
-    .setExtras({ isGlobal: false, modelNames: undefined }, (definition, { isGlobal, modelNames }) => {
+    .setExtras({ isGlobal: false, modelNames: undefined, embeddingModelNames: undefined }, (definition, { isGlobal, modelNames, embeddingModelNames }) => {
     const names = new Set([...(modelNames ?? []), ...requestedModelNames()]);
     // Transient, so that each class that injects a model is known (INQUIRER), and one that asks for a model the
     // module does not configure is named in the error.
@@ -20,11 +21,19 @@ export const { ConfigurableModuleClass, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new
         inject: [AiModels, INQUIRER],
         useFactory: (models, inquirer) => models.injected(name, inquirer),
     }));
+    const embeddingNames = new Set([...(embeddingModelNames ?? []), ...requestedEmbeddingModelNames()]);
+    const embeddingTokens = [...embeddingNames].map((name) => ({
+        provide: getEmbeddingModelToken(name),
+        scope: Scope.TRANSIENT,
+        inject: [AiEmbeddingModels, INQUIRER],
+        useFactory: (models, inquirer) => models.injected(name, inquirer),
+    }));
+    const allTokens = [...tokens, ...embeddingTokens];
     return {
         ...definition,
         global: isGlobal,
-        providers: [...(definition.providers ?? []), ...tokens],
-        exports: [...(definition.exports ?? []), ...tokens.map((provider) => provider.provide)],
+        providers: [...(definition.providers ?? []), ...allTokens],
+        exports: [...(definition.exports ?? []), ...allTokens.map((provider) => provider.provide)],
     };
 })
     .build();

package/dist/ai.module.js

@@ -6,9 +6,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 import { Module } from '@nestjs/common';
 import { DiscoveryModule } from '@nestjs/core';
-import { AI_MODEL_OVERRIDES } from './ai.constants.js';
+import { AI_EMBEDDING_MODEL_OVERRIDES, AI_MODEL_OVERRIDES } from './ai.constants.js';
 import { ConfigurableModuleClass, } from './ai.module-definition.js';
 import { AiModels } from './models/ai-models.service.js';
+import { AiEmbeddingModels } from './models/ai-embedding-models.service.js';
 import { AiService } from './services/ai.service.js';
 import { AiTools } from './tools/ai-tools.service.js';
 /**
@@ -20,7 +21,8 @@ let AiModule = class AiModule extends ConfigurableModuleClass {
     static forRoot(options) {
         // `@InjectModel()` may ask for every model `forRoot()` names.
         const modelNames = Object.keys(options?.models ?? {});
-        return super.forRoot({ ...options, modelNames });
+        const embeddingModelNames = Object.keys(options?.embeddingModels ?? {});
+        return super.forRoot({ ...options, modelNames, embeddingModelNames });
     }
     static forRootAsync(options) {
         return super.forRootAsync(options);
@@ -29,8 +31,15 @@ let AiModule = class AiModule extends ConfigurableModuleClass {
 AiModule = __decorate([
     Module({
         imports: [DiscoveryModule],
-        providers: [AiModels, AiTools, AiService, { provide: AI_MODEL_OVERRIDES, useValue: null }],
-        exports: [AiModels, AiTools, AiService],
+        providers: [
+            AiModels,
+            AiEmbeddingModels,
+            AiTools,
+            AiService,
+            { provide: AI_MODEL_OVERRIDES, useValue: null },
+            { provide: AI_EMBEDDING_MODEL_OVERRIDES, useValue: null },
+        ],
+        exports: [AiModels, AiEmbeddingModels, AiTools, AiService],
     })
 ], AiModule);
 export { AiModule };

package/dist/decorators/index.d.ts

@@ -1,2 +1,3 @@
 export * from './agent-function.decorator.js';
 export * from './inject-model.decorator.js';
+export * from './inject-embedding-model.decorator.js';

package/dist/decorators/index.js

@@ -1,2 +1,3 @@
 export * from './agent-function.decorator.js';
 export * from './inject-model.decorator.js';
+export * from './inject-embedding-model.decorator.js';

package/dist/decorators/inject-embedding-model.decorator.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Injects the configured `EmbeddingModel` called `name` (default `'default'`), for code that calls
+ * `ai` directly. Direct SDK calls do not get `AiService`'s resilience or usage events. An unknown
+ * name fails at startup.
+ *
+ * ```ts
+ * constructor(@InjectEmbeddingModel('documents') private readonly model: EmbeddingModel) {}
+ * ```
+ */
+export declare function InjectEmbeddingModel(name?: string): PropertyDecorator & ParameterDecorator;

package/dist/decorators/inject-embedding-model.decorator.js

@@ -0,0 +1,16 @@
+import { Inject } from '@nestjs/common';
+import { DEFAULT_MODEL_NAME, getEmbeddingModelToken } from '../ai.constants.js';
+import { recordEmbeddingModelRequest } from '../models/model-requests.js';
+/**
+ * Injects the configured `EmbeddingModel` called `name` (default `'default'`), for code that calls
+ * `ai` directly. Direct SDK calls do not get `AiService`'s resilience or usage events. An unknown
+ * name fails at startup.
+ *
+ * ```ts
+ * constructor(@InjectEmbeddingModel('documents') private readonly model: EmbeddingModel) {}
+ * ```
+ */
+export function InjectEmbeddingModel(name = DEFAULT_MODEL_NAME) {
+    recordEmbeddingModelRequest(name);
+    return Inject(getEmbeddingModelToken(name));
+}

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { AiModule } from './ai.module.js';
 export { AI_MODULE_OPTIONS, type AiModuleAsyncOptions, type AiModuleRootOptions, type AiOptionsFactory, } from './ai.module-definition.js';
-export { DEFAULT_MODEL_NAME, getModelToken } from './ai.constants.js';
-export type { AiBudget, AiCallDefaults, AiCallSettings, AiModelDefinition, AiModelPricing, AiModuleOptions, AiModuleStructure, } from './interfaces/index.js';
+export { DEFAULT_MODEL_NAME, getEmbeddingModelToken, getModelToken } from './ai.constants.js';
+export type { AiBudget, AiCallDefaults, AiCallSettings, AiModelDefinition, AiModelPricing, AiModuleOptions, AiModuleStructure, AiResilienceSettings, } from './interfaces/index.js';
 export { AiModels } from './models/ai-models.service.js';
+export { AiEmbeddingModels } from './models/ai-embedding-models.service.js';
 export { AiService } from './services/ai.service.js';
 export { AiTextStream, type AiStreamResponseOptions, type AiUIMessageStreamOptions, } from './runtime/text-stream.js';
-export type { AiCallOptions, AiModelInfo, AiModelReference, AiObjectCallOptions, AiObjectResult, AiSchema, AiStep, AiTextResult, AiToolCall, AiToolChoice, AiToolResult, AiUsage, AiUsageEvent, InferSchemaOutput, } from './interfaces/index.js';
+export type { AiCallOptions, AiEmbeddingCallOptions, AiEmbeddingModelDefinition, AiEmbeddingModelPricing, AiEmbeddingModelReference, AiEmbeddingSettings, AiEmbeddingUsageEvent, AiEmbedManyOptions, AiEmbedManyResult, AiEmbedOptions, AiEmbedResult, AiModelInfo, AiModelReference, AiObjectCallOptions, AiObjectResult, AiSchema, AiStep, AiTextResult, AiToolCall, AiToolChoice, AiToolResult, AiUsage, AiUsageEvent, InferSchemaOutput, } from './interfaces/index.js';
 export * from './decorators/index.js';
 export { AiExecutionContext, type AiContextType } from './context/ai-execution-context.js';
 export { AiTools, type AiToolEntry } from './tools/ai-tools.service.js';

package/dist/index.js

@@ -1,9 +1,10 @@
 // Module and options
 export { AiModule } from './ai.module.js';
 export { AI_MODULE_OPTIONS, } from './ai.module-definition.js';
-export { DEFAULT_MODEL_NAME, getModelToken } from './ai.constants.js';
+export { DEFAULT_MODEL_NAME, getEmbeddingModelToken, getModelToken } from './ai.constants.js';
 // Models and model calls
 export { AiModels } from './models/ai-models.service.js';
+export { AiEmbeddingModels } from './models/ai-embedding-models.service.js';
 export { AiService } from './services/ai.service.js';
 export { AiTextStream, } from './runtime/text-stream.js';
 // Models by injection (`@InjectModel()`); agent functions (`@AgentFunction()`), which the model is offered as tools:

package/dist/interfaces/ai-embedding.interface.d.ts

@@ -0,0 +1,79 @@
+import type { EmbeddingModel, EmbeddingModelUsage, EmbedManyResult, EmbedResult } from 'ai';
+import type { AiResilienceSettings } from './ai-module-options.interface.js';
+import type { AiModelInfo } from './ai-result.interface.js';
+/** Embedding settings, independent of language-model generation defaults. */
+export interface AiEmbeddingSettings extends AiResilienceSettings {
+    /** Provider-specific options, by provider name. */
+    providerOptions?: Record<string, Record<string, any>>;
+    /** HTTP headers sent to the embedding provider. */
+    headers?: Record<string, string>;
+    /** Maximum concurrent SDK batch requests within one `embedMany()` operation. Default 4. */
+    maxParallelCalls?: number;
+}
+/** Price per million input tokens, in the unit used for reported `cost`. */
+export interface AiEmbeddingModelPricing {
+    input: number;
+}
+/** A registered SDK embedding model with its own embedding settings. */
+export interface AiEmbeddingModelDefinition extends AiEmbeddingSettings {
+    model: EmbeddingModel;
+    pricing?: AiEmbeddingModelPricing;
+}
+/** A registered embedding name, or an SDK embedding-model object passed directly to a call. */
+export type AiEmbeddingModelReference = string | Exclude<EmbeddingModel, string>;
+/** Options shared by single and batch embedding calls. */
+export interface AiEmbeddingCallOptions extends AiEmbeddingSettings {
+    /** Name in `embeddingModels` (default `'default'`), or a direct SDK model object. */
+    model?: AiEmbeddingModelReference;
+    /**
+     * Cancels in-flight provider requests and retry backoff. `timeout` covers one provider request,
+     * so this is how to set a deadline for the whole operation (`AbortSignal.timeout(ms)`).
+     */
+    abortSignal?: AbortSignal;
+    /** Names this operation in usage and resilience events. */
+    label?: string;
+    /** Called after a successful operation, after the module's embedding usage listener. */
+    onEmbeddingUsage?: (event: AiEmbeddingUsageEvent) => void | Promise<void>;
+}
+export interface AiEmbedOptions extends AiEmbeddingCallOptions {
+    value: string;
+}
+export interface AiEmbedManyOptions extends AiEmbeddingCallOptions {
+    values: string[];
+}
+/** SDK single-embedding result with the resolved model and attempt count. */
+export interface AiEmbedResult extends EmbedResult {
+    model: AiModelInfo;
+    /** Provider requests made, retries included. */
+    attempts: number;
+    /** Cost of the reported usage; absent without model pricing. */
+    cost?: number;
+}
+/**
+ * SDK batch result, in input order. A failed operation rejects rather than returning partial
+ * results.
+ */
+export interface AiEmbedManyResult extends EmbedManyResult {
+    model: AiModelInfo;
+    /** Provider requests made, retries included. */
+    attempts: number;
+    /** Cost of the reported usage; absent without model pricing. */
+    cost?: number;
+}
+/**
+ * One successful embedding operation. Not a billing ledger: a provider may bill a request that
+ * timed out, and an operation that fails reports nothing, including the requests it completed.
+ * Input contents and output vectors are excluded.
+ */
+export interface AiEmbeddingUsageEvent {
+    operation: 'embed' | 'embedMany';
+    label?: string;
+    model: AiModelInfo;
+    inputCount: number;
+    usage: EmbeddingModelUsage;
+    /** Provider requests made, retries included. */
+    attempts: number;
+    /** Total duration of the operation, including retries and backoff. */
+    durationMs: number;
+    cost?: number;
+}

package/dist/interfaces/ai-embedding.interface.js

@@ -0,0 +1 @@
+export {};

package/dist/interfaces/ai-module-options.interface.d.ts

@@ -1,6 +1,7 @@
 import type { Duration, ResiliencePolicy, RetryOptions } from '@nestjs/resilience';
-import type { LanguageModel } from 'ai';
+import type { EmbeddingModel, LanguageModel } from 'ai';
 import type { AiUsageEvent } from './ai-usage.interface.js';
+import type { AiEmbeddingModelDefinition, AiEmbeddingSettings, AiEmbeddingUsageEvent } from './ai-embedding.interface.js';
 /** Prices per million tokens, in a unit of your choice: what `cost` is reported in. */
 export interface AiModelPricing {
     input: number;
@@ -15,12 +16,12 @@ export interface AiBudget {
     /** In the unit of the models' `pricing`. A model without pricing counts as free. */
     maxCost?: number;
 }
-/** Settings a model, the module's `defaults` and each call can set; the call's win, then the model's. */
-export interface AiCallSettings {
+/** Resilience settings shared by language-model and embedding calls. */
+export interface AiResilienceSettings {
     /**
      * The longest a model call may take to answer: its whole response for `generateText()` and `generateObject()`,
-     * its first chunk for `streamText()`, until its tools start for a step that calls them. Applied to each attempt,
-     * as a `TimeoutPolicy`. Default `'60s'`; `false` for none.
+     * its first chunk for `streamText()`, until its tools start for a step that calls them, one provider request for
+     * an embedding. Applied to each attempt, as a `TimeoutPolicy`. Default `'60s'`; `false` for none.
      */
     timeout?: Duration | false;
     /**
@@ -28,15 +29,19 @@ export interface AiCallSettings {
      * first included), `backoff` (default from `'1s'`, doubling, up to `'30s'`, full jitter), `retryIf`. Retried by
      * default: what the provider marks retryable (408, 409, 429, 5xx and network failures) and timeouts; a
      * `retry-after` the provider sends is honored, and one longer than `backoff.maxDelay` moves on to the fallback.
-     * `false` for none.
+     * An embedding call has no fallback, and retries only the provider request that failed. `false` for none.
      */
     retry?: RetryOptions | false;
     /**
      * A policy of your own (`ResiliencePolicy.wrap(breaker, retry, timeout)`), or the name of a preset of
      * `ResilienceService` (`ResilienceModule.forRoot({ presets })`), in place of `retry` and `timeout`: a circuit
-     * breaker or a bulkhead shared with the rest of the application. Fallback models are applied around it.
+     * breaker or a bulkhead shared with the rest of the application. Fallback models are applied around it. An
+     * embedding call runs it around each provider request, so a bulkhead or a rate limit counts requests.
      */
     resilience?: ResiliencePolicy | string;
+}
+/** Settings a language model, the module's `defaults` and each call can set; the call's win, then the model's. */
+export interface AiCallSettings extends AiResilienceSettings {
     /** Generation settings passed to the model. */
     maxOutputTokens?: number;
     temperature?: number;
@@ -51,7 +56,7 @@ export interface AiModelDefinition extends AiCallSettings {
     /** The models tried, in order, when this one fails after its retries: names of other models. */
     fallback?: string | string[];
 }
-/** Defaults for every call. `maxSteps` and `budget` are also those of durable runs (`AiAgents.run()`). */
+/** Defaults for language-model calls. `maxSteps` and `budget` are also those of durable runs (`AiAgents.run()`). */
 export interface AiCallDefaults extends AiCallSettings {
     /** Model calls one call may make while the model asks for tools. Default 10 (25 for a durable run). */
     maxSteps?: number;
@@ -64,10 +69,22 @@ export interface AiModuleOptions {
      * `'openai/gpt-5'`), or a definition with its pricing, fallback and settings. Calls that name no model use
      * `default`.
      */
-    models: Record<string, LanguageModel | AiModelDefinition>;
+    models?: Record<string, LanguageModel | AiModelDefinition>;
     defaults?: AiCallDefaults;
+    /**
+     * Named embedding models, independent of `models`. At least one of the two registries must be
+     * nonempty.
+     */
+    embeddingModels?: Record<string, EmbeddingModel | AiEmbeddingModelDefinition>;
+    /**
+     * Embedding-only defaults. They do not inherit generation settings, headers or options from
+     * `defaults`.
+     */
+    embeddingDefaults?: AiEmbeddingSettings;
     /** Called after every model call that answered, with its tokens and cost. Errors it throws are logged. */
     onUsage?: (event: AiUsageEvent) => void | Promise<void>;
+    /** Called once after a successful embedding operation. Errors it throws are logged. */
+    onEmbeddingUsage?: (event: AiEmbeddingUsageEvent) => void | Promise<void>;
     /**
      * The modules whose providers are searched for agent functions (`@AgentFunction()` methods). Default: every module
      * of the application.
@@ -81,6 +98,11 @@ export interface AiModuleStructure {
      * classes the module's file imports): for classes loaded later, such as lazily loaded modules.
      */
     modelNames?: string[];
+    /**
+     * Embedding-model counterpart of `modelNames`, for injection sites loaded after module
+     * definition.
+     */
+    embeddingModelNames?: string[];
 }
 /** What a class passed to `forRootAsync({ useClass })` implements. */
 export interface AiOptionsFactory {

package/dist/interfaces/ai-result.interface.d.ts

@@ -2,7 +2,10 @@ import type { FinishReason, ModelMessage } from 'ai';
 import type { AiUsage } from './ai-usage.interface.js';
 /** Which model answered. */
 export interface AiModelInfo {
-    /** Its name in `forRoot({ models })`; `undefined` for a `LanguageModel` passed to the call. */
+    /**
+     * Its name in `models` or `embeddingModels`; `undefined` for an SDK model object passed directly
+     * to the call.
+     */
     name?: string;
     provider: string;
     modelId: string;

package/dist/interfaces/index.d.ts

@@ -1,5 +1,6 @@
 export * from './agent-function.interface.js';
 export * from './ai-call-options.interface.js';
+export * from './ai-embedding.interface.js';
 export * from './ai-module-options.interface.js';
 export * from './ai-result.interface.js';
 export * from './ai-schema.interface.js';

package/dist/interfaces/index.js

@@ -1,5 +1,6 @@
 export * from './agent-function.interface.js';
 export * from './ai-call-options.interface.js';
+export * from './ai-embedding.interface.js';
 export * from './ai-module-options.interface.js';
 export * from './ai-result.interface.js';
 export * from './ai-schema.interface.js';

package/dist/models/ai-embedding-models.service.d.ts

@@ -0,0 +1,31 @@
+import type { EmbeddingModel } from 'ai';
+import type { AiEmbeddingModelPricing, AiEmbeddingModelReference, AiEmbeddingSettings } from '../interfaces/ai-embedding.interface.js';
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+import type { AiModelInfo } from '../interfaces/ai-result.interface.js';
+/** One resolved embedding model. Internal; embedding calls never switch to fallback models. */
+export interface ResolvedEmbeddingModel {
+    info: AiModelInfo;
+    model: EmbeddingModel;
+    pricing?: AiEmbeddingModelPricing;
+    settings: AiEmbeddingSettings;
+}
+/** The configured embedding models, independent of language-model names. */
+export declare class AiEmbeddingModels {
+    private readonly models;
+    constructor(options: AiModuleOptions, overrides?: Record<string, EmbeddingModel> | null);
+    names(): string[];
+    /** The SDK model, for direct calls without `AiService`'s resilience or usage events. */
+    get(name?: string): EmbeddingModel;
+    has(name: string): boolean;
+    /**
+     * @internal What `@InjectEmbeddingModel()` injects; unknown names fail during module
+     * initialization.
+     */
+    injected(name: string, inquirer: unknown): EmbeddingModel;
+    /**
+     * @internal Resolves a name or an SDK object. Direct objects have no registered settings or
+     * pricing.
+     */
+    resolve(reference: AiEmbeddingModelReference | undefined): ResolvedEmbeddingModel;
+    private known;
+}

package/dist/models/ai-embedding-models.service.js

@@ -0,0 +1,138 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable, Optional } from '@nestjs/common';
+import { AI_EMBEDDING_MODEL_OVERRIDES, AI_MODULE_OPTIONS, DEFAULT_MODEL_NAME, } from '../ai.constants.js';
+import { AiConfigurationError } from '../errors/ai.errors.js';
+import { assertModelRegistries } from './model-registry.util.js';
+/** The configured embedding models, independent of language-model names. */
+let AiEmbeddingModels = class AiEmbeddingModels {
+    constructor(options, overrides) {
+        this.models = new Map();
+        assertModelRegistries(options);
+        assertSettings(options.embeddingDefaults, 'AiModule: `embeddingDefaults`');
+        for (const [name, entry] of Object.entries(options.embeddingModels ?? {})) {
+            const { model, pricing, ...settings } = isDefinition(entry) ? entry : { model: entry };
+            assertModel(model, `AiModule: the embedding model "${name}"`);
+            assertSettings(settings, `AiModule: the embedding model "${name}"`);
+            if (pricing !== undefined &&
+                (typeof pricing !== 'object' ||
+                    pricing === null ||
+                    !Number.isFinite(pricing.input) ||
+                    pricing.input < 0)) {
+                throw new AiConfigurationError(`AiModule: the embedding model "${name}" pricing.input must be ` +
+                    'a finite nonnegative number.');
+            }
+            const used = overrides?.[name] ?? model;
+            assertModel(used, `AiModule: the replacement embedding model "${name}"`);
+            this.models.set(name, {
+                info: { name, ...identify(used) },
+                model: used,
+                ...(pricing !== undefined && { pricing }),
+                settings,
+            });
+        }
+        for (const name of Object.keys(overrides ?? {})) {
+            if (!this.models.has(name)) {
+                throw new AiConfigurationError(`overrideEmbeddingModels(): there is no embedding model "${name}" to override. ` +
+                    this.known());
+            }
+        }
+    }
+    names() {
+        return [...this.models.keys()];
+    }
+    /** The SDK model, for direct calls without `AiService`'s resilience or usage events. */
+    get(name = DEFAULT_MODEL_NAME) {
+        return this.resolve(name).model;
+    }
+    has(name) {
+        return this.models.has(name);
+    }
+    /**
+     * @internal What `@InjectEmbeddingModel()` injects; unknown names fail during module
+     * initialization.
+     */
+    injected(name, inquirer) {
+        const resolved = this.models.get(name);
+        if (!resolved) {
+            const requester = inquirer?.constructor
+                ?.name;
+            throw new AiConfigurationError(`${requester ? `${requester}: ` : ''}@InjectEmbeddingModel('${name}') ` +
+                'asks for an embedding model AiModule does not configure. ' +
+                `${this.known()} Add "${name}" to \`embeddingModels\` ` +
+                '(in forRootAsync(), to what the factory returns).');
+        }
+        return resolved.model;
+    }
+    /**
+     * @internal Resolves a name or an SDK object. Direct objects have no registered settings or
+     * pricing.
+     */
+    resolve(reference) {
+        if (reference === undefined || typeof reference === 'string') {
+            const name = reference ?? DEFAULT_MODEL_NAME;
+            const resolved = this.models.get(name);
+            if (!resolved) {
+                throw new AiConfigurationError(`There is no embedding model named "${name}". ${this.known()}`);
+            }
+            return resolved;
+        }
+        assertModel(reference, 'The embedding `model` option');
+        return { info: identify(reference), model: reference, settings: {} };
+    }
+    known() {
+        return `Configured embedding models: ${this.names().join(', ')}.`;
+    }
+};
+AiEmbeddingModels = __decorate([
+    Injectable(),
+    __param(0, Inject(AI_MODULE_OPTIONS)),
+    __param(1, Optional()),
+    __param(1, Inject(AI_EMBEDDING_MODEL_OVERRIDES)),
+    __metadata("design:paramtypes", [Object, Object])
+], AiEmbeddingModels);
+export { AiEmbeddingModels };
+function isDefinition(entry) {
+    return (typeof entry === 'object' &&
+        entry !== null &&
+        'model' in entry &&
+        !('specificationVersion' in entry));
+}
+function assertModel(model, where) {
+    const valid = (typeof model === 'string' && model.length > 0) ||
+        (typeof model === 'object' &&
+            model !== null &&
+            typeof model.doEmbed === 'function');
+    if (!valid) {
+        throw new AiConfigurationError(`${where} is not an embedding model. ` +
+            'Pass an embedding model from an AI SDK provider package.');
+    }
+}
+function assertSettings(settings, where) {
+    if (settings === undefined) {
+        return;
+    }
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+        throw new AiConfigurationError(`${where} must contain embedding settings.`);
+    }
+    if (settings.maxParallelCalls !== undefined &&
+        (!Number.isSafeInteger(settings.maxParallelCalls) || settings.maxParallelCalls < 1)) {
+        throw new AiConfigurationError(`${where} maxParallelCalls must be a finite positive safe integer.`);
+    }
+}
+/** Registered string ids are resolved by the SDK's default gateway provider. */
+function identify(model) {
+    return typeof model === 'string'
+        ? { provider: 'gateway', modelId: model }
+        : { provider: model.provider, modelId: model.modelId };
+}

package/dist/models/ai-models.service.js

@@ -13,14 +13,13 @@ var __param = (this && this.__param) || function (paramIndex, decorator) {
 import { Inject, Injectable, Optional } from '@nestjs/common';
 import { AiConfigurationError } from '../errors/ai.errors.js';
 import { AI_MODEL_OVERRIDES, AI_MODULE_OPTIONS, DEFAULT_MODEL_NAME } from '../ai.constants.js';
+import { assertModelRegistries } from './model-registry.util.js';
 /** The configured models, by name. */
 let AiModels = class AiModels {
     constructor(options, overrides) {
         this.models = new Map();
-        const models = options?.models;
-        if (typeof models !== 'object' || models === null || Object.keys(models).length === 0) {
-            throw new AiConfigurationError('AiModule: `models` must name at least one model, e.g. { default: anthropic("claude-opus-5-5") }.');
-        }
+        assertModelRegistries(options);
+        const models = options.models ?? {};
         for (const [name, entry] of Object.entries(models)) {
             const { model, pricing, fallback, ...settings } = isDefinition(entry) ? entry : { model: entry };
             assertModel(model, `AiModule: the model "${name}"`);

package/dist/models/model-registry.util.d.ts

@@ -0,0 +1,6 @@
+import type { AiModuleOptions } from '../interfaces/ai-module-options.interface.js';
+/**
+ * Checks registry structure without contacting a provider. Either kind may be omitted, but not
+ * both.
+ */
+export declare function assertModelRegistries(options: AiModuleOptions): void;

package/dist/models/model-registry.util.js

@@ -0,0 +1,21 @@
+import { AiConfigurationError } from '../errors/ai.errors.js';
+/**
+ * Checks registry structure without contacting a provider. Either kind may be omitted, but not
+ * both.
+ */
+export function assertModelRegistries(options) {
+    let count = 0;
+    for (const key of ['models', 'embeddingModels']) {
+        const entries = options?.[key];
+        if (entries === undefined) {
+            continue;
+        }
+        if (typeof entries !== 'object' || entries === null || Array.isArray(entries)) {
+            throw new AiConfigurationError(`AiModule: \`${key}\` must be a record of named models.`);
+        }
+        count += Object.keys(entries).length;
+    }
+    if (count === 0) {
+        throw new AiConfigurationError('AiModule: configure at least one model in `models` or `embeddingModels`.');
+    }
+}

package/dist/models/model-requests.d.ts

@@ -1,2 +1,5 @@
 export declare function recordModelRequest(name: string): void;
 export declare function requestedModelNames(): string[];
+/** Embedding injection requests use a separate namespace, even when the names are identical. */
+export declare function recordEmbeddingModelRequest(name: string): void;
+export declare function requestedEmbeddingModelNames(): string[];