# {{name}}

{{description}}

## Overview

This project provides a REST API server exposing Lab agents and RAG assistants via HTTP endpoints. Built with FastAPI, it supports both streaming and non-streaming responses.

## Prerequisites

1. **PyGEAI installed and configured:**
   ```bash
   pip install pygeai
   geai configure --key YOUR_API_KEY --url YOUR_API_URL
   ```

2. **Python 3.8+**

## Installation

Install dependencies:

```bash
pip install -r requirements.txt
```

## Usage

Start the server:

```bash
python server.py
```

The server will start on `http://localhost:8000`

## API Endpoints

### Health Check

```bash
GET /health
```

Returns:
```json
{"status": "healthy"}
```

### Chat Completion

```bash
POST /chat
```

Request body:
```json
{
  "model": "saia:agent:my_agent",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false,
  "temperature": 0.7,
  "max_tokens": 1000
}
```

Response:
```json
{
  "content": "Response from agent...",
  "model": "saia:agent:my_agent"
}
```

### Streaming Chat Completion

```bash
POST /chat/stream
```

Same request format as `/chat`, but returns streaming text response.

Example with curl:
```bash
curl -X POST http://localhost:8000/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "model": "saia:agent:my_agent",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## Model Formats

Specify the model using these formats:

- **Lab agents:** `saia:agent:agent_name`
- **RAG assistants:** `saia:assistant:assistant_name`

## Interactive Documentation

FastAPI provides interactive API documentation:

- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc

## Example Client Code

### Python

```python
import requests

response = requests.post(
    "http://localhost:8000/chat",
    json={
        "model": "saia:agent:my_agent",
        "messages": [
            {"role": "user", "content": "What is machine learning?"}
        ],
        "temperature": 0.7
    }
)

print(response.json()["content"])
```

### JavaScript (fetch)

```javascript
const response = await fetch('http://localhost:8000/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'saia:agent:my_agent',
    messages: [
      {role: 'user', content: 'What is machine learning?'}
    ],
    temperature: 0.7
  })
});

const data = await response.json();
console.log(data.content);
```

### Streaming with Python

```python
import requests

response = requests.post(
    "http://localhost:8000/chat/stream",
    json={
        "model": "saia:agent:my_agent",
        "messages": [
            {"role": "user", "content": "Tell me a story"}
        ]
    },
    stream=True
)

for chunk in response.iter_content(chunk_size=None, decode_unicode=True):
    print(chunk, end='', flush=True)
```

## Customization

### Change Port

Edit `server.py`:

```python
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=5000)  # Changed from 8000
```

### Add Authentication

Add middleware in `server.py`:

```python
from fastapi import Header, HTTPException

async def verify_token(x_token: str = Header()):
    if x_token != "expected-token":
        raise HTTPException(status_code=403, detail="Invalid token")

@app.post("/chat", dependencies=[Depends(verify_token)])
def chat_completion(request: ChatRequest):
    # ... existing code
```

### Add CORS

```python
from fastapi.middleware.cors import CORSMiddleware

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)
```

### Add Logging

```python
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

@app.post("/chat")
def chat_completion(request: ChatRequest):
    logger.info(f"Chat request for model: {request.model}")
    # ... existing code
```

## Deployment

### With Docker

Create `Dockerfile`:

```dockerfile
FROM python:3.11-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY server.py .

CMD ["python", "server.py"]
```

Build and run:

```bash
docker build -t pygeai-api-server .
docker run -p 8000:8000 pygeai-api-server
```

### With Gunicorn

```bash
pip install gunicorn
gunicorn -w 4 -k uvicorn.workers.UvicornWorker server:app --bind 0.0.0.0:8000
```

## Troubleshooting

**Server won't start:**
Check port 8000 is not in use: `lsof -i :8000`

**Agent/Assistant not found:**
Verify model name format and that the resource exists.

**PyGEAI configuration errors:**
Run `geai config show` to verify credentials.

## Next Steps

- Add authentication and rate limiting
- Implement conversation history management
- Add monitoring and metrics
- Deploy to production (AWS, GCP, etc.)

## Documentation

- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [PyGEAI Chat Client](https://pygeai.readthedocs.io/en/latest/chat/)
- [Uvicorn Documentation](https://www.uvicorn.org/)
