Unified HTTP interface for the LUKi agent & modules (auth, routing, rate limits)
luki-api-gateway is the single entry point for clients (SDKs, web apps, partner services) to access all LUKi capabilities:
- Chat / Agent endpoints (
/v1/chat, streaming) - Memory & ELR ops proxy (
/v1/elr/...) - Module endpoints pass-through (cognitive, engagement, reporting)
- AuthN/AuthZ, rate limiting, request logging & tracing
- Versioning, schema validation, error normalization
It hides internal topology, giving external consumers a stable, documented REST surface.
- Routing & Aggregation: Fan-out to underlying services (memory, modules, token service)
- Authentication: API keys, OAuth/JWT, service-to-service tokens
- Authorization: Enforce scopes/roles (integration with
luki-security-privacy) - Throttling & Quotas: Per-user and per-key rate limits
- Observability: Structured logs, metrics, traces, correlation IDs
- Schema & Version Control: Pydantic models and OpenAPI spec management
- Framework: FastAPI (ASGI), Uvicorn/Gunicorn
- Auth: PyJWT, custom middleware, RBAC from security module
- Rate Limit:
slowapior custom Redis-based limiter - Schema / Docs: Pydantic v2, OpenAPI auto-docs, Redoc UI
- HTTP Clients:
httpxasync clients to downstream services - Tracing: OpenTelemetry exporters (Jaeger/Tempo), structlog for logs
- Deployment: Docker/K8s, behind NGINX/API Gateway (cloud)
luki-api-gateway/
├── README.md
├── pyproject.toml
├── requirements.txt
├── requirements-railway.txt # railway deployment dependencies
├── env.example # environment template
├── .env # actual environment file (gitignored)
├── .railwayignore # railway deployment exclusions
├── .dockerignore # docker build exclusions
├── Dockerfile # container build configuration
├── railway.toml # railway deployment configuration
├── Procfile # process definitions
├── luki_api/ # main package
│ ├── __init__.py
│ ├── config.py # env vars, service URLs, rate limits
│ ├── main.py # FastAPI app entry
│ ├── auth/
│ │ ├── __init__.py
│ │ ├── api_key.py # API key authentication
│ │ ├── jwt.py # JWT token handling
│ │ └── rbac.py # role-based access control
│ ├── middleware/
│ │ ├── __init__.py
│ │ ├── auth.py # authentication middleware
│ │ ├── logging.py # structured logging
│ │ ├── rate_limit.py # rate limiting
│ │ └── tracing.py # request tracing
│ ├── routes/
│ │ ├── __init__.py
│ │ ├── chat.py # /v1/chat endpoints
│ │ ├── elr.py # /v1/elr proxy routes
│ │ ├── health.py # /health endpoint
│ │ └── metrics.py # /metrics endpoint
│ └── clients/
│ ├── __init__.py
│ ├── agent_client.py # LUKi core agent client
│ └── memory_service.py # memory service client
└── scripts/ # deployment and utility scripts
git clone [email protected]:REMELife/luki-api-gateway.git
cd luki-api-gateway
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn luki_api.main:app --reload --port 8081Set env vars in .env or export:
export AGENT_URL=http://localhost:9000
export MEMORY_URL=http://localhost:8002
export COG_URL=http://localhost:8101
export ENG_URL=http://localhost:8102
export REP_URL=http://localhost:8103
export JWT_PUBLIC_KEY_PATH=keys/jwt_pub.pem
export RATE_LIMIT_PER_MIN=60
export LOG_LEVEL=INFOPOST /v1/chat
{
"user_id": "user_123",
"message": "I feel anxious today, can you help?",
"context": {"mood": "anxious"}
}Response:
{
"text": "I’m here for you. Let's try a breathing exercise...",
"tool_calls": [],
"meta": {"trace_id": "abc-123"}
}GET /v1/chat/stream?user_id=user_123&message=Tell%20me%20a%20joke
- Server-Sent Events (SSE) or WebSocket (if enabled)
POST /v1/elr/ingest_text → proxies to memory service.
GET /v1/activities/recommend?user_id=user_123&k=3
POST /v1/reports/generate with {"user_id":"...", "window_days":7}
GET /health - Service health and status
GET /metrics - Prometheus metrics for monitoring
- Modes: API key (
Authorization: Bearer <key>), JWT, or internal service tokens. - Scopes:
chat:write,elr:read,elr:write, etc. checked inauth/scopes.py. - Rate limits: global + per-user/per-key using Redis backend.
- Request/response logs (no PHI) with trace IDs.
/healthzfor liveness;/metricsfor Prometheus.- OpenTelemetry tracing to Jaeger/Tempo (configured via ENV).
- All downstream errors normalized to JSON:
{
"error": {
"code": "DOWNSTREAM_TIMEOUT",
"message": "Memory service did not respond",
"trace_id": "abc-123"
}
}- Unit tests: routers, schema validation, auth.
- Integration: spin up mock downstreams via docker-compose.
pytest -q- CI pipeline: lint, test, build Docker, push to registry.
- GraphQL gateway (optional)
- gRPC passthrough for high-throughput clients
- Webhook callback support (push instead of poll)
- Canary releases & blue/green deploy helpers
- Advanced quota system with billing hooks
We welcome contributions to the LUKi API Gateway! Please follow these guidelines:
- Fork the repository
- Create a feature branch:
git checkout -b feature/your-feature - Make your changes and add tests
- Run the test suite:
pytest - Submit a pull request
- Follow PEP 8 style guidelines
- Add type hints for all functions
- Write tests for new functionality
- No hard-coded secrets; use environment variables
- Keep OpenAPI schema updated
- PR requires review + passing CI
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
- Documentation: Check the
/docsendpoint when running the server - Issues: Report bugs and feature requests via GitHub Issues
- Discussions: Join community discussions for questions and ideas
One door in. Everything safe, fast, and consistent out.