@carlonicora/nestjs-neo4jsonapi 1.4.1 → 1.5.1

package/dist/agents/drift/services/drift.migration.service.d.ts

@@ -0,0 +1,47 @@
+import { ClsService } from "nestjs-cls";
+import { AppLoggingService } from "../../../core/logging/services/logging.service";
+import { CommunityRepository } from "../../../foundations/community/repositories/community.repository";
+import { CompanyRepository } from "../../../foundations/company/repositories/company.repository";
+import { CommunityDetectorService } from "../../community.detector/services/community.detector.service";
+export interface MigrationResult {
+    totalCompanies: number;
+    processedCompanies: number;
+    failedCompanies: string[];
+    communitiesCreated: number;
+}
+export declare class DriftMigrationService {
+    private readonly logger;
+    private readonly clsService;
+    private readonly companyRepository;
+    private readonly communityRepository;
+    private readonly communityDetectorService;
+    constructor(logger: AppLoggingService, clsService: ClsService, companyRepository: CompanyRepository, communityRepository: CommunityRepository, communityDetectorService: CommunityDetectorService);
+    /**
+     * Run DRIFT migration for all companies
+     * This detects communities for all existing KeyConcepts
+     * The community summariser cron job will then generate summaries
+     */
+    migrateAll(): Promise<MigrationResult>;
+    /**
+     * Run DRIFT migration for a specific company
+     * Sets up CLS context and runs community detection
+     */
+    migrateCompany(companyId: string): Promise<void>;
+    /**
+     * Get migration status - count stale vs processed communities per company
+     */
+    getMigrationStatus(): Promise<{
+        companies: {
+            companyId: string;
+            companyName: string;
+            totalCommunities: number;
+            staleCommunities: number;
+            processedCommunities: number;
+        }[];
+    }>;
+    /**
+     * Get community counts for a specific company
+     */
+    private getCommunityCountsForCompany;
+}
+//# sourceMappingURL=drift.migration.service.d.ts.map

package/dist/agents/drift/services/drift.migration.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.migration.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/drift/services/drift.migration.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,mBAAmB,EAAE,MAAM,kEAAkE,CAAC;AACvG,OAAO,EAAE,iBAAiB,EAAE,MAAM,8DAA8D,CAAC;AACjG,OAAO,EAAE,wBAAwB,EAAE,MAAM,8DAA8D,CAAC;AAExG,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAC;IACvB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAED,qBACa,qBAAqB;IAE9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,iBAAiB;IAClC,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,wBAAwB;gBAJxB,MAAM,EAAE,iBAAiB,EACzB,UAAU,EAAE,UAAU,EACtB,iBAAiB,EAAE,iBAAiB,EACpC,mBAAmB,EAAE,mBAAmB,EACxC,wBAAwB,EAAE,wBAAwB;IAGrE;;;;OAIG;IACG,UAAU,IAAI,OAAO,CAAC,eAAe,CAAC;IAqC5C;;;OAGG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYtD;;OAEG;IACG,kBAAkB,IAAI,OAAO,CAAC;QAClC,SAAS,EAAE;YACT,SAAS,EAAE,MAAM,CAAC;YAClB,WAAW,EAAE,MAAM,CAAC;YACpB,gBAAgB,EAAE,MAAM,CAAC;YACzB,gBAAgB,EAAE,MAAM,CAAC;YACzB,oBAAoB,EAAE,MAAM,CAAC;SAC9B,EAAE,CAAC;KACL,CAAC;IAsBF;;OAEG;YACW,4BAA4B;CAqB3C"}

package/dist/agents/drift/services/drift.migration.service.js

@@ -0,0 +1,114 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriftMigrationService = void 0;
+const common_1 = require("@nestjs/common");
+const nestjs_cls_1 = require("nestjs-cls");
+const logging_service_1 = require("../../../core/logging/services/logging.service");
+const community_repository_1 = require("../../../foundations/community/repositories/community.repository");
+const company_repository_1 = require("../../../foundations/company/repositories/company.repository");
+const community_detector_service_1 = require("../../community.detector/services/community.detector.service");
+let DriftMigrationService = class DriftMigrationService {
+    constructor(logger, clsService, companyRepository, communityRepository, communityDetectorService) {
+        this.logger = logger;
+        this.clsService = clsService;
+        this.companyRepository = companyRepository;
+        this.communityRepository = communityRepository;
+        this.communityDetectorService = communityDetectorService;
+    }
+    /**
+     * Run DRIFT migration for all companies
+     * This detects communities for all existing KeyConcepts
+     * The community summariser cron job will then generate summaries
+     */
+    async migrateAll() {
+        this.logger.log("Starting DRIFT migration for all companies", "DriftMigrationService");
+        const result = {
+            totalCompanies: 0,
+            processedCompanies: 0,
+            failedCompanies: [],
+            communitiesCreated: 0,
+        };
+        const companies = await this.companyRepository.fetchAll();
+        result.totalCompanies = companies.length;
+        this.logger.log(`Found ${companies.length} companies to process`, "DriftMigrationService");
+        for (const company of companies) {
+            try {
+                await this.migrateCompany(company.id);
+                result.processedCompanies++;
+                this.logger.log(`Processed company ${company.id} (${company.name})`, "DriftMigrationService");
+            }
+            catch (error) {
+                result.failedCompanies.push(company.id);
+                this.logger.error(`Failed to process company ${company.id}: ${error.message}`, "DriftMigrationService");
+            }
+        }
+        this.logger.log(`DRIFT migration completed: ${result.processedCompanies}/${result.totalCompanies} companies processed`, "DriftMigrationService");
+        return result;
+    }
+    /**
+     * Run DRIFT migration for a specific company
+     * Sets up CLS context and runs community detection
+     */
+    async migrateCompany(companyId) {
+        await this.clsService.run(async () => {
+            this.clsService.set("companyId", companyId);
+            this.logger.debug(`Running community detection for company ${companyId}`, "DriftMigrationService");
+            await this.communityDetectorService.detectCommunities();
+            this.logger.debug(`Community detection completed for company ${companyId}`, "DriftMigrationService");
+        });
+    }
+    /**
+     * Get migration status - count stale vs processed communities per company
+     */
+    async getMigrationStatus() {
+        const companies = await this.companyRepository.fetchAll();
+        const status = [];
+        for (const company of companies) {
+            const counts = await this.getCommunityCountsForCompany(company.id);
+            status.push({
+                companyId: company.id,
+                companyName: company.name,
+                ...counts,
+            });
+        }
+        return { companies: status };
+    }
+    /**
+     * Get community counts for a specific company
+     */
+    async getCommunityCountsForCompany(companyId) {
+        return new Promise((resolve) => {
+            this.clsService.run(async () => {
+                this.clsService.set("companyId", companyId);
+                const levelCounts = await this.communityRepository.countByLevel();
+                const staleCommunities = await this.communityRepository.findStaleCommunities(1000);
+                const totalCommunities = (levelCounts ?? []).reduce((sum, lc) => sum + lc.count, 0);
+                const staleCount = (staleCommunities ?? []).length;
+                resolve({
+                    totalCommunities,
+                    staleCommunities: staleCount,
+                    processedCommunities: totalCommunities - staleCount,
+                });
+            });
+        });
+    }
+};
+exports.DriftMigrationService = DriftMigrationService;
+exports.DriftMigrationService = DriftMigrationService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [logging_service_1.AppLoggingService,
+        nestjs_cls_1.ClsService,
+        company_repository_1.CompanyRepository,
+        community_repository_1.CommunityRepository,
+        community_detector_service_1.CommunityDetectorService])
+], DriftMigrationService);
+//# sourceMappingURL=drift.migration.service.js.map

package/dist/agents/drift/services/drift.migration.service.js.map

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

package/dist/agents/drift/services/drift.search.service.d.ts

@@ -0,0 +1,52 @@
+import { AppLoggingService } from "../../../core/logging/services/logging.service";
+import { TracingService } from "../../../core/tracing/services/tracing.service";
+import { Community } from "../../../foundations/community/entities/community.entity";
+import { FollowUpAnswer } from "../contexts/drift.context";
+import { CommunitySearchNodeService } from "../nodes/community.search.node.service";
+import { FollowUpNodeService } from "../nodes/followup.node.service";
+import { HydeNodeService } from "../nodes/hyde.node.service";
+import { PrimerAnswerNodeService } from "../nodes/primer.answer.node.service";
+import { SynthesisNodeService } from "../nodes/synthesis.node.service";
+export interface DriftSearchResult {
+    answer: string;
+    matchedCommunities: Community[];
+    followUpAnswers: FollowUpAnswer[];
+    initialAnswer: string;
+    confidence: number;
+    hydeEmbedding: number[];
+}
+export interface DriftConfig {
+    primerTopK?: number;
+    followUpDepth?: number;
+}
+export declare class DriftSearchService {
+    private readonly hydeNode;
+    private readonly communitySearchNode;
+    private readonly primerAnswerNode;
+    private readonly followUpNode;
+    private readonly synthesisNode;
+    private readonly logger;
+    private readonly tracer;
+    constructor(hydeNode: HydeNodeService, communitySearchNode: CommunitySearchNodeService, primerAnswerNode: PrimerAnswerNodeService, followUpNode: FollowUpNodeService, synthesisNode: SynthesisNodeService, logger: AppLoggingService, tracer: TracingService);
+    /**
+     * Run full DRIFT search workflow using LangGraph StateGraph:
+     * 1. HyDE: Generate hypothetical document embedding
+     * 2. Community Search: Vector search against community summaries
+     * 3. Primer Answer: Generate initial answer + follow-up questions
+     * 4. Follow-up: Process follow-up questions iteratively
+     * 5. Synthesis: Combine all answers into final response
+     */
+    search(params: {
+        question: string;
+        config?: DriftConfig;
+    }): Promise<DriftSearchResult>;
+    /**
+     * Quick search - just HyDE + community search + primer answer (no follow-ups)
+     * Useful for when you want fast results
+     */
+    quickSearch(params: {
+        question: string;
+        topK?: number;
+    }): Promise<DriftSearchResult>;
+}
+//# sourceMappingURL=drift.search.service.d.ts.map

package/dist/agents/drift/services/drift.search.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drift.search.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/drift/services/drift.search.service.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,MAAM,gDAAgD,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,MAAM,0DAA0D,CAAC;AACrF,OAAO,EAAmC,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAC5F,OAAO,EAAE,0BAA0B,EAAE,MAAM,wCAAwC,CAAC;AACpF,OAAO,EAAE,mBAAmB,EAAE,MAAM,gCAAgC,CAAC;AACrE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AAC9E,OAAO,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC;AAEvE,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,SAAS,EAAE,CAAC;IAChC,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,WAAW;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,qBACa,kBAAkB;IAE3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,gBAAgB;IACjC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,aAAa;IAC9B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM;gBANN,QAAQ,EAAE,eAAe,EACzB,mBAAmB,EAAE,0BAA0B,EAC/C,gBAAgB,EAAE,uBAAuB,EACzC,YAAY,EAAE,mBAAmB,EACjC,aAAa,EAAE,oBAAoB,EACnC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,cAAc;IAGzC;;;;;;;OAOG;IACG,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAqI5F;;;OAGG;IACG,WAAW,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;CAS3F"}

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

@@ -0,0 +1,185 @@
+"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);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DriftSearchService = void 0;
+const langgraph_1 = require("@langchain/langgraph");
+const common_1 = require("@nestjs/common");
+const crypto_1 = require("crypto");
+const logging_service_1 = require("../../../core/logging/services/logging.service");
+const tracing_service_1 = require("../../../core/tracing/services/tracing.service");
+const drift_context_1 = require("../contexts/drift.context");
+const community_search_node_service_1 = require("../nodes/community.search.node.service");
+const followup_node_service_1 = require("../nodes/followup.node.service");
+const hyde_node_service_1 = require("../nodes/hyde.node.service");
+const primer_answer_node_service_1 = require("../nodes/primer.answer.node.service");
+const synthesis_node_service_1 = require("../nodes/synthesis.node.service");
+let DriftSearchService = class DriftSearchService {
+    constructor(hydeNode, communitySearchNode, primerAnswerNode, followUpNode, synthesisNode, logger, tracer) {
+        this.hydeNode = hydeNode;
+        this.communitySearchNode = communitySearchNode;
+        this.primerAnswerNode = primerAnswerNode;
+        this.followUpNode = followUpNode;
+        this.synthesisNode = synthesisNode;
+        this.logger = logger;
+        this.tracer = tracer;
+    }
+    /**
+     * Run full DRIFT search workflow using LangGraph StateGraph:
+     * 1. HyDE: Generate hypothetical document embedding
+     * 2. Community Search: Vector search against community summaries
+     * 3. Primer Answer: Generate initial answer + follow-up questions
+     * 4. Follow-up: Process follow-up questions iteratively
+     * 5. Synthesis: Combine all answers into final response
+     */
+    async search(params) {
+        const config = params.config ?? {};
+        const maxHops = 20;
+        this.logger.log(`Starting DRIFT search for: "${params.question}"`, "DriftSearchService");
+        this.tracer.startSpan("DRIFT Search Workflow", {
+            attributes: {
+                question: params.question,
+                topK: config.primerTopK ?? 5,
+                maxDepth: config.followUpDepth ?? 2,
+                maxHops,
+            },
+        });
+        const returnState = (state) => {
+            const nextStep = state.hops >= maxHops ? "synthesis" : state.nextStep;
+            return nextStep === "end" ? langgraph_1.END : nextStep;
+        };
+        const workflow = new langgraph_1.StateGraph(drift_context_1.DriftContext)
+            .addNode("hyde", async (state) => {
+            this.tracer.addSpanEvent(`Node: hyde - hop ${state.hops}/${maxHops}`, { hopCount: state.hops });
+            const result = await this.hydeNode.execute({ state });
+            this.tracer.addSpanEvent(`Node: hyde complete`, { nextStep: result.nextStep });
+            return result;
+        })
+            .addNode("community_search", async (state) => {
+            this.tracer.addSpanEvent(`Node: community_search - hop ${state.hops}/${maxHops}`, { hopCount: state.hops });
+            const result = await this.communitySearchNode.execute({ state });
+            this.tracer.addSpanEvent(`Node: community_search complete`, {
+                communitiesFound: result.matchedCommunities?.length ?? 0,
+                nextStep: result.nextStep,
+            });
+            return result;
+        })
+            .addNode("primer_answer", async (state) => {
+            this.tracer.addSpanEvent(`Node: primer_answer - hop ${state.hops}/${maxHops}`, { hopCount: state.hops });
+            const result = await this.primerAnswerNode.execute({ state });
+            this.tracer.addSpanEvent(`Node: primer_answer complete`, {
+                confidence: result.confidence,
+                followUpCount: result.followUpQuestions?.length ?? 0,
+                nextStep: result.nextStep,
+            });
+            return result;
+        })
+            .addNode("followup", async (state) => {
+            this.tracer.addSpanEvent(`Node: followup - hop ${state.hops}/${maxHops}`, {
+                hopCount: state.hops,
+                questionIndex: state.currentFollowUpIndex,
+                depth: state.currentDepth,
+            });
+            const result = await this.followUpNode.execute({ state });
+            this.tracer.addSpanEvent(`Node: followup complete`, { nextStep: result.nextStep });
+            return result;
+        })
+            .addNode("synthesis", async (state) => {
+            this.tracer.addSpanEvent(`Node: synthesis - hop ${state.hops}/${maxHops} (final)`, { hopCount: state.hops });
+            const result = await this.synthesisNode.execute({ state });
+            this.tracer.addSpanEvent(`Node: synthesis complete`);
+            return result;
+        })
+            .addEdge(langgraph_1.START, "hyde")
+            .addEdge("hyde", "community_search")
+            .addConditionalEdges("community_search", (state) => returnState(state))
+            .addConditionalEdges("primer_answer", (state) => returnState(state))
+            .addConditionalEdges("followup", (state) => returnState(state))
+            .addEdge("synthesis", langgraph_1.END);
+        const threadId = (0, crypto_1.randomUUID)();
+        const checkpointer = new langgraph_1.MemorySaver();
+        const app = workflow.compile({ checkpointer });
+        const initialState = {
+            question: params.question,
+            topK: config.primerTopK ?? 5,
+            maxDepth: config.followUpDepth ?? 2,
+            nextStep: "hyde",
+            hops: 0,
+            hypotheticalAnswer: "",
+            hydeEmbedding: [],
+            matchedCommunities: [],
+            communitySummaries: "",
+            initialAnswer: "",
+            followUpQuestions: [],
+            confidence: 0,
+            currentFollowUpIndex: 0,
+            currentDepth: 0,
+            followUpAnswers: [],
+            priorContext: "",
+            finalAnswer: "",
+            tokens: { input: 0, output: 0 },
+        };
+        this.tracer.addSpanEvent("Workflow Executing");
+        let finalState;
+        try {
+            finalState = await app.invoke(initialState, {
+                configurable: { thread_id: threadId },
+                recursionLimit: maxHops + 5,
+            });
+            this.tracer.addSpanEvent("Workflow Completed", {
+                finalHopCount: finalState.hops,
+                communitiesMatched: finalState.matchedCommunities.length,
+                followUpAnswersCount: finalState.followUpAnswers.length,
+            });
+            this.tracer.setSpanSuccess();
+            this.tracer.endSpan();
+        }
+        catch (e) {
+            this.tracer.setSpanError(e);
+            this.tracer.endSpan();
+            this.logger.error(`DRIFT workflow failed: ${e.message}`, "DriftSearchService");
+            throw e;
+        }
+        this.logger.log(`DRIFT search complete: ${finalState.matchedCommunities.length} communities, ${finalState.followUpAnswers.length} follow-ups, ${finalState.hops} hops`, "DriftSearchService");
+        return {
+            answer: finalState.finalAnswer,
+            matchedCommunities: finalState.matchedCommunities,
+            followUpAnswers: finalState.followUpAnswers,
+            initialAnswer: finalState.initialAnswer,
+            confidence: finalState.confidence,
+            hydeEmbedding: finalState.hydeEmbedding,
+        };
+    }
+    /**
+     * Quick search - just HyDE + community search + primer answer (no follow-ups)
+     * Useful for when you want fast results
+     */
+    async quickSearch(params) {
+        return this.search({
+            question: params.question,
+            config: {
+                primerTopK: params.topK,
+                followUpDepth: 0, // Skip follow-ups
+            },
+        });
+    }
+};
+exports.DriftSearchService = DriftSearchService;
+exports.DriftSearchService = DriftSearchService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [hyde_node_service_1.HydeNodeService,
+        community_search_node_service_1.CommunitySearchNodeService,
+        primer_answer_node_service_1.PrimerAnswerNodeService,
+        followup_node_service_1.FollowUpNodeService,
+        synthesis_node_service_1.SynthesisNodeService,
+        logging_service_1.AppLoggingService,
+        tracing_service_1.TracingService])
+], DriftSearchService);
+//# sourceMappingURL=drift.search.service.js.map

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

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

package/dist/agents/graph.creator/interfaces/chunk.analysis.interface.d.ts

@@ -9,6 +9,10 @@ export interface ChunkAnalysisInterface {
         keyConcept2: string;
         relationship: string;
     }[];
+    keyConceptDescriptions: {
+        keyConcept: string;
+        description: string;
+    }[];
     tokens: TokenUsageInterface;
 }
 //# sourceMappingURL=chunk.analysis.interface.d.ts.map

package/dist/agents/graph.creator/interfaces/chunk.analysis.interface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"chunk.analysis.interface.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph.creator/interfaces/chunk.analysis.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAEvF,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,EAAE,CAAC;IACJ,wBAAwB,EAAE;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACtB,EAAE,CAAC;IACJ,MAAM,EAAE,mBAAmB,CAAC;CAC7B"}
+{"version":3,"file":"chunk.analysis.interface.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph.creator/interfaces/chunk.analysis.interface.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,kDAAkD,CAAC;AAEvF,MAAM,WAAW,sBAAsB;IACrC,WAAW,EAAE;QACX,OAAO,EAAE,MAAM,CAAC;QAChB,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB,EAAE,CAAC;IACJ,wBAAwB,EAAE;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;KACtB,EAAE,CAAC;IACJ,sBAAsB,EAAE;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,WAAW,EAAE,MAAM,CAAC;KACrB,EAAE,CAAC;IACJ,MAAM,EAAE,mBAAmB,CAAC;CAC7B"}

package/dist/agents/graph.creator/services/graph.creator.service.d.ts

@@ -3,7 +3,7 @@ import { BaseConfigInterface } from "../../../config/interfaces";
 import { LLMService } from "../../../core/llm/services/llm.service";
 import { AppLoggingService } from "../../../core/logging/services/logging.service";
 import { ChunkAnalysisInterface } from "../../graph.creator/interfaces/chunk.analysis.interface";
-export declare const prompt = "\nYou are an intelligent assistant that extracts structured knowledge from text.\n\n## CRITICAL: Garbage Detection\n\n**BEFORE attempting any extraction, evaluate if the text is intelligible.**\n\nIf the text contains:\n- Unintelligible OCR garbage or random characters (e.g., \"!\u00A7Ydsv$\", \"aitsru{.*U\", \"Q\u00A7tvllvll\")\n- Mostly punctuation marks with no semantic meaning (e.g., \"!!!\", \"===\", \"|||\")\n- Random character sequences that form no recognizable words\n- Repetitive meaningless patterns\n- No coherent sentences or semantic content\n\n**Then you MUST:**\n- Return EMPTY atomicFacts array: []\n- Return EMPTY keyConceptsRelationships array: []\n- Do NOT attempt to extract anything from garbage text\n\n## Definitions\n\n**Atomic Fact**: A single, indivisible statement containing **ONE action, ONE event, or ONE relationship**. Each atomic fact must represent the smallest unit of meaningful information that cannot be broken down further.\n\n**CRITICAL: ONE ACTION PER FACT**\n- Each atomic fact must contain ONLY ONE verb/action\n- If a sentence contains multiple actions connected by \"and\", \"but\", commas, split it into separate atomic facts\n- Each action, decision, or event gets its own atomic fact\n\n**Examples of CORRECT Atomic Facts (one action each):**\n- \u2705 \"The president detects the ambiguity of the notification\"\n- \u2705 \"The president grants an extension until 15/2/2023\"\n- \u2705 \"The president postpones the hearing to 29/3/2023\"\n- \u2705 \"Joe Bauer was born in London on 03.04.1985\"\n\n**Examples of INCORRECT Atomic Facts (multiple actions - MUST BE SPLIT):**\n- \u274C \"The president detects the ambiguity of the notification, grants an extension until 15/2/2023 and postpones the hearing to 29/3/2023\"\n  \u2192 WRONG: Contains 3 actions (detects, grants, postpones) - must be split into 3 atomic facts\n- \u274C \"Joe Bauer was born in London and studied at university\"\n  \u2192 WRONG: Contains 2 actions (was born, studied) - must be split into 2 atomic facts\n\n**Key Concept**: ONLY semantically meaningful entities - proper nouns, specific terms, named entities:\n\n**VALID Key Concepts (extract these):**\n- **Proper names**: \"joe bauer\", \"mike modano\", ...\n- **Places**: \"london\", \"italy\", \"rome\", \"washington\", ...\n- **Organizations**: \"microsoft\", \"apple\", \"phlow\", \"united nations\", \"tribunale di roma\", ...\n- **Complete dates with legal significance**: \"28.12.2019\", \"15/2/2023\", \"29/3/2023\", \"03.04.1985\", \"15 january 2023\"\n  - \u2705 ONLY extract dates that are significant to the atomic fact\n  - \u2705 Include time ONLY when paired with a date AND relevant to the atomic fact: \"29/3/2023 alle 10.40\"\n- **Acronyms**: \"upu\", \"nlp\", \"api\", \"crm\", \"d.p.r.\", \"c.c.\", \"c.p.\" (always lowercase)\n- **Technical terms**: \"knowledge base\", \"semantic search\", \"blockchain\"\n- **Products/systems**: \"kubernetes\", \"microsoft\", \"s3\"\n\n**INVALID Key Concepts (NEVER extract these):**\n- \u274C Single characters: \"!\", \"e\", \"i\", \"a\", \"o\", \"n\", \"'\"\n- \u274C Pure punctuation: \".\", \",\", \":\", \";\", \"(\", \")\", \"[\", \"]\"\n- \u274C Random garbage: \"!\u00A7Ydsv$\", \"Q\u00A7tvllvll\", \"aitsru{.*U\", \"ourpEl}r\"\n- \u274C Meaningless sequences: \"||!\", \"===\", \"___\", \"***\"\n- \u274C Pure numbers without context: \"254\", \"819\", \"123\"\n- \u274C **Isolated times without dates**: \"12.40\", \"10:30\", \"15.00\" (unless part of legally significant event like \"udienza alle 10.40\" with date)\n- \u274C **Administrative timestamps**: \"verbale chiuso alle 12.40\", \"documento firmato alle 15.00\" (not legally significant)\n- \u274C Generic words without specific meaning: \"thing\", \"way\", \"type\", \"method\"\n\n**Markdown Headers**: Structural elements like \"## Data Architecture\" that organize content.\n\n## Instructions\n\n1. **Evaluate text quality** - Is this intelligible text or garbage? If garbage, return empty arrays.\n2. **Check for markdown headers** - If text starts with ##, ###, etc., note the complete header text\n3. **Decompose compound sentences** - If a sentence contains multiple actions/verbs (connected by \"and\", \"but\", commas):\n   - Break it into separate atomic facts\n   - Each action gets its own atomic fact\n   - Example: \"The president detects the ambiguity, grants an extension and postpones the hearing\" \u2192 3 atomic facts\n4. **Extract atomic facts** - Only from intelligible, meaningful text. ONE ACTION PER FACT.\n5. **MANDATORY: Create summary atomic fact** - Must include the markdown header if present. Example: \"Recommendation 1 focuses on improving UPU service standards\" (key concepts: \"recommendation 1\", \"upu\", \"service standards\")\n6. **Identify key concepts** - Only SEMANTICALLY MEANINGFUL entities (names, places, significant dates, organizations, legal terms)\n7. **Create relationships** - Between valid key concepts based on how they connect in atomic facts\n\n## Atomic Fact Rules\n\n**CRITICAL: ONE ACTION/EVENT PER ATOMIC FACT**\n- Each atomic fact must contain ONLY ONE verb/action\n- If you see multiple verbs in a sentence (e.g., \"detects\", \"grants\", \"postpones\"), create separate atomic facts for each\n- Use the subject from the original sentence for each split fact\n- Each atomic fact must be a complete, grammatically correct sentence\n\n**Decomposition Process:**\n1. Identify all verbs/actions in the sentence\n2. Count them - if more than one, decomposition is required\n3. Create one atomic fact per action, maintaining the subject\n4. Example:\n   - Input: \"The president detects the ambiguity, grants an extension and postpones the hearing\"\n   - Actions found: \"detects\" (1), \"grants\" (2), \"postpones\" (3) = 3 actions\n   - Output: 3 atomic facts:\n     1. \"The president detects the ambiguity\"\n     2. \"The president grants an extension\"\n     3. \"The president postpones the hearing\"\n\n## Key Concept Rules\n\n- Key concepts **MUST** be semantically meaningful entities (see examples above)\n- **COPY VERBATIM** from the text (lowercasing allowed, no other changes)\n- Minimum 2 characters length\n- Must contain actual semantic meaning (not punctuation, not single letters)\n- **DO NOT change** spelling, letters, or structure\n- Always include acronyms and technical terms found in text\n- Include complete markdown headers as Key Concepts: \"## Recommendation 1\" becomes \"recommendation 1\"\n- Every key concept must appear in at least one atomic fact\n\n**Character Requirements:**\n- Must have at least 40% alphanumeric characters (not mostly punctuation)\n- Cannot be pure punctuation or special characters\n- Cannot be random character sequences\n\n## Relationships Rules\n\n**Key Concepts Relationships**: Analyze relationships between key concepts to create a network graph.\n- For each relationship:\n  - **node_1**: First key concept (must be a valid key concept from extraction)\n  - **node_2**: Second key concept (must be a valid key concept from extraction)\n  - **edge**: Sentence describing the relationship in present tense\n- Only create relationships between VALID key concepts\n- Both nodes must be semantically meaningful entities\n\n## Additional Considerations\n\n- **DECOMPOSE compound sentences** - Always split sentences with multiple actions into separate atomic facts\n- Focus on extracting **named entities** and **specific domain terminology**\n- Ignore filler words, articles, prepositions, conjunctions\n- Pay special attention to proper names, places, significant dates, organizations, and legal entities\n- Terms mentioned in the same sentence or paragraph are typically related\n\n## CRITICAL: Quality over Quantity\n\n- It is BETTER to return empty arrays than to extract garbage\n- Only extract from intelligible, meaningful text\n- Every key concept must be a real entity with semantic meaning\n- Single characters, punctuation, and random sequences are NEVER valid key concepts\n\n## CRITICAL: Atomic Fact Decomposition\n\n**MANDATORY PROCESS FOR EVERY SENTENCE:**\n1. Count the number of actions/verbs in the sentence\n2. If count > 1, YOU MUST split into separate atomic facts\n3. Each action gets its own atomic fact with complete subject and context\n4. NEVER create compound atomic facts with multiple actions\n\n**Remember:**\n- \u274C WRONG: \"The president detects, grants and postpones\" (3 actions in 1 fact)\n- \u2705 RIGHT: Three separate facts - one for \"detects\", one for \"grants\", one for \"postpones\"\n\n## **Strictly follow the above instructions. Evaluate text quality first, then decompose compound sentences. Begin.**\n";
+export declare const prompt = "\nYou are an intelligent assistant that extracts structured knowledge from text.\n\n## CRITICAL: Garbage Detection\n\n**BEFORE attempting any extraction, evaluate if the text is intelligible.**\n\nIf the text contains:\n- Unintelligible OCR garbage or random characters (e.g., \"!\u00A7Ydsv$\", \"aitsru{.*U\", \"Q\u00A7tvllvll\")\n- Mostly punctuation marks with no semantic meaning (e.g., \"!!!\", \"===\", \"|||\")\n- Random character sequences that form no recognizable words\n- Repetitive meaningless patterns\n- No coherent sentences or semantic content\n\n**Then you MUST:**\n- Return EMPTY atomicFacts array: []\n- Return EMPTY keyConceptsRelationships array: []\n- Do NOT attempt to extract anything from garbage text\n\n## Definitions\n\n**Atomic Fact**: A single, indivisible statement containing **ONE action, ONE event, or ONE relationship**. Each atomic fact must represent the smallest unit of meaningful information that cannot be broken down further.\n\n**CRITICAL: ONE ACTION PER FACT**\n- Each atomic fact must contain ONLY ONE verb/action\n- If a sentence contains multiple actions connected by \"and\", \"but\", commas, split it into separate atomic facts\n- Each action, decision, or event gets its own atomic fact\n\n**Examples of CORRECT Atomic Facts (one action each):**\n- \u2705 \"The president detects the ambiguity of the notification\"\n- \u2705 \"The president grants an extension until 15/2/2023\"\n- \u2705 \"The president postpones the hearing to 29/3/2023\"\n- \u2705 \"Joe Bauer was born in London on 03.04.1985\"\n\n**Examples of INCORRECT Atomic Facts (multiple actions - MUST BE SPLIT):**\n- \u274C \"The president detects the ambiguity of the notification, grants an extension until 15/2/2023 and postpones the hearing to 29/3/2023\"\n  \u2192 WRONG: Contains 3 actions (detects, grants, postpones) - must be split into 3 atomic facts\n- \u274C \"Joe Bauer was born in London and studied at university\"\n  \u2192 WRONG: Contains 2 actions (was born, studied) - must be split into 2 atomic facts\n\n**Key Concept**: ONLY semantically meaningful entities - proper nouns, specific terms, named entities:\n\n**VALID Key Concepts (extract these):**\n- **Proper names**: \"joe bauer\", \"mike modano\", ...\n- **Places**: \"london\", \"italy\", \"rome\", \"washington\", ...\n- **Organizations**: \"microsoft\", \"apple\", \"phlow\", \"united nations\", \"tribunale di roma\", ...\n- **Complete dates with legal significance**: \"28.12.2019\", \"15/2/2023\", \"29/3/2023\", \"03.04.1985\", \"15 january 2023\"\n  - \u2705 ONLY extract dates that are significant to the atomic fact\n  - \u2705 Include time ONLY when paired with a date AND relevant to the atomic fact: \"29/3/2023 alle 10.40\"\n- **Acronyms**: \"upu\", \"nlp\", \"api\", \"crm\", \"d.p.r.\", \"c.c.\", \"c.p.\" (always lowercase)\n- **Technical terms**: \"knowledge base\", \"semantic search\", \"blockchain\"\n- **Products/systems**: \"kubernetes\", \"microsoft\", \"s3\"\n\n**INVALID Key Concepts (NEVER extract these):**\n- \u274C Single characters: \"!\", \"e\", \"i\", \"a\", \"o\", \"n\", \"'\"\n- \u274C Pure punctuation: \".\", \",\", \":\", \";\", \"(\", \")\", \"[\", \"]\"\n- \u274C Random garbage: \"!\u00A7Ydsv$\", \"Q\u00A7tvllvll\", \"aitsru{.*U\", \"ourpEl}r\"\n- \u274C Meaningless sequences: \"||!\", \"===\", \"___\", \"***\"\n- \u274C Pure numbers without context: \"254\", \"819\", \"123\"\n- \u274C **Isolated times without dates**: \"12.40\", \"10:30\", \"15.00\" (unless part of legally significant event like \"udienza alle 10.40\" with date)\n- \u274C **Administrative timestamps**: \"verbale chiuso alle 12.40\", \"documento firmato alle 15.00\" (not legally significant)\n- \u274C Generic words without specific meaning: \"thing\", \"way\", \"type\", \"method\"\n\n**Markdown Headers**: Structural elements like \"## Data Architecture\" that organize content.\n\n## Instructions\n\n1. **Evaluate text quality** - Is this intelligible text or garbage? If garbage, return empty arrays.\n2. **Check for markdown headers** - If text starts with ##, ###, etc., note the complete header text\n3. **Decompose compound sentences** - If a sentence contains multiple actions/verbs (connected by \"and\", \"but\", commas):\n   - Break it into separate atomic facts\n   - Each action gets its own atomic fact\n   - Example: \"The president detects the ambiguity, grants an extension and postpones the hearing\" \u2192 3 atomic facts\n4. **Extract atomic facts** - Only from intelligible, meaningful text. ONE ACTION PER FACT.\n5. **MANDATORY: Create summary atomic fact** - Must include the markdown header if present. Example: \"Recommendation 1 focuses on improving UPU service standards\" (key concepts: \"recommendation 1\", \"upu\", \"service standards\")\n6. **Identify key concepts** - Only SEMANTICALLY MEANINGFUL entities (names, places, significant dates, organizations, legal terms)\n7. **Create relationships** - Between valid key concepts based on how they connect in atomic facts\n\n## Atomic Fact Rules\n\n**CRITICAL: ONE ACTION/EVENT PER ATOMIC FACT**\n- Each atomic fact must contain ONLY ONE verb/action\n- If you see multiple verbs in a sentence (e.g., \"detects\", \"grants\", \"postpones\"), create separate atomic facts for each\n- Use the subject from the original sentence for each split fact\n- Each atomic fact must be a complete, grammatically correct sentence\n\n**Decomposition Process:**\n1. Identify all verbs/actions in the sentence\n2. Count them - if more than one, decomposition is required\n3. Create one atomic fact per action, maintaining the subject\n4. Example:\n   - Input: \"The president detects the ambiguity, grants an extension and postpones the hearing\"\n   - Actions found: \"detects\" (1), \"grants\" (2), \"postpones\" (3) = 3 actions\n   - Output: 3 atomic facts:\n     1. \"The president detects the ambiguity\"\n     2. \"The president grants an extension\"\n     3. \"The president postpones the hearing\"\n\n## Key Concept Rules\n\n- Key concepts **MUST** be semantically meaningful entities (see examples above)\n- **COPY VERBATIM** from the text (lowercasing allowed, no other changes)\n- Minimum 2 characters length\n- Must contain actual semantic meaning (not punctuation, not single letters)\n- **DO NOT change** spelling, letters, or structure\n- Always include acronyms and technical terms found in text\n- Include complete markdown headers as Key Concepts: \"## Recommendation 1\" becomes \"recommendation 1\"\n- Every key concept must appear in at least one atomic fact\n\n**Character Requirements:**\n- Must have at least 40% alphanumeric characters (not mostly punctuation)\n- Cannot be pure punctuation or special characters\n- Cannot be random character sequences\n\n## Key Concept Descriptions\n\nFor each unique key concept extracted, generate a brief description (1-2 sentences) that:\n- Explains what the entity is in the context of the document\n- Captures its role, type, or significance\n- Uses information from the text to provide context\n\n**Examples:**\n- \"joe bauer\" \u2192 \"A person born in London who studied at university\"\n- \"tribunale di roma\" \u2192 \"The court of Rome, an Italian judicial institution\"\n- \"upu\" \u2192 \"Universal Postal Union, an international postal organization\"\n- \"15/2/2023\" \u2192 \"Date when the president granted an extension\"\n\n## Relationships Rules\n\n**Key Concepts Relationships**: Analyze relationships between key concepts to create a network graph.\n- For each relationship:\n  - **node_1**: First key concept (must be a valid key concept from extraction)\n  - **node_2**: Second key concept (must be a valid key concept from extraction)\n  - **edge**: Sentence describing the relationship in present tense\n- Only create relationships between VALID key concepts\n- Both nodes must be semantically meaningful entities\n\n## Additional Considerations\n\n- **DECOMPOSE compound sentences** - Always split sentences with multiple actions into separate atomic facts\n- Focus on extracting **named entities** and **specific domain terminology**\n- Ignore filler words, articles, prepositions, conjunctions\n- Pay special attention to proper names, places, significant dates, organizations, and legal entities\n- Terms mentioned in the same sentence or paragraph are typically related\n\n## CRITICAL: Quality over Quantity\n\n- It is BETTER to return empty arrays than to extract garbage\n- Only extract from intelligible, meaningful text\n- Every key concept must be a real entity with semantic meaning\n- Single characters, punctuation, and random sequences are NEVER valid key concepts\n\n## CRITICAL: Atomic Fact Decomposition\n\n**MANDATORY PROCESS FOR EVERY SENTENCE:**\n1. Count the number of actions/verbs in the sentence\n2. If count > 1, YOU MUST split into separate atomic facts\n3. Each action gets its own atomic fact with complete subject and context\n4. NEVER create compound atomic facts with multiple actions\n\n**Remember:**\n- \u274C WRONG: \"The president detects, grants and postpones\" (3 actions in 1 fact)\n- \u2705 RIGHT: Three separate facts - one for \"detects\", one for \"grants\", one for \"postpones\"\n\n## **Strictly follow the above instructions. Evaluate text quality first, then decompose compound sentences. Begin.**\n";
 export declare class GraphCreatorService {
     private readonly llmService;
     private readonly logger;

package/dist/agents/graph.creator/services/graph.creator.service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"graph.creator.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph.creator/services/graph.creator.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAA0B,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,yDAAyD,CAAC;AAEjG,eAAO,MAAM,MAAM,8+QAwJlB,CAAC;AAkKF,qBACa,mBAAmB;IAI5B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IALhC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAAC;IAM9D,aAAa,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC;CAmKlF"}
+{"version":3,"file":"graph.creator.service.d.ts","sourceRoot":"","sources":["../../../../src/agents/graph.creator/services/graph.creator.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAE/C,OAAO,EAAE,mBAAmB,EAA0B,MAAM,4BAA4B,CAAC;AACzF,OAAO,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACpE,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,sBAAsB,EAAE,MAAM,yDAAyD,CAAC;AAEjG,eAAO,MAAM,MAAM,2lSAqKlB,CAAC;AA8KF,qBACa,mBAAmB;IAI5B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa;IALhC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;gBAGnB,UAAU,EAAE,UAAU,EACtB,MAAM,EAAE,iBAAiB,EACzB,aAAa,EAAE,aAAa,CAAC,mBAAmB,CAAC;IAM9D,aAAa,CAAC,MAAM,EAAE;QAAE,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,sBAAsB,CAAC;CA6LlF"}

package/dist/agents/graph.creator/services/graph.creator.service.js

@@ -129,6 +129,19 @@ If the text contains:
 - Cannot be pure punctuation or special characters
 - Cannot be random character sequences
 
+## Key Concept Descriptions
+
+For each unique key concept extracted, generate a brief description (1-2 sentences) that:
+- Explains what the entity is in the context of the document
+- Captures its role, type, or significance
+- Uses information from the text to provide context
+
+**Examples:**
+- "joe bauer" → "A person born in London who studied at university"
+- "tribunale di roma" → "The court of Rome, an Italian judicial institution"
+- "upu" → "Universal Postal Union, an international postal organization"
+- "15/2/2023" → "Date when the president granted an extension"
+
 ## Relationships Rules
 
 **Key Concepts Relationships**: Analyze relationships between key concepts to create a network graph.
@@ -188,6 +201,14 @@ const outputSchema = zod_1.z.object({
             .describe(`Relationship between the two specific entities, node_1 and node_2 in one or two sentences.`),
     }))
         .describe(`List of all the key concepts in the atomic facts and their relationships to one another`),
+    keyConceptDescriptions: zod_1.z
+        .array(zod_1.z.object({
+        keyConcept: zod_1.z.string().describe(`The key concept value (lowercase, exact match from atomicFacts)`),
+        description: zod_1.z
+            .string()
+            .describe(`Brief 1-2 sentence description of what this entity is in the context of the document. Explains its role, type, or significance.`),
+    }))
+        .describe(`Descriptions for each unique key concept extracted from the atomic facts`),
 });
 const inputSchema = zod_1.z.object({
     content: zod_1.z.string().describe("The content to analyse"),
@@ -312,6 +333,7 @@ let GraphCreatorService = class GraphCreatorService {
         const response = {
             atomicFacts: [],
             keyConceptsRelationships: [],
+            keyConceptDescriptions: [],
             tokens: { input: 0, output: 0 },
         };
         if (!params.content || typeof params.content !== "string" || params.content.trim().length === 0) {
@@ -406,12 +428,33 @@ let GraphCreatorService = class GraphCreatorService {
             return null;
         })
             .filter(Boolean);
+        // Collect all valid key concepts from atomicFacts for filtering descriptions
+        const validKeyConcepts = new Set();
+        response.atomicFacts.forEach((fact) => {
+            fact.keyConcepts.forEach((kc) => validKeyConcepts.add(kc));
+        });
+        // Process key concept descriptions - only keep those for valid key concepts
+        response.keyConceptDescriptions = (llmResponse.keyConceptDescriptions || [])
+            ?.map((desc) => {
+            const cleanKeyConcept = (desc.keyConcept || "").trim().toLowerCase();
+            // Only include descriptions for key concepts that exist in our valid set
+            if (isValidKeyConcept(cleanKeyConcept) && validKeyConcepts.has(cleanKeyConcept) && desc.description) {
+                return {
+                    keyConcept: cleanKeyConcept,
+                    description: desc.description.trim(),
+                };
+            }
+            return null;
+        })
+            .filter(Boolean);
         response.tokens = llmResponse.tokenUsage;
         this.logger.debug("Post-LLM filtering completed", "GraphCreatorService", {
             llmExtractedFacts: llmResponse.atomicFacts?.length || 0,
             llmExtractedRelationships: llmResponse.keyConceptsRelationships?.length || 0,
+            llmExtractedDescriptions: llmResponse.keyConceptDescriptions?.length || 0,
             finalAtomicFacts: response.atomicFacts.length,
             finalRelationships: response.keyConceptsRelationships.length,
+            finalDescriptions: response.keyConceptDescriptions.length,
             factsFilteredOut: (llmResponse.atomicFacts?.length || 0) - response.atomicFacts.length,
             relationshipsFilteredOut: (llmResponse.keyConceptsRelationships?.length || 0) - response.keyConceptsRelationships.length,
         });