README.md

metadata

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 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
• Complete developer guide
• Architecture
• API reference
• Patch inventory
• Datasource contracts
• Frontend guide
• Environment reference
• Deployment runbook
• Security and safety
• Operations and troubleshooting
• Testing and verification
• Contributing
• Current implementation status

Repository entry points

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

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:

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):

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.