API Documentation¶

This section contains comprehensive documentation for the RAG Modulo API and its simplified architecture.

Search API¶

Core Components¶

• Search API - Complete search API documentation with automatic pipeline resolution
• Search Schemas - Data structures for search requests and responses

Key Features¶

Simplified Pipeline Resolution: The search API now automatically handles pipeline selection based on user context, eliminating client-side pipeline management complexity.

Breaking Changes from Legacy API: - Removed pipeline_id from SearchInput schema - Added automatic pipeline resolution in SearchService - Simplified CLI interface without pipeline parameters - Enhanced error handling for configuration issues

Service Architecture¶

Backend Services¶

• Service Configuration - Service-based configuration system
• Provider Configuration - LLM provider and model management
• Prompt Templates - Template management system
• Question Suggestion - Intelligent query suggestions
• Custom Voice API - Voice sample upload and custom voice management

Development Documentation¶

Development-specific documentation has been moved to: - Backend Development - Guidelines and development tasks

Migration Guide¶

From Legacy API¶

Before (Legacy):

# Client had to manage pipeline selection
pipeline_id = get_user_pipeline(user_id, collection_id)
search_input = SearchInput(
    question="What is ML?",
    collection_id=collection_id,
    user_id=user_id,
    pipeline_id=pipeline_id  # Client-managed
)

After (Current):

# Backend handles pipeline selection automatically
search_input = SearchInput(
    question="What is ML?",
    collection_id=collection_id,
    user_id=user_id
    # No pipeline_id needed
)

Schema Changes¶

1. SearchInput Schema:
2. ✅ Removed pipeline_id field
3. ✅ Added extra="forbid" validation

4. ✅ Simplified field requirements

5. Service Layer:

6. ✅ Added automatic pipeline resolution
7. ✅ Enhanced error handling

8. ✅ Improved user experience

9. CLI Interface:

10. ✅ Removed pipeline parameters
11. ✅ Simplified command structure
12. ✅ Automatic configuration

Testing¶

Test Coverage¶

• Unit Tests: Schema validation, service logic, pipeline resolution
• Integration Tests: End-to-end search flow, database integration
• API Tests: Endpoint validation, error handling

Running Tests¶

# Schema and service tests
pytest backend/tests/unit/test_search_service_pipeline_resolution.py

# Integration tests
pytest backend/tests/integration/test_search_integration.py

# API endpoint tests
pytest backend/tests/api/test_search_endpoints.py

Performance Considerations¶

Automatic Pipeline Creation¶

• First search for new users triggers pipeline creation
• Pipeline creation includes LLM provider validation
• Default configurations applied automatically
• All operations logged for audit

Caching Strategy¶

• Response caching based on search input hash
• Pipeline resolution results cached per user
• Configurable cache TTL (default: 1 hour)

Security¶

Access Control¶

• User authentication required for all operations
• Collection access validation
• Pipeline isolation between users
• Audit logging for all search activities

Input Validation¶

• Strict schema validation with extra="forbid"
• Query length and content validation
• Configuration parameter range checking
• SQL injection prevention

Error Handling¶

Common Error Scenarios¶

1. Configuration Errors:
2. No LLM provider configured
3. Invalid provider credentials

4. Missing pipeline configuration

5. Access Errors:

6. Collection not found or access denied
7. User authentication failures

8. Rate limiting violations

9. Validation Errors:

10. Invalid search input format
11. Parameter out of range
12. Malformed configuration metadata

Error Response Format¶

{
    "detail": "Error description",
    "error_code": "STANDARDIZED_ERROR_CODE",
    "timestamp": "2023-12-07T10:30:00Z",
    "request_id": "req-unique-id",
    "user_id": "user-uuid-if-available"
}

Future Enhancements¶

Planned Improvements¶

1. Enhanced Pipeline Resolution:
2. Context-aware pipeline selection
3. Collection-specific optimizations

4. A/B testing support

5. Advanced Search Features:

6. Multi-collection search
7. Streaming responses

8. Real-time suggestions

9. Performance Optimizations:

10. Parallel processing
11. Predictive caching

12. Resource optimization

13. Analytics and Monitoring:

14. Search quality metrics
15. Performance dashboards
16. Usage analytics

Support¶

For additional help: - Check the troubleshooting guide - Review configuration options - See development workflow

Last Updated: December 2023 API Version: 2.0 (Simplified Pipeline Resolution)