feat(compression): wire ultra's modelPath/slmFallbackToAggressive to the llmlingua SLM tier

open-sse/services/compression/strategySelector.ts

@@ -240,9 +240,82 @@ export async function applyCompressionAsync(
     );
     return adapter.adapted ? { ...result, body: adapter.restore(result.body) } : result;
   }
+  // Ultra's optional SLM (model) tier is async — route it here when a model is configured.
+  if (mode === "ultra") {
+    return applyUltraAsync(body, options);
+  }
   return applyCompression(body, mode, options);
 }
 
+/**
+ * Ultra mode with the optional local SLM (model) tier.
+ *
+ * When `config.ultra.modelPath` is set, the prose is routed through the llmlingua engine
+ * (the real local-model compressor). The llmlingua backend fail-opens when the model is
+ * absent (e.g. the ONNX model is not provisioned), so this degrades gracefully:
+ *  - model present and it compresses  → return the SLM result (tagged "ultra-slm");
+ *  - model absent / no gain / failure → fall back to `aggressive` when
+ *    `slmFallbackToAggressive` is set, otherwise the heuristic ultra (`pruneByScore`).
+ *
+ * Without `modelPath` the behavior is byte-identical to the synchronous heuristic ultra.
+ */
+async function applyUltraAsync(
+  body: Record<string, unknown>,
+  options?: {
+    model?: string;
+    supportsVision?: boolean | null;
+    config?: CompressionConfig;
+    principalId?: string;
+    onEngineStep?: (step: StackedCompressionStep) => void;
+  }
+): Promise<CompressionResult> {
+  const ultraConfig = options?.config?.ultra;
+  const modelPath = typeof ultraConfig?.modelPath === "string" ? ultraConfig.modelPath.trim() : "";
+
+  // No model configured → heuristic ultra (unchanged default).
+  if (!modelPath) {
+    return applyCompression(body, "ultra", options);
+  }
+
+  registerBuiltinCompressionEngines();
+  const slmEngine = getCompressionEngine("llmlingua");
+  if (slmEngine?.applyAsync) {
+    const engineOptions: CompressionEngineApplyOptions = {
+      model: options?.model,
+      supportsVision: options?.supportsVision,
+      config: options?.config,
+      principalId: options?.principalId,
+      stepConfig: {
+        modelPath,
+        ...(typeof ultraConfig?.compressionRate === "number"
+          ? { compressionRate: ultraConfig.compressionRate }
+          : {}),
+      },
+    };
+    try {
+      const slm = await slmEngine.applyAsync(body, engineOptions);
+      if (slm.compressed && slm.stats) {
+        // Attribute the result to ultra (the selected mode) while marking the SLM tier.
+        return {
+          ...slm,
+          stats: {
+            ...slm.stats,
+            mode: "ultra",
+            techniquesUsed: Array.from(
+              new Set([...(slm.stats.techniquesUsed ?? []), "ultra-slm"])
+            ),
+          },
+        };
+      }
+    } catch {
+      // llmlingua fail-opens internally, but guard anyway and use the configured fallback.
+    }
+  }
+
+  // SLM tier unavailable or produced no gain → fall back per slmFallbackToAggressive.
+  return applyCompression(body, ultraConfig?.slmFallbackToAggressive ? "aggressive" : "ultra", options);
+}
+
 function normalizePipelineStep(step: CompressionPipelineStep | string): CompressionPipelineStep {
   if (typeof step !== "string") return step;
   if (step === "standard") return { engine: "caveman" };

tests/unit/compression/ultra-slm-tier.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Ultra SLM tier — wiring the ultra mode's modelPath / slmFallbackToAggressive config
+ * to the real model path (the llmlingua engine).
+ *
+ * Until now ultra was a pure heuristic (pruneByScore) and modelPath /
+ * slmFallbackToAggressive were inert config. The async entry point now routes ultra
+ * through the llmlingua engine when modelPath is set, falling back per
+ * slmFallbackToAggressive when the model is unavailable / yields no gain.
+ *
+ * The llmlingua backend is injectable (setLlmlinguaBackend), so the tier is testable
+ * without the real ONNX model.
+ */
+import { describe, it, after, afterEach } from "node:test";
+import assert from "node:assert/strict";
+
+import { applyCompressionAsync } from "../../../open-sse/services/compression/index.ts";
+import { setLlmlinguaBackend } from "../../../open-sse/services/compression/engines/llmlingua/index.ts";
+import { DEFAULT_ULTRA_CONFIG } from "../../../open-sse/services/compression/types.ts";
+
+// Comfortably above the llmlingua default 2000-token floor (estimate ≈ chars / 4).
+const LARGE_PROSE = "The quick brown fox jumps over the lazy dog every morning. ".repeat(260);
+
+function body() {
+  return { model: "gpt-4o", messages: [{ role: "user", content: LARGE_PROSE }] };
+}
+
+function ultraOpts(ultra: Record<string, unknown>) {
+  // Only config.ultra is read by the ultra SLM tier; the rest of CompressionConfig is unused here.
+  return { config: { ultra: { ...DEFAULT_ULTRA_CONFIG, ...ultra } } } as unknown as Parameters<
+    typeof applyCompressionAsync
+  >[2];
+}
+
+let backendCalls = 0;
+function trackingCompressingBackend(text: string): Promise<string> {
+  backendCalls++;
+  return Promise.resolve(text.slice(0, Math.max(1, Math.floor(text.length / 3))));
+}
+function identityBackend(text: string): Promise<string> {
+  backendCalls++;
+  return Promise.resolve(text); // no gain → llmlingua reports compressed:false
+}
+function throwingBackend(_text: string): Promise<string> {
+  backendCalls++;
+  return Promise.reject(new Error("model unavailable"));
+}
+
+afterEach(() => {
+  backendCalls = 0;
+});
+after(() => setLlmlinguaBackend(null));
+
+function techniques(stats: unknown): string[] {
+  return ((stats as { techniquesUsed?: string[] } | null)?.techniquesUsed ?? []) as string[];
+}
+
+describe("ultra SLM tier — modelPath routes through llmlingua", () => {
+  it("runs the SLM tier when modelPath is set and the model compresses", async () => {
+    setLlmlinguaBackend(trackingCompressingBackend);
+    const result = await applyCompressionAsync(
+      body(),
+      "ultra",
+      ultraOpts({ modelPath: "/models/fake.onnx", compressionRate: 0.5 })
+    );
+    assert.equal(backendCalls > 0, true, "backend was consulted");
+    assert.equal(result.compressed, true);
+    assert.equal((result.stats as { mode?: string } | null)?.mode, "ultra");
+    assert.ok(techniques(result.stats).includes("ultra-slm"), "tagged as the ultra SLM tier");
+  });
+
+  it("falls back to aggressive when the model yields no gain and slmFallbackToAggressive is on", async () => {
+    setLlmlinguaBackend(identityBackend);
+    const result = await applyCompressionAsync(
+      body(),
+      "ultra",
+      ultraOpts({ modelPath: "/models/fake.onnx", slmFallbackToAggressive: true })
+    );
+    assert.ok(techniques(result.stats).includes("aggressive"), "fell back to aggressive");
+    assert.ok(!techniques(result.stats).includes("ultra-slm"));
+  });
+
+  it("falls back to the heuristic when the model fails and slmFallbackToAggressive is off", async () => {
+    setLlmlinguaBackend(throwingBackend);
+    const result = await applyCompressionAsync(
+      body(),
+      "ultra",
+      ultraOpts({ modelPath: "/models/fake.onnx", slmFallbackToAggressive: false })
+    );
+    const techs = techniques(result.stats);
+    assert.equal((result.stats as { mode?: string } | null)?.mode, "ultra");
+    assert.ok(techs.includes("ultra"), "heuristic ultra ran");
+    assert.ok(!techs.includes("ultra-slm"), "not the SLM tier");
+    assert.ok(!techs.includes("aggressive"), "not the aggressive fallback");
+  });
+
+  it("uses the heuristic and never touches the model when modelPath is unset", async () => {
+    setLlmlinguaBackend(throwingBackend); // would blow up if (wrongly) consulted
+    const result = await applyCompressionAsync(body(), "ultra", ultraOpts({ modelPath: "" }));
+    assert.equal(backendCalls, 0, "model not consulted without modelPath");
+    assert.equal((result.stats as { mode?: string } | null)?.mode, "ultra");
+    assert.ok(!techniques(result.stats).includes("ultra-slm"));
+  });
+});