@iblai/iblai-api 4.116.2-core → 4.117.0-ai

package/src/services/AiSearchService.ts

@@ -0,0 +1,766 @@
+/* generated using openapi-typescript-codegen -- do not edit */
+/* istanbul ignore file */
+/* tslint:disable */
+/* eslint-disable */
+import type { MentorSearchResponse } from '../models/MentorSearchResponse';
+import type { PlatformPrompt } from '../models/PlatformPrompt';
+import type { PlatformPromptResponse } from '../models/PlatformPromptResponse';
+import type { V2GlobalMentorSearchResponse } from '../models/V2GlobalMentorSearchResponse';
+import type { V2PersonalizedMentorsResponse } from '../models/V2PersonalizedMentorsResponse';
+import type { V2RecommendationResponse } from '../models/V2RecommendationResponse';
+import type { CancelablePromise } from '../core/CancelablePromise';
+import { OpenAPI } from '../core/OpenAPI';
+import { request as __request } from '../core/request';
+export class AiSearchService {
+    /**
+     * Search and filter AI mentors across the platform
+     *
+     * Search and filter AI mentors with support for comprehensive filtering, pagination, and detailed mentor information.
+     * This endpoint supports both anonymous and authenticated users with different access levels.
+     *
+     * **Anonymous Users:**
+     * - Access to public mentors only (VIEWABLE_BY_ANYONE)
+     * - Limited search capabilities
+     * - No personalization
+     *
+     * **Authenticated Users:**
+     * - Full access based on platform permissions (scoped to requested platform)
+     * - Personalized results
+     * - Access to tenant-specific mentors
+     *
+     * **Required Parameters (Authenticated Users):**
+     * - `platform_key` OR `tenant`: Platform key for RBAC enforcement (required for authenticated requests)
+     * - Use `platform_key` (preferred) or `tenant` (backward compatibility) - both serve the same purpose
+     * - If both are provided, `platform_key` takes precedence
+     *
+     * **Available Filters:**
+     * - `query`: Search term to filter mentors by name or description
+     * - `tenant`: Filter by tenant/organization platform key(s) - can also be used as alias for `platform_key` (backward compatibility)
+     * - `category`: Filter by mentor category (comma-separated)
+     * - `subjects`: Filter by mentor subject (comma-separated)
+     * - `types`: Filter by mentor type (comma-separated)
+     * - `llm`: Filter by LLM provider (comma-separated, e.g., GPT-4, Claude)
+     * - `visibility`: Filter by visibility level (comma-separated: viewable_by_anyone, viewable_by_tenant_students, viewable_by_tenant_admins)
+     * - `created_by`: Filter mentors created by specific user (for personalized search)
+     * - `include_main_public_mentors`: Include main tenant public mentors
+     *
+     * **Facets:**
+     * The response includes facets with aggregated counts for all filterable attributes:
+     * - categories, subjects, types, llm_providers, visibility
+     * All facet values can be used as filter parameters in subsequent requests.
+     *
+     * Notes:
+     * - Detail view is removed; use the ibl_ai_mentor app for mentor details
+     * - include_main_public_mentors=true shows only VIEWABLE_BY_ANYONE mentors from the main tenant across tenants
+     * - For authenticated requests, either `platform_key` or `tenant` is required when username is provided
+     * - `tenant` parameter serves dual purpose: as a filter for multiple tenants, or as an alias for `platform_key` (backward compatibility)
+     * - Frontend uses `llm` parameter name (backend maps to `llm_provider` automatically)
+     *
+     * @returns V2GlobalMentorSearchResponse
+     * @throws ApiError
+     */
+    public static v2GlobalMentorSearch({
+        category,
+        createdBy,
+        featured,
+        includeMainPublicMentors = false,
+        limit,
+        llm,
+        offset,
+        platformKey,
+        query,
+        starred,
+        subjects,
+        tenant,
+        types,
+        visibility,
+    }: {
+        /**
+         * Mentor category filter
+         */
+        category?: string,
+        /**
+         * Filter mentors created by specific user (for personalized search)
+         */
+        createdBy?: string,
+        /**
+         * Filter by featured status (true/false)
+         */
+        featured?: boolean | null,
+        /**
+         * Include main tenant public mentors (VIEWABLE_BY_ANYONE) when true
+         */
+        includeMainPublicMentors?: boolean,
+        /**
+         * Number of results per page
+         */
+        limit?: number,
+        /**
+         * LLM provider filter
+         */
+        llm?: string,
+        /**
+         * Number of results to skip
+         */
+        offset?: number,
+        /**
+         * Platform key for RBAC enforcement. Required for authenticated requests. Can also use 'tenant' parameter as an alias (backward compatibility).
+         */
+        platformKey?: string,
+        /**
+         * Search query for mentors
+         */
+        query?: string,
+        /**
+         * Filter by starred status (true/false) - only for authenticated users
+         */
+        starred?: boolean | null,
+        /**
+         * Mentor subject filter
+         */
+        subjects?: string,
+        /**
+         * Tenant key(s) (CSV). Can be used as a filter for multiple tenants, or as an alias for 'platform_key' (backward compatibility).
+         */
+        tenant?: string,
+        /**
+         * Mentor type filter
+         */
+        types?: string,
+        /**
+         * Mentor visibility filter (viewable_by_anyone, viewable_by_tenant_students, viewable_by_tenant_admins)
+         */
+        visibility?: string,
+    }): CancelablePromise<V2GlobalMentorSearchResponse> {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/api/ai-search/mentors/',
+            query: {
+                'category': category,
+                'created_by': createdBy,
+                'featured': featured,
+                'include_main_public_mentors': includeMainPublicMentors,
+                'limit': limit,
+                'llm': llm,
+                'offset': offset,
+                'platform_key': platformKey,
+                'query': query,
+                'starred': starred,
+                'subjects': subjects,
+                'tenant': tenant,
+                'types': types,
+                'visibility': visibility,
+            },
+            errors: {
+                400: `Bad request - invalid parameters`,
+                500: `Internal server error`,
+            },
+        });
+    }
+    /**
+     * Handle GET requests for my mentors.
+     * @returns MentorSearchResponse
+     * @throws ApiError
+     */
+    public static aiSearchOrgsUsersMyMentorsRetrieve({
+        org,
+        username,
+        audience,
+        category,
+        createdBy,
+        featured,
+        id,
+        includeMainPublicMentors = false,
+        limit = 12,
+        llm,
+        offset,
+        orderBy,
+        orderDirection = 'desc',
+        query,
+        tags,
+        tenant,
+        uniqueId,
+    }: {
+        org: string,
+        username: string,
+        /**
+         * Filter by target audience
+         */
+        audience?: Array<string>,
+        /**
+         * Filter by mentor category
+         */
+        category?: Array<string>,
+        /**
+         * Filter mentors created by specific user
+         */
+        createdBy?: string,
+        /**
+         * Filter by featured status
+         */
+        featured?: boolean,
+        /**
+         * Retrieve a specific mentor by ID
+         */
+        id?: number,
+        /**
+         * Include public mentors from main tenant
+         */
+        includeMainPublicMentors?: boolean,
+        /**
+         * Number of results per page
+         */
+        limit?: number,
+        /**
+         * Filter by language model type
+         */
+        llm?: Array<string>,
+        /**
+         * Starting position for pagination
+         */
+        offset?: number,
+        /**
+         * Field to sort results by ('created_at', 'recently_accessed_at')
+         */
+        orderBy?: string,
+        /**
+         * Sort direction ('asc' or 'desc')
+         */
+        orderDirection?: string,
+        /**
+         * Search term to filter mentors by name or description
+         */
+        query?: string,
+        /**
+         * Filter by tags
+         */
+        tags?: Array<string>,
+        /**
+         * Filter by tenant/organization
+         */
+        tenant?: string,
+        /**
+         * Retrieve a specific mentor by UUID
+         */
+        uniqueId?: string,
+    }): CancelablePromise<MentorSearchResponse> {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/api/ai-search/orgs/{org}/users/{username}/my-mentors/',
+            path: {
+                'org': org,
+                'username': username,
+            },
+            query: {
+                'audience': audience,
+                'category': category,
+                'created_by': createdBy,
+                'featured': featured,
+                'id': id,
+                'include_main_public_mentors': includeMainPublicMentors,
+                'limit': limit,
+                'llm': llm,
+                'offset': offset,
+                'order_by': orderBy,
+                'order_direction': orderDirection,
+                'query': query,
+                'tags': tags,
+                'tenant': tenant,
+                'unique_id': uniqueId,
+            },
+            errors: {
+                400: `Bad request`,
+                401: `Unauthorized`,
+                403: `Forbidden`,
+                404: `Not found`,
+                500: `Server error`,
+            },
+        });
+    }
+    /**
+     * Get mentors created by a specific user
+     *
+     * Get mentors created by a specific user within a given organization/platform.
+     * This endpoint provides a personalized view of the user's own mentors with
+     * support for filtering, pagination, and detailed mentor information.
+     *
+     * **Authentication Required:**
+     * - username: Required for personalized mentor access
+     * - platform_key OR tenant: Required for tenant-specific content (both serve the same purpose)
+     * - Use `platform_key` (preferred) or `tenant` (backward compatibility)
+     * - If both are provided, `platform_key` takes precedence
+     *
+     * **Features:**
+     * - User's own mentors only
+     * - Personalization data (access counts, last used)
+     * - Filtering and faceted search
+     * - Pagination support
+     * - Detail and list views
+     *
+     * @returns V2PersonalizedMentorsResponse
+     * @throws ApiError
+     */
+    public static v2PersonalizedMentors({
+        audience,
+        category,
+        featured,
+        limit,
+        llm,
+        offset,
+        orderBy,
+        orderDirection,
+        platformKey,
+        query,
+        returnFacet,
+        starred,
+        tags,
+        tenant,
+        username,
+        visibility,
+    }: {
+        /**
+         * Filter by audience
+         */
+        audience?: Array<string>,
+        /**
+         * Mentor category filter
+         */
+        category?: string,
+        /**
+         * Filter by featured status (true/false)
+         */
+        featured?: boolean | null,
+        /**
+         * Number of results per page
+         */
+        limit?: number,
+        /**
+         * LLM provider filter (frontend uses 'llm', backend maps to 'llm_provider')
+         */
+        llm?: string,
+        /**
+         * Number of results to skip
+         */
+        offset?: number,
+        /**
+         * Field to sort by
+         */
+        orderBy?: string,
+        /**
+         * Sort direction
+         *
+         * * `asc` - asc
+         * * `desc` - desc
+         */
+        orderDirection?: 'asc' | 'desc',
+        /**
+         * Platform key for authentication. Required for authenticated requests. Can also use 'tenant' parameter as an alias (backward compatibility).
+         */
+        platformKey?: string,
+        /**
+         * Search query for personalized mentors
+         */
+        query?: string,
+        /**
+         * Include facet data in response
+         */
+        returnFacet?: boolean,
+        /**
+         * Filter by starred status (true/false)
+         */
+        starred?: boolean | null,
+        /**
+         * Filter by tags
+         */
+        tags?: Array<string>,
+        /**
+         * Tenant key (alias for 'platform_key' for backward compatibility). Can be used instead of 'platform_key' - both serve the same purpose.
+         */
+        tenant?: string,
+        /**
+         * Username for authentication (required for unauthenticated requests)
+         */
+        username?: string,
+        /**
+         * Filter by visibility
+         */
+        visibility?: Array<string>,
+    }): CancelablePromise<V2PersonalizedMentorsResponse> {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/api/ai-search/personalized-mentors/',
+            query: {
+                'audience': audience,
+                'category': category,
+                'featured': featured,
+                'limit': limit,
+                'llm': llm,
+                'offset': offset,
+                'order_by': orderBy,
+                'order_direction': orderDirection,
+                'platform_key': platformKey,
+                'query': query,
+                'return_facet': returnFacet,
+                'starred': starred,
+                'tags': tags,
+                'tenant': tenant,
+                'username': username,
+                'visibility': visibility,
+            },
+            errors: {
+                400: `Bad request - invalid parameters`,
+                401: `Unauthorized - missing credentials`,
+                403: `Forbidden - insufficient permissions`,
+                404: `Mentor not found`,
+                500: `Internal server error`,
+            },
+        });
+    }
+    /**
+     * List recommendation prompts for a platform
+     * Get all recommendation prompts for a specific platform. Optionally filter by SPA URL or recommendation type.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    public static listPlatformPrompts(): CancelablePromise<Array<PlatformPromptResponse>> {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/api/ai-search/prompts/',
+            errors: {
+                400: `Invalid parameters`,
+                401: `Authentication required`,
+                403: `Admin permissions required`,
+            },
+        });
+    }
+    /**
+     * Create a new recommendation prompt
+     * Create a new recommendation prompt for a platform and SPA.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    public static createPlatformPrompt({
+        requestBody,
+    }: {
+        requestBody?: PlatformPrompt,
+    }): CancelablePromise<PlatformPromptResponse> {
+        return __request(OpenAPI, {
+            method: 'POST',
+            url: '/api/ai-search/prompts/',
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                400: `Invalid data`,
+                401: `Authentication required`,
+                403: `Admin permissions required`,
+                409: `Prompt already exists for this combination`,
+            },
+        });
+    }
+    /**
+     * Update an existing recommendation prompt
+     * Update an existing prompt by ID. Must provide platform_key to verify ownership.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    public static updatePlatformPrompt({
+        requestBody,
+    }: {
+        requestBody?: PlatformPrompt,
+    }): CancelablePromise<PlatformPromptResponse> {
+        return __request(OpenAPI, {
+            method: 'PUT',
+            url: '/api/ai-search/prompts/',
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                400: `Invalid data`,
+                401: `Authentication required`,
+                403: `Admin permissions required or platform mismatch`,
+                404: `Prompt not found`,
+            },
+        });
+    }
+    /**
+     * Delete a recommendation prompt
+     * Delete a recommendation prompt by ID. Must provide platform_key to verify ownership. This permanently removes the prompt.
+     * @returns void
+     * @throws ApiError
+     */
+    public static deletePlatformPrompt(): CancelablePromise<void> {
+        return __request(OpenAPI, {
+            method: 'DELETE',
+            url: '/api/ai-search/prompts/',
+            errors: {
+                401: `Authentication required`,
+                403: `Admin permissions required or platform mismatch`,
+                404: `Prompt not found`,
+            },
+        });
+    }
+    /**
+     * List recommendation prompts for a platform
+     * Get all recommendation prompts for a specific platform. Optionally filter by SPA URL or recommendation type.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    public static listPlatformPrompts2(): CancelablePromise<Array<PlatformPromptResponse>> {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/api/ai-search/recommendation/prompts/',
+            errors: {
+                400: `Invalid parameters`,
+                401: `Authentication required`,
+                403: `Admin permissions required`,
+            },
+        });
+    }
+    /**
+     * Create a new recommendation prompt
+     * Create a new recommendation prompt for a platform and SPA.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    public static createPlatformPrompt2({
+        requestBody,
+    }: {
+        requestBody?: PlatformPrompt,
+    }): CancelablePromise<PlatformPromptResponse> {
+        return __request(OpenAPI, {
+            method: 'POST',
+            url: '/api/ai-search/recommendation/prompts/',
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                400: `Invalid data`,
+                401: `Authentication required`,
+                403: `Admin permissions required`,
+                409: `Prompt already exists for this combination`,
+            },
+        });
+    }
+    /**
+     * Update an existing recommendation prompt
+     * Update an existing prompt by ID. Must provide platform_key to verify ownership.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    public static updatePlatformPrompt2({
+        requestBody,
+    }: {
+        requestBody?: PlatformPrompt,
+    }): CancelablePromise<PlatformPromptResponse> {
+        return __request(OpenAPI, {
+            method: 'PUT',
+            url: '/api/ai-search/recommendation/prompts/',
+            body: requestBody,
+            mediaType: 'application/json',
+            errors: {
+                400: `Invalid data`,
+                401: `Authentication required`,
+                403: `Admin permissions required or platform mismatch`,
+                404: `Prompt not found`,
+            },
+        });
+    }
+    /**
+     * Delete a recommendation prompt
+     * Delete a recommendation prompt by ID. Must provide platform_key to verify ownership. This permanently removes the prompt.
+     * @returns void
+     * @throws ApiError
+     */
+    public static deletePlatformPrompt2(): CancelablePromise<void> {
+        return __request(OpenAPI, {
+            method: 'DELETE',
+            url: '/api/ai-search/recommendation/prompts/',
+            errors: {
+                401: `Authentication required`,
+                403: `Admin permissions required or platform mismatch`,
+                404: `Prompt not found`,
+            },
+        });
+    }
+    /**
+     * Generate AI-driven course recommendations
+     *
+     * Generate personalized course recommendations using AI that considers the user's
+     * learning history, organizational goals, and available courses.
+     *
+     * **Authentication Required:**
+     * - User must be authenticated
+     * - Platform key must be provided
+     * - User must have access to the specified platform
+     *
+     * **How It Works:**
+     * 1. Fetches tenant's custom recommendation prompt (if configured)
+     * 2. Analyzes user's course completion history and performance
+     * 3. Reviews available course catalog
+     * 4. Uses AI to match courses to user's needs and organizational goals
+     * 5. Returns 3-5 courses with clear explanations
+     *
+     * **Tenant Prompts:**
+     * Each organization can configure custom prompts that guide recommendations.
+     * For example: "Prioritize leadership for sales roles" or "Focus on technical skills."
+     *
+     * **Use Cases:**
+     * - Manual recommendation requests by users
+     * - Post-assessment recommendations
+     * - Milestone-triggered suggestions
+     * - Learning path planning
+     *
+     * @returns V2RecommendationResponse
+     * @throws ApiError
+     */
+    public static v2CourseRecommendations({
+        assessmentId,
+        contextType,
+        difficultyLevels,
+        domains,
+        includeMainCatalog = false,
+        includeUserHistory = false,
+        includeUserSkills = false,
+        k = 20,
+        limit = 5,
+        page = 1,
+        pageSize = 10,
+        platformKey,
+        platformOrg,
+        rankingPrompt,
+        rankingStrategy,
+        recommendationType = 'courses',
+        searchTerms,
+        spaUrl,
+        triggerSource = 'manual',
+        useLlmRanking = false,
+        useRagSearch = true,
+    }: {
+        /**
+         * Assessment ID if triggered by assessment completion
+         */
+        assessmentId?: string,
+        /**
+         * Context type for recommendation (e.g., 'assessment_completed', 'milestone_reached')
+         */
+        contextType?: string,
+        /**
+         * Filter recommendations to specific difficulty levels (CSV)
+         */
+        difficultyLevels?: string,
+        /**
+         * Filter recommendations to specific domains (CSV)
+         */
+        domains?: string,
+        /**
+         * Include items from 'main' tenant catalog IN ADDITION TO platform-specific catalog. By default, only platform-specific data is returned (tenant isolation). Set to True to also include shared 'main' tenant resources.
+         */
+        includeMainCatalog?: boolean,
+        /**
+         * Include user's learning history (completed courses, topics) in the RAG search query. Helps find content that builds on their background.
+         */
+        includeUserHistory?: boolean,
+        /**
+         * Include user's skills and badges in the RAG search query. Helps personalize results based on what the user already knows.
+         */
+        includeUserSkills?: boolean,
+        /**
+         * Number of similar items to retrieve via RAG per tenant (before filtering). Higher values give more options but may be slower.
+         */
+        k?: number,
+        /**
+         * Number of course recommendations to return (max 20)
+         */
+        limit?: number,
+        /**
+         * Page number for pagination (starts at 1)
+         */
+        page?: number,
+        /**
+         * Number of recommendations per page (max 100)
+         */
+        pageSize?: number,
+        /**
+         * Platform key for tenant-scoped recommendations
+         */
+        platformKey?: string,
+        /**
+         * Platform org identifier (optional - avoids database lookup if provided)
+         */
+        platformOrg?: string | null,
+        /**
+         * Custom prompt for LLM ranking (only if ranking_strategy='custom'). Define how the LLM should evaluate and order the recommendations.
+         */
+        rankingPrompt?: string,
+        /**
+         * Strategy for LLM ranking. Only used if use_llm_ranking=True.
+         *
+         * * `relevance` - Rank by relevance and value (default)
+         * * `difficulty` - Rank by difficulty progression
+         * * `personalized` - Personalize to user context and goals
+         * * `custom` - Use custom ranking prompt
+         */
+        rankingStrategy?: 'relevance' | 'difficulty' | 'personalized' | 'custom',
+        /**
+         * Type of resource to recommend. Catalog types (courses/programs/resources/pathways) will use the platform's 'catalog' prompt category if configured.
+         *
+         * * `mentors` - Mentor Recommendations
+         * * `courses` - Course Recommendations
+         * * `programs` - Program Recommendations
+         * * `resources` - Resource Recommendations
+         * * `pathways` - Pathway Recommendations
+         */
+        recommendationType?: 'mentors' | 'courses' | 'programs' | 'resources' | 'pathways',
+        /**
+         * Search terms to find similar content (e.g., 'leadership', 'data science'). Used to build the RAG query.
+         */
+        searchTerms?: string,
+        /**
+         * Frontend/SPA identifier (e.g., 'catalog.example.com', 'mentor-ai.ibl.com'). Used to retrieve the correct prompt for that specific frontend. Auto-detected from HTTP_REFERER if not provided.
+         */
+        spaUrl?: string,
+        /**
+         * What triggered this recommendation request
+         */
+        triggerSource?: string,
+        /**
+         * Use LLM to rank and personalize RAG results. Adds AI-generated reasoning but increases cost and latency. Only applies if use_rag_search=True.
+         */
+        useLlmRanking?: boolean,
+        /**
+         * Use RAG similarity search instead of full LLM catalog review. Faster and more cost-effective. Set to False for legacy LLM-only behavior.
+         */
+        useRagSearch?: boolean,
+    }): CancelablePromise<V2RecommendationResponse> {
+        return __request(OpenAPI, {
+            method: 'GET',
+            url: '/api/ai-search/recommendations/',
+            query: {
+                'assessment_id': assessmentId,
+                'context_type': contextType,
+                'difficulty_levels': difficultyLevels,
+                'domains': domains,
+                'include_main_catalog': includeMainCatalog,
+                'include_user_history': includeUserHistory,
+                'include_user_skills': includeUserSkills,
+                'k': k,
+                'limit': limit,
+                'page': page,
+                'page_size': pageSize,
+                'platform_key': platformKey,
+                'platform_org': platformOrg,
+                'ranking_prompt': rankingPrompt,
+                'ranking_strategy': rankingStrategy,
+                'recommendation_type': recommendationType,
+                'search_terms': searchTerms,
+                'spa_url': spaUrl,
+                'trigger_source': triggerSource,
+                'use_llm_ranking': useLlmRanking,
+                'use_rag_search': useRagSearch,
+            },
+            errors: {
+                400: `Bad request - invalid parameters or missing required fields`,
+                401: `Unauthorized - authentication required`,
+                500: `Internal server error`,
+            },
+        });
+    }
+}