# Psyche API Gateway

REST API Gateway for the Psyche AI Virtual Assistant Platform.

## Overview

The API Gateway provides a unified interface for all Psyche services, handling:

- Session management for AI assistant conversations
- Persona configuration and management
- Knowledge base document operations
- Tool registration and invocation
- Webhook configuration
- Real-time WebSocket communication
- Feature flags and A/B experiments

## API Documentation

When running in development mode, API documentation is available at:

- **Swagger UI**: http://localhost:8000/docs
- **ReDoc**: http://localhost:8000/redoc
- **OpenAPI JSON**: http://localhost:8000/openapi.json

## Health Endpoints

| Endpoint  | Purpose            | Response                      |
| --------- | ------------------ | ----------------------------- |
| `/health` | Basic health check | Status, version, environment  |
| `/ready`  | Readiness probe    | Dependency checks (DB, Redis) |
| `/live`   | Liveness probe     | Uptime status                 |

## Quick Start

### Prerequisites

- Python 3.11+
- Poetry
- PostgreSQL (for production)
- Redis (for production)

### Development

```bash
# Install dependencies
poetry install

# Run development server
poetry run uvicorn api_gateway.app:create_app --factory --reload --port 8000

# Or using Nx
nx serve psyche-api-gateway
```

### Testing

```bash
# Run tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=api_gateway --cov-report=html

# Or using Nx
nx test psyche-api-gateway
nx test-cov psyche-api-gateway
```

### Linting

```bash
# Check code
poetry run ruff check src/
poetry run mypy src/

# Format code
poetry run black src/
poetry run ruff check --fix src/

# Or using Nx
nx lint psyche-api-gateway
nx format psyche-api-gateway
```

## Configuration

Configuration is managed via environment variables. See `config.py` for all
options.

### Required Variables

```bash
# Database
DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/psyche

# Redis
REDIS_URL=redis://localhost:6379

# Security
SECRET_KEY=your-secret-key-here
```

### Optional Variables

```bash
# Server
HOST=0.0.0.0
PORT=8000
DEBUG=false

# API
API_PREFIX=/api/v1

# CORS
CORS_ORIGINS=["http://localhost:3000"]

# Monitoring
METRICS_ENABLED=true
TRACING_ENABLED=true
```

## API Routes

### Sessions (`/api/v1/sessions`)

- `POST /` - Create new session
- `GET /{id}` - Get session details
- `PATCH /{id}` - Update session
- `DELETE /{id}` - End session
- `POST /{id}/message` - Send message

### Personas (`/api/v1/personas`)

- `GET /` - List personas
- `POST /` - Create persona
- `GET /{id}` - Get persona
- `PATCH /{id}` - Update persona
- `DELETE /{id}` - Delete persona

### Knowledge (`/api/v1/knowledge`)

- `POST /documents` - Upload document
- `GET /documents` - List documents
- `DELETE /documents/{id}` - Delete document
- `POST /search` - Search knowledge base

### Tools (`/api/v1/tools`)

- `GET /` - List registered tools
- `POST /` - Register tool
- `DELETE /{id}` - Unregister tool
- `POST /{id}/invoke` - Invoke tool

### WebSocket (`/api/v1/ws`)

- `WS /events` - Real-time event stream
- `WS /control` - Control channel

## Docker

```bash
# Build image
docker build -t psyche-api-gateway:latest .

# Run container
docker run -p 8000:8000 --env-file .env psyche-api-gateway:latest

# Or using Nx
nx docker-build psyche-api-gateway
```

## Architecture

```
src/api_gateway/
├── app.py            # FastAPI application factory
├── config.py         # Configuration management
├── main.py           # Entry point
├── core/             # Core utilities
│   ├── exceptions.py # Custom exceptions
│   └── middleware.py # Middleware stack
├── models/           # Pydantic models
│   ├── base.py       # Base models
│   ├── sessions.py   # Session models
│   ├── personas.py   # Persona models
│   └── ...
├── routers/          # API route handlers
│   ├── health.py     # Health endpoints
│   ├── sessions.py   # Session endpoints
│   ├── personas.py   # Persona endpoints
│   └── ...
├── services/         # Business logic
│   └── webhooks.py   # Webhook service
└── websocket/        # WebSocket handlers
    ├── handlers.py   # Event handlers
    └── manager.py    # Connection manager
```

## Nx Integration

This service is integrated with the Oshun Nx monorepo:

```bash
# Available targets
nx serve psyche-api-gateway      # Development server
nx serve-prod psyche-api-gateway # Production server
nx build psyche-api-gateway      # Build package
nx install psyche-api-gateway    # Install dependencies
nx lint psyche-api-gateway       # Run linters
nx format psyche-api-gateway     # Format code
nx test psyche-api-gateway       # Run tests
nx test-cov psyche-api-gateway   # Tests with coverage
nx docker-build psyche-api-gateway # Build Docker image
nx openapi psyche-api-gateway    # Generate OpenAPI spec
```