@babav/knowledge-core-client 0.58.0 → 0.60.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;
@@ -686,6 +688,45 @@ export interface CitationArm {
     n_questions: number | null;
     note: string | null;
 }
+/** Per-model cost split within a stage. `actual_usd` is cache-discounted (matches the bill);
+ *  `representative_usd` is the as-if-uncached headline. */
+export interface CostByModel {
+    calls: number;
+    representative_usd: number;
+    actual_usd: number;
+    avg_actual_usd_per_query: number;
+}
+/** Cost of one pipeline stage (generate | rewrite | decompose | multi_query | inspect | citation |
+ *  groundedness | title | embedding | visual_concept | visual_vet | visual_proposer | visual_claims |
+ *  visual_vision_judge), split by model. */
+export interface CostByStage {
+    calls: number;
+    representative_usd: number;
+    actual_usd: number;
+    avg_actual_usd_per_query: number;
+    by_model: Record<string, CostByModel>;
+}
+/** Per-profile cost analytics (GET /v1/query-profiles/{id}/cost). By default reflects the profile's
+ *  CURRENT config only (`config_fingerprint`); `current_config_pending` is true right after a
+ *  cost-impacting change, before any query has run under the new config (so totals are 0 until then).
+ *  `by_stage` covers the whole text + visual pipeline. `breakdown_capped` => the stage/model split was
+ *  computed from the most recent `breakdown_from_n` queries (top-line totals are exact regardless). */
+export interface CostSummary {
+    query_profile_id: string | null;
+    config_fingerprint: string | null;
+    all_configs: boolean;
+    current_config_pending: boolean;
+    since_days: number;
+    price_sheet_version: string;
+    n_queries: number;
+    total_actual_usd: number;
+    total_representative_usd: number;
+    avg_actual_usd_per_query: number;
+    avg_representative_usd_per_query: number;
+    breakdown_from_n: number;
+    breakdown_capped: boolean;
+    by_stage: Record<string, CostByStage>;
+}
 /** 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. */
@@ -1136,6 +1177,16 @@ export declare class KnowledgeCoreClient extends HttpBase {
         }) => Promise<QueryProfile>;
         update: (id: UUID, b: QueryProfileWrite) => Promise<QueryProfile>;
         delete: (id: UUID) => Promise<void>;
+        /** Per-profile COST analytics (GET /v1/query-profiles/{id}/cost): per-query averages + totals,
+         *  broken down by stage and model, over the last `sinceDays` (default 30). By default only the
+         *  profile's CURRENT config is counted (so the numbers reflect the live config; a cost-impacting
+         *  change auto-resets — `current_config_pending` is true until the first query under the new config).
+         *  `allConfigs: true` aggregates every config the profile has run under. `actual_usd` matches the
+         *  provider bill (cache-discounted); `representative_usd` is the as-if-uncached headline. */
+        cost: (id: UUID, opts?: {
+            sinceDays?: number;
+            allConfigs?: boolean;
+        }) => Promise<CostSummary>;
         /** The model catalog for an query-profile-config UI: supported models + default per field, per-model
          *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
         modelOptions: () => Promise<ModelOptions>;

package/dist/index.js

@@ -465,6 +465,13 @@ export class KnowledgeCoreClient extends HttpBase {
         create: (b) => this.request("POST", "/v1/query-profiles", { json: b }),
         update: (id, b) => this.request("PATCH", `/v1/query-profiles/${id}`, { json: b }),
         delete: (id) => this.request("DELETE", `/v1/query-profiles/${id}`),
+        /** Per-profile COST analytics (GET /v1/query-profiles/{id}/cost): per-query averages + totals,
+         *  broken down by stage and model, over the last `sinceDays` (default 30). By default only the
+         *  profile's CURRENT config is counted (so the numbers reflect the live config; a cost-impacting
+         *  change auto-resets — `current_config_pending` is true until the first query under the new config).
+         *  `allConfigs: true` aggregates every config the profile has run under. `actual_usd` matches the
+         *  provider bill (cache-discounted); `representative_usd` is the as-if-uncached headline. */
+        cost: (id, opts) => this.request("GET", `/v1/query-profiles/${id}/cost`, { query: { since_days: opts?.sinceDays, all_configs: opts?.allConfigs } }),
         /** The model catalog for an query-profile-config UI: supported models + default per field, per-model
          *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
         modelOptions: () => this.request("GET", "/v1/query-profiles/model-options"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.58.0",
+  "version": "0.60.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
@@ -651,6 +657,45 @@ export interface CitationArm {
   n_questions: number | null;
   note: string | null;
 }
+/** Per-model cost split within a stage. `actual_usd` is cache-discounted (matches the bill);
+ *  `representative_usd` is the as-if-uncached headline. */
+export interface CostByModel {
+  calls: number;
+  representative_usd: number;
+  actual_usd: number;
+  avg_actual_usd_per_query: number;
+}
+/** Cost of one pipeline stage (generate | rewrite | decompose | multi_query | inspect | citation |
+ *  groundedness | title | embedding | visual_concept | visual_vet | visual_proposer | visual_claims |
+ *  visual_vision_judge), split by model. */
+export interface CostByStage {
+  calls: number;
+  representative_usd: number;
+  actual_usd: number;
+  avg_actual_usd_per_query: number;
+  by_model: Record<string, CostByModel>;
+}
+/** Per-profile cost analytics (GET /v1/query-profiles/{id}/cost). By default reflects the profile's
+ *  CURRENT config only (`config_fingerprint`); `current_config_pending` is true right after a
+ *  cost-impacting change, before any query has run under the new config (so totals are 0 until then).
+ *  `by_stage` covers the whole text + visual pipeline. `breakdown_capped` => the stage/model split was
+ *  computed from the most recent `breakdown_from_n` queries (top-line totals are exact regardless). */
+export interface CostSummary {
+  query_profile_id: string | null;
+  config_fingerprint: string | null;      // null => aggregated across all configs (all_configs=true) or none yet
+  all_configs: boolean;
+  current_config_pending: boolean;
+  since_days: number;
+  price_sheet_version: string;
+  n_queries: number;
+  total_actual_usd: number;
+  total_representative_usd: number;
+  avg_actual_usd_per_query: number;
+  avg_representative_usd_per_query: number;
+  breakdown_from_n: number;
+  breakdown_capped: boolean;
+  by_stage: Record<string, CostByStage>;
+}
 /** 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. */
@@ -1279,6 +1324,15 @@ export class KnowledgeCoreClient extends HttpBase {
     create: (b: QueryProfileWrite & { name: string }) => this.request<QueryProfile>("POST", "/v1/query-profiles", { json: b }),
     update: (id: UUID, b: QueryProfileWrite) => this.request<QueryProfile>("PATCH", `/v1/query-profiles/${id}`, { json: b }),
     delete: (id: UUID) => this.request<void>("DELETE", `/v1/query-profiles/${id}`),
+    /** Per-profile COST analytics (GET /v1/query-profiles/{id}/cost): per-query averages + totals,
+     *  broken down by stage and model, over the last `sinceDays` (default 30). By default only the
+     *  profile's CURRENT config is counted (so the numbers reflect the live config; a cost-impacting
+     *  change auto-resets — `current_config_pending` is true until the first query under the new config).
+     *  `allConfigs: true` aggregates every config the profile has run under. `actual_usd` matches the
+     *  provider bill (cache-discounted); `representative_usd` is the as-if-uncached headline. */
+    cost: (id: UUID, opts?: { sinceDays?: number; allConfigs?: boolean }) =>
+      this.request<CostSummary>("GET", `/v1/query-profiles/${id}/cost`,
+        { query: { since_days: opts?.sinceDays, all_configs: opts?.allConfigs } }),
     /** The model catalog for an query-profile-config UI: supported models + default per field, per-model
      *  capabilities (`supports_reasoning`), and mode↔model dependencies. */
     modelOptions: () => this.request<ModelOptions>("GET", "/v1/query-profiles/model-options"),