Spaces:
Sleeping
Sleeping
| title: HermesFace | |
| sdk: docker | |
| emoji: 🚀 | |
| colorFrom: green | |
| colorTo: green | |
| pinned: false | |
| app_port: 7860 | |
| # HermesFace / Hermes Futures Desk | |
| HermesFace is an overlay installed onto [NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) and deployed on Hugging Face Spaces. It adds an authenticated, deterministic cryptocurrency Futures analysis desk to the existing Hermes web application on port **7860** — no second backend, port, or decision engine. | |
| The Futures Desk is **analysis-first, safety-first, and Paper-trading-first**. Datasource 4 remains the authority for Futures safety metadata. Binance public data is tried first as a field-level fallback; KuCoin Futures continues the public-provider chain when Binance is unavailable or regionally restricted. Datasource 2 is complementary context. **Optional AI context** (Hermes auxiliary task `futures_advisory`) is advisory only and never alters deterministic decisions. DS4 uses a fast request plus one bounded cold-start wake retry. Provider provenance is preserved and no fallback may weaken `noTradeGuard`. | |
| Read-only Futures tools are registered via the **`futures_trading` Hermes plugin** (`hermes_overlay/plugins/futures_trading/`). Dashboard and Telegram routes are mounted into the upstream Hermes FastAPI app by `scripts/sync_hf.py` (Option A — existing URLs preserved). | |
| The Space runs the authenticated Futures dashboard as its default single | |
| process. The optional Hermes messaging/cron gateway is disabled by default to | |
| keep the desktop stable; set `HERMES_GATEWAY_ENABLED=true` only when those | |
| background integrations are intentionally required. | |
| ## Production UI data policy | |
| The production dashboard does not populate market cards, positions, symbols, | |
| watchlists, history, provider health, or charts with demo/random data. Every | |
| server-backed value is loaded from the authenticated Futures and Telegram API | |
| routes. If a provider, catalog, position response, or OHLCV window is not | |
| available, the interface shows an explicit unavailable/blocked state and clears | |
| any stale chart from the previous market. Manual symbol entry remains available | |
| for a real server-side analysis, but it is never presented as a verified Futures | |
| contract unless the authoritative verification path confirms it. | |
| The UI distinguishes **deterministic system output** (emerald) from **optional AI context** (violet) on the trade-plan authority-contrast panel and advisory page. | |
| ## Quick links | |
| - [Developer documentation index](docs/README.md) | |
| - [Complete developer guide](docs/DEVELOPER_GUIDE.md) | |
| - [Architecture](docs/ARCHITECTURE.md) | |
| - [API reference](docs/API_REFERENCE.md) | |
| - [Patch inventory](docs/PATCH_INVENTORY.md) | |
| - [Datasource contracts](docs/DATA_PIPELINE_AND_CONTRACTS.md) | |
| - [Frontend guide](docs/FRONTEND_GUIDE.md) | |
| - [Environment reference](docs/ENVIRONMENT_CONFIGURATION.md) | |
| - [Deployment runbook](docs/DEPLOYMENT_RUNBOOK.md) | |
| - [Security and safety](docs/SECURITY_AND_SAFETY.md) | |
| - [Operations and troubleshooting](docs/OPERATIONS_AND_TROUBLESHOOTING.md) | |
| - [Testing and verification](docs/TESTING_AND_VERIFICATION.md) | |
| - [Contributing](docs/CONTRIBUTING.md) | |
| - [Current implementation status](docs/PROJECT_STATUS.md) | |
| ## Repository entry points | |
| ```text | |
| app.py | |
| Dockerfile | |
| scripts/entrypoint.sh | |
| scripts/sync_hf.py | |
| hermes_overlay/plugins/futures_trading/ | |
| hermes_overlay/tools/futures_dashboard_api.py | |
| hermes_overlay/tools/templates/hermes_futures_desk_luxury.html | |
| hermes_overlay/external_ai/advisory.py | |
| hermes_overlay/trading/trade_cycle.py | |
| hermes_overlay/trading/dual_datasource_client.py | |
| ``` | |
| ## Local container start | |
| ```bash | |
| cp .env.example .env | |
| # Fill required secrets without committing the file. | |
| docker build -t hermesface . | |
| docker run --rm -p 7860:7860 --env-file .env hermesface | |
| ``` | |
| Open `http://localhost:7860/futures` and authenticate with the configured Hermes dashboard credentials. | |
| ## Local verification | |
| Run the repository checks from the project root: | |
| ```bash | |
| python scripts/validate_startup_configuration.py | |
| python scripts/check_migrations.py | |
| python -m pytest hermes_overlay/tests -q | |
| ``` | |
| The first command validates fail-closed runtime configuration, the second checks deterministic migration plans, and the third runs the complete repository test suite (currently **433 passed**, with 2 pre-existing Dockerfile/dependency-inventory failures unrelated to Futures logic). | |
| Optional browser E2E click-through (requires Chrome + Playwright): | |
| ```bash | |
| python temp/e2e_futures_dashboard_clickthrough.py | |
| ``` | |
| ## Safety notice | |
| Do not weaken deterministic decisions, Datasource 4 authority, `noTradeGuard`, freshness checks, Futures verification, risk approval, Stop Loss / Take Profit, leverage, sizing, Paper execution validation, or Telegram webhook-only isolation. Do not use fabricated production market data. Do not execute Paper, Testnet, or Live trades during routine development verification. The three LLM mutation handlers (`set_leverage_and_margin`, `execute_futures_position`, `close_futures_position`) remain hard-reject stubs and are not registered in the runtime toolset. | |