README.md

---
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.