@babav/knowledge-core-client 0.24.0 → 0.25.0

package/dist/index.d.ts

@@ -242,6 +242,76 @@ export interface FinalizeResult {
     status: "ingesting" | "failed";
     error?: string;
 }
+export type AnalyticsBand = "frequent" | "occasional" | "rare" | "never" | "insufficient_data";
+export interface UsageSeries {
+    corpus_id: UUID;
+    granularity: string;
+    points: Array<{
+        bucket: string;
+        queries: number;
+    }>;
+}
+export interface DocumentAnalytics {
+    document_id: UUID;
+    filename: string | null;
+    chunks_retrieved: number;
+    chunks_reranked: number;
+    citation_count: number;
+    best_rerank_rank: number | null;
+    best_rerank_score: number | null;
+    exposure_queries: number;
+    retrieved_reach: number;
+    citation_reach: number;
+    conversion: number;
+    band: AnalyticsBand;
+}
+export interface SectionAnalytics {
+    parent_id: UUID;
+    ordinal: number;
+    chunks_retrieved: number;
+    chunks_reranked: number;
+    citation_count: number;
+    best_rerank_score: number | null;
+    band: AnalyticsBand;
+}
+export interface SectionsResponse {
+    document_id: UUID;
+    sections: SectionAnalytics[];
+}
+export interface MonthlyCorpus {
+    corpus_id: UUID;
+    yyyy_mm: string;
+    queries: number;
+    documents_retrieved: number;
+    chunks_retrieved: number;
+    citations: number;
+    revenue_share: number;
+}
+export interface CorpusMonthSlice {
+    corpus_id: UUID;
+    queries: number;
+    documents_retrieved: number;
+    chunks_retrieved: number;
+    citations: number;
+    revenue_share: number;
+}
+export interface MonthTotals {
+    yyyy_mm: string;
+    queries: number;
+    documents_retrieved: number;
+    chunks_retrieved: number;
+    citations: number;
+    unattributed_share: number;
+    corpora: CorpusMonthSlice[];
+}
+export interface RetrievalEventRow {
+    id: UUID;
+    created_at: string;
+    corpus_ids: UUID[];
+    pool_size: number;
+    message_id: UUID | null;
+    documents: Array<Record<string, unknown>>;
+}
 export interface Conversation {
     id: UUID;
     title: string | null;
@@ -685,6 +755,48 @@ export declare class KnowledgeCoreClient extends HttpBase {
         listAll: () => Promise<Agent[]>;
         get: (id: UUID) => Promise<Agent>;
     };
+    analytics: {
+        /** Query-volume time series for a corpus (the denominator for everything). */
+        corpusUsage: (corpusId: UUID, q?: {
+            from?: string;
+            to?: string;
+            granularity?: "day" | "week" | "month";
+        }) => Promise<UsageSeries>;
+        /** Per-document analytics for a corpus (feeds the document list + the quadrant scatter). */
+        corpusDocuments: (corpusId: UUID, q?: {
+            sort?: "citations" | "reranked" | "retrieved" | "best_score";
+            limit?: number;
+            cursor?: string;
+            from?: string;
+            to?: string;
+        }) => Promise<{
+            items: DocumentAnalytics[];
+            next_cursor: string | null;
+        }>;
+        /** One document's lifetime rollup (headline reach is CITATION reach). */
+        document: (documentId: UUID) => Promise<DocumentAnalytics>;
+        /** Parent-section grain for a document (never exposes chunk ids). */
+        documentSections: (documentId: UUID) => Promise<SectionsResponse>;
+        /** A corpus's monthly metrics + revenue_share (YYYY-MM). */
+        corpusMonthly: (corpusId: UUID, yyyyMm: string) => Promise<MonthlyCorpus>;
+        /** Cross-corpus monthly totals + per-corpus breakdown + unattributed share (YYYY-MM). */
+        month: (yyyyMm: string) => Promise<MonthTotals>;
+        /** Raw immutable events + document rollups (escape hatch for custom formulas). */
+        events: (q?: {
+            from?: string;
+            to?: string;
+            limit?: number;
+            cursor?: string;
+        }) => Promise<{
+            items: RetrievalEventRow[];
+            next_cursor: string | null;
+        }>;
+        /** Flush pending events into the read tables NOW (idempotent; read-your-writes). The Cloud
+         *  Scheduler drain is the authoritative periodic driver — this is a convenience trigger. */
+        drain: () => Promise<{
+            processed: number;
+        }>;
+    };
 }
 export declare class AdminClient extends HttpBase {
     /** @param opts.apiKey the ADMIN key, supplied by the caller. */

package/dist/index.js

@@ -410,6 +410,26 @@ export class KnowledgeCoreClient extends HttpBase {
         listAll: () => this.pageAll("/v1/agents"),
         get: (id) => this.request("GET", `/v1/agents/${id}`),
     };
+    // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
+    analytics = {
+        /** Query-volume time series for a corpus (the denominator for everything). */
+        corpusUsage: (corpusId, q) => this.request("GET", `/v1/analytics/corpora/${corpusId}/usage`, { query: q }),
+        /** Per-document analytics for a corpus (feeds the document list + the quadrant scatter). */
+        corpusDocuments: (corpusId, q) => this.request("GET", `/v1/analytics/corpora/${corpusId}/documents`, { query: q }),
+        /** One document's lifetime rollup (headline reach is CITATION reach). */
+        document: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}`),
+        /** Parent-section grain for a document (never exposes chunk ids). */
+        documentSections: (documentId) => this.request("GET", `/v1/analytics/documents/${documentId}/sections`),
+        /** A corpus's monthly metrics + revenue_share (YYYY-MM). */
+        corpusMonthly: (corpusId, yyyyMm) => this.request("GET", `/v1/analytics/corpora/${corpusId}/monthly/${yyyyMm}`),
+        /** Cross-corpus monthly totals + per-corpus breakdown + unattributed share (YYYY-MM). */
+        month: (yyyyMm) => this.request("GET", `/v1/analytics/months/${yyyyMm}`),
+        /** Raw immutable events + document rollups (escape hatch for custom formulas). */
+        events: (q) => this.request("GET", "/v1/analytics/events", { query: q }),
+        /** Flush pending events into the read tables NOW (idempotent; read-your-writes). The Cloud
+         *  Scheduler drain is the authoritative periodic driver — this is a convenience trigger. */
+        drain: () => this.request("POST", "/v1/analytics/drain"),
+    };
 }
 // ---------------------------------------------------------------------------
 // Admin client (tenant + key + agent management) — use the ADMIN key

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.24.0",
+  "version": "0.25.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

@@ -258,6 +258,41 @@ export interface FinalizeResult {
   status: "ingesting" | "failed";
   error?: string;
 }
+// --- retrieval analytics ---
+export type AnalyticsBand = "frequent" | "occasional" | "rare" | "never" | "insufficient_data";
+export interface UsageSeries {
+  corpus_id: UUID;
+  granularity: string;
+  points: Array<{ bucket: string; queries: number }>;
+}
+export interface DocumentAnalytics {
+  document_id: UUID; filename: string | null;
+  chunks_retrieved: number; chunks_reranked: number; citation_count: number;
+  best_rerank_rank: number | null; best_rerank_score: number | null;
+  exposure_queries: number; retrieved_reach: number; citation_reach: number;
+  conversion: number; band: AnalyticsBand;
+}
+export interface SectionAnalytics {
+  parent_id: UUID; ordinal: number; chunks_retrieved: number; chunks_reranked: number;
+  citation_count: number; best_rerank_score: number | null; band: AnalyticsBand;
+}
+export interface SectionsResponse { document_id: UUID; sections: SectionAnalytics[] }
+export interface MonthlyCorpus {
+  corpus_id: UUID; yyyy_mm: string; queries: number; documents_retrieved: number;
+  chunks_retrieved: number; citations: number; revenue_share: number;
+}
+export interface CorpusMonthSlice {
+  corpus_id: UUID; queries: number; documents_retrieved: number;
+  chunks_retrieved: number; citations: number; revenue_share: number;
+}
+export interface MonthTotals {
+  yyyy_mm: string; queries: number; documents_retrieved: number; chunks_retrieved: number;
+  citations: number; unattributed_share: number; corpora: CorpusMonthSlice[];
+}
+export interface RetrievalEventRow {
+  id: UUID; created_at: string; corpus_ids: UUID[]; pool_size: number;
+  message_id: UUID | null; documents: Array<Record<string, unknown>>;
+}
 export interface Conversation {
   id: UUID;
   title: string | null;
@@ -863,6 +898,30 @@ export class KnowledgeCoreClient extends HttpBase {
     listAll: () => this.pageAll<Agent>("/v1/agents"),
     get: (id: UUID) => this.request<Agent>("GET", `/v1/agents/${id}`),
   };
+
+  // --- retrieval analytics (read-only, tenant-scoped, aggregate-on-read) ---
+  analytics = {
+    /** Query-volume time series for a corpus (the denominator for everything). */
+    corpusUsage: (corpusId: UUID, q?: { from?: string; to?: string; granularity?: "day" | "week" | "month" }) =>
+      this.request<UsageSeries>("GET", `/v1/analytics/corpora/${corpusId}/usage`, { query: q }),
+    /** Per-document analytics for a corpus (feeds the document list + the quadrant scatter). */
+    corpusDocuments: (corpusId: UUID, q?: { sort?: "citations" | "reranked" | "retrieved" | "best_score"; limit?: number; cursor?: string; from?: string; to?: string }) =>
+      this.request<{ items: DocumentAnalytics[]; next_cursor: string | null }>("GET", `/v1/analytics/corpora/${corpusId}/documents`, { query: q }),
+    /** One document's lifetime rollup (headline reach is CITATION reach). */
+    document: (documentId: UUID) => this.request<DocumentAnalytics>("GET", `/v1/analytics/documents/${documentId}`),
+    /** Parent-section grain for a document (never exposes chunk ids). */
+    documentSections: (documentId: UUID) => this.request<SectionsResponse>("GET", `/v1/analytics/documents/${documentId}/sections`),
+    /** A corpus's monthly metrics + revenue_share (YYYY-MM). */
+    corpusMonthly: (corpusId: UUID, yyyyMm: string) => this.request<MonthlyCorpus>("GET", `/v1/analytics/corpora/${corpusId}/monthly/${yyyyMm}`),
+    /** Cross-corpus monthly totals + per-corpus breakdown + unattributed share (YYYY-MM). */
+    month: (yyyyMm: string) => this.request<MonthTotals>("GET", `/v1/analytics/months/${yyyyMm}`),
+    /** Raw immutable events + document rollups (escape hatch for custom formulas). */
+    events: (q?: { from?: string; to?: string; limit?: number; cursor?: string }) =>
+      this.request<{ items: RetrievalEventRow[]; next_cursor: string | null }>("GET", "/v1/analytics/events", { query: q }),
+    /** Flush pending events into the read tables NOW (idempotent; read-your-writes). The Cloud
+     *  Scheduler drain is the authoritative periodic driver — this is a convenience trigger. */
+    drain: () => this.request<{ processed: number }>("POST", "/v1/analytics/drain"),
+  };
 }
 
 // ---------------------------------------------------------------------------