@iblai/data-layer 1.13.1 → 1.13.3

package/dist/src/features/analytics/constants.d.ts

@@ -1,10 +1,26 @@
 import { SERVICES } from '../../constants';
-import { DetailedFinancialStatsArgs, FinancialStatsArgs, TranscriptsConversationHeadlineArgs, TranscriptsMessagesArgs, TranscriptsMessagesDetailsArgs } from './types';
+import { TranscriptsConversationHeadlineArgs, TranscriptsMessagesArgs, TranscriptsMessagesDetailsArgs } from './types';
 export declare const ANALYTICS_ENDPOINTS: {
     GET_OVERVIEW_SUMMARY: {
         service: SERVICES;
         path: (org: string, userId: string) => string;
     };
+    GET_TENANT_COST: {
+        service: SERVICES;
+        path: (org: string, userId: string) => string;
+    };
+    GET_AGENT_COST: {
+        service: SERVICES;
+        path: (org: string, userId: string, mentorUniqueId: string) => string;
+    };
+    GET_MODEL_COSTS: {
+        service: SERVICES;
+        path: (org: string, userId: string) => string;
+    };
+    GET_PER_USER_COSTS: {
+        service: SERVICES;
+        path: (org: string, userId: string) => string;
+    };
     GET_CONVERSATION: {
         service: SERVICES;
         path: (org: string, userId: string) => string;
@@ -79,14 +95,6 @@ export declare const NON_AI_ANALYTICS_ENDPOINTS: {
         service: SERVICES;
         path: (platform_key: string, mentor_unique_id?: string, date_filter?: string, start_date?: string, end_date?: string) => string;
     };
-    GET_FINANCIAL_STATS: {
-        service: SERVICES;
-        path: (args: FinancialStatsArgs) => string;
-    };
-    GET_DETAILED_FINANCIAL_STATS: {
-        service: SERVICES;
-        path: (args: DetailedFinancialStatsArgs) => string;
-    };
     GET_TRANSCRIPTS_MESSAGES: {
         service: SERVICES;
         path: (args: TranscriptsMessagesArgs) => string;
@@ -115,9 +123,23 @@ export declare const NON_AI_ANALYTICS_ENDPOINTS: {
         service: SERVICES;
         path: (username: string, platform_key: string, metrics: string, course_id?: string, include_edx_progress?: boolean, program_id?: string) => string;
     };
+    /**
+     * LLM cost/usage analytics (Langfuse proxy; renamed from
+     * `/api/analytics/langfuse/`). One endpoint, three resources — the caller
+     * picks with `resource` and the typed args in `types.ts` keep unsupported
+     * parameter combinations unrepresentable.
+     */
+    GET_LLM_USAGE: {
+        service: SERVICES;
+        path: (resource: "metrics" | "observations" | "traces", args: Record<string, string | number | string[] | undefined>) => string;
+    };
 };
 export declare const ANALYTICS_QUERY_KEYS: {
     GET_OVERVIEW_SUMMARY: () => string[];
+    GET_TENANT_COST: () => string[];
+    GET_AGENT_COST: () => string[];
+    GET_MODEL_COSTS: () => string[];
+    GET_PER_USER_COSTS: () => string[];
     GET_CONVERSATION: () => string[];
     GET_MOST_DISCUSSED_TOPICS: () => string[];
     GET_AVERAGE_MESSAGES_PER_SESSION: () => string[];

package/dist/src/features/analytics/types.d.ts

@@ -69,6 +69,8 @@ export interface TranscriptsMessagesDetailsResponse {
         model: string;
         username: string;
         name: string;
+        /** Preferred over `name`/`username` in the UI; older deployments omit it. */
+        email?: string | null;
         first_user_message: string;
         topics: string[];
         message_count: number;
@@ -102,6 +104,8 @@ export interface TranscriptsMessagesResponse {
         cost: number;
         username: string;
         name: string;
+        /** Preferred over `name`/`username` in the UI; older deployments omit it. */
+        email?: string | null;
         first_user_message: string;
         topics: string[];
         message_count: number;
@@ -327,67 +331,47 @@ export interface UserDetailsStatsResponse {
         end_index: number;
     };
 }
-export interface FinancialStatsArgs {
-    metric: 'total_costs' | 'weekly_costs' | 'monthly_costs';
-    date_filter?: DateFilter;
-    platform_key: string;
-    mentor_unique_id?: string;
-    start_date?: string;
-    end_date?: string;
-    all_time?: 'true';
-    usergroup_ids?: number[];
-}
-export interface FinancialStatsFilters {
+/**
+ * ClickHouse-backed cost analytics (`/api/ai-analytics/.../tenant-cost/`,
+ * `agents/{id}/cost/`, `costs/model/`, `costs/peruser/`). These replace the
+ * deprecated `/api/analytics/financial/` family. Every endpoint takes an
+ * explicit YYYY-MM-DD date range — there is no `date_filter` shorthand and
+ * no period comparison, so deltas are computed client-side from a second
+ * request over the previous window.
+ */
+export interface ClickhouseCostRangeArgs {
+    org: string;
+    /** The requesting admin's username — an `/orgs/{org}/users/{userId}/` path segment. */
+    userId: string;
     start_date: string;
     end_date: string;
-    granularity: string;
-    all_time: boolean;
 }
-export interface FinancialStatsPeriodInfo {
-    start_date: string;
-    end_date: string;
-    period_days: number;
-    range_type: string;
+export interface ClickhouseAgentCostArgs extends ClickhouseCostRangeArgs {
+    mentor_unique_id: string;
 }
-export interface FinancialStatsResponse {
-    metric: string;
-    filters: FinancialStatsFilters;
-    value: number;
-    percentage_change: number | undefined;
-    overtime: Array<{
-        date: string;
-        value: number;
-    }>;
-    period_info: FinancialStatsPeriodInfo;
-    comparison_info: Record<string, any>;
+export interface ClickhouseCostResponse {
+    total_cost: number;
 }
-export interface DetailedFinancialStatsArgs {
-    metric?: string;
-    metrics?: string;
-    group_by: 'llm_model' | 'provider' | 'username';
-    date_filter: DateFilter;
-    platform_key: string;
-    mentor_unique_id?: string;
-    start_date?: string;
-    end_date?: string;
-    page?: number;
-    limit?: number;
-    search?: string;
-    usergroup_ids?: number[];
+export interface ClickhouseModelCost {
+    model: string;
+    total_cost: number;
 }
-export interface DetailedFinancialStatsMetric {
-    name: string;
-    unit: string;
-    description: string;
+export interface ClickhousePerUserCostsArgs extends ClickhouseCostRangeArgs {
+    limit?: number;
+    offset?: number;
 }
-export interface DetailedFinancialStatsResponse {
-    page: number;
-    limit: number;
-    total_pages: number;
-    total_records: number;
-    rows: Record<string, any>[];
+export interface ClickhousePerUserCostRow {
+    username?: string;
+    email?: string;
     total_cost: number;
-    metrics: DetailedFinancialStatsMetric[];
+    /** Not every deployment returns these — render them conditionally. */
+    sessions?: number;
+    last_active?: string;
+}
+export interface ClickhousePerUserCostsResponse {
+    results: ClickhousePerUserCostRow[];
+    /** Total records across all pages, when the backend reports it. */
+    count?: number;
 }
 export interface TimeTrackingRequest {
     timestamp: string;
@@ -696,3 +680,130 @@ export interface LearnerDetailsResponse {
     user: LearnerDetailsUser;
     data: LearnerDetailsData;
 }
+/** Measures the metrics resource can aggregate. */
+export type LlmUsageMeasure = 'total_cost' | 'input_tokens' | 'output_tokens' | 'total_tokens' | 'count' | 'latency';
+export type LlmUsageAggregation = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'p50' | 'p75' | 'p90' | 'p95' | 'p99';
+/** Dimensions Langfuse accepts. Per-mentor ranking rides `tags`; per-user and
+ *  per-session are not supported here by design. */
+export type LlmUsageGroupBy = 'type' | 'model' | 'tags' | 'environment';
+export type LlmUsageGranularity = 'day' | 'week' | 'month';
+interface LlmUsageCommonArgs {
+    platform_key: string;
+    /**
+     * ⚠️ The endpoint's own default is `today`, not all-time. Callers should
+     * always pass an explicit filter so the shared date-range control and this
+     * endpoint never disagree.
+     */
+    date_filter?: DateFilter;
+    start_date?: string;
+    end_date?: string;
+    username?: string;
+    /** Service that produced the trace: `chat`, `call`, `memory`, `grading`, … */
+    trace_name?: string;
+}
+export interface LlmUsageMetricsArgs extends LlmUsageCommonArgs {
+    mentor_unique_id?: string;
+    session_id?: string;
+    llm_model?: string;
+    /** Joined as a comma-separated list. Defaults to `total_cost` upstream. */
+    measures?: LlmUsageMeasure[];
+    aggregation?: LlmUsageAggregation;
+    group_by?: LlmUsageGroupBy;
+    granularity?: LlmUsageGranularity;
+    order_by?: LlmUsageMeasure;
+    direction?: 'asc' | 'desc';
+    limit?: number;
+    view?: 'observations' | 'scores';
+}
+export interface LlmUsageTracesArgs extends LlmUsageCommonArgs {
+    mentor_unique_id?: string;
+    session_id?: string;
+    /** Get-by-id; a cross-tenant id answers 404, never 403. */
+    trace_id?: string;
+    order_by?: 'timestamp' | 'name' | 'username' | 'session_id';
+    direction?: 'asc' | 'desc';
+    page?: number;
+    limit?: number;
+}
+/** No `mentor_unique_id` (upstream 403) and no `session_id` (upstream 400) —
+ *  scope row-level drill-down with `trace_id` instead. */
+export interface LlmUsageObservationsArgs extends LlmUsageCommonArgs {
+    trace_id?: string;
+    observation_id?: string;
+    page?: number;
+    limit?: number;
+}
+/**
+ * A metrics row: the grouped dimension (if any) plus one key per measure named
+ * `{aggregation}_{langfuseMeasure}` (`sum_totalCost`, `p95_latency`, …), and
+ * `time_dimension` when a granularity was requested.
+ */
+export interface LlmUsageMetricsRow {
+    traceName?: string;
+    providedModelName?: string;
+    tags?: string[];
+    environment?: string;
+    time_dimension?: string;
+    [measureKey: string]: string | number | string[] | null | undefined;
+}
+export interface LlmUsageMetricsResponse {
+    resource: 'metrics';
+    data: LlmUsageMetricsRow[];
+}
+export interface LlmUsagePaginationMeta {
+    page: number;
+    limit: number;
+    totalItems: number;
+    totalPages: number;
+}
+export interface LlmUsageTrace {
+    id: string;
+    timestamp: string;
+    name?: string;
+    userId?: string;
+    sessionId?: string;
+    environment?: string;
+    tags?: string[];
+    latency?: number;
+    totalCost?: number;
+    input?: unknown;
+    output?: unknown;
+    metadata?: Record<string, unknown>;
+    observations?: string[];
+    [key: string]: unknown;
+}
+export interface LlmUsageTracesResponse {
+    resource: 'traces';
+    /** A list page, or the single record when `trace_id` was passed. */
+    data: LlmUsageTrace[] | LlmUsageTrace;
+    meta?: LlmUsagePaginationMeta;
+}
+export interface LlmUsageObservation {
+    id: string;
+    traceId?: string;
+    type?: string;
+    name?: string;
+    startTime?: string;
+    endTime?: string;
+    latency?: number;
+    model?: string;
+    providedModelName?: string;
+    usage?: {
+        input?: number;
+        output?: number;
+        total?: number;
+    };
+    usageDetails?: Record<string, number>;
+    calculatedTotalCost?: number;
+    totalCost?: number;
+    input?: unknown;
+    output?: unknown;
+    [key: string]: unknown;
+}
+export interface LlmUsageObservationsResponse {
+    resource: 'observations';
+    /** A list page, or the single record when `observation_id` was passed. */
+    data: LlmUsageObservation[] | LlmUsageObservation;
+    meta?: LlmUsagePaginationMeta;
+}
+export {};