@postxl/generators 1.12.3 → 1.13.0

package/dist/backend-ai/ai.generator.d.ts

@@ -0,0 +1,18 @@
+import * as Generator from '@postxl/generator';
+import { WithBackend } from '../backend-core';
+import { WithBase } from '../base';
+import { WithTypes } from '../types';
+type ContextRequirements = WithTypes<WithBackend<WithBase<Generator.Context>>>;
+export type ContextResult = WithBackendAi<ContextRequirements>;
+export type WithBackendAi<Context> = Generator.ExtendContext<Context, {
+    ai: {
+        module: Generator.ImportableClass;
+        agentService: Generator.ImportableClass;
+        route: Generator.ImportableFunction & {
+            _filePath: Generator.FilePath;
+        };
+    };
+}>;
+export declare const generatorId: string & import("zod").$brand<"PXL.GeneratorInterfaceId">;
+export declare const generator: Generator.GeneratorInterface;
+export {};

package/dist/backend-ai/ai.generator.js

@@ -0,0 +1,174 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generator = exports.generatorId = void 0;
+const Generator = __importStar(require("@postxl/generator"));
+const backend_core_1 = require("../backend-core");
+const base_1 = require("../base");
+const types_1 = require("../types");
+const ai_agent_service_generator_1 = require("./generators/ai-agent-service.generator");
+const ai_cache_service_generator_1 = require("./generators/ai-cache-service.generator");
+const ai_config_generator_1 = require("./generators/ai-config.generator");
+const ai_module_generator_1 = require("./generators/ai-module.generator");
+const ai_route_generator_1 = require("./generators/ai-route.generator");
+const ai_tools_service_generator_1 = require("./generators/ai-tools-service.generator");
+const model_provider_interface_generator_1 = require("./generators/model-provider-interface.generator");
+const openai_model_provider_service_generator_1 = require("./generators/openai-model-provider-service.generator");
+const apiKeyDummyValue = 'sk-...';
+exports.generatorId = Generator.toGeneratorInterfaceId('backend-ai');
+exports.generator = {
+    id: exports.generatorId,
+    requires: [backend_core_1.backendGeneratorId, base_1.baseGeneratorId, types_1.typesGeneratorId],
+    register: (context) => {
+        const module = {
+            name: Generator.toClassName('AiModule'),
+            location: Generator.toBackendModuleLocation('@ai/ai.module'),
+        };
+        const agentService = {
+            name: Generator.toClassName('AiAgentService'),
+            location: Generator.toBackendModuleLocation('@ai/ai-agent.service'),
+        };
+        const aiModule = {
+            name: Generator.toBackendModuleName('ai'),
+            moduleClass: module,
+            apiModuleRegistration: {
+                code: Generator.ts('AiModule.forRoot(config.ai)'),
+            },
+            envConfig: {
+                decoder: Generator.ts(`
+AI_ENABLED: zEnvBoolean.optional().default(true),
+AI_OPENAI_KEY: z.string().optional(),
+AI_OPENAI_MODEL: z.string().optional().default('gpt-4.1-mini'),
+AI_OPENAI_KEYS: z.string().optional(),
+AI_OPENAI_TIMEOUT_MS: z.coerce.number().optional().default(20000),
+AI_RATE_LIMIT_WINDOW_MS: z.coerce.number().optional().default(60000),
+AI_RATE_LIMIT_MAX_REQUESTS: z.coerce.number().optional().default(120),
+AI_CONVERSATION_TTL_MS: z.coerce.number().optional().default(900000),
+AI_CONVERSATION_CACHE_MAX_SIZE: z.coerce.number().optional().default(500),
+AI_MAX_INTERNAL_TOOL_STEPS: z.coerce.number().optional().default(12),
+        `),
+                transformer: Generator.ts(`
+ai: {
+  ...(() => {
+    const singleKey = typeof val.AI_OPENAI_KEY === 'string' ? val.AI_OPENAI_KEY.trim() : ''
+    const keyPool =
+      typeof val.AI_OPENAI_KEYS === 'string'
+        ? val.AI_OPENAI_KEYS
+            .split(',')
+            .map((key) => key.trim())
+            .filter((key) => key.length > 0)
+        : []
+
+    const hasSingleKey = singleKey.length > 0
+    const hasKeyPool = keyPool.length > 0
+    const hasDummySingleKey = singleKey === '${apiKeyDummyValue}'
+    const hasDummyKeyInPool = keyPool.includes('${apiKeyDummyValue}')
+
+    if (val.AI_ENABLED && !hasSingleKey && !hasKeyPool) {
+      throw new Error('AI_ENABLED=true requires AI_OPENAI_KEY or AI_OPENAI_KEYS')
+    }
+    if (val.AI_ENABLED && (hasDummySingleKey || hasDummyKeyInPool)) {
+      throw new Error('AI_ENABLED=true requires a real OpenAI key, not the placeholder "${apiKeyDummyValue}"')
+    }
+
+    return {
+      enabled: val.AI_ENABLED,
+      openAIApiKey: val.AI_OPENAI_KEY,
+      model: val.AI_OPENAI_MODEL,
+      openAIApiKeys: val.AI_OPENAI_KEYS,
+      timeoutMs: val.AI_OPENAI_TIMEOUT_MS,
+      rateLimitWindowMs: val.AI_RATE_LIMIT_WINDOW_MS,
+      rateLimitMaxRequests: val.AI_RATE_LIMIT_MAX_REQUESTS,
+      conversationTtlMs: val.AI_CONVERSATION_TTL_MS,
+      conversationCacheMaxSize: val.AI_CONVERSATION_CACHE_MAX_SIZE,
+      maxInternalToolSteps: val.AI_MAX_INTERNAL_TOOL_STEPS,
+    }
+  })(),
+},
+        `),
+                dotEnvExample: Generator.ts(`
+# Enable or disable AI assistant features on the backend
+AI_ENABLED=true
+# Required when AI is enabled unless AI_OPENAI_KEYS is set
+AI_OPENAI_KEY="${apiKeyDummyValue}"
+# Optional: key pool for rotation (comma-separated); used before AI_OPENAI_KEY when set
+# AI_OPENAI_KEYS="sk-key-1,sk-key-2"
+# Optional model override
+# AI_OPENAI_MODEL="gpt-4.1-mini"
+# Optional request timeout in milliseconds
+# AI_OPENAI_TIMEOUT_MS=20000
+# Optional global backend AI request rate limit (window + max requests)
+# AI_RATE_LIMIT_WINDOW_MS=60000
+# AI_RATE_LIMIT_MAX_REQUESTS=120
+# Optional in-memory conversation cache controls
+# AI_CONVERSATION_TTL_MS=900000
+# AI_CONVERSATION_CACHE_MAX_SIZE=500
+# Optional max number of backend tool executions in one AI turn
+# AI_MAX_INTERNAL_TOOL_STEPS=12
+        `),
+            },
+        };
+        context.backend.modules.push(aiModule);
+        return {
+            ...context,
+            ai: {
+                module,
+                agentService,
+                route: {
+                    name: Generator.toFunctionName('ai'),
+                    location: Generator.toBackendModuleLocation('@ai/ai.route'),
+                    _filePath: Generator.toFilePath('./ai.route.ts'),
+                },
+            },
+        };
+    },
+    generate: (context) => {
+        const vfsSrc = new Generator.VirtualFileSystem();
+        vfsSrc.write(Generator.toLocalFile(context.ai.module), (0, ai_module_generator_1.generateAiModule)(context));
+        vfsSrc.write(Generator.toLocalFile(context.ai.agentService), (0, ai_agent_service_generator_1.generateAiAgentService)({ context }));
+        vfsSrc.write(Generator.toFilePath('./ai.route.ts'), (0, ai_route_generator_1.generateAiRoute)());
+        vfsSrc.write(Generator.toFilePath('./ai-cache.service.ts'), (0, ai_cache_service_generator_1.generateAiCacheService)());
+        vfsSrc.write(Generator.toFilePath('./ai-config.ts'), (0, ai_config_generator_1.generateAiConfig)());
+        vfsSrc.write(Generator.toFilePath('./ai-tools.service.ts'), (0, ai_tools_service_generator_1.generateAiToolsService)({ context }));
+        vfsSrc.write(Generator.toFilePath('./model-provider/model-provider.interface.ts'), (0, model_provider_interface_generator_1.generateModelProviderInterface)());
+        vfsSrc.write(Generator.toFilePath('./model-provider/openai-model-provider.service.ts'), (0, openai_model_provider_service_generator_1.generateOpenAiModelProviderService)());
+        const vfs = new Generator.VirtualFileSystem();
+        vfs.insertFromVfs({ targetPath: 'src', vfs: vfsSrc });
+        vfs.write('/tsconfig.lib.json', Generator.generateTsConfig('ai'));
+        context.vfs.insertFromVfs({ targetPath: 'backend/libs/ai', vfs });
+        return Promise.resolve(context);
+    },
+};
+//# sourceMappingURL=ai.generator.js.map

package/dist/backend-ai/ai.generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai.generator.js","sourceRoot":"","sources":["../../src/backend-ai/ai.generator.ts"],"names":[],"mappings":"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"}

package/dist/backend-ai/generators/ai-agent-service.generator.d.ts

@@ -0,0 +1,4 @@
+import { ContextResult } from '../ai.generator';
+export declare function generateAiAgentService({ context }: {
+    context: ContextResult;
+}): string;

package/dist/backend-ai/generators/ai-agent-service.generator.js

@@ -0,0 +1,264 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAiAgentService = generateAiAgentService;
+const Generator = __importStar(require("@postxl/generator"));
+function generateAiAgentService({ context }) {
+    const imports = Generator.ImportGenerator.from(Generator.toFilePath('./ai-agent.service.ts')).addImport({
+        from: context.types.location,
+        items: [Generator.toTypeName('AskStepInput'), Generator.toTypeName('AskTaskInput')],
+    });
+    return /* ts */ `
+import { Inject, Injectable } from '@nestjs/common'
+
+${imports.generate()}
+
+import { AiCacheService } from './ai-cache.service'
+import { AiConfig } from './ai-config'
+import type {
+  AiModelProvider,
+  ChatMessage,
+} from './model-provider/model-provider.interface'
+import { AiToolsService, BackendToolExecutionLog } from './ai-tools.service'
+
+export const AI_MODEL_PROVIDER = Symbol('AI_MODEL_PROVIDER')
+
+type ResolvedToolCall = {
+  messages: ChatMessage[]
+  key: string
+  input: Record<string, unknown>
+  pendingToolCallId?: string
+  backendLogs: BackendToolExecutionLog[]
+}
+
+@Injectable()
+export class AiAgentService {
+  private readonly systemPrompt = [
+    'You are an AI assistant controlling tools to satisfy a user task.',
+    'Choose one tool call at a time and stop once task is completed.',
+    'Call done when task is complete or no further progress can be made.',
+    'Do not repeat the same tool twice in a row.',
+    'If required information is missing or ambiguous, call ask-user with a clear question and wait for the answer.',
+  ].join('\\n')
+
+  constructor(
+    private readonly cache: AiCacheService,
+    private readonly aiConfig: AiConfig,
+    private readonly tools: AiToolsService,
+    @Inject(AI_MODEL_PROVIDER) private readonly modelProvider: AiModelProvider,
+  ) {}
+
+  public async startExecution({ task, tools }: AskTaskInput, actorId: unknown) {
+    const actorKey = this.toActorKey(actorId)
+    if (!this.aiConfig.config.enabled) {
+      throw new Error('AI feature is disabled')
+    }
+
+    this.cache.pruneConversationCache()
+
+    const messages: ChatMessage[] = [
+      { role: 'system', content: this.systemPrompt },
+      { role: 'user', content: task },
+    ]
+
+    const resolved = await this.resolveNextToolCall({ messages, tools, actorKey })
+
+    const conversation = resolved.key !== 'done' && resolved.pendingToolCallId
+      ? this.cache.createConversation({
+          actorKey,
+          pendingToolCallId: resolved.pendingToolCallId,
+          messages: resolved.messages,
+        })
+      : (globalThis.crypto.randomUUID() as string)
+
+    return {
+      conversation,
+      key: resolved.key,
+      input: resolved.input,
+      backendLogs: resolved.backendLogs,
+    }
+  }
+
+  public async continueExecution({ conversation, output, tools }: AskStepInput, actorId: unknown) {
+    const actorKey = this.toActorKey(actorId)
+    const history = this.cache.getConversation(conversation, actorKey)
+
+    if (!history?.pendingToolCallId) {
+      throw new Error('Conversation not found')
+    }
+
+    const toolOutput = output ? JSON.stringify(output) : JSON.stringify({ ok: true })
+
+    const messages: ChatMessage[] = [
+      ...history.messages,
+      {
+        role: 'tool',
+        tool_call_id: history.pendingToolCallId,
+        content: toolOutput,
+      },
+    ]
+
+    const resolved = await this.resolveNextToolCall({ messages, tools, actorKey })
+
+    if (resolved.key === 'done') {
+      this.cache.deleteConversation(conversation, actorKey)
+    } else if (resolved.pendingToolCallId) {
+      this.cache.upsertConversation(conversation, {
+        actorKey,
+        pendingToolCallId: resolved.pendingToolCallId,
+        messages: resolved.messages,
+      })
+    }
+
+    return {
+      conversation,
+      key: resolved.key,
+      input: resolved.input,
+      backendLogs: resolved.backendLogs,
+    }
+  }
+
+  public cancelExecution(conversation: string, actorId: unknown) {
+    const actorKey = this.toActorKey(actorId)
+    return this.cache.deleteConversation(conversation, actorKey)
+  }
+
+  private async resolveNextToolCall({
+    messages,
+    tools,
+    actorKey,
+  }: {
+    messages: ChatMessage[]
+    tools: AskTaskInput['tools']
+    actorKey: string
+  }): Promise<ResolvedToolCall> {
+    const normalizedFrontendTools = this.tools.normalizeFrontendTools(tools)
+    this.tools.assertNoToolKeyCollision(normalizedFrontendTools)
+
+    const conversationMessages = [...messages]
+    const backendLogs: BackendToolExecutionLog[] = []
+
+    for (let step = 0; step < this.aiConfig.config.maxInternalToolSteps; step += 1) {
+      this.cache.assertWithinRateLimit(actorKey)
+
+      const providerResult = await this.modelProvider.requestSingleToolCall({
+        messages: conversationMessages,
+        tools: this.tools.buildTools(normalizedFrontendTools),
+      })
+
+      conversationMessages.push(providerResult.assistantMessage)
+
+      const parsedInput = this.parseArguments(providerResult.toolCall.function.arguments)
+
+      if (providerResult.toolCall.function.name === 'done') {
+        return {
+          messages: conversationMessages,
+          key: 'done',
+          input: parsedInput,
+          backendLogs,
+        }
+      }
+
+      const backendTool = this.tools.getBackendTool(providerResult.toolCall.function.name)
+      if (!backendTool) {
+        return {
+          messages: conversationMessages,
+          key: providerResult.toolCall.function.name,
+          input: parsedInput,
+          pendingToolCallId: providerResult.toolCall.id,
+          backendLogs,
+        }
+      }
+
+      const toolLabel = backendTool.definition.label
+
+      try {
+        const output = (await backendTool.execute(parsedInput, { actorKey })) ?? { ok: true }
+        backendLogs.push({
+          toolKey: backendTool.definition.key,
+          status: 'done',
+          text: 'Executed backend tool: ' + toolLabel,
+        })
+
+        conversationMessages.push({
+          role: 'tool',
+          tool_call_id: providerResult.toolCall.id,
+          content: JSON.stringify(output),
+        })
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error)
+        backendLogs.push({
+          toolKey: backendTool.definition.key,
+          status: 'error',
+          text: 'Backend tool failed: ' + toolLabel + ' (' + message + ')',
+        })
+
+        conversationMessages.push({
+          role: 'tool',
+          tool_call_id: providerResult.toolCall.id,
+          content: JSON.stringify({ ok: false, error: message }),
+        })
+      }
+    }
+
+    throw new Error('AI exceeded backend tool iteration limit')
+  }
+
+  private parseArguments(argumentsJson: string): Record<string, unknown> {
+    try {
+      const parsed = JSON.parse(argumentsJson)
+      if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+        return parsed as Record<string, unknown>
+      }
+
+      console.warn('AI action arguments must be a JSON object. Received:', parsed)
+      return {}
+    } catch (error) {
+      console.warn('Failed to parse AI action arguments:', error)
+      return {}
+    }
+  }
+
+  private toActorKey(userId: unknown): string {
+    if (typeof userId === 'string' && userId.length > 0) {
+      return userId
+    }
+
+    return String(userId ?? 'unknown-user')
+  }
+}
+`;
+}
+//# sourceMappingURL=ai-agent-service.generator.js.map

package/dist/backend-ai/generators/ai-agent-service.generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-agent-service.generator.js","sourceRoot":"","sources":["../../../src/backend-ai/generators/ai-agent-service.generator.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAIA,wDAkOC;AAtOD,6DAA8C;AAI9C,SAAgB,sBAAsB,CAAC,EAAE,OAAO,EAA8B;IAC5E,MAAM,OAAO,GAAG,SAAS,CAAC,eAAe,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,uBAAuB,CAAC,CAAC,CAAC,SAAS,CAAC;QACtG,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,QAAQ;QAC5B,KAAK,EAAE,CAAC,SAAS,CAAC,UAAU,CAAC,cAAc,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,cAAc,CAAC,CAAC;KACpF,CAAC,CAAA;IAEF,OAAO,QAAQ,CAAC;;;EAGhB,OAAO,CAAC,QAAQ,EAAE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAwNnB,CAAA;AACD,CAAC"}

package/dist/backend-ai/generators/ai-cache-service.generator.d.ts

@@ -0,0 +1 @@
+export declare function generateAiCacheService(): string;

package/dist/backend-ai/generators/ai-cache-service.generator.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAiCacheService = generateAiCacheService;
+function generateAiCacheService() {
+    return /* ts */ `
+import { Injectable } from '@nestjs/common'
+
+import { AiConfig } from './ai-config'
+import type { ChatMessage } from './model-provider/model-provider.interface'
+
+export type ConversationState = {
+  actorKey: string
+  pendingToolCallId?: string
+  messages: ChatMessage[]
+  expiresAt: number
+  updatedAt: number
+}
+
+@Injectable()
+export class AiCacheService {
+  private readonly conversationCache = new Map<string, ConversationState>()
+  private readonly actorRateLimit = new Map<string, { windowStart: number; requestCount: number }>()
+
+  constructor(private readonly aiConfig: AiConfig) {}
+
+  public createConversation(value: { actorKey: string; pendingToolCallId?: string; messages: ChatMessage[] }): string {
+    const conversation = globalThis.crypto.randomUUID() as string
+    this.upsertConversation(conversation, value)
+    return conversation
+  }
+
+  public upsertConversation(
+    conversation: string,
+    value: { actorKey: string; pendingToolCallId?: string; messages: ChatMessage[] },
+  ) {
+    const now = Date.now()
+    this.pruneConversationCache(now)
+
+    this.conversationCache.set(conversation, {
+      ...value,
+      updatedAt: now,
+      expiresAt: now + this.aiConfig.config.conversationTtlMs,
+    })
+  }
+
+  public getConversation(conversation: string, actorKey: string): ConversationState | undefined {
+    const now = Date.now()
+    const value = this.conversationCache.get(conversation)
+    if (!value) {
+      return undefined
+    }
+    if (value.actorKey !== actorKey) {
+      return undefined
+    }
+    if (value.expiresAt <= now) {
+      this.conversationCache.delete(conversation)
+      return undefined
+    }
+
+    value.updatedAt = now
+    value.expiresAt = now + this.aiConfig.config.conversationTtlMs
+    this.conversationCache.set(conversation, value)
+    return value
+  }
+
+  public deleteConversation(conversation: string, actorKey: string): boolean {
+    const history = this.conversationCache.get(conversation)
+    if (history?.actorKey !== actorKey) {
+      return false
+    }
+
+    return this.conversationCache.delete(conversation)
+  }
+
+  public assertWithinRateLimit(actorKey: string, now = Date.now()) {
+    const current = this.actorRateLimit.get(actorKey)
+    if (!current || now - current.windowStart >= this.aiConfig.config.rateLimitWindowMs) {
+      this.actorRateLimit.set(actorKey, { windowStart: now, requestCount: 1 })
+      return
+    }
+
+    current.requestCount += 1
+    if (current.requestCount > this.aiConfig.config.rateLimitMaxRequests) {
+      throw new Error('AI rate limit exceeded for current user. Please retry shortly.')
+    }
+
+    this.actorRateLimit.set(actorKey, current)
+  }
+
+  public pruneConversationCache(now = Date.now()) {
+    for (const [conversation, value] of this.conversationCache.entries()) {
+      if (value.expiresAt <= now) {
+        this.conversationCache.delete(conversation)
+      }
+    }
+
+    if (this.conversationCache.size <= this.aiConfig.config.conversationCacheMaxSize) {
+      return
+    }
+
+    const entries = [...this.conversationCache.entries()].sort((left, right) => left[1].updatedAt - right[1].updatedAt)
+    const excess = this.conversationCache.size - this.aiConfig.config.conversationCacheMaxSize
+    for (const [conversation] of entries.slice(0, excess)) {
+      this.conversationCache.delete(conversation)
+    }
+  }
+}
+`;
+}
+//# sourceMappingURL=ai-cache-service.generator.js.map

package/dist/backend-ai/generators/ai-cache-service.generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-cache-service.generator.js","sourceRoot":"","sources":["../../../src/backend-ai/generators/ai-cache-service.generator.ts"],"names":[],"mappings":";;AAAA,wDAyGC;AAzGD,SAAgB,sBAAsB;IACpC,OAAO,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuGjB,CAAA;AACD,CAAC"}

package/dist/backend-ai/generators/ai-config.generator.d.ts

@@ -0,0 +1 @@
+export declare function generateAiConfig(): string;

package/dist/backend-ai/generators/ai-config.generator.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAiConfig = generateAiConfig;
+function generateAiConfig() {
+    return /* ts */ `
+import { Injectable } from '@nestjs/common'
+
+export type Config = Readonly<{
+  enabled: boolean
+  openAIApiKey?: string
+  openAIApiKeys?: string
+  model: string
+  timeoutMs: number
+  rateLimitWindowMs: number
+  rateLimitMaxRequests: number
+  conversationTtlMs: number
+  conversationCacheMaxSize: number
+  maxInternalToolSteps: number
+}>
+
+@Injectable()
+export class AiConfig {
+  constructor(public readonly config: Config) {}
+}
+`;
+}
+//# sourceMappingURL=ai-config.generator.js.map

package/dist/backend-ai/generators/ai-config.generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ai-config.generator.js","sourceRoot":"","sources":["../../../src/backend-ai/generators/ai-config.generator.ts"],"names":[],"mappings":";;AAAA,4CAsBC;AAtBD,SAAgB,gBAAgB;IAC9B,OAAO,QAAQ,CAAC;;;;;;;;;;;;;;;;;;;;CAoBjB,CAAA;AACD,CAAC"}

package/dist/backend-ai/generators/ai-module.generator.d.ts

@@ -0,0 +1,2 @@
+import { ContextResult } from '../ai.generator';
+export declare function generateAiModule(context: ContextResult): string;