@babav/knowledge-core-client 0.59.0 → 0.60.0

package/dist/index.d.ts

@@ -688,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. */
@@ -1138,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.59.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

@@ -657,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. */
@@ -1285,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"),