Hermes X

Institutional-Grade AI Trading Operating System

Hermes X is a modular, event-driven trading platform that integrates AI agents, real-time market data, technical indicators, and broker execution into a unified operating system for algorithmic trading.

This repository ships two systems: Hermes X itself, and OmniTrader, a multi-agent trading system that runs as a separate process and is reachable from Hermes X over an HTTP bridge.

---

Architecture

Hermes X is a clean architecture monolith designed for future decomposition into microservices. OmniTrader is a separate FastAPI service — an optional peer, not a dependency.

   :5173                        :8000
┌────────────┐   /api/v1   ┌──────────────────┐    ┌──────────────┐
│ Hermes X   │────────────▶│    Hermes X      │───▶│ PostgreSQL   │
│ React UI   │◀────────────│   FastAPI (async)│    │  (asyncpg)   │
└────────────┘   Bearer    └────┬────────┬────┘    └──────────────┘
                                │        │
                                │        ▼
                                │   ┌──────────────┐
                                │   │    Redis     │
                                │   │ (cache/pub)  │
                                │   └──────────────┘
                                │
                   HTTP bridge  │  /api/v1/omnitrader/*
                                ▼            :8100
   :5174                   ┌──────────────────────┐
┌────────────┐             │     OmniTrader       │
│ omnitrader │────────────▶│   FastAPI + agents   │
│    UI      │   /api      │  scheduler, paper    │
└────────────┘             └──────────────────────┘
                                     ▲
                                     │ stdio
                              ┌──────────────┐
                              │  MCP server  │
                              └──────────────┘

Hermes X calls OmniTrader; OmniTrader never calls back, and neither imports the other's Python package. If OmniTrader is down, bridge routes return 503 and the rest of Hermes X keeps working.

Key design decisions:

• Async-first Python backend for high-concurrency market data handling
• Event bus architecture for loose coupling between trading modules
• API versioning for backward compatibility
• Type-safe configuration via Pydantic Settings
• HTTP-only coupling between the two systems — zero import coupling
• Multi-stage Docker builds for production-ready images

Ports

Tech Stack

Quick Start

git clone https://github.com/arya0O7/Felix-.git
cd Felix-

(The GitHub remote still carries the project's former name.)

Local development

Configuration comes first — the backend will not start without it:

cp .env.example backend/.env

Then edit backend/.env and set HERMES_JWT_SECRET to a random string of at least 32 characters and HERMES_POSTGRES_PASSWORD to anything other than the rejected defaults. validate_security() refuses hermes_secret, change_me_in_production, and hermes-development-secret-change-me. Generate a secret with:

python3 -c "import secrets; print(secrets.token_hex(24))"

.env resolves relative to the working directory, and uvicorn runs from backend/, which is why the file goes in backend/.env rather than the repo root.

Hermes X backend (Postgres and Redis are optional — repositories fall back to in-memory state):

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements-dev.txt
uvicorn app.main:app --reload --port 8000

OmniTrader backend — separate terminal, launched from the repo root (its package root), with its own dependency set:

pip install -r requirements.txt
uvicorn omnitrader.api.server:app --reload --port 8100

Frontends — one terminal each:

cd frontend && npm install && npm run dev          # :5173
cd omnitrader-ui && npm install && npm run dev     # :5174

Docker

cp .env.example .env      # docker compose reads the root .env
docker compose up -d

Brings up postgres, redis, backend (:8000), omnitrader (:8100) and frontend (:80). HERMES_POSTGRES_PASSWORD is required — compose fails fast if it's unset.

Authentication

Every /api/v1/* route requires a bearer token; auth cannot be disabled. For development, mint one:

curl -s -X POST localhost:8000/api/v1/auth/token -H 'content-type: application/json' -d '{"subject":"dev","role":"admin"}'

Then send it as Authorization: Bearer <token>. This endpoint returns 403 when HERMES_ENVIRONMENT is production or prod, which docker-compose.prod.yml sets. It is a development affordance, not a user/session system.

The frontend does this automatically — frontend/src/lib/http.ts fetches and caches a token, attaches the header, and retries once on 401.

Project Structure

hermes-x/
├── backend/                    # Hermes X — FastAPI backend
│   ├── app/
│   │   ├── api/v1/endpoints/   # 31 endpoint modules
│   │   ├── core/               # Config, DB, Redis, security, clock
│   │   ├── events/             # Async event bus
│   │   ├── middleware/         # Correlation ID, timing, exceptions
│   │   ├── models/             # SQLAlchemy models
│   │   ├── shared/contracts/   # Cross-module Pydantic contracts
│   │   ├── omnitrader/         # HTTP bridge client (no omnitrader imports)
│   │   └── …                   # 30+ domain modules — see CLAUDE.md
│   ├── tests/                  # Backend tests
│   ├── scripts/verify_bridge.py# End-to-end ASGI verification harness
│   ├── alembic/                # Database migrations
│   └── requirements*.txt       # Hermes X dependencies
├── omnitrader/                 # OmniTrader — multi-agent trading system
│   ├── api/                    # server.py, routes/, mcp.py
│   ├── agents/                 # 11 agents incl. plugins/
│   ├── core/orchestrator.py    # Agent debate orchestration
│   ├── decision/ policy/       # Decision engine + policy validation
│   ├── execution/ memory/      # Paper trader, trade/failure/regime memory
│   └── tests/
├── frontend/                   # Hermes X React UI (:5173)
├── omnitrader-ui/              # OmniTrader React UI (:5174)
├── docs/                       # Documentation
├── requirements.txt            # OmniTrader dependencies (NOT Hermes X)
├── .mcp.json                   # MCP server registration
├── docker-compose.yml          # Development environment
├── docker-compose.prod.yml     # Production environment
└── .pre-commit-config.yaml     # Pre-commit hooks

Development

Linting & Formatting

# Backend
cd backend
ruff check .
ruff format .
black .

# Frontend
cd frontend
npm run lint

Testing

cd backend && pytest -v --cov=app     # Hermes X
pytest omnitrader/tests -v            # OmniTrader (from repo root)
pre-commit install                    # install hooks

Verifying the bridge

cd backend && python scripts/verify_bridge.py

Runs both apps in-process over httpx.ASGITransport — no sockets needed — and checks the health routes, the auth round-trip (401 without a token, 200 with one), and that bridge routes degrade to 503 rather than 500 when OmniTrader is absent.

Roadmap

• Phase 0: Foundation — clean architecture, config, event bus, middleware
• Phase 1: Market Data & Indicator Engine — providers, market structure, smart money, market context
• Phase 2: Trading Strategy Framework — evidence, scenarios, decision pipeline, risk committee
• Phase 3: AI Agent Integration — AI gateway, 9 analyst agents, copilot, knowledge graph
• Phase 4: MT5 Bridge & Execution — broker adapters, execution engine, paper trading, digital twin
• Phase 5: Dashboard & Monitoring — mission control, audit engine, research lab, both UIs
• Phase 6: Production Hardening — in progress
  • Redis Streams event bus, replacing the two separate in-process buses
  • Real authentication and session management (the dev token endpoint is a stopgap)
  • Alembic migrations covering all 20 model files (only 001_initial_schema.py exists)
  • Bidirectional Hermes X ↔ OmniTrader event flow (today the bridge is request/response only)

License

MIT License — see LICENSE for details.