@exulu/backend 3.0.0 → 3.1.0

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

@@ -1,6 +1,6 @@
 import { generateHydePassage, clearHydeCache } from "./hyde";
 
-jest.mock("ai", () => ({ generateText: jest.fn() }));
+jest.mock("ai", () => ({ ...jest.requireActual("ai"), generateText: jest.fn() }));
 import { generateText } from "ai";
 
 beforeEach(() => {

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

@@ -1,4 +1,4 @@
-import { generateText } from "ai";
+import { microCall } from "./micro-call";
 import { extractIdentifierTokens } from "./text-utils";
 
 // Per-question memoization of the HyDE passage. A single search invokes
@@ -122,11 +122,14 @@ IMPORTANT:
 Question: "${originalQuestion}"
 Relevant keywords: ${relevantKeywords.join(", ")}`;
 
-  const { text } = await generateText({
+  // Single attempt on purpose: HyDE is an optional search anchor with a null
+  // fallback and per-question cache eviction on failure — retry backoff here
+  // would delay every search phase behind it.
+  const { text } = await microCall({
     model,
     prompt,
     temperature: 0.3,
-    maxOutputTokens: 500,
+    maxAttempts: 1,
   });
   const passage = (text || "").trim();
   return passage.length > 0 ? passage : null;

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

@@ -1,7 +1,11 @@
 // ee/agentic-retrieval/pipeline/memory.test.ts
 import { runMemoryPhase, clearMemoryItemCache } from "./memory";
 
-jest.mock("ai", () => ({ generateText: jest.fn(), Output: { object: (x: any) => x } }));
+jest.mock("ai", () => ({
+  ...jest.requireActual("ai"),
+  generateText: jest.fn(),
+  Output: { object: (x: any) => x },
+}));
 jest.mock("./multi-query", () => ({ singleSearch: jest.fn(async () => []) }));
 jest.mock("./prefilter", () => ({ fuzzyPrefilter: jest.fn(async () => []) }));
 import { generateText } from "ai";

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

@@ -1,6 +1,5 @@
-import { generateText, Output } from "ai";
 import { z } from "zod";
-import { withRetry } from "@SRC/utils/with-retry";
+import { microCall } from "./micro-call";
 import { singleSearch } from "./multi-query";
 import { fuzzyPrefilter } from "./prefilter";
 import { deriveKeywordVariants, normalizeFileName, stripSeparators } from "./text-utils";
@@ -219,35 +218,27 @@ export async function runMemoryPhase({
 
     let relevantMemoryChunks: Chunk[] = [];
     try {
-      const { output: output_relevant_memory } = await withRetry(
-        () =>
-          generateText({
-            model,
-            temperature: 0,
-            system: CHECK_MEMORIES_FOR_RELEVANT_INFORMATION,
-            messages: [
-              {
-                role: "user",
-                content: `
+      const { output: output_relevant_memory } = await microCall({
+        model,
+        system: CHECK_MEMORIES_FOR_RELEVANT_INFORMATION,
+        messages: [
+          {
+            role: "user",
+            content: `
             <user_question>${question}</user_question>
             <relevant_keywords>${keywords.join(", ")}</relevant_keywords>
             <important_keyword>${importantKeyword}</important_keyword>
             `,
-              },
-            ],
-            output: Output.object({
-              schema: z.object({
-                relevantChunkIds: z
-                  .array(z.string())
-                  .describe(
-                    "The chunk_ids (UUIDs at the start of each bullet) of chunks containing information relevant to the user's question. Empty array if none are relevant.",
-                  ),
-              }),
-            }),
-            maxOutputTokens: 400,
-          }),
-        3,
-      );
+          },
+        ],
+        schema: z.object({
+          relevantChunkIds: z
+            .array(z.string())
+            .describe(
+              "The chunk_ids (UUIDs at the start of each bullet) of chunks containing information relevant to the user's question. Empty array if none are relevant.",
+            ),
+        }),
+      });
 
       const ids = new Set(output_relevant_memory?.relevantChunkIds ?? []);
       relevantMemoryChunks =
@@ -360,50 +351,42 @@ export async function runMemoryPhase({
       const [overrideResult, fileResult, queryResult] = await Promise.all([
         // Override check: strict gate to decide if memory should be authoritative
         memoryConfig.override
-          ? withRetry(
-              () =>
-                generateText({
-                  model,
-                  temperature: 0,
-                  system: CHECK_MEMORY_OVERRIDE,
-                  messages: [
-                    {
-                      role: "user",
-                      content: `
+          ? microCall({
+              model,
+              system: CHECK_MEMORY_OVERRIDE,
+              messages: [
+                {
+                  role: "user",
+                  content: `
                   <user_question>${question}</user_question>
                   <relevant_keywords>${keywords.join(", ")}</relevant_keywords>
                   <important_keyword>${importantKeyword}</important_keyword>
                   `,
-                    },
-                  ],
-                  output: Output.object({
-                    schema: z.object({
-                      overrides: z
-                        .boolean()
-                        .describe(
-                          "True ONLY if a memory chunk directly and sufficiently answers the user's question and should be authoritative over the documents. Be strict; when unsure, false.",
-                        ),
-                      confidence: z
-                        .enum(["high", "medium", "low"])
-                        .describe(
-                          "Confidence that the selected memory chunk(s) fully and directly answer the question.",
-                        ),
-                      authoritativeChunkIds: z
-                        .array(z.string())
-                        .describe(
-                          "The chunk_ids of the memory chunk(s) that directly answer the question. Empty if overrides is false.",
-                        ),
-                      reason: z
-                        .string()
-                        .describe(
-                          "One short sentence: why this memory does or does not directly answer the question.",
-                        ),
-                    }),
-                  }),
-                  maxOutputTokens: 300,
-                }),
-              3,
-            ).catch(() => ({
+                },
+              ],
+              schema: z.object({
+                overrides: z
+                  .boolean()
+                  .describe(
+                    "True ONLY if a memory chunk directly and sufficiently answers the user's question and should be authoritative over the documents. Be strict; when unsure, false.",
+                  ),
+                confidence: z
+                  .enum(["high", "medium", "low"])
+                  .describe(
+                    "Confidence that the selected memory chunk(s) fully and directly answer the question.",
+                  ),
+                authoritativeChunkIds: z
+                  .array(z.string())
+                  .describe(
+                    "The chunk_ids of the memory chunk(s) that directly answer the question. Empty if overrides is false.",
+                  ),
+                reason: z
+                  .string()
+                  .describe(
+                    "One short sentence: why this memory does or does not directly answer the question.",
+                  ),
+              }),
+            }).catch(() => ({
               output: {
                 overrides: false,
                 confidence: "low",
@@ -422,24 +405,16 @@ export async function runMemoryPhase({
 
         // File prioritization: detect explicit document-pinning instructions in memory
         memoryConfig.filePrioritization
-          ? withRetry(
-              () =>
-                generateText({
-                  model,
-                  temperature: 0,
-                  system:
-                    "You are a helpful assistant that will strictly follow the user's instructions.",
-                  messages: [{ role: "user", content: PROMPT_EXTRACT_PRIORITIZED_FILES }],
-                  output: Output.object({
-                    schema: z.object({
-                      shouldPrioritizeFiles: z.boolean(),
-                      fileNameHints: z.array(z.string()).optional(),
-                    }),
-                  }),
-                  maxOutputTokens: 300,
-                }),
-              3,
-            ).catch(() => ({
+          ? microCall({
+              model,
+              system:
+                "You are a helpful assistant that will strictly follow the user's instructions.",
+              messages: [{ role: "user", content: PROMPT_EXTRACT_PRIORITIZED_FILES }],
+              schema: z.object({
+                shouldPrioritizeFiles: z.boolean(),
+                fileNameHints: z.array(z.string()).optional(),
+              }),
+            }).catch(() => ({
               output: { shouldPrioritizeFiles: false, fileNameHints: [] as string[] },
             }))
           : Promise.resolve({
@@ -448,25 +423,17 @@ export async function runMemoryPhase({
 
         // Query augmentation: expand keywords with synonyms/abbreviations from memory
         memoryConfig.queryAugmentation && hasAugmentationContent
-          ? withRetry(
-              () =>
-                generateText({
-                  model,
-                  temperature: 0,
-                  system:
-                    "You are a helpful assistant that will strictly follow the user's instructions.",
-                  messages: [{ role: "user", content: QUERY_AUGMENTATION_PROMPT }],
-                  output: Output.object({
-                    schema: z.object({
-                      updatedUserQuestion: z.string(),
-                      updatedRelevantKeywords: z.array(z.string()),
-                      updatedImportantKeyword: z.string(),
-                    }),
-                  }),
-                  maxOutputTokens: 600,
-                }),
-              3,
-            ).catch(() => ({
+          ? microCall({
+              model,
+              system:
+                "You are a helpful assistant that will strictly follow the user's instructions.",
+              messages: [{ role: "user", content: QUERY_AUGMENTATION_PROMPT }],
+              schema: z.object({
+                updatedUserQuestion: z.string(),
+                updatedRelevantKeywords: z.array(z.string()),
+                updatedImportantKeyword: z.string(),
+              }),
+            }).catch(() => ({
               output: {
                 updatedUserQuestion: question,
                 updatedRelevantKeywords: [],

package/ee/agentic-retrieval/pipeline/micro-call.test.ts

@@ -0,0 +1,112 @@
+// ee/agentic-retrieval/pipeline/micro-call.test.ts
+import { z } from "zod";
+
+jest.mock("ai", () => {
+  const actual = jest.requireActual("ai");
+  return { ...actual, generateText: jest.fn() };
+});
+import { generateText } from "ai";
+import {
+  microCall,
+  microCallProviderOptions,
+  MICRO_CALL_MAX_OUTPUT_TOKENS,
+} from "./micro-call";
+
+const { NoOutputGeneratedError } = jest.requireActual("ai");
+
+beforeEach(() => {
+  (generateText as jest.Mock).mockReset();
+});
+
+describe("microCallProviderOptions", () => {
+  it("disables thinking for gemini model ids (object and string forms)", () => {
+    expect(microCallProviderOptions({ modelId: "vertex-gemini-3.5-flash" } as any)).toEqual({
+      litellm: { reasoningEffort: "disable" },
+    });
+    expect(microCallProviderOptions("gemini-3.1-flash-lite")).toEqual({
+      litellm: { reasoningEffort: "disable" },
+    });
+  });
+
+  it("returns undefined for non-gemini models", () => {
+    expect(microCallProviderOptions({ modelId: "qwen3-235b" } as any)).toBeUndefined();
+    expect(microCallProviderOptions({} as any)).toBeUndefined();
+  });
+});
+
+describe("microCall", () => {
+  const schema = z.object({ ok: z.boolean() });
+
+  it("applies shared defaults: temperature 0, raised token cap, no SDK-internal retries", async () => {
+    (generateText as jest.Mock).mockResolvedValue({ output: { ok: true }, text: "" });
+    await microCall({
+      model: { modelId: "vertex-gemini-3.5-flash" } as any,
+      system: "s",
+      messages: [{ role: "user", content: "q" }],
+      schema,
+    });
+    const args = (generateText as jest.Mock).mock.calls[0][0];
+    expect(args.temperature).toBe(0);
+    expect(args.maxOutputTokens).toBe(MICRO_CALL_MAX_OUTPUT_TOKENS);
+    expect(MICRO_CALL_MAX_OUTPUT_TOKENS).toBe(2000);
+    expect(args.maxRetries).toBe(0);
+    expect(args.providerOptions).toEqual({ litellm: { reasoningEffort: "disable" } });
+  });
+
+  it("returns the parsed output for schema calls", async () => {
+    (generateText as jest.Mock).mockResolvedValue({ output: { ok: true }, text: "{}" });
+    const { output } = await microCall({
+      model: {} as any,
+      system: "s",
+      messages: [{ role: "user", content: "q" }],
+      schema,
+    });
+    expect(output).toEqual({ ok: true });
+  });
+
+  it("returns text and omits structured output when no schema is given", async () => {
+    (generateText as jest.Mock).mockResolvedValue({ text: "a passage" });
+    const { text } = await microCall({
+      model: {} as any,
+      prompt: "write",
+      temperature: 0.3,
+    });
+    expect(text).toBe("a passage");
+    const args = (generateText as jest.Mock).mock.calls[0][0];
+    expect(args.output).toBeUndefined();
+    expect(args.temperature).toBe(0.3);
+  });
+
+  it("fails fast without retrying when the model generated no output", async () => {
+    (generateText as jest.Mock).mockResolvedValue({
+      text: "",
+      get output(): unknown {
+        throw new NoOutputGeneratedError({ message: "No output generated." });
+      },
+    });
+    await expect(
+      microCall({
+        model: {} as any,
+        system: "s",
+        messages: [{ role: "user", content: "q" }],
+        schema,
+      }),
+    ).rejects.toThrow("No output generated.");
+    expect(generateText).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries transient errors and succeeds", async () => {
+    (generateText as jest.Mock)
+      .mockRejectedValueOnce(new Error("socket hang up"))
+      .mockResolvedValueOnce({ output: { ok: true }, text: "" });
+    const { output } = await microCall({
+      model: {} as any,
+      system: "s",
+      messages: [{ role: "user", content: "q" }],
+      schema,
+      retryBaseDelayMs: 1,
+    });
+    expect(output).toEqual({ ok: true });
+    expect(generateText).toHaveBeenCalledTimes(2);
+  });
+});

package/ee/agentic-retrieval/pipeline/micro-call.ts

@@ -0,0 +1,98 @@
+// ee/agentic-retrieval/pipeline/micro-call.ts
+//
+// Shared wrapper for the pipeline's internal LLM micro-calls (routing,
+// classification, memory checks, identifier extraction, HyDE). Centralizes the
+// settings that keep these calls working on reasoning models.
+import { generateText, NoOutputGeneratedError, Output } from "ai";
+import type { LanguageModel, ModelMessage } from "ai";
+import type { z } from "zod";
+import { withRetry } from "@SRC/utils/with-retry";
+
+/**
+ * Reasoning models (Gemini 3+) count thinking tokens against maxOutputTokens.
+ * The earlier 200–600 caps got fully consumed by thinking on such models —
+ * finishReason "length" with zero visible text — so every micro-call failed
+ * with NoOutputGeneratedError and its phase fell back to the degraded path.
+ * 2000 leaves headroom even when thinking can only be minimized, not disabled.
+ */
+export const MICRO_CALL_MAX_OUTPUT_TOKENS = 2000;
+
+/**
+ * Thinking off for Gemini utility models: LiteLLM maps reasoning_effort
+ * "disable" to thinkingBudget 0 (Gemini ≤2.5) or thinkingLevel "minimal"
+ * (Gemini 3+, which cannot fully disable thinking). Gated on the model id
+ * because LiteLLM rejects reasoning params for providers without a mapping
+ * (e.g. vertex qwen MaaS) unless drop_params is set in the proxy config.
+ */
+export function microCallProviderOptions(
+  model: LanguageModel,
+): Record<string, Record<string, string>> | undefined {
+  const modelId = typeof model === "string" ? model : model?.modelId;
+  return typeof modelId === "string" && /gemini/i.test(modelId)
+    ? { litellm: { reasoningEffort: "disable" } }
+    : undefined;
+}
+
+export type MicroCallArgs<OUTPUT> = {
+  model: LanguageModel;
+  system?: string;
+  prompt?: string;
+  messages?: ModelMessage[];
+  /** Structured output schema; omit for free-text calls. */
+  schema?: z.ZodType<OUTPUT>;
+  /** Defaults to 0 — the pipeline's determinism requirement. */
+  temperature?: number;
+  maxOutputTokens?: number;
+  /** Total attempts for transient failures (network, provider 429/5xx). */
+  maxAttempts?: number;
+  retryBaseDelayMs?: number;
+};
+
+export async function microCall<OUTPUT = undefined>(
+  args: MicroCallArgs<OUTPUT>,
+): Promise<{ output: OUTPUT; text: string }> {
+  const {
+    model,
+    system,
+    prompt,
+    messages,
+    schema,
+    temperature = 0,
+    maxOutputTokens = MICRO_CALL_MAX_OUTPUT_TOKENS,
+    maxAttempts = 3,
+    retryBaseDelayMs,
+  } = args;
+
+  return withRetry(
+    async () => {
+      const result = await generateText({
+        model,
+        temperature,
+        system,
+        prompt,
+        messages,
+        ...(schema ? { output: Output.object({ schema }) } : {}),
+        maxOutputTokens,
+        // withRetry owns retries. The SDK's internal retries on top of it
+        // tripled request volume per attempt while the provider was already
+        // rate-limiting.
+        maxRetries: 0,
+        providerOptions: microCallProviderOptions(model),
+      } as Parameters<typeof generateText>[0]);
+      // Read .output inside the retried closure — the SDK throws
+      // NoOutputGeneratedError from this getter, so reading it later would
+      // escape both the retry classification and the caller's per-call catch.
+      return {
+        output: (schema ? (result as { output: OUTPUT }).output : undefined) as OUTPUT,
+        text: result.text,
+      };
+    },
+    maxAttempts,
+    {
+      // Empty output is deterministic for identical params — retrying only
+      // added latency before the degraded path. Fail fast instead.
+      shouldRetry: (error) => !NoOutputGeneratedError.isInstance(error),
+      ...(retryBaseDelayMs !== undefined ? { baseDelayMs: retryBaseDelayMs } : {}),
+    },
+  );
+}

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

@@ -1,6 +1,7 @@
 import { fuzzyPrefilter, exactTokenPrefilter, resolveIdentifierPins, clearPrefilterCaches } from "./prefilter";
 
 jest.mock("ai", () => ({
+  ...jest.requireActual("ai"),
   generateText: jest.fn(),
   Output: { object: jest.fn((o) => o) },
 }));

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

@@ -1,7 +1,6 @@
 import Fuse from "fuse.js";
-import { generateText, Output } from "ai";
 import { z } from "zod";
-import { withRetry } from "@SRC/utils/with-retry";
+import { microCall } from "./micro-call";
 import { normalizeFileName } from "./text-utils";
 import { DEFAULT_PREFILTER_CUTOFF, type IdentifierSet, type KbKind } from "./config";
 import type { PhaseStep } from "./types";
@@ -322,24 +321,16 @@ export async function resolveIdentifierPins({
     identifierSets.map(async (set) => {
       if (!set.contexts.length) return;
       try {
-        const { output } = await withRetry(
-          () =>
-            generateText({
-              model,
-              temperature: 0,
-              system:
-                set.strategy === "exact" ? EXACT_EXTRACTION_PROMPT(set) : FUZZY_EXTRACTION_PROMPT(set),
-              messages: [{ role: "user", content: question }],
-              output: Output.object({
-                schema: z.object({
-                  hasMatches: z.boolean(),
-                  matches: z.array(z.string()).optional(),
-                }),
-              }),
-              maxOutputTokens: 300,
-            }),
-          3,
-        );
+        const { output } = await microCall({
+          model,
+          system:
+            set.strategy === "exact" ? EXACT_EXTRACTION_PROMPT(set) : FUZZY_EXTRACTION_PROMPT(set),
+          messages: [{ role: "user", content: question }],
+          schema: z.object({
+            hasMatches: z.boolean(),
+            matches: z.array(z.string()).optional(),
+          }),
+        });
         if (!output?.hasMatches || !output.matches?.length) return;
         steps.push({ text: `Detected ${set.name} in the question: ${output.matches.join(", ")}` });
 

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

@@ -1,7 +1,10 @@
 // ee/agentic-retrieval/pipeline/routing.test.ts
 import { runRoutingPhase } from "./routing";
 
-jest.mock("ai", () => ({ generateText: jest.fn(), Output: { object: (x: any) => x } }));
+jest.mock("ai", () => {
+  const actual = jest.requireActual("ai");
+  return { ...actual, generateText: jest.fn(), Output: { object: (x: any) => x } };
+});
 jest.mock("./prefilter", () => ({ fuzzyPrefilter: jest.fn(async () => []) }));
 import { generateText } from "ai";
 import { fuzzyPrefilter } from "./prefilter";
@@ -141,4 +144,44 @@ describe("runRoutingPhase", () => {
     });
     expect(r.mainContexts).toEqual(["docs", "tickets"]);
   }, 30000); // withRetry backs off 2s+4s before exhausting
+
+  it("sends thinking-disable provider options and the raised token cap on every micro-call (gemini)", async () => {
+    (generateText as jest.Mock)
+      .mockResolvedValueOnce(noHints)
+      .mockResolvedValueOnce(noExplicit)
+      .mockResolvedValueOnce({ output: { ruleId: "t", reason: "r" } });
+    await runRoutingPhase({
+      question: "how do I fix the door?", enabledContexts: enabled, documentContexts: [],
+      routingRules: [{ id: "t", label: "T", description: "d", main: ["docs"], fallback: ["tickets"] }],
+      preselectedItems: new Map(), model: { modelId: "vertex-gemini-3.5-flash" },
+    });
+    const calls = (generateText as jest.Mock).mock.calls;
+    expect(calls.length).toBe(3);
+    for (const [args] of calls) {
+      expect(args.maxOutputTokens).toBe(2000);
+      expect(args.maxRetries).toBe(0);
+      expect(args.providerOptions).toEqual({ litellm: { reasoningEffort: "disable" } });
+    }
+  });
+
+  it("degrades only the doc/page step when the model returns empty output (thinking-starvation regression)", async () => {
+    const { NoOutputGeneratedError } = jest.requireActual("ai");
+    (generateText as jest.Mock)
+      .mockResolvedValueOnce({
+        text: "",
+        get output(): any {
+          throw new NoOutputGeneratedError({ message: "No output generated." });
+        },
+      })
+      .mockResolvedValueOnce(noExplicit);
+    const r = await runRoutingPhase({
+      question: "q", enabledContexts: enabled, documentContexts: [], routingRules: [],
+      preselectedItems: new Map(), model: {},
+    });
+    // Empty output is deterministic: no blind retry, and only the one step degrades.
+    expect(generateText).toHaveBeenCalledTimes(2);
+    expect(r.steps.some((s) => s.text.includes("Doc/page detection failed"))).toBe(true);
+    expect(r.steps.some((s) => s.text.includes("Routing failed"))).toBe(false);
+    expect(r.mainContexts).toEqual(["docs", "tickets"]);
+  });
 });