@iblai/iblai-api 4.6.2-dev1-ai-plus → 4.6.2-dev2-ai

package/src/services/AnalyticsService.ts

@@ -0,0 +1,314 @@
+/* generated using openapi-typescript-codegen -- do not edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+import type { BaseFinanceResponse } from '../models/BaseFinanceResponse';
+import type { FinanceDetailsResponse } from '../models/FinanceDetailsResponse';
+import type { CancelablePromise } from '../core/CancelablePromise';
+import { OpenAPI } from '../core/OpenAPI';
+import { request as __request } from '../core/request';
+export class AnalyticsService {
+    /**
+     * Financial Analytics API - Get comprehensive cost metrics with comparison analysis.
+     *
+     * This endpoint provides period-based cost analysis (not cumulative) with support for:
+     * - Multiple time granularities and metrics
+     * - Cross-dimensional filtering
+     * - Percentage change vs comparison periods
+     * - Forward-filled time series
+     *
+     * **Examples:**
+     *
+     * **Basic Weekly Costs:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=weekly_costs&comparison_days=10
+     * ```
+     *
+     * **Platform & Mentor Filtered:**
+     * ```
+     * # Get total costs for a specific platform and mentor
+     * GET /api/v2/analytics/financial/?metric=total_costs&platform_key=web-app&mentor_unique_id=mentor-123&comparison_days=14
+     * ```
+     *
+     * **Monthly Costs by Provider:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=monthly_costs&provider=openai&granularity=month&comparison_days=30
+     * ```
+     *
+     * **Daily Costs for Specific User:**
+     * ```
+     * GET /api/v2/analytics/financial/?metric=total_costs&username=user-456&granularity=day&start_date=2025-01-15&end_date=2025-01-21&comparison_days=7
+     * ```
+     *
+     *
+     * **Response Structure:**
+     * ```json
+     * {
+         * "metric": "weekly_costs",
+         * "value": 12.47,
+         * "percentage_change": 8.5,
+         * "overtime": [
+             * {"date": "2025-01-06", "value": 2.89},
+             * {"date": "2025-01-13", "value": 3.12}
+             * ],
+             * "period_info": {
+                 * "start_date": "2025-01-01",
+                 * "end_date": "2025-01-31",
+                 * "period_days": 31
+                 * },
+                 * "comparison_info": {
+                     * "previous_period_value": 11.50,
+                     * ...
+                     * }
+                     * }
+                     * ```
+                     * @returns BaseFinanceResponse Successful financial metrics response with period-based cost data
+                     * @throws ApiError
+                     */
+                    public static analyticsFinancialRetrieve({
+                        metric,
+                        allTime = false,
+                        comparisonDays,
+                        endDate,
+                        fillMethod = 'zero',
+                        granularity = 'day',
+                        llmModel,
+                        mentorUniqueId,
+                        platformKey,
+                        provider,
+                        showOvertime = true,
+                        startDate,
+                        username,
+                    }: {
+                        /**
+                         * Type of financial metric to retrieve
+                         *
+                         * * `total_costs` - Total costs for selected timeframe
+                         * * `weekly_costs` - Costs for current/selected week
+                         * * `monthly_costs` - Costs for current/selected month
+                         */
+                        metric: 'total_costs' | 'weekly_costs' | 'monthly_costs',
+                        /**
+                         * calculate from platform inception (ignores date filters)
+                         */
+                        allTime?: boolean,
+                        /**
+                         * Number of days for comparison period to calculate percentage change (e.g., 10 for 10-day comparison)
+                         */
+                        comparisonDays?: number,
+                        /**
+                         * End date for analysis (YYYY-MM-DD). Defaults to today.
+                         */
+                        endDate?: string,
+                        /**
+                         * Method for filling missing time periods in overtime data
+                         *
+                         * * `zero` - Fill missing periods with zero
+                         * * `previous` - Fill missing periods with previous value
+                         */
+                        fillMethod?: 'zero' | 'previous',
+                        /**
+                         * Time granularity for overtime series data
+                         *
+                         * * `day` - Daily data points
+                         * * `week` - Weekly data points
+                         * * `month` - Monthly data points
+                         */
+                        granularity?: 'day' | 'week' | 'month',
+                        /**
+                         * Filter by specific LLM model (e.g., gpt-4o, claude-3-5-sonnet)
+                         */
+                        llmModel?: string,
+                        /**
+                         * Filter by specific mentor ID
+                         */
+                        mentorUniqueId?: string,
+                        /**
+                         * Filter by specific platform key
+                         */
+                        platformKey?: string,
+                        /**
+                         * Filter by AI provider
+                         *
+                         * * `openai` - OpenAI
+                         * * `anthropic` - Anthropic
+                         * * `azure` - Azure
+                         * * `google` - Google
+                         * * `meta` - Meta
+                         * * `other` - Other
+                         */
+                        provider?: 'openai' | 'anthropic' | 'azure' | 'google' | 'meta' | 'other',
+                        /**
+                         * Whether to include overtime series data in response
+                         */
+                        showOvertime?: boolean,
+                        /**
+                         * Start date for analysis (YYYY-MM-DD). Defaults to 30 days ago.
+                         */
+                        startDate?: string,
+                        /**
+                         * Filter by specific username - returns costs for this user only
+                         */
+                        username?: string,
+                    }): CancelablePromise<BaseFinanceResponse> {
+                        return __request(OpenAPI, {
+                            method: 'GET',
+                            url: '/api/analytics/financial/',
+                            query: {
+                                'all_time': allTime,
+                                'comparison_days': comparisonDays,
+                                'end_date': endDate,
+                                'fill_method': fillMethod,
+                                'granularity': granularity,
+                                'llm_model': llmModel,
+                                'mentor_unique_id': mentorUniqueId,
+                                'metric': metric,
+                                'platform_key': platformKey,
+                                'provider': provider,
+                                'show_overtime': showOvertime,
+                                'start_date': startDate,
+                                'username': username,
+                            },
+                            errors: {
+                                400: `Bad Request - Invalid query parameters`,
+                                403: `Forbidden - Insufficient permissions`,
+                                500: `Internal Server Error`,
+                            },
+                        });
+                    }
+                    /**
+                     * Financial Details Analytics API – paginated cost tables with flexible grouping.
+                     *
+                     * This endpoint returns tabular cost metrics aggregated by the dimension
+                     * specified via the `group_by` query parameter.  One or more KPI columns
+                     * can be requested through the comma-separated `metrics` list while
+                     * typical filters (date range, provider, platform_key, user, etc.) narrow the
+                     * dataset.  Results are paginated with `page` / `limit`.
+                     *
+                     * **Required query parameters**
+                     * - group_by – provider | llm_model | username | user_id | date | session_id
+                     * - metrics – csv list of KPI names, e.g. total_cost, sessions, cost_per_session
+                     *
+                     * **Shared optional filters**
+                     * - start_date, end_date   – ISO yyyy-mm-dd (ignored when all_time=true)
+                     * - platform_key           – tenant isolation
+                     * - mentor_unique_id       – filter to one mentor
+                     * - username / user_id     – filter to a learner
+                     * - provider / llm_model   – filter to LLM provider / model
+                     * - all_time               – true → lifetime totals
+                     * - page (default 1), limit (default 50)
+                     *
+                     * **Examples**
+                     * --------
+                     * 1. Cost by provider for the last week
+                     * ```
+                     * GET /api/v2/analytics/financial/details?
+                     * group_by=provider&
+                     * metrics=total_cost&
+                     * start_date=2025-01-01&
+                     * end_date=2025-01-07&
+                     * page=1&limit=10
+                     * ```
+                     *
+                     * 2. Lifetime cost per user with extra KPIs
+                     * ```
+                     * GET /api/v2/analytics/financial/details?
+                     * group_by=username&
+                     * metrics=total_cost,sessions,cost_per_session&
+                     * all_time=true&page=1&limit=50
+                     * ```
+                     * 3. Cost by LLM model with tenant filter
+                     * ```
+                     * GET /api/v2/analytics/financial/details?
+                     * group_by=llm_model&
+                     * metrics=total_cost&
+                     * platform_key=web-app&
+                     * start_date=2025-01-01&end_date=2025-01-31
+                     * ```
+                     * Response structure
+                     * -------------------
+                     * ```
+                     * {
+                         * "page": 1,
+                         * "limit": 10,
+                         * "total_pages": 1,
+                         * "total_records": 3,
+                         * "rows": [
+                             * {"provider": "openai", "total_cost": 2.5},
+                             * {"provider": "anthropic", "total_cost": 1.0},
+                             * {"provider": "azure",    "total_cost": 0.5}
+                             * ],
+                             * "metrics": [
+                                 * {
+                                     * "name": "total_cost",
+                                     * "unit": "$",
+                                     * "description": "Cost for this entity in period"
+                                     * }
+                                     * ],
+                                     * "total_cost": 4.0   // optional grand-total when available
+                                     * }
+                                     * ``
+                                     * @returns FinanceDetailsResponse
+                                     * @throws ApiError
+                                     */
+                                    public static analyticsFinancialDetailsRetrieve({
+                                        groupBy,
+                                        allTime = false,
+                                        endDate,
+                                        limit = 50,
+                                        llmModel,
+                                        mentorUniqueId,
+                                        metrics = 'total_cost',
+                                        page = 1,
+                                        platformKey,
+                                        provider,
+                                        startDate,
+                                        username,
+                                    }: {
+                                        /**
+                                         * Dimension to group by
+                                         *
+                                         * * `provider` - Group by provider
+                                         * * `llm_model` - Group by LLM model
+                                         * * `username` - Group by username
+                                         */
+                                        groupBy: 'provider' | 'llm_model' | 'username',
+                                        allTime?: boolean,
+                                        endDate?: string,
+                                        limit?: number,
+                                        llmModel?: string,
+                                        mentorUniqueId?: string,
+                                        /**
+                                         * Comma-separated list of metrics (e.g. total_cost,sessions, last_active)
+                                         */
+                                        metrics?: string,
+                                        page?: number,
+                                        platformKey?: string,
+                                        provider?: string,
+                                        startDate?: string,
+                                        username?: string,
+                                    }): CancelablePromise<FinanceDetailsResponse> {
+                                        return __request(OpenAPI, {
+                                            method: 'GET',
+                                            url: '/api/analytics/financial/details/',
+                                            query: {
+                                                'all_time': allTime,
+                                                'end_date': endDate,
+                                                'group_by': groupBy,
+                                                'limit': limit,
+                                                'llm_model': llmModel,
+                                                'mentor_unique_id': mentorUniqueId,
+                                                'metrics': metrics,
+                                                'page': page,
+                                                'platform_key': platformKey,
+                                                'provider': provider,
+                                                'start_date': startDate,
+                                                'username': username,
+                                            },
+                                            errors: {
+                                                400: `Bad Request – invalid query params`,
+                                                500: `Internal Server Error`,
+                                            },
+                                        });
+                                    }
+                                }

package/dist/types/models/Bot.d.ts

@@ -1,15 +0,0 @@
-import type { Provider05cEnum } from './Provider05cEnum';
-export type Bot = {
-    readonly id: number;
-    readonly platform: number;
-    readonly tenant: string;
-    name: string;
-    provider: Provider05cEnum;
-    readonly is_configured: boolean;
-    slack_config: number;
-    readonly discord_config: number;
-    readonly webex_config: number;
-    readonly whatsapp_config: number;
-    readonly teams_config: number;
-    readonly webhook_url: string;
-};

package/dist/types/models/BotCommand.d.ts

@@ -1,6 +0,0 @@
-export type BotCommand = {
-    readonly id: number;
-    command: string;
-    mentor: number;
-    bot: number;
-};

package/dist/types/models/BotCreate.d.ts

@@ -1,12 +0,0 @@
-import type { Provider05cEnum } from './Provider05cEnum';
-export type BotCreate = {
-    readonly id: number;
-    name: string;
-    provider: Provider05cEnum;
-    readonly is_configured: boolean;
-    readonly webhook_url: string;
-    readonly discord_config: number;
-    readonly webex_config: number;
-    readonly whatsapp_config: number;
-    readonly teams_config: number;
-};

package/dist/types/models/DataSet.d.ts

@@ -1,21 +0,0 @@
-import type { DataSetStatusEnum } from './DataSetStatusEnum';
-export type DataSet = {
-    readonly id: string;
-    readonly platform: Record<string, (string | number)> | null;
-    name: string;
-    /**
-     * (if any) Special instructions for generating the dataset. This could be requirements on tone, language, style, etc.
-     */
-    prompt?: string;
-    source_url?: string;
-    source_file?: string;
-    status?: DataSetStatusEnum;
-    num_data_points?: number;
-    train_split?: number;
-    train_file?: string;
-    test_file?: string;
-    retry_attempts?: number;
-    error_log?: string;
-    readonly date_created: string;
-    readonly last_modified: string;
-};

package/dist/types/models/DataSetCreate.d.ts

@@ -1,12 +0,0 @@
-export type DataSetCreate = {
-    readonly id: string;
-    name: string;
-    source_url?: string;
-    source_file?: string;
-    num_data_points?: number;
-    train_split?: number;
-    /**
-     * (if any) Special instructions for generating the dataset. This could be requirements on tone, language, style, etc.
-     */
-    prompt?: string;
-};

package/dist/types/models/DataSetStatusEnum.d.ts

@@ -1,12 +0,0 @@
-/**
- * * `pending` - Pending
- * * `processing` - Processing
- * * `completed` - Completed
- * * `failed` - Failed
- */
-export declare enum DataSetStatusEnum {
-    PENDING = "pending",
-    PROCESSING = "processing",
-    COMPLETED = "completed",
-    FAILED = "failed"
-}

package/dist/types/models/DiscordConfig.d.ts

@@ -1,7 +0,0 @@
-export type DiscordConfig = {
-    readonly id: number;
-    readonly bot: number;
-    client_id: string;
-    token: string;
-    client_secret: string;
-};

package/dist/types/models/DiscordUserConfig.d.ts

@@ -1,10 +0,0 @@
-export type DiscordUserConfig = {
-    readonly id: number;
-    /**
-     * edX user ID
-     */
-    readonly user: number;
-    discord_user_id: string;
-    readonly date_created: string;
-    readonly last_modified: string;
-};

package/dist/types/models/DiscordWebhook.d.ts

@@ -1,6 +0,0 @@
-export type DiscordWebhook = {
-    application_id: string;
-    type: string;
-    token: string;
-    id: string;
-};

package/dist/types/models/PaginatedDataSetList.d.ts

@@ -1,7 +0,0 @@
-import type { DataSet } from './DataSet';
-export type PaginatedDataSetList = {
-    count: number;
-    next?: string | null;
-    previous?: string | null;
-    results: Array<DataSet>;
-};

package/dist/types/models/PaginatedTrainingList.d.ts

@@ -1,7 +0,0 @@
-import type { Training } from './Training';
-export type PaginatedTrainingList = {
-    count: number;
-    next?: string | null;
-    previous?: string | null;
-    results: Array<Training>;
-};

package/dist/types/models/PatchedBotCommand.d.ts

@@ -1,6 +0,0 @@
-export type PatchedBotCommand = {
-    readonly id?: number;
-    command?: string;
-    mentor?: number;
-    bot?: number;
-};

package/dist/types/models/PatchedBotCreate.d.ts

@@ -1,12 +0,0 @@
-import type { Provider05cEnum } from './Provider05cEnum';
-export type PatchedBotCreate = {
-    readonly id?: number;
-    name?: string;
-    provider?: Provider05cEnum;
-    readonly is_configured?: boolean;
-    readonly webhook_url?: string;
-    readonly discord_config?: number;
-    readonly webex_config?: number;
-    readonly whatsapp_config?: number;
-    readonly teams_config?: number;
-};

package/dist/types/models/PatchedDataSet.d.ts

@@ -1,21 +0,0 @@
-import type { DataSetStatusEnum } from './DataSetStatusEnum';
-export type PatchedDataSet = {
-    readonly id?: string;
-    readonly platform?: Record<string, (string | number)> | null;
-    name?: string;
-    /**
-     * (if any) Special instructions for generating the dataset. This could be requirements on tone, language, style, etc.
-     */
-    prompt?: string;
-    source_url?: string;
-    source_file?: string;
-    status?: DataSetStatusEnum;
-    num_data_points?: number;
-    train_split?: number;
-    train_file?: string;
-    test_file?: string;
-    retry_attempts?: number;
-    error_log?: string;
-    readonly date_created?: string;
-    readonly last_modified?: string;
-};

package/dist/types/models/PatchedDiscordConfig.d.ts

@@ -1,7 +0,0 @@
-export type PatchedDiscordConfig = {
-    readonly id?: number;
-    readonly bot?: number;
-    client_id?: string;
-    token?: string;
-    client_secret?: string;
-};

package/dist/types/models/PatchedDiscordUserConfig.d.ts

@@ -1,10 +0,0 @@
-export type PatchedDiscordUserConfig = {
-    readonly id?: number;
-    /**
-     * edX user ID
-     */
-    readonly user?: number;
-    discord_user_id?: string;
-    readonly date_created?: string;
-    readonly last_modified?: string;
-};

package/dist/types/models/PatchedSlackConfig.d.ts

@@ -1,8 +0,0 @@
-export type PatchedSlackConfig = {
-    readonly id?: number;
-    bot?: number;
-    client_id?: string;
-    client_secret?: string;
-    app_token?: string;
-    verification_token?: string;
-};

package/dist/types/models/PatchedSlackUserConfig.d.ts

@@ -1,17 +0,0 @@
-export type PatchedSlackUserConfig = {
-    readonly id?: number;
-    /**
-     * edX user ID
-     */
-    readonly user?: number;
-    /**
-     * Team Domain in the stated slack workspace. This is also the workspace name.
-     */
-    slack_team_domain?: string;
-    /**
-     * Username in the stated slack workspace
-     */
-    slack_username?: string;
-    readonly date_created?: string;
-    readonly last_modified?: string;
-};

package/dist/types/models/PatchedTeamsConfig.d.ts

@@ -1,7 +0,0 @@
-export type PatchedTeamsConfig = {
-    readonly id?: number;
-    readonly bot?: number;
-    client_id?: string;
-    client_secret?: string;
-    verification_token?: string;
-};

package/dist/types/models/PatchedTrainingCreate.d.ts

@@ -1,31 +0,0 @@
-import type { Provider63aEnum } from './Provider63aEnum';
-export type PatchedTrainingCreate = {
-    readonly id?: string;
-    project_name?: string;
-    dataset?: string;
-    base_model_name?: string;
-    provider?: Provider63aEnum;
-    text_column?: string;
-    learning_rate?: number;
-    batch_size?: number;
-    num_epochs?: number;
-    block_size?: number;
-    warmup_ratio?: number;
-    lora_r?: number;
-    lora_alpha?: number;
-    lora_dropout?: number;
-    weight_decay?: number;
-    gradient_accumulation?: number;
-    use_peft?: boolean;
-    use_fp16?: boolean;
-    use_int4?: boolean;
-    push_to_hub?: boolean;
-    repo_id?: string;
-    preprocess_dataset?: boolean;
-    prompt_column?: string;
-    prompt_prefix?: string;
-    prompt_suffix?: string;
-    response_prefix?: string;
-    readonly date_created?: string;
-    readonly last_modified?: string;
-};

package/dist/types/models/PatchedWebexConfig.d.ts

@@ -1,10 +0,0 @@
-export type PatchedWebexConfig = {
-    readonly id?: number;
-    readonly bot?: number;
-    /**
-     * Bot id from webex
-     */
-    webex_bot_id?: string;
-    bot_access_token?: string;
-    bot_username?: string;
-};

package/dist/types/models/PatchedWhatsappConfig.d.ts

@@ -1,11 +0,0 @@
-export type PatchedWhatsappConfig = {
-    readonly id?: number;
-    readonly bot?: number;
-    phone_number_id?: string;
-    application_secret?: string;
-    webhook_verification_token?: string;
-    /**
-     * Access token to the bot. This can also be a temporary access token.
-     */
-    access_token?: string;
-};

package/dist/types/models/PatchedWhatsappUserConfig.d.ts

@@ -1,10 +0,0 @@
-export type PatchedWhatsappUserConfig = {
-    readonly id?: number;
-    /**
-     * edX user ID
-     */
-    readonly user?: number;
-    phone_number?: string;
-    readonly date_created?: string;
-    readonly last_modified?: string;
-};

package/dist/types/models/Provider05cEnum.d.ts

@@ -1,14 +0,0 @@
-/**
- * * `webex` - Webex
- * * `slack` - Slack
- * * `whatsapp` - Whatsapp
- * * `discord` - Discord
- * * `teams` - Teams
- */
-export declare enum Provider05cEnum {
-    WEBEX = "webex",
-    SLACK = "slack",
-    WHATSAPP = "whatsapp",
-    DISCORD = "discord",
-    TEAMS = "teams"
-}

package/dist/types/models/Provider63aEnum.d.ts

@@ -1,6 +0,0 @@
-/**
- * * `openai` - Openai
- */
-export declare enum Provider63aEnum {
-    OPENAI = "openai"
-}

package/dist/types/models/SlackConfig.d.ts

@@ -1,8 +0,0 @@
-export type SlackConfig = {
-    readonly id: number;
-    bot: number;
-    client_id: string;
-    client_secret: string;
-    app_token: string;
-    verification_token: string;
-};

package/dist/types/models/SlackUserConfig.d.ts

@@ -1,17 +0,0 @@
-export type SlackUserConfig = {
-    readonly id: number;
-    /**
-     * edX user ID
-     */
-    readonly user: number;
-    /**
-     * Team Domain in the stated slack workspace. This is also the workspace name.
-     */
-    slack_team_domain: string;
-    /**
-     * Username in the stated slack workspace
-     */
-    slack_username: string;
-    readonly date_created: string;
-    readonly last_modified: string;
-};