@exulu/backend 1.53.1 → 1.55.0

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

@@ -0,0 +1,375 @@
+import { z } from "zod";
+import { createBashTool } from "bash-tool";
+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, parseGlobalItemIds } from "./tools";
+import { STRATEGIES } from "./strategies";
+import { runAgentLoop } from "./agent-loop";
+import { TrajectoryLogger } from "./trajectory";
+import type { AgenticRetrievalOutput, QueryType } from "./types";
+
+// Module-level sampler — shared across all tool instances so the cache is warm
+// across requests within the same process.
+const sampler = new ContextSampler();
+
+async function* executeV3({
+  query,
+  contexts,
+  reranker,
+  model,
+  user,
+  role,
+  customInstructions,
+  logTrajectory,
+  sessionId,
+  preselectedItemIds,
+}: {
+  query: string;
+  contexts: ExuluContext[];
+  reranker?: ExuluReranker;
+  model: LanguageModel;
+  user?: User;
+  role?: string;
+  customInstructions?: string;
+  logTrajectory?: boolean;
+  sessionId?: string;
+  preselectedItemIds?: string[];
+}): AsyncGenerator<AgenticRetrievalOutput> {
+  // ── 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(activeContexts, user, role);
+
+  // ── 3. Classify query (single fast LLM call) ──────────────────────────────
+  console.log("[EXULU] v3 — classifying query");
+  let classification;
+  try {
+    classification = await classifyQuery(query, activeContexts, samples, model);
+  } catch (err) {
+    console.warn("[EXULU] v3 — classification failed, falling back to exploratory:", err);
+    classification = {
+      queryType: "exploratory" as QueryType,
+      language: "eng",
+      suggestedContextIds: [],
+    };
+  }
+  console.log("[EXULU] v3 — classified as:", classification);
+
+  // ── 4. Select strategy ────────────────────────────────────────────────────
+  const strategy = STRATEGIES[classification.queryType];
+
+  // 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 = activeContexts
+    .filter((c) => !suggestedIds.includes(c.id))
+    .map((c) => c.id);
+  const 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: [${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.`
+    : "";
+
+  const contextGuidance = contextBase + preselectedNote;
+
+  // ── 5. Initialize tools ───────────────────────────────────────────────────
+  const bashToolkit = await createBashTool({ files: {} });
+
+  const retrievalTools = createRetrievalTools({
+    contexts: activeContexts,
+    user,
+    role,
+    updateVirtualFiles: (files) => bashToolkit.sandbox.writeFiles(files),
+    preselectedItemsByContext: preselectedByContext,
+  });
+
+  // Build the tool set for this strategy
+  const activeTools: Record<string, Tool> = {};
+  for (const name of strategy.retrieval_tools) {
+    if (name in retrievalTools) {
+      activeTools[name] = retrievalTools[name as keyof typeof retrievalTools];
+    }
+  }
+  if (strategy.include_bash) {
+    Object.assign(activeTools, bashToolkit.tools);
+  }
+
+  // ── 6. Set up trajectory logging ──────────────────────────────────────────
+  const trajectory = new TrajectoryLogger(query, classification, undefined, preselectedItemIds);
+
+  // ── 7. Run agent loop ─────────────────────────────────────────────────────
+  let finalOutput: AgenticRetrievalOutput | undefined;
+  let executionError: Error | undefined;
+
+  try {
+    for await (const output of runAgentLoop({
+      query,
+      strategy,
+      tools: activeTools,
+      model,
+      reranker,
+      contextGuidance,
+      customInstructions,
+      classification,
+      sessionId,
+      onStepComplete: (step) => trajectory.recordStep(step),
+      onTrajectoryStep: (data) => trajectory.recordRichStep(data),
+    })) {
+      finalOutput = output;
+      yield output;
+    }
+  } catch (err) {
+    executionError = err as Error;
+    console.error("[EXULU] v3 — agent loop error:", err);
+    throw err;
+  } finally {
+    if (finalOutput) {
+      const trajectoryFile = await trajectory.finalize(finalOutput, !executionError, executionError, logTrajectory);
+      if (trajectoryFile) {
+        finalOutput.trajectoryFile = trajectoryFile;
+      }
+    }
+  }
+}
+
+/**
+ * Creates the v3 ExuluTool for agentic context retrieval.
+ *
+ * Compared to v2:
+ * - Single LLM call per step (vs two in v2)
+ * - Query classification upfront → strategy-based step budget (1–3 vs hardcoded 2)
+ * - Context example records sampled at init and cached
+ * - Strategy-specific instructions and tool sets
+ */
+export function createAgenticRetrievalToolV3({
+  contexts,
+  instructions: adminInstructions,
+  rerankers,
+  user,
+  role,
+  model,
+  preselectedItemIds,
+}: {
+  contexts: ExuluContext[];
+  rerankers: ExuluReranker[];
+  user?: User;
+  role?: string;
+  model?: LanguageModel;
+  instructions?: string;
+  preselectedItemIds?: string[];
+}): ExuluTool | undefined {
+  const license = checkLicense();
+  if (!license["agentic-retrieval"]) {
+    console.warn("[EXULU] Not licensed for agentic retrieval");
+    return undefined;
+  }
+
+  const contextNames = contexts.map((c) => c.id).join(", ");
+
+  return new ExuluTool({
+    id: "agentic_context_search",
+    name: "Agentic Context Search",
+    description: `Intelligent context search with query classification, strategy-based retrieval, and virtual filesystem filtering. Searches: ${contextNames}`,
+    category: "contexts",
+    needsApproval: false,
+    type: "context",
+    config: [
+      {
+        name: "instructions",
+        description: "Custom instructions for the retrieval agent",
+        type: "string",
+        default: "",
+      },
+      {
+        name: "reranker",
+        description: "Reranker to use for result ranking",
+        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",
+        type: "string",
+        default: "",
+      },
+      {
+        name: "search_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 search phase",
+        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: "log_trajectories",
+        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,
+        description: `Enable search in "${ctx.name}". ${ctx.description}`,
+        type: "boolean" as const,
+        default: true,
+      })),
+    ],
+    inputSchema: z.object({
+      query: z.string().describe("The question or query to answer"),
+      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,
+      userInstructions,
+      confirmedContextIds,
+      toolVariablesConfig,
+      sessionID,
+    }: {
+      query: 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({});
+        if (!reasoningModel) {
+          throw new Error("Reasoning model not found");
+        }
+      }
+
+      if (toolVariablesConfig?.search_model) {
+        searchModel = app.provider(toolVariablesConfig.search_model);
+        if (!searchModel) {
+          throw new Error("Search model not found");
+        }
+      } */
+
+      if (!model) {
+        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["log_trajectories"] === true ||
+          toolVariablesConfig["log_trajectories"] === "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,
+        );
+        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:", preselectedItemIds);
+
+      if (managedContextEnabled && !preselectedItemIds?.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 && !preselectedItemIds?.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}` : "",
+      ]
+        .filter(Boolean)
+        .join("\n");
+
+      for await (const output of executeV3({
+        query,
+        contexts: activeContexts,
+        reranker: configuredReranker,
+        model,
+        user,
+        role,
+        customInstructions: combinedInstructions || undefined,
+        logTrajectory,
+        sessionId: sessionID,
+        preselectedItemIds,
+      })) {
+        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

@@ -0,0 +1,171 @@
+import type { QueryType } from "./types";
+
+export interface StrategyConfig {
+  queryType: QueryType;
+  /** How many agent loop iterations are allowed */
+  stepBudget: number;
+  /** Which tool names from createRetrievalTools() are exposed */
+  retrieval_tools: string[];
+  /** Whether bash tools should be included */
+  include_bash: boolean;
+  instructions: string;
+}
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Per-strategy instructions
+// These are intentionally in separate exported strings so they can be tuned
+// without touching the rest of the code.
+// ──────────────────────────────────────────────────────────────────────────────
+
+export const BASE_INSTRUCTIONS = `
+You are an intelligent retrieval assistant. Your only job is to retrieve relevant information from
+the available knowledge bases and return it. You do NOT answer the user's question yourself —
+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 — 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.
+3. If your first search returned related but not specific enough content, run a follow-up search
+   with more targeted terms or an alternative phrasing of the key concept.
+
+Never give up after a single search — always try at least one follow-up before finishing.
+
+When retrieval is complete (sufficient content found OR all reasonable strategies exhausted),
+you MUST call the finish_retrieval tool — do NOT write a text conclusion.
+`.trim();
+
+export const AGGREGATE_INSTRUCTIONS = `
+${BASE_INSTRUCTIONS}
+
+STRATEGY: This is a COUNTING or AGGREGATION query.
+- 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
+- Return immediately after counting — one step is sufficient
+- If the count needs a content filter, use content_query parameter
+`.trim();
+
+export const LIST_INSTRUCTIONS = `
+${BASE_INSTRUCTIONS}
+
+STRATEGY: This is a LISTING query — the user wants a list of matching items/documents.
+
+Decision tree:
+- "List documents BY NAME/TITLE" → search_items_by_name
+- "List documents ABOUT a topic/subject" → search_content with includeContent: false
+
+Always prefer search_content with includeContent: false for content-based listing:
+- This searches actual document content and returns matching document names
+- It does NOT load chunk text, keeping token use minimal
+- Dynamic page-content tools will be created if the user needs to drill into specific documents
+
+When to use search_items_by_name:
+- Query explicitly mentions document titles or filename patterns
+- User asks for documents whose NAME contains a keyword
+
+Never set includeContent: true for a listing query unless explicitly asked for the actual text.
+`.trim();
+
+export const TARGETED_INSTRUCTIONS = `
+${BASE_INSTRUCTIONS}
+
+STRATEGY: This is a TARGETED query — the user wants specific information from a document.
+
+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 — 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}
+  to load adjacent sections. The specific answer is often in a nearby chunk, not the top result.
+- If the topic was found but the exact detail is missing, search again with more specific terms
+  (e.g., add a key technical term, parameter name, or section keyword to the query).
+- Try alternative phrasings if the first query doesn't surface the right answer.
+
+Product-specific filtering:
+- 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.
+`.trim();
+
+export const EXPLORATORY_INSTRUCTIONS = `
+${BASE_INSTRUCTIONS}
+
+STRATEGY: This is an EXPLORATORY query — general question requiring broad search.
+
+Recommended approach:
+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 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.
+`.trim();
+
+// ──────────────────────────────────────────────────────────────────────────────
+// Strategy map
+// ──────────────────────────────────────────────────────────────────────────────
+
+export const STRATEGIES: Record<QueryType, StrategyConfig> = {
+  aggregate: {
+    queryType: "aggregate",
+    stepBudget: 1,
+    retrieval_tools: ["count_items_or_chunks"],
+    include_bash: false,
+    instructions: AGGREGATE_INSTRUCTIONS,
+  },
+  list: {
+    queryType: "list",
+    stepBudget: 3,
+    retrieval_tools: ["count_items_or_chunks", "search_items_by_name", "search_content"],
+    include_bash: false,
+    instructions: LIST_INSTRUCTIONS,
+  },
+  targeted: {
+    queryType: "targeted",
+    stepBudget: 5,
+    retrieval_tools: ["search_items_by_name", "search_content", "save_search_results"],
+    include_bash: true,
+    instructions: TARGETED_INSTRUCTIONS,
+  },
+  exploratory: {
+    queryType: "exploratory",
+    stepBudget: 5,
+    retrieval_tools: [
+      "count_items_or_chunks",
+      "search_items_by_name",
+      "search_content",
+      "save_search_results",
+    ],
+    include_bash: true,
+    instructions: EXPLORATORY_INSTRUCTIONS,
+  },
+};