# Enrich Questions API Documentation ## Overview The `enrich-questions` endpoint is a reverse API that takes existing questions and assigns them to specific areas and members. This endpoint returns the exact same response structure as `generate_questions_from_sop_v3`. Each question is intelligently assigned to the most relevant area_tag and member using OpenAI analysis. ## Endpoint ``` POST /api/v1/common/enrich-questions ``` ## Authentication Requires Bearer token authentication: ``` Authorization: Bearer ``` ## Request Format ### Headers ``` Content-Type: application/json Authorization: Bearer ``` ### Request Body The request body should be a JSON array of question objects. Each question object must contain: - `question` (string): The question text - `role` (string): The role associated with the question - `position_id` (integer): The position ID (used as role ID in response) - `area_tags` (array): Array of area tag objects with `name` and `id` (OpenAI selects the most relevant one) - `members` (array): Array of member objects with `id` (algorithm selects the most appropriate one) ### Example Request ```json [ { "question": "Is the system monitoring working properly?", "role": "IT Expert", "position_id": 522, "area_tags": [ { "name": "IT Operations", "id": 1276 }, { "name": "Communication & Coordination", "id": 1426 }, { "name": "Quality Assurance", "id": 1427 } ], "members": [ { "id": 159 } ] }, { "question": "Are safety protocols being followed?", "role": "IT Expert", "position_id": 522, "area_tags": [ { "name": "IT Operations", "id": 1276 }, { "name": "Safety Protocols", "id": 1436 } ], "members": [ { "id": 159 } ] } ] ``` ## Response Format ### Success Response (200 OK) The response structure is identical to `generate_questions_from_sop_v3`. Each question is assigned to ONE area_tag and ONE member: ```json { "questions": { "items": [ { "area_tag": 1276, "area_name": "IT Operations", "assigned_to": 159, "questions": "Is the system monitoring working properly?", "role": 522 }, { "area_tag": 1436, "area_name": "Safety Protocols", "assigned_to": 159, "questions": "Are safety protocols being followed?", "role": 522 } ] } } ``` ### Response Structure Explanation - Each question creates exactly ONE item in the response - OpenAI analyzes the question content and selects the most relevant `area_tag` from available options - The algorithm selects the most appropriate `member` from the available members - `area_tag`: The OpenAI-selected area tag ID - `area_name`: The OpenAI-selected area tag name - `assigned_to`: The selected member ID - `questions`: The question text - `role`: The position_id from the request (used as role identifier) ## AI-Powered Assignment Algorithm ### OpenAI Area Tag Selection The system uses OpenAI's GPT-4o-mini model to intelligently analyze each question and select the most relevant area tag: 1. **Content Analysis**: OpenAI analyzes the question content, context, and meaning 2. **Domain Matching**: Determines which area/domain the question is actually testing or assessing 3. **Relevance Scoring**: Considers the purpose and intent of the question 4. **Smart Selection**: Chooses the most specific and primary area tag from available options 5. **Fallback**: If OpenAI analysis fails, defaults to the first available area tag **OpenAI Prompt Guidelines:** - Analyze question content and context - Match questions to appropriate area tags based on meaning and purpose - Consider what domain/area the question is actually testing - Choose only ONE area tag per question - the most relevant one - If multiple areas seem relevant, choose the most specific or primary one ### Member Selection Currently uses a simple selection algorithm (first member), but can be enhanced to consider: - Member skills and expertise - Current workload distribution - Availability and capacity - Historical performance ### Error Responses #### 400 Bad Request - Invalid Input Format ```json { "error": "Invalid input", "message": "Input data must be in JSON format." } ``` #### 400 Bad Request - Missing Required Fields ```json { "error": "Invalid data", "message": "Question object at index 0 is missing required field 'question'." } ``` #### 400 Bad Request - Invalid Array Structure ```json { "error": "Invalid input", "message": "Input data must be an array of question objects." } ``` #### 401 Unauthorized ```json { "error": "Unauthorized", "message": "API key is missing or invalid." } ``` #### 500 Internal Server Error ```json { "error": "Internal Server Error", "message": "An unexpected error occurred." } ``` ## Usage Examples ### Basic Usage ```bash curl -X POST "http://localhost:5402/api/v1/common/enrich-questions" \ -H "Authorization: Bearer your-api-key" \ -H "Content-Type: application/json" \ -d '[ { "question": "Is the system performance being monitored?", "role": "Developer", "position_id": 123, "area_tags": [ {"name": "Development", "id": 1}, {"name": "Performance Monitoring", "id": 2} ], "members": [ {"id": 456} ] } ]' ``` ### Python Example ```python import requests import json url = "http://localhost:5402/api/v1/common/enrich-questions" headers = { "Authorization": "Bearer your-api-key", "Content-Type": "application/json" } payload = [ { "question": "Is the system performance being monitored?", "role": "Developer", "position_id": 123, "area_tags": [ {"name": "Development", "id": 1}, {"name": "Performance Monitoring", "id": 2} ], "members": [ {"id": 456} ] } ] response = requests.post(url, json=payload, headers=headers) result = response.json() print(result) ``` ## Validation Rules 1. **Input must be a JSON array** of question objects 2. **Each question object must contain all required fields**: - `question`: Non-empty string - `role`: Non-empty string - `position_id`: Integer - `area_tags`: Array of objects with `name` and `id` - `members`: Array of objects with `id` 3. **Area tags must be valid objects** with both `name` (string) and `id` (integer/string) 4. **Members must be valid objects** with `id` (integer/string) 5. **Arrays can be empty** but must be present ## Response Logic The endpoint uses AI to intelligently assign each question to the most relevant area and member: - **Input**: 2 questions with multiple area_tags and members each - **Output**: 2 items (one per question) with the best area_tag and member selected for each - **AI Analysis**: OpenAI analyzes question content and meaning to find the most relevant area_tag - **Smart Assignment**: Uses natural language understanding to make intelligent assignments - **No Cartesian Product**: Each question gets exactly one area assignment and one member assignment ## Performance Considerations - **Batch Processing**: OpenAI analysis is performed in batches for efficiency - **Caching**: Consider implementing caching for frequently assigned questions - **Fallback**: Robust fallback mechanisms ensure the endpoint always returns valid assignments - **Error Handling**: Comprehensive error handling for OpenAI API failures ## Integration with Existing System This endpoint complements the existing question generation APIs: - `POST /api/v1/qs/generate_questions_from_sop` - Generates questions from SOPs - `POST /api/v1/qs/generate_questions_from_sop-latest` - Enhanced question generation - `POST /api/v1/common/enrich-questions` - Enriches existing questions (NEW) The enrich-questions endpoint returns the **exact same structure** as `generate_questions_from_sop_v3`, with AI-powered intelligent assignment of questions to the most relevant areas and members, making it seamlessly interchangeable in your application workflow.