@babav/knowledge-core-client 0.48.0 → 0.50.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,12 +540,18 @@ 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
@@ -605,6 +612,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;
@@ -1057,25 +1087,29 @@ export declare class KnowledgeCoreClient extends HttpBase {
             eval_version?: string;
         }) => Promise<QueryProfile>;
     };
-    /** Query-profile benchmark leaderboards — top-N system-swept profiles per eval version, per tier
-     *  (client_quick | screening | full) and per category (quality | quality_cost | quality_latency).
-     *  Tenant-anonymous (keyed by config hash); never a customer config. */
+    /** Query-profile benchmark leaderboard — top-N FULL-eval-set-scored profiles per eval version, per
+     *  category (quality | quality_cost | quality_latency). One tier only (the full eval-set); every row
+     *  is a full score. Tenant-anonymous (keyed by config hash); never a customer config. */
     benchmark: {
         leaderboard: (q?: {
             eval_version?: string;
-            tier?: BenchmarkTier;
             category?: BenchmarkCategory;
             limit?: number;
         }) => Promise<Leaderboard>;
-        /** Kick the NSGA-II sweep as the BENCHMARK TENANT (this client's own key — no admin key). The
-         *  benchmark tenant owns the bench corpora + eval-set; the sweep exercises candidate configs and
-         *  populates the leaderboards. Runs in the background — returns 202 immediately. */
+        /** 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. */
         sweep: (b?: {
-            scale?: "full" | "scoped";
             concurrency?: number;
         }) => Promise<{
             status: string;
-            scale: string;
             concurrency: number | null;
         }>;
     };

package/dist/index.js

@@ -477,14 +477,19 @@ export class KnowledgeCoreClient extends HttpBase {
          *  defaults to the current one. Pair with `benchmark.leaderboard` (pick a row -> its config_hash). */
         createFromLeaderboard: (b) => this.request("POST", "/v1/query-profiles/from-leaderboard", { json: b }),
     };
-    /** Query-profile benchmark leaderboards — top-N system-swept profiles per eval version, per tier
-     *  (client_quick | screening | full) and per category (quality | quality_cost | quality_latency).
-     *  Tenant-anonymous (keyed by config hash); never a customer config. */
+    /** Query-profile benchmark leaderboard — top-N FULL-eval-set-scored profiles per eval version, per
+     *  category (quality | quality_cost | quality_latency). One tier only (the full eval-set); every row
+     *  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 }),
-        /** Kick the NSGA-II sweep as the BENCHMARK TENANT (this client's own key — no admin key). The
-         *  benchmark tenant owns the bench corpora + eval-set; the sweep exercises candidate configs and
-         *  populates the leaderboards. Runs in the background — returns 202 immediately. */
+        /** 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. */
         sweep: (b) => this.request("POST", "/v1/benchmark/sweep", { query: b }),
     };
     /** Ingestion profiles — the build-side config object (counterpart to query profiles): a tenant-owned,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.48.0",
+  "version": "0.50.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,13 +507,24 @@ 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);
@@ -563,6 +575,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;
@@ -1193,17 +1230,23 @@ export class KnowledgeCoreClient extends HttpBase {
       this.request<QueryProfile>("POST", "/v1/query-profiles/from-leaderboard", { json: b }),
   };
 
-  /** Query-profile benchmark leaderboards — top-N system-swept profiles per eval version, per tier
-   *  (client_quick | screening | full) and per category (quality | quality_cost | quality_latency).
-   *  Tenant-anonymous (keyed by config hash); never a customer config. */
+  /** Query-profile benchmark leaderboard — top-N FULL-eval-set-scored profiles per eval version, per
+   *  category (quality | quality_cost | quality_latency). One tier only (the full eval-set); every row
+   *  is a full score. Tenant-anonymous (keyed by config hash); never a customer config. */
   benchmark = {
-    leaderboard: (q?: { eval_version?: string; tier?: BenchmarkTier; category?: BenchmarkCategory; limit?: number }) =>
+    leaderboard: (q?: { eval_version?: string; category?: BenchmarkCategory; limit?: number }) =>
       this.request<Leaderboard>("GET", "/v1/benchmark/leaderboard", { query: q }),
-    /** Kick the NSGA-II sweep as the BENCHMARK TENANT (this client's own key — no admin key). The
-     *  benchmark tenant owns the bench corpora + eval-set; the sweep exercises candidate configs and
-     *  populates the leaderboards. Runs in the background — returns 202 immediately. */
-    sweep: (b?: { scale?: "full" | "scoped"; concurrency?: number }) =>
-      this.request<{ status: string; scale: string; concurrency: number | null }>(
+    /** 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. */
+    sweep: (b?: { concurrency?: number }) =>
+      this.request<{ status: string; concurrency: number | null }>(
         "POST", "/v1/benchmark/sweep", { query: b }),
   };