@iblai/iblai-api 2025.11.14-teams-bot-renovation-2-core → 2025.11.14-teams-bot-renovation-2-ai

package/dist/types/services/AiSearchService.d.ts

@@ -0,0 +1,451 @@
+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';
+export declare 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
+     */
+    static v2GlobalMentorSearch({ category, createdBy, includeMainPublicMentors, limit, llm, offset, platformKey, query, subjects, tenant, types, visibility, }: {
+        /**
+         * Mentor category filter
+         */
+        category?: string;
+        /**
+         * Filter mentors created by specific user (for personalized search)
+         */
+        createdBy?: string;
+        /**
+         * 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;
+        /**
+         * 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' in authenticated requests (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>;
+    /**
+     * Handle GET requests for my mentors.
+     * @returns MentorSearchResponse
+     * @throws ApiError
+     */
+    static aiSearchOrgsUsersMyMentorsRetrieve({ org, username, audience, category, createdBy, featured, id, includeMainPublicMentors, limit, llm, offset, orderBy, orderDirection, 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>;
+    /**
+     * 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
+     */
+    static v2PersonalizedMentors({ audience, category, limit, llmProviders, offset, orderBy, orderDirection, platformKey, query, returnFacet, tags, tenant, username, visibility, }: {
+        /**
+         * Filter by audience
+         */
+        audience?: Array<string>;
+        /**
+         * Mentor category filter
+         */
+        category?: string;
+        /**
+         * Number of results per page
+         */
+        limit?: number;
+        /**
+         * Filter by LLM provider
+         */
+        llmProviders?: Array<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 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>;
+    /**
+     * 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
+     */
+    static listPlatformPrompts(): CancelablePromise<Array<PlatformPromptResponse>>;
+    /**
+     * Create a new recommendation prompt
+     * Create a new recommendation prompt for a platform and SPA.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    static createPlatformPrompt({ requestBody, }: {
+        requestBody?: PlatformPrompt;
+    }): CancelablePromise<PlatformPromptResponse>;
+    /**
+     * Update an existing recommendation prompt
+     * Update an existing prompt by ID. Must provide platform_key to verify ownership.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    static updatePlatformPrompt({ requestBody, }: {
+        requestBody?: PlatformPrompt;
+    }): CancelablePromise<PlatformPromptResponse>;
+    /**
+     * 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
+     */
+    static deletePlatformPrompt(): CancelablePromise<void>;
+    /**
+     * 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
+     */
+    static listPlatformPrompts2(): CancelablePromise<Array<PlatformPromptResponse>>;
+    /**
+     * Create a new recommendation prompt
+     * Create a new recommendation prompt for a platform and SPA.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    static createPlatformPrompt2({ requestBody, }: {
+        requestBody?: PlatformPrompt;
+    }): CancelablePromise<PlatformPromptResponse>;
+    /**
+     * Update an existing recommendation prompt
+     * Update an existing prompt by ID. Must provide platform_key to verify ownership.
+     * @returns PlatformPromptResponse
+     * @throws ApiError
+     */
+    static updatePlatformPrompt2({ requestBody, }: {
+        requestBody?: PlatformPrompt;
+    }): CancelablePromise<PlatformPromptResponse>;
+    /**
+     * 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
+     */
+    static deletePlatformPrompt2(): CancelablePromise<void>;
+    /**
+     * 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
+     */
+    static v2CourseRecommendations({ assessmentId, contextType, difficultyLevels, domains, includeMainCatalog, includeUserHistory, includeUserSkills, k, limit, page, pageSize, platformKey, platformOrg, rankingPrompt, rankingStrategy, recommendationType, searchTerms, spaUrl, triggerSource, useLlmRanking, useRagSearch, }: {
+        /**
+         * 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>;
+}