@exulu/backend 1.53.0 → 1.54.0

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

@@ -0,0 +1,281 @@
+import { z } from "zod";
+import { createBashTool } from "bash-tool";
+import type { LanguageModel } 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 { 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,
+}: {
+  query: string;
+  contexts: ExuluContext[];
+  reranker?: ExuluReranker;
+  model: LanguageModel;
+  user?: User;
+  role?: string;
+  customInstructions?: string;
+}): AsyncGenerator<AgenticRetrievalOutput> {
+  // ── 1. Sample example records from each context (cached) ──────────────────
+  console.log("[EXULU] v3 — sampling contexts");
+  const samples = await sampler.getSamples(contexts, user, role);
+
+  // ── 2. Classify query (single fast LLM call) ──────────────────────────────
+  console.log("[EXULU] v3 — classifying query");
+  let classification;
+  try {
+    classification = await classifyQuery(query, contexts, 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);
+
+  // ── 3. 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 = contexts
+    .filter((c) => !suggestedIds.includes(c.id))
+    .map((c) => c.id);
+  const contextGuidance =
+    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(", ")}].`;
+
+  // ── 4. Initialize tools ───────────────────────────────────────────────────
+  const bashToolkit = await createBashTool({ files: {} });
+
+  const retrievalTools = createRetrievalTools({
+    contexts, // ALL contexts — agent decides which to search based on context guidance
+    user,
+    role,
+    updateVirtualFiles: (files) => bashToolkit.sandbox.writeFiles(files),
+  });
+
+  // Build the tool set for this strategy
+  const activeTools: Record<string, any> = {};
+  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);
+  }
+
+  // ── 5. Set up trajectory logging ──────────────────────────────────────────
+  const trajectory = new TrajectoryLogger(query, classification);
+
+  // ── 6. 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,
+      onStepComplete: (step) => trajectory.recordStep(step),
+    })) {
+      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);
+      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,
+}: {
+  contexts: ExuluContext[];
+  rerankers: ExuluReranker[];
+  user?: User;
+  role?: string;
+  model?: LanguageModel;
+  instructions?: 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: "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: "",
+      },
+      ...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"),
+    }),
+    execute: async function* ({
+      query,
+      userInstructions,
+      toolVariablesConfig,
+    }: {
+      query: string;
+      userInstructions?: string;
+      toolVariablesConfig?: Record<string, any>;
+    }) {
+      
+      /* 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) {
+        throw new Error("Model is required for executing the agentic retrieval tool");
+      }
+      let activeContexts = contexts;
+      let configuredReranker: ExuluReranker | undefined;
+      let configInstructions = "";
+
+      if (toolVariablesConfig) {
+        configInstructions = toolVariablesConfig["instructions"] ?? "";
+
+        activeContexts = contexts.filter(
+          (ctx) =>
+            toolVariablesConfig[ctx.id] === true ||
+            toolVariablesConfig[ctx.id] === "true" ||
+            toolVariablesConfig[ctx.id] === 1,
+        );
+        if (activeContexts.length === 0) activeContexts = contexts;
+
+        const rerankerId = toolVariablesConfig["reranker"];
+        if (rerankerId && rerankerId !== "none") {
+          configuredReranker = rerankers.find((r) => r.id === rerankerId);
+        }
+      }
+
+      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,
+      })) {
+        yield { result: JSON.stringify(output) };
+      }
+    },
+  });
+}

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

@@ -0,0 +1,167 @@
+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 — 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.
+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
+- 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();
+
+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 — 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 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 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
+  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 = `
+${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)
+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
+- 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: 2,
+    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: 4,
+    retrieval_tools: [
+      "count_items_or_chunks",
+      "search_items_by_name",
+      "search_content",
+      "save_search_results",
+    ],
+    include_bash: true,
+    instructions: EXPLORATORY_INSTRUCTIONS,
+  },
+};