Eve library

Psyche API Gateway

Other

Revision 1

On this page

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#

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