Skip to content

API_README.md

Latest commit

 

History

History
351 lines (282 loc) · 9.17 KB

API_README.md

File metadata and controls

351 lines (282 loc) · 9.17 KB

BI Assistant API Service

A comprehensive FastAPI-based service for the BI Assistant with stateful session management and streaming support.

Project Structure

bi_assistant/
├── api/                          # API package
│   ├── __init__.py              # Package initialization  
│   ├── main.py                  # FastAPI application setup
│   ├── models/                  # Pydantic models
│   │   ├── __init__.py
│   │   ├── session.py           # Session-related models
│   │   ├── chat.py              # Chat-related models  
│   │   └── auth.py              # Auth models (future)
│   ├── routes/                  # API route handlers
│   │   ├── __init__.py
│   │   ├── session.py           # Session endpoints
│   │   ├── chat.py              # Chat endpoints
│   │   └── health.py            # Health/utility endpoints
│   ├── services/                # Business logic services
│   │   ├── __init__.py
│   │   ├── session_manager.py   # Session management
│   │   └── chat_service.py      # Chat processing
│   └── middleware/              # Middleware components
│       ├── __init__.py
│       └── auth.py              # Auth middleware (future)
├── src/                         # Original BI Agent source
├── server.py                    # Main server entry point
├── api_client_example.py        # Client usage example
├── docker-compose.yml           # Docker deployment
└── Dockerfile                   # Container configuration

Features

  • Stateful Sessions: Persistent conversation sessions with automatic cleanup
  • Streaming Support: Real-time streaming responses for better user experience
  • RESTful API: Clean, well-documented REST endpoints
  • Session Management: Create, manage, and track multiple user sessions
  • Conversation History: Persistent conversation tracking per session
  • Error Handling: Comprehensive error handling and logging
  • Docker Support: Ready-to-deploy Docker configuration
  • Production Ready: Nginx configuration and health checks included

Architecture

The service is built around several key components:

Core Components

  1. Session Manager: Manages user sessions, handles timeouts, and cleanup
  2. BI Agent Integration: Seamless integration with the existing BI Agent
  3. Streaming Handler: Manages real-time streaming responses
  4. State Management: Maintains conversation state across requests

API Endpoints

Session Management

  • POST /sessions - Create a new session
  • GET /sessions - List all active sessions
  • GET /sessions/{session_id} - Get session information
  • DELETE /sessions/{session_id} - Delete a session
  • GET /sessions/{session_id}/history - Get conversation history
  • GET /sessions/{session_id}/capabilities - Get available capabilities

Chat Endpoints

  • POST /chat - Send message (non-streaming)
  • POST /chat/stream - Send message (streaming)

Utility Endpoints

  • GET / - Service information
  • GET /health - Health check

Quick Start

Development Setup

  1. Install Dependencies

    pip install -r api_requirements.txt

  2. Set Environment Variables Create a .env file:

    # Database configuration
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=your_database
POSTGRES_USER=your_user
POSTGRES_PASSWORD=your_password

# LLM API keys
OPENAI_API_KEY=your_openai_key
GOOGLE_API_KEY=your_google_key

# Optional: Qdrant configuration
QDRANT_URL=your_qdrant_url
QDRANT_API_KEY=your_qdrant_key

  3. Run the Service

    python server.py

    The service will be available at http://localhost:8888

  4. View API Documentation

    • Swagger UI: http://localhost:8888/docs
    • ReDoc: http://localhost:8888/redoc

Production Deployment with Docker

  1. Build and Run with Docker Compose

    docker-compose up -d

    This will start:

    • BI Assistant API service
    • PostgreSQL database
    • Nginx reverse proxy

  2. Access the Service

    • API: http://localhost:8888
    • Through Nginx: http://localhost:80

Usage Examples

Using cURL

  1. Create a Session

    curl -X POST "http://localhost:8888/sessions" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "Test User",
    "user_role": "BI",
    "preferred_language": "en",
    "streaming": true
  }'

  2. Send a Chat Message (Non-streaming)

    curl -X POST "http://localhost:8888/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, what can you help me with?",
    "session_id": "your-session-id"
  }'

{"message":"tell me more","session_id":"6aab113e-771a-48c2-a8c1-62d6d96f6100"} 3. Send a Chat Message (Streaming)

curl -X POST "http://localhost:8888/chat/stream" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Hello, what can you help me with?",
    "session_id": "6aab113e-771a-48c2-a8c1-62d6d96f6100"
  }'
  1. Get Session Information 
    curl "http://localhost:8888/sessions/your-session-id"

Using JavaScript/Fetch

// Create session
const createSession = async () => {
  const response = await fetch('/sessions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      username: 'Web User',
      user_role: 'Analyst',
      streaming: true
    })
  });
  return await response.json();
};

// Streaming chat
const streamingChat = async (sessionId, message) => {
  const response = await fetch('/chat/stream', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      message: message,
      session_id: sessionId
    })
  });

  const reader = response.body.getReader();
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const text = new TextDecoder().decode(value);
    const lines = text.split('\n');
    
    for (const line of lines) {
      if (line.startsWith('data: ')) {
        const data = JSON.parse(line.slice(6));
        console.log('Stream data:', data);
      }
    }
  }
};

Configuration

Session Configuration

Sessions can be configured with the following parameters:

  • username: Display name for the user
  • user_role: User's role (affects prompt behavior)
  • preferred_language: Language preference (en, vi, etc.)
  • preferred_generation_format: Chart generation preferences
  • streaming: Enable/disable streaming by default

Service Configuration

Key configuration options in api_service.py:

# Session timeout (default: 2 hours)
session_timeout = timedelta(hours=2)

# Cleanup interval (default: 5 minutes)
cleanup_interval = 300

# CORS settings
allow_origins = ["*"]  # Configure for production

API Response Formats

Session Info Response

{
  "session_id": "uuid",
  "username": "John Doe",
  "user_role": "Data Analyst",
  "preferred_language": "en",
  "created_at": "2024-01-01T10:00:00",
  "last_activity": "2024-01-01T10:30:00",
  "message_count": 5,
  "streaming_enabled": true,
  "status": "active"
}

Chat Response (Non-streaming)

{
  "session_id": "uuid",
  "message_id": "uuid",
  "response": "Generated response text",
  "success": true,
  "iterations": 2,
  "exist_reason": "response_generated",
  "error": null,
  "timestamp": "2024-01-01T10:30:00"
}

Streaming Response Format

data: {"type": "start", "session_id": "uuid", "message_id": "uuid"}

data: {"type": "text", "text": "Hello, I can help you with..."}

data: {"type": "complete", "session_id": "uuid", "success": true, "iterations": 1}

Error Handling

The API returns appropriate HTTP status codes:

  • 200: Success
  • 404: Session not found
  • 410: Session expired
  • 422: Validation error
  • 500: Internal server error

Error responses include detailed messages:

{
  "detail": "Session not found"
}

Monitoring and Logging

Health Check

curl http://localhost:8888/health

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T10:30:00",
  "active_sessions": 3
}

Debugging

Enable debug mode by setting:

uvicorn.run(
    "api_service:app",
    host="0.0.0.0",
    port=8888,
    reload=True,
    log_level="debug"  # Enable debug logging
)

Troubleshooting

Common Issues

  1. Import Errors: Ensure the src directory is in the Python path
  2. Database Connection: Check PostgreSQL credentials and connectivity
  3. Session Timeouts: Adjust session_timeout in SessionManager
  4. Memory Usage: Monitor session cleanup and consider reducing timeout
  5. Streaming Issues: Check client implementation of Server-Sent Events

Performance Optimization

  1. Connection Pooling: Configure database connection pooling
  2. Async Processing: Use background tasks for heavy operations
  3. Caching: Implement Redis for session storage
  4. Load Balancing: Use multiple API instances with nginx

License

[Add your license information here]