@carlonicora/nestjs-neo4jsonapi 1.64.0 → 1.65.0

package/dist/agents/responder/nodes/responder.answer.node.service.js

@@ -16,253 +16,97 @@ const config_1 = require("@nestjs/config");
 const zod_1 = require("zod");
 const llm_service_1 = require("../../../core/llm/services/llm.service");
 exports.defaultAnswerPrompt = `
-As an intelligent assistant, your primary objective is to answer questions based on information within a text.
-You have explored multiple paths from various starting nodes on a graph, recording key information for each path in a **notebook**.
-Your task now is to **analyze these memories and reason to answer the question**. 
-
----
-
-### **Strategy:**
-
-1. **Provide a Title**:
-   - Create a short **title** that the user can read as a quick reference.
-
-2. **Analyze Notebook Content**:
-   - Carefully review each entry in your notebook before providing a final answer.
-   - Consider complementary information from different notes.
-
-3. **Assess Availability of Information**:
-   - Determine whether the notebook contains **explicit and sufficient information** to answer the question.
-   - **Do not infer or assume information** not explicitly present in the notebook.
-   - **If the notebook contains sufficient information**, proceed to formulate the final answer using only the information provided.
-   - **If the notebook does NOT contain enough information**, clearly state that the answer to the question is not available in the company knowledge.
-   - **Do not use any external information, prior knowledge, or make assumptions beyond what is in the notebook.**
-
-4. **Citations with Relevance Scores**:
-   - For each line in your notebook, consider the **chunkId** at the beginning of the line.
-   - **ChunkIds are valid UUIDs** (e.g., '123e4567-e89b-12d3-a456-426614174000').
-   - **Use only the chunkIds provided in the notebook**. **Do not invent or make up chunkIds**.
-   - **Do not use line numbers or indices as chunkIds**.
-   - Assign a **percentage relevance score** to indicate how much each line influenced your final answer.
-   - This relevance score reflects the parts of your thought process used to generate the answer and will be used for citations.
-   - **If the notebook is empty or lacks relevant information, the citations section should be empty.**
-
-5. **Generate Follow-up Questions**:
-   - **If sufficient information is available**, provide a list of **5 follow-up or refinement questions** based on the final answer.
-   - **If the answer is not available**, **do not generate any follow-up questions**.
-
-6. **Provide a Comprehensive Final Answer**:
-   - **When sufficient information is available**, create a thorough, detailed, and well-structured response that goes beyond minimal explanations.
-   - **Expand on concepts thoroughly**: Don't just state facts - explain them, provide context, and help users understand the complete picture.
-   - **Use structured formatting**: Organize content with headers, subheadings, bullet points, and numbered lists to make complex information digestible.
-   - **Be educational and informative**: Treat each answer as an opportunity to teach and provide comprehensive understanding of the topic.
-   - **If the answer is not available**, clearly inform the user that the information is not present in the company knowledge.
-   - **Format Requirements for Comprehensive Answers**:
-     - Use proper markdown formatting with headers (##, ###) to organize different sections
-     - Include bullet points or numbered lists when presenting multiple items or steps
-     - Expand on concepts with detailed explanations rather than brief summaries
-     - Use subheadings to break down complex topics into digestible sections
-     - Provide context and background information when relevant to help users understand the full picture
-     - Include examples or specific details from the notebook when available
-     - Ensure the answer flows logically from one section to another
-     - Make the response comprehensive, detailed, and educational rather than minimalistic
-   - **Do not include any technical terms** such as "nodes," "text chunks," or "atomic facts" in your final answer or title.
-   - Avoid using technical jargon and ensure the response is user-friendly while being comprehensive.
-
----
-
-### **Important Notes:**
-
-- **Use Only Notebook Information**:
-  - Do not use any external sources, prior knowledge, or make up information not present in the notebook.
-  - Do not provide definitions, explanations, or details that are not explicitly stated in the notebook.
-
-- **No Paraphrasing Beyond Notebook Content**:
-  - Do not restate or rephrase the notebook content as the final answer unless it directly and explicitly answers the question.
-
-- **Do Not Infer or Assume**:
-  - Avoid making inferences or assumptions based on partial information.
-  - If the notebook does not explicitly provide the answer, acknowledge that the information is not available.
-
-- **Do Not guess the presume to know the acronyms**:
-  - If your notebook contains the definition of an acronym, you can use it, but if the precise definition of the acronym does NOT exist in the notebook, you must not use it.
-  - NEVER GUESS an ACRONYM. If you don't have a clear definition in the notebook, use only the acronym and don't try to explain it.
-  - **NEVER** write your own definitions or explanations for acronyms. An acronym is a word on its own, and you don't have to explain it.
-
-- **ChunkIds Must Match Exactly**:
-  - Use only the actual chunkIds provided in the notebook entries.
-  - **ChunkIds are valid UUIDs**. Do not use line numbers, indices, or any other placeholders.
-  - **Do not invent or make up chunkIds**.
-
-- **Empty or Insufficient Notebook Handling**:
-  - If the notebook is empty or lacks sufficient information, acknowledge this in your analysis and final answer.
-  - **Do not provide a final answer based on assumptions or external knowledge**.
-  - **Do not generate any follow-up questions if the answer is not available**.
-
-- **Provide Clear and User-Friendly Responses**:
-  - Communicate clearly without technical jargon.
-  - Do not include any technical terms such as "nodes," "text chunks," or "atomic facts" in your final answer or title.
-
----
-
-### **Expected Output Format:**
-
-Your output should include the following fields in the order specified:
-
-- **Title**: A short title providing the user with a quick reference to the answer.
-
-- **Analyse**:
-  - An analysis of the notebook content, considering complementary information and resolving inconsistencies.
-  - State whether the notebook contains sufficient information to answer the question.
-  - If not, acknowledge that the information is not available.
-
-- **Citations**:
-  - A list of citations for the information you used to generate the final answer.
-  - Each citation includes:
-    - **chunkId**: The ID of the line in your notebook.
-    - **relevance**: The relevance of the information in that line (as a percentage).
-  - **If the notebook is empty or lacks relevant information, the citations section should be empty**.
-
-- **Questions**:
-  - **If sufficient information is available**, provide a list of **5 follow-up or refinement questions** based on the final answer.
-  - **If the answer is not available**, **do not generate any follow-up questions**.
-
-- **Final Answer**:
-  - **If sufficient information is available**, provide a comprehensive, detailed, and well-structured answer, strictly using only the information from the notebook.
-  - The answer should be thorough and educational, expanding on concepts with proper explanations.
-  - Use markdown formatting with appropriate headers, subheadings, lists, and sections to organize the content clearly.
-  - **If insufficient information is available**, state that the answer is not available in the company knowledge.
-
----
-
-### **Example When Information Is Available:**
-
-**User:**
-
-Question: What is project management?
-
-Notebook of different exploration paths:
-
-- 123e4567-e89b-12d3-a456-426614174000: Project management is the application of processes, methods, skills, knowledge and experience to achieve specific project objectives.
-- 987f6543-e21a-34c5-b678-539725841901: Project management involves planning, organizing, securing, managing, leading, and controlling resources to achieve specific goals.
-- 456a1234-f56b-78c9-d012-345678901234: The primary challenge of project management is to achieve all project goals within the given constraints like time, budget, and scope.
-
-**Assistant:**
-
-**Title:**
-
-Understanding Project Management: Processes, Goals, and Constraints
-
-**Analyse:**
-
-The notebook contains comprehensive information about project management, covering its definition, key activities, and primary challenges. The information is consistent across different sources and provides a complete foundation for explaining what project management entails.
-
-**Citations:**
-
-- chunkId: "123e4567-e89b-12d3-a456-426614174000", relevance: 95
-- chunkId: "987f6543-e21a-34c5-b678-539725841901", relevance: 90
-- chunkId: "456a1234-f56b-78c9-d012-345678901234", relevance: 85
-
-**Questions:**
-
-1. What specific methodologies are commonly used in project management?
-2. How do project managers handle scope creep and changing requirements?
-3. What tools and software are most effective for project planning and tracking?
-4. How does project management differ across various industries?
-5. What skills are essential for becoming an effective project manager?
-
-**Final Answer:**
-
-## What is Project Management?
-
-Project management is a comprehensive discipline that involves **the application of processes, methods, skills, knowledge, and experience to achieve specific project objectives**. It represents a structured approach to turning ideas and goals into tangible results within defined parameters.
-
-### Core Components of Project Management
-
-Project management encompasses several critical activities that work together to ensure project success:
-
-- **Planning**: Establishing clear objectives, timelines, and resource requirements
-- **Organizing**: Structuring teams, workflows, and project elements efficiently
-- **Securing**: Obtaining necessary resources, approvals, and stakeholder buy-in
-- **Managing**: Overseeing day-to-day operations and progress monitoring
-- **Leading**: Guiding teams and stakeholders toward common goals
-- **Controlling**: Monitoring performance and making necessary adjustments
-
-### The Primary Challenge
-
-The fundamental challenge of project management lies in **achieving all project goals within the given constraints**. These constraints typically include:
-
-- **Time**: Meeting established deadlines and milestones
-- **Budget**: Staying within allocated financial resources
-- **Scope**: Delivering all required features and functionality without exceeding boundaries
-
-### Why Project Management Matters
-
-Project management serves as the bridge between conceptual ideas and practical implementation. By applying systematic approaches and proven methodologies, project managers help organizations transform vision into reality while minimizing risks and maximizing efficiency.
-
-The discipline ensures that resources are used effectively, stakeholders remain aligned, and deliverables meet quality standards within the established timeframe and budget constraints.
-
----
-
-### **Example When Information Is Not Available:**
-
-**User:**
-
-Question: What is Ontology?
-
-Notebook of different exploration paths:
-
-- *(Notebook is empty or does not contain relevant information.)*
-
-**Assistant:**
-
-**Title:**
-
-Information on Ontology
-
-**Analyse:**
-
-- After reviewing the notebook, there is no information available regarding the definition or explanation of ontology.
-- The notebook does not contain sufficient information to answer the question.
-
-**Citations:**
-
-*(No citations since the notebook is empty or lacks relevant information.)*
-
-**Questions:**
-
-*(No questions since the answer is not available.)*
-
-**Final Answer:**
-
-The answer to your question is not available in the company knowledge. There is insufficient information to explain what ontology is based on the provided data.
-
----
-
-### **Please Proceed by Following These Instructions Carefully:**
-
-- **Use Only Information Provided in the Notebook**:
-  - Do not incorporate any external knowledge or make assumptions.
-  - Do not provide definitions or explanations that are not explicitly in the notebook.
-
-- **Do Not Restate Notebook Content as Answer**:
-  - Unless the notebook explicitly answers the question, do not restate the notebook content as the final answer.
-
-- **ChunkIds are Valid UUIDs**:
-  - Use only the chunkIds provided in the notebook, which are valid UUIDs (e.g., '123e4567-e89b-12d3-a456-426614174000').
-  - **Do not invent or make up chunkIds**.
-  - **Do not use line numbers or indices as chunkIds**.
-
-- **Handle Empty or Insufficient Notebooks Appropriately**:
-  - If the notebook is empty or lacks sufficient information, acknowledge this in your analysis and final answer.
-  - **Do not generate any follow-up questions if the answer is not available**.
-
-- **Provide Clear and User-Friendly Responses**:
-  - Communicate clearly without technical jargon.
-
----
-
-By emphasizing that ChunkIds are valid UUIDs and that you should not invent or make up any chunkIds, as well as specifying that no follow-up questions should be generated if the answer is not available, this updated prompt should help prevent the LLM from including information from outside the notebook or making up chunkIds. It also clarifies how to handle situations where the notebook does not contain sufficient information to answer the question.
+You are the synthesizer of a unified ERP assistant. You are given a user
+question and the results of up to three retrieval branches that ran in
+parallel before you. Your job is to write a clear, useful answer using
+ONLY the data those branches returned.
+
+## What you receive
+
+Each turn arrives with these inputs:
+
+- \`question\` — the user's refined question.
+- \`graphSection\` — the graph branch's own prose reply about the records it
+  loaded, followed by an "--- entities for citation ---" block listing each
+  cited entity as \`[ref:N] type — reason\` plus an optional JSON block of
+  field values. Treat the prose at the top of \`graphSection\` as the
+  authoritative graph result; weave it into the unified answer rather than
+  restating the entity list line-by-line. The \`[ref:N]\` handles are opaque
+  reference tokens — use them only inside the \`references\` array, never
+  inside \`finalAnswer\` or \`title\`.
+- \`notebookSection\` — chunks the contextualiser branch retrieved from the
+  document store, each prefixed with its chunkId followed by a snippet of
+  text.
+- \`driftSection\` — community-level summaries (when the drift branch ran).
+- \`scopeSection\` — optional scope hint when the conversation is bound to a
+  single content.
+- \`branchesUsed\` — list of branches that produced data this turn.
+
+A section is the empty string \`""\` when its branch did not run. When all
+data sections are empty, you have no information for this turn — say so
+plainly without referencing "company knowledge", "notebook", or other
+system internals.
+
+## How to write the answer
+
+1. **Identify the user's intent.** Are they asking for a list, a single
+   fact, a procedure, a status, or a comparison? Match the answer's shape
+   to the question.
+
+2. **Use the graph branch's prose as authoritative graph data.** The
+   prose at the top of \`graphSection\` was written by the same component
+   that loaded the records; it already contains the field values, names,
+   and statuses. Weave it into \`finalAnswer\`. You may reorganise it,
+   merge it with material from \`notebookSection\` or \`driftSection\`, or
+   tighten the wording — but do not invent values that are not in the
+   prose, the entity field blocks, or the chunks.
+
+3. **Quote chunk content faithfully.** When you draw from
+   \`notebookSection\`, quote or paraphrase the snippet rather than
+   substituting your own restatement.
+
+4. **Cite the chunks that grounded a document answer.** When you quote or
+   paraphrase from \`notebookSection\`, add the chunkId to \`citations\` with
+   a relevance score 0–100. Use only chunkIds that actually appear in
+   \`notebookSection\`. If \`notebookSection\` is empty, \`citations\` MUST be
+   \`[]\`.
+
+5. **Cite the entities that grounded a graph answer.** Every entity whose
+   information the answer relies on goes into \`references\` as
+   \`{ ref, relevance, reason }\`, with the \`ref\` handle copied verbatim
+   from the "entities for citation" block (e.g. \`"ref:0"\`). Never invent
+   a handle. Never put a chunk into \`references\`; never put an entity
+   into \`citations\`. If \`graphSection\` is empty, \`references\` MUST be
+   \`[]\`.
+
+6. **No handles, no UUIDs in user-facing text.** \`title\` and
+   \`finalAnswer\` must not contain the word "ref", the bracketed handle,
+   or any UUID. The handles are translated back to real (type, id) pairs
+   after you return.
+
+7. **Suggested questions are optional.** If the answer is solid and
+   obvious next-step questions exist, propose 3–5; otherwise return \`[]\`.
+   Do not return suggestions when you had no data.
+
+8. **No-data case.** If every data section is empty (or together they do
+   not cover what the user asked), say so directly. Do not say "answer
+   is not available in the company knowledge" — that is a bad system
+   phrase. Return \`citations: []\` and \`references: []\` in this case.
+
+## Output schema
+
+Return strictly:
+
+- \`title\` — short headline for the UI (under ~70 chars). No handles, no UUIDs.
+- \`analyse\` — one to three sentences describing how you derived the answer
+  (which branches you used, which records you compared). Internal-facing.
+  No handles.
+- \`finalAnswer\` — the user-facing markdown answer. Use headings sparingly,
+  bullet lists where they help, and field values from the graph branch's
+  prose and entity field blocks. No handles, no UUIDs.
+- \`citations\` — array of \`{ chunkId, relevance }\` for chunks you used.
+- \`references\` — array of \`{ ref, relevance, reason }\` for entities you used.
+- \`questions\` — array of follow-up question strings.
 `;
 const outputSchema = zod_1.z.object({
     title: zod_1.z.string().describe(`You should generate a short title to provide the user a quick reference`),
@@ -277,6 +121,15 @@ const outputSchema = zod_1.z.object({
             .describe(`The relevance of the information in the line of your notebook in percentage between 0 and 100. This defines if the information is relevant to the question or not and if it will be used as a citation.`),
     }))
         .describe(`You should provide citations to the information you used to generate the final answer. Consider ALL the ChunkIds in your notebook. Each citation should have a relevance score. Each ChunkId should be unique. Each ChunkId should have a relevance score.`),
+    references: zod_1.z
+        .array(zod_1.z.object({
+        ref: zod_1.z
+            .string()
+            .describe('A `[ref:N]` handle copied verbatim from the "entities for citation" block of `graphSection`'),
+        relevance: zod_1.z.number().describe("Relevance of this entity to the final answer (0-100)"),
+        reason: zod_1.z.string().describe("A short justification for why the entity grounds the answer"),
+    }))
+        .describe(`The graph entities the answer is grounded on. Use ONLY \`ref\` handles that appear in the "entities for citation" block of \`graphSection\`, copied verbatim (e.g. "ref:0"). Never invent ref handles. If the graph branch did not run or no entities were used, return an empty array.`),
     questions: zod_1.z
         .array(zod_1.z.string())
         .describe(`A list of **5 follow-up or refinement questions** based on the final answer.`),
@@ -294,16 +147,14 @@ Format Requirements:
       `),
 });
 const inputSchema = zod_1.z.object({
-    question: zod_1.z.string().describe("The question asked by the user"),
-    annotations: zod_1.z.string().describe("A set of annotations to provide additional context"),
-    notebook: zod_1.z
-        .array(zod_1.z.object({
-        chunkId: zod_1.z.string().describe("The UUID of the chunk"),
-        content: zod_1.z
-            .string()
-            .describe("The note you took about the content of the text chunk in relation to the user question."),
-    }))
-        .describe("A set of notes identified for each chunk of text that could be used as sources"),
+    question: zod_1.z.string().describe("The user's refined question"),
+    notebookSection: zod_1.z
+        .string()
+        .describe("Notebook from the contextualiser branch (chunkId-prefixed lines), or empty if that branch did not run"),
+    graphSection: zod_1.z.string().describe("Graph entities discovered for the question, or empty if that branch did not run"),
+    driftSection: zod_1.z.string().describe("Community-level summaries from drift, or empty if that branch did not run"),
+    scopeSection: zod_1.z.string().describe("Optional content-scope hint, or empty"),
+    branchesUsed: zod_1.z.array(zod_1.z.string()).describe("Names of branches whose data is included"),
 });
 let ResponderAnswerNodeService = ResponderAnswerNodeService_1 = class ResponderAnswerNodeService {
     constructor(llmService, configService) {
@@ -314,203 +165,177 @@ let ResponderAnswerNodeService = ResponderAnswerNodeService_1 = class ResponderA
         this.systemPrompt = prompts?.responder ?? exports.defaultAnswerPrompt;
     }
     async execute(params) {
-        const hasDriftContext = params.state.useDrift && params.state.driftContext;
-        const hasContextualiserContext = params.state.context;
-        // Hybrid mode: both DRIFT and Contextualiser available
-        if (hasDriftContext && hasContextualiserContext) {
-            return this.executeHybridMode(params);
-        }
-        // DRIFT-only mode (fallback, shouldn't happen with current flow)
-        if (hasDriftContext) {
-            return this.executeDriftMode(params);
-        }
-        // Contextualiser-only mode (default)
-        return this.executeContextualiserMode(params);
-    }
-    /**
-     * Execute answer generation using Contextualiser data (traditional mode)
-     */
-    async executeContextualiserMode(params) {
-        const inputParams = {
-            question: params.state.context.question,
-            annotations: params.state.context.annotations,
-            notebook: params.state.context.notebook,
+        const state = params.state;
+        const branchPlan = state.branchPlan ?? {
+            runGraph: false,
+            runContextualiser: false,
+            runDrift: false,
+            reasoning: "",
         };
-        const llmResponse = await this.llmService.call({
-            inputSchema: inputSchema,
-            inputParams: inputParams,
-            outputSchema: outputSchema,
-            systemPrompts: [this.systemPrompt],
-            temperature: 0.1,
-        });
-        const sources = llmResponse.citations.map((citation) => ({
-            chunkId: citation.chunkId ?? "",
-            relevance: citation.relevance ?? 0,
-            reason: "",
+        const branchesUsed = [];
+        if (branchPlan.runGraph)
+            branchesUsed.push("graph");
+        if (branchPlan.runContextualiser)
+            branchesUsed.push("contextualiser");
+        if (branchPlan.runDrift)
+            branchesUsed.push("drift");
+        // Build a ref-handle map so the synthesizer never sees raw UUIDs.
+        const refMap = (state.graphContext?.entities ?? []).map((e, i) => ({
+            ref: `ref:${i}`,
+            type: e.type,
+            id: e.id,
+            reason: e.reason,
+            fields: e.fields,
         }));
-        const filteredSources = [];
-        for (const source of sources) {
-            const existingSource = filteredSources.find((s) => s.chunkId === source.chunkId);
-            const existingNote = params.state.context.notebook.find((n) => n.chunkId === source.chunkId);
-            if (existingNote)
-                source.reason = existingNote.reason;
-            if (!existingSource) {
-                filteredSources.push(source);
-                continue;
-            }
-            if (source.relevance > existingSource.relevance) {
-                existingSource.relevance = source.relevance;
-            }
-        }
-        params.state.sources = filteredSources;
-        params.state.ontologies = params.state.context.ontology;
-        params.state.tokens = llmResponse.tokenUsage;
-        params.state.finalAnswer = {
-            title: llmResponse.title,
-            answer: llmResponse.finalAnswer,
-            analysis: llmResponse.analyse,
-            questions: llmResponse.questions,
-            hasAnswer: true,
-        };
-        return params.state;
-    }
-    /**
-     * Execute answer generation using both DRIFT (global) and Contextualiser (local) data
-     * Combines community-level insights with chunk-level citations
-     */
-    async executeHybridMode(params) {
-        const driftContext = params.state.driftContext;
-        const contextualiserContext = params.state.context;
-        // Build enhanced context that includes DRIFT global insights
-        const globalContext = this.buildGlobalContextSection(driftContext);
-        // Create enhanced input with both global and local context
-        const inputParams = {
-            question: contextualiserContext.question,
-            annotations: `${contextualiserContext.annotations}\n\n--- GLOBAL CONTEXT FROM KNOWLEDGE COMMUNITIES ---\n${globalContext}`,
-            notebook: contextualiserContext.notebook,
-        };
+        const notebookSection = branchPlan.runContextualiser && state.context ? this.buildNotebookSection(state.context) : "";
+        const graphAnswer = state.graphContext?.answer ?? "";
+        const graphSection = branchPlan.runGraph && state.graphContext ? this.buildGraphSection(graphAnswer, refMap) : "";
+        const driftSection = branchPlan.runDrift && state.driftContext ? this.buildDriftSection(state.driftContext) : "";
+        const scopeSection = state.contentId && state.contentType
+            ? `\n\n--- CONVERSATION SCOPE ---\nThe conversation is scoped to ${state.contentType}:${state.contentId}.`
+            : "";
+        this.logger.log(`answer node input: branchesUsed=${JSON.stringify(branchesUsed)} ` +
+            `graphEntities=${state.graphContext?.entities?.length ?? 0} ` +
+            `graphAnswerChars=${graphAnswer.length} ` +
+            `notebookChars=${notebookSection.length} ` +
+            `graphChars=${graphSection.length} ` +
+            `driftChars=${driftSection.length} ` +
+            `scopeChars=${scopeSection.length}`);
+        if (graphSection.length)
+            this.logger.debug(`answer node graphSection:\n${graphSection}`);
         const llmResponse = await this.llmService.call({
-            inputSchema: inputSchema,
-            inputParams: inputParams,
-            outputSchema: outputSchema,
+            inputSchema,
+            inputParams: {
+                question: state.question ?? "",
+                notebookSection,
+                graphSection,
+                driftSection,
+                scopeSection,
+                branchesUsed,
+            },
+            outputSchema,
             systemPrompts: [this.systemPrompt],
             temperature: 0.1,
+            metadata: {
+                nodeName: "answer",
+                agentName: "responder",
+                userQuestion: state.question,
+            },
         });
-        // Process citations from contextualiser notebook
-        const sources = llmResponse.citations.map((citation) => ({
-            chunkId: citation.chunkId ?? "",
-            relevance: citation.relevance ?? 0,
+        // Sources — chunks from the contextualiser branch
+        const sources = (llmResponse.citations ?? []).map((c) => ({
+            chunkId: c.chunkId ?? "",
+            relevance: c.relevance ?? 0,
             reason: "",
         }));
-        const filteredSources = [];
-        for (const source of sources) {
-            const existingSource = filteredSources.find((s) => s.chunkId === source.chunkId);
-            const existingNote = contextualiserContext.notebook.find((n) => n.chunkId === source.chunkId);
-            if (existingNote)
-                source.reason = existingNote.reason;
-            if (!existingSource) {
-                filteredSources.push(source);
-                continue;
-            }
-            if (source.relevance > existingSource.relevance) {
-                existingSource.relevance = source.relevance;
+        if (state.context) {
+            for (const s of sources) {
+                const note = state.context.notebook?.find((n) => n.chunkId === s.chunkId);
+                if (note)
+                    s.reason = note.reason;
             }
         }
-        params.state.sources = filteredSources;
-        params.state.ontologies = contextualiserContext.ontology;
-        // Combine token usage from both DRIFT and this call
-        params.state.tokens = {
-            input: (params.state.tokens?.input || 0) + (llmResponse.tokenUsage?.input || 0),
-            output: (params.state.tokens?.output || 0) + (llmResponse.tokenUsage?.output || 0),
+        const filteredSources = this.deduplicateByChunkId(sources);
+        // References — remap [ref:N] handles back to (type, id). Drop any handle the
+        // synthesizer invented that doesn't appear in the graph node's output.
+        const byRef = new Map(refMap.map((e) => [e.ref, e]));
+        const references = (llmResponse.references ?? [])
+            .map((r) => {
+            const hit = byRef.get(r.ref);
+            if (!hit)
+                return null;
+            return {
+                type: hit.type,
+                id: hit.id,
+                relevance: Math.max(0, Math.min(100, r.relevance ?? 0)),
+                reason: r.reason ?? "",
+            };
+        })
+            .filter((x) => x !== null);
+        const llmRefCount = (llmResponse.references ?? []).length;
+        const droppedRefs = llmRefCount - references.length;
+        this.logger.log(`answer node done: title=${JSON.stringify(llmResponse.title)} ` +
+            `finalAnswerChars=${(llmResponse.finalAnswer ?? "").length} ` +
+            `citations=${filteredSources.length} ` +
+            `references=${references.length}${droppedRefs > 0 ? ` (${droppedRefs} hallucinated dropped)` : ""} ` +
+            `tokens=${JSON.stringify(llmResponse.tokenUsage ?? { input: 0, output: 0 })}`);
+        if (llmRefCount === 0 && (state.graphContext?.entities?.length ?? 0) > 0) {
+            this.logger.warn(`answer node returned 0 references despite ${state.graphContext?.entities?.length} graph entities being available — synthesizer prompt likely needs reinforcement`);
+        }
+        state.sources = filteredSources;
+        state.references = references;
+        state.ontologies = state.context?.ontology ?? [];
+        state.tokens = {
+            input: (state.tokens?.input || 0) + (llmResponse.tokenUsage?.input || 0),
+            output: (state.tokens?.output || 0) + (llmResponse.tokenUsage?.output || 0),
         };
-        params.state.finalAnswer = {
+        state.finalAnswer = {
             title: llmResponse.title,
-            answer: llmResponse.finalAnswer,
             analysis: llmResponse.analyse,
-            questions: llmResponse.questions,
-            hasAnswer: true,
+            answer: llmResponse.finalAnswer,
+            questions: llmResponse.questions ?? [],
+            hasAnswer: branchesUsed.length > 0 || filteredSources.length + references.length > 0,
+        };
+        state.trace = {
+            ...state.trace,
+            answer: { branchesUsed, tokens: llmResponse.tokenUsage ?? { input: 0, output: 0 } },
+            totalTokens: state.tokens,
         };
-        return params.state;
+        return state;
     }
-    /**
-     * Build global context section from DRIFT search results
-     */
-    buildGlobalContextSection(driftContext) {
-        const sections = [];
-        // Add matched communities summary
-        if (driftContext.matchedCommunities?.length > 0) {
-            sections.push("## Relevant Knowledge Communities\n");
-            for (const community of driftContext.matchedCommunities) {
-                sections.push(`### ${community.name || "Community"}`);
-                if (community.summary) {
-                    sections.push(community.summary);
-                }
-                sections.push("");
-            }
-        }
-        // Add DRIFT's initial answer as additional context
-        if (driftContext.initialAnswer) {
-            sections.push("## Initial Analysis\n");
-            sections.push(driftContext.initialAnswer);
-            sections.push("");
+    buildNotebookSection(ctx) {
+        const lines = ["", "--- NOTEBOOK (chunks discovered) ---"];
+        if (ctx.annotations)
+            lines.push(ctx.annotations);
+        for (const n of ctx.notebook ?? [])
+            lines.push(`${n.chunkId}: ${n.content}`);
+        return lines.join("\n");
+    }
+    buildGraphSection(graphAnswer, refMap) {
+        const lines = ["", "--- GRAPH BRANCH ---"];
+        if (graphAnswer.trim().length > 0) {
+            lines.push("", graphAnswer.trim());
         }
-        // Add follow-up investigation findings
-        if (driftContext.followUpAnswers?.length > 0) {
-            sections.push("## Additional Findings\n");
-            for (const followUp of driftContext.followUpAnswers) {
-                sections.push(`**${followUp.question}**`);
-                sections.push(followUp.answer);
-                sections.push("");
+        lines.push("", "--- entities for citation ---");
+        for (const e of refMap) {
+            lines.push(`[${e.ref}] ${e.type} — ${e.reason}`);
+            if (e.fields && Object.keys(e.fields).length > 0) {
+                lines.push(JSON.stringify(e.fields, null, 2));
             }
         }
-        // Add confidence indicator
-        if (driftContext.confidence !== undefined) {
-            const confidenceLevel = driftContext.confidence >= 70 ? "high" : driftContext.confidence >= 40 ? "medium" : "low";
-            sections.push(`_Global search confidence: ${confidenceLevel} (${driftContext.confidence}%)_`);
-        }
-        return sections.join("\n");
-    }
-    /**
-     * Execute answer generation using DRIFT search data
-     * DRIFT already provides a synthesized answer, so we format it for the response
-     */
-    async executeDriftMode(params) {
-        const driftContext = params.state.driftContext;
-        // Extract questions from follow-up answers
-        const questions = driftContext.followUpAnswers?.slice(0, 5).map((f) => f.question) ?? [];
-        // Generate title from matched communities
-        const communityNames = driftContext.matchedCommunities?.map((c) => c.name).filter(Boolean) ?? [];
-        const title = communityNames.length > 0 ? `Answer based on: ${communityNames.slice(0, 3).join(", ")}` : "DRIFT Search Result";
-        // Build analysis from DRIFT information
-        const analysis = this.buildDriftAnalysis(driftContext);
-        // Sources from matched communities (no chunk-level sources in DRIFT)
-        params.state.sources = [];
-        params.state.ontologies = [];
-        params.state.finalAnswer = {
-            title,
-            answer: driftContext.answer,
-            analysis,
-            questions,
-            hasAnswer: driftContext.confidence > 10,
-        };
-        return params.state;
+        return lines.join("\n");
     }
-    /**
-     * Build analysis text from DRIFT context
-     */
-    buildDriftAnalysis(driftContext) {
-        const parts = [];
-        if (driftContext.matchedCommunities?.length > 0) {
-            parts.push(`Searched ${driftContext.matchedCommunities.length} knowledge communities.`);
+    buildDriftSection(d) {
+        const parts = ["", "--- DRIFT (community-level summaries) ---"];
+        if (d.matchedCommunities?.length) {
+            for (const c of d.matchedCommunities) {
+                parts.push(`### ${c.name ?? "Community"}`);
+                if (c.summary)
+                    parts.push(c.summary);
+            }
         }
-        if (driftContext.confidence !== undefined) {
-            const confidenceLevel = driftContext.confidence >= 70 ? "high" : driftContext.confidence >= 40 ? "medium" : "low";
-            parts.push(`Confidence level: ${confidenceLevel} (${driftContext.confidence}%).`);
+        if (d.initialAnswer)
+            parts.push(`Initial analysis: ${d.initialAnswer}`);
+        if (d.followUpAnswers?.length) {
+            for (const f of d.followUpAnswers)
+                parts.push(`${f.question} → ${f.answer}`);
         }
-        if (driftContext.followUpAnswers?.length > 0) {
-            parts.push(`Conducted ${driftContext.followUpAnswers.length} follow-up investigations for depth.`);
+        if (d.confidence !== undefined)
+            parts.push(`Drift confidence: ${d.confidence}%`);
+        return parts.join("\n");
+    }
+    deduplicateByChunkId(sources) {
+        const out = [];
+        for (const s of sources) {
+            const existing = out.find((o) => o.chunkId === s.chunkId);
+            if (!existing) {
+                out.push(s);
+                continue;
+            }
+            if (s.relevance > existing.relevance)
+                existing.relevance = s.relevance;
         }
-        return parts.join(" ");
+        return out;
     }
 };
 exports.ResponderAnswerNodeService = ResponderAnswerNodeService;