@babav/knowledge-core-client 0.49.0 → 0.51.0

package/dist/index.d.ts

@@ -520,6 +520,7 @@ export interface QueryProfile {
     top_k_reranked_chunks: number | null;
     sibling_window: number | null;
     rerank_instruction: string | null;
+    reranker_provider: string | null;
     max_subqueries: number | null;
     max_reasoning_rounds: number | null;
     decomposition_model: string | null;
@@ -539,16 +540,23 @@ export interface QueryProfile {
     visual_max_revisions: number | null;
     visual_combine_generation_and_concept: boolean | null;
     concept_model_mode: string | null;
+    scoring_status: "unscored" | "queued" | "running" | "scored" | "failed" | "stale" | null;
+    scoring_progress_done: number | null;
+    scoring_progress_total: number | null;
+    scoring_updated_at: string | null;
+    score_composite_q: number | null;
+    score_scored_at: string | null;
 }
 /** Fields settable when creating/updating a query profile. All optional except `name` on create
  *  (null/omit => server default); model fields must be one of
  *  `profiles.modelOptions().fields[field].supported`. The owning tenant is the caller's key —
- *  it is never part of the body. */
-export type QueryProfileWrite = Partial<Omit<QueryProfile, "id" | "tenant_id">>;
+ *  it is never part of the body. The score-my-profile status/score fields are read-only (server-set). */
+export type QueryProfileWrite = Partial<Omit<QueryProfile, "id" | "tenant_id" | "scoring_status" | "scoring_progress_done" | "scoring_progress_total" | "scoring_updated_at" | "score_composite_q" | "score_scored_at">>;
 /** Model catalog for the query-profile-config UI (GET /v1/query-profiles/model-options). `models` maps id → its
  *  capabilities; `fields` gives each profile model-field its supported ids + default (+ usage metadata);
  *  `modes` says which model field governs each mode (reasoning is valid only if that model's
- *  supports_reasoning is true). KC provides the data; the UI decides presentation. */
+ *  supports_reasoning is true); `rerankers` gives the supported values for a profile's `reranker_provider`
+ *  field + the system default. KC provides the data; the UI decides presentation. */
 export interface ModelOptions {
     models: Record<string, {
         label: string;
@@ -567,6 +575,11 @@ export interface ModelOptions {
         depends_on: string;
         values: string[];
     }>;
+    /** Supported `reranker_provider` values (null on a profile => system default). */
+    rerankers: {
+        supported: string[];
+        default: string;
+    };
 }
 export type BenchmarkTier = "client_quick" | "screening" | "full";
 export type BenchmarkCategory = "quality" | "quality_cost" | "quality_latency";
@@ -605,6 +618,29 @@ export interface Leaderboard {
     category: BenchmarkCategory;
     entries: LeaderboardEntry[];
 }
+/** One reranker measured on a head. `contextual` is the self-hosted GPU baseline (delta 0); each other
+ *  provider was measured varying ONLY reranker_provider on the same head + same full-150 eval-set.
+ *  p50_ms/p95_ms/cost are that cell's measured end-to-end query figures. */
+export interface RerankerCell {
+    provider: string;
+    composite_q: number | null;
+    delta_vs_contextual: number | null;
+    p50_ms: number | null;
+    p95_ms: number | null;
+    prod_cost_per_query_usd: number | null;
+}
+/** A head = the top query profile of one generation model; `cells` = [contextual, ...tested rerankers]. */
+export interface RerankerHead {
+    generation_model: string;
+    config_hash: string;
+    cells: RerankerCell[];
+}
+/** Reranker comparison matrix (GET /v1/benchmark/rerankers) — system-level R&D result: per head,
+ *  contextual vs each tested non-GPU reranker. `heads` is empty if no reranker benchmark has run. */
+export interface RerankerComparison {
+    eval_version: string;
+    heads: RerankerHead[];
+}
 export interface Tenant {
     id: UUID;
     name: string;
@@ -1066,6 +1102,13 @@ export declare class KnowledgeCoreClient extends HttpBase {
             category?: BenchmarkCategory;
             limit?: number;
         }) => Promise<Leaderboard>;
+        /** Reranker comparison matrix — per head (the top query profile of each benchmarked generation
+         *  model), the self-hosted contextual GPU reranker vs each tested non-GPU reranker (Voyage, …),
+         *  with quality (full-150 composite_q + delta) and measured end-to-end latency/cost. Read-only,
+         *  tenant-anonymous. `heads` is empty when no reranker benchmark has run for the eval version. */
+        rerankers: (q?: {
+            eval_version?: string;
+        }) => Promise<RerankerComparison>;
         /** Kick the sweep as the BENCHMARK TENANT (this client's own key — no admin key). The benchmark
          *  tenant owns the bench corpora + eval-set; the sweep FULL-scores the sensible config set and
          *  populates the leaderboard. Runs in the background — returns 202 immediately. */

package/dist/index.js

@@ -482,6 +482,11 @@ export class KnowledgeCoreClient extends HttpBase {
      *  is a full score. Tenant-anonymous (keyed by config hash); never a customer config. */
     benchmark = {
         leaderboard: (q) => this.request("GET", "/v1/benchmark/leaderboard", { query: q }),
+        /** Reranker comparison matrix — per head (the top query profile of each benchmarked generation
+         *  model), the self-hosted contextual GPU reranker vs each tested non-GPU reranker (Voyage, …),
+         *  with quality (full-150 composite_q + delta) and measured end-to-end latency/cost. Read-only,
+         *  tenant-anonymous. `heads` is empty when no reranker benchmark has run for the eval version. */
+        rerankers: (q) => this.request("GET", "/v1/benchmark/rerankers", { query: q }),
         /** Kick the sweep as the BENCHMARK TENANT (this client's own key — no admin key). The benchmark
          *  tenant owns the bench corpora + eval-set; the sweep FULL-scores the sensible config set and
          *  populates the leaderboard. Runs in the background — returns 202 immediately. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.49.0",
+  "version": "0.51.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps). Includes the babav.visual grammar TYPES at the ./visual subpath (types only; all visual rendering is server-side).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -486,6 +486,7 @@ export interface QueryProfile {
   top_k_reranked_chunks: number | null;
   sibling_window: number | null;
   rerank_instruction: string | null;
+  reranker_provider: string | null;  // contextual | voyage | cohere | none (null => system default = contextual)
   max_subqueries: number | null;
   max_reasoning_rounds: number | null;
   decomposition_model: string | null;
@@ -506,22 +507,36 @@ export interface QueryProfile {
   visual_max_revisions: number | null;
   visual_combine_generation_and_concept: boolean | null;
   concept_model_mode: string | null;         // "reasoning" | "standard"; overrules gen mode when combining
+  // --- score-my-profile status/progress (READ-only; not settable) ---------------------------------
+  // Durable on the profile so a client can kick scoring, leave, and see the status/result on any later
+  // read. score_composite_q/score_scored_at are the cached score for the CURRENT eval version.
+  scoring_status: "unscored" | "queued" | "running" | "scored" | "failed" | "stale" | null;
+  scoring_progress_done: number | null;
+  scoring_progress_total: number | null;
+  scoring_updated_at: string | null;         // ISO timestamp; heartbeat while running
+  score_composite_q: number | null;
+  score_scored_at: string | null;
 }
 
 /** Fields settable when creating/updating a query profile. All optional except `name` on create
  *  (null/omit => server default); model fields must be one of
  *  `profiles.modelOptions().fields[field].supported`. The owning tenant is the caller's key —
- *  it is never part of the body. */
-export type QueryProfileWrite = Partial<Omit<QueryProfile, "id" | "tenant_id">>;
+ *  it is never part of the body. The score-my-profile status/score fields are read-only (server-set). */
+export type QueryProfileWrite = Partial<Omit<QueryProfile,
+  "id" | "tenant_id" | "scoring_status" | "scoring_progress_done" | "scoring_progress_total"
+  | "scoring_updated_at" | "score_composite_q" | "score_scored_at">>;
 
 /** Model catalog for the query-profile-config UI (GET /v1/query-profiles/model-options). `models` maps id → its
  *  capabilities; `fields` gives each profile model-field its supported ids + default (+ usage metadata);
  *  `modes` says which model field governs each mode (reasoning is valid only if that model's
- *  supports_reasoning is true). KC provides the data; the UI decides presentation. */
+ *  supports_reasoning is true); `rerankers` gives the supported values for a profile's `reranker_provider`
+ *  field + the system default. KC provides the data; the UI decides presentation. */
 export interface ModelOptions {
   models: Record<string, { label: string; provider: "anthropic" | "vertex" | "moonshot"; kind: "text" | "vision"; supports_reasoning: boolean }>;
   fields: Record<string, { supported: string[]; default: string; applies_when?: string; applies_to?: string[]; note?: string }>;
   modes: Record<string, { depends_on: string; values: string[] }>;
+  /** Supported `reranker_provider` values (null on a profile => system default). */
+  rerankers: { supported: string[]; default: string };
 }
 
 // ---- benchmark (score-my-profile + leaderboards) --------------------------
@@ -563,6 +578,31 @@ export interface Leaderboard {
   category: BenchmarkCategory;
   entries: LeaderboardEntry[];
 }
+
+/** One reranker measured on a head. `contextual` is the self-hosted GPU baseline (delta 0); each other
+ *  provider was measured varying ONLY reranker_provider on the same head + same full-150 eval-set.
+ *  p50_ms/p95_ms/cost are that cell's measured end-to-end query figures. */
+export interface RerankerCell {
+  provider: string;                          // contextual | voyage | cohere | ...
+  composite_q: number | null;
+  delta_vs_contextual: number | null;
+  p50_ms: number | null;
+  p95_ms: number | null;
+  prod_cost_per_query_usd: number | null;
+}
+/** A head = the top query profile of one generation model; `cells` = [contextual, ...tested rerankers]. */
+export interface RerankerHead {
+  generation_model: string;
+  config_hash: string;
+  cells: RerankerCell[];
+}
+/** Reranker comparison matrix (GET /v1/benchmark/rerankers) — system-level R&D result: per head,
+ *  contextual vs each tested non-GPU reranker. `heads` is empty if no reranker benchmark has run. */
+export interface RerankerComparison {
+  eval_version: string;
+  heads: RerankerHead[];
+}
+
 export interface Tenant {
   id: UUID;
   name: string;
@@ -1199,6 +1239,12 @@ export class KnowledgeCoreClient extends HttpBase {
   benchmark = {
     leaderboard: (q?: { eval_version?: string; category?: BenchmarkCategory; limit?: number }) =>
       this.request<Leaderboard>("GET", "/v1/benchmark/leaderboard", { query: q }),
+    /** Reranker comparison matrix — per head (the top query profile of each benchmarked generation
+     *  model), the self-hosted contextual GPU reranker vs each tested non-GPU reranker (Voyage, …),
+     *  with quality (full-150 composite_q + delta) and measured end-to-end latency/cost. Read-only,
+     *  tenant-anonymous. `heads` is empty when no reranker benchmark has run for the eval version. */
+    rerankers: (q?: { eval_version?: string }) =>
+      this.request<RerankerComparison>("GET", "/v1/benchmark/rerankers", { query: q }),
     /** Kick the sweep as the BENCHMARK TENANT (this client's own key — no admin key). The benchmark
      *  tenant owns the bench corpora + eval-set; the sweep FULL-scores the sensible config set and
      *  populates the leaderboard. Runs in the background — returns 202 immediately. */