Query Expansion API Reference

This document provides comprehensive API reference for the Query Expansion System.

Core Classes

QueryExpansionSystem

Main system for comprehensive query expansion.

from packages.rag.query_expansion import QueryExpansionSystem

system = QueryExpansionSystem(db_path="synonyms.db")

Methods

`expand_query(query: str, context: ExpansionContext, enabled_strategies: Optional[List[ExpansionType]] = None) -> List[ExpansionResult]`

Expand a query using multiple strategies.

Parameters:

query (str): The query to expand
context (ExpansionContext): Expansion context with user information
enabled_strategies (Optional[List[ExpansionType]]): Strategies to use for expansion

Returns:

List[ExpansionResult]: List of expansion results

Example:

expansions = await system.expand_query(
    query="API documentation",
    context=expansion_context,
    enabled_strategies=[ExpansionType.SYNONYM_EXPANSION, ExpansionType.ACRONYM_EXPANSION]
)

`add_synonym(term: str, synonym: str, domain: str, source: SynonymSource, confidence: float = 0.8, context: Optional[str] = None, user_role: Optional[str] = None, department: Optional[str] = None) -> bool`

Add a new synonym to the system.

Parameters:

term (str): The original term
synonym (str): The synonym
domain (str): Domain context
source (SynonymSource): Source of the synonym
confidence (float): Confidence score (0.0-1.0)
context (Optional[str]): Additional context
user_role (Optional[str]): User role restriction
department (Optional[str]): Department restriction

Returns:

bool: Success status

`record_feedback(expansion_result: ExpansionResult, user_id: str, was_helpful: bool, rating: Optional[int] = None, comment: Optional[str] = None)`

Record user feedback on expansion effectiveness.

Parameters:

expansion_result (ExpansionResult): The expansion result
user_id (str): User ID
was_helpful (bool): Whether expansion was helpful
rating (Optional[int]): Rating 1-5
comment (Optional[str]): User comment

ExpansionContext

Context for query expansion.

from packages.rag.query_expansion import ExpansionContext

context = ExpansionContext(
    user_id="user123",
    user_role="developer",
    department="engineering",
    domain="technical",
    session_id="session123",
    conversation_history=[],
    available_documents=[],
    user_preferences={},
    expansion_settings={}
)

Fields

user_id (str): User identifier
user_role (str): User role (developer, manager, analyst, designer)
department (str): User department
domain (str): Domain context (technical, business, general)
session_id (str): Session identifier
conversation_history (List[Dict[str, Any]]): Previous conversation context
available_documents (List[Dict[str, Any]]): Available document context
user_preferences (Dict[str, Any]): User preferences
expansion_settings (Dict[str, Any]): Expansion configuration

ExpansionResult

Result of query expansion.

from packages.rag.query_expansion import ExpansionResult

result = ExpansionResult(
    original_query="API documentation",
    expanded_query="API documentation OR Application Programming Interface documentation",
    expansion_type=ExpansionType.SYNONYM_EXPANSION,
    synonyms_used=[synonym1, synonym2],
    confidence_score=0.8,
    relevance_score=0.9,
    expansion_metadata={}
)

Fields

original_query (str): Original query text
expanded_query (str): Expanded query text
expansion_type (ExpansionType): Type of expansion used
synonyms_used (List[Synonym]): Synonyms used in expansion
confidence_score (float): Confidence score (0.0-1.0)
relevance_score (float): Relevance score (0.0-1.0)
expansion_metadata (Dict[str, Any]): Additional metadata

Enums

ExpansionType

Types of query expansion.

from packages.rag.query_expansion import ExpansionType

# Available types
ExpansionType.SYNONYM_EXPANSION      # Synonym-based expansion
ExpansionType.ACRONYM_EXPANSION      # Acronym resolution
ExpansionType.ABBREVIATION_EXPANSION # Abbreviation expansion
ExpansionType.DOMAIN_SPECIFIC        # Domain-specific expansion
ExpansionType.CONTEXTUAL             # Contextual expansion
ExpansionType.SEMANTIC               # Semantic similarity expansion

SynonymSource

Sources of synonyms.

from packages.rag.query_expansion import SynonymSource

# Available sources
SynonymSource.MANUAL_CURATION    # Manually curated
SynonymSource.USER_FEEDBACK      # From user feedback
SynonymSource.ML_DISCOVERY       # Machine learning discovery
SynonymSource.DOMAIN_EXPERT      # Domain expert input
SynonymSource.COLLABORATIVE      # Collaborative filtering
SynonymSource.EXTERNAL_API       # External API

Analytics API

SynonymAnalytics

Analytics system for expansion monitoring.

from packages.rag.synonym_analytics import create_synonym_analytics

analytics = create_synonym_analytics("synonyms.db")

Methods

`get_expansion_metrics(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, domain: Optional[str] = None) -> ExpansionMetrics`

Get comprehensive expansion metrics.

Parameters:

start_date (Optional[datetime]): Start date filter
end_date (Optional[datetime]): End date filter
domain (Optional[str]): Domain filter

Returns:

ExpansionMetrics: Expansion effectiveness metrics

`get_synonym_metrics(domain: Optional[str] = None) -> SynonymMetrics`

Get synonym usage and effectiveness metrics.

Parameters:

domain (Optional[str]): Domain filter

Returns:

SynonymMetrics: Synonym usage metrics

`get_user_behavior_metrics(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None) -> UserBehaviorMetrics`

Get user behavior and engagement metrics.

Parameters:

start_date (Optional[datetime]): Start date filter
end_date (Optional[datetime]): End date filter

Returns:

UserBehaviorMetrics: User behavior metrics

`generate_analytics_report(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, domain: Optional[str] = None) -> Dict[str, Any]`

Generate comprehensive analytics report.

Parameters:

start_date (Optional[datetime]): Start date filter
end_date (Optional[datetime]): End date filter
domain (Optional[str]): Domain filter

Returns:

Dict[str, Any]: Comprehensive analytics report

Management API

SynonymManagementSystem

Management system for synonym operations.

from packages.rag.synonym_management import create_synonym_management_system

management = create_synonym_management_system("synonyms.db")

Methods

`add_synonym_entry(term: str, synonym: str, domain: str, created_by: str, confidence: float = 0.8, context: Optional[str] = None, user_role: Optional[str] = None, department: Optional[str] = None, tags: Optional[List[str]] = None, notes: Optional[str] = None, status: SynonymStatus = SynonymStatus.PENDING) -> Optional[int]`

Add a new synonym entry.

Parameters:

term (str): The original term
synonym (str): The synonym
domain (str): Domain context
created_by (str): User who created the entry
confidence (float): Confidence score
context (Optional[str]): Additional context
user_role (Optional[str]): User role restriction
department (Optional[str]): Department restriction
tags (Optional[List[str]]): Tags for categorization
notes (Optional[str]): Additional notes
status (SynonymStatus): Entry status

Returns:

Optional[int]: Synonym entry ID if successful

`get_synonym_entries(domain: Optional[str] = None, status: Optional[SynonymStatus] = None, user_role: Optional[str] = None, department: Optional[str] = None, limit: int = 100, offset: int = 0) -> List[SynonymEntry]`

Get synonym entries with filtering.

Parameters:

domain (Optional[str]): Domain filter
status (Optional[SynonymStatus]): Status filter
user_role (Optional[str]): User role filter
department (Optional[str]): Department filter
limit (int): Maximum number of results
offset (int): Result offset

Returns:

List[SynonymEntry]: List of synonym entries

`bulk_import_synonyms(file_path: str, import_format: str = "csv", created_by: str, domain: Optional[str] = None) -> BulkImportResult`

Bulk import synonyms from file.

Parameters:

file_path (str): Path to import file
import_format (str): Import format (csv, json)
created_by (str): User performing import
domain (Optional[str]): Default domain

Returns:

BulkImportResult: Import operation result

`export_synonyms(output_path: str, export_format: str = "csv", domain: Optional[str] = None, status: Optional[SynonymStatus] = None) -> bool`

Export synonyms to file.

Parameters:

output_path (str): Output file path
export_format (str): Export format (csv, json)
domain (Optional[str]): Domain filter
status (Optional[SynonymStatus]): Status filter

Returns:

bool: Success status

REST API Endpoints

Query Expansion

`POST /query-expansion/expand`

Expand a query using multiple strategies.

Request Body:

{
    "query": "API documentation",
    "user_id": "user123",
    "user_role": "developer",
    "department": "engineering",
    "domain": "technical",
    "session_id": "session123",
    "enabled_strategies": ["synonym_expansion", "acronym_expansion"],
    "expansion_settings": {
        "max_expansions": 3,
        "confidence_threshold": 0.7
    }
}

Response:

{
    "original_query": "API documentation",
    "expanded_queries": [
        {
            "expanded_query": "API documentation OR Application Programming Interface documentation",
            "expansion_type": "synonym_expansion",
            "confidence_score": 0.9,
            "relevance_score": 0.8,
            "synonyms_used": [
                {
                    "term": "API",
                    "synonym": "Application Programming Interface",
                    "confidence": 0.9
                }
            ],
            "metadata": {
                "expanded_token": "API",
                "synonym_count": 1
            }
        }
    ],
    "expansion_metadata": {
        "total_expansions": 1,
        "strategies_used": ["synonym_expansion"],
        "avg_confidence": 0.9
    },
    "success": true
}

`POST /query-expansion/feedback`

Submit user feedback on expansion effectiveness.

Request Body:

{
    "expansion_id": "exp_123",
    "was_helpful": true,
    "rating": 5,
    "comment": "Very helpful expansion"
}

Response:

{
    "success": true,
    "message": "Feedback recorded successfully"
}

Synonym Management

`POST /query-expansion/synonyms`

Add a new synonym.

Request Body:

{
    "term": "ML",
    "synonym": "Machine Learning",
    "domain": "technical",
    "confidence": 0.9,
    "context": "artificial intelligence",
    "user_role": "developer",
    "department": "engineering",
    "tags": ["ai", "learning"],
    "notes": "Machine learning abbreviation"
}

Response:

{
    "success": true,
    "message": "Synonym added successfully",
    "synonym_id": 123
}

`GET /query-expansion/synonyms`

Get synonyms with filtering.

Query Parameters:

domain (optional): Domain filter
status (optional): Status filter
user_role (optional): User role filter
department (optional): Department filter
limit (optional): Maximum results (default: 100)
offset (optional): Result offset (default: 0)

Response:

{
    "synonyms": [
        {
            "id": 123,
            "term": "API",
            "synonym": "Application Programming Interface",
            "domain": "technical",
            "confidence": 0.9,
            "relevance_score": 0.8,
            "usage_count": 15,
            "success_rate": 0.85,
            "status": "active",
            "created_by": "admin_user",
            "created_at": "2024-01-01T00:00:00Z",
            "updated_at": "2024-01-01T00:00:00Z",
            "tags": ["programming", "interface"],
            "notes": "Common programming interface"
        }
    ],
    "total": 1
}

Analytics

`GET /query-expansion/analytics/expansion`

Get expansion analytics.

Query Parameters:

start_date (optional): Start date filter
end_date (optional): End date filter
domain (optional): Domain filter

Response:

{
    "metrics": {
        "total_expansions": 1000,
        "successful_expansions": 850,
        "success_rate": 0.85,
        "average_confidence": 0.78,
        "average_relevance": 0.82,
        "domain_breakdown": {
            "technical": 600,
            "business": 400
        },
        "user_satisfaction": 0.85,
        "expansion_quality_score": 0.81
    }
}

`GET /query-expansion/analytics/report`

Get comprehensive analytics report.

Query Parameters:

start_date (optional): Start date filter
end_date (optional): End date filter
domain (optional): Domain filter

Response:

{
    "report_metadata": {
        "generated_at": "2024-01-01T00:00:00Z",
        "start_date": "2024-01-01T00:00:00Z",
        "end_date": "2024-01-31T23:59:59Z",
        "domain": "technical"
    },
    "expansion_metrics": {...},
    "synonym_metrics": {...},
    "user_behavior_metrics": {...},
    "quality_metrics": {...},
    "insights": [
        {
            "type": "positive",
            "category": "expansion_effectiveness",
            "message": "High expansion success rate: 85%",
            "impact": "high"
        }
    ],
    "recommendations": [
        {
            "category": "expansion_optimization",
            "priority": "high",
            "action": "Improve expansion quality",
            "description": "Focus on improving synonym confidence and relevance scoring",
            "impact": "high"
        }
    ]
}

Error Handling

All API endpoints return appropriate HTTP status codes and error messages:

200 OK: Successful operation
400 Bad Request: Invalid request parameters
401 Unauthorized: Authentication required
403 Forbidden: Insufficient permissions
404 Not Found: Resource not found
500 Internal Server Error: Server error

Error responses include a detailed error message:

{
    "error": "Invalid query parameter",
    "message": "The 'query' parameter is required",
    "code": "MISSING_QUERY_PARAMETER"
}

Core Classes​

QueryExpansionSystem​

Methods​

expand_query(query: str, context: ExpansionContext, enabled_strategies: Optional[List[ExpansionType]] = None) -> List[ExpansionResult]​

add_synonym(term: str, synonym: str, domain: str, source: SynonymSource, confidence: float = 0.8, context: Optional[str] = None, user_role: Optional[str] = None, department: Optional[str] = None) -> bool​

record_feedback(expansion_result: ExpansionResult, user_id: str, was_helpful: bool, rating: Optional[int] = None, comment: Optional[str] = None)​

ExpansionContext​

Fields​

ExpansionResult​

Fields​

Enums​

ExpansionType​

SynonymSource​

Analytics API​

SynonymAnalytics​

Methods​

get_expansion_metrics(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, domain: Optional[str] = None) -> ExpansionMetrics​

get_synonym_metrics(domain: Optional[str] = None) -> SynonymMetrics​

get_user_behavior_metrics(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None) -> UserBehaviorMetrics​

generate_analytics_report(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, domain: Optional[str] = None) -> Dict[str, Any]​

Management API​

SynonymManagementSystem​

Methods​

get_synonym_entries(domain: Optional[str] = None, status: Optional[SynonymStatus] = None, user_role: Optional[str] = None, department: Optional[str] = None, limit: int = 100, offset: int = 0) -> List[SynonymEntry]​

bulk_import_synonyms(file_path: str, import_format: str = "csv", created_by: str, domain: Optional[str] = None) -> BulkImportResult​

export_synonyms(output_path: str, export_format: str = "csv", domain: Optional[str] = None, status: Optional[SynonymStatus] = None) -> bool​

REST API Endpoints​

Query Expansion​

POST /query-expansion/expand​

POST /query-expansion/feedback​

Synonym Management​

POST /query-expansion/synonyms​

GET /query-expansion/synonyms​

Analytics​

GET /query-expansion/analytics/expansion​

GET /query-expansion/analytics/report​

Error Handling​

Core Classes

QueryExpansionSystem

Methods

`expand_query(query: str, context: ExpansionContext, enabled_strategies: Optional[List[ExpansionType]] = None) -> List[ExpansionResult]`

`add_synonym(term: str, synonym: str, domain: str, source: SynonymSource, confidence: float = 0.8, context: Optional[str] = None, user_role: Optional[str] = None, department: Optional[str] = None) -> bool`

`record_feedback(expansion_result: ExpansionResult, user_id: str, was_helpful: bool, rating: Optional[int] = None, comment: Optional[str] = None)`

ExpansionContext

Fields

ExpansionResult

Fields

Enums

ExpansionType

SynonymSource

Analytics API

SynonymAnalytics

Methods

`get_expansion_metrics(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, domain: Optional[str] = None) -> ExpansionMetrics`

`get_synonym_metrics(domain: Optional[str] = None) -> SynonymMetrics`

`get_user_behavior_metrics(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None) -> UserBehaviorMetrics`

`generate_analytics_report(start_date: Optional[datetime] = None, end_date: Optional[datetime] = None, domain: Optional[str] = None) -> Dict[str, Any]`

Management API

SynonymManagementSystem

Methods

`get_synonym_entries(domain: Optional[str] = None, status: Optional[SynonymStatus] = None, user_role: Optional[str] = None, department: Optional[str] = None, limit: int = 100, offset: int = 0) -> List[SynonymEntry]`

`bulk_import_synonyms(file_path: str, import_format: str = "csv", created_by: str, domain: Optional[str] = None) -> BulkImportResult`

`export_synonyms(output_path: str, export_format: str = "csv", domain: Optional[str] = None, status: Optional[SynonymStatus] = None) -> bool`

REST API Endpoints

Query Expansion

`POST /query-expansion/expand`

`POST /query-expansion/feedback`

Synonym Management

`POST /query-expansion/synonyms`

`GET /query-expansion/synonyms`

Analytics

`GET /query-expansion/analytics/expansion`

`GET /query-expansion/analytics/report`

Error Handling