@mgvdev/nestjs-ai 0.1.0

package/dist/typeorm.js

@@ -0,0 +1,113 @@
+import { PrimaryGeneratedColumn, Index, Column, Entity } from 'typeorm';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var ConversationMessageEntity = class {
+  static {
+    __name(this, "ConversationMessageEntity");
+  }
+  id;
+  conversationId;
+  role;
+  /** Message content stored as JSON to preserve structured parts. */
+  content;
+  position;
+  createdAt;
+};
+_ts_decorate([
+  PrimaryGeneratedColumn("uuid"),
+  _ts_metadata("design:type", String)
+], ConversationMessageEntity.prototype, "id", void 0);
+_ts_decorate([
+  Index(),
+  Column(),
+  _ts_metadata("design:type", String)
+], ConversationMessageEntity.prototype, "conversationId", void 0);
+_ts_decorate([
+  Column(),
+  _ts_metadata("design:type", String)
+], ConversationMessageEntity.prototype, "role", void 0);
+_ts_decorate([
+  Column({
+    type: "simple-json"
+  }),
+  _ts_metadata("design:type", Object)
+], ConversationMessageEntity.prototype, "content", void 0);
+_ts_decorate([
+  Column({
+    type: "bigint"
+  }),
+  _ts_metadata("design:type", Number)
+], ConversationMessageEntity.prototype, "position", void 0);
+_ts_decorate([
+  Column({
+    type: "datetime",
+    default: /* @__PURE__ */ __name(() => "CURRENT_TIMESTAMP", "default")
+  }),
+  _ts_metadata("design:type", typeof Date === "undefined" ? Object : Date)
+], ConversationMessageEntity.prototype, "createdAt", void 0);
+ConversationMessageEntity = _ts_decorate([
+  Entity("ai_conversation_messages")
+], ConversationMessageEntity);
+
+// src/memory/adapters/typeorm/typeorm-conversation.store.ts
+var TypeOrmConversationStore = class {
+  static {
+    __name(this, "TypeOrmConversationStore");
+  }
+  repository;
+  constructor(repository) {
+    this.repository = repository;
+  }
+  async load(conversationId) {
+    const rows = await this.repository.find({
+      where: {
+        conversationId
+      },
+      order: {
+        position: "ASC"
+      }
+    });
+    return rows.map((row) => ({
+      role: row.role,
+      content: row.content
+    }));
+  }
+  async append(conversationId, messages) {
+    if (messages.length === 0) {
+      return;
+    }
+    const base = await this.repository.count({
+      where: {
+        conversationId
+      }
+    });
+    const entities = messages.map((message, index) => this.repository.create({
+      conversationId,
+      role: message.role,
+      content: message.content,
+      position: base + index
+    }));
+    await this.repository.save(entities);
+  }
+  async clear(conversationId) {
+    await this.repository.delete({
+      conversationId
+    });
+  }
+};
+
+export { ConversationMessageEntity, TypeOrmConversationStore };
+//# sourceMappingURL=typeorm.js.map
+//# sourceMappingURL=typeorm.js.map

package/dist/typeorm.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/memory/adapters/typeorm/conversation-message.entity.ts","../src/memory/adapters/typeorm/typeorm-conversation.store.ts"],"names":["ConversationMessageEntity","id","conversationId","role","content","position","createdAt","type","default","TypeOrmConversationStore","repository","load","rows","find","where","order","map","row","append","messages","length","base","count","entities","message","index","create","save","clear","delete"],"mappings":";;;;;;;;;;;;;;;AAQO,IAAMA,4BAAN,MAAMA;AAAAA,EAAAA;;;AAEXC,EAAAA,EAAAA;AAIAC,EAAAA,cAAAA;AAGAC,EAAAA,IAAAA;;AAIAC,EAAAA,OAAAA;AAGAC,EAAAA,QAAAA;AAGAC,EAAAA,SAAAA;AACF;;;;;;;;;;;;;;;;IARYC,IAAAA,EAAM;;;;;;IAGNA,IAAAA,EAAM;;;;;;IAGNA,IAAAA,EAAM,UAAA;AAAYC,IAAAA,OAAAA,+BAAe,mBAAA,EAAN,SAAA;;;;;;;;;ACLhC,IAAMC,2BAAN,MAAMA;EAhBb;;;;AAiBE,EAAA,WAAA,CACmBC,UAAAA,EACjB;SADiBA,UAAAA,GAAAA,UAAAA;AAChB,EAAA;AAEH,EAAA,MAAMC,KAAKT,cAAAA,EAA8C;AACvD,IAAA,MAAMU,IAAAA,GAAO,MAAM,IAAA,CAAKF,UAAAA,CAAWG,IAAAA,CAAK;MACtCC,KAAAA,EAAO;AAAEZ,QAAAA;AAAe,OAAA;MACxBa,KAAAA,EAAO;QAAEV,QAAAA,EAAU;AAAM;KAC3B,CAAA;AACA,IAAA,OAAOO,IAAAA,CAAKI,GAAAA,CAAI,CAACC,GAAAA,MAAS;AACxBd,MAAAA,IAAAA,EAAMc,GAAAA,CAAId,IAAAA;AACVC,MAAAA,OAAAA,EAASa,GAAAA,CAAIb;KACf,CAAA,CAAA;AACF,EAAA;EAEA,MAAMc,MAAAA,CACJhB,gBACAiB,QAAAA,EACe;AACf,IAAA,IAAIA,QAAAA,CAASC,WAAW,CAAA,EAAG;AACzB,MAAA;AACF,IAAA;AACA,IAAA,MAAMC,IAAAA,GAAO,MAAM,IAAA,CAAKX,UAAAA,CAAWY,KAAAA,CAAM;MAAER,KAAAA,EAAO;AAAEZ,QAAAA;AAAe;KAAE,CAAA;AACrE,IAAA,MAAMqB,QAAAA,GAAWJ,SAASH,GAAAA,CAAI,CAACQ,SAASC,KAAAA,KACtC,IAAA,CAAKf,WAAWgB,MAAAA,CAAO;AACrBxB,MAAAA,cAAAA;AACAC,MAAAA,IAAAA,EAAMqB,OAAAA,CAAQrB,IAAAA;AACdC,MAAAA,OAAAA,EAASoB,OAAAA,CAAQpB,OAAAA;AACjBC,MAAAA,QAAAA,EAAUgB,IAAAA,GAAOI;AACnB,KAAA,CAAA,CAAA;AAEF,IAAA,MAAM,IAAA,CAAKf,UAAAA,CAAWiB,IAAAA,CAAKJ,QAAAA,CAAAA;AAC7B,EAAA;AAEA,EAAA,MAAMK,MAAM1B,cAAAA,EAAuC;AACjD,IAAA,MAAM,IAAA,CAAKQ,WAAWmB,MAAAA,CAAO;AAAE3B,MAAAA;KAAe,CAAA;AAChD,EAAA;AACF","file":"typeorm.js","sourcesContent":["import { Column, Entity, Index, PrimaryGeneratedColumn } from 'typeorm';\n\n/**\n * Persisted conversation message. Register this entity in your TypeORM\n * `DataSource` (`entities: [ConversationMessageEntity]`) and wire\n * `TypeOrmConversationStore` as the module's `conversationStore`.\n */\n@Entity('ai_conversation_messages')\nexport class ConversationMessageEntity {\n  @PrimaryGeneratedColumn('uuid')\n  id!: string;\n\n  @Index()\n  @Column()\n  conversationId!: string;\n\n  @Column()\n  role!: string;\n\n  /** Message content stored as JSON to preserve structured parts. */\n  @Column({ type: 'simple-json' })\n  content!: unknown;\n\n  @Column({ type: 'bigint' })\n  position!: number;\n\n  @Column({ type: 'datetime', default: () => 'CURRENT_TIMESTAMP' })\n  createdAt!: Date;\n}\n","import type { Repository } from 'typeorm';\nimport type { AiMessage } from '../../../messages/message.types.js';\nimport type { ConversationStore } from '../../conversation-store.interface.js';\nimport { ConversationMessageEntity } from './conversation-message.entity.js';\n\n/**\n * TypeORM-backed conversation store. Framework-agnostic: pass a\n * `Repository<ConversationMessageEntity>` (obtain it via `@nestjs/typeorm`'s\n * `getRepositoryToken` in a factory provider). Messages are ordered by an\n * append-only `position` column.\n *\n * @example\n * ```ts\n * AiModule.forRoot({\n *   conversationStore: {\n *     useFactory: (repo) => new TypeOrmConversationStore(repo),\n *     inject: [getRepositoryToken(ConversationMessageEntity)],\n *   },\n * })\n * ```\n */\nexport class TypeOrmConversationStore implements ConversationStore {\n  constructor(\n    private readonly repository: Repository<ConversationMessageEntity>,\n  ) {}\n\n  async load(conversationId: string): Promise<AiMessage[]> {\n    const rows = await this.repository.find({\n      where: { conversationId },\n      order: { position: 'ASC' },\n    });\n    return rows.map((row) => ({\n      role: row.role,\n      content: row.content,\n    })) as AiMessage[];\n  }\n\n  async append(\n    conversationId: string,\n    messages: AiMessage[],\n  ): Promise<void> {\n    if (messages.length === 0) {\n      return;\n    }\n    const base = await this.repository.count({ where: { conversationId } });\n    const entities = messages.map((message, index) =>\n      this.repository.create({\n        conversationId,\n        role: message.role,\n        content: message.content,\n        position: base + index,\n      }),\n    );\n    await this.repository.save(entities);\n  }\n\n  async clear(conversationId: string): Promise<void> {\n    await this.repository.delete({ conversationId });\n  }\n}\n"]}

package/dist/websocket.cjs

@@ -0,0 +1,154 @@
+'use strict';
+
+var websockets = require('@nestjs/websockets');
+var common = require('@nestjs/common');
+var core = require('@nestjs/core');
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/ai.constants.ts
+var AGENT_METADATA = /* @__PURE__ */ Symbol("nestjs-ai:agent");
+
+// src/agent/orchestration/agent-registry.ts
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var AgentRegistry = class {
+  static {
+    __name(this, "AgentRegistry");
+  }
+  discovery;
+  agents = /* @__PURE__ */ new Map();
+  constructor(discovery) {
+    this.discovery = discovery;
+  }
+  onModuleInit() {
+    for (const wrapper of this.discovery.getProviders()) {
+      const instance = wrapper.instance;
+      const ctor = instance?.constructor;
+      if (instance && ctor && Reflect.getMetadata(AGENT_METADATA, ctor)) {
+        this.agents.set(ctor.name, {
+          name: ctor.name,
+          instance,
+          target: ctor
+        });
+      }
+    }
+  }
+  /** Returns an agent instance by class name. */
+  get(name) {
+    return this.agents.get(name)?.instance;
+  }
+  /** Returns an agent instance by its class. */
+  getByClass(target) {
+    return this.agents.get(target.name)?.instance;
+  }
+  /** All discovered agents. */
+  all() {
+    return [
+      ...this.agents.values()
+    ];
+  }
+};
+AgentRegistry = _ts_decorate([
+  common.Injectable(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof core.DiscoveryService === "undefined" ? Object : core.DiscoveryService
+  ])
+], AgentRegistry);
+
+// src/websocket/stream-to-socket.ts
+async function streamAgentToSocket(stream, socket, options = {}) {
+  const chunkEvent = options.chunkEvent ?? "agent:chunk";
+  const doneEvent = options.doneEvent ?? "agent:done";
+  const errorEvent = options.errorEvent ?? "agent:error";
+  try {
+    let text = "";
+    for await (const delta of stream.textStream) {
+      text += delta;
+      socket.emit(chunkEvent, {
+        delta
+      });
+    }
+    socket.emit(doneEvent, {
+      text
+    });
+    return text;
+  } catch (error) {
+    socket.emit(errorEvent, {
+      message: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+__name(streamAgentToSocket, "streamAgentToSocket");
+
+// src/websocket/agent.gateway.ts
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+exports.AgentGateway = class AgentGateway {
+  static {
+    __name(this, "AgentGateway");
+  }
+  agents;
+  constructor(agents) {
+    this.agents = agents;
+  }
+  async run(message, client) {
+    const agent = this.agents.get(message.agent);
+    if (!agent) {
+      client.emit("agent:error", {
+        message: `Unknown agent "${message.agent}".`
+      });
+      return;
+    }
+    await streamAgentToSocket(agent.stream(message.input), client);
+  }
+};
+_ts_decorate2([
+  websockets.SubscribeMessage("agent:run"),
+  _ts_param(0, websockets.MessageBody()),
+  _ts_param(1, websockets.ConnectedSocket()),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof AgentRunMessage === "undefined" ? Object : AgentRunMessage,
+    typeof SocketLike === "undefined" ? Object : SocketLike
+  ]),
+  _ts_metadata2("design:returntype", Promise)
+], exports.AgentGateway.prototype, "run", null);
+exports.AgentGateway = _ts_decorate2([
+  websockets.WebSocketGateway(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof AgentRegistry === "undefined" ? Object : AgentRegistry
+  ])
+], exports.AgentGateway);
+
+exports.streamAgentToSocket = streamAgentToSocket;
+//# sourceMappingURL=websocket.cjs.map
+//# sourceMappingURL=websocket.cjs.map

package/dist/websocket.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ai.constants.ts","../src/agent/orchestration/agent-registry.ts","../src/websocket/stream-to-socket.ts","../src/websocket/agent.gateway.ts"],"names":["AGENT_METADATA","AgentRegistry","agents","Map","discovery","onModuleInit","wrapper","getProviders","instance","ctor","Reflect","getMetadata","set","name","target","get","getByClass","all","values","streamAgentToSocket","stream","socket","options","chunkEvent","doneEvent","errorEvent","text","delta","textStream","emit","error","message","Error","String","AgentGateway","run","client","agent","input"],"mappings":"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","file":"websocket.cjs","sourcesContent":["/**\n * Dependency-injection tokens used across the module.\n */\nexport const AI_MODULE_OPTIONS = Symbol('AI_MODULE_OPTIONS');\nexport const CONVERSATION_STORE = Symbol('CONVERSATION_STORE');\nexport const VECTOR_STORE = Symbol('VECTOR_STORE');\nexport const AI_CACHE = Symbol('AI_CACHE');\nexport const APPROVAL_GATE = Symbol('APPROVAL_GATE');\nexport const AGENT_QUEUE = Symbol('AGENT_QUEUE');\nexport const RATE_LIMITER = Symbol('RATE_LIMITER');\nexport const RERANKER = Symbol('RERANKER');\n\n/**\n * Reflect metadata keys for the `@Tool` and `@Agent` decorators.\n */\nexport const TOOL_METADATA = Symbol('nestjs-ai:tool');\nexport const AGENT_METADATA = Symbol('nestjs-ai:agent');\nexport const GUARDRAIL_METADATA = Symbol('nestjs-ai:guardrail');\n\n/**\n * Default number of tool-calling steps allowed before an agent run stops.\n */\nexport const DEFAULT_MAX_STEPS = 5;\n","import { Injectable, type OnModuleInit, type Type } from '@nestjs/common';\nimport { DiscoveryService } from '@nestjs/core';\nimport { AGENT_METADATA } from '../../ai.constants.js';\n\n/** A discovered agent instance and its class. */\nexport interface AgentEntry {\n  name: string;\n  instance: any;\n  target: Type<any>;\n}\n\n/**\n * Indexes every `@Agent`-decorated provider by class name, enabling\n * multi-agent orchestration (supervisor/handoff) and background-job resolution.\n */\n@Injectable()\nexport class AgentRegistry implements OnModuleInit {\n  private readonly agents = new Map<string, AgentEntry>();\n\n  constructor(private readonly discovery: DiscoveryService) {}\n\n  onModuleInit(): void {\n    for (const wrapper of this.discovery.getProviders()) {\n      const instance = wrapper.instance;\n      const ctor = instance?.constructor as Type<any> | undefined;\n      if (instance && ctor && Reflect.getMetadata(AGENT_METADATA, ctor)) {\n        this.agents.set(ctor.name, { name: ctor.name, instance, target: ctor });\n      }\n    }\n  }\n\n  /** Returns an agent instance by class name. */\n  get(name: string): any | undefined {\n    return this.agents.get(name)?.instance;\n  }\n\n  /** Returns an agent instance by its class. */\n  getByClass(target: Type<any>): any | undefined {\n    return this.agents.get(target.name)?.instance;\n  }\n\n  /** All discovered agents. */\n  all(): AgentEntry[] {\n    return [...this.agents.values()];\n  }\n}\n","/** Minimal socket shape (compatible with socket.io's `Socket`). */\nexport interface SocketLike {\n  emit(event: string, payload?: unknown): void;\n}\n\n/** A stream result exposing a text stream (from agent `.stream()`). */\nexport interface TextStreamLike {\n  textStream: AsyncIterable<string>;\n}\n\nexport interface StreamToSocketOptions {\n  chunkEvent?: string;\n  doneEvent?: string;\n  errorEvent?: string;\n}\n\n/**\n * Forwards an agent text stream to a socket: emits `chunkEvent` per delta, then\n * `doneEvent` with the full text; emits `errorEvent` and rethrows on failure.\n * Framework-agnostic — the WebSocket gateway is thin glue over this.\n */\nexport async function streamAgentToSocket(\n  stream: TextStreamLike,\n  socket: SocketLike,\n  options: StreamToSocketOptions = {},\n): Promise<string> {\n  const chunkEvent = options.chunkEvent ?? 'agent:chunk';\n  const doneEvent = options.doneEvent ?? 'agent:done';\n  const errorEvent = options.errorEvent ?? 'agent:error';\n\n  try {\n    let text = '';\n    for await (const delta of stream.textStream) {\n      text += delta;\n      socket.emit(chunkEvent, { delta });\n    }\n    socket.emit(doneEvent, { text });\n    return text;\n  } catch (error) {\n    socket.emit(errorEvent, {\n      message: error instanceof Error ? error.message : String(error),\n    });\n    throw error;\n  }\n}\n","import {\n  ConnectedSocket,\n  MessageBody,\n  SubscribeMessage,\n  WebSocketGateway,\n} from '@nestjs/websockets';\nimport { AgentRegistry } from '../agent/orchestration/agent-registry.js';\nimport {\n  streamAgentToSocket,\n  type SocketLike,\n} from './stream-to-socket.js';\n\n/** Payload for the `agent:run` message. */\nexport interface AgentRunMessage {\n  agent: string;\n  input: string;\n}\n\n/**\n * WebSocket gateway that streams agent responses over socket.io. Client emits\n * `agent:run { agent, input }`; the server streams `agent:chunk { delta }` then\n * `agent:done { text }`. Requires the optional peers `@nestjs/websockets`,\n * `@nestjs/platform-socket.io`, and `socket.io`.\n *\n * Published under `@mgvdev/nestjs-ai/websocket`.\n */\n@WebSocketGateway()\nexport class AgentGateway {\n  constructor(private readonly agents: AgentRegistry) {}\n\n  @SubscribeMessage('agent:run')\n  async run(\n    @MessageBody() message: AgentRunMessage,\n    @ConnectedSocket() client: SocketLike,\n  ): Promise<void> {\n    const agent = this.agents.get(message.agent);\n    if (!agent) {\n      client.emit('agent:error', {\n        message: `Unknown agent \"${message.agent}\".`,\n      });\n      return;\n    }\n    await streamAgentToSocket(agent.stream(message.input), client);\n  }\n}\n"]}

package/dist/websocket.d.cts

@@ -0,0 +1,25 @@
+import { A as AgentRegistry, S as SocketLike } from './stream-to-socket-fJphU0WN.cjs';
+export { b as StreamToSocketOptions, T as TextStreamLike, s as streamAgentToSocket } from './stream-to-socket-fJphU0WN.cjs';
+import '@nestjs/common';
+import '@nestjs/core';
+
+/** Payload for the `agent:run` message. */
+interface AgentRunMessage {
+    agent: string;
+    input: string;
+}
+/**
+ * WebSocket gateway that streams agent responses over socket.io. Client emits
+ * `agent:run { agent, input }`; the server streams `agent:chunk { delta }` then
+ * `agent:done { text }`. Requires the optional peers `@nestjs/websockets`,
+ * `@nestjs/platform-socket.io`, and `socket.io`.
+ *
+ * Published under `@mgvdev/nestjs-ai/websocket`.
+ */
+declare class AgentGateway {
+    private readonly agents;
+    constructor(agents: AgentRegistry);
+    run(message: AgentRunMessage, client: SocketLike): Promise<void>;
+}
+
+export { AgentGateway, type AgentRunMessage, SocketLike };

package/dist/websocket.d.ts

@@ -0,0 +1,25 @@
+import { A as AgentRegistry, S as SocketLike } from './stream-to-socket-fJphU0WN.js';
+export { b as StreamToSocketOptions, T as TextStreamLike, s as streamAgentToSocket } from './stream-to-socket-fJphU0WN.js';
+import '@nestjs/common';
+import '@nestjs/core';
+
+/** Payload for the `agent:run` message. */
+interface AgentRunMessage {
+    agent: string;
+    input: string;
+}
+/**
+ * WebSocket gateway that streams agent responses over socket.io. Client emits
+ * `agent:run { agent, input }`; the server streams `agent:chunk { delta }` then
+ * `agent:done { text }`. Requires the optional peers `@nestjs/websockets`,
+ * `@nestjs/platform-socket.io`, and `socket.io`.
+ *
+ * Published under `@mgvdev/nestjs-ai/websocket`.
+ */
+declare class AgentGateway {
+    private readonly agents;
+    constructor(agents: AgentRegistry);
+    run(message: AgentRunMessage, client: SocketLike): Promise<void>;
+}
+
+export { AgentGateway, type AgentRunMessage, SocketLike };

package/dist/websocket.js

@@ -0,0 +1,152 @@
+import { SubscribeMessage, MessageBody, ConnectedSocket, WebSocketGateway } from '@nestjs/websockets';
+import { Injectable } from '@nestjs/common';
+import { DiscoveryService } from '@nestjs/core';
+
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/ai.constants.ts
+var AGENT_METADATA = /* @__PURE__ */ Symbol("nestjs-ai:agent");
+
+// src/agent/orchestration/agent-registry.ts
+function _ts_decorate(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate, "_ts_decorate");
+function _ts_metadata(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata, "_ts_metadata");
+var AgentRegistry = class {
+  static {
+    __name(this, "AgentRegistry");
+  }
+  discovery;
+  agents = /* @__PURE__ */ new Map();
+  constructor(discovery) {
+    this.discovery = discovery;
+  }
+  onModuleInit() {
+    for (const wrapper of this.discovery.getProviders()) {
+      const instance = wrapper.instance;
+      const ctor = instance?.constructor;
+      if (instance && ctor && Reflect.getMetadata(AGENT_METADATA, ctor)) {
+        this.agents.set(ctor.name, {
+          name: ctor.name,
+          instance,
+          target: ctor
+        });
+      }
+    }
+  }
+  /** Returns an agent instance by class name. */
+  get(name) {
+    return this.agents.get(name)?.instance;
+  }
+  /** Returns an agent instance by its class. */
+  getByClass(target) {
+    return this.agents.get(target.name)?.instance;
+  }
+  /** All discovered agents. */
+  all() {
+    return [
+      ...this.agents.values()
+    ];
+  }
+};
+AgentRegistry = _ts_decorate([
+  Injectable(),
+  _ts_metadata("design:type", Function),
+  _ts_metadata("design:paramtypes", [
+    typeof DiscoveryService === "undefined" ? Object : DiscoveryService
+  ])
+], AgentRegistry);
+
+// src/websocket/stream-to-socket.ts
+async function streamAgentToSocket(stream, socket, options = {}) {
+  const chunkEvent = options.chunkEvent ?? "agent:chunk";
+  const doneEvent = options.doneEvent ?? "agent:done";
+  const errorEvent = options.errorEvent ?? "agent:error";
+  try {
+    let text = "";
+    for await (const delta of stream.textStream) {
+      text += delta;
+      socket.emit(chunkEvent, {
+        delta
+      });
+    }
+    socket.emit(doneEvent, {
+      text
+    });
+    return text;
+  } catch (error) {
+    socket.emit(errorEvent, {
+      message: error instanceof Error ? error.message : String(error)
+    });
+    throw error;
+  }
+}
+__name(streamAgentToSocket, "streamAgentToSocket");
+
+// src/websocket/agent.gateway.ts
+function _ts_decorate2(decorators, target, key, desc) {
+  var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+  else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+__name(_ts_decorate2, "_ts_decorate");
+function _ts_metadata2(k, v) {
+  if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+__name(_ts_metadata2, "_ts_metadata");
+function _ts_param(paramIndex, decorator) {
+  return function(target, key) {
+    decorator(target, key, paramIndex);
+  };
+}
+__name(_ts_param, "_ts_param");
+var AgentGateway = class {
+  static {
+    __name(this, "AgentGateway");
+  }
+  agents;
+  constructor(agents) {
+    this.agents = agents;
+  }
+  async run(message, client) {
+    const agent = this.agents.get(message.agent);
+    if (!agent) {
+      client.emit("agent:error", {
+        message: `Unknown agent "${message.agent}".`
+      });
+      return;
+    }
+    await streamAgentToSocket(agent.stream(message.input), client);
+  }
+};
+_ts_decorate2([
+  SubscribeMessage("agent:run"),
+  _ts_param(0, MessageBody()),
+  _ts_param(1, ConnectedSocket()),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof AgentRunMessage === "undefined" ? Object : AgentRunMessage,
+    typeof SocketLike === "undefined" ? Object : SocketLike
+  ]),
+  _ts_metadata2("design:returntype", Promise)
+], AgentGateway.prototype, "run", null);
+AgentGateway = _ts_decorate2([
+  WebSocketGateway(),
+  _ts_metadata2("design:type", Function),
+  _ts_metadata2("design:paramtypes", [
+    typeof AgentRegistry === "undefined" ? Object : AgentRegistry
+  ])
+], AgentGateway);
+
+export { AgentGateway, streamAgentToSocket };
+//# sourceMappingURL=websocket.js.map
+//# sourceMappingURL=websocket.js.map

package/dist/websocket.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/ai.constants.ts","../src/agent/orchestration/agent-registry.ts","../src/websocket/stream-to-socket.ts","../src/websocket/agent.gateway.ts"],"names":["AGENT_METADATA","AgentRegistry","agents","Map","discovery","onModuleInit","wrapper","getProviders","instance","ctor","Reflect","getMetadata","set","name","target","get","getByClass","all","values","streamAgentToSocket","stream","socket","options","chunkEvent","doneEvent","errorEvent","text","delta","textStream","emit","error","message","Error","String","AgentGateway","run","client","agent","input"],"mappings":"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","file":"websocket.js","sourcesContent":["/**\n * Dependency-injection tokens used across the module.\n */\nexport const AI_MODULE_OPTIONS = Symbol('AI_MODULE_OPTIONS');\nexport const CONVERSATION_STORE = Symbol('CONVERSATION_STORE');\nexport const VECTOR_STORE = Symbol('VECTOR_STORE');\nexport const AI_CACHE = Symbol('AI_CACHE');\nexport const APPROVAL_GATE = Symbol('APPROVAL_GATE');\nexport const AGENT_QUEUE = Symbol('AGENT_QUEUE');\nexport const RATE_LIMITER = Symbol('RATE_LIMITER');\nexport const RERANKER = Symbol('RERANKER');\n\n/**\n * Reflect metadata keys for the `@Tool` and `@Agent` decorators.\n */\nexport const TOOL_METADATA = Symbol('nestjs-ai:tool');\nexport const AGENT_METADATA = Symbol('nestjs-ai:agent');\nexport const GUARDRAIL_METADATA = Symbol('nestjs-ai:guardrail');\n\n/**\n * Default number of tool-calling steps allowed before an agent run stops.\n */\nexport const DEFAULT_MAX_STEPS = 5;\n","import { Injectable, type OnModuleInit, type Type } from '@nestjs/common';\nimport { DiscoveryService } from '@nestjs/core';\nimport { AGENT_METADATA } from '../../ai.constants.js';\n\n/** A discovered agent instance and its class. */\nexport interface AgentEntry {\n  name: string;\n  instance: any;\n  target: Type<any>;\n}\n\n/**\n * Indexes every `@Agent`-decorated provider by class name, enabling\n * multi-agent orchestration (supervisor/handoff) and background-job resolution.\n */\n@Injectable()\nexport class AgentRegistry implements OnModuleInit {\n  private readonly agents = new Map<string, AgentEntry>();\n\n  constructor(private readonly discovery: DiscoveryService) {}\n\n  onModuleInit(): void {\n    for (const wrapper of this.discovery.getProviders()) {\n      const instance = wrapper.instance;\n      const ctor = instance?.constructor as Type<any> | undefined;\n      if (instance && ctor && Reflect.getMetadata(AGENT_METADATA, ctor)) {\n        this.agents.set(ctor.name, { name: ctor.name, instance, target: ctor });\n      }\n    }\n  }\n\n  /** Returns an agent instance by class name. */\n  get(name: string): any | undefined {\n    return this.agents.get(name)?.instance;\n  }\n\n  /** Returns an agent instance by its class. */\n  getByClass(target: Type<any>): any | undefined {\n    return this.agents.get(target.name)?.instance;\n  }\n\n  /** All discovered agents. */\n  all(): AgentEntry[] {\n    return [...this.agents.values()];\n  }\n}\n","/** Minimal socket shape (compatible with socket.io's `Socket`). */\nexport interface SocketLike {\n  emit(event: string, payload?: unknown): void;\n}\n\n/** A stream result exposing a text stream (from agent `.stream()`). */\nexport interface TextStreamLike {\n  textStream: AsyncIterable<string>;\n}\n\nexport interface StreamToSocketOptions {\n  chunkEvent?: string;\n  doneEvent?: string;\n  errorEvent?: string;\n}\n\n/**\n * Forwards an agent text stream to a socket: emits `chunkEvent` per delta, then\n * `doneEvent` with the full text; emits `errorEvent` and rethrows on failure.\n * Framework-agnostic — the WebSocket gateway is thin glue over this.\n */\nexport async function streamAgentToSocket(\n  stream: TextStreamLike,\n  socket: SocketLike,\n  options: StreamToSocketOptions = {},\n): Promise<string> {\n  const chunkEvent = options.chunkEvent ?? 'agent:chunk';\n  const doneEvent = options.doneEvent ?? 'agent:done';\n  const errorEvent = options.errorEvent ?? 'agent:error';\n\n  try {\n    let text = '';\n    for await (const delta of stream.textStream) {\n      text += delta;\n      socket.emit(chunkEvent, { delta });\n    }\n    socket.emit(doneEvent, { text });\n    return text;\n  } catch (error) {\n    socket.emit(errorEvent, {\n      message: error instanceof Error ? error.message : String(error),\n    });\n    throw error;\n  }\n}\n","import {\n  ConnectedSocket,\n  MessageBody,\n  SubscribeMessage,\n  WebSocketGateway,\n} from '@nestjs/websockets';\nimport { AgentRegistry } from '../agent/orchestration/agent-registry.js';\nimport {\n  streamAgentToSocket,\n  type SocketLike,\n} from './stream-to-socket.js';\n\n/** Payload for the `agent:run` message. */\nexport interface AgentRunMessage {\n  agent: string;\n  input: string;\n}\n\n/**\n * WebSocket gateway that streams agent responses over socket.io. Client emits\n * `agent:run { agent, input }`; the server streams `agent:chunk { delta }` then\n * `agent:done { text }`. Requires the optional peers `@nestjs/websockets`,\n * `@nestjs/platform-socket.io`, and `socket.io`.\n *\n * Published under `@mgvdev/nestjs-ai/websocket`.\n */\n@WebSocketGateway()\nexport class AgentGateway {\n  constructor(private readonly agents: AgentRegistry) {}\n\n  @SubscribeMessage('agent:run')\n  async run(\n    @MessageBody() message: AgentRunMessage,\n    @ConnectedSocket() client: SocketLike,\n  ): Promise<void> {\n    const agent = this.agents.get(message.agent);\n    if (!agent) {\n      client.emit('agent:error', {\n        message: `Unknown agent \"${message.agent}\".`,\n      });\n      return;\n    }\n    await streamAgentToSocket(agent.stream(message.input), client);\n  }\n}\n"]}

package/documentation/README.md

@@ -0,0 +1,44 @@
+# @mgvdev/nestjs-ai — Documentation
+
+A NestJS toolkit over the [Vercel AI SDK](https://ai-sdk.dev) (v7): DI-native
+agents, tools, structured output, streaming, embeddings, RAG, multimodal,
+prompts, guardrails, orchestration, MCP, and production features (cost, rate
+limiting, memory, evals).
+
+## Table of contents
+
+1. [Getting started](./getting-started.md)
+2. [Configuration](./configuration.md)
+3. [Agents & tools](./agents-and-tools.md)
+4. [Structured output & streaming](./structured-output-and-streaming.md)
+5. [Embeddings & RAG](./embeddings-and-rag.md)
+6. [Multimodal (image / speech / transcription)](./multimodal.md)
+7. [Prompt registry](./prompts.md)
+8. [Memory (conversation & semantic)](./memory.md)
+9. [Guardrails, events & telemetry](./guardrails-events-telemetry.md)
+10. [Content safety (PII & moderation)](./content-safety.md)
+11. [Orchestration & MCP](./orchestration-and-mcp.md)
+12. [Reliability (fallback, retry, cache, rate limit, budgets)](./reliability.md)
+13. [Background jobs & realtime](./jobs-and-realtime.md)
+14. [Evals & testing](./evals-and-testing.md)
+15. [API reference](./api-reference.md)
+
+## Entry points
+
+| Import | Contents |
+| --- | --- |
+| `@mgvdev/nestjs-ai` | Everything except the adapters below |
+| `@mgvdev/nestjs-ai/typeorm` | `TypeOrmConversationStore`, `ConversationMessageEntity` |
+| `@mgvdev/nestjs-ai/websocket` | `AgentGateway` |
+| `@mgvdev/nestjs-ai/testing` | `createTestingAiModule`, `createMockModel` |
+
+## Peer dependencies
+
+**Required:** `@nestjs/common`, `@nestjs/core`, `ai`, `zod`, `reflect-metadata`, `rxjs`.
+
+**Optional** (install per feature): `@ai-sdk/openai` · `@ai-sdk/anthropic` ·
+`@ai-sdk/google` · `@ai-sdk/cohere` (reranking) · `@nestjs/event-emitter`
+(events) · `@nestjs/typeorm` + `typeorm` (TypeORM store) · `bullmq` (jobs) ·
+`pg` (pgvector) · `@qdrant/js-client-rest` · `@pinecone-database/pinecone` ·
+`@nestjs/websockets` + `@nestjs/platform-socket.io` + `socket.io` (realtime) ·
+`@modelcontextprotocol/sdk` (MCP) · `msw` (testing).

package/documentation/agents-and-tools.md

@@ -0,0 +1,102 @@
+# Agents & tools
+
+## Tools
+
+A tool is a method on an injectable provider, decorated with `@Tool`. It keeps
+full access to injected dependencies.
+
+```ts
+@Injectable()
+export class WeatherTools {
+  constructor(private readonly api: WeatherApi) {}
+
+  @Tool({
+    name: 'get_weather',                 // optional; defaults to the method name
+    description: 'Get the weather for a city',
+    schema: z.object({ city: z.string() }),
+    requiresApproval: false,             // gate behind an ApprovalGate when true
+  })
+  getWeather({ city }: { city: string }) {
+    return this.api.lookup(city);        // return value is fed back to the model
+  }
+}
+```
+
+- **`schema`** is a Zod schema for the arguments; the method receives the parsed object.
+- The return value (any JSON-serializable value) is returned to the model.
+- Tools are discovered automatically once the class is a registered provider.
+
+### `ToolRegistry`
+
+Introspect discovered tools:
+
+```ts
+constructor(private readonly tools: ToolRegistry) {}
+this.tools.getAll();                 // ToolEntry[]
+this.tools.getByName('get_weather');
+this.tools.buildToolSet([WeatherTools, 'get_weather']); // for AiService
+```
+
+## Agents
+
+Extend `AiAgent` and annotate with `@Agent`.
+
+```ts
+@Agent({
+  model: 'openai:gpt-4o',              // string | string[] (fallback)
+  system: 'You are a helpful assistant.',
+  tools: [WeatherTools],               // @Tool providers and/or @Agent sub-agents
+  maxSteps: 5,                         // tool-calling loop bound
+  output: z.object({ answer: z.string() }), // optional structured output
+})
+export class SupportAgent extends AiAgent {}
+```
+
+### Running
+
+```ts
+const { text, usage, steps, toolCalls } = await agent.run('Weather in Paris?');
+const { object } = await agent.run<Shape>(input);   // when `output`/`schema` set
+const stream = agent.stream('Hi');                  // Vercel stream result
+```
+
+### `AgentRunOptions`
+
+```ts
+await agent.run(input, {
+  model,                       // override model / fallback chain
+  system,                      // override system prompt
+  systemPrompt: { name, vars, version }, // resolve from PromptRegistry
+  conversationId,              // load + persist history
+  maxSteps,
+  schema,                      // structured output for this call
+  temperature,
+  maxRetries,
+  recall: { query?, topK? },   // prepend semantic-memory context
+  abortSignal,
+});
+```
+
+`run()` returns an `AgentResult`: `{ text, object?, steps?, toolCalls?, usage?, finishReason?, messages }`.
+
+## The raw facade — `AiService`
+
+When you don't want an agent class:
+
+```ts
+const { text } = await this.ai.generateText({
+  model: 'openai:gpt-4o',
+  tools: [WeatherTools],       // tool provider classes and/or names
+  prompt: 'Weather in Paris?',
+});
+```
+
+`AiService` mirrors `generateText` / `streamText` / `generateObject` /
+`streamObject`, resolving `model` strings and `tools` references for you.
+
+## How the tool loop works
+
+`run()` calls the model with the resolved tools and `stopWhen: stepCountIs(maxSteps)`.
+When the model emits a tool call, the SDK executes the matching `@Tool` method on
+its DI instance, feeds the result back, and continues until the model produces a
+final answer or `maxSteps` is reached.