@mgvdev/nestjs-ai 0.1.0

package/documentation/api-reference.md

@@ -0,0 +1,117 @@
+# API reference
+
+All exports are from `@mgvdev/nestjs-ai` unless a subpath is noted.
+
+## Module
+
+| Export | Kind | Notes |
+| --- | --- | --- |
+| `AiModule` | module | `forRoot` / `forRootAsync` / `forFeature` |
+| `AI_MODULE_OPTIONS` | token | injected options |
+| `DEFAULT_MAX_STEPS` | const | default tool-loop bound (5) |
+
+### Tokens
+
+`CONVERSATION_STORE` · `VECTOR_STORE` · `AI_CACHE` · `APPROVAL_GATE` ·
+`AGENT_QUEUE` · `RATE_LIMITER` · `RERANKER`.
+
+## Agents & tools
+
+| Export | Kind |
+| --- | --- |
+| `@Agent(options)` | class decorator |
+| `AiAgent` | base class (`.run` / `.stream`) |
+| `AgentExecutorService` | runtime |
+| `@Tool(options)` | method decorator |
+| `ToolRegistry` | discovered-tool registry |
+| `AiService` | raw `generateText`/`streamText`/`generateObject`/`streamObject` |
+| `ProviderRegistry` | model resolution |
+
+Types: `AgentOptions`, `AgentRunOptions`, `AgentResult`, `ToolOptions`,
+`ToolMetadata`, `ToolEntry`, `ToolRef`, `AiMessage`, `AiInput`, `toMessages`.
+
+## Embeddings & RAG
+
+| Export | Kind |
+| --- | --- |
+| `EmbeddingsService` | `embed` / `embedMany` |
+| `RagService` | `ingest` / `retrieve` |
+| `createRetrievalTool(rag, opts)` | tool factory |
+| `InMemoryVectorStore` | default store |
+| `PgVectorStore` | Postgres/pgvector (structural `pg` Pool) |
+| `QdrantVectorStore` | Qdrant (structural client) |
+| `PineconeVectorStore` | Pinecone (structural index) |
+| `HeuristicReranker` / `ModelReranker` | reranking |
+| `splitText(text, size, overlap)` | chunker |
+
+Types: `VectorStore`, `VectorDocument`, `VectorQueryResult`, `VectorQueryOptions`,
+`IngestItem`, `IngestOptions`, `RetrieveOptions`, `Reranker`.
+
+## Multimodal
+
+`ImageService` · `SpeechService` · `TranscriptionService`. Option types:
+`GenerateImageOptions`, `GenerateSpeechOptions`, `TranscribeOptions`, `AudioInput`.
+
+## Prompts
+
+`PromptRegistry` · `interpolate(template, vars)`. Types: `PromptDefinition`,
+`PromptRef`.
+
+## Memory
+
+`InMemoryConversationStore` · `SemanticMemory`. Interface: `ConversationStore`.
+Subpath `@mgvdev/nestjs-ai/typeorm`: `TypeOrmConversationStore`,
+`ConversationMessageEntity`. Main: `PrismaConversationStore`,
+`PrismaConversationDelegate`.
+
+## Guardrails, events & safety
+
+| Export | Kind |
+| --- | --- |
+| `@Guardrail()` | class decorator |
+| `GuardrailRegistry` | runs the chain |
+| `AiEventEmitter` / `AI_EVENTS` | events |
+| `PiiRedactionGuardrail` / `createPiiRedactionGuardrail` | PII |
+| `redactPii` / `redactMessages` / `DEFAULT_PII_PATTERNS` | helpers |
+| `createModerationGuardrail` / `ContentBlockedError` | moderation |
+
+Types: `Guardrail` (as `GuardrailContract`), `GuardrailContext`, event payloads.
+
+## Orchestration & MCP
+
+`AgentRegistry` · `createAgentTool` · `McpService`. Types: `AgentEntry`,
+`AgentToolOptions`, `McpClientLike`, `McpToolInfo`, `McpCallResult`.
+
+## Reliability
+
+| Export | Kind |
+| --- | --- |
+| `createFallbackModel(models, opts)` | composite model |
+| `InMemoryAiCache` / `createCacheMiddleware` / `cacheKey` | caching |
+| `InMemoryRateLimiter` / `RateLimitGuardrail` / `RateLimitedError` | rate limit |
+| `AutoApproveGate` / `DenyApproveGate` / `ToolApprovalDeniedError` | approval |
+| `UsageTracker` / `BudgetGuard` / `BudgetExceededError` | cost |
+| `costOf` / `DEFAULT_PRICING` / `bareModelId` | pricing |
+
+Interfaces: `AiCache`, `RateLimiter`, `ApprovalGate`, `ApprovalContext`. Types:
+`ModelPricing`, `PricingTable`, `UsageTotals`, `UsageRecord`.
+
+## Jobs, HTTP & realtime
+
+| Export | Kind |
+| --- | --- |
+| `AgentJobsModule` / `AgentQueueService` / `AgentJobProcessor` | BullMQ |
+| `pipeAgentStream` / `AgentStreamInterceptor` | HTTP/SSE |
+| `streamAgentToSocket` | WebSocket helper (main entry) |
+| `AgentGateway` | WebSocket gateway (`@mgvdev/nestjs-ai/websocket`) |
+
+Types: `AgentJobData`, `QueueLike`, `AgentJobsOptions`, `PipeAgentStreamOptions`,
+`SocketLike`, `AgentRunMessage`.
+
+## Evals & testing
+
+`EvalRunner` · `createLlmJudge` · `defaultJudge`. Types: `EvalCase`, `EvalScore`,
+`EvalResult`, `EvalReport`, `Judge`, `RunnableAgent`, `JudgeAi`.
+
+Subpath `@mgvdev/nestjs-ai/testing`: `createTestingAiModule`, `createMockModel`,
+`createEmbeddingMock`.

package/documentation/configuration.md

@@ -0,0 +1,87 @@
+# Configuration
+
+## `AiModule.forRoot(options)`
+
+```ts
+AiModule.forRoot({
+  providers: {
+    openai: { apiKey: '…', baseURL?: '…', headers?: {} },
+    anthropic: { apiKey: '…' },
+    google: { apiKey: '…' },
+  },
+  defaultModel: 'openai:gpt-4o',                  // string | string[] (fallback chain)
+  defaultEmbeddingModel: 'openai:text-embedding-3-small',
+  defaultImageModel: 'openai:dall-e-3',
+  defaultSpeechModel: 'openai:tts-1',
+  defaultTranscriptionModel: 'openai:whisper-1',
+  defaultMaxSteps: 5,
+  maxRetries: 2,
+
+  // memory
+  conversationStore: MyStore,                     // class | { useClass | useFactory | useValue }
+  // rag
+  vectorStore: { useFactory: () => new PgVectorStore(pool) },
+  rerankingModel: 'cohere:rerank-v3.5',
+  // prompts / guardrails
+  prompts: [{ name: 'support', template: 'Help {{user}}.' }],
+  guardrails: [MyGuardrail],
+  // reliability
+  cache: InMemoryAiCache,
+  cacheTtlMs: 60_000,
+  approvalGate: MyApprovalGate,
+  rateLimiter: { useValue: new InMemoryRateLimiter({ capacity: 10, refillTokens: 10, intervalMs: 60_000 }) },
+  // cost
+  pricing: { 'gpt-4o': { input: 2.5, output: 10 } },
+  maxCostPerConversation: 1.0,
+  // telemetry
+  telemetry: { isEnabled: true, functionId: 'my-app' },
+});
+```
+
+Every field is optional. Providers you don't list are simply unavailable; their
+`@ai-sdk/*` package only needs to be installed if you configure that provider.
+
+## `AiModule.forRootAsync(options)`
+
+Build options from injected dependencies (e.g. `ConfigService`):
+
+```ts
+AiModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    providers: { openai: { apiKey: config.getOrThrow('OPENAI_API_KEY') } },
+    defaultModel: 'openai:gpt-4o',
+  }),
+});
+```
+
+## `AiModule.forFeature(feature)`
+
+Convenience registration so agents/tools/guardrails don't have to be added to a
+consuming module's own `providers`:
+
+```ts
+AiModule.forFeature({
+  agents: [SupportAgent],
+  tools: [WeatherTools],
+  guardrails: [ProfanityGuard],
+  prompts: [{ name: 'greeting', template: 'Hi {{name}}' }],
+});
+```
+
+Discovery finds providers globally regardless of where they're registered — but
+they **must** be registered somewhere (here, or in your own module `providers`).
+
+## Model ids
+
+- `"provider:model"` — explicit, e.g. `"openai:gpt-4o"`, `"anthropic:claude-sonnet-4"`.
+- Bare `"model"` — works only when a single provider is configured, or when
+  `defaultModel` carries the provider prefix.
+- `string[]` — a **fallback chain**: each is tried in order (see
+  [Reliability](./reliability.md)).
+
+## Environment
+
+AI SDK v7 requires **Node.js ≥ 22**. Provider SDKs also read their own env vars
+(e.g. `OPENAI_API_KEY`) if you omit `apiKey`.

package/documentation/content-safety.md

@@ -0,0 +1,51 @@
+# Content safety
+
+Two guardrails: **PII redaction** and **moderation**. Both integrate with the
+guardrail pipeline — register them as providers or via `forFeature({ guardrails })`.
+
+## PII redaction
+
+Redacts emails, phone numbers, credit cards, and US SSNs from the messages sent
+to the model.
+
+```ts
+import { PiiRedactionGuardrail } from '@mgvdev/nestjs-ai';
+
+AiModule.forFeature({ guardrails: [PiiRedactionGuardrail] });
+```
+
+Custom patterns / replacement:
+
+```ts
+import { createPiiRedactionGuardrail } from '@mgvdev/nestjs-ai';
+
+const MyRedaction = createPiiRedactionGuardrail({
+  patterns: [/\bACC-\d{6}\b/g],
+  replacement: '[HIDDEN]',
+});
+AiModule.forFeature({ guardrails: [MyRedaction] });
+```
+
+Standalone helpers are exported too: `redactPii(text, patterns?, replacement?)`
+and `redactMessages(messages, …)`.
+
+## Moderation
+
+Blocks a run when the input contains a deny-listed term or fails a custom check.
+
+```ts
+import { createModerationGuardrail } from '@mgvdev/nestjs-ai';
+
+const Moderation = createModerationGuardrail({
+  blocked: ['secret-project', 'internal-only'],
+  moderate: async (text) => (await callModerationApi(text)).flagged, // optional
+});
+AiModule.forFeature({ guardrails: [Moderation] });
+```
+
+A blocked run throws `ContentBlockedError`.
+
+## Ordering
+
+Guardrails run in registration order. Put PII redaction before moderation if you
+want moderation to see the redacted text, or after if it should see the raw text.

package/documentation/embeddings-and-rag.md

@@ -0,0 +1,105 @@
+# Embeddings & RAG
+
+## Embeddings
+
+```ts
+import { EmbeddingsService } from '@mgvdev/nestjs-ai';
+
+@Injectable()
+export class SearchService {
+  constructor(private readonly embeddings: EmbeddingsService) {}
+
+  async run(docs: string[]) {
+    const { embedding } = await this.embeddings.embed('hello');
+    const { embeddings } = await this.embeddings.embedMany(docs);
+    return embeddings;
+  }
+}
+```
+
+Model resolves from `defaultEmbeddingModel` or the `model` option. When a
+[cache](./reliability.md#caching) is configured, single `embed` calls are cached.
+
+## RAG
+
+`RagService` chunks, embeds, and stores documents, then retrieves the most
+relevant chunks for a query.
+
+```ts
+await this.rag.ingest(
+  [{ id: 'handbook', content: longText, metadata: { source: 'hr' } }],
+  { chunkSize: 1000, chunkOverlap: 100 },
+);
+
+const hits = await this.rag.retrieve('vacation policy', { topK: 4 });
+// hits: { id, content, score, metadata }[]
+```
+
+### Expose retrieval to an agent
+
+A `@Tool` method that calls `RagService`:
+
+```ts
+@Injectable()
+export class KnowledgeTools {
+  constructor(private readonly rag: RagService) {}
+
+  @Tool({ description: 'Search the handbook', schema: z.object({ query: z.string() }) })
+  async search({ query }: { query: string }) {
+    const hits = await this.rag.retrieve(query);
+    return hits.map((h) => h.content).join('\n\n');
+  }
+}
+```
+
+Or use the factory:
+
+```ts
+import { createRetrievalTool } from '@mgvdev/nestjs-ai';
+const tool = createRetrievalTool(rag, { topK: 5 });
+await this.ai.generateText({ model: 'openai:gpt-4o', tools: { search: tool }, prompt });
+```
+
+## Reranking
+
+Fetch more candidates then rerank down to `topK`:
+
+```ts
+const hits = await this.rag.retrieve('query', { topK: 4, rerank: true }); // heuristic default
+```
+
+- `rerank: true` uses the configured default (`HeuristicReranker`, no dependency).
+- Pass a `Reranker` to override; `ModelReranker` uses the AI SDK `rerank()` with a
+  rerank-capable provider (`rerankingModel`, e.g. Cohere).
+
+## Vector stores
+
+The default store is `InMemoryVectorStore` (cosine similarity). Swap it via
+`vectorStore`:
+
+```ts
+// pgvector — pass your own `pg` Pool
+AiModule.forRoot({ vectorStore: { useFactory: () => new PgVectorStore(pool, { table: 'ai_documents' }) } });
+
+// Qdrant
+AiModule.forRoot({ vectorStore: { useFactory: () => new QdrantVectorStore(qdrant, { collection: 'docs' }) } });
+
+// Pinecone
+AiModule.forRoot({ vectorStore: { useFactory: () => new PineconeVectorStore(index) } });
+```
+
+Implement the `VectorStore` interface (`upsert` / `query` / `delete` / `clear`)
+for any other backend.
+
+### pgvector schema
+
+```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);
+```

package/documentation/evals-and-testing.md

@@ -0,0 +1,56 @@
+# Evals & testing
+
+## Testing
+
+Never hit real providers in tests. Use `@mgvdev/nestjs-ai/testing` (needs the
+optional peer `msw`, which `ai/test` requires).
+
+```ts
+import { createTestingAiModule, createMockModel } from '@mgvdev/nestjs-ai/testing';
+
+it('answers', async () => {
+  const app = await createTestingAiModule({
+    model: createMockModel('mocked answer'),
+    providers: [SupportAgent],
+  });
+  const { text } = await app.get(SupportAgent).run('hi');
+  expect(text).toBe('mocked answer');
+  await app.close();
+});
+```
+
+- `createMockModel(reply | replies[])` — a mock language model; an array yields
+  one reply per successive call (multi-step).
+- `createEmbeddingMock(fn)` — a mock embedding model from `value => number[]`.
+- `createTestingAiModule({ model, embedding, providers, imports, aiOptions })` —
+  boots `AiModule` with `ProviderRegistry` overridden to serve the mocks.
+
+To exercise tool calls or multi-step loops with full control, build a
+`MockLanguageModelV3` from `ai/test` directly and pass it via
+`createTestingAiModule({ model })`.
+
+## Evals (LLM-as-judge)
+
+`EvalRunner` runs an agent over a set of cases and scores each output.
+
+```ts
+import { EvalRunner, createLlmJudge } from '@mgvdev/nestjs-ai';
+
+const report = await this.evals.run(
+  supportAgent,
+  [
+    { input: 'capital of France?', expected: 'Paris' },
+    { input: 'summarize X', rubric: 'accurate and concise' },
+  ],
+  { judge: createLlmJudge(this.ai, { scale: 5, passThreshold: 0.6 }) },
+);
+
+// report.averageScore, report.passRate, report.results[]
+```
+
+- **Default judge** (no `judge` option): substring match against `case.expected`.
+- **`createLlmJudge(ai, { model?, scale?, passThreshold? })`**: an LLM scores each
+  output 0..`scale` (normalized to `[0, 1]`) using the case's `rubric` / `expected`.
+
+Each `EvalResult` has `{ name, input, output, score, passed, reasoning? }`.
+`EvalReport` aggregates `averageScore` and `passRate`.

package/documentation/getting-started.md

@@ -0,0 +1,96 @@
+# Getting started
+
+## Install
+
+```bash
+npm install @mgvdev/nestjs-ai ai zod
+npm install @ai-sdk/openai         # and/or @ai-sdk/anthropic, @ai-sdk/google
+```
+
+`@nestjs/common`, `@nestjs/core`, `reflect-metadata`, and `rxjs` are already in
+every Nest app. Ensure `reflect-metadata` is imported once at your app entry.
+
+## Register the module
+
+```ts
+import { Module } from '@nestjs/common';
+import { AiModule } from '@mgvdev/nestjs-ai';
+
+@Module({
+  imports: [
+    AiModule.forRoot({
+      providers: { openai: { apiKey: process.env.OPENAI_API_KEY } },
+      defaultModel: 'openai:gpt-4o',
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`AiModule` is global — its services are injectable everywhere.
+
+## Your first agent
+
+```ts
+// support.agent.ts
+import { Agent, AiAgent } from '@mgvdev/nestjs-ai';
+
+@Agent({ model: 'openai:gpt-4o', system: 'You are a concise assistant.' })
+export class SupportAgent extends AiAgent {}
+```
+
+```ts
+// support.module.ts
+import { Module } from '@nestjs/common';
+import { AiModule } from '@mgvdev/nestjs-ai';
+import { SupportAgent } from './support.agent';
+
+@Module({ imports: [AiModule.forFeature({ agents: [SupportAgent] })] })
+export class SupportModule {}
+```
+
+```ts
+// support.service.ts
+import { Injectable } from '@nestjs/common';
+import { SupportAgent } from './support.agent';
+
+@Injectable()
+export class SupportService {
+  constructor(private readonly agent: SupportAgent) {}
+
+  ask(question: string) {
+    return this.agent.run(question).then((r) => r.text);
+  }
+}
+```
+
+## Add a tool
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { Tool } from '@mgvdev/nestjs-ai';
+import { z } from 'zod';
+
+@Injectable()
+export class ClockTools {
+  @Tool({ description: 'Get the current time', schema: z.object({}) })
+  now() {
+    return new Date().toISOString();
+  }
+}
+```
+
+Reference it on the agent and register both:
+
+```ts
+@Agent({ model: 'openai:gpt-4o', system: '…', tools: [ClockTools] })
+export class SupportAgent extends AiAgent {}
+
+AiModule.forFeature({ agents: [SupportAgent], tools: [ClockTools] });
+```
+
+## Next
+
+- [Configuration](./configuration.md) — providers, defaults, async config.
+- [Agents & tools](./agents-and-tools.md) — the full agent/tool model.
+- [Evals & testing](./evals-and-testing.md) — test without hitting providers.

package/documentation/guardrails-events-telemetry.md

@@ -0,0 +1,72 @@
+# Guardrails, events & telemetry
+
+## Guardrails
+
+A guardrail inspects, mutates, or blocks agent runs and tool calls. Throw from
+any hook to abort.
+
+```ts
+import { Guardrail, type GuardrailContext } from '@mgvdev/nestjs-ai';
+
+@Guardrail()
+export class ProfanityGuard {
+  beforeRun(ctx: GuardrailContext) {
+    // ctx.messages is mutable; throw to block
+    if (isProfane(ctx.messages)) throw new ForbiddenException('Blocked');
+  }
+  afterRun(ctx: GuardrailContext, result) { /* inspect the result */ }
+  onToolCall(tool: string, args: unknown) { /* veto specific tool calls */ }
+}
+```
+
+Register as a provider (auto-discovered) or via
+`AiModule.forRoot({ guardrails: [ProfanityGuard] })` /
+`AiModule.forFeature({ guardrails })`.
+
+Hooks run in registration order:
+- `beforeRun(ctx)` — before generation; mutate `ctx.messages` or throw.
+- `afterRun(ctx, result)` — after generation.
+- `onToolCall(tool, args)` — before each tool executes; throw to block.
+
+Built-in guardrails ship for cost budgets, rate limiting, PII redaction, and
+moderation — see [Reliability](./reliability.md) and
+[Content safety](./content-safety.md).
+
+## Events
+
+With `@nestjs/event-emitter` installed and `EventEmitterModule.forRoot()`
+imported, the library emits lifecycle events (no-op otherwise).
+
+```ts
+import { AI_EVENTS } from '@mgvdev/nestjs-ai';
+
+@Injectable()
+export class AiListener {
+  @OnEvent(AI_EVENTS.agentRunFinish)
+  onFinish(payload: { agent: string; result: AgentResult }) { /* … */ }
+
+  @OnEvent(AI_EVENTS.usage)
+  onUsage(record: { model: string; cost: number; inputTokens: number }) { /* … */ }
+}
+```
+
+Event names:
+
+| Constant | Name | Payload |
+| --- | --- | --- |
+| `agentRunStart` | `ai.agent.run.start` | `{ agent, input, options }` |
+| `agentRunFinish` | `ai.agent.run.finish` | `{ agent, result }` |
+| `agentRunError` | `ai.agent.run.error` | `{ agent, error }` |
+| `toolCall` | `ai.tool.call` | `{ tool, args }` |
+| `toolResult` | `ai.tool.result` | `{ tool, args, result }` |
+| `streamFinish` | `ai.stream.finish` | `{ agent }` |
+| `usage` | `ai.usage` | `{ model, agent?, inputTokens, outputTokens, cost }` |
+
+## Telemetry (OpenTelemetry)
+
+Forward spans to the AI SDK's `experimental_telemetry` (requires an OTel setup in
+your app):
+
+```ts
+AiModule.forRoot({ telemetry: { isEnabled: true, functionId: 'support-agent' } });
+```

package/documentation/jobs-and-realtime.md

@@ -0,0 +1,69 @@
+# Background jobs & realtime
+
+## Background jobs (BullMQ)
+
+Run agents asynchronously. `AgentJobsModule` is a separate module (not part of
+the global `AiModule`); it needs the optional peer `bullmq` and a Redis instance.
+
+```ts
+import { AgentJobsModule } from '@mgvdev/nestjs-ai';
+
+@Module({
+  imports: [
+    AgentJobsModule.forRoot({
+      connection: { host: 'localhost', port: 6379 },
+      queueName: 'ai-agent-runs',   // optional
+      runWorker: true,               // start a worker in this process (default)
+    }),
+  ],
+})
+export class JobsModule {}
+```
+
+Enqueue a run:
+
+```ts
+constructor(private readonly queue: AgentQueueService) {}
+
+const jobId = await this.queue.enqueue({
+  agent: 'SupportAgent',     // agent class name (resolved via AgentRegistry)
+  input: 'summarize ticket 42',
+  options: { conversationId: 't-42' },
+});
+```
+
+The worker resolves the agent from `AgentRegistry`, runs it, and returns the
+`AgentResult` as the job's return value (BullMQ stores it). Query status via the
+BullMQ job API.
+
+For fine control, inject `AgentJobProcessor` and call `run(data)` yourself from a
+custom worker.
+
+## Realtime (WebSocket)
+
+Stream agent responses over socket.io. From `@mgvdev/nestjs-ai/websocket` (needs
+`@nestjs/websockets`, `@nestjs/platform-socket.io`, `socket.io`).
+
+```ts
+import { AgentGateway } from '@mgvdev/nestjs-ai/websocket';
+
+@Module({ providers: [AgentGateway] })
+export class RealtimeModule {}
+```
+
+Protocol:
+- Client emits `agent:run` `{ agent, input }`.
+- Server streams `agent:chunk` `{ delta }` per token, then `agent:done` `{ text }`.
+- Errors arrive as `agent:error` `{ message }`.
+
+```js
+socket.emit('agent:run', { agent: 'ChatAgent', input: 'Hello' });
+socket.on('agent:chunk', ({ delta }) => append(delta));
+socket.on('agent:done', ({ text }) => finalize(text));
+```
+
+### Framework-agnostic helper
+
+`streamAgentToSocket(streamResult, socket, options?)` (from the main entry)
+forwards a stream to any object with an `emit` method — use it to build your own
+gateway or adapter.