@mgvdev/nestjs-ai 0.1.0

package/documentation/memory.md

@@ -0,0 +1,101 @@
+# Memory
+
+Two complementary systems: **conversation history** (raw turns) and **semantic
+memory** (embedding-based recall).
+
+## Conversation history
+
+Pass a `conversationId` to load prior turns before a run and persist the new
+exchange after.
+
+```ts
+await agent.run('What about tomorrow?', { conversationId: user.id });
+```
+
+The default `ConversationStore` is in-memory. Provide your own by implementing
+the interface:
+
+```ts
+interface ConversationStore {
+  load(conversationId: string): Promise<AiMessage[]>;
+  append(conversationId: string, messages: AiMessage[]): Promise<void>;
+  clear(conversationId: string): Promise<void>;
+}
+```
+
+### TypeORM store
+
+From `@mgvdev/nestjs-ai/typeorm` (needs `typeorm` + `@nestjs/typeorm`):
+
+```ts
+import { getRepositoryToken, TypeOrmModule } from '@nestjs/typeorm';
+import { ConversationMessageEntity, TypeOrmConversationStore } from '@mgvdev/nestjs-ai/typeorm';
+
+@Module({
+  imports: [
+    TypeOrmModule.forFeature([ConversationMessageEntity]),
+    AiModule.forRoot({
+      providers: { openai: { apiKey } },
+      conversationStore: {
+        useFactory: (repo) => new TypeOrmConversationStore(repo),
+        inject: [getRepositoryToken(ConversationMessageEntity)],
+      },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Prisma store
+
+No build-time dependency — pass a model delegate:
+
+```ts
+import { PrismaConversationStore } from '@mgvdev/nestjs-ai';
+
+AiModule.forRoot({
+  conversationStore: {
+    useFactory: (prisma: PrismaService) => new PrismaConversationStore(prisma.aiMessage),
+    inject: [PrismaService],
+  },
+});
+```
+
+```prisma
+model AiMessage {
+  id             String   @id @default(cuid())
+  conversationId String
+  role           String
+  content        Json
+  position       Int
+  createdAt      DateTime @default(now())
+  @@index([conversationId])
+}
+```
+
+## Semantic memory
+
+`SemanticMemory` stores snippets per conversation as embeddings and recalls the
+most relevant ones — useful for long-term facts beyond raw turns.
+
+```ts
+await this.memory.remember(conversationId, 'The user prefers dark mode.');
+
+// recall relevant snippets:
+const hits = await this.memory.recall(conversationId, 'settings', { topK: 3 });
+
+// summarize a conversation and store it (requires AiService):
+await this.memory.rememberConversation(conversationId, messages, { summarize: true });
+```
+
+### Automatic recall in a run
+
+```ts
+await agent.run('what are my settings?', {
+  conversationId,
+  recall: { topK: 3 },   // recalled snippets are prepended to the system prompt
+});
+```
+
+Semantic memory uses the configured `VectorStore` (isolated per conversation via
+metadata), so it works with in-memory, pgvector, Qdrant, or Pinecone.

package/documentation/multimodal.md

@@ -0,0 +1,49 @@
+# Multimodal
+
+Three injectable services wrap the AI SDK's image, speech, and transcription
+APIs. Set `defaultImageModel` / `defaultSpeechModel` /
+`defaultTranscriptionModel`, or pass `model` per call.
+
+## Image generation
+
+```ts
+import { ImageService } from '@mgvdev/nestjs-ai';
+
+const { image, images } = await this.images.generate('a fox in the snow', {
+  model: 'openai:dall-e-3',
+  size: '1024x1024',
+  aspectRatio: '16:9',
+  n: 1,
+});
+// image: GeneratedFile (base64 / bytes)
+```
+
+## Speech (text-to-speech)
+
+```ts
+import { SpeechService } from '@mgvdev/nestjs-ai';
+
+const { audio } = await this.speech.generate('Hello there', {
+  model: 'openai:tts-1',
+  voice: 'alloy',
+  outputFormat: 'mp3',
+});
+```
+
+## Transcription (speech-to-text)
+
+```ts
+import { TranscriptionService } from '@mgvdev/nestjs-ai';
+
+const { text, segments } = await this.transcription.transcribe(audioBuffer, {
+  model: 'openai:whisper-1',
+});
+```
+
+`audio` accepts a `Uint8Array`, `ArrayBuffer`, `Buffer`, base64 string, or `URL`.
+
+## Provider support
+
+Availability depends on the provider SDK. OpenAI supports image, speech, and
+transcription; other providers vary. A clear error is thrown when a configured
+provider does not support the requested capability.

package/documentation/orchestration-and-mcp.md

@@ -0,0 +1,68 @@
+# Orchestration & MCP
+
+## Multi-agent orchestration
+
+Reference an `@Agent` class in another agent's `tools` to delegate to it
+(supervisor / handoff). The sub-agent's output text is returned to the caller.
+
+```ts
+@Agent({ model: 'openai:gpt-4o', system: 'Research facts.' })
+export class ResearchAgent extends AiAgent {}
+
+@Agent({ model: 'openai:gpt-4o', system: 'Write the final answer.' })
+export class WriterAgent extends AiAgent {}
+
+@Agent({
+  model: 'openai:gpt-4o',
+  system: 'Coordinate specialists to answer the user.',
+  tools: [ResearchAgent, WriterAgent],   // sub-agents used as tools
+})
+export class SupervisorAgent extends AiAgent {}
+```
+
+Register all three as providers. The supervisor calls each sub-agent by its class
+name.
+
+### `AgentRegistry`
+
+Indexes all agents by class name — used by orchestration and background jobs.
+
+```ts
+this.agents.get('ResearchAgent');   // instance
+this.agents.all();                  // AgentEntry[]
+```
+
+### `createAgentTool`
+
+Wrap an agent as a tool manually:
+
+```ts
+import { createAgentTool } from '@mgvdev/nestjs-ai';
+const tool = createAgentTool(researchAgent, { name: 'research', description: '…' });
+```
+
+## MCP (Model Context Protocol)
+
+Adapt tools from an MCP server into an agent tool set. Bring your own client from
+`@modelcontextprotocol/sdk` — any object with `listTools` / `callTool` / `close`.
+
+```ts
+import { McpService } from '@mgvdev/nestjs-ai';
+
+// connect once (e.g. on module init)
+const toolSet = await this.mcp.connect('filesystem', mcpClient);
+
+// use the tools
+await this.ai.generateText({ model: 'openai:gpt-4o', tools: toolSet, prompt });
+
+// or fetch later / merge
+this.mcp.getToolSet('filesystem');
+this.mcp.getAllTools();
+```
+
+Clients are closed automatically on module destroy. MCP tools are exposed to the
+model via the AI SDK's `dynamicTool`, with input schemas passed through from the
+server's JSON schema.
+
+> AI SDK v7 does not ship an MCP client; use `@modelcontextprotocol/sdk` directly
+> to construct the transport + client, then hand it to `McpService`.

package/documentation/prompts.md

@@ -0,0 +1,51 @@
+# Prompt registry
+
+Register named, versioned prompt templates and render them with `{{var}}`
+interpolation.
+
+## Register
+
+```ts
+AiModule.forRoot({
+  prompts: [
+    { name: 'support', version: 'v1', template: 'Help {{user}} with {{topic}}.' },
+    { name: 'support', version: 'v2', template: 'Assist {{user}} regarding {{topic}}.' },
+  ],
+});
+```
+
+Also via `AiModule.forFeature({ prompts })`, or imperatively:
+
+```ts
+this.prompts.register({ name: 'greeting', template: 'Hi {{name}}!' });
+```
+
+## Render
+
+```ts
+this.prompts.render('support', { user: 'Ada', topic: 'billing' });
+// latest version by default; pass { version: 'v1' } to pin
+this.prompts.render('support', { user: 'Ada', topic: 'billing' }, { version: 'v1' });
+```
+
+Unknown variables throw, so typos are caught early. Duplicate `(name, version)`
+registration throws.
+
+## Use as an agent's system prompt
+
+Resolve the system prompt per call from the registry:
+
+```ts
+await agent.run(question, {
+  systemPrompt: { name: 'support', vars: { user, topic }, version: 'v2' },
+});
+```
+
+This overrides the agent's static `system`.
+
+## API
+
+- `register(def)` / `registerAll(defs)`
+- `render(name, vars?, { version? })`
+- `get(name, version?)` — the raw `PromptDefinition`
+- `has(name)`

package/documentation/reliability.md

@@ -0,0 +1,90 @@
+# Reliability
+
+Fallback models, retries, caching, rate limiting, tool approval, and cost budgets.
+
+## Fallback models & retries
+
+Pass a **model array** to configure a fallback chain — each model is tried in
+order when the previous one throws.
+
+```ts
+@Agent({ model: ['openai:gpt-4o', 'anthropic:claude-sonnet-4'] })
+export class ResilientAgent extends AiAgent {}
+
+// or per call, plus SDK-native retries:
+await agent.run(prompt, { model: ['openai:gpt-4o', 'openai:gpt-4o-mini'], maxRetries: 3 });
+```
+
+Build a composite model manually with `createFallbackModel(models, { shouldRetry })`.
+
+## Caching
+
+Memoize model responses (via middleware) and single embeddings.
+
+```ts
+AiModule.forRoot({
+  providers: { openai: { apiKey } },
+  cache: InMemoryAiCache,     // or a class/factory/value implementing AiCache
+  cacheTtlMs: 60_000,
+});
+```
+
+Implement `AiCache` (`get` / `set`) for Redis or another backend. Cache keys are
+derived from the model id and call parameters.
+
+## Rate limiting
+
+Throttle runs per conversation (or `"global"`).
+
+```ts
+AiModule.forRoot({
+  providers: { openai: { apiKey } },
+  rateLimiter: {
+    useValue: new InMemoryRateLimiter({ capacity: 10, refillTokens: 10, intervalMs: 60_000 }),
+  },
+});
+```
+
+A throttled run throws `RateLimitedError`. Implement `RateLimiter`
+(`consume(key, cost?)`) for a distributed limiter.
+
+## Tool approval (human-in-the-loop)
+
+Flag a tool with `requiresApproval` and register an `ApprovalGate`.
+
+```ts
+@Tool({ description: 'Delete a record', schema: z.object({ id: z.string() }), requiresApproval: true })
+deleteRecord({ id }: { id: string }) { /* … */ }
+
+@Injectable()
+class QueueApprovalGate implements ApprovalGate {
+  async requestApproval({ tool, args }: ApprovalContext) {
+    return askAHuman(tool, args); // resolve true to allow, false to block
+  }
+}
+
+AiModule.forRoot({ providers: { openai: { apiKey } }, approvalGate: QueueApprovalGate });
+```
+
+Defaults `AutoApproveGate` / `DenyApproveGate` are provided. A denied call throws
+`ToolApprovalDeniedError`.
+
+## Cost tracking & budgets
+
+Token usage and USD cost are tracked per conversation. Set a budget to block
+runaway spend.
+
+```ts
+AiModule.forRoot({
+  providers: { openai: { apiKey } },
+  maxCostPerConversation: 0.5,   // blocks the next run once $0.50 is reached
+  pricing: { 'gpt-4o': { input: 2.5, output: 10 } }, // override defaults ($/1M tokens)
+});
+
+// inspect anytime
+const { cost, inputTokens, runs } = this.usage.totals(conversationId);
+```
+
+Listen with `@OnEvent('ai.usage')`. The budget check throws `BudgetExceededError`.
+Costs use `DEFAULT_PRICING` (a small built-in table) merged with your `pricing`
+overrides; unknown models cost `0`.

package/documentation/structured-output-and-streaming.md

@@ -0,0 +1,81 @@
+# Structured output & streaming
+
+## Structured output
+
+Declare an `output` schema on the agent (or pass `schema` per call) to receive a
+validated object instead of text.
+
+```ts
+@Agent({
+  model: 'openai:gpt-4o',
+  system: 'Extract the order details.',
+  output: z.object({ product: z.string(), quantity: z.number() }),
+})
+export class OrderAgent extends AiAgent {}
+
+const { object } = await orderAgent.run<{ product: string; quantity: number }>(text);
+```
+
+Per call:
+
+```ts
+const { object } = await agent.run(input, {
+  schema: z.object({ sentiment: z.enum(['positive', 'neutral', 'negative']) }),
+});
+```
+
+Structured-output runs use `generateObject` under the hood; the result's
+`object` is validated against the schema.
+
+## Streaming
+
+`.stream()` returns the raw Vercel AI SDK stream result. Iterate `textStream` or
+pipe it to an HTTP response.
+
+```ts
+const result = agent.stream('Tell me a story');
+for await (const delta of result.textStream) {
+  process.stdout.write(delta);
+}
+```
+
+### Stream to an HTTP response
+
+```ts
+import { pipeAgentStream } from '@mgvdev/nestjs-ai';
+
+@Post('chat')
+chat(@Body('prompt') prompt: string, @Res() res: Response) {
+  pipeAgentStream(agent.stream(prompt), res, { protocol: 'ui' }); // 'ui' | 'text'
+}
+```
+
+- `'ui'` → AI SDK UI message stream (for `useChat` on the frontend).
+- `'text'` → a plain text stream.
+
+### With an interceptor
+
+```ts
+import { AgentStreamInterceptor } from '@mgvdev/nestjs-ai';
+
+@UseInterceptors(new AgentStreamInterceptor({ protocol: 'ui' }))
+@Post('chat')
+chat(@Body('prompt') prompt: string) {
+  return agent.stream(prompt);   // returned stream result is piped automatically
+}
+```
+
+### Streaming structured objects
+
+When the agent has an `output` schema, `.stream()` returns a `streamObject`
+result — iterate `partialObjectStream` for progressive objects.
+
+### Realtime over WebSocket
+
+See [Background jobs & realtime](./jobs-and-realtime.md) for `AgentGateway`
+(`@mgvdev/nestjs-ai/websocket`).
+
+## Persistence during streaming
+
+When you pass a `conversationId`, the new user turn and the model's response are
+persisted on stream finish (`onFinish`), just like `run()`.

package/package.json

@@ -0,0 +1,146 @@
+{
+  "name": "@mgvdev/nestjs-ai",
+  "version": "0.1.0",
+  "description": "Structured AI toolkit for NestJS — agents, tools, structured output, streaming and embeddings on top of the Vercel AI SDK.",
+  "author": "Maxence Guyonvarho",
+  "license": "MIT",
+  "keywords": [
+    "nestjs",
+    "ai",
+    "llm",
+    "agents",
+    "tools",
+    "openai",
+    "anthropic",
+    "vercel-ai-sdk",
+    "embeddings"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./typeorm": {
+      "types": "./dist/typeorm.d.ts",
+      "import": "./dist/typeorm.js",
+      "require": "./dist/typeorm.cjs"
+    },
+    "./websocket": {
+      "types": "./dist/websocket.d.ts",
+      "import": "./dist/websocket.js",
+      "require": "./dist/websocket.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "documentation",
+    "skill",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@nestjs/event-emitter": "^2.0.0 || ^3.0.0",
+    "@nestjs/typeorm": "^10.0.0 || ^11.0.0",
+    "ai": "^7.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "rxjs": "^7.0.0",
+    "typeorm": "^0.3.0 || ^1.0.0",
+    "zod": "^3.23.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@nestjs/event-emitter": {
+      "optional": true
+    },
+    "@nestjs/typeorm": {
+      "optional": true
+    },
+    "typeorm": {
+      "optional": true
+    },
+    "bullmq": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    },
+    "@nestjs/websockets": {
+      "optional": true
+    },
+    "@nestjs/platform-socket.io": {
+      "optional": true
+    },
+    "socket.io": {
+      "optional": true
+    },
+    "@qdrant/js-client-rest": {
+      "optional": true
+    },
+    "@pinecone-database/pinecone": {
+      "optional": true
+    },
+    "msw": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^3.0.95",
+    "@ai-sdk/google": "^3.0.90",
+    "@ai-sdk/openai": "^3.0.82",
+    "@nestjs/common": "^11.0.0",
+    "@nestjs/core": "^11.0.0",
+    "@nestjs/event-emitter": "^3.1.0",
+    "@nestjs/platform-socket.io": "^11.1.28",
+    "@nestjs/testing": "^11.0.0",
+    "@nestjs/typeorm": "^11.0.3",
+    "@nestjs/websockets": "^11.1.28",
+    "@swc/core": "^1.15.43",
+    "@types/node": "^22.0.0",
+    "ai": "^7.0.17",
+    "better-sqlite3": "^12.11.1",
+    "msw": "^2.15.0",
+    "reflect-metadata": "^0.2.2",
+    "rxjs": "^7.8.1",
+    "socket.io": "^4.8.3",
+    "tsup": "^8.3.0",
+    "typeorm": "^1.0.0",
+    "typescript": "^5.6.0",
+    "unplugin-swc": "^1.5.9",
+    "vitest": "^2.1.0",
+    "zod": "^3.23.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}