@klhapp/skillmux 1.0.1 → 1.1.0

package/src/cli.ts

@@ -399,10 +399,52 @@ async function handleCalibrateCommand(
 ) {
   if (sub === "run") {
     let datasetPath: string | undefined;
+    let minAutoMatchPrecision: number | undefined;
+    let minRetrievalRecallAtK: number | undefined;
+    let minDeliveredShortlistRecallAtK: number | undefined;
+    let minAutoMatchCount: number | undefined;
+    const readNumber = (flag: string, raw: string | undefined): number => {
+      if (raw === undefined) throw new Error(`${flag} requires a value`);
+      const value = Number(raw);
+      if (!Number.isFinite(value)) throw new Error(`${flag} must be a number`);
+      return value;
+    };
     for (let i = 0; i < args.length; i++) {
-      if (args[i] === "--dataset") datasetPath = args[++i];
+      const option = args[i];
+      if (option === "--dataset") {
+        datasetPath = args[++i];
+        if (!datasetPath) throw new Error("--dataset requires a path value");
+      } else if (option === "--min-auto-match-precision") {
+        minAutoMatchPrecision = readNumber(option, args[++i]);
+      } else if (option === "--min-retrieval-recall-at-k") {
+        minRetrievalRecallAtK = readNumber(option, args[++i]);
+      } else if (option === "--min-delivered-shortlist-recall-at-k") {
+        minDeliveredShortlistRecallAtK = readNumber(option, args[++i]);
+      } else if (option === "--min-auto-match-count") {
+        minAutoMatchCount = readNumber(option, args[++i]);
+        if (!Number.isInteger(minAutoMatchCount) || minAutoMatchCount < 1) {
+          throw new Error("--min-auto-match-count must be a positive integer");
+        }
+      } else {
+        throw new Error(`unknown calibrate run option: ${option}`);
+      }
     }
-    const res = await adapter.calibrateRun({ datasetPath });
+    for (const [flag, value] of [
+      ["--min-auto-match-precision", minAutoMatchPrecision],
+      ["--min-retrieval-recall-at-k", minRetrievalRecallAtK],
+      ["--min-delivered-shortlist-recall-at-k", minDeliveredShortlistRecallAtK],
+    ] as const) {
+      if (value !== undefined && (value < 0 || value > 1)) {
+        throw new Error(`${flag} must be between 0 and 1`);
+      }
+    }
+    const res = await adapter.calibrateRun({
+      datasetPath,
+      minAutoMatchPrecision,
+      minRetrievalRecallAtK,
+      minDeliveredShortlistRecallAtK,
+      minAutoMatchCount,
+    });
     emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
       renderTargetBanner(ctx.target);
       console.log(`Calibration run complete.`);

package/src/clients.ts

@@ -1,13 +1,17 @@
-import type { Clients, Config } from "./types";
+import type { Clients, Config, RemoteRerankerConfig } from "./types";
 import { expandHome } from "./config";
 import type { pipeline as createPipeline } from "@huggingface/transformers";
 
-interface EmbeddingResponse {
-  data: { index: number; embedding: number[] }[];
-}
+export type RemoteErrorKind = "configuration" | "availability" | "protocol";
 
-interface RerankResponse {
-  results: { index: number; relevance_score: number }[];
+export class RemoteInferenceError extends Error {
+  constructor(
+    public readonly kind: RemoteErrorKind,
+    message: string,
+  ) {
+    super(message);
+    this.name = "RemoteInferenceError";
+  }
 }
 
 // Lazy-loaded model instances for in-process ONNX inference
@@ -15,6 +19,220 @@ type FeatureExtractor = Awaited<ReturnType<typeof createPipeline<"feature-extrac
 
 let localEmbedder: FeatureExtractor | null = null;
 
+function authorizationHeaders(
+  apiKeyEnv: string | undefined,
+  configKey: string,
+): Record<string, string> {
+  if (apiKeyEnv === undefined) return {};
+  const apiKey = process.env[apiKeyEnv];
+  if (apiKey === undefined || apiKey === "") {
+    throw new RemoteInferenceError(
+      "configuration",
+      `${configKey} names environment variable "${apiKeyEnv}", but it is unset or empty.`,
+    );
+  }
+  return { authorization: `Bearer ${apiKey}` };
+}
+
+function httpFailure(surface: string, status: number): RemoteInferenceError {
+  const kind: RemoteErrorKind =
+    status === 401 || status === 403
+      ? "configuration"
+      : status === 408 || status === 429 || status >= 500
+        ? "availability"
+        : "protocol";
+  return new RemoteInferenceError(kind, `${surface} returned HTTP ${status}`);
+}
+
+function finiteFloat32(
+  values: unknown[],
+  error: () => Error,
+): Float32Array {
+  const result = new Float32Array(values.length);
+  for (let index = 0; index < values.length; index++) {
+    const value = values[index];
+    if (typeof value !== "number" || !Number.isFinite(value)) throw error();
+    result[index] = value;
+    if (!Number.isFinite(result[index]!)) throw error();
+  }
+  return result;
+}
+
+function parseEmbeddingVectors(
+  value: unknown,
+  inputCount: number,
+  dimension: number,
+): Float32Array[] {
+  const response = value as { data?: unknown };
+  if (
+    typeof response !== "object" ||
+    response === null ||
+    !Array.isArray(response.data) ||
+    response.data.length !== inputCount
+  ) {
+    throw new RemoteInferenceError(
+      "protocol",
+      "embedding endpoint returned an incomplete data array",
+    );
+  }
+
+  const vectors = new Array<Float32Array>(inputCount);
+  const seen = new Set<number>();
+  for (const value of response.data) {
+    const entry = value as { index?: unknown; embedding?: unknown };
+    if (
+      typeof entry !== "object" ||
+      entry === null ||
+      !Number.isInteger(entry.index) ||
+      (entry.index as number) < 0 ||
+      (entry.index as number) >= inputCount ||
+      seen.has(entry.index as number) ||
+      !Array.isArray(entry.embedding) ||
+      entry.embedding.length !== dimension
+    ) {
+      throw new RemoteInferenceError(
+        "protocol",
+        "embedding endpoint returned invalid indexed vectors",
+      );
+    }
+    seen.add(entry.index as number);
+    vectors[entry.index as number] = finiteFloat32(
+      entry.embedding,
+      () => new RemoteInferenceError("protocol", "embedding endpoint returned invalid vector values"),
+    );
+  }
+  return vectors;
+}
+
+export function parseLocalEmbeddingVectors(
+  value: unknown,
+  inputCount: number,
+  dimension: number,
+): Float32Array[] {
+  if (!Array.isArray(value) || value.length !== inputCount) {
+    throw new Error("Embedding model returned an unexpected batch size.");
+  }
+  return value.map((row) => {
+    if (!Array.isArray(row) || row.length !== dimension) {
+      throw new Error("Embedding model returned unexpected vector dimensions.");
+    }
+    return finiteFloat32(
+      row,
+      () => new Error("Embedding model returned invalid vector values."),
+    );
+  });
+}
+
+function rerankerRequestBody(
+  reranker: RemoteRerankerConfig,
+  query: string,
+  docs: { skill_id: string; text: string }[],
+): Record<string, unknown> {
+  if (reranker.adapter === "jina-v1") {
+    return {
+      model: reranker.model,
+      query,
+      documents: docs.map((doc) => doc.text),
+    };
+  }
+  return {
+    model: reranker.model,
+    query,
+    documents: docs.map((doc) => ({
+      text: doc.text,
+      id: doc.skill_id,
+      meta: {},
+    })),
+    top_n: docs.length,
+    return_documents: false,
+  };
+}
+
+function parseRerankerScores(
+  adapter: RemoteRerankerConfig["adapter"],
+  value: unknown,
+  documentCount: number,
+): number[] {
+  const response = value as { results?: unknown };
+  if (
+    typeof response !== "object" ||
+    response === null ||
+    !Array.isArray(response.results) ||
+    response.results.length !== documentCount
+  ) {
+    throw new RemoteInferenceError(
+      "protocol",
+      `reranker adapter "${adapter}" returned an incomplete results array`,
+    );
+  }
+
+  const scores = new Array<number>(documentCount);
+  const seen = new Set<number>();
+  for (const value of response.results) {
+    const result = value as { index?: unknown; relevance_score?: unknown };
+    if (
+      typeof result !== "object" ||
+      result === null ||
+      !Number.isInteger(result.index) ||
+      (result.index as number) < 0 ||
+      (result.index as number) >= documentCount ||
+      seen.has(result.index as number) ||
+      typeof result.relevance_score !== "number" ||
+      !Number.isFinite(result.relevance_score)
+    ) {
+      throw new RemoteInferenceError(
+        "protocol",
+        `reranker adapter "${adapter}" returned invalid indexed scores`,
+      );
+    }
+    seen.add(result.index as number);
+    scores[result.index as number] = result.relevance_score;
+  }
+  return scores;
+}
+
+async function fetchRerankerScores(
+  reranker: RemoteRerankerConfig,
+  timeoutMs: number,
+  query: string,
+  docs: { skill_id: string; text: string }[],
+): Promise<number[]> {
+  if (docs.length === 0) return [];
+
+  let response: Response;
+  try {
+    response = await fetch(reranker.endpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...authorizationHeaders(reranker.api_key_env, "inference.reranker.api_key_env"),
+      },
+      body: JSON.stringify(rerankerRequestBody(reranker, query, docs)),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    if (error instanceof RemoteInferenceError) throw error;
+    throw new RemoteInferenceError(
+      "availability",
+      `reranker adapter "${reranker.adapter}" request failed`,
+    );
+  }
+  if (!response.ok) {
+    throw httpFailure(`reranker adapter "${reranker.adapter}"`, response.status);
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = await response.json();
+  } catch {
+    throw new RemoteInferenceError(
+      "protocol",
+      `reranker adapter "${reranker.adapter}" returned malformed JSON`,
+    );
+  }
+  return parseRerankerScores(reranker.adapter, parsed, docs.length);
+}
+
 function localInference(config: Config) {
   if (config.inference.mode !== "local") throw new Error("Local inference is not configured.");
   return config.inference;
@@ -56,37 +274,45 @@ export function createClients(config: Config): Clients {
         const pipe = await getLocalEmbedder(config);
         const output = await pipe(texts, { pooling: "mean", normalize: true });
         const dim = output.dims[1];
-        if (dim === undefined || output.dims.length !== 2 || output.dims[0] !== texts.length) {
+        if (
+          dim === undefined ||
+          output.dims.length !== 2 ||
+          output.dims[0] !== texts.length ||
+          dim !== config.inference.embedding.dimension
+        ) {
           throw new Error(`Embedding model returned unexpected dimensions: ${output.dims.join("x")}`);
         }
-        const result: Float32Array[] = [];
-        for (let i = 0; i < texts.length; i++) {
-          const row = output.slice(i, null).tolist();
-          if (!Array.isArray(row) || row.some((value) => typeof value !== "number")) {
-            throw new Error("Embedding model returned non-numeric values.");
-          }
-          result.push(Float32Array.from(row));
-        }
-        return result;
+        const rows = Array.from({ length: texts.length }, (_, index) =>
+          output.slice(index, null).tolist(),
+        );
+        return parseLocalEmbeddingVectors(rows, texts.length, dim);
       }
 
       const embedding = config.inference.embedding;
-      const apiKey = embedding.api_key_env ? process.env[embedding.api_key_env] : undefined;
-      const cleanBase = embedding.base_url.replace(/\/$/, "");
-      const embedPath = cleanBase.endsWith("/v1") ? "/embeddings" : "/v1/embeddings";
-      const response = await fetch(`${cleanBase}${embedPath}`, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
-        },
-        body: JSON.stringify({ model: embedding.model, input: texts }),
-        signal: AbortSignal.timeout(config.inference.timeout_ms),
-      });
-      if (!response.ok) throw new Error(`embeddings endpoint returned ${response.status}`);
-      const parsed = (await response.json()) as EmbeddingResponse;
-      const byIndex = [...parsed.data].sort((a, b) => a.index - b.index);
-      return byIndex.map((d) => Float32Array.from(d.embedding));
+      let response: Response;
+      try {
+        response = await fetch(embedding.endpoint, {
+          method: "POST",
+          headers: {
+            "content-type": "application/json",
+            ...authorizationHeaders(embedding.api_key_env, "inference.embedding.api_key_env"),
+          },
+          body: JSON.stringify({ model: embedding.model, input: texts }),
+          signal: AbortSignal.timeout(config.inference.timeout_ms),
+        });
+      } catch (error) {
+        if (error instanceof RemoteInferenceError) throw error;
+        throw new RemoteInferenceError("availability", "embedding endpoint request failed");
+      }
+      if (!response.ok) throw httpFailure("embedding endpoint", response.status);
+
+      let parsed: unknown;
+      try {
+        parsed = await response.json();
+      } catch {
+        throw new RemoteInferenceError("protocol", "embedding endpoint returned malformed JSON");
+      }
+      return parseEmbeddingVectors(parsed, texts.length, embedding.dimension);
     },
   };
   if (config.inference.mode === "remote" && config.inference.reranker) {
@@ -94,22 +320,12 @@ export function createClients(config: Config): Clients {
     clients.rerank = async (query, docs) => {
       const reranker = inference.reranker;
       if (!reranker) throw new Error("Reranker is not configured.");
-      const apiKey = reranker.api_key_env ? process.env[reranker.api_key_env] : undefined;
-      const response = await fetch(`${reranker.base_url.replace(/\/$/, "")}/rerank`, {
-        method: "POST",
-        headers: { "content-type": "application/json", ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}) },
-        body: JSON.stringify({
-          model: reranker.model,
-          query,
-          documents: docs.map((d) => d.text),
-        }),
-        signal: AbortSignal.timeout(inference.timeout_ms),
-      });
-      if (!response.ok) throw new Error(`rerank endpoint returned ${response.status}`);
-      const parsed = (await response.json()) as RerankResponse;
-      const scores = new Array<number>(docs.length).fill(0);
-      for (const result of parsed.results) scores[result.index] = result.relevance_score;
-      return scores;
+      return fetchRerankerScores(
+        reranker,
+        inference.timeout_ms,
+        query,
+        docs,
+      );
     };
   }
   return clients;

package/src/config-service.ts

@@ -44,6 +44,10 @@ export const RESTART_REQUIRED_KEYS = [
   "inference.bundle",
   "inference.models_dir",
   "state_dir",
+  "inference.embedding.model",
+  "inference.embedding.dimension",
+  "inference.embedding.device",
+  "inference.embedding.dtype",
 ];
 
 export const RELOADABLE_KEYS = [
@@ -54,12 +58,13 @@ export const RELOADABLE_KEYS = [
   "thresholds.match_score",
   "thresholds.match_margin",
   "thresholds.candidate_floor",
-  "inference.embedding.model",
-  "inference.embedding.dimension",
-  "inference.embedding.device",
-  "inference.embedding.dtype",
-  "inference.embedding.base_url",
+  "inference.embedding.endpoint",
   "inference.embedding.api_key_env",
+  "inference.reranker.adapter",
+  "inference.reranker.endpoint",
+  "inference.reranker.model",
+  "inference.reranker.api_key_env",
+  "inference.timeout_ms",
   "server.rate_limit.enabled",
   "server.rate_limit.requests_per_minute",
   "server.rate_limit.trust_proxy",
@@ -146,8 +151,12 @@ export async function getEffectiveConfig(configPath?: string): Promise<{
     "inference.embedding.dimension",
     "inference.embedding.device",
     "inference.embedding.dtype",
-    "inference.embedding.base_url",
+    "inference.embedding.endpoint",
     "inference.embedding.api_key_env",
+    "inference.reranker.adapter",
+    "inference.reranker.endpoint",
+    "inference.reranker.model",
+    "inference.reranker.api_key_env",
     "inference.timeout_ms",
     "server.auth_enabled",
     "server.auth_token_env",
@@ -178,8 +187,12 @@ export function isEnvMasked(key: string): boolean {
   if (key === "inference.models_dir" && (process.env.SKILLMUX_MODELS_DIR || process.env.SKILL_ROUTER_MODELS_DIR)) return true;
   if (key === "inference.embedding.device" && process.env.EMBED_DEVICE) return true;
   if (key === "inference.embedding.dtype" && process.env.EMBED_DTYPE) return true;
-  if (key === "inference.embedding.base_url" && (process.env.SKILLMUX_EMBED_BASE_URL || process.env.EMBED_BASE_URL)) return true;
+  if (key === "inference.embedding.endpoint" && (process.env.SKILLMUX_EMBED_ENDPOINT || process.env.EMBED_ENDPOINT)) return true;
   if (key === "inference.embedding.model" && (process.env.SKILLMUX_EMBED_MODEL || process.env.EMBED_MODEL)) return true;
+  if (key === "inference.embedding.dimension" && (process.env.SKILLMUX_EMBED_DIMENSION || process.env.EMBED_DIMENSION)) return true;
+  if (key === "inference.reranker.adapter" && (process.env.SKILLMUX_RERANK_ADAPTER || process.env.RERANK_ADAPTER)) return true;
+  if (key === "inference.reranker.endpoint" && (process.env.SKILLMUX_RERANK_ENDPOINT || process.env.RERANK_ENDPOINT)) return true;
+  if (key === "inference.reranker.model" && (process.env.SKILLMUX_RERANK_MODEL || process.env.RERANK_MODEL)) return true;
   if (key === "server.auth_enabled" && process.env.HTTP_AUTH_ENABLED) return true;
   if (key === "server.auth_token_env" && process.env.HTTP_AUTH_TOKEN_ENV) return true;
   if (key === "server.hostname" && process.env.HTTP_HOSTNAME) return true;
@@ -206,8 +219,12 @@ export function validateDottedKey(key: string): void {
     "inference.embedding.dimension",
     "inference.embedding.device",
     "inference.embedding.dtype",
-    "inference.embedding.base_url",
+    "inference.embedding.endpoint",
     "inference.embedding.api_key_env",
+    "inference.reranker.adapter",
+    "inference.reranker.endpoint",
+    "inference.reranker.model",
+    "inference.reranker.api_key_env",
     "inference.timeout_ms",
     "server.auth_enabled",
     "server.auth_token_env",

package/src/config-watcher.ts

@@ -18,6 +18,13 @@ export const LIVE_RELOAD_KEYS = new Set([
   "recall.k_lexical",
   "recall.k_vector",
   "thresholds.candidate_limit",
+  "inference.embedding.endpoint",
+  "inference.embedding.api_key_env",
+  "inference.reranker.adapter",
+  "inference.reranker.endpoint",
+  "inference.reranker.model",
+  "inference.reranker.api_key_env",
+  "inference.timeout_ms",
 ]);
 
 // ---------------------------------------------------------------------------

package/src/config.ts

@@ -48,14 +48,14 @@ const configSchema = z.object({
       timeout_ms: z.number().int().min(100),
       embedding: z.object({
         provider: z.literal("openai"),
-        base_url: z.url(),
+        endpoint: z.url(),
         model: z.string().min(1),
         dimension: z.number().int().positive(),
         api_key_env: z.string().min(1).optional(),
       }).strict(),
       reranker: z.object({
-        provider: z.literal("infinity"),
-        base_url: z.url(),
+        adapter: z.enum(["jina-v1", "bifrost-v1"]),
+        endpoint: z.url(),
         model: z.string().min(1),
         api_key_env: z.string().min(1).optional(),
       }).strict().optional(),
@@ -133,6 +133,12 @@ export function embeddingFingerprint(config: Config): string {
   return `${implementation}:${inference.embedding.model}:${inference.embedding.dimension}`;
 }
 
+export function rerankerFingerprint(config: Config): string | undefined {
+  const inference = config.inference;
+  if (inference.mode !== "remote" || !inference.reranker) return undefined;
+  return `remote:${inference.reranker.adapter}:${inference.reranker.model}`;
+}
+
 export function expandHome(path: string): string {
   return path.startsWith("~") ? join(homedir(), path.slice(1)) : path;
 }
@@ -183,6 +189,30 @@ export function resolveConfigPath(path?: string): string {
 
 export async function loadConfig(path?: string): Promise<Config> {
   migrateLegacyPaths();
+  const removedRerankerEnv = [
+    "SKILLMUX_RERANK_BASE_URL",
+    "SKILL_ROUTER_RERANK_BASE_URL",
+    "RERANK_BASE_URL",
+  ].find((name) => process.env[name] !== undefined);
+  if (removedRerankerEnv) {
+    throw new Error(
+      `${removedRerankerEnv} is no longer supported. Configure ` +
+        "inference.reranker.endpoint with the complete request URL and " +
+        'inference.reranker.adapter (for example, "jina-v1"). The old client appended /rerank.',
+    );
+  }
+  const removedEmbeddingEnv = [
+    "SKILLMUX_EMBED_BASE_URL",
+    "SKILL_ROUTER_EMBED_BASE_URL",
+    "EMBED_BASE_URL",
+  ].find((name) => process.env[name] !== undefined);
+  if (removedEmbeddingEnv) {
+    throw new Error(
+      `${removedEmbeddingEnv} is no longer supported. Configure ` +
+        "inference.embedding.endpoint with the complete OpenAI-compatible embeddings request URL. " +
+        "The old client appended /v1/embeddings.",
+    );
+  }
   const configPath = resolveConfigPath(path);
   const file = Bun.file(expandHome(configPath));
 
@@ -204,6 +234,27 @@ export async function loadConfig(path?: string): Promise<Config> {
         "Legacy inference config is not supported. Move [embedding], [rerank], and remote_timeout_ms under [inference] using config.remote.example.toml.",
       );
     }
+    const rawReranker = isPlainObject(parsed.inference)
+      ? parsed.inference.reranker
+      : undefined;
+    const rawEmbedding = isPlainObject(parsed.inference)
+      ? parsed.inference.embedding
+      : undefined;
+    if (
+      isPlainObject(rawReranker) &&
+      ("provider" in rawReranker || "base_url" in rawReranker)
+    ) {
+      throw new Error(
+        "inference.reranker.provider and inference.reranker.base_url are no longer supported. " +
+          "Use adapter and the complete endpoint URL instead; the old client appended /rerank.",
+      );
+    }
+    if (isPlainObject(rawEmbedding) && "base_url" in rawEmbedding) {
+      throw new Error(
+        "inference.embedding.base_url is no longer supported. Use inference.embedding.endpoint " +
+          "with the complete OpenAI-compatible embeddings request URL; the old client appended /v1/embeddings.",
+      );
+    }
     if (isPlainObject(parsed.inference) && parsed.inference.mode === "remote") {
       if (!isPlainObject(parsed.inference.embedding)) {
         throw new Error("Remote inference requires an inference.embedding section.");
@@ -258,46 +309,76 @@ export async function loadConfig(path?: string): Promise<Config> {
     if (merged.inference.embedding?.provider !== "openai") {
       throw new Error('Remote inference.embedding.provider must be "openai".');
     }
-    if (merged.inference.reranker && merged.inference.reranker.provider !== "infinity") {
-      throw new Error('Remote inference.reranker.provider must be "infinity".');
-    }
     if (!Number.isInteger(merged.inference.timeout_ms) || merged.inference.timeout_ms < 100) {
       throw new Error("Remote inference.timeout_ms must be an integer of at least 100.");
     }
-    if (!merged.inference.embedding?.base_url || !merged.inference.embedding.model || !merged.inference.embedding.dimension) {
-      throw new Error("Remote inference requires inference.embedding base_url, model, and dimension.");
+    if (!merged.inference.embedding?.endpoint || !merged.inference.embedding.model || !merged.inference.embedding.dimension) {
+      throw new Error("Remote inference requires inference.embedding endpoint, model, and dimension.");
     }
-    if (merged.inference.reranker && (!merged.inference.reranker.base_url || !merged.inference.reranker.model)) {
-      throw new Error("Configured inference.reranker requires base_url and model.");
+    if (merged.inference.reranker && (!merged.inference.reranker.endpoint || !merged.inference.reranker.model)) {
+      throw new Error("Configured inference.reranker requires adapter, endpoint, and model.");
     }
     if (merged.inference.reranker && !merged.inference.thresholds) {
-      throw new Error("Configured inference.reranker requires calibrated inference.thresholds.");
-    }
-    for (const [name, value] of [
-      ["inference.embedding.base_url", merged.inference.embedding.base_url],
-      ...(merged.inference.reranker ? [["inference.reranker.base_url", merged.inference.reranker.base_url] as const] : []),
-    ] as const) {
-      try {
-        const url = new URL(value);
-        if (!['http:', 'https:'].includes(url.protocol)) throw new Error();
-      } catch {
-        throw new Error(`${name} must be an HTTP(S) URL.`);
+      const warningKey = "inference.reranker.without-thresholds";
+      if (!warnedEnv.has(warningKey)) {
+        warnedEnv.add(warningKey);
+        console.error(
+          "skillmux: configured reranker has no calibrated inference.thresholds; " +
+            "routing will remain ambiguous until you run `skillmux calibrate run`.",
+        );
       }
     }
-    const embedUrl = getEnv("SKILLMUX_EMBED_BASE_URL", "EMBED_BASE_URL");
+    const embedEndpoint = getEnv("SKILLMUX_EMBED_ENDPOINT", "EMBED_ENDPOINT");
     const embedModel = getEnv("SKILLMUX_EMBED_MODEL", "EMBED_MODEL");
     const embedDimStr = getEnv("SKILLMUX_EMBED_DIMENSION", "EMBED_DIMENSION");
-    const rerankUrl = getEnv("SKILLMUX_RERANK_BASE_URL", "RERANK_BASE_URL");
+    const rerankEndpoint = getEnv("SKILLMUX_RERANK_ENDPOINT", "RERANK_ENDPOINT");
+    const rerankAdapter = getEnv("SKILLMUX_RERANK_ADAPTER", "RERANK_ADAPTER");
     const rerankModel = getEnv("SKILLMUX_RERANK_MODEL", "RERANK_MODEL");
-    if (embedUrl) merged.inference.embedding.base_url = embedUrl;
+    if (embedEndpoint) merged.inference.embedding.endpoint = embedEndpoint;
     if (embedModel) merged.inference.embedding.model = embedModel;
-    if (rerankUrl && merged.inference.reranker) merged.inference.reranker.base_url = rerankUrl;
+    if (rerankEndpoint && merged.inference.reranker) merged.inference.reranker.endpoint = rerankEndpoint;
+    if (rerankAdapter && merged.inference.reranker) {
+      merged.inference.reranker.adapter = rerankAdapter as "jina-v1" | "bifrost-v1";
+    }
     if (rerankModel && merged.inference.reranker) merged.inference.reranker.model = rerankModel;
     if (embedDimStr) {
       const dimension = Number(embedDimStr);
       if (!Number.isInteger(dimension) || dimension < 1) throw new Error(`Invalid embedding dimension: ${embedDimStr}`);
       merged.inference.embedding.dimension = dimension;
     }
+    for (const [name, value, exactEndpoint] of [
+      ["inference.embedding.endpoint", merged.inference.embedding.endpoint, true],
+      ...(merged.inference.reranker
+        ? [["inference.reranker.endpoint", merged.inference.reranker.endpoint, true] as const]
+        : []),
+    ] as const) {
+      try {
+        const url = new URL(value);
+        if (!["http:", "https:"].includes(url.protocol)) throw new Error();
+        if (exactEndpoint && (url.username || url.password || url.hash)) throw new Error();
+      } catch {
+        throw new Error(
+          exactEndpoint
+            ? `${name} must be an absolute HTTP(S) URL without userinfo or a fragment.`
+            : `${name} must be an HTTP(S) URL.`,
+        );
+      }
+    }
+    for (const [name, apiKeyEnv] of [
+      ["inference.embedding.api_key_env", merged.inference.embedding.api_key_env],
+      ...(merged.inference.reranker
+        ? [["inference.reranker.api_key_env", merged.inference.reranker.api_key_env] as const]
+        : []),
+    ] as const) {
+      if (
+        apiKeyEnv !== undefined &&
+        (process.env[apiKeyEnv] === undefined || process.env[apiKeyEnv] === "")
+      ) {
+        throw new Error(
+          `${name} names environment variable "${apiKeyEnv}", but it is unset or empty.`,
+        );
+      }
+    }
   } else {
     throw new Error(`Invalid inference.mode: ${(merged.inference as { mode?: unknown }).mode}`);
   }