@mgvdev/nestjs-ai 0.1.0

package/skill/nestjs-ai/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: nestjs-ai
+description: Use when building AI features in a NestJS app with @mgvdev/nestjs-ai — agents, tools, structured output, streaming, embeddings, RAG, multimodal, prompts, guardrails, orchestration, MCP, caching, fallback, tool approval, jobs, cost/budgets, rate limiting, semantic memory, content safety, reranking, evals, and testing. Triggers on mentions of @mgvdev/nestjs-ai, AiModule, @Agent, @Tool, AiAgent, or "NestJS AI".
+---
+
+# Building with @mgvdev/nestjs-ai
+
+`@mgvdev/nestjs-ai` is a NestJS toolkit over the Vercel AI SDK (v7). It adds
+DI-native decorators, a dynamic module, automatic tool discovery, and production
+features (cost, rate limiting, guardrails, memory, evals).
+
+## Golden rules
+
+1. **Configure once** with `AiModule.forRoot()` / `forRootAsync()`. It is global.
+2. **Model ids are `"provider:model"`** — e.g. `"openai:gpt-4o"`. A bare id works
+   when a single provider is configured or a `defaultModel` sets the provider.
+3. **Agents extend `AiAgent`** and are annotated `@Agent`. Call `.run()` / `.stream()`.
+4. **Tools are `@Tool` methods on injectable providers** — they keep full DI.
+5. **Register agents/tools/guardrails as providers** (or via `AiModule.forFeature`)
+   so discovery finds them.
+6. **Install only the provider SDKs you use** (`@ai-sdk/openai`, etc.) — they are
+   optional peers. Same for `bullmq`, `pg`, `@nestjs/websockets`, `msw`.
+
+## Minimal setup
+
+```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 {}
+```
+
+`forRootAsync({ imports, inject, useFactory })` builds options from
+`ConfigService`.
+
+## Tools (function calling)
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { Tool } from '@mgvdev/nestjs-ai';
+import { z } from 'zod';
+
+@Injectable()
+export class WeatherTools {
+  constructor(private readonly api: WeatherApi) {} // regular DI
+
+  @Tool({ description: 'Get weather for a city', schema: z.object({ city: z.string() }) })
+  getWeather({ city }: { city: string }) {
+    return this.api.lookup(city);
+  }
+}
+```
+
+- `@Tool({ name?, description, schema, requiresApproval? })`. `schema` is Zod.
+- `requiresApproval: true` gates the call behind the configured `ApprovalGate`.
+
+## Agents
+
+```ts
+import { Agent, AiAgent } from '@mgvdev/nestjs-ai';
+
+@Agent({
+  model: 'openai:gpt-4o',            // or ['openai:gpt-4o', 'anthropic:claude-sonnet-4'] for fallback
+  system: 'You are a helpful assistant.',
+  tools: [WeatherTools],             // @Tool providers, or other @Agent classes (sub-agents)
+  maxSteps: 5,
+  // output: z.object({...}),        // structured output
+})
+export class SupportAgent extends AiAgent {}
+```
+
+Run it (inject the agent class):
+
+```ts
+const { text } = await this.support.run('Weather in Paris?');
+const { object } = await this.support.run<MyType>(input);       // when `output` is set
+const stream = this.support.stream('Hi');                        // Vercel stream result
+```
+
+`AgentRunOptions`: `{ model?, system?, systemPrompt?, conversationId?, maxSteps?, schema?, temperature?, maxRetries?, recall?, abortSignal? }`.
+
+## Register your classes
+
+```ts
+@Module({
+  imports: [AiModule.forFeature({ agents: [SupportAgent], tools: [WeatherTools] })],
+  providers: [WeatherApi],
+})
+export class SupportModule {}
+```
+
+## Feature cheat-sheet
+
+| Need | Use |
+| --- | --- |
+| Conversation history | `run(input, { conversationId })` — in-memory default; TypeORM (`/typeorm`) or Prisma store |
+| Structured output | `@Agent({ output })` or `run(input, { schema })` |
+| Streaming to HTTP | `pipeAgentStream(agent.stream(x), res, { protocol: 'ui' })` |
+| Streaming over WebSocket | `AgentGateway` from `@mgvdev/nestjs-ai/websocket` |
+| Embeddings | `EmbeddingsService.embed` / `embedMany` |
+| RAG | `RagService.ingest` / `retrieve`; stores: in-memory, `PgVectorStore`, `QdrantVectorStore`, `PineconeVectorStore` |
+| Reranking | `retrieve(q, { rerank: true })` (heuristic) or a `ModelReranker` |
+| Multimodal | `ImageService`, `SpeechService`, `TranscriptionService` |
+| Prompts | `PromptRegistry` + `AiModule.forRoot({ prompts })`; `run(x, { systemPrompt })` |
+| Events | `@OnEvent('ai.agent.run.finish')` (needs `@nestjs/event-emitter`) |
+| Guardrails | `@Guardrail()` classes; `beforeRun` / `afterRun` / `onToolCall` |
+| Tool approval | `@Tool({ requiresApproval: true })` + `approvalGate` option |
+| Multi-agent | list `@Agent` classes in another agent's `tools` |
+| MCP tools | `McpService.connect(name, client)` (bring an `@modelcontextprotocol/sdk` client) |
+| Fallback / retry | model array + `maxRetries` |
+| Caching | `AiModule.forRoot({ cache: InMemoryAiCache })` |
+| Background jobs | `AgentJobsModule.forRoot({ connection })` (BullMQ) |
+| Cost & budgets | `UsageTracker`; `AiModule.forRoot({ maxCostPerConversation })` |
+| Rate limiting | `AiModule.forRoot({ rateLimiter })` |
+| Semantic memory | `SemanticMemory.remember` / `recall`; `run(x, { recall })` |
+| Content safety | `PiiRedactionGuardrail`, `createModerationGuardrail` |
+| Evals | `EvalRunner.run(agent, cases, { judge })` |
+| Testing | `createTestingAiModule`, `createMockModel` from `@mgvdev/nestjs-ai/testing` |
+
+## Testing
+
+Never call real providers in tests. Use the testing subpath:
+
+```ts
+import { createTestingAiModule, createMockModel } from '@mgvdev/nestjs-ai/testing';
+
+const app = await createTestingAiModule({
+  model: createMockModel('mocked answer'),
+  providers: [SupportAgent],
+});
+const { text } = await app.get(SupportAgent).run('hi');
+```
+
+## Common mistakes
+
+- Forgetting to register an agent/tool/guardrail as a provider → discovery misses it.
+- Using a bare model id with multiple providers configured → prefix with `provider:`.
+- Expecting MCP or a rerank model from OpenAI/Google — MCP needs an external client;
+  reranking needs a rerank-capable provider (e.g. Cohere).
+- Importing the TypeORM store / WebSocket gateway / testing utils from the main entry —
+  they live at `@mgvdev/nestjs-ai/typeorm`, `/websocket`, `/testing`.
+
+## Deeper docs
+
+Full guides ship in the package under `documentation/` — read them for
+configuration, each feature, and the API reference.