@carlonicora/nestjs-neo4jsonapi 1.62.7 → 1.64.0

package/dist/agents/chatbot/services/chatbot.search.service.js

@@ -0,0 +1,148 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var ChatbotSearchService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatbotSearchService = exports.CHATBOT_SEMANTIC_MIN_SCORE = exports.CHATBOT_RESOLVE_MAX_RESULTS = exports.CHATBOT_SEMANTIC_MAX_RESULTS = exports.CHATBOT_FUZZY_MAX_RESULTS = exports.CHATBOT_EXACT_MAX_RESULTS = void 0;
+const common_1 = require("@nestjs/common");
+const embedder_service_1 = require("../../../core/llm/services/embedder.service");
+const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
+const chatbot_index_manager_1 = require("./chatbot.index.manager");
+const graph_catalog_service_1 = require("./graph.catalog.service");
+exports.CHATBOT_EXACT_MAX_RESULTS = 10;
+exports.CHATBOT_FUZZY_MAX_RESULTS = 10;
+exports.CHATBOT_SEMANTIC_MAX_RESULTS = 5;
+exports.CHATBOT_RESOLVE_MAX_RESULTS = 10;
+exports.CHATBOT_SEMANTIC_MIN_SCORE = 0.6;
+const CHATBOT_VECTOR_OVERFETCH = 50;
+const LUCENE_RESERVED_RE = /[+\-&|!(){}[\]^"~*?:\\/]/g;
+let ChatbotSearchService = ChatbotSearchService_1 = class ChatbotSearchService {
+    constructor(neo4j, embedder, indexNames, catalog) {
+        this.neo4j = neo4j;
+        this.embedder = embedder;
+        this.indexNames = indexNames;
+        this.catalog = catalog;
+        this.logger = new common_1.Logger(ChatbotSearchService_1.name);
+    }
+    async resolveEntity(params) {
+        const entities = this.catalog.getAllChatEnabledEntities().filter((e) => params.userModuleIds.includes(e.moduleId));
+        if (!entities.length) {
+            return { matchMode: "none", items: [] };
+        }
+        const tiers = [
+            ["substring", "exact"],
+            ["fuzzy", "fuzzy"],
+            ["semantic", "semantic"],
+        ];
+        for (const [tier, label] of tiers) {
+            const buckets = await Promise.all(entities.map((e) => this.runTierForEntitySafe(e, params, tier)));
+            const merged = buckets.flat();
+            if (merged.length) {
+                merged.sort((a, b) => b.score - a.score);
+                return { matchMode: label, items: merged.slice(0, exports.CHATBOT_RESOLVE_MAX_RESULTS) };
+            }
+        }
+        return { matchMode: "none", items: [] };
+    }
+    async runTierForEntitySafe(entity, params, tier) {
+        try {
+            const runParams = {
+                entity,
+                text: params.text,
+                companyId: params.companyId,
+                limit: tier === "semantic"
+                    ? exports.CHATBOT_SEMANTIC_MAX_RESULTS
+                    : tier === "fuzzy"
+                        ? exports.CHATBOT_FUZZY_MAX_RESULTS
+                        : exports.CHATBOT_EXACT_MAX_RESULTS,
+            };
+            const inner = tier === "semantic" ? await this.tierSemantic(runParams) : await this.tierFulltext(runParams, tier);
+            return inner.items.map((i) => ({
+                type: entity.type,
+                id: i.id,
+                summary: this.projectSummary(entity, i.properties, i.id),
+                score: i.score,
+            }));
+        }
+        catch (err) {
+            this.logger.warn(`resolveEntity: tier=${tier} type=${entity.type} threw: ${err instanceof Error ? err.message : String(err)}`);
+            return [];
+        }
+    }
+    projectSummary(entity, properties, id) {
+        if (entity.summary) {
+            try {
+                return entity.summary(properties);
+            }
+            catch {
+                /* fall through */
+            }
+        }
+        const name = properties.name;
+        if (typeof name === "string" && name.length)
+            return name;
+        return id;
+    }
+    async tierFulltext(params, mode) {
+        const indexName = this.indexNames.fulltextIndexName(params.entity.labelName);
+        const escaped = params.text.replace(LUCENE_RESERVED_RE, "\\$&").toLowerCase();
+        const term = mode === "substring" ? `*${escaped}*` : `${escaped}~`;
+        const max = mode === "substring" ? exports.CHATBOT_EXACT_MAX_RESULTS : exports.CHATBOT_FUZZY_MAX_RESULTS;
+        const result = await this.neo4j.read(`
+      CALL db.index.fulltext.queryNodes($indexName, $term)
+      YIELD node, score
+      WHERE (node)-[:BELONGS_TO]->(:Company { id: $companyId })
+      RETURN node.id AS id, properties(node) AS properties, score
+      ORDER BY score DESC
+      LIMIT toInteger($limit)
+      `, { indexName, term, companyId: params.companyId, limit: Math.min(params.limit, max) });
+        const items = result.records.map((r) => ({
+            id: r.get("id"),
+            score: r.get("score"),
+            properties: r.get("properties") ?? {},
+        }));
+        return { matchMode: mode === "substring" ? "exact" : "fuzzy", items };
+    }
+    async tierSemantic(params) {
+        const indexName = this.indexNames.vectorIndexName(params.entity.labelName);
+        const queryEmbedding = await this.embedder.vectoriseText({ text: params.text });
+        const result = await this.neo4j.read(`
+      CALL db.index.vector.queryNodes($indexName, toInteger($overFetch), $queryEmbedding)
+      YIELD node, score
+      WHERE (node)-[:BELONGS_TO]->(:Company { id: $companyId })
+        AND score >= $minScore
+      RETURN node.id AS id, properties(node) AS properties, score
+      ORDER BY score DESC
+      LIMIT toInteger($limit)
+      `, {
+            indexName,
+            overFetch: CHATBOT_VECTOR_OVERFETCH,
+            queryEmbedding,
+            companyId: params.companyId,
+            minScore: exports.CHATBOT_SEMANTIC_MIN_SCORE,
+            limit: Math.min(params.limit, exports.CHATBOT_SEMANTIC_MAX_RESULTS),
+        });
+        const items = result.records.map((r) => ({
+            id: r.get("id"),
+            score: r.get("score"),
+            properties: r.get("properties") ?? {},
+        }));
+        return { matchMode: items.length ? "semantic" : "none", items };
+    }
+};
+exports.ChatbotSearchService = ChatbotSearchService;
+exports.ChatbotSearchService = ChatbotSearchService = ChatbotSearchService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [neo4j_service_1.Neo4jService,
+        embedder_service_1.EmbedderService,
+        chatbot_index_manager_1.ChatbotIndexManager,
+        graph_catalog_service_1.GraphCatalogService])
+], ChatbotSearchService);
+//# sourceMappingURL=chatbot.search.service.js.map

package/dist/agents/chatbot/services/chatbot.search.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatbot.search.service.js","sourceRoot":"","sources":["../../../../src/agents/chatbot/services/chatbot.search.service.ts"],"names":[],"mappings":"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"}

package/dist/agents/chatbot/services/chatbot.service.d.ts

@@ -0,0 +1,36 @@
+import { WebSocketService } from "../../../core/websocket/services/websocket.service";
+import { LLMService } from "../../../core/llm/services/llm.service";
+import { GraphCatalogService } from "./graph.catalog.service";
+import { ToolFactory } from "../tools/tool.factory";
+import { ResolveEntityTool } from "../tools/resolve-entity.tool";
+import { DescribeEntityTool } from "../tools/describe-entity.tool";
+import { SearchEntitiesTool } from "../tools/search-entities.tool";
+import { ReadEntityTool } from "../tools/read-entity.tool";
+import { TraverseTool } from "../tools/traverse.tool";
+import { ChatbotResponseInterface } from "../interfaces/chatbot.response.interface";
+export interface ChatbotRunParams {
+    companyId: string;
+    userId: string;
+    userModuleIds: string[];
+    messages: Array<{
+        role: "user" | "assistant" | "system";
+        content: string;
+    }>;
+    /** Optional — populated on subsequent turns; undefined on the first send of a new thread. */
+    assistantId?: string;
+}
+export declare class ChatbotService {
+    private readonly llm;
+    private readonly graph;
+    private readonly factory;
+    private readonly resolveTool;
+    private readonly describeTool;
+    private readonly searchTool;
+    private readonly readTool;
+    private readonly traverseTool;
+    private readonly ws?;
+    private readonly logger;
+    constructor(llm: LLMService, graph: GraphCatalogService, factory: ToolFactory, resolveTool: ResolveEntityTool, describeTool: DescribeEntityTool, searchTool: SearchEntitiesTool, readTool: ReadEntityTool, traverseTool: TraverseTool, ws?: WebSocketService);
+    run(params: ChatbotRunParams): Promise<ChatbotResponseInterface>;
+}
+//# sourceMappingURL=chatbot.service.d.ts.map

package/dist/agents/chatbot/services/chatbot.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chatbot.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/chatbot/services/chatbot.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oDAAoD,CAAC;AAGtF,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAkB,MAAM,uBAAuB,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC3D,OAAO,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAEtD,OAAO,EAAE,wBAAwB,EAAE,MAAM,0CAA0C,CAAC;AAapF,MAAM,WAAW,gBAAgB;IAC/B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5E,6FAA6F;IAC7F,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,qBACa,cAAc;IAIvB,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,YAAY;IACjB,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC;IAXlC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;gBAGvC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,WAAW,EACpB,WAAW,EAAE,iBAAiB,EAC9B,YAAY,EAAE,kBAAkB,EAChC,UAAU,EAAE,kBAAkB,EAC9B,QAAQ,EAAE,cAAc,EACxB,YAAY,EAAE,YAAY,EACd,EAAE,CAAC,EAAE,gBAAgB;IAG9C,GAAG,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,wBAAwB,CAAC;CA8LvE"}

package/dist/agents/chatbot/services/chatbot.service.js

@@ -0,0 +1,220 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (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;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var ChatbotService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ChatbotService = void 0;
+const common_1 = require("@nestjs/common");
+const websocket_service_1 = require("../../../core/websocket/services/websocket.service");
+const zod_1 = require("zod");
+const tools_1 = require("@langchain/core/tools");
+const llm_service_1 = require("../../../core/llm/services/llm.service");
+const graph_catalog_service_1 = require("./graph.catalog.service");
+const tool_factory_1 = require("../tools/tool.factory");
+const resolve_entity_tool_1 = require("../tools/resolve-entity.tool");
+const describe_entity_tool_1 = require("../tools/describe-entity.tool");
+const search_entities_tool_1 = require("../tools/search-entities.tool");
+const read_entity_tool_1 = require("../tools/read-entity.tool");
+const traverse_tool_1 = require("../tools/traverse.tool");
+const chatbot_system_prompt_1 = require("../prompts/chatbot.system.prompt");
+const agentmessage_type_1 = require("../../../common/enums/agentmessage.type");
+const humanize_tool_1 = require("./humanize-tool");
+const MAX_TOOL_ITERATIONS = 15;
+const outputSchema = zod_1.z.object({
+    answer: zod_1.z.string(),
+    references: zod_1.z.array(zod_1.z.object({ type: zod_1.z.string(), id: zod_1.z.string(), reason: zod_1.z.string() })),
+    needsClarification: zod_1.z.boolean(),
+    suggestedQuestions: zod_1.z.array(zod_1.z.string()).max(5),
+});
+let ChatbotService = ChatbotService_1 = class ChatbotService {
+    constructor(llm, graph, factory, resolveTool, describeTool, searchTool, readTool, traverseTool, ws) {
+        this.llm = llm;
+        this.graph = graph;
+        this.factory = factory;
+        this.resolveTool = resolveTool;
+        this.describeTool = describeTool;
+        this.searchTool = searchTool;
+        this.readTool = readTool;
+        this.traverseTool = traverseTool;
+        this.ws = ws;
+        this.logger = new common_1.Logger(ChatbotService_1.name);
+    }
+    async run(params) {
+        this.logger.log(`run: userId=${params.userId} companyId=${params.companyId} userModuleIds=${JSON.stringify(params.userModuleIds)} messageCount=${params.messages.length}`);
+        if (!params.userModuleIds.length) {
+            this.logger.warn(`run: empty userModuleIds — returning clean refusal without invoking LLM`);
+            return {
+                type: agentmessage_type_1.AgentMessageType.Assistant,
+                answer: "You have no enabled modules with described data — there is nothing I can query.",
+                references: [],
+                needsClarification: false,
+                suggestedQuestions: [],
+                tokens: { input: 0, output: 0 },
+                toolCalls: [],
+            };
+        }
+        const ctx = {
+            companyId: params.companyId,
+            userId: params.userId,
+            userModuleIds: params.userModuleIds,
+        };
+        const recorder = [];
+        const graphMap = this.graph.getMapFor(params.userModuleIds);
+        this.logger.log(`run: graph map length=${graphMap.length} chars`);
+        this.logger.debug(`run: graph map contents:\n${graphMap}`);
+        const systemPrompt = (0, chatbot_system_prompt_1.renderChatbotSystemPrompt)(graphMap);
+        let tools = [
+            this.resolveTool.build(ctx, recorder),
+            this.describeTool.build(ctx, recorder),
+            this.searchTool.build(ctx, recorder),
+            this.readTool.build(ctx, recorder),
+            this.traverseTool.build(ctx, recorder),
+        ];
+        this.logger.log(`run: bound tools=${JSON.stringify(tools.map((t) => t.name))}`);
+        if (this.ws) {
+            const ws = this.ws;
+            const userId = params.userId;
+            const assistantId = params.assistantId;
+            tools = tools.map((t) => new tools_1.DynamicStructuredTool({
+                name: t.name,
+                description: t.description,
+                schema: t.schema,
+                func: async (input) => {
+                    try {
+                        await ws.sendMessageToUser(userId, "assistant:status", {
+                            assistantId,
+                            status: (0, humanize_tool_1.humanizeTool)(t.name, input),
+                            at: new Date().toISOString(),
+                        });
+                    }
+                    catch (err) {
+                        // Non-fatal — status updates are progress hints, not functional.
+                        this.logger.warn(`assistant:status emit failed: ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                    return t.func(input);
+                },
+            }));
+        }
+        const history = params.messages.map((m) => ({
+            role: m.role === "user"
+                ? agentmessage_type_1.AgentMessageType.User
+                : m.role === "assistant"
+                    ? agentmessage_type_1.AgentMessageType.Assistant
+                    : agentmessage_type_1.AgentMessageType.System,
+            content: m.content,
+        }));
+        const RETRY_INSTRUCTION = `Your previous attempt did not call any tools and did not return any references. You cannot know whether the user's question is ambiguous without searching first — so "needsClarification: true" is NOT a valid response at this stage.
+
+You MUST call at least one tool BEFORE responding. For a question that names an entity (e.g., "Show me the last order from Acme"), the first tool call is always:
+
+    resolve_entity({ text: "<the user's literal phrase>" })
+
+Inspect the returned candidates, pick the right type, then call describe_entity and proceed with the typed tools. Do not respond with text — call the tool now.`;
+        this.logger.log(`run: calling LLM (first attempt) with historyLength=${history.length} maxToolIterations=${MAX_TOOL_ITERATIONS}`);
+        let started = Date.now();
+        let response = await this.llm.call({
+            systemPrompts: [systemPrompt],
+            history,
+            outputSchema,
+            inputParams: {},
+            tools,
+            maxToolIterations: MAX_TOOL_ITERATIONS,
+            temperature: 0.1,
+        });
+        this.logger.log(`run: first-attempt LLM returned in ${Date.now() - started}ms | toolCallsObserved=${recorder.length} | referencesCount=${response.references?.length ?? 0}`);
+        if (recorder.length === 0 && (response.references?.length ?? 0) === 0) {
+            this.logger.warn(`run: LLM returned no tool calls AND no references — retrying once with enforcement prompt`);
+            started = Date.now();
+            response = await this.llm.call({
+                systemPrompts: [systemPrompt, RETRY_INSTRUCTION],
+                history,
+                outputSchema,
+                inputParams: {},
+                tools,
+                maxToolIterations: MAX_TOOL_ITERATIONS,
+                temperature: 0.1,
+            });
+            this.logger.log(`run: retry LLM returned in ${Date.now() - started}ms | toolCallsObserved=${recorder.length} | referencesCount=${response.references?.length ?? 0}`);
+        }
+        // Error-recovery retry. If the LLM hit a tool error and bounced an
+        // apology to the user instead of correcting the call, force another pass
+        // with the error details and instructions to retry the failing tool
+        // with valid arguments. The enhanced error messages from the tools
+        // already include the list of valid fields/relationships — the retry
+        // just has to point the LLM back at them.
+        const erroredCalls = recorder.filter((c) => c.error);
+        const answerSoundsApologetic = /^\s*(i am sorry|i'm sorry|i am unable|i cannot|please provide|could you (please )?specify)/i.test(response.answer ?? "");
+        if (erroredCalls.length > 0 && answerSoundsApologetic) {
+            this.logger.warn(`run: LLM bounced apology after tool error(s) — retrying with recovery prompt (${erroredCalls.length} errored calls)`);
+            const lastError = erroredCalls[erroredCalls.length - 1];
+            const recoveryInstruction = `A previous tool call failed and you responded to the user with an apology instead of retrying. That is wrong — the user did not cause the error. Read the error message carefully, correct the arguments, and call the tool again.
+
+Most recent failing call:
+  tool: ${lastError.tool}
+  input: ${JSON.stringify(lastError.input)}
+  error: ${lastError.error}
+
+If the error lists valid fields or relationships, pick one of those and retry NOW. Do not respond to the user until the tool succeeds or you have exhausted sensible options. Do not open your final answer with "I am sorry" or "I cannot".`;
+            started = Date.now();
+            response = await this.llm.call({
+                systemPrompts: [systemPrompt, recoveryInstruction],
+                history,
+                outputSchema,
+                inputParams: {},
+                tools,
+                maxToolIterations: MAX_TOOL_ITERATIONS,
+                temperature: 0.1,
+            });
+            this.logger.log(`run: recovery retry LLM returned in ${Date.now() - started}ms | toolCallsObserved=${recorder.length} | referencesCount=${response.references?.length ?? 0}`);
+        }
+        // Post-retry honesty guard. If the LLM still ships needsClarification: true
+        // without having called any tool, it is refusing to search — not actually
+        // dealing with ambiguous data. Replace the lazy clarification with a clear
+        // failure message so the user knows the assistant did not even look.
+        if (recorder.length === 0 && response.needsClarification) {
+            this.logger.warn(`run: LLM set needsClarification=true with 0 tool calls after retry — rewriting to honest failure`);
+            response = {
+                ...response,
+                answer: "I was unable to answer this question — I did not call any tool to look up data for it, so I cannot provide a real response. Please try rephrasing, or ask about a specific entity by name.",
+                references: [],
+                suggestedQuestions: [],
+                needsClarification: false,
+            };
+        }
+        this.logger.log(`run: final response | toolCallsObserved=${recorder.length} | needsClarification=${response.needsClarification} | referencesCount=${response.references?.length ?? 0} | tokens=${JSON.stringify(response.tokenUsage ?? {})}`);
+        return {
+            type: agentmessage_type_1.AgentMessageType.Assistant,
+            answer: response.answer,
+            references: response.references,
+            needsClarification: response.needsClarification,
+            suggestedQuestions: response.suggestedQuestions,
+            tokens: response.tokenUsage ?? { input: 0, output: 0 },
+            toolCalls: recorder,
+        };
+    }
+};
+exports.ChatbotService = ChatbotService;
+exports.ChatbotService = ChatbotService = ChatbotService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(8, (0, common_1.Optional)()),
+    __metadata("design:paramtypes", [llm_service_1.LLMService,
+        graph_catalog_service_1.GraphCatalogService,
+        tool_factory_1.ToolFactory,
+        resolve_entity_tool_1.ResolveEntityTool,
+        describe_entity_tool_1.DescribeEntityTool,
+        search_entities_tool_1.SearchEntitiesTool,
+        read_entity_tool_1.ReadEntityTool,
+        traverse_tool_1.TraverseTool,
+        websocket_service_1.WebSocketService])
+], ChatbotService);
+//# sourceMappingURL=chatbot.service.js.map

package/dist/agents/chatbot/services/chatbot.service.js.map

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

package/dist/agents/chatbot/services/descriptor.source.d.ts

@@ -0,0 +1,18 @@
+import { DescriptorSource } from "./graph.catalog.service";
+export declare class GraphDescriptorRegistry implements DescriptorSource {
+    private readonly entries;
+    /**
+     * Register a feature-module's descriptor with the chatbot graph catalog.
+     *
+     * `moduleId` must be the stable UUID of the `(Module)` node seeded in the
+     * host app's Neo4j migrations. Matching the ID — not the name — means the
+     * catalog continues to work after module renames and is decoupled from the
+     * host app's naming conventions.
+     */
+    register(params: {
+        descriptor: any;
+        moduleId: string;
+    }): void;
+    loadAll(): any[];
+}
+//# sourceMappingURL=descriptor.source.d.ts.map

package/dist/agents/chatbot/services/descriptor.source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.source.d.ts","sourceRoot":"","sources":["../../../../src/agents/chatbot/services/descriptor.source.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAO3D,qBACa,uBAAwB,YAAW,gBAAgB;IAC9D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyB;IAEjD;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,GAAG,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI;IAI7D,OAAO,IAAI,GAAG,EAAE;CAUjB"}

package/dist/agents/chatbot/services/descriptor.source.js

@@ -0,0 +1,41 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (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;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GraphDescriptorRegistry = void 0;
+const common_1 = require("@nestjs/common");
+let GraphDescriptorRegistry = class GraphDescriptorRegistry {
+    constructor() {
+        this.entries = [];
+    }
+    /**
+     * Register a feature-module's descriptor with the chatbot graph catalog.
+     *
+     * `moduleId` must be the stable UUID of the `(Module)` node seeded in the
+     * host app's Neo4j migrations. Matching the ID — not the name — means the
+     * catalog continues to work after module renames and is decoupled from the
+     * host app's naming conventions.
+     */
+    register(params) {
+        this.entries.push({ descriptor: params.descriptor, moduleId: params.moduleId });
+    }
+    loadAll() {
+        return this.entries.map((e) => ({
+            model: e.descriptor.model,
+            description: e.descriptor.description,
+            moduleId: e.moduleId,
+            fields: e.descriptor.fields ?? {},
+            relationships: e.descriptor.relationships ?? {},
+            chat: e.descriptor.chat,
+        }));
+    }
+};
+exports.GraphDescriptorRegistry = GraphDescriptorRegistry;
+exports.GraphDescriptorRegistry = GraphDescriptorRegistry = __decorate([
+    (0, common_1.Injectable)()
+], GraphDescriptorRegistry);
+//# sourceMappingURL=descriptor.source.js.map

package/dist/agents/chatbot/services/descriptor.source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"descriptor.source.js","sourceRoot":"","sources":["../../../../src/agents/chatbot/services/descriptor.source.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AASrC,IAAM,uBAAuB,GAA7B,MAAM,uBAAuB;IAA7B;QACY,YAAO,GAAsB,EAAE,CAAC;IAwBnD,CAAC;IAtBC;;;;;;;OAOG;IACH,QAAQ,CAAC,MAA6C;QACpD,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClF,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC9B,KAAK,EAAE,CAAC,CAAC,UAAU,CAAC,KAAK;YACzB,WAAW,EAAE,CAAC,CAAC,UAAU,CAAC,WAAW;YACrC,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,MAAM,IAAI,EAAE;YACjC,aAAa,EAAE,CAAC,CAAC,UAAU,CAAC,aAAa,IAAI,EAAE;YAC/C,IAAI,EAAE,CAAC,CAAC,UAAU,CAAC,IAAI;SACxB,CAAC,CAAC,CAAC;IACN,CAAC;CACF,CAAA;AAzBY,0DAAuB;kCAAvB,uBAAuB;IADnC,IAAA,mBAAU,GAAE;GACA,uBAAuB,CAyBnC"}

package/dist/agents/chatbot/services/field-formatting.d.ts

@@ -0,0 +1,18 @@
+import { CatalogField } from "../interfaces/graph.catalog.interface";
+import { FieldKind } from "../../../common/interfaces/entity.schema.interface";
+/**
+ * Format a money field's raw minor-unit integer as a decimal string the LLM
+ * can safely quote to the user (e.g. 600 with minorUnits=2 → "6.00").
+ * Returns null when the value is not a finite number so callers can skip
+ * emitting a companion key for missing / null values.
+ */
+export declare function formatMoneyField(value: unknown, kind: FieldKind): string | null;
+/**
+ * Build the `fields` object a tool returns to the LLM for one record.
+ * Emits the raw scalar for every catalogued field, and for money fields
+ * also emits a sibling `<name>_formatted` decimal string alongside the raw
+ * integer. The sibling name mirrors the prompt's documented convention so
+ * the LLM quotes the formatted string instead of the raw minor-unit integer.
+ */
+export declare function buildToolFieldsOutput(fields: CatalogField[], record: Record<string, unknown>): Record<string, unknown>;
+//# sourceMappingURL=field-formatting.d.ts.map

package/dist/agents/chatbot/services/field-formatting.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-formatting.d.ts","sourceRoot":"","sources":["../../../../src/agents/chatbot/services/field-formatting.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,uCAAuC,CAAC;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,oDAAoD,CAAC;AAE/E;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAO/E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,YAAY,EAAE,EACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAazB"}

package/dist/agents/chatbot/services/field-formatting.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatMoneyField = formatMoneyField;
+exports.buildToolFieldsOutput = buildToolFieldsOutput;
+/**
+ * Format a money field's raw minor-unit integer as a decimal string the LLM
+ * can safely quote to the user (e.g. 600 with minorUnits=2 → "6.00").
+ * Returns null when the value is not a finite number so callers can skip
+ * emitting a companion key for missing / null values.
+ */
+function formatMoneyField(value, kind) {
+    if (kind.type !== "money")
+        return null;
+    if (typeof value !== "number" || !Number.isFinite(value))
+        return null;
+    const minor = kind.minorUnits ?? 2;
+    if (minor === 0)
+        return String(Math.trunc(value));
+    const factor = 10 ** minor;
+    return (value / factor).toFixed(minor);
+}
+/**
+ * Build the `fields` object a tool returns to the LLM for one record.
+ * Emits the raw scalar for every catalogued field, and for money fields
+ * also emits a sibling `<name>_formatted` decimal string alongside the raw
+ * integer. The sibling name mirrors the prompt's documented convention so
+ * the LLM quotes the formatted string instead of the raw minor-unit integer.
+ */
+function buildToolFieldsOutput(fields, record) {
+    const out = {};
+    for (const f of fields) {
+        const value = record[f.name];
+        out[f.name] = value;
+        if (f.kind?.type === "money") {
+            const formatted = formatMoneyField(value, f.kind);
+            if (formatted !== null) {
+                out[`${f.name}_formatted`] = formatted;
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=field-formatting.js.map

package/dist/agents/chatbot/services/field-formatting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-formatting.js","sourceRoot":"","sources":["../../../../src/agents/chatbot/services/field-formatting.ts"],"names":[],"mappings":";;AASA,4CAOC;AASD,sDAgBC;AAtCD;;;;;GAKG;AACH,SAAgB,gBAAgB,CAAC,KAAc,EAAE,IAAe;IAC9D,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACvC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtE,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;IACnC,IAAI,KAAK,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;IAClD,MAAM,MAAM,GAAG,EAAE,IAAI,KAAK,CAAC;IAC3B,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,SAAgB,qBAAqB,CACnC,MAAsB,EACtB,MAA+B;IAE/B,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,IAAI,MAAM,EAAE,CAAC;QACvB,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC7B,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC;QACpB,IAAI,CAAC,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,EAAE,CAAC;YAC7B,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;YAClD,IAAI,SAAS,KAAK,IAAI,EAAE,CAAC;gBACvB,GAAG,CAAC,GAAG,CAAC,CAAC,IAAI,YAAY,CAAC,GAAG,SAAS,CAAC;YACzC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/agents/chatbot/services/graph.catalog.service.d.ts

@@ -0,0 +1,60 @@
+import { OnApplicationBootstrap } from "@nestjs/common";
+import { CatalogEntity } from "../interfaces/graph.catalog.interface";
+import { FieldKind } from "../../../common/interfaces/entity.schema.interface";
+/**
+ * Provided by the library bootstrap layer. Must return the full list of registered
+ * entity descriptors (including their `moduleId` — the stable UUID of the `(Module)`
+ * node in Neo4j, supplied by the feature module at `graphRegistry.register()` time).
+ */
+export interface DescriptorSource {
+    loadAll(): Array<{
+        model: {
+            type: string;
+            nodeName: string;
+            labelName: string;
+        };
+        description?: string;
+        moduleId: string;
+        fields: Record<string, {
+            type: string;
+            description?: string;
+            kind?: FieldKind;
+        }>;
+        relationships: Record<string, {
+            model: {
+                type: string;
+                nodeName: string;
+                labelName: string;
+            };
+            direction: "in" | "out";
+            relationship: string;
+            cardinality: "one" | "many";
+            description?: string;
+            reverse?: {
+                name: string;
+                description: string;
+            };
+        }>;
+        chat?: {
+            summary?: (d: any) => string;
+            textSearchFields?: string[];
+        };
+    }>;
+}
+export declare class GraphCatalogService implements OnApplicationBootstrap {
+    private readonly source;
+    private readonly logger;
+    private entities;
+    /** Keyed by `moduleId` (UUID), value is the pre-rendered text fragment. */
+    private renderedByModuleId;
+    constructor(source: DescriptorSource);
+    onApplicationBootstrap(): void;
+    buildCatalog(): void;
+    private renderModule;
+    getMapFor(userModuleIds: string[]): string;
+    private filterCrossModule;
+    getAllChatEnabledEntities(): CatalogEntity[];
+    hasType(type: string): boolean;
+    getEntityDetail(type: string, userModuleIds: string[]): CatalogEntity | null;
+}
+//# sourceMappingURL=graph.catalog.service.d.ts.map