codetrap 0.1.7 → 0.1.9

package/src/lib/embedder.ts

@@ -19,6 +19,7 @@ export interface EmbeddingConfig {
 
 export interface StoredEmbedding {
   trap_id: number;
+  profile_id: string;
   provider: string;
   model: string;
   dimensions: number;
@@ -91,9 +92,119 @@ export class JinaEmbedder implements EmbeddingProvider {
   }
 }
 
-export function createDefaultEmbeddingProvider(): EmbeddingProvider | undefined {
-  const apiKey = process.env.JINA_API_KEY;
-  return apiKey ? new JinaEmbedder(apiKey) : undefined;
+export type OllamaEmbedderOptions = {
+  endpoint?: string;
+  model?: string;
+  dimensions?: number;
+  fetch?: FetchLike;
+};
+
+export type OllamaProviderHealth = {
+  ok: boolean;
+  message?: string;
+  command?: string;
+};
+
+type FetchLike = (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
+
+export const DEFAULT_OLLAMA_ENDPOINT = "http://127.0.0.1:11434";
+export const DEFAULT_OLLAMA_MODEL = "qwen3-embedding:0.6b";
+export const DEFAULT_OLLAMA_DIMENSIONS = 1024;
+
+export class OllamaEmbedder implements EmbeddingProvider {
+  readonly provider = "ollama";
+  readonly model: string;
+  readonly dimensions: number;
+  private readonly endpoint: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(options: OllamaEmbedderOptions = {}) {
+    this.endpoint = normalizeOllamaEndpoint(options.endpoint ?? DEFAULT_OLLAMA_ENDPOINT);
+    this.model = options.model ?? DEFAULT_OLLAMA_MODEL;
+    this.dimensions = options.dimensions ?? DEFAULT_OLLAMA_DIMENSIONS;
+    this.fetchImpl = options.fetch ?? fetch;
+  }
+
+  async embed(texts: string[], _task: EmbeddingTask): Promise<Float32Array[]> {
+    if (texts.length === 0) return [];
+
+    const response = await this.fetchImpl(`${this.endpoint}/api/embed`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: texts,
+        dimensions: this.dimensions,
+        truncate: true,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Ollama embeddings request failed (${response.status}): ${body}`);
+    }
+
+    const payload = (await response.json()) as {
+      embeddings?: number[][];
+    };
+    const rows = payload.embeddings ?? [];
+    if (rows.length !== texts.length) {
+      throw new Error(`Ollama embeddings returned ${rows.length} vectors for ${texts.length} inputs.`);
+    }
+
+    return rows.map((embedding) => {
+      if (!Array.isArray(embedding)) {
+        throw new Error("Ollama embeddings response is missing an embedding vector.");
+      }
+      if (embedding.length !== this.dimensions) {
+        throw new Error(
+          `Ollama embeddings returned ${embedding.length} dimensions, expected ${this.dimensions}.`
+        );
+      }
+      return Float32Array.from(embedding);
+    });
+  }
+
+  async health(): Promise<OllamaProviderHealth> {
+    try {
+      const response = await this.fetchImpl(`${this.endpoint}/api/tags`);
+      if (!response.ok) {
+        return {
+          ok: false,
+          message: `Ollama is not reachable at ${this.endpoint} (${response.status}).`,
+          command: "ollama list",
+        };
+      }
+
+      const payload = (await response.json()) as {
+        models?: { name?: string; model?: string }[];
+      };
+      const models = payload.models ?? [];
+      const installed = models.some((model) => model.name === this.model || model.model === this.model);
+      if (!installed) {
+        return {
+          ok: false,
+          message: `Ollama model ${this.model} is not installed.`,
+          command: `ollama pull ${this.model}`,
+        };
+      }
+
+      return { ok: true };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        ok: false,
+        message: `Ollama is not reachable at ${this.endpoint}: ${message}`,
+        command: "ollama list",
+      };
+    }
+  }
+}
+
+function normalizeOllamaEndpoint(endpoint: string): string {
+  return endpoint.replace(/\/+$/, "");
 }
 
 export function embeddingConfig(provider: EmbeddingProvider): EmbeddingConfig {
@@ -105,6 +216,10 @@ export function embeddingConfig(provider: EmbeddingProvider): EmbeddingConfig {
   };
 }
 
+export function embeddingProfileId(config: EmbeddingConfig): string {
+  return `${config.provider}:${config.model}:${config.dimensions}:p${config.passageVersion}`;
+}
+
 export function encodeEmbedding(embedding: Float32Array): Buffer {
   return Buffer.from(embedding.buffer, embedding.byteOffset, embedding.byteLength);
 }

package/src/lib/embedding-health.ts

@@ -1,4 +1,4 @@
-import type { EmbeddingConfig } from "./embedder";
+import { embeddingProfileId, type EmbeddingConfig } from "./embedder";
 
 export type EmbeddingStateCounts = {
   total: number;
@@ -13,6 +13,7 @@ export type EmbeddingStateSummary = EmbeddingStateCounts & {
   model: string | null;
   dimensions: number | null;
   passage_version: number | null;
+  profile_id: string | null;
 };
 
 export type EmbeddingStatsResult = {
@@ -33,6 +34,7 @@ export function summarizeEmbeddingState(
     model: config?.model ?? null,
     dimensions: config?.dimensions ?? null,
     passage_version: config?.passageVersion ?? null,
+    profile_id: config ? embeddingProfileId(config) : null,
   };
 }
 

package/src/lib/embedding-job.ts

@@ -1,6 +1,7 @@
 import type { Trap } from "../domain/trap";
 import {
   embeddingConfig,
+  embeddingProfileId,
   type EmbeddingConfig,
   type EmbeddingProvider,
   type StoredEmbedding,
@@ -35,6 +36,7 @@ export async function runEmbeddingJob(
   opts: EmbeddingJobOptions = {}
 ): Promise<EmbeddingJobResult> {
   const config = embeddingConfig(provider);
+  const profileId = embeddingProfileId(config);
   const total = adapter.countEmbeddable({ scope: opts.scope, category: opts.category });
   const traps = adapter.trapsNeedingEmbeddings(config, opts);
   if (traps.length === 0) return { generated: 0, skipped: total, batches: 0 };
@@ -53,6 +55,7 @@ export async function runEmbeddingJob(
     for (let i = 0; i < batch.length; i++) {
       adapter.saveEmbedding({
         trap_id: batch[i].id,
+        profile_id: profileId,
         provider: config.provider,
         model: config.model,
         dimensions: config.dimensions,

package/src/lib/embedding-management.ts

@@ -0,0 +1,65 @@
+import type { ConfigWriteResult, EmbeddingSettings } from "./config";
+import type { EmbeddingScopeStatus, TrapEmbeddingProfiles, TrapEmbeddingStatus } from "./store";
+import type { EmbeddingProfileSummary } from "../db/embedding-queries";
+
+export type EmbeddingsUseResult = ConfigWriteResult & {
+  embeddings: EmbeddingSettings;
+  next_action: {
+    command: string;
+    reason: string;
+  };
+};
+
+export function formatEmbeddingStatusText(status: TrapEmbeddingStatus): string {
+  const runtime = status.runtime.provider
+    ? `${status.runtime.provider}/${status.runtime.model} (${status.runtime.dimensions}d)`
+    : "unconfigured";
+  const lines = [
+    `Runtime: ${runtime}`,
+    `Available: ${status.runtime.available ? "yes" : "no"}`,
+    `Active profile: ${status.runtime.profile_id ?? "(none)"}`,
+  ];
+
+  if (status.runtime.setup_action) {
+    lines.push(`Next setup: ${status.runtime.setup_action.command}`);
+  }
+
+  lines.push(...scopeStatusLines("Project", status.project));
+  lines.push(...scopeStatusLines("Global", status.global));
+  return lines.join("\n");
+}
+
+export function formatEmbeddingProfilesText(profiles: TrapEmbeddingProfiles): string {
+  const lines = [
+    ...profileSectionLines("Project", profiles.project),
+    ...profileSectionLines("Global", profiles.global),
+  ];
+  return lines.length > 0 ? lines.join("\n") : "No stored embedding profiles.";
+}
+
+export function formatEmbeddingsUseText(result: EmbeddingsUseResult): string {
+  return [
+    `Configured embeddings provider: ${result.embeddings.provider}`,
+    `Config: ${result.path}`,
+    `Next: ${result.next_action.command}`,
+  ].join("\n");
+}
+
+function scopeStatusLines(label: string, status: EmbeddingScopeStatus | null): string[] {
+  if (!status) return [];
+  return [
+    "",
+    `${label}: total ${status.total}, fresh ${status.fresh}, stale ${status.stale}, missing ${status.missing}`,
+    ...profileSectionLines("Stored profiles", status.profiles),
+  ];
+}
+
+function profileSectionLines(label: string, profiles: EmbeddingProfileSummary[] | null): string[] {
+  if (!profiles || profiles.length === 0) return [];
+  return [
+    `${label}:`,
+    ...profiles.map((profile) =>
+      `  - ${profile.id} (${profile.embedding_count} embeddings, updated ${profile.updated_at ?? "unknown"})`
+    ),
+  ];
+}

package/src/lib/embedding-runtime.ts

@@ -0,0 +1,177 @@
+import {
+  DEFAULT_OLLAMA_DIMENSIONS,
+  DEFAULT_OLLAMA_ENDPOINT,
+  DEFAULT_OLLAMA_MODEL,
+  EmbeddingProviderUnavailableError,
+  JinaEmbedder,
+  OllamaEmbedder,
+  embeddingConfig,
+  embeddingProfileId,
+  type EmbeddingConfig,
+  type EmbeddingProvider,
+} from "./embedder";
+import { loadCodetrapConfig, type CodetrapConfig, type EmbeddingProviderSetting } from "./config";
+
+export type EmbeddingRuntimeInput = EmbeddingRuntime | EmbeddingProvider | undefined;
+
+export type EmbeddingRuntimeAction = {
+  command: string;
+  reason: string;
+};
+
+export type EmbeddingRuntimeStatus = {
+  available: boolean;
+  provider: string | null;
+  model: string | null;
+  dimensions: number | null;
+  passage_version: number | null;
+  profile_id: string | null;
+  setup_action: EmbeddingRuntimeAction | null;
+};
+
+export class EmbeddingRuntime {
+  constructor(
+    private readonly adapter?: EmbeddingProvider,
+    private readonly setupProvider: EmbeddingProviderSetting = "ollama",
+    private readonly configuredConfig: EmbeddingConfig | null = null
+  ) {}
+
+  static fromEnvironment(
+    env: NodeJS.ProcessEnv = process.env,
+    config: CodetrapConfig = loadCodetrapConfig()
+  ): EmbeddingRuntime {
+    const provider = configuredProvider(env, config);
+    if (provider === "ollama") {
+      return new EmbeddingRuntime(new OllamaEmbedder(ollamaOptions(env, config)), "ollama");
+    }
+    if (provider === "jina") {
+      const apiKey = env.JINA_API_KEY;
+      const configuredConfig = embeddingConfig(new JinaEmbedder(apiKey ?? ""));
+      return new EmbeddingRuntime(apiKey ? new JinaEmbedder(apiKey) : undefined, "jina", configuredConfig);
+    }
+
+    const apiKey = env.JINA_API_KEY;
+    if (apiKey) return new EmbeddingRuntime(new JinaEmbedder(apiKey), "jina");
+    return new EmbeddingRuntime(undefined, "ollama");
+  }
+
+  provider(): EmbeddingProvider | undefined {
+    return this.adapter;
+  }
+
+  available(): boolean {
+    return this.adapter !== undefined;
+  }
+
+  config(): EmbeddingConfig | null {
+    return this.adapter ? embeddingConfig(this.adapter) : this.configuredConfig;
+  }
+
+  requireProvider(message?: string): EmbeddingProvider {
+    if (!this.adapter) throw this.unavailableError(message);
+    return this.adapter;
+  }
+
+  unavailableError(message?: string): EmbeddingProviderUnavailableError {
+    return new EmbeddingProviderUnavailableError(
+      message ?? "Embedding provider is unavailable. Configure an embedding provider or use --mode fts."
+    );
+  }
+
+  setupAction(): EmbeddingRuntimeAction | null {
+    if (this.adapter) return null;
+    if (this.setupProvider === "jina") {
+      return {
+        command: "export JINA_API_KEY=<your-jina-api-key>",
+        reason: "Enable Jina semantic and hybrid search; otherwise use --mode fts.",
+      };
+    }
+    return {
+      command: "export CODETRAP_EMBEDDING_PROVIDER=ollama",
+      reason: "Enable local semantic and hybrid search after installing Ollama and pulling qwen3-embedding:0.6b; otherwise use --mode fts.",
+    };
+  }
+
+  status(): EmbeddingRuntimeStatus {
+    const config = this.config();
+    return {
+      available: this.available(),
+      provider: config?.provider ?? null,
+      model: config?.model ?? null,
+      dimensions: config?.dimensions ?? null,
+      passage_version: config?.passageVersion ?? null,
+      profile_id: config ? embeddingProfileId(config) : null,
+      setup_action: this.setupAction(),
+    };
+  }
+
+  async health(): Promise<EmbeddingRuntimeStatus> {
+    const status = this.status();
+    if (!this.adapter || !(this.adapter instanceof OllamaEmbedder)) return status;
+
+    const health = await this.adapter.health();
+    if (health.ok) return status;
+    return {
+      ...status,
+      available: false,
+      setup_action: {
+        command: health.command ?? `ollama pull ${this.adapter.model}`,
+        reason: health.message ?? "Ollama embedding provider is unavailable.",
+      },
+    };
+  }
+}
+
+export function defaultEmbeddingRuntime(
+  env: NodeJS.ProcessEnv = process.env,
+  config?: CodetrapConfig
+): EmbeddingRuntime {
+  return EmbeddingRuntime.fromEnvironment(env, config);
+}
+
+export function embeddingRuntimeFrom(input: EmbeddingRuntimeInput): EmbeddingRuntime {
+  return input instanceof EmbeddingRuntime ? input : new EmbeddingRuntime(input);
+}
+
+function configuredProvider(
+  env: NodeJS.ProcessEnv,
+  config: CodetrapConfig
+): EmbeddingProviderSetting | undefined {
+  if (config.embeddings?.provider) return config.embeddings.provider;
+  if (env.CODETRAP_EMBEDDING_PROVIDER) return parseProviderEnv(env.CODETRAP_EMBEDDING_PROVIDER);
+  if (config.embeddings?.endpoint || config.embeddings?.model || config.embeddings?.dimensions) return "ollama";
+  if (env.CODETRAP_OLLAMA_ENDPOINT || env.CODETRAP_OLLAMA_MODEL || env.CODETRAP_OLLAMA_DIMENSIONS) {
+    return "ollama";
+  }
+  return undefined;
+}
+
+function ollamaOptions(env: NodeJS.ProcessEnv, config: CodetrapConfig) {
+  return {
+    endpoint: normalizeEndpointSetting(
+      config.embeddings?.endpoint ?? env.CODETRAP_OLLAMA_ENDPOINT ?? env.OLLAMA_HOST ?? DEFAULT_OLLAMA_ENDPOINT
+    ),
+    model: config.embeddings?.model ?? env.CODETRAP_OLLAMA_MODEL ?? DEFAULT_OLLAMA_MODEL,
+    dimensions:
+      config.embeddings?.dimensions ??
+      parseOptionalPositiveInt(env.CODETRAP_OLLAMA_DIMENSIONS, "CODETRAP_OLLAMA_DIMENSIONS") ??
+      DEFAULT_OLLAMA_DIMENSIONS,
+  };
+}
+
+function parseProviderEnv(value: string): EmbeddingProviderSetting {
+  if (value === "ollama" || value === "jina") return value;
+  throw new Error(`Invalid CODETRAP_EMBEDDING_PROVIDER: ${value}. Expected ollama or jina.`);
+}
+
+function parseOptionalPositiveInt(value: string | undefined, label: string): number | undefined {
+  if (!value) return undefined;
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isInteger(parsed) && parsed > 0) return parsed;
+  throw new Error(`Invalid ${label}: expected a positive integer.`);
+}
+
+function normalizeEndpointSetting(endpoint: string): string {
+  if (/^https?:\/\//.test(endpoint)) return endpoint;
+  return `http://${endpoint}`;
+}

package/src/lib/output-json.ts

@@ -137,5 +137,3 @@ export function toStatsJson(stats: TrapStatsResult, embeddings?: EmbeddingStatsR
 export function toDoctorJson(input: DoctorReport): DoctorReport {
   return input;
 }
-
-export { toTrapEvidenceJson, toTrapJson, type JsonTrap, type JsonTrapEvidence };

package/src/lib/scope-context.ts

@@ -2,9 +2,10 @@ import { openGlobal, openProject } from "../db/connection";
 import { TrapRepository } from "../db/repository";
 import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
 import type { Scope } from "./constants";
-import type { EmbeddingProvider } from "./embedder";
-import { findProjectRoot, getGlobalDB, resolveScopePath } from "./scope";
-import { ScopePathResolver } from "./scope-path";
+import type { EmbeddingRuntime } from "./embedding-runtime";
+import type { RankingConfig } from "./search-policy";
+import { findProjectRoot, getGlobalDB } from "./scope";
+import { resolveScopePath, ScopePathResolver } from "./scope-path";
 
 const scopePath = new ScopePathResolver();
 
@@ -36,7 +37,12 @@ export class ScopedRepositoryContext {
   private globalRepository?: TrapRepository;
   private projectRepository?: TrapRepository;
 
-  constructor(cwd = process.cwd(), private readonly embedder?: EmbeddingProvider, private readonly home?: string) {
+  constructor(
+    cwd = process.cwd(),
+    private readonly embeddings?: EmbeddingRuntime,
+    private readonly home?: string,
+    private readonly ranking?: RankingConfig
+  ) {
     this.context = createScopeContext(cwd, home);
   }
 
@@ -87,14 +93,14 @@ export class ScopedRepositoryContext {
       throw new Error("Not in a project. Run 'codetrap init' first, or use --scope global.");
     }
     if (!this.projectRepository) {
-      this.projectRepository = new TrapRepository(openProject(projectRoot), this.embedder);
+      this.projectRepository = new TrapRepository(openProject(projectRoot), this.embeddings, this.ranking);
     }
     return this.projectRepository;
   }
 
   private globalRepo(): TrapRepository {
     if (!this.globalRepository) {
-      this.globalRepository = new TrapRepository(openGlobal(this.home), this.embedder);
+      this.globalRepository = new TrapRepository(openGlobal(this.home), this.embeddings, this.ranking);
     }
     return this.globalRepository;
   }

package/src/lib/scope-migration.ts

@@ -3,7 +3,8 @@ import { homedir } from "node:os";
 import { openDatabase } from "../db/connection";
 import { TrapRepository } from "../db/repository";
 import type { TrapExportRecord } from "../domain/trap";
-import { findProjectRoot, resolveScopePath } from "./scope";
+import { findProjectRoot } from "./scope";
+import { resolveScopePath } from "./scope-path";
 import {
   backupScopeDatabase,
   buildScopeMaintenancePaths,

package/src/lib/scope.ts

@@ -3,8 +3,6 @@ import { homedir } from "node:os";
 import { CODETRAP_DIR, TRAPS_DB_FILE } from "./constants";
 import { defaultScopePathResolver, resolveScopePath, ScopePathResolver } from "./scope-path";
 
-export { resolveScopePath, ScopePathResolver } from "./scope-path";
-
 export function getGlobalDir(homeDir = homedir()): string {
   const dir = defaultScopePathResolver.join(homeDir, CODETRAP_DIR);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });

package/src/lib/search-eval.ts

@@ -3,13 +3,19 @@ import { openDatabase } from "../db/connection";
 import { TrapRepository } from "../db/repository";
 import type { TrapInput, TrapSearchResult } from "../domain/trap";
 import { SEARCH_MODES, type SearchMode } from "./constants";
+import { isRecord } from "./value-types";
 import {
-  createDefaultEmbeddingProvider,
-  embeddingConfig,
   type EmbeddingConfig,
   type EmbeddingProvider,
   type EmbeddingTask,
 } from "./embedder";
+import {
+  EmbeddingRuntime,
+  defaultEmbeddingRuntime,
+  embeddingRuntimeFrom,
+  type EmbeddingRuntimeInput,
+} from "./embedding-runtime";
+import type { RankingConfig } from "./search-policy";
 
 export type PhaseGate = "phase0" | "phase1" | "phase4" | "dogfood";
 export const DOGFOOD_JUDGMENTS = ["useful_hit", "miss", "noisy_hit", "no_relevant_trap"] as const;
@@ -79,6 +85,10 @@ export type SearchEvalReport = {
   next_actions: SearchEvalNextAction[];
 };
 
+export type SearchEvalDetailedReport = Omit<SearchEvalReport, "mode" | "fixture" | "next_actions"> & {
+  cases: EvalCaseReport[];
+};
+
 export type RecordDogfoodResult = {
   success: true;
   fixture: string;
@@ -115,8 +125,8 @@ export function recordDogfoodCase(fixturePath: string, jsonInput: string | undef
 
 export async function reportDogfood(fixturePath: string, live: boolean): Promise<SearchEvalReport> {
   const fixture = readEvalFixture(fixturePath);
-  const provider = live ? createDefaultEmbeddingProvider() : new EvalEmbedder();
-  const evaluated = await evaluateSearchFixture(fixture, provider);
+  const runtime = live ? defaultEmbeddingRuntime() : new EmbeddingRuntime(new EvalEmbedder());
+  const evaluated = await evaluateSearchFixture(fixture, runtime);
   const mode: SearchEvalReport["mode"] = live ? "live" : "deterministic";
   const report: Omit<SearchEvalReport, "next_actions"> = {
     mode,
@@ -131,19 +141,30 @@ export async function reportDogfood(fixturePath: string, live: boolean): Promise
 
 export async function evaluateSearchFixture(
   fixture: EvalFixture,
-  provider: EmbeddingProvider | undefined
+  embeddings: EmbeddingRuntimeInput,
+  ranking?: RankingConfig
 ): Promise<Omit<SearchEvalReport, "mode" | "fixture" | "next_actions">> {
-  const repo = fixtureRepository(fixture, provider);
+  const { cases: _cases, ...report } = await evaluateSearchFixtureCases(fixture, embeddings, ranking);
+  return report;
+}
+
+export async function evaluateSearchFixtureCases(
+  fixture: EvalFixture,
+  embeddings: EmbeddingRuntimeInput,
+  ranking?: RankingConfig
+): Promise<SearchEvalDetailedReport> {
+  const runtime = embeddingRuntimeFrom(embeddings);
+  const repo = fixtureRepository(fixture, runtime, ranking);
 
   let providerError: string | null = null;
-  if (provider) {
+  if (runtime.available()) {
     try {
       await repo.ensureEmbeddings();
     } catch (error) {
       providerError = errorMessage(error);
     }
   }
-  const searchRepo = providerError ? fixtureRepository(fixture, undefined) : repo;
+  const searchRepo = providerError ? fixtureRepository(fixture, undefined, ranking) : repo;
 
   const cases: EvalCaseReport[] = [];
   let hybridFallbackCount = 0;
@@ -154,7 +175,7 @@ export async function evaluateSearchFixture(
       const results = await searchRepo.search(item.query, { mode: item.mode, limit: 5 });
       const report = caseReport(item, fixture, results);
       cases.push(report);
-      if (item.mode === "hybrid" && (!provider || hasSemanticFallback(results))) {
+      if (item.mode === "hybrid" && (!runtime.available() || hasSemanticFallback(results))) {
         hybridFallbackCount++;
       }
     } catch (error) {
@@ -169,8 +190,8 @@ export async function evaluateSearchFixture(
   const noisyHits = cases.filter((item) => item.judgment === "noisy_hit");
   const metrics = aggregateMetrics(cases);
   return {
-    provider: provider ? embeddingConfig(provider) : null,
-    semantic_available: Boolean(provider && providerError === null),
+    provider: runtime.config(),
+    semantic_available: runtime.available() && providerError === null,
     provider_error: providerError,
     total_cases: cases.length,
     metrics: {
@@ -190,6 +211,7 @@ export async function evaluateSearchFixture(
     failures,
     misses,
     noisy_hits: noisyHits,
+    cases,
   };
 }
 
@@ -240,8 +262,9 @@ function buildSearchEvalNextActions(
 ): SearchEvalNextAction[] {
   const actions: SearchEvalNextAction[] = [];
   if (report.mode === "live" && !report.semantic_available) {
-    actions.push({
-      command: "export JINA_API_KEY=<your-jina-api-key>",
+    const action = defaultEmbeddingRuntime().setupAction();
+    if (action) actions.push({
+      command: action.command,
       reason: "Enable live semantic checks, then rerun bun run eval:dogfood -- report --live.",
     });
   }
@@ -309,8 +332,8 @@ function formatNextActions(actions: SearchEvalNextAction[]): string[] {
   return actions.map((action) => `  - ${action.command} # ${action.reason}`);
 }
 
-function fixtureRepository(fixture: EvalFixture, provider: EmbeddingProvider | undefined): TrapRepository {
-  const repo = new TrapRepository(openDatabase(":memory:"), provider);
+function fixtureRepository(fixture: EvalFixture, embeddings: EmbeddingRuntimeInput, ranking?: RankingConfig): TrapRepository {
+  const repo = new TrapRepository(openDatabase(":memory:"), embeddings, ranking);
   for (const trap of fixture.traps) repo.add(trap);
   return repo;
 }
@@ -471,9 +494,6 @@ function providerLabel(provider: EmbeddingConfig | null): string {
   return `${provider.provider}/${provider.model}`;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === "object" && value !== null && !Array.isArray(value);
-}
 
 function round(value: number): number {
   return Math.round(value * 10000) / 10000;