Morpheus API Gateway - FastAPI Implementation

A robust API Gateway connecting Web2 clients to the Morpheus-Lumerin AI Marketplace using FastAPI, PostgreSQL, and secure key management practices.

Overview

This project migrates the existing Morpheus API Gateway functionality from Node.js/Express to Python/FastAPI, incorporating robust authentication, persistent storage, secure key management, and best practices for API development and deployment using Docker.

The gateway provides OpenAI-compatible endpoints that connect to the Morpheus blockchain, allowing users to access AI models in a familiar way while leveraging blockchain technology behind the scenes.

Technology Stack

Web Framework: FastAPI
Data Validation: Pydantic
Database ORM: SQLAlchemy with Alembic for migrations
Database: PostgreSQL
Caching: In-memory with DirectModelService
Asynchronous HTTP Client: httpx (for communicating with the proxy-router)
JWT Handling: python-jose
Password Hashing: passlib[bcrypt]
Cryptography: cryptography for private key encryption
KMS Integration: AWS KMS for secure key management
Containerization: Docker, Docker Compose

Project Structure

morpheus_api_python/
├── alembic/                  # Database migrations
├── alembic.ini
├── src/
│   ├── api/                  # FastAPI routers/endpoints
│   │   ├── v1/
│   │   │   ├── auth.py       # User registration, login, API keys, private key mgmt
│   │   │   ├── models.py     # OpenAI compatible models endpoint
│   │   │   ├── chat.py       # OpenAI compatible chat completions
│   │   │   ├── chat_history.py # Chat history management
│   │   │   ├── session.py    # Session management
│   │   │   └── automation.py # Automation settings
│   │   └── __init__.py
│   ├── core/                 # Core logic, configuration, security
│   │   ├── config.py         # Pydantic settings
│   │   ├── security.py       # JWT generation/validation, password hashing, API key handling
│   │   ├── key_vault.py      # Private key encryption/decryption, KMS interaction
│   │   ├── direct_model_service.py # Direct model fetching with in-memory cache
│   │   ├── model_routing.py  # Model name to blockchain ID routing
│   │   ├── local_testing.py  # Local testing mode and authentication bypass
│   │   └── __init__.py
│   ├── crud/                 # Database interaction functions
│   │   ├── user.py
│   │   ├── api_key.py
│   │   ├── private_key.py
│   │   ├── chat.py           # Chat and message CRUD operations
│   │   ├── session.py        # Session CRUD operations
│   │   └── __init__.py
│   ├── db/                   # Database session management, base model
│   │   ├── database.py
│   │   ├── models.py         # SQLAlchemy models (includes Chat, Message)
│   │   └── __init__.py
│   ├── schemas/              # Pydantic schemas for request/response validation
│   │   ├── user.py
│   │   ├── token.py
│   │   ├── api_key.py
│   │   ├── private_key.py
│   │   ├── openai.py         # Schemas for OpenAI compatibility
│   │   └── __init__.py
│   ├── services/             # Business logic layer
│   │   ├── cognito_service.py    # Cognito integration
│   │   ├── session_service.py    # Session management logic
│   │   ├── proxy_router.py       # Proxy router communication
│   │   └── __init__.py
│   ├── dependencies.py       # FastAPI dependency injection functions
│   └── main.py               # FastAPI application instance and root setup
├── ai-docs/                  # Documentation and guides
│   ├── DOCKER_TESTING.md     # Local testing guide
│   ├── SELF_CONTAINED_LOCAL_TESTING.md # Detailed local setup
│   └── ...                   # Other documentation files
├── scripts/                  # Development and deployment scripts
│   ├── test_local.sh         # Self-contained local testing
│   ├── start_local_dev.sh    # Container startup with auto-migration
│   └── ...                   # Other utility scripts
├── tests/                    # Test files
│   ├── api/                  # API integration tests
│   └── unit/                 # Unit tests
├── .env.example              # Production environment template
├── env.local.example         # Local testing environment template
├── .gitignore                # Git ignore file
├── Dockerfile                # Docker build configuration
├── docker-compose.local.yml  # Local development container setup
├── pyproject.toml            # Python project dependencies
└── README.md                 # This file

Getting Started

🚀 Quick Start - Local Development (Recommended)

No external dependencies needed! For rapid development and testing:

# One-time setup
cp env.local.example .env.local

# Start local development environment
./scripts/test_local.sh

What this gives you:

✅ No Authentication Required - All endpoints work without tokens/keys
✅ Fresh Database - PostgreSQL with auto-migrations on every start
✅ Hot Reload - Code changes apply instantly
✅ Complete API Testing - Test all endpoints via Swagger UI
✅ Ephemeral Environment - Clean state every restart

Access your local environment:

API: http://localhost:8000
Swagger UI: http://localhost:8000/docs (all endpoints work without auth!)
Health Check: http://localhost:8000/health

📚 For detailed testing instructions, see Docker Testing Guide

Prerequisites (Production Setup)

Python 3.11+
Docker and Docker Compose
PostgreSQL (if running locally without Docker)
AWS Account with KMS access (for production)

Production Installation

Clone the repository:

git clone https://github.com/yourusername/morpheus-api-python.git
cd morpheus-api-python

Create a virtual environment:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

Install dependencies:
```
pip install poetry
poetry install
```
Configure environment variables:
```
cp .env.example .env
```
Edit the .env file with your specific settings

Environment Configuration

Configure the following key environment variables:

# Database
POSTGRES_USER=morpheus_user
POSTGRES_PASSWORD=secure_password_here
POSTGRES_DB=morpheus_db
DATABASE_URL=postgresql+asyncpg://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/${POSTGRES_DB}

# Model Service (uses in-memory caching)
ACTIVE_MODELS_URL=https://active.dev.mor.org/active_models.json

# JWT
JWT_SECRET_KEY=generate_this_with_openssl_rand_-hex_32
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# AWS KMS (for production)
KMS_PROVIDER=aws
KMS_MASTER_KEY_ID=your_kms_key_id_or_arn
AWS_REGION=us-east-1
# AWS_ACCESS_KEY_ID=your_access_key_id         # If not using IAM roles
# AWS_SECRET_ACCESS_KEY=your_secret_access_key # If not using IAM roles

# Development mode local encryption (not for production)
MASTER_ENCRYPTION_KEY=generate_this_with_openssl_rand_-hex_32

# Proxy Router
PROXY_ROUTER_URL=http://localhost:8545  # URL of the Morpheus-Lumerin Node proxy-router

Database Setup

Local Development Database

Using Local Testing Environment (Recommended):

Database setup is automatic when using ./scripts/test_local.sh
PostgreSQL starts in Docker with auto-migrations
No manual database setup required!

Manual Database Setup (Production)

Start PostgreSQL:

docker run --name morpheus-postgres -e POSTGRES_USER=morpheus_user -e POSTGRES_PASSWORD=morpheus_password -e POSTGRES_DB=morpheus_db -p 5432:5432 -d postgres:15-alpine

Run migrations:
```
alembic upgrade head
```

Database Migrations

Local Development:

Migrations run automatically on container startup
Always uses the latest schema
Fresh database on every restart

Production/Manual:

Generate a new migration after model changes:

alembic revision --autogenerate -m "Description of changes"

Apply migrations:

alembic upgrade head

Roll back migrations:

alembic downgrade -1  # Roll back one migration

Model Service

The API uses an in-memory caching system for model data fetched from CloudFront. No external caching service is required.

AWS KMS Setup (Production)

Create a KMS key in the AWS console or using AWS CLI
Note the key ARN or ID
Configure IAM permissions for your service principal
Update environment variables with key details

Running the Application

🚀 Local Development (Recommended)

One command starts everything:

./scripts/test_local.sh

Features:

✅ PostgreSQL database with auto-migrations
✅ API with hot reload
✅ Authentication bypass for easy testing
✅ All endpoints accessible via Swagger UI

Monitor your environment:

# View logs
docker compose -f docker-compose.local.yml logs -f api-local

# Check status
docker compose -f docker-compose.local.yml ps

# Stop environment
docker compose -f docker-compose.local.yml down

Production Docker Setup

Build and start containers:
```
docker-compose up -d
```
Check container status:
```
docker-compose ps
```
View logs:
```
docker-compose logs -f api
```

Manual Local Development

Start PostgreSQL (see Database Setup above)

Run the FastAPI application:

uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

Testing the API

🧪 Local Development Testing

Using Local Environment (No Authentication Required):

# Start environment
./scripts/test_local.sh

# Access Swagger UI - all endpoints work without authentication!
# http://localhost:8000/docs

Test any endpoint directly:

No Bearer tokens needed
No API keys required
Click "Try it out" and execute immediately
Test user automatically created: [email protected]

API Documentation

FastAPI automatically generates interactive API documentation:

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

📚 For comprehensive testing instructions, see Docker Testing Guide

Core Endpoints

Authentication

POST /api/v1/auth/register - Create a new user
POST /api/v1/auth/login - Log in and get JWT tokens
POST /api/v1/auth/refresh - Refresh access token

API Key Management

POST /api/v1/auth/keys - Create a new API key
GET /api/v1/auth/keys - List your API keys
DELETE /api/v1/auth/keys/{key_id} - Delete an API key

Private Key Management

POST /api/v1/auth/private-key - Store your blockchain private key
GET /api/v1/auth/private-key/status - Check if you have a stored private key
DELETE /api/v1/auth/private-key - Delete your stored private key

OpenAI-Compatible Endpoints

GET /api/v1/models - List available models
GET /api/v1/models/{model_id} - Get model details
POST /api/v1/chat/completions - Create a chat completion

Example: Testing Chat Completion

🚀 Local Development (No Authentication)

# Start local environment
./scripts/test_local.sh

# Test chat completion directly (no auth needed!)
curl -X POST http://localhost:8000/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

# Test chat history
curl -X POST http://localhost:8000/api/v1/chat-history/chats \
  -H "Content-Type: application/json" \
  -d '{"title": "Test Chat"}'

# List available models
curl http://localhost:8000/api/v1/models

🏭 Production (Full Authentication Flow)

Register a user:

curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"name": "Test User", "email": "[email protected]", "password": "securepassword"}'

Login to get tokens:

curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "securepassword"}'

Create an API key (using JWT from login):

curl -X POST http://localhost:8000/api/v1/auth/keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "My API Key"}'

Store a private key:

curl -X POST http://localhost:8000/api/v1/auth/private-key \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"private_key": "YOUR_BLOCKCHAIN_PRIVATE_KEY"}'

Create a chat completion using the API key:

curl -X POST http://localhost:8000/api/v1/chat/completions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-3.5-turbo",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'

Health Checks

GET /health - Check API and model service health
GET / - Basic API information

Open Questions and TODOs

This implementation is based on the FastAPI Implementation Plan and has the following open questions:

Proxy-Router API Specifics: The exact API contract of the morpheus-lumerin-node proxy-router needs clarification.
Model Mapping Source: The source of mapping between OpenAI model names and blockchain model IDs needs to be determined.
Token Spending Approval: The mechanism for the /auth/approve-spending endpoint needs specification.
Private Key Scope: Confirm if a single private key per user is sufficient.
Rate Limiting: Determine rate-limiting requirements and implement if needed.
Security Requirements: Confirm if there are any specific compliance or advanced security requirements.

The current implementation uses placeholder/mock data for model information and chat completions until the proxy-router integration is finalized.

🔄 Development Workflow

Daily Development

# Start local environment (one-time per session)
./scripts/test_local.sh

# Make code changes (hot reload active - changes apply instantly!)
# Test in Swagger UI: http://localhost:8000/docs

# Stop environment when done
# Ctrl+C or: docker compose -f docker-compose.local.yml down

Key Features for Development

✅ Hot Reload - Code changes apply instantly
✅ No Authentication - Test all endpoints immediately
✅ Fresh Database - Clean state every restart
✅ Auto-Migration - Database schema always current
✅ Comprehensive Testing - All endpoints accessible via Swagger UI

Testing Different Scenarios

# Test chat functionality
curl -X POST http://localhost:8000/api/v1/chat-history/chats \
  -H "Content-Type: application/json" \
  -d '{"title": "Development Test"}'

# Test model service
curl http://localhost:8000/api/v1/models

# Test health checks
curl http://localhost:8000/health

Development and Contributing

Format code with ruff format
Run linting with ruff check
Run type checking with mypy
Run tests with pytest

License

MIT License

Name		Name	Last commit message	Last commit date
Latest commit History 106 Commits
.github/workflows		.github/workflows
ai-docs		ai-docs
alembic		alembic
migration		migration
scripts		scripts
src		src
tests		tests
.DS_Store		.DS_Store
.cursorignore		.cursorignore
.gitignore		.gitignore
DEFAULT_MODEL_FALLBACK_SYSTEM.md		DEFAULT_MODEL_FALLBACK_SYSTEM.md
Dockerfile		Dockerfile
README.md		README.md
alembic.ini		alembic.ini
docker-compose.local.yml		docker-compose.local.yml
env.example		env.example
env.local.example		env.local.example
models.json		models.json
poetry.lock		poetry.lock
pyproject.toml		pyproject.toml

MorpheusAIs/Morpheus-Marketplace-API

Folders and files

Latest commit

History

Repository files navigation

Morpheus API Gateway - FastAPI Implementation

Overview

Technology Stack

Project Structure

Getting Started

🚀 Quick Start - Local Development (Recommended)

Prerequisites (Production Setup)

Production Installation

Environment Configuration

Database Setup

Local Development Database

Manual Database Setup (Production)

Database Migrations

Model Service

AWS KMS Setup (Production)

Running the Application

🚀 Local Development (Recommended)

Production Docker Setup

Manual Local Development

Testing the API

🧪 Local Development Testing

API Documentation

Core Endpoints

Authentication

API Key Management

Private Key Management

OpenAI-Compatible Endpoints

Example: Testing Chat Completion

🚀 Local Development (No Authentication)

🏭 Production (Full Authentication Flow)

Health Checks

Open Questions and TODOs

🔄 Development Workflow

Daily Development

Key Features for Development

Testing Different Scenarios

Development and Contributing

License

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors 5

Uh oh!

Languages

Packages