chat_agent/api/README.md

# Chat Agent API Documentation

This document describes the REST API endpoints for the multi-language chat agent.

## Base URL

All API endpoints are prefixed with `/api/v1/chat`

## Authentication

All endpoints (except health check and supported languages) require authentication via one of the following methods:

### Header-based Authentication (Development)
```

X-User-ID: your-user-id

```

### Token-based Authentication (Production)
```

Authorization: Bearer your-session-token

```

## Rate Limiting

The API implements rate limiting to prevent abuse:
- Default: 200 requests per day, 50 requests per hour
- Session creation: 10 requests per minute
- Session deletion: 5 requests per minute
- Other endpoints: 20-30 requests per minute

Rate limit exceeded responses return HTTP 429 with retry information.

## Endpoints

### 1. Get Supported Languages

Get a list of all supported programming languages.

**Endpoint:** `GET /api/v1/chat/languages`

**Authentication:** Not required

**Response:**
```json

{

  "languages": [

    {

      "code": "python",

      "name": "Python",

      "syntax_highlighting": "python",

      "file_extensions": [".py", ".pyw"]

    },

    {

      "code": "javascript",

      "name": "JavaScript", 

      "syntax_highlighting": "javascript",

      "file_extensions": [".js", ".mjs"]

    }

  ],

  "default_language": "python",

  "total_count": 8

}

```

### 2. Create Chat Session

Create a new chat session for a user.

**Endpoint:** `POST /api/v1/chat/sessions`

**Authentication:** Required

**Request Body:**
```json

{

  "language": "python",

  "metadata": {

    "source": "web_app",

    "user_preferences": {}

  }

}

```

**Response (201 Created):**
```json

{

  "session_id": "uuid-string",

  "user_id": "user-123",

  "language": "python",

  "created_at": "2023-01-01T00:00:00",

  "message_count": 0,

  "metadata": {

    "source": "web_app"

  }

}

```

**Error Responses:**
- `400 Bad Request`: Invalid language or missing required fields
- `401 Unauthorized`: Missing or invalid authentication
- `429 Too Many Requests`: Rate limit exceeded

### 3. Get Chat Session

Retrieve information about a specific chat session.

**Endpoint:** `GET /api/v1/chat/sessions/{session_id}`

**Authentication:** Required (must own the session)

**Response (200 OK):**
```json

{

  "session_id": "uuid-string",

  "user_id": "user-123",

  "language": "python",

  "created_at": "2023-01-01T00:00:00",

  "last_active": "2023-01-01T01:00:00",

  "message_count": 5,

  "is_active": true,

  "metadata": {}

}

```

**Error Responses:**
- `403 Forbidden`: Session belongs to different user
- `404 Not Found`: Session does not exist
- `410 Gone`: Session has expired

### 4. List User Sessions

Get all sessions for the authenticated user.

**Endpoint:** `GET /api/v1/chat/sessions`

**Authentication:** Required

**Query Parameters:**
- `active_only` (boolean, default: true): Only return active sessions

**Response (200 OK):**
```json

{

  "sessions": [

    {

      "session_id": "uuid-string",

      "language": "python",

      "created_at": "2023-01-01T00:00:00",

      "last_active": "2023-01-01T01:00:00",

      "message_count": 5,

      "is_active": true,

      "metadata": {}

    }

  ],

  "total_count": 1,

  "active_only": true

}

```

### 5. Delete Chat Session

Delete a chat session and all associated data.

**Endpoint:** `DELETE /api/v1/chat/sessions/{session_id}`

**Authentication:** Required (must own the session)

**Response (200 OK):**
```json

{

  "message": "Session deleted successfully",

  "session_id": "uuid-string",

  "messages_deleted": 10

}

```

**Error Responses:**
- `403 Forbidden`: Session belongs to different user
- `404 Not Found`: Session does not exist

### 6. Get Chat History

Retrieve chat history for a session.

**Endpoint:** `GET /api/v1/chat/sessions/{session_id}/history`

**Authentication:** Required (must own the session)

**Query Parameters:**
- `page` (integer, default: 1): Page number for pagination
- `page_size` (integer, default: 50, max: 100): Messages per page
- `recent_only` (boolean, default: false): Get only recent messages
- `limit` (integer, default: 10, max: 50): Number of recent messages (when recent_only=true)



**Response (200 OK):**

```json

{

  "messages": [

    {

      "id": "uuid-string",

      "role": "user",

      "content": "Hello, can you help me with Python?",

      "language": "python",

      "timestamp": "2023-01-01T00:00:00",

      "metadata": {}

    },

    {

      "id": "uuid-string",

      "role": "assistant", 

      "content": "Of course! I'd be happy to help you with Python.",

      "language": "python",

      "timestamp": "2023-01-01T00:01:00",

      "metadata": {

        "tokens": 15

      }

    }

  ],

  "session_id": "uuid-string",
  "total_count": 2,

  "page": 1,

  "page_size": 50,
  "total_pages": 1

}

```



### 7. Search Chat History



Search messages within a session.



**Endpoint:** `GET /api/v1/chat/sessions/{session_id}/history/search`

**Authentication:** Required (must own the session)

**Query Parameters:**
- `q` (string, required, min: 3 chars): Search query
- `limit` (integer, default: 20, max: 50): Maximum results

**Response (200 OK):**
```json

{

  "messages": [

    {

      "id": "uuid-string",

      "role": "user",

      "content": "How do I use Python lists?",

      "language": "python",

      "timestamp": "2023-01-01T00:00:00",

      "metadata": {}

    }

  ],

  "session_id": "uuid-string",

  "query": "Python",

  "result_count": 1

}

```

**Error Responses:**
- `400 Bad Request`: Query too short or missing

### 8. Get Language Context

Get the current language context for a session.

**Endpoint:** `GET /api/v1/chat/sessions/{session_id}/language`

**Authentication:** Required (must own the session)

**Response (200 OK):**
```json

{

  "session_id": "uuid-string",

  "language": "python",

  "prompt_template": "You are a helpful Python programming assistant...",

  "syntax_highlighting": "python",

  "language_info": {

    "name": "Python",

    "syntax_highlighting": "python",

    "file_extensions": [".py", ".pyw"],

    "prompt_template": "..."

  },

  "updated_at": "2023-01-01T00:00:00"

}

```

### 9. Update Language Context

Change the programming language for a session.

**Endpoint:** `PUT /api/v1/chat/sessions/{session_id}/language`

**Authentication:** Required (must own the session)

**Request Body:**
```json

{

  "language": "javascript"

}

```

**Response (200 OK):**
```json

{

  "session_id": "uuid-string",

  "language": "javascript",

  "prompt_template": "You are a helpful JavaScript programming assistant...",

  "syntax_highlighting": "javascript",

  "language_info": {

    "name": "JavaScript",

    "syntax_highlighting": "javascript",

    "file_extensions": [".js", ".mjs"],

    "prompt_template": "..."

  },

  "updated_at": "2023-01-01T01:00:00"

}

```

**Error Responses:**
- `400 Bad Request`: Unsupported language

### 10. Health Check

Check the health status of the API and its dependencies.

**Endpoint:** `GET /api/v1/chat/health`

**Authentication:** Not required

**Response (200 OK):**
```json

{

  "status": "healthy",

  "timestamp": "2023-01-01T00:00:00",

  "services": {

    "database": "connected",

    "redis": "connected"

  }

}

```

**Response (503 Service Unavailable):**
```json

{

  "status": "unhealthy",

  "timestamp": "2023-01-01T00:00:00",

  "error": "Database connection failed"

}

```

## Error Responses

All error responses follow a consistent format:

```json

{

  "error": "Error type",

  "message": "Detailed error message"

}

```

### Common HTTP Status Codes

- `200 OK`: Request successful
- `201 Created`: Resource created successfully
- `400 Bad Request`: Invalid request data
- `401 Unauthorized`: Authentication required
- `403 Forbidden`: Access denied
- `404 Not Found`: Resource not found
- `410 Gone`: Resource expired
- `429 Too Many Requests`: Rate limit exceeded
- `500 Internal Server Error`: Server error
- `503 Service Unavailable`: Service temporarily unavailable

## Security Considerations

1. **Authentication**: All endpoints require valid authentication
2. **Authorization**: Users can only access their own sessions
3. **Rate Limiting**: Prevents abuse and manages API costs
4. **Input Validation**: All inputs are validated and sanitized
5. **Error Handling**: Errors don't expose sensitive information

## Usage Examples

### Create a Session and Send Messages

```bash

# Create session

curl -X POST http://localhost:5000/api/v1/chat/sessions \

  -H "X-User-ID: user-123" \

  -H "Content-Type: application/json" \

  -d '{"language": "python"}'



# Get session info

curl -X GET http://localhost:5000/api/v1/chat/sessions/{session_id} \

  -H "X-User-ID: user-123"



# Change language

curl -X PUT http://localhost:5000/api/v1/chat/sessions/{session_id}/language \

  -H "X-User-ID: user-123" \

  -H "Content-Type: application/json" \

  -d '{"language": "javascript"}'



# Get chat history

curl -X GET http://localhost:5000/api/v1/chat/sessions/{session_id}/history \

  -H "X-User-ID: user-123"



# Delete session

curl -X DELETE http://localhost:5000/api/v1/chat/sessions/{session_id} \

  -H "X-User-ID: user-123"

```

### JavaScript/TypeScript Example

```javascript

const API_BASE = 'http://localhost:5000/api/v1/chat';

const USER_ID = 'user-123';



// Create session

const response = await fetch(`${API_BASE}/sessions`, {

  method: 'POST',

  headers: {

    'X-User-ID': USER_ID,

    'Content-Type': 'application/json'

  },

  body: JSON.stringify({

    language: 'python',

    metadata: { source: 'web_app' }

  })

});



const session = await response.json();

console.log('Created session:', session.session_id);



// Get chat history

const historyResponse = await fetch(

  `${API_BASE}/sessions/${session.session_id}/history`,

  {

    headers: { 'X-User-ID': USER_ID }

  }

);



const history = await historyResponse.json();

console.log('Messages:', history.messages);

```

## WebSocket API Documentation

The chat agent also supports real-time communication via WebSocket for interactive chat sessions.

### WebSocket Connection

**Endpoint:** `ws://localhost:5000/socket.io/`

**Authentication:** Include user ID in connection query parameters or headers

**Connection Example:**
```javascript

const socket = io('http://localhost:5000', {

  query: { user_id: 'user-123' },

  transports: ['websocket']

});

```

### WebSocket Events

#### 1. Connect Event
Automatically triggered when client connects.

**Client sends:**
```javascript

// Connection is automatic, but you can send auth data

socket.emit('authenticate', {

  user_id: 'user-123',

  session_token: 'optional-token'

});

```

**Server responds:**
```javascript

socket.on('connected', (data) => {

  console.log(data);

  // {

  //   "status": "connected",

  //   "user_id": "user-123",

  //   "timestamp": "2023-01-01T00:00:00Z"

  // }

});

```

#### 2. Send Message Event
Send a chat message to the assistant.

**Client sends:**
```javascript

socket.emit('message', {

  session_id: 'session-uuid',

  content: 'How do I create a Python list?',

  language: 'python',

  metadata: {

    source: 'web_chat',

    timestamp: new Date().toISOString()

  }

});

```

**Server responds:**
```javascript

socket.on('message_response', (data) => {

  console.log(data);

  // {

  //   "session_id": "session-uuid",

  //   "message_id": "msg-uuid",

  //   "content": "To create a Python list, you can use square brackets...",

  //   "language": "python",

  //   "timestamp": "2023-01-01T00:01:00Z",

  //   "metadata": {

  //     "tokens": 45,

  //     "response_time": 0.85

  //   }

  // }

});

```

#### 3. Streaming Response Event
For real-time streaming responses.

**Client sends:**
```javascript

socket.emit('message_stream', {

  session_id: 'session-uuid',

  content: 'Explain Python functions in detail',

  language: 'python'

});

```

**Server responds with multiple events:**
```javascript

socket.on('stream_start', (data) => {

  // { "session_id": "session-uuid", "message_id": "msg-uuid" }

});



socket.on('stream_chunk', (data) => {

  // { "session_id": "session-uuid", "chunk": "A Python function is..." }

});



socket.on('stream_end', (data) => {

  // { "session_id": "session-uuid", "complete_response": "..." }

});

```

#### 4. Language Switch Event
Change the programming language context.

**Client sends:**
```javascript

socket.emit('language_switch', {

  session_id: 'session-uuid',

  language: 'javascript'

});

```

**Server responds:**
```javascript

socket.on('language_switched', (data) => {

  // {

  //   "session_id": "session-uuid",

  //   "previous_language": "python",

  //   "new_language": "javascript",

  //   "timestamp": "2023-01-01T00:02:00Z"

  // }

});

```

#### 5. Typing Indicator Events
Show when user or assistant is typing.

**Client sends:**
```javascript

socket.emit('typing_start', {

  session_id: 'session-uuid'

});



socket.emit('typing_stop', {

  session_id: 'session-uuid'

});

```

**Server responds:**
```javascript

socket.on('assistant_typing', (data) => {

  // { "session_id": "session-uuid", "typing": true }

});



socket.on('assistant_typing_stop', (data) => {

  // { "session_id": "session-uuid", "typing": false }

});

```

#### 6. Error Events
Handle various error conditions.

**Server sends:**
```javascript

socket.on('error', (data) => {

  console.error(data);

  // {

  //   "error": "session_not_found",

  //   "message": "Session does not exist or has expired",

  //   "session_id": "session-uuid",

  //   "timestamp": "2023-01-01T00:03:00Z"

  // }

});

```

### Complete WebSocket Example

```html

<!DOCTYPE html>

<html>

<head>

    <title>Chat Agent WebSocket Example</title>

    <script src="https://cdn.socket.io/4.0.0/socket.io.min.js"></script>

</head>

<body>

    <div id="messages"></div>

    <input type="text" id="messageInput" placeholder="Type your message...">

    <select id="languageSelect">

        <option value="python">Python</option>

        <option value="javascript">JavaScript</option>

        <option value="java">Java</option>

    </select>

    <button onclick="sendMessage()">Send</button>



    <script>

        const socket = io('http://localhost:5000', {

            query: { user_id: 'demo-user' }

        });



        let currentSessionId = null;



        // Create session first

        fetch('/api/v1/chat/sessions', {

            method: 'POST',

            headers: {

                'X-User-ID': 'demo-user',

                'Content-Type': 'application/json'

            },

            body: JSON.stringify({ language: 'python' })

        })

        .then(response => response.json())

        .then(data => {

            currentSessionId = data.session_id;

            console.log('Session created:', currentSessionId);

        });



        // Handle connection

        socket.on('connected', (data) => {

            console.log('Connected to chat agent:', data);

        });



        // Handle messages

        socket.on('message_response', (data) => {

            addMessage('Assistant', data.content);

        });



        // Handle streaming

        let streamBuffer = '';

        socket.on('stream_chunk', (data) => {

            streamBuffer += data.chunk;

            updateStreamingMessage(streamBuffer);

        });



        socket.on('stream_end', (data) => {

            addMessage('Assistant', data.complete_response);

            streamBuffer = '';

        });



        // Handle language switches

        socket.on('language_switched', (data) => {

            console.log('Language switched:', data);

            addMessage('System', `Language changed to ${data.new_language}`);

        });



        // Handle errors

        socket.on('error', (data) => {

            console.error('Chat error:', data);

            addMessage('Error', data.message);

        });



        function sendMessage() {

            const input = document.getElementById('messageInput');

            const message = input.value.trim();

            

            if (message && currentSessionId) {

                addMessage('You', message);

                

                socket.emit('message', {

                    session_id: currentSessionId,

                    content: message,

                    language: document.getElementById('languageSelect').value

                });

                

                input.value = '';

            }

        }



        function addMessage(sender, content) {

            const messages = document.getElementById('messages');

            const messageDiv = document.createElement('div');

            messageDiv.innerHTML = `<strong>${sender}:</strong> ${content}`;

            messages.appendChild(messageDiv);

            messages.scrollTop = messages.scrollHeight;

        }



        // Language switching

        document.getElementById('languageSelect').addEventListener('change', (e) => {

            if (currentSessionId) {

                socket.emit('language_switch', {

                    session_id: currentSessionId,

                    language: e.target.value

                });

            }

        });



        // Enter key to send message

        document.getElementById('messageInput').addEventListener('keypress', (e) => {

            if (e.key === 'Enter') {

                sendMessage();

            }

        });

    </script>

</body>

</html>

```

## Advanced Usage Examples

### Error Handling and Retry Logic

```javascript

class ChatAPIClient {

    constructor(baseURL, userID) {

        this.baseURL = baseURL;

        this.userID = userID;

        this.maxRetries = 3;

        this.retryDelay = 1000; // 1 second

    }



    async makeRequest(endpoint, options = {}) {

        const url = `${this.baseURL}${endpoint}`;

        const config = {

            ...options,

            headers: {

                'X-User-ID': this.userID,

                'Content-Type': 'application/json',

                ...options.headers

            }

        };



        for (let attempt = 1; attempt <= this.maxRetries; attempt++) {

            try {

                const response = await fetch(url, config);

                

                if (response.status === 429) {

                    // Rate limited - wait and retry

                    const retryAfter = response.headers.get('Retry-After') || this.retryDelay / 1000;

                    await this.sleep(retryAfter * 1000);

                    continue;

                }

                

                if (!response.ok) {

                    const error = await response.json();

                    throw new Error(`API Error: ${error.message}`);

                }

                

                return await response.json();

                

            } catch (error) {

                if (attempt === this.maxRetries) {

                    throw error;

                }

                

                console.warn(`Attempt ${attempt} failed, retrying...`, error.message);

                await this.sleep(this.retryDelay * attempt);

            }

        }

    }



    async createSession(language = 'python') {

        return await this.makeRequest('/api/v1/chat/sessions', {

            method: 'POST',

            body: JSON.stringify({ language })

        });

    }



    async getChatHistory(sessionId, page = 1, pageSize = 50) {

        return await this.makeRequest(

            `/api/v1/chat/sessions/${sessionId}/history?page=${page}&page_size=${pageSize}`

        );

    }



    async switchLanguage(sessionId, language) {

        return await this.makeRequest(`/api/v1/chat/sessions/${sessionId}/language`, {

            method: 'PUT',

            body: JSON.stringify({ language })

        });

    }



    sleep(ms) {

        return new Promise(resolve => setTimeout(resolve, ms));

    }

}



// Usage

const client = new ChatAPIClient('http://localhost:5000', 'user-123');



try {

    const session = await client.createSession('python');

    console.log('Session created:', session.session_id);

    

    const history = await client.getChatHistory(session.session_id);

    console.log('Chat history:', history.messages);

    

    await client.switchLanguage(session.session_id, 'javascript');

    console.log('Language switched to JavaScript');

    

} catch (error) {

    console.error('API operation failed:', error.message);

}

```

### Batch Operations

```python

import asyncio

import aiohttp

import json



class AsyncChatClient:

    def __init__(self, base_url, user_id):

        self.base_url = base_url

        self.user_id = user_id

        self.headers = {

            'X-User-ID': user_id,

            'Content-Type': 'application/json'

        }

    

    async def create_multiple_sessions(self, languages):

        """Create multiple sessions concurrently."""

        async with aiohttp.ClientSession() as session:

            tasks = []

            for language in languages:

                task = self._create_session(session, language)

                tasks.append(task)

            

            results = await asyncio.gather(*tasks, return_exceptions=True)

            return results

    

    async def _create_session(self, session, language):

        url = f"{self.base_url}/api/v1/chat/sessions"

        data = {"language": language}

        

        async with session.post(url, headers=self.headers, json=data) as response:

            if response.status == 201:

                return await response.json()

            else:

                error = await response.json()

                raise Exception(f"Failed to create {language} session: {error['message']}")



# Usage

async def main():

    client = AsyncChatClient('http://localhost:5000', 'batch-user')

    languages = ['python', 'javascript', 'java', 'cpp']

    

    sessions = await client.create_multiple_sessions(languages)

    

    for i, session in enumerate(sessions):

        if isinstance(session, Exception):

            print(f"Failed to create {languages[i]} session: {session}")

        else:

            print(f"Created {languages[i]} session: {session['session_id']}")



# Run the async function

asyncio.run(main())

```

## Implementation Notes

- The API uses SQLite for testing and PostgreSQL for production
- Redis is used for caching and session management
- Rate limiting uses in-memory storage by default (configure Redis for production)
- All timestamps are in ISO 8601 format (UTC)
- UUIDs are used for all resource identifiers
- The API supports both development (header-based) and production (token-based) authentication
- WebSocket connections are managed using Flask-SocketIO
- Streaming responses use Server-Sent Events (SSE) over WebSocket
- All WebSocket events include session_id for proper message routing

- Error handling includes automatic retry logic for transient failures

- The system supports concurrent operations across multiple sessions