catonline_ai/vw-agentic-rag/docs/topics/SERVICE_SETUP.md

# Agentic RAG Service Setup Guide

## 🚀 Quick Start

### Prerequisites
- Python 3.11+ with `uv` package manager
- `config.yaml` file in the root directory

### Starting the Service

#### Option 1: Using the startup script (Recommended)
```bash
# Production mode (background)
./start_service.sh

# Development mode (with auto-reload)
./start_service.sh --dev
```

#### Option 2: Manual startup
```bash
# Make sure you're in the root directory with config.yaml
cd /home/fl/code/ai-solution/agentic-rag-4

# Start the service
uv run uvicorn service.main:app --host 127.0.0.1 --port 8000
```

### Stopping the Service
```bash
./stop_service.sh
```

### Configuration

The service expects a `config.yaml` file in the root directory. Example structure:

```yaml
# Configuration
provider: azure  # or openai

openai:
  base_url: "${OPENAI_BASE_URL:-https://api.openai.com/v1}"
  api_key: "${OPENAI_API_KEY}"
  model: "gpt-4o"

azure:
  base_url: "https://your-azure-endpoint.com/..."
  api_key: "your-azure-api-key"
  deployment: "gpt-4o"
  api_version: "2024-11-20"

retrieval:
  endpoint: "http://your-retrieval-endpoint.com"
  api_key: "your-retrieval-api-key"

app:
  name: "agentic-rag"
  memory_ttl_days: 7
  max_tool_loops: 3
  cors_origins: ["*"]
  logging:
    level: "INFO"

llm:
  rag:
    temperature: 0.2
    max_tokens: 4000
    system_prompt: |
      # Your detailed system prompt here...
    user_prompt: |
      <user_query>{{user_query}}</user_query>
      # Rest of your user prompt template...

logging:
  level: "INFO"
  format: "json"
```

### Service Endpoints

Once running, the service provides:

- **Health Check**: `http://127.0.0.1:8000/health`
- **API Documentation**: `http://127.0.0.1:8000/docs`
- **Chat API**: `http://127.0.0.1:8000/api/chat` (POST with streaming response)

### Environment Variables

The configuration supports environment variable substitution:

- `${OPENAI_API_KEY}` - Your OpenAI API key
- `${OPENAI_BASE_URL:-https://api.openai.com/v1}` - OpenAI base URL with default fallback

### Troubleshooting

#### Service won't start
1. Check if `config.yaml` exists in the root directory
2. Verify the configuration syntax
3. Check if the port is already in use: `lsof -i :8000`
4. View logs: `tail -f server.log`

#### Configuration issues
1. Ensure all required fields are present in `config.yaml`
2. Check environment variables are set correctly
3. Validate YAML syntax

#### Performance issues
1. Monitor logs: `tail -f server.log`
2. Check retrieval service connectivity
3. Verify LLM provider configuration

### Development

For development with auto-reload:
```bash
./start_service.sh --dev
```

This will watch for file changes and automatically restart the service.

## 📁 File Structure

```
/home/fl/code/ai-solution/agentic-rag-4/
├── config.yaml              # Main configuration file
├── start_service.sh          # Service startup script
├── stop_service.sh          # Service stop script
├── server.log               # Service logs (when running in background)
├── service/                 # Service source code
│   ├── main.py             # FastAPI application
│   ├── config.py           # Configuration handling
│   ├── graph/              # Workflow graph
│   ├── memory/             # Memory store
│   ├── tools/              # Retrieval tools
│   └── schemas/            # Data models
└── ...
```