@babav/knowledge-core-client 0.57.0 → 0.59.0

package/dist/index.d.ts

@@ -79,6 +79,7 @@ export interface VisualOverrides {
     claims_check_model?: string;
     vision_judge_model?: string;
     image_gen_model?: string;
+    html_advisory_judge?: boolean;
 }
 /** Per-request visual control. Absent => mode resolves from the profile default. All visual
  * PROCESSING is server-side; the client only displays the result. */
@@ -544,6 +545,7 @@ export interface QueryProfile {
     visual_image_gen_model: string | null;
     visual_max_revisions: number | null;
     visual_combine_generation_and_concept: boolean | null;
+    visual_html_advisory_judge: boolean | null;
     concept_model_mode: string | null;
     scoring_status: "no_score" | "queued" | "running" | "scored" | null;
     scoring_progress_done: number | null;
@@ -672,6 +674,28 @@ export interface VisualComparison {
     note: string | null;
     arms: VisualArm[];
 }
+/** One citation configuration measured in the citation benchmark. */
+export interface CitationArm {
+    arm: string;
+    generation_model: string | null;
+    citation_model: string | null;
+    mechanism: string | null;
+    precision: number | null;
+    avg_citations_per_answer: number | null;
+    zero_citation_rate: number | null;
+    avg_cost_per_query_usd: number | null;
+    p50_ms: number | null;
+    n_questions: number | null;
+    note: string | null;
+}
+/** Citation-benchmark leaderboard (GET /v1/benchmark/citations) — per configuration: citation
+ *  precision + yield + cost + latency. Native citations (~1.0 by construction) vs post-hoc (lower
+ *  ceiling); each arm's `mechanism` says which. `arms` empty if no citation benchmark has run. */
+export interface CitationComparison {
+    eval_version: string;
+    note: string | null;
+    arms: CitationArm[];
+}
 export interface Tenant {
     id: UUID;
     name: string;
@@ -1154,6 +1178,14 @@ export declare class KnowledgeCoreClient extends HttpBase {
         visuals: (q?: {
             eval_version?: string;
         }) => Promise<VisualComparison>;
+        /** Citation-benchmark leaderboard — per configuration (arm): citation precision, yield
+         *  (citations/answer, zero-citation rate), cost, latency. NATIVE-citation arms (Anthropic gen)
+         *  score ~1.0 by construction (verbatim inline quotes); POST-HOC arms (non-native gen + an
+         *  attributor) have a much lower ceiling regardless of attributor — see each arm's `mechanism`
+         *  and `note`. Read-only, tenant-anonymous. `arms` empty when no citation benchmark has run. */
+        citations: (q?: {
+            eval_version?: string;
+        }) => Promise<CitationComparison>;
         /** 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

@@ -493,6 +493,12 @@ export class KnowledgeCoreClient extends HttpBase {
          *  vision judge — a Gemini-family concept model (Flash) may be self-flattered, so cross-family arms
          *  (Opus) are the cleaner quality figure (see each arm's `quality_caveat`). */
         visuals: (q) => this.request("GET", "/v1/benchmark/visuals", { query: q }),
+        /** Citation-benchmark leaderboard — per configuration (arm): citation precision, yield
+         *  (citations/answer, zero-citation rate), cost, latency. NATIVE-citation arms (Anthropic gen)
+         *  score ~1.0 by construction (verbatim inline quotes); POST-HOC arms (non-native gen + an
+         *  attributor) have a much lower ceiling regardless of attributor — see each arm's `mechanism`
+         *  and `note`. Read-only, tenant-anonymous. `arms` empty when no citation benchmark has run. */
+        citations: (q) => this.request("GET", "/v1/benchmark/citations", { 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.57.0",
+  "version": "0.59.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

@@ -101,6 +101,7 @@ export interface VisualOverrides {
   claims_check_model?: string;
   vision_judge_model?: string;
   image_gen_model?: string;  // scenic image generator (profile field: visual_image_gen_model)
+  html_advisory_judge?: boolean;  // measure-only vision judge on shipped HTML figures (profile: visual_html_advisory_judge)
 }
 
 /** Per-request visual control. Absent => mode resolves from the profile default. All visual
@@ -511,6 +512,11 @@ export interface QueryProfile {
   visual_image_gen_model: string | null;     // Vertex Gemini image-gen model (scenic register)
   visual_max_revisions: number | null;
   visual_combine_generation_and_concept: boolean | null;
+  // Measure-only vision judge on shipped conceptual (HTML) figures (null => on). When on, every
+  // shipped HTML figure is scored by the vision judge OFF the critical path — it's logged/counted
+  // server-side to reveal how often a figure would be flagged, but NEVER revises or drops it (zero
+  // added latency). A pure quality-telemetry knob; it does not change what the client receives.
+  visual_html_advisory_judge: 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
@@ -637,6 +643,28 @@ export interface VisualComparison {
   note: string | null;
   arms: VisualArm[];
 }
+/** One citation configuration measured in the citation benchmark. */
+export interface CitationArm {
+  arm: string;                               // e.g. "opus_native" | "flash_self" | "flash_opus"
+  generation_model: string | null;
+  citation_model: string | null;            // post-hoc attributor; null/native for Anthropic gen
+  mechanism: string | null;                  // "native" (inline, verbatim) | "posthoc" (attributor pass)
+  precision: number | null;                  // 0..1 — cited source actually supports the claim
+  avg_citations_per_answer: number | null;
+  zero_citation_rate: number | null;         // fraction of answers with no citation
+  avg_cost_per_query_usd: number | null;
+  p50_ms: number | null;
+  n_questions: number | null;
+  note: string | null;
+}
+/** Citation-benchmark leaderboard (GET /v1/benchmark/citations) — per configuration: citation
+ *  precision + yield + cost + latency. Native citations (~1.0 by construction) vs post-hoc (lower
+ *  ceiling); each arm's `mechanism` says which. `arms` empty if no citation benchmark has run. */
+export interface CitationComparison {
+  eval_version: string;
+  note: string | null;
+  arms: CitationArm[];
+}
 
 export interface Tenant {
   id: UUID;
@@ -1290,6 +1318,13 @@ export class KnowledgeCoreClient extends HttpBase {
      *  (Opus) are the cleaner quality figure (see each arm's `quality_caveat`). */
     visuals: (q?: { eval_version?: string }) =>
       this.request<VisualComparison>("GET", "/v1/benchmark/visuals", { query: q }),
+    /** Citation-benchmark leaderboard — per configuration (arm): citation precision, yield
+     *  (citations/answer, zero-citation rate), cost, latency. NATIVE-citation arms (Anthropic gen)
+     *  score ~1.0 by construction (verbatim inline quotes); POST-HOC arms (non-native gen + an
+     *  attributor) have a much lower ceiling regardless of attributor — see each arm's `mechanism`
+     *  and `note`. Read-only, tenant-anonymous. `arms` empty when no citation benchmark has run. */
+    citations: (q?: { eval_version?: string }) =>
+      this.request<CitationComparison>("GET", "/v1/benchmark/citations", { 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. */