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 sessionGET /{id}- Get session detailsPATCH /{id}- Update sessionDELETE /{id}- End sessionPOST /{id}/message- Send message
Personas (/api/v1/personas)#
GET /- List personasPOST /- Create personaGET /{id}- Get personaPATCH /{id}- Update personaDELETE /{id}- Delete persona
Knowledge (/api/v1/knowledge)#
POST /documents- Upload documentGET /documents- List documentsDELETE /documents/{id}- Delete documentPOST /search- Search knowledge base
Tools (/api/v1/tools)#
GET /- List registered toolsPOST /- Register toolDELETE /{id}- Unregister toolPOST /{id}/invoke- Invoke tool
WebSocket (/api/v1/ws)#
WS /events- Real-time event streamWS /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#
text
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