@mgvdev/nestjs-ai 0.1.0

package/dist/ai-module-options.interface-B5X4AFLC.d.cts

@@ -0,0 +1,192 @@
+import * as _nestjs_common from '@nestjs/common';
+import { Type, ModuleMetadata } from '@nestjs/common';
+import { C as ConversationStore } from './conversation-store.interface-CtQY-qcc.cjs';
+
+/** Price per 1M tokens, in USD. */
+interface ModelPricing {
+    input: number;
+    output: number;
+}
+/** Maps a bare model id (no provider prefix) to its pricing. */
+type PricingTable = Record<string, ModelPricing>;
+/** Minimal usage shape needed for cost. */
+interface UsageLike {
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/**
+ * Default USD pricing per 1M tokens for common models. Override or extend via
+ * `AiModule.forRoot({ pricing })`. Prices are indicative — verify against your
+ * provider's current rates.
+ */
+declare const DEFAULT_PRICING: PricingTable;
+/** Strips a `"provider:"` prefix from a model id. */
+declare function bareModelId(modelId: string): string;
+/**
+ * Computes the USD cost of a usage record for a model. Returns 0 when the model
+ * is not in the pricing table.
+ */
+declare function costOf(usage: UsageLike, modelId: string, pricing?: PricingTable): number;
+
+/**
+ * A named, optionally versioned prompt template.
+ */
+interface PromptDefinition {
+    /** Unique name used to look the prompt up. */
+    name: string;
+    /** Optional version; when omitted the latest registered version is used. */
+    version?: string;
+    /** Template body with `{{variable}}` placeholders. */
+    template: string;
+    /** Optional human-readable description. */
+    description?: string;
+}
+/** Reference to a registered prompt for rendering. */
+interface PromptRef {
+    name: string;
+    vars?: Record<string, unknown>;
+    version?: string;
+}
+/**
+ * Replaces `{{var}}` placeholders in `template` with values from `vars`.
+ * Throws if a referenced variable is missing, to catch typos early.
+ */
+declare function interpolate(template: string, vars?: Record<string, unknown>): string;
+
+/**
+ * Ways to supply a custom conversation store: a class, or a class/factory/value
+ * provider (registered under the internal store token).
+ */
+type ConversationStoreProvider = Type<ConversationStore> | {
+    useClass: Type<ConversationStore>;
+} | {
+    useFactory: (...args: any[]) => ConversationStore | Promise<ConversationStore>;
+    inject?: any[];
+} | {
+    useValue: ConversationStore;
+};
+/**
+ * Per-provider configuration. Every field is optional so a provider can also
+ * rely on its SDK's implicit environment variables (e.g. `OPENAI_API_KEY`).
+ */
+interface ProviderConfig {
+    apiKey?: string;
+    baseURL?: string;
+    /** Extra headers forwarded on every request to this provider. */
+    headers?: Record<string, string>;
+}
+/**
+ * Providers the module knows how to instantiate out of the box. The matching
+ * `@ai-sdk/*` package must be installed for a configured provider to resolve.
+ */
+interface ProvidersConfig {
+    openai?: ProviderConfig;
+    anthropic?: ProviderConfig;
+    google?: ProviderConfig;
+}
+interface AiModuleOptions {
+    /** Provider credentials keyed by provider name. */
+    providers?: ProvidersConfig;
+    /**
+     * Model used when a call does not specify one, e.g. `"openai:gpt-4o"` or a
+     * bare `"gpt-4o"` when a single provider is configured. An array configures a
+     * fallback chain (each tried in order).
+     */
+    defaultModel?: string | string[];
+    /** Default retry count forwarded to generate/stream calls. */
+    maxRetries?: number;
+    /** Default embedding model, e.g. `"openai:text-embedding-3-small"`. */
+    defaultEmbeddingModel?: string;
+    /** Default image model, e.g. `"openai:dall-e-3"`. */
+    defaultImageModel?: string;
+    /** Default speech (text-to-speech) model, e.g. `"openai:tts-1"`. */
+    defaultSpeechModel?: string;
+    /** Default transcription model, e.g. `"openai:whisper-1"`. */
+    defaultTranscriptionModel?: string;
+    /** Default maximum tool-calling steps for agent runs. */
+    defaultMaxSteps?: number;
+    /**
+     * OpenTelemetry settings forwarded to the AI SDK's `experimental_telemetry`.
+     * Requires an OTel setup in the host app to actually export spans.
+     */
+    telemetry?: {
+        isEnabled?: boolean;
+        functionId?: string;
+    };
+    /** Prompt templates to register at startup. */
+    prompts?: PromptDefinition[];
+    /** Guardrail provider classes to register (also discovered via `@Guardrail`). */
+    guardrails?: _nestjs_common.Type<any>[];
+    /** Custom vector store provider (defaults to `InMemoryVectorStore`). */
+    vectorStore?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /**
+     * Response/embedding cache. When set, resolved language models are wrapped
+     * with a caching middleware and embeddings are cached.
+     */
+    cache?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /** TTL (ms) for cached generations/embeddings. Default: no expiry. */
+    cacheTtlMs?: number;
+    /** Per-model USD pricing (per 1M tokens) for cost tracking. */
+    pricing?: PricingTable;
+    /** Max accumulated USD cost per conversation before runs are blocked. */
+    maxCostPerConversation?: number;
+    /** Rate limiter for throttling agent runs. */
+    rateLimiter?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /** Reranking model id (e.g. `"cohere:rerank-v3.5"`) for `ModelReranker`. */
+    rerankingModel?: string;
+    /** Approval gate for tools flagged `requiresApproval` (defaults to auto-approve). */
+    approvalGate?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /**
+     * Optional conversation store provider. When omitted an in-memory store is
+     * registered. Use `useClass`/`useFactory`/`useValue` to plug a custom store.
+     */
+    conversationStore?: ConversationStoreProvider;
+}
+/**
+ * Async configuration for `AiModule.forRootAsync`, allowing the options to be
+ * built from injected dependencies such as `ConfigService`.
+ */
+interface AiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    useFactory: (...args: any[]) => Promise<AiModuleOptions> | AiModuleOptions;
+    inject?: any[];
+    /**
+     * Optional conversation store provider registered alongside the async
+     * options (the factory result's `conversationStore` is ignored for DI
+     * reasons — declare it here instead).
+     */
+    conversationStore?: ConversationStoreProvider;
+}
+/**
+ * Classes registered via `AiModule.forFeature` for convenience so users do not
+ * have to wire agents/tools into their own module's `providers` array.
+ */
+interface AiFeatureOptions {
+    agents?: Type<any>[];
+    tools?: Type<any>[];
+    /** Guardrail provider classes to register for discovery. */
+    guardrails?: Type<any>[];
+    /** Prompt templates to register at startup. */
+    prompts?: PromptDefinition[];
+}
+
+export { type AiModuleOptions as A, type ConversationStoreProvider as C, DEFAULT_PRICING as D, type ModelPricing as M, type PromptRef as P, type UsageLike as U, type AiModuleAsyncOptions as a, type AiFeatureOptions as b, type PromptDefinition as c, type PricingTable as d, type ProviderConfig as e, type ProvidersConfig as f, bareModelId as g, costOf as h, interpolate as i };

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

@@ -0,0 +1,192 @@
+import * as _nestjs_common from '@nestjs/common';
+import { Type, ModuleMetadata } from '@nestjs/common';
+import { C as ConversationStore } from './conversation-store.interface-CtQY-qcc.js';
+
+/** Price per 1M tokens, in USD. */
+interface ModelPricing {
+    input: number;
+    output: number;
+}
+/** Maps a bare model id (no provider prefix) to its pricing. */
+type PricingTable = Record<string, ModelPricing>;
+/** Minimal usage shape needed for cost. */
+interface UsageLike {
+    inputTokens?: number;
+    outputTokens?: number;
+}
+/**
+ * Default USD pricing per 1M tokens for common models. Override or extend via
+ * `AiModule.forRoot({ pricing })`. Prices are indicative — verify against your
+ * provider's current rates.
+ */
+declare const DEFAULT_PRICING: PricingTable;
+/** Strips a `"provider:"` prefix from a model id. */
+declare function bareModelId(modelId: string): string;
+/**
+ * Computes the USD cost of a usage record for a model. Returns 0 when the model
+ * is not in the pricing table.
+ */
+declare function costOf(usage: UsageLike, modelId: string, pricing?: PricingTable): number;
+
+/**
+ * A named, optionally versioned prompt template.
+ */
+interface PromptDefinition {
+    /** Unique name used to look the prompt up. */
+    name: string;
+    /** Optional version; when omitted the latest registered version is used. */
+    version?: string;
+    /** Template body with `{{variable}}` placeholders. */
+    template: string;
+    /** Optional human-readable description. */
+    description?: string;
+}
+/** Reference to a registered prompt for rendering. */
+interface PromptRef {
+    name: string;
+    vars?: Record<string, unknown>;
+    version?: string;
+}
+/**
+ * Replaces `{{var}}` placeholders in `template` with values from `vars`.
+ * Throws if a referenced variable is missing, to catch typos early.
+ */
+declare function interpolate(template: string, vars?: Record<string, unknown>): string;
+
+/**
+ * Ways to supply a custom conversation store: a class, or a class/factory/value
+ * provider (registered under the internal store token).
+ */
+type ConversationStoreProvider = Type<ConversationStore> | {
+    useClass: Type<ConversationStore>;
+} | {
+    useFactory: (...args: any[]) => ConversationStore | Promise<ConversationStore>;
+    inject?: any[];
+} | {
+    useValue: ConversationStore;
+};
+/**
+ * Per-provider configuration. Every field is optional so a provider can also
+ * rely on its SDK's implicit environment variables (e.g. `OPENAI_API_KEY`).
+ */
+interface ProviderConfig {
+    apiKey?: string;
+    baseURL?: string;
+    /** Extra headers forwarded on every request to this provider. */
+    headers?: Record<string, string>;
+}
+/**
+ * Providers the module knows how to instantiate out of the box. The matching
+ * `@ai-sdk/*` package must be installed for a configured provider to resolve.
+ */
+interface ProvidersConfig {
+    openai?: ProviderConfig;
+    anthropic?: ProviderConfig;
+    google?: ProviderConfig;
+}
+interface AiModuleOptions {
+    /** Provider credentials keyed by provider name. */
+    providers?: ProvidersConfig;
+    /**
+     * Model used when a call does not specify one, e.g. `"openai:gpt-4o"` or a
+     * bare `"gpt-4o"` when a single provider is configured. An array configures a
+     * fallback chain (each tried in order).
+     */
+    defaultModel?: string | string[];
+    /** Default retry count forwarded to generate/stream calls. */
+    maxRetries?: number;
+    /** Default embedding model, e.g. `"openai:text-embedding-3-small"`. */
+    defaultEmbeddingModel?: string;
+    /** Default image model, e.g. `"openai:dall-e-3"`. */
+    defaultImageModel?: string;
+    /** Default speech (text-to-speech) model, e.g. `"openai:tts-1"`. */
+    defaultSpeechModel?: string;
+    /** Default transcription model, e.g. `"openai:whisper-1"`. */
+    defaultTranscriptionModel?: string;
+    /** Default maximum tool-calling steps for agent runs. */
+    defaultMaxSteps?: number;
+    /**
+     * OpenTelemetry settings forwarded to the AI SDK's `experimental_telemetry`.
+     * Requires an OTel setup in the host app to actually export spans.
+     */
+    telemetry?: {
+        isEnabled?: boolean;
+        functionId?: string;
+    };
+    /** Prompt templates to register at startup. */
+    prompts?: PromptDefinition[];
+    /** Guardrail provider classes to register (also discovered via `@Guardrail`). */
+    guardrails?: _nestjs_common.Type<any>[];
+    /** Custom vector store provider (defaults to `InMemoryVectorStore`). */
+    vectorStore?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /**
+     * Response/embedding cache. When set, resolved language models are wrapped
+     * with a caching middleware and embeddings are cached.
+     */
+    cache?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /** TTL (ms) for cached generations/embeddings. Default: no expiry. */
+    cacheTtlMs?: number;
+    /** Per-model USD pricing (per 1M tokens) for cost tracking. */
+    pricing?: PricingTable;
+    /** Max accumulated USD cost per conversation before runs are blocked. */
+    maxCostPerConversation?: number;
+    /** Rate limiter for throttling agent runs. */
+    rateLimiter?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /** Reranking model id (e.g. `"cohere:rerank-v3.5"`) for `ModelReranker`. */
+    rerankingModel?: string;
+    /** Approval gate for tools flagged `requiresApproval` (defaults to auto-approve). */
+    approvalGate?: _nestjs_common.Type<any> | {
+        useClass?: _nestjs_common.Type<any>;
+        useFactory?: (...args: any[]) => any;
+        useValue?: any;
+        inject?: any[];
+    };
+    /**
+     * Optional conversation store provider. When omitted an in-memory store is
+     * registered. Use `useClass`/`useFactory`/`useValue` to plug a custom store.
+     */
+    conversationStore?: ConversationStoreProvider;
+}
+/**
+ * Async configuration for `AiModule.forRootAsync`, allowing the options to be
+ * built from injected dependencies such as `ConfigService`.
+ */
+interface AiModuleAsyncOptions extends Pick<ModuleMetadata, 'imports'> {
+    useFactory: (...args: any[]) => Promise<AiModuleOptions> | AiModuleOptions;
+    inject?: any[];
+    /**
+     * Optional conversation store provider registered alongside the async
+     * options (the factory result's `conversationStore` is ignored for DI
+     * reasons — declare it here instead).
+     */
+    conversationStore?: ConversationStoreProvider;
+}
+/**
+ * Classes registered via `AiModule.forFeature` for convenience so users do not
+ * have to wire agents/tools into their own module's `providers` array.
+ */
+interface AiFeatureOptions {
+    agents?: Type<any>[];
+    tools?: Type<any>[];
+    /** Guardrail provider classes to register for discovery. */
+    guardrails?: Type<any>[];
+    /** Prompt templates to register at startup. */
+    prompts?: PromptDefinition[];
+}
+
+export { type AiModuleOptions as A, type ConversationStoreProvider as C, DEFAULT_PRICING as D, type ModelPricing as M, type PromptRef as P, type UsageLike as U, type AiModuleAsyncOptions as a, type AiFeatureOptions as b, type PromptDefinition as c, type PricingTable as d, type ProviderConfig as e, type ProvidersConfig as f, bareModelId as g, costOf as h, interpolate as i };

package/dist/conversation-store.interface-CtQY-qcc.d.cts

@@ -0,0 +1,30 @@
+import { ModelMessage } from 'ai';
+
+/**
+ * A single conversation message, re-exported from the AI SDK so consumers of
+ * this library never need to import `ai` types directly.
+ */
+type AiMessage = ModelMessage;
+/**
+ * The input accepted by agent `.run()` / `.stream()` and the raw facade: either
+ * a plain user string or an explicit list of messages.
+ */
+type AiInput = string | AiMessage[];
+/** Normalizes a string or message list into a message array. */
+declare function toMessages(input: AiInput): AiMessage[];
+
+/**
+ * Persistence contract for conversation history. Implement this interface to
+ * back conversations with a database, cache, or any other store, then register
+ * it through `AiModule.forRoot({ conversationStore })`.
+ */
+interface ConversationStore {
+    /** Returns the ordered messages for a conversation (empty if unknown). */
+    load(conversationId: string): Promise<AiMessage[]>;
+    /** Appends messages to a conversation, preserving order. */
+    append(conversationId: string, messages: AiMessage[]): Promise<void>;
+    /** Removes all messages for a conversation. */
+    clear(conversationId: string): Promise<void>;
+}
+
+export { type AiMessage as A, type ConversationStore as C, type AiInput as a, toMessages as t };

package/dist/conversation-store.interface-CtQY-qcc.d.ts

@@ -0,0 +1,30 @@
+import { ModelMessage } from 'ai';
+
+/**
+ * A single conversation message, re-exported from the AI SDK so consumers of
+ * this library never need to import `ai` types directly.
+ */
+type AiMessage = ModelMessage;
+/**
+ * The input accepted by agent `.run()` / `.stream()` and the raw facade: either
+ * a plain user string or an explicit list of messages.
+ */
+type AiInput = string | AiMessage[];
+/** Normalizes a string or message list into a message array. */
+declare function toMessages(input: AiInput): AiMessage[];
+
+/**
+ * Persistence contract for conversation history. Implement this interface to
+ * back conversations with a database, cache, or any other store, then register
+ * it through `AiModule.forRoot({ conversationStore })`.
+ */
+interface ConversationStore {
+    /** Returns the ordered messages for a conversation (empty if unknown). */
+    load(conversationId: string): Promise<AiMessage[]>;
+    /** Appends messages to a conversation, preserving order. */
+    append(conversationId: string, messages: AiMessage[]): Promise<void>;
+    /** Removes all messages for a conversation. */
+    clear(conversationId: string): Promise<void>;
+}
+
+export { type AiMessage as A, type ConversationStore as C, type AiInput as a, toMessages as t };