@mgvdev/nestjs-ai 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1441 @@
+import { DynamicModule, OnModuleInit, Type, NestInterceptor, ExecutionContext, CallHandler, OnModuleDestroy } from '@nestjs/common';
+import { A as AiModuleOptions, a as AiModuleAsyncOptions, b as AiFeatureOptions, P as PromptRef, c as PromptDefinition, U as UsageLike } from './ai-module-options.interface-B5X4AFLC.cjs';
+export { C as ConversationStoreProvider, D as DEFAULT_PRICING, M as ModelPricing, d as PricingTable, e as ProviderConfig, f as ProvidersConfig, g as bareModelId, h as costOf, i as interpolate } from './ai-module-options.interface-B5X4AFLC.cjs';
+import * as ai from 'ai';
+import { LanguageModel, EmbeddingModel, ImageModel, RerankingModel, SpeechModel, TranscriptionModel, StepResult, LanguageModelUsage, FinishReason, Tool as Tool$1, ToolSet, generateText, streamText, generateObject, streamObject, LanguageModelMiddleware } from 'ai';
+import { DiscoveryService, MetadataScanner, Reflector } from '@nestjs/core';
+import { ZodType } from 'zod';
+import { A as AiMessage, a as AiInput, C as ConversationStore } from './conversation-store.interface-CtQY-qcc.cjs';
+export { t as toMessages } from './conversation-store.interface-CtQY-qcc.cjs';
+import { A as AgentRegistry } from './stream-to-socket-fJphU0WN.cjs';
+export { a as AgentEntry, S as SocketLike, b as StreamToSocketOptions, T as TextStreamLike, s as streamAgentToSocket } from './stream-to-socket-fJphU0WN.cjs';
+import { LanguageModelV3 } from '@ai-sdk/provider';
+import { ServerResponse } from 'node:http';
+import { Observable } from 'rxjs';
+
+/**
+ * Root module for `@mgvdev/nestjs-ai`. Registered globally so agents, tools and
+ * services are available everywhere once configured.
+ */
+declare class AiModule {
+    /** Configure the module with static options. */
+    static forRoot(options?: AiModuleOptions): DynamicModule;
+    /** Configure the module asynchronously (e.g. from `ConfigService`). */
+    static forRootAsync(options: AiModuleAsyncOptions): DynamicModule;
+    /**
+     * Convenience registration of agents / tools / guardrails so they don't have
+     * to be added to a consuming module's own `providers` array, plus feature
+     * prompts. Discovery still finds providers globally regardless of where they
+     * are registered.
+     */
+    static forFeature(feature?: AiFeatureOptions): DynamicModule;
+    private static build;
+    private static coreProviders;
+    /**
+     * Registers an optional provider (class / factory / value / useClass shape)
+     * under `token`, or nothing when not configured.
+     */
+    private static tokenProvider;
+    private static exportedTokens;
+    private static guardrailClasses;
+    /** Seeds prompts (and future startup wiring) once dependencies exist. */
+    private static initializerProvider;
+    /**
+     * Optionally resolves `EventEmitter2` from `@nestjs/event-emitter` if the
+     * package is installed and its module is imported; otherwise `undefined`.
+     */
+    private static eventEmitterProvider;
+    private static storeProvider;
+    private static vectorStoreProvider;
+}
+
+/**
+ * Dependency-injection tokens used across the module.
+ */
+declare const AI_MODULE_OPTIONS: unique symbol;
+declare const CONVERSATION_STORE: unique symbol;
+declare const VECTOR_STORE: unique symbol;
+declare const AI_CACHE: unique symbol;
+declare const APPROVAL_GATE: unique symbol;
+declare const AGENT_QUEUE: unique symbol;
+declare const RATE_LIMITER: unique symbol;
+declare const RERANKER: unique symbol;
+/**
+ * Default number of tool-calling steps allowed before an agent run stops.
+ */
+declare const DEFAULT_MAX_STEPS = 5;
+
+/**
+ * Pluggable cache for language-model responses and embeddings. Implement this
+ * (e.g. Redis) and register it via `AiModule.forRoot({ cache })`.
+ */
+interface AiCache {
+    /** Returns the cached value, or `undefined` on a miss / expiry. */
+    get(key: string): Promise<unknown | undefined>;
+    /** Stores a value with an optional time-to-live in milliseconds. */
+    set(key: string, value: unknown, ttlMs?: number): Promise<void>;
+}
+
+/**
+ * Instantiates and caches the configured `@ai-sdk/*` providers, and resolves
+ * `"provider:model"` strings into concrete language / embedding models.
+ *
+ * Provider packages are imported lazily on module init so only the SDKs a
+ * project actually configures need to be installed.
+ */
+declare class ProviderRegistry implements OnModuleInit {
+    private readonly options;
+    private readonly cache?;
+    private readonly providers;
+    constructor(options: AiModuleOptions, cache?: AiCache | undefined);
+    /** Wraps a model with the cache middleware when a cache is configured. */
+    private applyCache;
+    onModuleInit(): Promise<void>;
+    /**
+     * Resolves a language model. Accepts a `LanguageModel` instance (returned
+     * as-is), a `"provider:model"` string, a bare `"model"` string (using the
+     * default provider), or `undefined` (using `defaultModel`).
+     */
+    getLanguageModel(model?: string | LanguageModel | Array<string | LanguageModel>): LanguageModel;
+    /** Resolves a single (non-array) model reference without cache wrapping. */
+    private resolveSingle;
+    /**
+     * Resolves an embedding model from a `"provider:model"` string, a bare model
+     * string, an `EmbeddingModel` instance, or `undefined` (using
+     * `defaultEmbeddingModel`).
+     */
+    getEmbeddingModel(model?: string | EmbeddingModel): EmbeddingModel;
+    /** Resolves an image-generation model (default `defaultImageModel`). */
+    getImageModel(model?: string | ImageModel): ImageModel;
+    /** Resolves a reranking model (default `rerankingModel` option). */
+    getRerankingModel(model?: string | RerankingModel): RerankingModel;
+    /** Resolves a speech (text-to-speech) model (default `defaultSpeechModel`). */
+    getSpeechModel(model?: string | SpeechModel): SpeechModel;
+    /** Resolves a transcription (speech-to-text) model. */
+    getTranscriptionModel(model?: string | TranscriptionModel): TranscriptionModel;
+    /**
+     * Shared resolution for multimodal models: resolves the provider, then calls
+     * the first available factory method (standard name, then shorthand).
+     */
+    private resolveMultimodal;
+    private resolve;
+    private parseProviderName;
+    private parseModelId;
+    private initProvider;
+}
+
+/** Minimal shape of `EventEmitter2` from `@nestjs/event-emitter`. */
+interface EventEmitterLike {
+    emit(event: string, payload: unknown): boolean;
+}
+/** Injection token for an optional event emitter (EventEmitter2). */
+declare const EVENT_EMITTER: unique symbol;
+/**
+ * Emits library events through `@nestjs/event-emitter`'s `EventEmitter2` when
+ * it is available, and is a no-op otherwise. This keeps `@nestjs/event-emitter`
+ * a truly optional peer dependency.
+ */
+declare class AiEventEmitter {
+    private readonly emitter?;
+    constructor(emitter?: EventEmitterLike | undefined);
+    emit(event: string, payload: unknown): void;
+    /** Whether an underlying emitter is wired up. */
+    get enabled(): boolean;
+}
+
+/**
+ * Per-call overrides for an agent `.run()` / `.stream()`.
+ */
+interface AgentRunOptions {
+    /** Override the agent's model for this call. Array = fallback chain. */
+    model?: string | string[];
+    /** Retry count forwarded to the underlying generate/stream call. */
+    maxRetries?: number;
+    /** Override the agent's system prompt for this call. */
+    system?: string;
+    /** Resolve the system prompt from the PromptRegistry (overrides `system`). */
+    systemPrompt?: PromptRef;
+    /**
+     * Recall relevant snippets from semantic memory and prepend them as context.
+     * Requires `conversationId` and a `SemanticMemory` service.
+     */
+    recall?: {
+        query?: string;
+        topK?: number;
+    };
+    /**
+     * Conversation id. When set, prior messages are loaded from the
+     * `ConversationStore` before the call and the new exchange is persisted after.
+     */
+    conversationId?: string;
+    /** Override the maximum tool-calling steps. */
+    maxSteps?: number;
+    /** Structured-output schema for this call (overrides the agent's `output`). */
+    schema?: ZodType<any, any, any>;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Abort signal to cancel the underlying request. */
+    abortSignal?: AbortSignal;
+}
+/**
+ * Result of an agent `.run()`.
+ */
+interface AgentResult<T = unknown> {
+    /** Generated text (empty string for structured-output runs). */
+    text: string;
+    /** Parsed structured object, present only for structured-output runs. */
+    object?: T;
+    /** Per-step details for multi-step tool runs. */
+    steps?: StepResult<any>[];
+    /** Tool calls made during the run. */
+    toolCalls?: unknown[];
+    /** Aggregate token usage across all steps. */
+    usage?: LanguageModelUsage;
+    /** Why generation stopped. */
+    finishReason?: FinishReason;
+    /** Assistant/tool messages produced by the run. */
+    messages: AiMessage[];
+}
+
+/** Mutable context passed to guardrails before an agent run. */
+interface GuardrailContext {
+    agent: string;
+    /** Messages to be sent; a guardrail may mutate this array in place. */
+    messages: AiMessage[];
+    options: AgentRunOptions;
+}
+/**
+ * A guardrail can inspect, mutate, or block agent runs and tool calls. Throw
+ * from any hook to abort the run. Register guardrails via
+ * `AiModule.forRoot({ guardrails })` or `forFeature({ guardrails })`.
+ */
+interface Guardrail$1 {
+    /** Runs before generation. Mutate `ctx.messages` or throw to block. */
+    beforeRun?(ctx: GuardrailContext): void | Promise<void>;
+    /** Runs after generation with the result. */
+    afterRun?(ctx: GuardrailContext, result: AgentResult): void | Promise<void>;
+    /** Runs before a tool executes. Throw to block the tool call. */
+    onToolCall?(tool: string, args: unknown): void | Promise<void>;
+}
+
+/**
+ * Collects all `@Guardrail`-decorated providers and runs their hooks in
+ * registration order around agent execution.
+ */
+declare class GuardrailRegistry implements OnModuleInit {
+    private readonly discovery;
+    private readonly guardrails;
+    constructor(discovery: DiscoveryService);
+    onModuleInit(): void;
+    get count(): number;
+    runBeforeRun(ctx: GuardrailContext): Promise<void>;
+    runAfterRun(ctx: GuardrailContext, result: AgentResult): Promise<void>;
+    runOnToolCall(tool: string, args: unknown): Promise<void>;
+}
+
+/** Context passed to an approval gate for a tool call awaiting approval. */
+interface ApprovalContext {
+    tool: string;
+    args: unknown;
+    /** Name of the agent making the call, when available. */
+    agent?: string;
+}
+/**
+ * Decides whether a tool flagged `requiresApproval` may execute. Implement this
+ * to plug in human-in-the-loop approval (e.g. block on a queue, check a policy)
+ * and register it via `AiModule.forRoot({ approvalGate })`.
+ */
+interface ApprovalGate {
+    /** Resolve `true` to allow the tool call, `false` to block it. */
+    requestApproval(context: ApprovalContext): Promise<boolean>;
+}
+/** Thrown when an approval gate denies a tool call. */
+declare class ToolApprovalDeniedError extends Error {
+    readonly tool: string;
+    constructor(tool: string);
+}
+
+/** A discovered tool together with the class that declared it. */
+interface ToolEntry {
+    name: string;
+    tool: Tool$1<any, any>;
+    target: Type<any>;
+}
+/** A tool reference accepted by `buildToolSet`: a provider class or a name. */
+type ToolRef = Type<any> | string;
+/**
+ * Discovers every `@Tool`-decorated method across the application's providers
+ * and wraps each into a Vercel AI SDK `tool()` whose `execute` calls the method
+ * on its DI-managed instance (preserving `this` and injected dependencies).
+ */
+declare class ToolRegistry implements OnModuleInit {
+    private readonly discovery;
+    private readonly scanner;
+    private readonly reflector;
+    private readonly events?;
+    private readonly guardrails?;
+    private readonly approvalGate?;
+    private readonly agentRegistry?;
+    private readonly tools;
+    constructor(discovery: DiscoveryService, scanner: MetadataScanner, reflector: Reflector, events?: AiEventEmitter | undefined, guardrails?: GuardrailRegistry | undefined, approvalGate?: ApprovalGate | undefined, agentRegistry?: AgentRegistry | undefined);
+    onModuleInit(): void;
+    private register;
+    /** Returns the tool registered under `name`, if any. */
+    getByName(name: string): ToolEntry | undefined;
+    /** Returns every tool declared by the given provider class. */
+    getForClass(target: Type<any>): ToolEntry[];
+    /** Returns all discovered tools. */
+    getAll(): ToolEntry[];
+    /**
+     * Builds the `ToolSet` passed to `generateText`/`streamText` from a list of
+     * tool references (provider classes and/or tool names). Passing no refs
+     * returns every discovered tool.
+     */
+    buildToolSet(refs?: ToolRef[]): ToolSet;
+    private resolveRef;
+    private resolveAgentRef;
+}
+
+/** Replaces `model` (a resolvable id) and `tools` (tool refs) on SDK params. */
+type NestAiParams<Fn extends (arg: any) => any> = Omit<Parameters<Fn>[0], 'model' | 'tools'> & {
+    /** Model id string (e.g. `"openai:gpt-4o"`); defaults to the module model. */
+    model?: string;
+    /** Tool references (provider classes and/or names) to expose to the model. */
+    tools?: ToolRef[];
+};
+/**
+ * Thin, DI-friendly facade over the Vercel AI SDK generation functions for
+ * callers that don't want to declare an `@Agent` class. Resolves `model`
+ * strings and `tools` references, then forwards everything else unchanged.
+ */
+declare class AiService {
+    private readonly providers;
+    private readonly toolRegistry;
+    constructor(providers: ProviderRegistry, toolRegistry: ToolRegistry);
+    generateText(params: NestAiParams<typeof generateText>): ReturnType<typeof generateText>;
+    streamText(params: NestAiParams<typeof streamText>): ReturnType<typeof streamText>;
+    generateObject(params: NestAiParams<typeof generateObject>): ReturnType<typeof generateObject>;
+    streamObject(params: NestAiParams<typeof streamObject>): ReturnType<typeof streamObject>;
+    private resolve;
+}
+
+/**
+ * Options accepted by the `@Tool` decorator.
+ */
+interface ToolOptions {
+    /** Tool name exposed to the model. Defaults to the method name. */
+    name?: string;
+    /** Human-readable description the model uses to decide when to call it. */
+    description: string;
+    /** Zod schema describing the tool's input arguments. */
+    schema: ZodType<any, any, any>;
+    /** Require approval from the configured `ApprovalGate` before executing. */
+    requiresApproval?: boolean;
+}
+/**
+ * Metadata stored on a `@Tool`-decorated method.
+ */
+interface ToolMetadata extends ToolOptions {
+    methodName: string;
+}
+
+/**
+ * Marks a method of an injectable provider as an AI tool (a.k.a. function
+ * call). The method receives the validated arguments (typed by the Zod
+ * `schema`) and its return value is fed back to the model.
+ *
+ * Because the owning class is a normal NestJS provider, the method keeps full
+ * access to injected dependencies.
+ *
+ * @example
+ * ```ts
+ * @Injectable()
+ * class WeatherTools {
+ *   constructor(private readonly api: WeatherApi) {}
+ *
+ *   @Tool({ description: 'Get the weather for a city', schema: z.object({ city: z.string() }) })
+ *   getWeather({ city }: { city: string }) {
+ *     return this.api.lookup(city);
+ *   }
+ * }
+ * ```
+ */
+declare function Tool(options: ToolOptions): MethodDecorator;
+
+/**
+ * Configuration provided to the `@Agent` class decorator.
+ */
+interface AgentOptions {
+    /** Model id, e.g. `"openai:gpt-4o"`. Array = fallback chain. */
+    model?: string | string[];
+    /** System prompt establishing the agent's role and behavior. */
+    system?: string;
+    /** Tools the agent may call: provider classes and/or tool names. */
+    tools?: ToolRef[];
+    /** Maximum tool-calling steps before the run stops. */
+    maxSteps?: number;
+    /** Default Zod schema for structured output. Enables object generation. */
+    output?: ZodType<any, any, any>;
+}
+
+/**
+ * Declares a class as an AI agent. The class should extend {@link AiAgent} to
+ * gain `.run()` / `.stream()`. `@Agent` also marks the class `@Injectable`, so
+ * it participates in DI and can inject its own dependencies.
+ *
+ * @example
+ * ```ts
+ * @Agent({
+ *   model: 'openai:gpt-4o',
+ *   system: 'You are a helpful support assistant.',
+ *   tools: [WeatherTools],
+ * })
+ * export class SupportAgent extends AiAgent {}
+ * ```
+ */
+declare function Agent(options?: AgentOptions): ClassDecorator;
+
+/**
+ * In-memory registry of named, versioned prompt templates. Register prompts via
+ * `AiModule.forRoot({ prompts })`, `AiModule.forFeature({ prompts })`, or
+ * imperatively, then `render(name, vars)` to produce a final string.
+ */
+declare class PromptRegistry {
+    /** name -> (version -> definition) */
+    private readonly prompts;
+    /** name -> most recently registered version key */
+    private readonly latest;
+    /** Registers a prompt. Throws on a duplicate (name, version). */
+    register(definition: PromptDefinition): void;
+    /** Registers many prompts. */
+    registerAll(definitions: PromptDefinition[]): void;
+    /** Returns a prompt definition (latest version when `version` omitted). */
+    get(name: string, version?: string): PromptDefinition;
+    /** Renders a prompt to a string, interpolating `{{var}}` placeholders. */
+    render(name: string, vars?: Record<string, unknown>, options?: {
+        version?: string;
+    }): string;
+    /** Whether a prompt (any version) is registered. */
+    has(name: string): boolean;
+}
+
+/** Accumulated usage totals for a scope (conversation or global). */
+interface UsageTotals {
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    runs: number;
+}
+/** A single recorded run's usage. */
+interface UsageRecord extends UsageTotals {
+    conversationId?: string;
+    agent?: string;
+    model: string;
+}
+/**
+ * Tracks token usage and USD cost per conversation (and globally), and emits an
+ * `ai.usage` event per recorded run.
+ */
+declare class UsageTracker {
+    private readonly options;
+    private readonly events?;
+    private readonly totalsByScope;
+    constructor(options: AiModuleOptions, events?: AiEventEmitter | undefined);
+    /** Records a run's usage, returns the single-run record, emits `ai.usage`. */
+    record(entry: {
+        model: string;
+        usage: UsageLike | undefined;
+        conversationId?: string;
+        agent?: string;
+    }): UsageRecord;
+    /** Totals for a conversation, or global totals when no id is given. */
+    totals(conversationId?: string): UsageTotals;
+    /** Clears totals for a conversation (or all when no id). */
+    reset(conversationId?: string): void;
+}
+
+interface EmbedOptions {
+    /** Embedding model id, e.g. `"openai:text-embedding-3-small"`. */
+    model?: string;
+    abortSignal?: AbortSignal;
+    maxRetries?: number;
+}
+/**
+ * Generates vector embeddings for semantic search, clustering, and similarity.
+ * Wraps the Vercel AI SDK's `embed` / `embedMany`.
+ */
+declare class EmbeddingsService {
+    private readonly providers;
+    private readonly cache?;
+    constructor(providers: ProviderRegistry, cache?: AiCache | undefined);
+    /** Embeds a single value (cached when a cache is configured). */
+    embed(value: string, options?: EmbedOptions): Promise<ai.EmbedResult>;
+    /** Embeds many values (the SDK batches automatically). */
+    embedMany(values: string[], options?: EmbedOptions): Promise<ai.EmbedManyResult>;
+}
+
+/** A document stored in a vector store. */
+interface VectorDocument {
+    id: string;
+    content: string;
+    /** Precomputed embedding. Required by stores that don't embed themselves. */
+    embedding?: number[];
+    metadata?: Record<string, unknown>;
+}
+/** A single similarity-search hit. */
+interface VectorQueryResult {
+    id: string;
+    content: string;
+    /** Similarity score (higher is closer). */
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+/** Options for a vector similarity query. */
+interface VectorQueryOptions {
+    /** Maximum number of results to return (default 4). */
+    topK?: number;
+    /** Optional metadata equality filter. */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Persistence + similarity-search contract for RAG. Implement this to back
+ * retrieval with pgvector, a managed vector DB, etc., then register it via
+ * `AiModule.forRoot({ vectorStore })`.
+ */
+interface VectorStore {
+    /** Inserts or replaces documents by id. */
+    upsert(documents: VectorDocument[]): Promise<void>;
+    /** Returns the closest documents to `embedding`, ranked by similarity. */
+    query(embedding: number[], options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
+    /** Removes documents by id. */
+    delete(ids: string[]): Promise<void>;
+    /** Removes all documents. */
+    clear(): Promise<void>;
+}
+
+interface RecallOptions {
+    topK?: number;
+    model?: string;
+}
+/**
+ * Long-term semantic memory: stores snippets per conversation as embeddings and
+ * recalls the most relevant ones for a query. Backed by the configured
+ * `VectorStore` (isolated per conversation via metadata).
+ */
+declare class SemanticMemory {
+    private readonly embeddings;
+    private readonly store;
+    private readonly ai?;
+    constructor(embeddings: EmbeddingsService, store: VectorStore, ai?: AiService | undefined);
+    /** Embeds and stores a snippet under a conversation. */
+    remember(conversationId: string, text: string, options?: {
+        model?: string;
+        metadata?: Record<string, unknown>;
+    }): Promise<void>;
+    /** Returns the most relevant stored snippets for a query. */
+    recall(conversationId: string, query: string, options?: RecallOptions): Promise<VectorQueryResult[]>;
+    /**
+     * Summarizes messages with the LLM (requires `AiService`), then stores the
+     * summary as a memory snippet. Returns the stored text.
+     */
+    rememberConversation(conversationId: string, input: AiInput, options?: {
+        summarize?: boolean;
+        model?: string;
+    }): Promise<string>;
+    /** Summarizes messages into a compact string via the LLM. */
+    summarize(input: AiInput, model?: string): Promise<string>;
+}
+
+/**
+ * Runtime that executes `@Agent` classes: resolves their model, tools and
+ * memory, then drives the Vercel AI SDK (`generateText` / `streamText`, or the
+ * object variants when a structured-output schema is present).
+ */
+declare class AgentExecutorService {
+    private readonly providers;
+    private readonly toolRegistry;
+    private readonly store;
+    private readonly options;
+    private readonly events?;
+    private readonly guardrails?;
+    private readonly prompts?;
+    private readonly usageTracker?;
+    private readonly semanticMemory?;
+    constructor(providers: ProviderRegistry, toolRegistry: ToolRegistry, store: ConversationStore, options: AiModuleOptions, events?: AiEventEmitter | undefined, guardrails?: GuardrailRegistry | undefined, prompts?: PromptRegistry | undefined, usageTracker?: UsageTracker | undefined, semanticMemory?: SemanticMemory | undefined);
+    /** Runs an agent to completion and returns its result. */
+    run<T = unknown>(agent: object, input: AiInput, opts?: AgentRunOptions): Promise<AgentResult<T>>;
+    private runObject;
+    private runText;
+    /**
+     * Streams an agent's response. Returns the raw Vercel stream result so
+     * controllers can pipe it to an HTTP response or iterate `textStream`.
+     * Conversation persistence happens on stream finish.
+     */
+    stream(agent: object, input: AiInput, opts?: AgentRunOptions): ReturnType<typeof streamText> | ReturnType<typeof streamObject>;
+    /** Resolves the system prompt and prepends recalled memory when requested. */
+    private resolveSystemWithRecall;
+    private resolveSystem;
+    private telemetry;
+    private readMetadata;
+    private resolveMaxSteps;
+    private loadHistory;
+    private persist;
+}
+
+/**
+ * Base class for `@Agent`-decorated agents. Provides `.run()` and `.stream()`
+ * by delegating to the {@link AgentExecutorService}, which is property-injected
+ * so subclasses need no constructor boilerplate.
+ *
+ * @example
+ * ```ts
+ * @Agent({ model: 'openai:gpt-4o', system: 'You are helpful.' })
+ * class ChatAgent extends AiAgent {}
+ *
+ * // elsewhere
+ * const { text } = await chatAgent.run('Hello!');
+ * ```
+ */
+declare abstract class AiAgent {
+    protected readonly executor: AgentExecutorService;
+    /** Runs the agent to completion. */
+    run<T = unknown>(input: AiInput, opts?: AgentRunOptions): Promise<AgentResult<T>>;
+    /** Streams the agent's response (returns the raw Vercel stream result). */
+    stream(input: AiInput, opts?: AgentRunOptions): ReturnType<AgentExecutorService['stream']>;
+}
+
+/**
+ * Default in-process conversation store. Suitable for development, tests, and
+ * single-instance deployments. History is lost on restart and not shared
+ * across processes — provide a persistent implementation for production.
+ */
+declare class InMemoryConversationStore implements ConversationStore {
+    private readonly conversations;
+    load(conversationId: string): Promise<AiMessage[]>;
+    append(conversationId: string, messages: AiMessage[]): Promise<void>;
+    clear(conversationId: string): Promise<void>;
+}
+
+interface GenerateImageOptions {
+    /** Image model id, e.g. `"openai:dall-e-3"`. Defaults to `defaultImageModel`. */
+    model?: string;
+    /** Number of images to generate. */
+    n?: number;
+    /** Size string, e.g. `"1024x1024"`. */
+    size?: `${number}x${number}`;
+    /** Aspect ratio, e.g. `"16:9"`. */
+    aspectRatio?: `${number}:${number}`;
+    seed?: number;
+    providerOptions?: Record<string, Record<string, any>>;
+    abortSignal?: AbortSignal;
+    maxRetries?: number;
+}
+/**
+ * Generates images from a text prompt. Wraps the Vercel AI SDK's
+ * `experimental_generateImage`. Result exposes `.image` and `.images`.
+ */
+declare class ImageService {
+    private readonly providers;
+    constructor(providers: ProviderRegistry);
+    generate(prompt: string, options?: GenerateImageOptions): Promise<ai.GenerateImageResult>;
+}
+
+interface GenerateSpeechOptions {
+    /** Speech model id, e.g. `"openai:tts-1"`. Defaults to `defaultSpeechModel`. */
+    model?: string;
+    /** Voice identifier (provider-specific). */
+    voice?: string;
+    /** Output audio format, e.g. `"mp3"`. */
+    outputFormat?: string;
+    /** Extra guidance for the synthesis. */
+    instructions?: string;
+    speed?: number;
+    language?: string;
+    providerOptions?: Record<string, Record<string, any>>;
+    abortSignal?: AbortSignal;
+    maxRetries?: number;
+}
+/**
+ * Synthesizes speech from text. Wraps the Vercel AI SDK's
+ * `experimental_generateSpeech`. Result exposes `.audio`.
+ */
+declare class SpeechService {
+    private readonly providers;
+    constructor(providers: ProviderRegistry);
+    generate(text: string, options?: GenerateSpeechOptions): Promise<ai.SpeechResult>;
+}
+
+/** Audio input accepted by the transcription service. */
+type AudioInput = Uint8Array | ArrayBuffer | Buffer | string | URL;
+interface TranscribeOptions {
+    /** Transcription model id, e.g. `"openai:whisper-1"`. */
+    model?: string;
+    providerOptions?: Record<string, Record<string, any>>;
+    abortSignal?: AbortSignal;
+    maxRetries?: number;
+}
+/**
+ * Transcribes audio to text. Wraps the Vercel AI SDK's
+ * `experimental_transcribe`. Result exposes `.text` and `.segments`.
+ */
+declare class TranscriptionService {
+    private readonly providers;
+    constructor(providers: ProviderRegistry);
+    transcribe(audio: AudioInput, options?: TranscribeOptions): Promise<ai.TranscriptionResult>;
+}
+
+/**
+ * In-process vector store ranking by cosine similarity. Suitable for
+ * development, tests, and small datasets. Not persistent or shared across
+ * processes — provide a durable `VectorStore` for production.
+ */
+declare class InMemoryVectorStore implements VectorStore {
+    private readonly documents;
+    upsert(documents: VectorDocument[]): Promise<void>;
+    query(embedding: number[], options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+    private matchesFilter;
+}
+
+/**
+ * Re-orders retrieval results by relevance to the query, returning the top `topN`.
+ */
+interface Reranker {
+    rerank(query: string, results: VectorQueryResult[], topN: number): Promise<VectorQueryResult[]>;
+}
+
+/** An item to ingest into the vector store. */
+interface IngestItem {
+    /** Base id; chunks are suffixed `#0`, `#1`, … Defaults to a positional id. */
+    id?: string;
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+interface IngestOptions {
+    /** Max characters per chunk (default 1000; 0 disables chunking). */
+    chunkSize?: number;
+    /** Character overlap between consecutive chunks (default 100). */
+    chunkOverlap?: number;
+    /** Embedding model id. */
+    model?: string;
+}
+interface RetrieveOptions {
+    topK?: number;
+    model?: string;
+    filter?: Record<string, unknown>;
+    /**
+     * Rerank the results before truncating to `topK`. `true` uses the configured
+     * default reranker; pass a `Reranker` to override. When reranking, more
+     * candidates (`fetchK`) are fetched first.
+     */
+    rerank?: boolean | Reranker;
+    /** Candidates to fetch before reranking (default `topK * 4`). */
+    fetchK?: number;
+}
+/**
+ * Retrieval-augmented generation helper: chunk + embed + store documents, and
+ * embed queries to fetch the most relevant chunks.
+ */
+declare class RagService {
+    private readonly embeddings;
+    private readonly store;
+    private readonly defaultReranker?;
+    constructor(embeddings: EmbeddingsService, store: VectorStore, defaultReranker?: Reranker | undefined);
+    /** Chunks, embeds, and upserts items into the vector store. */
+    ingest(items: IngestItem[], options?: IngestOptions): Promise<void>;
+    /** Embeds `query` and returns the most similar stored chunks. */
+    retrieve(query: string, options?: RetrieveOptions): Promise<VectorQueryResult[]>;
+}
+/** Splits text into overlapping fixed-size character chunks. */
+declare function splitText(text: string, chunkSize: number, overlap: number): string[];
+
+interface RetrievalToolOptions {
+    /** Tool name exposed to the model (default `"searchKnowledgeBase"`). */
+    name?: string;
+    /** Tool description guiding when the model should search. */
+    description?: string;
+    /** Number of chunks to return (default 4). */
+    topK?: number;
+    /** Embedding model id for the query. */
+    model?: string;
+    /** Optional metadata filter applied to every retrieval. */
+    filter?: Record<string, unknown>;
+}
+/**
+ * Builds a Vercel AI SDK `tool()` that retrieves relevant chunks from a
+ * `RagService`, so an agent can ground its answers. Register it by exposing it
+ * from a `@Tool`-style provider, or pass its tool set directly to `AiService`.
+ *
+ * @example
+ * ```ts
+ * const tool = createRetrievalTool(rag, { topK: 5 });
+ * await ai.generateText({ model: 'openai:gpt-4o', tools: { search: tool }, prompt });
+ * ```
+ */
+declare function createRetrievalTool(rag: RagService, options?: RetrievalToolOptions): Tool$1<{
+    query: string;
+}, string>;
+
+/** Event names emitted by the library (namespaced for `@OnEvent`). */
+declare const AI_EVENTS: {
+    readonly agentRunStart: "ai.agent.run.start";
+    readonly agentRunFinish: "ai.agent.run.finish";
+    readonly agentRunError: "ai.agent.run.error";
+    readonly toolCall: "ai.tool.call";
+    readonly toolResult: "ai.tool.result";
+    readonly streamFinish: "ai.stream.finish";
+    readonly usage: "ai.usage";
+};
+interface AgentRunStartPayload {
+    agent: string;
+    input: unknown;
+    options: AgentRunOptions;
+}
+interface AgentRunFinishPayload {
+    agent: string;
+    result: AgentResult;
+}
+interface AgentRunErrorPayload {
+    agent: string;
+    error: unknown;
+}
+interface ToolCallPayload {
+    tool: string;
+    args: unknown;
+}
+interface ToolResultPayload {
+    tool: string;
+    args: unknown;
+    result: unknown;
+}
+
+/**
+ * Marks an injectable provider as a {@link Guardrail}. Discovered guardrails run
+ * on every agent execution. The class may inject its own dependencies.
+ *
+ * @example
+ * ```ts
+ * @Guardrail()
+ * export class BlockProfanity implements Guardrail {
+ *   beforeRun(ctx: GuardrailContext) {
+ *     if (containsProfanity(ctx.messages)) throw new Error('Blocked');
+ *   }
+ * }
+ * ```
+ */
+declare function Guardrail(): ClassDecorator;
+
+/**
+ * Minimal shape of a Prisma model delegate this store needs. Pass your
+ * generated delegate (e.g. `prisma.aiMessage`) — no dependency on
+ * `@prisma/client` is required by this library.
+ *
+ * Expected Prisma model:
+ * ```prisma
+ * model AiMessage {
+ *   id             String   @id @default(cuid())
+ *   conversationId String
+ *   role           String
+ *   content        Json
+ *   position       Int
+ *   createdAt      DateTime @default(now())
+ *   @@index([conversationId])
+ * }
+ * ```
+ */
+interface PrismaConversationDelegate {
+    findMany(args: {
+        where: {
+            conversationId: string;
+        };
+        orderBy: {
+            position: 'asc' | 'desc';
+        };
+    }): Promise<Array<{
+        role: string;
+        content: unknown;
+    }>>;
+    create(args: {
+        data: {
+            conversationId: string;
+            role: string;
+            content: unknown;
+            position: number;
+        };
+    }): Promise<unknown>;
+    count(args: {
+        where: {
+            conversationId: string;
+        };
+    }): Promise<number>;
+    deleteMany(args: {
+        where: {
+            conversationId: string;
+        };
+    }): Promise<unknown>;
+}
+/**
+ * Prisma-backed conversation store built on a delegate interface, so it works
+ * with any generated Prisma client without a compile-time dependency on it.
+ */
+declare class PrismaConversationStore implements ConversationStore {
+    private readonly delegate;
+    constructor(delegate: PrismaConversationDelegate);
+    load(conversationId: string): Promise<AiMessage[]>;
+    append(conversationId: string, messages: AiMessage[]): Promise<void>;
+    clear(conversationId: string): Promise<void>;
+}
+
+interface FallbackOptions {
+    /**
+     * Decide whether an error from a model should trigger a fallback to the next
+     * one. Defaults to always retrying on the next model.
+     */
+    shouldRetry?: (error: unknown) => boolean;
+    /** Provider name reported by the composite model. */
+    provider?: string;
+}
+/**
+ * Composes several language models into one that tries each in order, falling
+ * back to the next when a model throws (subject to `shouldRetry`). Fallback
+ * applies to the initial `doGenerate` / `doStream` call; once a stream starts it
+ * is not switched mid-flight.
+ *
+ * @example
+ * ```ts
+ * const model = createFallbackModel([
+ *   registry.getLanguageModel('openai:gpt-4o'),
+ *   registry.getLanguageModel('anthropic:claude-sonnet-5'),
+ * ]);
+ * ```
+ */
+declare function createFallbackModel(models: LanguageModelV3[], options?: FallbackOptions): LanguageModelV3;
+
+/**
+ * Default in-process cache with optional per-entry TTL. Not shared across
+ * processes — provide a distributed `AiCache` for production.
+ */
+declare class InMemoryAiCache implements AiCache {
+    private readonly store;
+    get(key: string): Promise<unknown | undefined>;
+    set(key: string, value: unknown, ttlMs?: number): Promise<void>;
+}
+
+interface CacheMiddlewareOptions {
+    /** Time-to-live for cached generations, in milliseconds (default: no expiry). */
+    ttlMs?: number;
+}
+/**
+ * Language-model middleware that caches non-streaming generations in an
+ * {@link AiCache}, keyed by the model id and call parameters. Wrap a model with
+ * `wrapLanguageModel({ model, middleware: createCacheMiddleware(cache) })`.
+ */
+declare function createCacheMiddleware(cache: AiCache, options?: CacheMiddlewareOptions): LanguageModelMiddleware;
+/** Builds a stable cache key from the model id and call parameters. */
+declare function cacheKey(modelId: string, params: unknown): string;
+
+/** Default gate: approves every request. */
+declare class AutoApproveGate implements ApprovalGate {
+    requestApproval(_context: ApprovalContext): Promise<boolean>;
+}
+/** Gate that denies every request (useful to hard-block approval tools). */
+declare class DenyApproveGate implements ApprovalGate {
+    requestApproval(_context: ApprovalContext): Promise<boolean>;
+}
+
+interface AgentToolOptions {
+    /** Tool name exposed to the calling model (default: the agent class name). */
+    name?: string;
+    /** Description guiding when to delegate to this agent. */
+    description?: string;
+    /**
+     * Input schema. Defaults to `{ input: string }`; the `input` field is passed
+     * to the sub-agent's `.run()`.
+     */
+    inputSchema?: ZodType<any, any, any>;
+}
+/**
+ * Wraps an agent as a tool so another agent can delegate to it (supervisor /
+ * handoff patterns). The wrapped agent's `.run()` output text is returned to the
+ * caller.
+ *
+ * @example
+ * ```ts
+ * @Agent({ model: 'openai:gpt-4o', system: 'Supervisor', tools: [ResearchAgent] })
+ * class SupervisorAgent extends AiAgent {}
+ * ```
+ */
+declare function createAgentTool(agent: Pick<AiAgent, 'run'>, options?: AgentToolOptions): Tool$1<any, string>;
+
+/** Structural type for the pipe methods on a Vercel AI SDK stream result. */
+interface PipeableStreamResult {
+    pipeUIMessageStreamToResponse?: (res: ServerResponse) => void;
+    pipeTextStreamToResponse?: (res: ServerResponse) => void;
+}
+interface PipeAgentStreamOptions {
+    /**
+     * Wire protocol: `'ui'` (AI SDK UI message stream, for `useChat`) or `'text'`
+     * (plain text stream). Defaults to `'ui'`.
+     */
+    protocol?: 'ui' | 'text';
+}
+/**
+ * Pipes an agent/`AiService` stream result to an HTTP response (Express-style
+ * `ServerResponse`). Use in a controller that injected `@Res()`.
+ *
+ * @example
+ * ```ts
+ * @Post('chat')
+ * chat(@Body('prompt') prompt: string, @Res() res: Response) {
+ *   pipeAgentStream(this.agent.stream(prompt), res, { protocol: 'ui' });
+ * }
+ * ```
+ */
+declare function pipeAgentStream(result: PipeableStreamResult, res: ServerResponse, options?: PipeAgentStreamOptions): void;
+
+/**
+ * Interceptor that pipes a stream result returned by a route handler to the
+ * HTTP response. The handler returns the `streamText`/agent `.stream()` result;
+ * the interceptor pipes it and completes the request.
+ *
+ * @example
+ * ```ts
+ * @UseInterceptors(new AgentStreamInterceptor({ protocol: 'ui' }))
+ * @Post('chat')
+ * chat(@Body('prompt') prompt: string) {
+ *   return this.agent.stream(prompt);
+ * }
+ * ```
+ */
+declare class AgentStreamInterceptor implements NestInterceptor {
+    private readonly options;
+    constructor(options?: PipeAgentStreamOptions);
+    intercept(context: ExecutionContext, next: CallHandler): Observable<never>;
+}
+
+/** A listed MCP tool (subset of the MCP `tools/list` result we use). */
+interface McpToolInfo {
+    name: string;
+    description?: string;
+    inputSchema: unknown;
+}
+/** Result of an MCP `tools/call` (subset). */
+interface McpCallResult {
+    content?: Array<{
+        type: string;
+        text?: string;
+        [k: string]: unknown;
+    }>;
+    isError?: boolean;
+    [k: string]: unknown;
+}
+/**
+ * Structural interface for an MCP client (e.g. `Client` from
+ * `@modelcontextprotocol/sdk`). Kept structural so this library has no
+ * compile-time dependency on the SDK and can be tested with a fake.
+ */
+interface McpClientLike {
+    listTools(): Promise<{
+        tools: McpToolInfo[];
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: Record<string, unknown>;
+    }): Promise<McpCallResult>;
+    close?(): Promise<void>;
+}
+/**
+ * Connects to MCP servers and adapts their tools into AI SDK tool sets that
+ * agents can use. Register a connected client via `connect(name, client)`, then
+ * reference its tools with `getToolSet(name)`.
+ */
+declare class McpService implements OnModuleDestroy {
+    private readonly clients;
+    private readonly toolSets;
+    /**
+     * Registers an MCP client under `name`, lists its tools, and builds a
+     * matching AI SDK tool set. Returns the tool set.
+     */
+    connect(name: string, client: McpClientLike): Promise<ToolSet>;
+    /** Returns the tool set for a connected server (empty if unknown). */
+    getToolSet(name: string): ToolSet;
+    /** Returns tool sets for all connected servers, merged. */
+    getAllTools(): ToolSet;
+    onModuleDestroy(): Promise<void>;
+    /** Closes every connected client. */
+    closeAll(): Promise<void>;
+}
+
+interface AgentJobsOptions {
+    /** BullMQ connection (ioredis connection or options). */
+    connection: unknown;
+    /** Queue name (default `"ai-agent-runs"`). */
+    queueName?: string;
+    /** Start a worker in this process to consume jobs (default `true`). */
+    runWorker?: boolean;
+}
+/**
+ * Background-job module for asynchronous agent execution on BullMQ. Import it
+ * where you need it (it is separate from the global `AiModule`).
+ *
+ * @example
+ * ```ts
+ * AgentJobsModule.forRoot({ connection: { host: 'localhost', port: 6379 } })
+ * ```
+ * Requires the optional peers `bullmq` (and typically a Redis instance).
+ */
+declare class AgentJobsModule {
+    static forRoot(options: AgentJobsOptions): DynamicModule;
+}
+
+/** Payload of a queued agent run. */
+interface AgentJobData {
+    /** Agent class name (as indexed by `AgentRegistry`). */
+    agent: string;
+    /** Input passed to the agent's `.run()`. */
+    input: AiInput;
+    /** Per-call run options. */
+    options?: AgentRunOptions;
+}
+/** Minimal structural interface for a BullMQ-like queue. */
+interface QueueLike {
+    add(name: string, data: AgentJobData, opts?: Record<string, unknown>): Promise<{
+        id?: string;
+    }>;
+}
+
+/** The job name used for queued agent runs. */
+declare const AGENT_JOB_NAME = "agent-run";
+/**
+ * Enqueues agent runs onto a BullMQ queue for asynchronous processing. The
+ * queue is injected under the `AGENT_QUEUE` token by `AgentJobsModule`.
+ */
+declare class AgentQueueService {
+    private readonly queue;
+    constructor(queue: QueueLike);
+    /** Enqueues an agent run and returns the created job id. */
+    enqueue(data: AgentJobData, jobOptions?: Record<string, unknown>): Promise<string | undefined>;
+}
+
+/**
+ * Runs a queued agent job by resolving the agent from the {@link AgentRegistry}
+ * and invoking its `.run()`. Framework-agnostic: a BullMQ worker simply calls
+ * `run(job.data)`.
+ */
+declare class AgentJobProcessor {
+    private readonly agents;
+    constructor(agents: AgentRegistry);
+    run(data: AgentJobData): Promise<AgentResult>;
+}
+
+/** Structural interface for a `pg` Pool/Client (only `query` is used). */
+interface PgPoolLike {
+    query(sql: string, params?: unknown[]): Promise<{
+        rows: Array<Record<string, any>>;
+    }>;
+}
+interface PgVectorStoreOptions {
+    /** Table name (default `"ai_documents"`). */
+    table?: string;
+}
+/**
+ * `VectorStore` backed by Postgres + the `pgvector` extension. Pass a `pg`
+ * `Pool` (or any object with a compatible `query`). Expects a table like:
+ *
+ * ```sql
+ * CREATE EXTENSION IF NOT EXISTS vector;
+ * CREATE TABLE ai_documents (
+ *   id text PRIMARY KEY,
+ *   content text NOT NULL,
+ *   embedding vector(1536) NOT NULL,
+ *   metadata jsonb
+ * );
+ * CREATE INDEX ON ai_documents USING hnsw (embedding vector_cosine_ops);
+ * ```
+ */
+declare class PgVectorStore implements VectorStore {
+    private readonly pool;
+    private readonly table;
+    constructor(pool: PgPoolLike, options?: PgVectorStoreOptions);
+    upsert(documents: VectorDocument[]): Promise<void>;
+    query(embedding: number[], options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/** Thrown when a conversation exceeds its configured cost budget. */
+declare class BudgetExceededError extends Error {
+    readonly conversationId: string | undefined;
+    readonly spent: number;
+    readonly limit: number;
+    constructor(conversationId: string | undefined, spent: number, limit: number);
+}
+/**
+ * Guardrail that blocks a run when the conversation's accumulated cost has
+ * reached `maxCostPerConversation`. Registered automatically when that option
+ * is set.
+ */
+declare class BudgetGuard implements Guardrail$1 {
+    private readonly usage;
+    private readonly options;
+    constructor(usage: UsageTracker, options: AiModuleOptions);
+    beforeRun(ctx: GuardrailContext): void;
+}
+
+/**
+ * Throttles agent runs. Implement this (e.g. Redis) for distributed limiting
+ * and register it via `AiModule.forRoot({ rateLimiter })`.
+ */
+interface RateLimiter {
+    /**
+     * Attempts to consume `cost` units for `key`. Resolves `true` if allowed,
+     * `false` if the limit is exceeded.
+     */
+    consume(key: string, cost?: number): Promise<boolean>;
+}
+/** Thrown by the rate-limit guardrail when a run is throttled. */
+declare class RateLimitedError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+
+interface InMemoryRateLimiterOptions {
+    /** Maximum tokens in the bucket (burst size). */
+    capacity: number;
+    /** Tokens added per `intervalMs`. */
+    refillTokens: number;
+    /** Refill interval in milliseconds. */
+    intervalMs: number;
+    /** Clock, for testing. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/**
+ * In-process token-bucket rate limiter, keyed (e.g. by conversation or user).
+ * Not shared across processes — provide a distributed `RateLimiter` for scale.
+ */
+declare class InMemoryRateLimiter implements RateLimiter {
+    private readonly options;
+    private readonly buckets;
+    private readonly now;
+    constructor(options: InMemoryRateLimiterOptions);
+    consume(key: string, cost?: number): Promise<boolean>;
+}
+
+/**
+ * Guardrail that throttles runs through the configured `RateLimiter`, keyed by
+ * conversation id (or `"global"`). Registered when `rateLimiter` is set.
+ */
+declare class RateLimitGuardrail implements Guardrail$1 {
+    private readonly limiter;
+    constructor(limiter: RateLimiter);
+    beforeRun(ctx: GuardrailContext): Promise<void>;
+}
+
+/** Default PII regexes: email, phone, credit card, US SSN. */
+declare const DEFAULT_PII_PATTERNS: RegExp[];
+interface PiiRedactionOptions {
+    patterns?: RegExp[];
+    replacement?: string;
+}
+/** Redacts PII matches in a string. */
+declare function redactPii(text: string, patterns?: RegExp[], replacement?: string): string;
+/** Redacts PII in every message's textual content, in place. */
+declare function redactMessages(messages: AiMessage[], patterns?: RegExp[], replacement?: string): void;
+/**
+ * Guardrail that redacts PII in the messages sent to the model (default
+ * patterns). For custom patterns use {@link createPiiRedactionGuardrail}.
+ */
+declare class PiiRedactionGuardrail implements Guardrail$1 {
+    beforeRun(ctx: GuardrailContext): void;
+}
+/** Builds a configured PII-redaction guardrail class (discoverable via DI). */
+declare function createPiiRedactionGuardrail(options?: PiiRedactionOptions): Type<Guardrail$1>;
+
+/** Thrown when moderation blocks content. */
+declare class ContentBlockedError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+interface ModerationOptions {
+    /** Case-insensitive terms that block a run when present. */
+    blocked?: string[];
+    /**
+     * Optional async check returning `true` to block. Runs in addition to the
+     * deny-list (e.g. call a provider moderation endpoint).
+     */
+    moderate?: (text: string) => boolean | Promise<boolean>;
+}
+/**
+ * Builds a moderation guardrail that blocks runs whose input contains a
+ * deny-listed term or fails a custom `moderate` check.
+ */
+declare function createModerationGuardrail(options?: ModerationOptions): Type<Guardrail$1>;
+
+interface HeuristicRerankerOptions {
+    /** Weight of the query-term overlap boost relative to the base score. */
+    overlapWeight?: number;
+}
+/**
+ * Zero-dependency reranker that boosts results whose content shares terms with
+ * the query, on top of the base similarity score. A pragmatic default when no
+ * reranking model is configured.
+ */
+declare class HeuristicReranker implements Reranker {
+    private readonly options;
+    constructor(options?: HeuristicRerankerOptions);
+    rerank(query: string, results: VectorQueryResult[], topN: number): Promise<VectorQueryResult[]>;
+}
+
+/**
+ * Reranker backed by a provider reranking model via the AI SDK's `rerank()`.
+ * Requires a rerank-capable provider (e.g. `@ai-sdk/cohere`) configured through
+ * `rerankingModel`.
+ */
+declare class ModelReranker implements Reranker {
+    private readonly providers;
+    private readonly model?;
+    constructor(providers: ProviderRegistry, model?: string | undefined);
+    rerank(query: string, results: VectorQueryResult[], topN: number): Promise<VectorQueryResult[]>;
+}
+
+/** Structural subset of the Qdrant JS client we use. */
+interface QdrantClientLike {
+    upsert(collection: string, params: unknown): Promise<unknown>;
+    search(collection: string, params: unknown): Promise<Array<{
+        id: string | number;
+        score: number;
+        payload?: any;
+    }>>;
+    delete(collection: string, params: unknown): Promise<unknown>;
+}
+interface QdrantVectorStoreOptions {
+    collection: string;
+}
+/**
+ * `VectorStore` backed by Qdrant. Pass a `@qdrant/js-client-rest` `QdrantClient`
+ * (or a compatible object). The payload stores `content` alongside metadata.
+ */
+declare class QdrantVectorStore implements VectorStore {
+    private readonly client;
+    private readonly options;
+    constructor(client: QdrantClientLike, options: QdrantVectorStoreOptions);
+    upsert(documents: VectorDocument[]): Promise<void>;
+    query(embedding: number[], options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/** Structural subset of a Pinecone index (namespace) we use. */
+interface PineconeIndexLike {
+    upsert(vectors: Array<{
+        id: string;
+        values: number[];
+        metadata?: any;
+    }>): Promise<unknown>;
+    query(params: {
+        vector: number[];
+        topK: number;
+        includeMetadata?: boolean;
+        filter?: Record<string, unknown>;
+    }): Promise<{
+        matches?: Array<{
+            id: string;
+            score?: number;
+            metadata?: any;
+        }>;
+    }>;
+    deleteMany(ids: string[]): Promise<unknown>;
+    deleteAll(): Promise<unknown>;
+}
+/**
+ * `VectorStore` backed by Pinecone. Pass a Pinecone index (optionally scoped to
+ * a namespace): `pinecone.index('name').namespace('ns')`. `content` is stored in
+ * the vector metadata.
+ */
+declare class PineconeVectorStore implements VectorStore {
+    private readonly index;
+    constructor(index: PineconeIndexLike);
+    upsert(documents: VectorDocument[]): Promise<void>;
+    query(embedding: number[], options?: VectorQueryOptions): Promise<VectorQueryResult[]>;
+    delete(ids: string[]): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/** A single evaluation case. */
+interface EvalCase {
+    name?: string;
+    input: string;
+    /** Expected substring/answer (used by the default judge). */
+    expected?: string;
+    /** Rubric text passed to an LLM judge. */
+    rubric?: string;
+}
+/** A judge's verdict for one output. */
+interface EvalScore {
+    /** Normalized score in [0, 1]. */
+    score: number;
+    passed: boolean;
+    reasoning?: string;
+}
+/** Full result for one case. */
+interface EvalResult extends EvalScore {
+    name: string;
+    input: string;
+    output: string;
+}
+/** Aggregate report over all cases. */
+interface EvalReport {
+    results: EvalResult[];
+    averageScore: number;
+    passRate: number;
+}
+/** Scores an agent output against its case. */
+type Judge = (ctx: {
+    case: EvalCase;
+    output: string;
+}) => Promise<EvalScore> | EvalScore;
+
+/** Minimal agent shape the runner needs. */
+interface RunnableAgent {
+    run(input: string): Promise<{
+        text: string;
+    }>;
+}
+/** Minimal `AiService` shape for the LLM judge. */
+interface JudgeAi {
+    generateObject(params: {
+        model?: string;
+        schema: unknown;
+        prompt: string;
+    }): Promise<{
+        object: {
+            score: number;
+            reasoning: string;
+        };
+    }>;
+}
+interface RunEvalOptions {
+    judge?: Judge;
+    /** Pass threshold in [0, 1] for the default judge (default 1). */
+    passThreshold?: number;
+}
+/**
+ * Runs an agent over a set of cases and scores each output with a judge
+ * (default: substring match against `expected`; or an LLM judge).
+ */
+declare class EvalRunner {
+    run(agent: RunnableAgent, cases: EvalCase[], options?: RunEvalOptions): Promise<EvalReport>;
+}
+/** Substring-match judge against `case.expected`. */
+declare function defaultJudge(threshold: number): Judge;
+/**
+ * Builds an LLM-as-judge that scores outputs 0..`scale` and normalizes to [0,1].
+ */
+declare function createLlmJudge(ai: JudgeAi, options?: {
+    model?: string;
+    scale?: number;
+    passThreshold?: number;
+}): Judge;
+
+export { AGENT_JOB_NAME, AGENT_QUEUE, AI_CACHE, AI_EVENTS, AI_MODULE_OPTIONS, APPROVAL_GATE, Agent, AgentExecutorService, type AgentJobData, AgentJobProcessor, AgentJobsModule, type AgentJobsOptions, type AgentOptions, AgentQueueService, AgentRegistry, type AgentResult, type AgentRunErrorPayload, type AgentRunFinishPayload, type AgentRunOptions, type AgentRunStartPayload, AgentStreamInterceptor, type AgentToolOptions, AiAgent, type AiCache, AiEventEmitter, AiFeatureOptions, AiInput, AiMessage, AiModule, AiModuleAsyncOptions, AiModuleOptions, AiService, type ApprovalContext, type ApprovalGate, type AudioInput, AutoApproveGate, BudgetExceededError, BudgetGuard, CONVERSATION_STORE, type CacheMiddlewareOptions, ContentBlockedError, ConversationStore, DEFAULT_MAX_STEPS, DEFAULT_PII_PATTERNS, DenyApproveGate, EVENT_EMITTER, type EmbedOptions, EmbeddingsService, type EvalCase, type EvalReport, type EvalResult, EvalRunner, type EvalScore, type EventEmitterLike, type FallbackOptions, type GenerateImageOptions, type GenerateSpeechOptions, Guardrail, type GuardrailContext, type Guardrail$1 as GuardrailContract, GuardrailRegistry, HeuristicReranker, type HeuristicRerankerOptions, ImageService, InMemoryAiCache, InMemoryConversationStore, InMemoryRateLimiter, type InMemoryRateLimiterOptions, InMemoryVectorStore, type IngestItem, type IngestOptions, type Judge, type JudgeAi, type McpCallResult, type McpClientLike, McpService, type McpToolInfo, ModelReranker, type ModerationOptions, type PgPoolLike, PgVectorStore, type PgVectorStoreOptions, PiiRedactionGuardrail, type PiiRedactionOptions, type PineconeIndexLike, PineconeVectorStore, type PipeAgentStreamOptions, type PipeableStreamResult, type PrismaConversationDelegate, PrismaConversationStore, PromptDefinition, PromptRef, PromptRegistry, ProviderRegistry, type QdrantClientLike, QdrantVectorStore, type QdrantVectorStoreOptions, type QueueLike, RATE_LIMITER, RERANKER, RagService, RateLimitGuardrail, RateLimitedError, type RateLimiter, type RecallOptions, type Reranker, type RetrievalToolOptions, type RetrieveOptions, type RunEvalOptions, type RunnableAgent, SemanticMemory, SpeechService, Tool, ToolApprovalDeniedError, type ToolCallPayload, type ToolEntry, type ToolMetadata, type ToolOptions, type ToolRef, ToolRegistry, type ToolResultPayload, type TranscribeOptions, TranscriptionService, type UsageRecord, type UsageTotals, UsageTracker, VECTOR_STORE, type VectorDocument, type VectorQueryOptions, type VectorQueryResult, type VectorStore, cacheKey, createAgentTool, createCacheMiddleware, createFallbackModel, createLlmJudge, createModerationGuardrail, createPiiRedactionGuardrail, createRetrievalTool, defaultJudge, pipeAgentStream, redactMessages, redactPii, splitText };