@exulu/backend 3.7.3 → 4.0.0

package/dist/python-setup-DRJ3QX5F.js

@@ -0,0 +1,17 @@
+import "dotenv/config";
+import {
+  getPackageRoot,
+  getPythonSetupInstructions,
+  getPythonVenvPath,
+  isPythonEnvironmentSetup,
+  setupPythonEnvironment,
+  validatePythonEnvironment
+} from "./chunk-QMN6MVHQ.js";
+export {
+  getPackageRoot,
+  getPythonSetupInstructions,
+  getPythonVenvPath,
+  isPythonEnvironmentSetup,
+  setupPythonEnvironment,
+  validatePythonEnvironment
+};

package/ee/LICENSE.md

@@ -5,7 +5,7 @@ Certain peripheral components of Exulu are subject to
 commercial licensing and governed by this Enterprise License.
 For clarity, this license does not cover the core of Exulu
 as defined in the license located at "/LICENSE" (distinct from
-this file at "ee/LICENSE"), which may be used and operated
+this file at "ee/LICENSE.md"), which may be used and operated
 without violating this license or its licensed materials.
 
 Additionally, any functionality within the software that is
@@ -59,4 +59,4 @@ For any third-party components integrated into the Exulu Software, such
 components remain governed by the original license provided by the respective
 component owner.
 
-END OF LICENSE
+END OF LICENSE

package/ee/agentic-retrieval/pipeline/config.test.ts

@@ -4,7 +4,8 @@ describe("parsePipelineConfig", () => {
   it("returns full defaults for an empty/missing config", () => {
     const cfg = parsePipelineConfig(undefined);
     expect(cfg.tuning).toEqual({ topK: 5, fallbackThreshold: 0.95, pinBoost: 0.15,
-      identifierBoost: 0.15, pageWindow: 1, maxQueriesPerContext: 5 });
+      identifierBoost: 0.15, pageWindow: 1, maxQueriesPerContext: 5,
+      engine: "v1", v2: { mergedMemoryCall: true, mergedRoutingCall: true, parallelPins: true } });
     expect(cfg.memory).toEqual({ enabled: true, override: false, filePrioritization: false, queryAugmentation: true });
     expect(cfg.routing.rules).toEqual([]);
     expect(cfg.knowledgeBases).toEqual({});
@@ -94,3 +95,19 @@ describe("project_search option", () => {
     expect(parsePipelineConfig({ project_search: true }).projectSearch).toBe(true);
   });
 });
+
+describe("tuning.engine — the per-agent switch between the v1 flow and the parallel v2 flow", () => {
+  it("defaults to v1 so existing agents keep today's behaviour", () => {
+    expect(parsePipelineConfig({ tuning: '{"topK": 8}' }).tuning.engine).toBe("v1");
+  });
+  it("enables v2 with every sub-feature on, and lets a single feature be switched off for bisecting", () => {
+    const cfg = parsePipelineConfig({ tuning: '{"engine": "v2", "v2": {"parallelPins": false}}' });
+    expect(cfg.tuning.engine).toBe("v2");
+    expect(cfg.tuning.v2).toEqual({ mergedMemoryCall: true, mergedRoutingCall: true, parallelPins: false });
+  });
+  it("falls back to v1 on an unknown engine value", () => {
+    const warn = jest.spyOn(console, "warn").mockImplementation(() => {});
+    expect(parsePipelineConfig({ tuning: '{"engine": "v9"}' }).tuning.engine).toBe("v1");
+    warn.mockRestore();
+  });
+});

package/ee/agentic-retrieval/pipeline/config.ts

@@ -57,6 +57,21 @@ const tuningSchema = z.object({
   identifierBoost: z.number().min(0).max(1).default(0.15),
   pageWindow: z.number().int().min(0).default(1),
   maxQueriesPerContext: z.number().int().positive().default(5),
+  /**
+   * Orchestration engine. "v1" is the sequential flow every agent ran before 2026-09;
+   * "v2" merges the phase-1 LLM hops and runs identifier pins in parallel. Per agent,
+   * so a candidate agent can run v2 while the production agent stays on v1.
+   */
+  engine: z.enum(["v1", "v2"]).default("v1"),
+  /** v2 sub-features; each can be switched off on its own to bisect a regression. */
+  v2: z
+    .object({
+      mergedMemoryCall: z.boolean().default(true),
+      mergedRoutingCall: z.boolean().default(true),
+      parallelPins: z.boolean().default(true),
+    })
+    // zod's .default() returns the value as-is (inner defaults are not applied), so spell it out.
+    .default({ mergedMemoryCall: true, mergedRoutingCall: true, parallelPins: true }),
 });
 
 export type KbProfile = z.infer<typeof kbProfileSchema>;

package/ee/agentic-retrieval/pipeline/index.test.ts

@@ -223,3 +223,76 @@ describe("projectScope execute-level wiring", () => {
     expect(rerankCall.state.pinnedItemIds.has("item1")).toBe(true);
   });
 });
+
+describe("phase timings", () => {
+  it("records how long the retrieval phases took as a step, so latency can be read from the stored tool result", async () => {
+    const run = makeTool({});
+    const out = await drain(run(inputs));
+    const last = JSON.parse(out[out.length - 1].result);
+    const timing = last.steps.find((s: any) => typeof s.text === "string" && s.text.startsWith("Timing:"));
+    expect(timing).toBeDefined();
+    expect(timing.text).toMatch(/memory\+routing \d+ms/);
+    expect(timing.text).toMatch(/search \d+ms/);
+    expect(timing.text).toMatch(/rerank \d+ms/);
+    expect(timing.text).toMatch(/total \d+ms/);
+    expect(last.timings).toEqual(expect.objectContaining({ totalMs: expect.any(Number), searchMs: expect.any(Number) }));
+  });
+});
+
+describe("engine v2 — identifier pins run alongside memory and routing", () => {
+  it("resolves pins on the original question in parallel, and only once when memory leaves the question unchanged", async () => {
+    const { resolveIdentifierPins } = jest.requireMock("./prefilter");
+    resolveIdentifierPins.mockClear();
+    const run = makeTool({ tuning: '{"engine": "v2"}' });
+    await drain(run(inputs));
+    expect(resolveIdentifierPins).toHaveBeenCalledTimes(1);
+    expect(resolveIdentifierPins.mock.calls[0][0].question).toBe("q");
+  });
+
+  it("keeps the parallel pins when memory only added synonyms to the question", async () => {
+    const { resolveIdentifierPins } = jest.requireMock("./prefilter");
+    const { runMemoryPhase } = jest.requireMock("./memory");
+    resolveIdentifierPins.mockClear();
+    runMemoryPhase.mockResolvedValueOnce({
+      memoryChunksForAnswer: [], memoryOverride: { active: false, chunks: [], reason: "" },
+      memoryPinnedItemIdsByContext: new Map(), updatedQuestion: "q plus synonym", updatedKeywords: ["k"],
+      updatedImportantKeyword: "k", steps: [] });
+    const run = makeTool({ tuning: '{"engine": "v2"}' });
+    await drain(run(inputs));
+    expect(resolveIdentifierPins).toHaveBeenCalledTimes(1);
+  });
+
+  it("re-resolves pins on the memory-augmented question when it introduces a new designation (v1 fidelity)", async () => {
+    const { resolveIdentifierPins } = jest.requireMock("./prefilter");
+    const { runMemoryPhase } = jest.requireMock("./memory");
+    resolveIdentifierPins.mockClear();
+    runMemoryPhase.mockResolvedValueOnce({
+      memoryChunksForAnswer: [], memoryOverride: { active: false, chunks: [], reason: "" },
+      memoryPinnedItemIdsByContext: new Map(), updatedQuestion: "q plus FST-2XT", updatedKeywords: ["k"],
+      updatedImportantKeyword: "k", steps: [] });
+    const run = makeTool({ tuning: '{"engine": "v2"}' });
+    await drain(run(inputs));
+    expect(resolveIdentifierPins).toHaveBeenCalledTimes(2);
+    expect(resolveIdentifierPins.mock.calls[1][0].question).toBe("q plus FST-2XT");
+  });
+
+  it("passes the merged-call flags to the memory and routing phases", async () => {
+    const { runMemoryPhase } = jest.requireMock("./memory");
+    const { runRoutingPhase } = jest.requireMock("./routing");
+    runMemoryPhase.mockClear(); runRoutingPhase.mockClear();
+    const run = makeTool({ tuning: '{"engine": "v2", "v2": {"mergedRoutingCall": false}}' });
+    await drain(run(inputs));
+    expect(runMemoryPhase.mock.calls[0][0].mergedCall).toBe(true);
+    expect(runRoutingPhase.mock.calls[0][0].mergedCall).toBe(false);
+  });
+
+  it("keeps v1 sequential pins by default", async () => {
+    const { resolveIdentifierPins } = jest.requireMock("./prefilter");
+    const { runMemoryPhase } = jest.requireMock("./memory");
+    resolveIdentifierPins.mockClear(); runMemoryPhase.mockClear();
+    const run = makeTool({});
+    await drain(run(inputs));
+    expect(resolveIdentifierPins).toHaveBeenCalledTimes(1);
+    expect(runMemoryPhase.mock.calls[0][0].mergedCall).toBeFalsy();
+  });
+});

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

@@ -15,6 +15,8 @@ import { resolveIdentifierPins } from "./prefilter";
 import { searchContexts } from "./search";
 import { rerankResults } from "./rerank";
 import type { AgenticRetrievalOutput, RerankState, ChunkWithScore } from "./types";
+import { withTiming } from "./timing";
+import { needsPinRerun } from "./pin-rerun";
 import type { VectorSearchChunkResult } from "@SRC/graphql/resolvers/vector-search";
 import { parsePreselectedItems } from "./global-ids";
 export { parsePreselectedItems } from "./global-ids";
@@ -238,6 +240,16 @@ export function createAgenticRetrievalTool(opts: {
         usage: [],
         totalTokens: 0,
       };
+      // Phase timings (ms) — surfaced as a step and as `timings` on the result so latency
+      // can be analysed from stored tool results on deployments without tracing.
+      const t0 = Date.now();
+      const timings: Record<string, number> = {};
+      let tPhase = t0;
+      const lap = (name: string) => {
+        const now = Date.now();
+        timings[name] = (timings[name] ?? 0) + (now - tPhase);
+        tPhase = now;
+      };
 
       try {
       // ── Enabled contexts (knowledge_bases.enabled filter + restore-all) ───
@@ -340,8 +352,21 @@ export function createAgenticRetrievalTool(opts: {
         .filter(Boolean)
         .join("\n");
 
-      const [memResult, routResult] = await Promise.all([
-        runMemoryPhase({
+      const engineV2 = cfg.tuning.engine === "v2";
+      const v2 = cfg.tuning.v2;
+      const pinsFor = (question: string) =>
+        resolveIdentifierPins({
+          question,
+          identifierSets: cfg.vocabulary.identifiers,
+          contextsById,
+          kbKindById,
+          model: utilityModel,
+        });
+
+      const [memResult, routResult, parallelPins] = await Promise.all([
+        withTiming(timings, "memoryMs", () => runMemoryPhase({
+          timings,
+          mergedCall: engineV2 && v2.mergedMemoryCall,
           memoryChunks: memoryItems ?? [],
           memoryContext,
           question: userQuery,
@@ -353,8 +378,10 @@ export function createAgenticRetrievalTool(opts: {
           memoryConfig: cfg.memory,
           glossary: cfg.vocabulary.glossary,
           documentContexts,
-        }),
-        runRoutingPhase({
+        })),
+        withTiming(timings, "routingMs", () => runRoutingPhase({
+          timings,
+          mergedCall: engineV2 && v2.mergedRoutingCall,
           question: userQuery,
           enabledContexts,
           documentContexts,
@@ -365,9 +392,15 @@ export function createAgenticRetrievalTool(opts: {
           // detector must never treat these as filename hints.
           knownIdentifiers: cfg.vocabulary.identifiers.flatMap((i) => i.examples),
           model: utilityModel,
-        }),
+        })),
+        // engine v2: identifier pins depend only on the question, so they run alongside
+        // memory and routing instead of after them (re-run below if memory rewrote the question).
+        engineV2 && v2.parallelPins
+          ? withTiming(timings, "pinsParallelMs", () => pinsFor(userQuery))
+          : Promise.resolve(null),
       ]);
 
+      lap("memoryRoutingMs");
       // Merge steps from both phases
       for (const step of [...memResult.steps, ...routResult.steps]) {
         result.steps.push({
@@ -431,14 +464,11 @@ export function createAgenticRetrievalTool(opts: {
 
       // ── Identifier pins (upfront, before Phase 2) ────────────────────────
       const { pinsByContext: identifierPinsByContext, exactPinsByContext, steps: pinSteps } =
-        await resolveIdentifierPins({
-          question: updatedQuestion,
-          identifierSets: cfg.vocabulary.identifiers,
-          contextsById,
-          kbKindById,
-          model: utilityModel,
-        });
+        parallelPins && !needsPinRerun(userQuery, updatedQuestion)
+          ? parallelPins
+          : await pinsFor(updatedQuestion);
 
+      lap("pinsMs");
       for (const step of pinSteps) {
         result.steps.push({
           stepNumber: 1,
@@ -470,6 +500,8 @@ export function createAgenticRetrievalTool(opts: {
           rewrites: cfg.vocabulary.rewrites,
           styleHint: cfg.vocabulary.styleHint,
           maxQueries: cfg.tuning.maxQueriesPerContext,
+          timings,
+          timingPrefix: "search.main",
           skipPrefilter: false,
         }),
         fallbackContextsToSearch.length > 0 && !hasExplicitDocAndPage
@@ -491,11 +523,14 @@ export function createAgenticRetrievalTool(opts: {
               rewrites: cfg.vocabulary.rewrites,
               styleHint: cfg.vocabulary.styleHint,
               maxQueries: cfg.tuning.maxQueriesPerContext,
+              timings,
+              timingPrefix: "search.fallback",
               skipPrefilter: true,
             })
           : Promise.resolve({ chunks: [] }),
       ]);
 
+      lap("searchMs");
       // ── Build rerank state ────────────────────────────────────────────────
       // pinnedItemIds = memory ∪ exact identifier pins ∪ user pins ∪ project pins
       const pinnedItemIds = new Set<string>([
@@ -567,6 +602,7 @@ export function createAgenticRetrievalTool(opts: {
         tokens: 0,
       });
 
+      lap("rerankMs");
       // Accumulate main results (dedup by chunk_id, memory chunks already first)
       addChunks(result, mainRerank.limited_results);
       yield { result: serializeOutput(result) };
@@ -636,6 +672,7 @@ export function createAgenticRetrievalTool(opts: {
         });
         result.reasoning.push({ text: "Fallback results reranked", tools: [] });
         addChunks(result, fallbackRerank.limited_results);
+        lap("fallbackRerankMs");
         yield { result: serializeOutput(result) };
       }
 
@@ -667,10 +704,27 @@ export function createAgenticRetrievalTool(opts: {
         yield { result: serializeOutput(result) };
       }
 
+      timings.totalMs = Date.now() - t0;
+      result.timings = timings;
+      result.steps.push({
+        stepNumber: 1,
+        text:
+          `Timing: memory+routing ${timings.memoryRoutingMs ?? 0}ms (memory ${timings.memoryMs ?? 0}ms, routing ${timings.routingMs ?? 0}ms), pins ${timings.pinsMs ?? 0}ms, ` +
+          `search ${timings.searchMs ?? 0}ms, rerank ${timings.rerankMs ?? 0}ms` +
+          (timings.fallbackRerankMs !== undefined ? `, fallback rerank ${timings.fallbackRerankMs}ms` : "") +
+          `, total ${timings.totalMs}ms`,
+        toolCalls: [],
+        chunks: [],
+        tokens: 0,
+      });
+
       if (cfg.logging) {
-        console.log("[EXULU pipeline] final result:", JSON.stringify({ steps: result.steps.length, chunks: result.chunks.length }));
+        console.log("[EXULU pipeline] final result:", JSON.stringify({ steps: result.steps.length, chunks: result.chunks.length, timings }));
       }
 
+      // The generator's return value is not consumed by the tool wrapper (for-await only sees
+      // yields), so the final payload — including the timing step — must be yielded.
+      yield { result: serializeOutput(result) };
       return { result: serializeOutput(result) };
       } catch (err) {
         console.warn("[EXULU pipeline] retrieval pipeline failed:", err);

package/ee/agentic-retrieval/pipeline/memory.test.ts

@@ -105,3 +105,62 @@ describe("runMemoryPhase", () => {
     expect(r.updatedQuestion).toBe(baseOpts.question);
   });
 });
+
+describe("recallMemoryByKeywords — fetching the chunks of keyword-matched memory items", () => {
+  const { singleSearch } = jest.requireMock("./multi-query") as { singleSearch: jest.Mock };
+  const { recallMemoryByKeywords, clearMemoryItemCache } = jest.requireActual("./memory") as typeof import("./memory");
+
+  it("uses the full-text method, not the hybrid one: the items are already chosen by keyword, so an embedding call would only add latency", async () => {
+    clearMemoryItemCache();
+    singleSearch.mockClear();
+    const memoryContext = {
+      id: "memory-ctx",
+      getItems: async () => [{ id: "item-1", name: "CBM2 Version", description: "Hinweis zur CBM2 Firmware", information: "" }],
+    };
+    await recallMemoryByKeywords({ keywords: ["CBM2"], importantKeyword: "CBM2", user: {}, role: {}, memoryContext });
+    expect(singleSearch).toHaveBeenCalledTimes(1);
+    expect(singleSearch.mock.calls[0][0].config.method).toBe("tsvector");
+    expect(singleSearch.mock.calls[0][0].pinnedItemIds).toEqual(["item-1"]);
+  });
+});
+
+describe("runMemoryPhase with mergedCall (engine v2)", () => {
+  const merged = (over: Partial<any> = {}) => ({ output: {
+    relevantChunkIds: ["1"],
+    override: { overrides: true, confidence: "high", authoritativeChunkIds: ["1"], reason: "direct answer" },
+    filePrioritization: { shouldPrioritizeFiles: false, fileNameHints: [] },
+    augmentation: { updatedUserQuestion: baseOpts.question + " (Türkontakt)", updatedRelevantKeywords: ["türkontakt"], updatedImportantKeyword: "FST-2XT" },
+    ...over,
+  } });
+
+  it("asks the model once and produces the same result shape as the four v1 hops", async () => {
+    (generateText as jest.Mock).mockResolvedValueOnce(merged());
+    const r = await runMemoryPhase({ ...baseOpts, mergedCall: true, memoryChunks: [memChunk("1", "hint"), memChunk("2", "other")],
+      memoryContext: undefined, memoryConfig: allOn });
+    expect(generateText).toHaveBeenCalledTimes(1);
+    expect(r.memoryChunksForAnswer.map((c) => c.chunk_id)).toEqual(["1"]);
+    expect(r.memoryOverride).toMatchObject({ active: true, reason: "direct answer" });
+    expect(r.memoryOverride.chunks.map((c) => c.chunk_id)).toEqual(["1"]);
+    expect(r.updatedQuestion).toBe(baseOpts.question + " (Türkontakt)");
+    expect(r.updatedKeywords).toEqual(["door", "türkontakt"]);
+    expect(r.updatedImportantKeyword).toBe("FST-2XT"); // original always preserved
+  });
+
+  it("ignores override/file/augmentation parts of the answer when those features are off", async () => {
+    (generateText as jest.Mock).mockResolvedValueOnce(merged());
+    const r = await runMemoryPhase({ ...baseOpts, mergedCall: true, memoryChunks: [memChunk("1", "hint")], memoryContext: undefined,
+      memoryConfig: { enabled: true, override: false, filePrioritization: false, queryAugmentation: false } });
+    expect(generateText).toHaveBeenCalledTimes(1);
+    expect(r.memoryOverride.active).toBe(false);
+    expect(r.updatedQuestion).toBe(baseOpts.question);
+    expect(r.updatedKeywords).toEqual(["door"]);
+  });
+
+  it("treats no relevant chunks as a neutral result even if the model filled the other parts", async () => {
+    (generateText as jest.Mock).mockResolvedValueOnce(merged({ relevantChunkIds: [] }));
+    const r = await runMemoryPhase({ ...baseOpts, mergedCall: true, memoryChunks: [memChunk("1", "hint")], memoryContext: undefined, memoryConfig: allOn });
+    expect(r.memoryChunksForAnswer).toEqual([]);
+    expect(r.memoryOverride.active).toBe(false);
+    expect(r.updatedQuestion).toBe(baseOpts.question);
+  });
+});