@exulu/backend 1.54.0 → 1.56.0

package/ee/agentic-retrieval/v3/index.ts

@@ -1,18 +1,19 @@
 import { z } from "zod";
 import { createBashTool } from "bash-tool";
-import type { LanguageModel } from "ai";
+import type { LanguageModel, Tool } from "ai";
 import type { ExuluContext } from "@SRC/exulu/context";
 import type { ExuluReranker } from "@SRC/exulu/reranker";
 import { ExuluTool } from "@SRC/exulu/tool";
 import type { User } from "@EXULU_TYPES/models/user";
 import { checkLicense } from "@EE/entitlements";
-import { ContextSampler } from "./context-sampler";
 import { classifyQuery } from "./classifier";
-import { createRetrievalTools } from "./tools";
+import { createRetrievalTools, parseGlobalItemIds } from "./tools";
 import { STRATEGIES } from "./strategies";
 import { runAgentLoop } from "./agent-loop";
 import { TrajectoryLogger } from "./trajectory";
 import type { AgenticRetrievalOutput, QueryType } from "./types";
+import type { ExuluItem } from "@SRC/index";
+import { ContextSampler } from "./context-sampler";
 
 // Module-level sampler — shared across all tool instances so the cache is warm
 // across requests within the same process.
@@ -23,27 +24,45 @@ async function* executeV3({
   contexts,
   reranker,
   model,
+  toolVariablesConfig,
   user,
   role,
   customInstructions,
+  logTrajectory,
+  sessionId,
+  preselectedItemIds,
 }: {
   query: string;
   contexts: ExuluContext[];
   reranker?: ExuluReranker;
+  toolVariablesConfig?: Record<string, any>;
   model: LanguageModel;
   user?: User;
   role?: string;
   customInstructions?: string;
+  logTrajectory?: boolean;
+  sessionId?: string;
+  preselectedItemIds?: string[];
 }): AsyncGenerator<AgenticRetrievalOutput> {
-  // ── 1. Sample example records from each context (cached) ──────────────────
+  // ── 1. Parse preselected item IDs (global format: "<context_id>/<item_id>") ─
+  const preselectedByContext = preselectedItemIds?.length
+    ? parseGlobalItemIds(preselectedItemIds)
+    : undefined;
+
+  // When preselection is active, restrict to only contexts that have selected items
+  const activeContexts = preselectedByContext?.size
+    ? contexts.filter((c) => preselectedByContext.has(c.id))
+    : contexts;
+
+  // ── 2. Sample example records from each context (cached) ──────────────────
   console.log("[EXULU] v3 — sampling contexts");
-  const samples = await sampler.getSamples(contexts, user, role);
+  const samples = await sampler.getSamples(activeContexts, user, role);
 
-  // ── 2. Classify query (single fast LLM call) ──────────────────────────────
+  // ── 3. Classify query (single fast LLM call) ──────────────────────────────
   console.log("[EXULU] v3 — classifying query");
   let classification;
   try {
-    classification = await classifyQuery(query, contexts, samples, model);
+    classification = await classifyQuery(query, activeContexts, samples, model);
   } catch (err) {
     console.warn("[EXULU] v3 — classification failed, falling back to exploratory:", err);
     classification = {
@@ -54,32 +73,63 @@ async function* executeV3({
   }
   console.log("[EXULU] v3 — classified as:", classification);
 
-  // ── 3. Select strategy ────────────────────────────────────────────────────
+  // ── 4. Select strategy ────────────────────────────────────────────────────
   const strategy = STRATEGIES[classification.queryType];
-
+  const contextSpecificInstructions = activeContexts.map(ctx => {
+    const instructions = toolVariablesConfig?.[`${ctx.id}_|_instructions`] ?? "";
+    if (instructions) {
+      return `
+      <${ctx.id}>
+      ${instructions}
+      </${ctx.id}>
+    `;
+    } else {
+      return null;
+    }
+  }).filter(Boolean).join("\n");
   // Build context guidance: the classifier is a priority hint, not a hard filter.
   // All contexts remain available so the agent can fall back if suggested ones miss.
   const suggestedIds = classification.suggestedContextIds;
-  const fallbackIds = contexts
+  const fallbackIds = activeContexts
     .filter((c) => !suggestedIds.includes(c.id))
     .map((c) => c.id);
-  const contextGuidance =
+  let contextBase =
     suggestedIds.length > 0
-      ? `Suggested priority contexts: [${suggestedIds.join(", ")}]. Also available: [${fallbackIds.join(", ")}]. Custom instructions may require searching additional or all contexts — follow them.`
-      : `All contexts available: [${contexts.map((c) => c.id).join(", ")}].`;
+      ? `
+      Suggested priority contexts: [${suggestedIds.join(", ")}]. 
+      
+      Also available: [${fallbackIds.join(", ")}]. 
+      
+      Custom instructions may require searching additional or all contexts — follow them.`
+      : `All contexts available: [${activeContexts.map((c) => c.id).join(", ")}].`;
+
+  const preselectedNote = preselectedByContext?.size
+    ? `\nSCOPE CONSTRAINT: Retrieval is scoped to preselected items/contexts. Per context: ${[...preselectedByContext.entries()].map(([ctx, ids]) => ids === null ? `${ctx} (full context)` : `${ctx} (${ids.length} item${ids.length === 1 ? "" : "s"})`).join(", ")}. All tools enforce this scope automatically. For full-context entries you may search freely; for item-restricted entries do NOT use search_items_by_name for discovery — go directly to search_content or save_search_results.`
+    : "";
+
+  if (contextSpecificInstructions?.length) {
+    contextBase += `
+      Context specific instructions:
+      ${contextSpecificInstructions}
+      `;
+  }
+
+  const contextGuidance = contextBase + preselectedNote;
 
-  // ── 4. Initialize tools ───────────────────────────────────────────────────
+  // ── 5. Initialize tools ───────────────────────────────────────────────────
   const bashToolkit = await createBashTool({ files: {} });
 
   const retrievalTools = createRetrievalTools({
-    contexts, // ALL contexts — agent decides which to search based on context guidance
+    contexts: activeContexts,
+    toolVariablesConfig,
     user,
     role,
     updateVirtualFiles: (files) => bashToolkit.sandbox.writeFiles(files),
+    preselectedItemsByContext: preselectedByContext,
   });
 
   // Build the tool set for this strategy
-  const activeTools: Record<string, any> = {};
+  const activeTools: Record<string, Tool> = {};
   for (const name of strategy.retrieval_tools) {
     if (name in retrievalTools) {
       activeTools[name] = retrievalTools[name as keyof typeof retrievalTools];
@@ -89,10 +139,10 @@ async function* executeV3({
     Object.assign(activeTools, bashToolkit.tools);
   }
 
-  // ── 5. Set up trajectory logging ──────────────────────────────────────────
-  const trajectory = new TrajectoryLogger(query, classification);
+  // ── 6. Set up trajectory logging ──────────────────────────────────────────
+  const trajectory = new TrajectoryLogger(query, classification, undefined, preselectedItemIds);
 
-  // ── 6. Run agent loop ─────────────────────────────────────────────────────
+  // ── 7. Run agent loop ─────────────────────────────────────────────────────
   let finalOutput: AgenticRetrievalOutput | undefined;
   let executionError: Error | undefined;
 
@@ -106,7 +156,9 @@ async function* executeV3({
       contextGuidance,
       customInstructions,
       classification,
+      sessionId,
       onStepComplete: (step) => trajectory.recordStep(step),
+      onTrajectoryStep: (data) => trajectory.recordRichStep(data),
     })) {
       finalOutput = output;
       yield output;
@@ -117,7 +169,7 @@ async function* executeV3({
     throw err;
   } finally {
     if (finalOutput) {
-      const trajectoryFile = await trajectory.finalize(finalOutput, !executionError, executionError);
+      const trajectoryFile = await trajectory.finalize(finalOutput, !executionError, executionError, logTrajectory);
       if (trajectoryFile) {
         finalOutput.trajectoryFile = trajectoryFile;
       }
@@ -141,6 +193,8 @@ export function createAgenticRetrievalToolV3({
   user,
   role,
   model,
+  preselected,
+  memoryItems
 }: {
   contexts: ExuluContext[];
   rerankers: ExuluReranker[];
@@ -148,6 +202,8 @@ export function createAgenticRetrievalToolV3({
   role?: string;
   model?: LanguageModel;
   instructions?: string;
+  preselected?: string[];
+  memoryItems?: ExuluItem[];
 }): ExuluTool | undefined {
   const license = checkLicense();
   if (!license["agentic-retrieval"]) {
@@ -177,6 +233,12 @@ export function createAgenticRetrievalToolV3({
         type: "string",
         default: "none",
       },
+      {
+        name: "managed_context",
+        description: "Makes sure the user defines which items from which contexts the agentic retrieval tool will search in",
+        type: "boolean",
+        default: false,
+      },
       {
         name: "reasoning_model",
         description: "By default the agentic retrieval tool uses the model from the agent calling the tool, but you can overwrite this here for the reasoning phase",
@@ -189,35 +251,89 @@ export function createAgenticRetrievalToolV3({
         type: "string",
         default: "",
       },
+      {
+        name: "require_preselected_contexts",
+        description: "Require the user to preselect contexts before executing the tool, meaning the user will be asked to select the contexts they want to search in",
+        type: "boolean",
+        default: false,
+      },
+      {
+        name: "logging",
+        description: "Save a detailed markdown + JSON log of every retrieval execution to disk. Useful for debugging and evaluation.",
+        type: "boolean",
+        default: false,
+      },
       ...contexts.map((ctx) => ({
-        name: ctx.id,
+        name: ctx.id + "_|_enabled",
         description: `Enable search in "${ctx.name}". ${ctx.description}`,
         type: "boolean" as const,
         default: true,
+      }
+      )),
+      ...contexts.map((ctx) => ({
+        name: `${ctx.id}_|_instructions`,
+        description: `Instructions for the retrieval agent about how to search in the ${ctx.name} context`,
+        type: "string" as const,
+        default: "",
+      })),
+      ...contexts.map((ctx) => ({
+        name: `${ctx.id}_|_priority`,
+        description: `Defines in which order the context should be searched in, the higher the number the higher the priority, if contexts have the same priority they are searched in parallel`,
+        type: "number" as const,
+        default: 0,
       })),
+      ...contexts.map((ctx) => ({
+        name: `${ctx.id}_|_max_results`,
+        description: `Defines the maximum number of results to return for the ${ctx.name} context`,
+        type: "number" as const,
+        default: 0,
+      })),
+      ...contexts.map((ctx) => ({
+        name: `${ctx.id}_|_max_steps`,
+        description: `Defines the maximum number of steps the agent is allowed to take when searching the ${ctx.name} context`,
+        type: "number" as const,
+        default: 0,
+      })),
+      ...contexts.map((ctx) => ({
+        name: `${ctx.id}_|_expand_chunks`,
+        description: `Defines if the agent automatically retrieves nearby chunks around the matched chunks, usefull if relevant content might be split up`,
+        type: "number" as const,
+        default: 0,
+      }))
     ],
     inputSchema: z.object({
-      query: z.string().describe("The question or query to answer"),
+      userQuery: z.string().describe("The original unaltered question from the user"),
       userInstructions: z
         .string()
         .optional()
         .describe("Additional instructions from the user to guide retrieval"),
+      confirmedContextIds: z
+        .array(z.string())
+        .optional()
+        .describe(
+          "Knowledge base IDs explicitly confirmed by the user to be used in the retrieval. " +
+          "When presen only searches these contexts. "
+        )
     }),
     execute: async function* ({
-      query,
+      userQuery,
       userInstructions,
+      confirmedContextIds,
       toolVariablesConfig,
+      sessionID,
     }: {
-      query: string;
+      userQuery: string;
       userInstructions?: string;
+      confirmedContextIds?: string[];
       toolVariablesConfig?: Record<string, any>;
+      sessionID?: string;
     }) {
-      
+
       /* ROADMAP:
       const app = exuluApp.get();
       let reasoningModel: LanguageModel | undefined = model;
       let searchModel: LanguageModel | undefined = model;
-
+  
       
        if (toolVariablesConfig?.reasoning_model) {
         reasoningModel = app.provider(toolVariablesConfig.reasoning_model)?.model?.create({});
@@ -225,7 +341,7 @@ export function createAgenticRetrievalToolV3({
           throw new Error("Reasoning model not found");
         }
       }
-
+  
       if (toolVariablesConfig?.search_model) {
         searchModel = app.provider(toolVariablesConfig.search_model);
         if (!searchModel) {
@@ -234,48 +350,108 @@ export function createAgenticRetrievalToolV3({
       } */
 
       if (!model) {
-        throw new Error("Model is required for executing the agentic retrieval tool");
+        yield { result: "Model is required for executing the agentic retrieval tool" };
+        return;
       }
+
       let activeContexts = contexts;
       let configuredReranker: ExuluReranker | undefined;
       let configInstructions = "";
+      let logTrajectory = false;
+      let requiresPreselectedContexts = false;
+      let managedContextEnabled = false;
 
       if (toolVariablesConfig) {
         configInstructions = toolVariablesConfig["instructions"] ?? "";
+        logTrajectory =
+          toolVariablesConfig["logging"] === true ||
+          toolVariablesConfig["logging"] === "true";
+
+        managedContextEnabled = toolVariablesConfig["managed_context"] === true || toolVariablesConfig["managed_context"] === "true";
 
         activeContexts = contexts.filter(
           (ctx) =>
-            toolVariablesConfig[ctx.id] === true ||
-            toolVariablesConfig[ctx.id] === "true" ||
-            toolVariablesConfig[ctx.id] === 1,
+            toolVariablesConfig[ctx.id + "_|_enabled"] === true ||
+            toolVariablesConfig[ctx.id + "_|_enabled"] === "true" ||
+            toolVariablesConfig[ctx.id + "_|_enabled"] === 1,
         );
         if (activeContexts.length === 0) activeContexts = contexts;
 
+        requiresPreselectedContexts = toolVariablesConfig["require_preselected_contexts"] === true || toolVariablesConfig["require_preselected_contexts"] === "true";
+
         const rerankerId = toolVariablesConfig["reranker"];
+
         if (rerankerId && rerankerId !== "none") {
           configuredReranker = rerankers.find((r) => r.id === rerankerId);
         }
       }
 
+      console.log("[EXULU] Managed context enabled:", managedContextEnabled);
+      console.log("[EXULU] Preselected item IDs:", preselected);
+
+      if (managedContextEnabled && !preselected?.length) {
+        console.log("[EXULU] Managed context was enabled for the agentic retrieval tool. This means that the user must preselect items that the agentic retrieval tool will search in, please notify the user to preselect items before executing the tool.");
+        yield { result: "Managed context was enabled for the agentic retrieval tool. This means that the user must preselect items that the agentic retrieval tool will search in, please notify the user to preselect items before executing the tool." };
+        return;
+      }
+
+      if (requiresPreselectedContexts && !confirmedContextIds?.length && !preselected?.length) {
+        console.log("[EXULU] The user must choose between the available contexts before executing the tool. The available contexts are: " + activeContexts.map((c) => c.id).join(", ") + ". If the question_ask tool is available use that to ask the user which contexts they want to search in, otherwise just ask them in plain text.");
+        yield { result: "The user must choose between the available contexts before executing the tool, the available contexts are: " + activeContexts.map((c) => c.id).join(", ") + ". If the question_ask tool is available use that to ask the user which contexts they want to search in, otherwise just ask them in plain text." };
+        return;
+      }
+
+      if (confirmedContextIds?.length) {
+        const confirmed = new Set(confirmedContextIds);
+        const filtered = activeContexts.filter((c) => confirmed.has(c.id));
+        if (filtered.length > 0) activeContexts = filtered;
+      }
+
       const combinedInstructions = [
-        configInstructions ? `Configuration instructions: ${configInstructions}` : "",
-        adminInstructions ? `Admin instructions: ${adminInstructions}` : "",
-        userInstructions ? `User instructions: ${userInstructions}` : "",
+        configInstructions ? `
+        Configuration instructions: 
+        <configuration_instructions>
+        ${configInstructions}
+        </configuration_instructions>
+        ` : "",
+        adminInstructions ? `
+        Admin instructions: 
+        <admin_instructions>
+        ${adminInstructions}
+        </admin_instructions>
+        ` : "",
+        userInstructions ? `
+        User instructions: 
+        <user_instructions>
+        ${userInstructions}
+        </user_instructions>
+        ` : "",
+        memoryItems ? `
+        Relevant memories (these are items that the agent has retrieved from the memory context and are relevant to the query):
+        <relevant_memories>
+        ${memoryItems?.map(item => JSON.stringify(item)).join("\n")}
+        </relevant_memories>
+        ` : "",
       ]
         .filter(Boolean)
         .join("\n");
 
       for await (const output of executeV3({
-        query,
+        query: userQuery,
         contexts: activeContexts,
         reranker: configuredReranker,
+        toolVariablesConfig,
         model,
         user,
         role,
         customInstructions: combinedInstructions || undefined,
+        logTrajectory,
+        sessionId: sessionID,
+        preselectedItemIds: preselected,
       })) {
         yield { result: JSON.stringify(output) };
       }
+      return;
     },
   });
 }

package/ee/agentic-retrieval/v3/session-tools-registry.ts

@@ -0,0 +1,20 @@
+import type { Tool as AITool } from "ai";
+
+// Persists dynamic tools (get_more_content_from_X, get_X_page_N_content) created
+// during an agentic retrieval run, keyed by session ID. This lets the outer chat
+// agent call them directly on follow-up questions without re-running retrieval.
+const registry = new Map<string, Map<string, AITool>>();
+
+export function registerSessionTools(sessionId: string, tools: Record<string, AITool>): void {
+  const existing = registry.get(sessionId) ?? new Map();
+  for (const [name, toolDef] of Object.entries(tools)) {
+    existing.set(name, toolDef);
+  }
+  registry.set(sessionId, existing);
+}
+
+export function getSessionTools(sessionId: string): Record<string, AITool> {
+  const toolMap = registry.get(sessionId);
+  if (!toolMap || toolMap.size === 0) return {};
+  return Object.fromEntries(toolMap.entries());
+}

package/ee/agentic-retrieval/v3/strategies.ts

@@ -25,9 +25,10 @@ another component will do that based on what you retrieve.
 Always respond in the SAME LANGUAGE as the user's query.
 Always write search queries in the SAME LANGUAGE as the user's query — do NOT translate to English.
 
-SEARCH APPROACH — go wide first, then deep:
-1. First step: search broadly across all sources the system instructions indicate — do NOT
-   pre-filter to a single context on step 1.
+SEARCH APPROACH — one knowledge base at a time, then go deep:
+1. search_content and save_search_results accept ONE knowledge base per call. Make a separate
+   call for each knowledge base you need to cover — never skip one. Search all relevant
+   knowledge bases before concluding, even if the first one already returned good results.
 2. After finding a relevant document, use get_more_content_from_{item} dynamic tools to load
    additional pages/sections. The specific answer is often NOT in the first retrieved chunk —
    always explore adjacent content before concluding.
@@ -44,9 +45,8 @@ export const AGGREGATE_INSTRUCTIONS = `
 ${BASE_INSTRUCTIONS}
 
 STRATEGY: This is a COUNTING or AGGREGATION query.
-- Use count_items_or_chunks exclusively
+- Use count_items_or_chunks exclusively — it accepts multiple knowledge bases in one call for efficiency
 - Do NOT use search_content — it loads unnecessary data
-- Search ALL contexts in parallel in a single tool call
 - Return immediately after counting — one step is sufficient
 - If the count needs a content filter, use content_query parameter
 `.trim();
@@ -81,9 +81,23 @@ Search language:
 - Always write search queries in the SAME LANGUAGE as the user's query.
 - Do NOT translate the query to English — the documents are indexed in their original language.
 
-Step 1 — wide hybrid search (includeContent: true, limit 10):
-- Search broadly across all sources per the system instructions — do not limit to 1 context.
-- This gives you the best results from every relevant source at once.
+Step 1 — match the opening move to what the query actually needs:
+
+  Query references a SPECIFIC NAMED DOCUMENT (product manual, titled report, named file):
+  → ALWAYS start with search_items_by_name — searches document name/title directly
+  → Only proceed to load content if the document is found
+
+  Query asks WHETHER a topic EXISTS or WHAT documents cover a topic (no specific title given):
+  → search_content with includeContent: false
+  → Returns matching document names without loading chunk text — efficient and precise
+  → Load content with dynamic get_{item}_page_{n}_content tools only if needed in step 2
+
+  Query asks for CONTENT itself (procedures, parameters, explanations, how-to):
+  → search_content with includeContent: true, limit 20, searchMethod: "hybrid"
+  → Make one call per knowledge base — search each separately before concluding
+
+  Query provides an EXACT TERM (error code, product code, ID, parameter name):
+  → search_content with searchMethod: "keyword"
 
 Step 2+ — depth and follow-up:
 - For any relevant document found with fewer than 5 chunks, use get_more_content_from_{item}
@@ -93,19 +107,9 @@ Step 2+ — depth and follow-up:
 - Try alternative phrasings if the first query doesn't surface the right answer.
 
 Product-specific filtering:
-- When the query mentions a specific product (e.g., "FST-3", "ECO"), you MAY use
-  item_names: ["<product>"] on a follow-up search to narrow results — but only after an initial
+- When the query mentions a specific named entity (product, model, version), you MAY use
+  item_names: ["<entity>"] on a follow-up search to narrow results — but only after an initial
   wide search. Never start with item_names filtering alone.
-
-Two-step approach — use includeContent: false first:
-- Only when you expect many results (>20) and need to identify the right document first.
-- Step 1: search_content with includeContent: false → see which documents/chunks match.
-- Step 2: use dynamic get_{item}_page_{n}_content tools to load specific pages.
-
-Search method selection:
-- hybrid (default): best for most queries
-- keyword: exact product codes, document IDs, error codes
-- semantic: conceptual questions, synonyms, paraphrasing
 `.trim();
 
 export const EXPLORATORY_INSTRUCTIONS = `
@@ -114,13 +118,13 @@ ${BASE_INSTRUCTIONS}
 STRATEGY: This is an EXPLORATORY query — general question requiring broad search.
 
 Recommended approach:
-1. Start with a wide hybrid search across all relevant contexts (includeContent: true, limit: 10)
+1. Search each relevant knowledge base separately with hybrid search (includeContent: true, limit: 20) — one call per knowledge base
 2. If results are insufficient: try alternative search terms or different search method
 3. Use save_search_results + bash grep when you need to scan many results without context bloat
 4. Use dynamic get_more_content_from_{item} tools to read adjacent pages when a relevant item is found
 
 When to declare done:
-- You have retrieved chunks that cover the key aspects of the query
+- You have retrieved chunks that cover the key aspects of the query from all relevant knowledge bases
 - OR you have tried 3+ different search strategies and found nothing relevant
 
 Do NOT use count_items_or_chunks for exploratory queries — the user wants content, not statistics.
@@ -140,7 +144,7 @@ export const STRATEGIES: Record<QueryType, StrategyConfig> = {
   },
   list: {
     queryType: "list",
-    stepBudget: 2,
+    stepBudget: 3,
     retrieval_tools: ["count_items_or_chunks", "search_items_by_name", "search_content"],
     include_bash: false,
     instructions: LIST_INSTRUCTIONS,
@@ -154,7 +158,7 @@ export const STRATEGIES: Record<QueryType, StrategyConfig> = {
   },
   exploratory: {
     queryType: "exploratory",
-    stepBudget: 4,
+    stepBudget: 5,
     retrieval_tools: [
       "count_items_or_chunks",
       "search_items_by_name",