@iblai/data-layer 1.18.0 → 1.19.0

package/dist/src/features/user-llm-usage/hooks.d.ts

@@ -0,0 +1,43 @@
+import type { LlmUsageMetricsRow, LlmUsageTrace } from '../analytics/types';
+import type { UserLlmCostByModelRow, UserLlmCostByServiceRow, UserLlmSpendPoint, UserLlmUsageMetricsParams, UserLlmUsageObservation, UserLlmUsageObservationsParams, UserLlmUsageQueryState, UserLlmUsageScope, UserLlmUsageSummary, UserLlmUsageTracesParams } from './types';
+export interface UserLlmUsageHookOptions {
+    /** Extra switch on top of the built-in platform-key guard. */
+    skip?: boolean;
+}
+/** Any metrics query. Idle until `platform_key` and `username` are set. */
+export declare function useUserLlmUsageMetrics(params: UserLlmUsageMetricsParams | null | undefined, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<LlmUsageMetricsRow>;
+/** Any traces query. Idle until `platform_key` and `username` are set. */
+export declare function useUserLlmUsageTraces(params: UserLlmUsageTracesParams | null | undefined, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<LlmUsageTrace>;
+/** Any observations query. Idle until `platform_key` and `username` are set. */
+export declare function useUserLlmUsageObservations(params: UserLlmUsageObservationsParams | null | undefined, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<UserLlmUsageObservation>;
+/** Headline totals for the user: `measures=total_cost,total_tokens,count`, summed. */
+export declare function useUserLlmUsageSummary(scope: UserLlmUsageScope, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<LlmUsageMetricsRow> & {
+    summary: UserLlmUsageSummary | null;
+};
+/** The user's spend per time bucket (`granularity=day` unless told otherwise). */
+export declare function useUserLlmSpendOverTime(scope: UserLlmUsageScope & {
+    granularity?: UserLlmUsageMetricsParams['granularity'];
+}, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<LlmUsageMetricsRow> & {
+    points: UserLlmSpendPoint[];
+};
+/** The user's spend and call count per model, most expensive first. */
+export declare function useUserLlmCostByModel(scope: UserLlmUsageScope & {
+    limit?: number;
+}, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<LlmUsageMetricsRow> & {
+    models: UserLlmCostByModelRow[];
+};
+/** The user's spend and call count per service (the trace name: chat, memory, …). */
+export declare function useUserLlmCostByService(scope: UserLlmUsageScope, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<LlmUsageMetricsRow> & {
+    services: UserLlmCostByServiceRow[];
+};
+export declare const USER_LLM_RECENT_ACTIVITY_PAGE_SIZE = 10;
+/** The user's traces, newest first, one page at a time. */
+export declare function useUserLlmRecentActivity(scope: UserLlmUsageScope & {
+    page?: number;
+    limit?: number;
+}, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<LlmUsageTrace>;
+/** The steps (observations) inside one trace. Idle until a trace is picked. */
+export declare function useUserLlmTraceObservations(scope: UserLlmUsageScope & {
+    traceId: string | null | undefined;
+    limit?: number;
+}, options?: UserLlmUsageHookOptions): UserLlmUsageQueryState<UserLlmUsageObservation>;

package/dist/src/features/user-llm-usage/types.d.ts

@@ -0,0 +1,150 @@
+import type { DateFilter, LlmUsageAggregation, LlmUsageGranularity, LlmUsageGroupBy, LlmUsageMeasure, LlmUsageMetricsRow, LlmUsageObservation, LlmUsagePaginationMeta, LlmUsageTrace } from '../analytics/types';
+export type UserLlmUsageResource = 'metrics' | 'traces' | 'observations';
+/**
+ * Services the platform emits traces for. Deployments emit others too
+ * (`rag`, `memory_context`, `guided_prompt_generation`, …), so any string is
+ * accepted while the known names still autocomplete.
+ */
+export type UserLlmUsageTraceName = 'chat' | 'call' | 'memory' | 'grading' | 'moderation' | 'embeddings' | (string & {});
+export type UserLlmUsageDirection = 'asc' | 'desc';
+/** Every range the endpoint knows except `custom`, which needs its own dates. */
+export type UserLlmUsagePresetDateFilter = Exclude<DateFilter, 'custom'>;
+/**
+ * Omitting `date_filter` means **today** upstream. `start_date`/`end_date`
+ * only exist alongside `date_filter: 'custom'`, and then both are required.
+ */
+export type UserLlmUsageDateRange = {
+    date_filter?: UserLlmUsagePresetDateFilter;
+    start_date?: never;
+    end_date?: never;
+} | {
+    date_filter: 'custom';
+    start_date: string;
+    end_date: string;
+};
+interface UserLlmUsageCommonParams {
+    /** Always sent; the backend validates it against the caller's tenancy. */
+    platform_key: string;
+    /**
+     * The user whose usage this is — the profile being viewed, not necessarily
+     * the caller. Required, so a request can never silently widen to the
+     * caller's own scope (which for an admin is the whole platform).
+     */
+    username: string;
+    trace_name?: UserLlmUsageTraceName;
+    llm_model?: string;
+    /** Upstream maximum is {@link USER_LLM_USAGE_MAX_LIMIT}. */
+    limit?: number;
+}
+export type UserLlmUsageMetricsParams = UserLlmUsageCommonParams & UserLlmUsageDateRange & {
+    resource: 'metrics';
+    /** Serialized as a comma-separated list. Upstream default: `total_cost`. */
+    measures?: LlmUsageMeasure[];
+    aggregation?: LlmUsageAggregation;
+    group_by?: LlmUsageGroupBy;
+    /** Turns the result into a time series bucketed by this unit. */
+    granularity?: LlmUsageGranularity;
+    session_id?: string;
+    mentor_unique_id?: string;
+    order_by?: LlmUsageMeasure;
+    direction?: UserLlmUsageDirection;
+};
+export type UserLlmUsageTracesParams = UserLlmUsageCommonParams & UserLlmUsageDateRange & {
+    resource: 'traces';
+    session_id?: string;
+    mentor_unique_id?: string;
+    order_by?: 'timestamp' | 'name' | 'session_id';
+    direction?: UserLlmUsageDirection;
+    page?: number;
+    /** Single-trace lookup; an id the caller cannot see answers 404. */
+    trace_id?: string;
+};
+export type UserLlmUsageObservationsParams = UserLlmUsageCommonParams & UserLlmUsageDateRange & {
+    resource: 'observations';
+    trace_id?: string;
+    observation_id?: string;
+    page?: number;
+    /** Not accepted on observations upstream (400) — scope with `trace_id`. */
+    session_id?: never;
+    /** Not accepted on observations upstream (403/400) — scope with `trace_id`. */
+    mentor_unique_id?: never;
+};
+/** Self-view request params, discriminated by `resource`. No `username`. */
+export type UserLlmUsageParams = UserLlmUsageMetricsParams | UserLlmUsageTracesParams | UserLlmUsageObservationsParams;
+/** Observation rows also carry flattened token counts next to `usage`. */
+export type UserLlmUsageObservation = LlmUsageObservation & {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+    costDetails?: {
+        total?: number;
+        [key: string]: number | undefined;
+    };
+};
+/**
+ * The response envelope, with `data` always a list — single-item lookups
+ * (`trace_id` on traces, `observation_id` on observations) are wrapped. `meta`
+ * is only sent for paginated list pages of traces and observations.
+ */
+export interface UserLlmUsageEnvelope<R extends UserLlmUsageResource, Row> {
+    resource: R;
+    data: Row[];
+    meta?: R extends 'metrics' ? never : LlmUsagePaginationMeta;
+}
+export type UserLlmUsageMetricsResponse = UserLlmUsageEnvelope<'metrics', LlmUsageMetricsRow>;
+export type UserLlmUsageTracesResponse = UserLlmUsageEnvelope<'traces', LlmUsageTrace>;
+export type UserLlmUsageObservationsResponse = UserLlmUsageEnvelope<'observations', UserLlmUsageObservation>;
+/**
+ * What the UI branches on. `forbidden` and `not_found` deliberately carry the
+ * same kind of neutral message whatever the backend said, so the view never
+ * reveals whether another user or tenant exists.
+ */
+export type UserLlmUsageErrorKind = 'forbidden' | 'not_found' | 'unauthorized' | 'unavailable' | 'invalid_params' | 'unknown';
+export interface UserLlmUsageError {
+    kind: UserLlmUsageErrorKind;
+    /** HTTP status (or RTK's string status) when there was a response. */
+    status?: number | string;
+    /** A user-safe English fallback; UIs should prefer their own copy per `kind`. */
+    message: string;
+}
+/** Derived state every usage hook returns. */
+export interface UserLlmUsageQueryState<Row> {
+    rows: Row[];
+    meta?: LlmUsagePaginationMeta;
+    /** True once loaded with nothing to show (`meta.totalItems === 0` or no rows). */
+    isEmpty: boolean;
+    /** True while the platform key or username is missing, so nothing was requested. */
+    isIdle: boolean;
+    isLoading: boolean;
+    isFetching: boolean;
+    error: UserLlmUsageError | null;
+    refetch: () => void;
+}
+/** Shared by the thin wrapper hooks: whose usage, on which tenant and window. */
+export type UserLlmUsageScope = {
+    /** The current platform; hooks stay idle while it is empty. */
+    platformKey: string | null | undefined;
+    /** The profile being viewed; hooks stay idle while it is empty. */
+    username: string | null | undefined;
+} & UserLlmUsageDateRange;
+export interface UserLlmUsageSummary {
+    totalCost: number;
+    totalTokens: number;
+    count: number;
+}
+export interface UserLlmSpendPoint {
+    /** Bucket start as `YYYY-MM-DD`. */
+    date: string;
+    totalCost: number;
+}
+export interface UserLlmCostByModelRow {
+    model: string;
+    totalCost: number;
+    count: number;
+}
+export interface UserLlmCostByServiceRow {
+    service: string;
+    totalCost: number;
+    count: number;
+}
+export {};

package/dist/src/features/user-llm-usage/utils.d.ts

@@ -0,0 +1,35 @@
+import type { UserLlmUsageEnvelope, UserLlmUsageError, UserLlmUsageParams, UserLlmUsageResource } from './types';
+export type UserLlmUsageValidation = {
+    ok: true;
+    params: UserLlmUsageParams;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Runtime twin of the param types, for params assembled dynamically where the
+ * compiler cannot see them. Runs before every request, so an invalid
+ * combination never leaves the browser.
+ */
+export declare function validateUserLlmUsageParams(params: unknown): UserLlmUsageValidation;
+/**
+ * Maps whatever a usage query failed with onto a typed, user-safe error.
+ * The backend's own `detail`/`error` text is never carried over.
+ *
+ * A 401 is reported as `unauthorized` for completeness, but it has already
+ * gone through the app's registered auth handler (token refresh, then the
+ * host's 401 handler) inside the base query before it gets here.
+ */
+export declare function normalizeUserLlmUsageError(error: unknown): UserLlmUsageError | null;
+/**
+ * Wraps the raw response so `data` is always a list. Single-item lookups
+ * (`trace_id`, `observation_id`) come back as one object without `meta`.
+ */
+export declare function toUserLlmUsageEnvelope<R extends UserLlmUsageResource, Row>(raw: unknown, resource: R): UserLlmUsageEnvelope<R, Row>;
+/**
+ * Empty-state rule shared by every usage hook: paginated resources trust
+ * `meta.totalItems`; metrics (and unpaginated lookups) fall back to the rows.
+ */
+export declare function isUserLlmUsageEmpty(envelope: Pick<UserLlmUsageEnvelope<UserLlmUsageResource, unknown>, 'data' | 'meta'> | undefined): boolean;
+/** Reads a numeric measure (`sum_totalCost`, `avg_latency`, …) off a metrics row. */
+export declare function readMeasure(row: Record<string, unknown> | undefined, key: string): number;

package/dist/src/index.d.ts

@@ -139,6 +139,11 @@ export * from './features/watched-groups/types';
 export * from './features/user-chat-history/api-slice';
 export * from './features/user-chat-history/constants';
 export * from './features/user-chat-history/types';
+export * from './features/user-llm-usage/api-slice';
+export * from './features/user-llm-usage/constants';
+export * from './features/user-llm-usage/types';
+export * from './features/user-llm-usage/utils';
+export * from './features/user-llm-usage/hooks';
 export * from './reducers';
 export * from './utils';
 export type { CustomQueryArgs } from './features/utils';