erp-ai-latest/ENRICH_QUESTIONS_API.md

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 <your-api-key>

Request Format

Headers

Content-Type: application/json
Authorization: Bearer <your-api-key>

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

[
  {
    "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:

{
  "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

{
  "error": "Invalid input",
  "message": "Input data must be in JSON format."
}

400 Bad Request - Missing Required Fields

{
  "error": "Invalid data",
  "message": "Question object at index 0 is missing required field 'question'."
}

400 Bad Request - Invalid Array Structure

{
  "error": "Invalid input",
  "message": "Input data must be an array of question objects."
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "API key is missing or invalid."
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred."
}

Usage Examples

Basic Usage

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

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.