fix(cli): resolve embedding provider explicitly and surface lane status in sl search (#192)

* feat(cli): add tryUseManagedLocalEmbeddingsDaemon for read-only callers * feat(cli): add resolveProjectEmbeddingProvider helper * fix(cli): wire sl search through resolveProjectEmbeddingProvider so semantic lane works * fix(cli): wire wiki/knowledge search through resolveProjectEmbeddingProvider * feat(cli): surface embeddings-unavailable status when sl search returns empty * refactor(cli): route admin reindex through resolveProjectEmbeddingProvider * refactor: pass embeddingProvider into ingest/scan instead of resolving inside @ktx/context * refactor(mcp): resolve embedding provider in CLI factory, pass into context ports * refactor(context): delete MANAGED_SENTENCE_TRANSFORMERS_BASE_URL sentinel * refactor(cli): delete sentinel-based managed-embeddings indirection * chore: scrub stale managed-embeddings sentinel references from tests and smoke script * chore: unexport unused EmbeddingResolutionMode alias * fix(cli): force pathPrefix="" when targeting the managed embeddings daemon The managed daemon serves /embeddings/compute directly. The default pathPrefix in @ktx/llm is /api, so omitting sentenceTransformers from ktx.yaml produced /api/embeddings/compute -> 404. The resolver now sets pathPrefix='' explicitly when wiring the managed daemon URL, matching what the daemon actually exposes.
2026-06-22 08:38:08 +02:00 · 2026-05-21 02:21:22 +02:00 · 2026-05-21 02:21:22 +02:00 · 9d92c79988
commit 9d92c79988
parent 56a967278a
36 changed files with 750 additions and 442 deletions
--- a/packages/cli/src/embedding-resolution.ts
+++ b/packages/cli/src/embedding-resolution.ts
@ -0,0 +1,107 @@
+import {
+  type KtxEmbeddingProvider,
+  createKtxEmbeddingProvider as defaultCreateKtxEmbeddingProvider,
+} from '@ktx/llm';
+import type { KtxLocalProject, KtxProjectEmbeddingConfig } from '@ktx/context/project';
+import { resolveLocalKtxEmbeddingConfig } from '@ktx/context';
+import type { KtxCliIo } from './cli-runtime.js';
+import {
+  ensureManagedLocalEmbeddingsDaemon as defaultEnsureManagedDaemon,
+  tryUseManagedLocalEmbeddingsDaemon as defaultTryUseManagedDaemon,
+} from './managed-local-embeddings.js';
+import type { KtxManagedPythonInstallPolicy } from './managed-python-command.js';
+
+type EmbeddingResolutionMode = 'ensure' | 'use-if-running';
+
+export type EmbeddingProviderResolution =
+  | { kind: 'disabled' }
+  | { kind: 'configured'; provider: KtxEmbeddingProvider; baseUrl: string }
+  | { kind: 'managed-running'; provider: KtxEmbeddingProvider; baseUrl: string }
+  | { kind: 'managed-started'; provider: KtxEmbeddingProvider; baseUrl: string }
+  | { kind: 'managed-unavailable'; reason: string };
+
+export interface ResolveProjectEmbeddingProviderOptions {
+  mode: EmbeddingResolutionMode;
+  cliVersion: string;
+  io: KtxCliIo;
+  /** Required when mode === 'ensure'. */
+  installPolicy?: KtxManagedPythonInstallPolicy;
+  tryUseManagedDaemon?: typeof defaultTryUseManagedDaemon;
+  ensureManagedDaemon?: typeof defaultEnsureManagedDaemon;
+  createKtxEmbeddingProvider?: typeof defaultCreateKtxEmbeddingProvider;
+}
+
+function usesManagedDaemon(embeddings: KtxProjectEmbeddingConfig): boolean {
+  if (embeddings.backend !== 'sentence-transformers') {
+    return false;
+  }
+  const baseUrl = embeddings.sentenceTransformers?.base_url;
+  return baseUrl === undefined || baseUrl === '';
+}
+
+export async function resolveProjectEmbeddingProvider(
+  project: KtxLocalProject,
+  options: ResolveProjectEmbeddingProviderOptions,
+): Promise<EmbeddingProviderResolution> {
+  const embeddings = project.config.ingest.embeddings;
+  if (embeddings.backend === 'none') {
+    return { kind: 'disabled' };
+  }
+  const createProvider = options.createKtxEmbeddingProvider ?? defaultCreateKtxEmbeddingProvider;
+
+  if (!usesManagedDaemon(embeddings)) {
+    const resolved = resolveLocalKtxEmbeddingConfig(embeddings, process.env);
+    if (!resolved) {
+      return { kind: 'managed-unavailable', reason: 'embedding config missing required fields' };
+    }
+    const provider = createProvider(resolved);
+    const baseUrl = embeddings.sentenceTransformers?.base_url ?? '';
+    return { kind: 'configured', provider, baseUrl };
+  }
+
+  const tryUse = options.tryUseManagedDaemon ?? defaultTryUseManagedDaemon;
+  const running = await tryUse({ cliVersion: options.cliVersion, projectDir: project.projectDir });
+
+  if (running) {
+    const provider = buildManagedProvider(embeddings, running.baseUrl, createProvider);
+    return provider
+      ? { kind: 'managed-running', provider, baseUrl: running.baseUrl }
+      : { kind: 'managed-unavailable', reason: 'failed to build embedding provider from running daemon' };
+  }
+
+  if (options.mode === 'use-if-running') {
+    return { kind: 'managed-unavailable', reason: 'managed embeddings daemon is not running' };
+  }
+
+  const ensure = options.ensureManagedDaemon ?? defaultEnsureManagedDaemon;
+  if (!options.installPolicy) {
+    throw new Error("installPolicy is required when mode === 'ensure'");
+  }
+  const daemon = await ensure({
+    cliVersion: options.cliVersion,
+    projectDir: project.projectDir,
+    installPolicy: options.installPolicy,
+    io: options.io,
+  });
+  const provider = buildManagedProvider(embeddings, daemon.baseUrl, createProvider);
+  return provider
+    ? { kind: 'managed-started', provider, baseUrl: daemon.baseUrl }
+    : { kind: 'managed-unavailable', reason: 'failed to build embedding provider after starting daemon' };
+}
+
+function buildManagedProvider(
+  embeddings: KtxProjectEmbeddingConfig,
+  baseUrl: string,
+  createProvider: typeof defaultCreateKtxEmbeddingProvider,
+): KtxEmbeddingProvider | null {
+  const merged: KtxProjectEmbeddingConfig = {
+    ...embeddings,
+    sentenceTransformers: {
+      ...embeddings.sentenceTransformers,
+      base_url: baseUrl,
+      pathPrefix: '',
+    },
+  };
+  const resolved = resolveLocalKtxEmbeddingConfig(merged, process.env);
+  return resolved ? createProvider(resolved) : null;
+}