ai.module.ts · Source

ai.module.tsapps/api/src/modules/ai/ai.module.tsraw ← ai5,232 B← Back to the app
1/**
2 * AI module (Phase 12, TASK-0121).
3 *
4 * Wires the `@factory/ai` `AiGateway` into the API:
5 *
6 *   - `AI_LEDGER` ({@link AiLedgerService}) — the gateway's usage sink
7 *     (observability; the durable `ai_messages` rows are written by the
8 *     feature services — see the ledger service's module doc).
9 *   - `AI_GATEWAY` — the gateway (provider registry + config resolution
10 *     from `workspace.settings.ai` over the env defaults).
11 *   - `AiBudgetGuardService` — the service-level, Postgres-backed budget
12 *     guard every AI endpoint awaits BEFORE the gateway call (402
13 *     `AI_BUDGET_EXCEEDED` / 429); on exhaustion it notifies admins +
14 *     writes the `ai.budget_exceeded` audit event (24 h throttle).
15 *
16 * Provider selection is configuration-only (`AI_PROVIDER`/`AI_BASE_URL`/
17 * `AI_API_KEY`/`AI_MODEL` env or `workspace.settings.ai`): swapping the
18 * provider changes zero application code (ROADMAP Phase 12 exit criterion).
19 */
20import { Module } from "@nestjs/common";
21import { m } from "@factory/observability";
22import { NotificationsModule } from "../notifications/notifications.module.js";
23import { AiChatService } from "./ai-chat.service.js";
24import { AiController } from "./ai.controller.js";
25import { AiService } from "./ai.service.js";
26import { AI_GATEWAY, buildAiGateway } from "./gateway-provider.js";
27import { AiLedgerService, AI_LEDGER } from "./ledger.service.js";
28import { AiBudgetGuardService } from "./budget-guard.service.js";
29import { AiRateLimitService } from "./ai-rate-limit.js";
30import { AiWritingService } from "./ai-writing.service.js";
31import { AiWritingController } from "./ai-writing.controller.js";
32import { DatabaseAiService } from "./database-ai.service.js";
33import { DatabaseAiController } from "./database-ai.controller.js";
34import { BlocksModule } from "../blocks/blocks.module.js";
35import { DatabasesModule } from "../databases/databases.module.js";
36import { PagesModule } from "../pages/pages.module.js";
37import { SearchModule } from "../search/search.module.js";
38import { TasksModule } from "../tasks/tasks.module.js";
39import { RagService } from "./rag.service.js";
40import { RagController } from "./rag.controller.js";
41import { AiGenerateService } from "./generator/generate.service.js";
42import { AiGenerateController } from "./generator/generate.controller.js";
43import { AssistantService } from "./assistant/assistant.service.js";
44import { AssistantController } from "./assistant/assistant.controller.js";
45 
46@Module({
47  // SearchModule exports SearchService — the RAG query path reuses its
48  // fail-closed viewer resolver + the same OpenSearch client (no duplicate
49  // permission-filter implementation — the spec's Security requirement).
50  imports: [NotificationsModule, BlocksModule, DatabasesModule, PagesModule, SearchModule, TasksModule],
51  controllers: [AiController, AiWritingController, DatabaseAiController, RagController, AiGenerateController, AssistantController],
52  providers: [
53    { provide: AI_LEDGER, useClass: AiLedgerService },
54    AiBudgetGuardService,
55    {
56      provide: AI_GATEWAY,
57      // Explicit `inject`: `useFactory` params have no `design:paramtypes`
58      // metadata to infer from, so without it Nest calls the factory with
59      // zero args and the ledger sink is undefined (caught by the TASK-0121
60      // capability suite: "ai usage sink failed").
61      inject: [AI_LEDGER],
62      useFactory: (ledger: AiLedgerService) =>
63        buildAiGateway({
64          onBudgetExceeded: () => {
65            // No-op: the service-level guard (AiBudgetGuardService) is the
66            // enforcement + notification point. The gateway's in-memory
67            // submit-time backstop never fires its hook — a backstop hit
68            // throws before the provider call regardless.
69          },
70          // TASK-0135: the spec's AI metrics are recorded HERE — the
71          // gateway's usage sink is the ONE funnel every AI call flows
72          // through (chat + embed + generate, all 7 call sites, success
73          // AND error paths), with `model`/`tokensIn`/`tokensOut`/
74          // `latencyMs` already resolved. Recording centrally (instead of
75          // at each service) means no call path is missed and none is
76          // double-counted. The `model` label separates chat vs embed
77          // models (different model strings), so the direction labels
78          // stay spec-exact (in|out): embeddings meter as `out` (the
79          // gateway's own `tokensOut` estimate) under the embed model.
80          ledgerSink: (record) => {
81            m.ai.tokens({ direction: "in", model: record.model }, record.tokensIn);
82            m.ai.tokens({ direction: "out", model: record.model }, record.tokensOut);
83            m.ai.request({ model: record.model }, record.latencyMs / 1000);
84            return ledger.record(record);
85          }
86        })
87    },
88    AiService,
89    AiChatService,
90    AiRateLimitService,
91    AiWritingService,
92    DatabaseAiService,
93    RagService,
94    AiGenerateService,
95    AssistantService
96  ],
97  exports: [AiService, AI_GATEWAY, AiBudgetGuardService, AiChatService, AiRateLimitService, AiWritingService, DatabaseAiService, RagService, AiGenerateService, AssistantService]
98})
99export class AiModule {}
100