Spaces:
Sleeping
Sleeping
File size: 10,723 Bytes
2e658e7 1f8cf56 2e658e7 1f8cf56 255b13e 1f8cf56 255b13e f05c460 1f8cf56 255b13e 1f8cf56 255b13e 2e658e7 255b13e 2e658e7 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 | # Environment Configuration
Configure secrets in Hugging Face Space Settings or inject them at container runtime. Never commit a populated `.env` file.
## Core persistence
| Variable | Default | Purpose |
|---|---|---|
| `HF_TOKEN` | none | Hugging Face token with required repository access. |
| `HERMES_DATASET_REPO` | derived/none | Private Dataset used to persist `/opt/data`. |
| `AUTO_CREATE_DATASET` | `true` | Create the private Dataset when missing. |
| `SYNC_INTERVAL` | `60` | Persistence sync interval in seconds. |
| `HF_HUB_DOWNLOAD_TIMEOUT` | implementation default | Hub download timeout. |
| `HF_HUB_UPLOAD_TIMEOUT` | implementation default | Hub upload timeout. |
| `HERMES_HOME` | `/opt/data` | Persistent Hermes data root. |
| `MAX_BACKUPS` | script default | Backup retention used by persistence helper. |
## Dashboard authentication
| Variable | Default | Purpose |
|---|---|---|
| `HERMES_ADMIN_PASSWORD` | none | Required production dashboard password. |
| `HERMES_ADMIN_USERNAME` | `admin` | Username written to Hermes dashboard config by entrypoint. |
| `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` | `admin` | Username checked by Futures router and runtime audit. |
| `HERMES_DASHBOARD_BASIC_AUTH_SECRET` | generated/persisted | Stable signing secret for password-login session cookies; set as a Space secret so restarts do not invalidate every browser session. |
| `HERMES_GATEWAY_ENABLED` | `false` | Opt-in Hermes messaging/cron worker; keep disabled for a stable dashboard-only Space. |
For the audit tool only:
| Variable | Purpose |
|---|---|
| `HERMES_DASHBOARD_COOKIE` | Existing authenticated session cookie when Basic auth is not used. |
| `HERMES_FUTURES_BASE_URL` | Default audit target base URL. |
For a private Hugging Face Space, also provide `HF_TOKEN` to the audit process.
The utility uses that bearer token only at the Hugging Face proxy, then uses
`HERMES_ADMIN_PASSWORD` to establish the separate dashboard session cookie.
Neither credential is written to the audit report.
## Datasources
| Variable | Default | Purpose |
|---|---|---|
| `DS4_BASE_URL` | DS4 Hugging Face Space URL | Authoritative Datasource 4 base. |
| `DS4_TIMEOUT_S` | `6` | DS4 request timeout. |
| `DS2_BASE_URL` | DS2 Hugging Face Space URL | Complementary Datasource 2 base. |
| `DS2_TIMEOUT_S` | `6` | DS2 request timeout. |
| `HERMES_SYMBOL_CACHE_PATH` | `/opt/data/futures_symbols_cache.json` | Symbol catalog cache. |
## Binance fallback
| Variable | Default | Purpose |
|---|---|---|
| `BINANCE_PUBLIC_FALLBACK_ENABLED` | `true` | Enable unauthenticated field fallback. |
| `BINANCE_FUTURES_PUBLIC_BASE_URL` | `https://fapi.binance.com` | Binance Futures public base. |
| `BINANCE_FUTURES_TIMEOUT_S` | `5` | Request timeout. |
| `BINANCE_FUTURES_MAX_RETRIES` | `2` | Retry bound. |
| `BINANCE_KLINE_INTERVAL` | `5m` | Default fallback interval. |
| `BINANCE_KLINE_LIMIT` | `100` | Default kline count. |
| `BINANCE_ATR_PERIOD` | `14` | ATR lookback in fallback client. |
| `BINANCE_ORDERBOOK_LIMIT` | `20` | Depth level limit. |
| `BINANCE_OI_PERIOD` | `5m` | Open Interest history period. |
A regional HTTP 451 must be surfaced honestly. Do not use raw IP, DNS bypass, or TLS bypass.
## KuCoin Futures fallback
KuCoin is tried after Binance for missing or unusable public Futures fields.
The client is read-only and does not require private credentials.
| Variable | Default | Purpose |
|---|---|---|
| `KUCOIN_FUTURES_PUBLIC_FALLBACK_ENABLED` | `true` | Enable unauthenticated KuCoin fallback. |
| `KUCOIN_FUTURES_PUBLIC_BASE_URL` | `https://api-futures.kucoin.com` | KuCoin Futures public base. |
| `KUCOIN_FUTURES_TIMEOUT_S` | `5` | Request timeout. |
| `KUCOIN_FUTURES_MAX_RETRIES` | `1` | Retry bound. |
| `FRESHNESS_FUTURE_TOLERANCE_SECONDS` | `120` | Bounded provider/local clock-skew allowance; larger future timestamps remain invalid. |
KuCoin values are labelled `kucoin_futures`; they must not be relabelled as
Binance or Datasource 4 data. KuCoin contract metadata may independently verify
an otherwise-unverified active Futures contract, but it cannot override an
explicit Datasource 4 safety block or `noTradeGuard`.
## Deterministic analysis
| Variable | Default | Purpose |
|---|---:|---|
| `FUTURES_MIN_SIGNAL_SCORE` | `0.55` | Minimum absolute deterministic score. |
| `FUTURES_MIN_SIGNAL_COMPONENTS` | `3` | Minimum present scoring components. |
| `FUTURES_MIN_DIRECTION_CONFIRMATIONS` | `2` | Minimum components confirming direction. |
| `FUTURES_STOP_ATR_MULTIPLIER` | `1.2` | ATR stop-distance multiplier. |
| `FUTURES_TAKE_PROFIT_RR` | `1.8` | Target reward-to-risk. |
| `FUTURES_MIN_STOP_BPS` | `20` | Minimum stop distance in basis points. |
| `FUTURES_PLAN_MAX_AGE_SECONDS` | `20` | Plan expiry window. |
| `FUTURES_DEFAULT_LEVERAGE` | `5` | Requested leverage before caps/haircut. |
Changing these variables changes deterministic behavior and requires explicit review, tests, and deployment evidence.
## Execution and Paper account
| Variable | Default | Purpose |
|---|---|---|
| `PAPER_EQUITY_USDT` | implementation default | Initial Paper account equity. |
| `FUTURES_EXCHANGE_ID` | implementation default | Exchange adapter ID. |
| `FUTURES_API_KEY` | none | Exchange credential boundary. Do not set for routine Paper-only development. |
| `FUTURES_API_SECRET` | none | Exchange secret. |
| `FUTURES_API_PASSPHRASE` | none | Optional exchange passphrase. |
Do not introduce credentials into source, logs, diagnostics, screenshots, patches, or generated reports.
## Optional AI context (Hermes auxiliary)
| Variable | Default | Purpose |
|---|---|---|
| `EXTERNAL_AI_ENABLED` | `true` | Allow optional AI context when explicitly requested (`include_external_context`). |
| `EXTERNAL_AI_TOTAL_TIMEOUT_SECONDS` | `15` | Outer safety cap for the `futures_advisory` auxiliary call in `advisory.py`; also seeds `auxiliary.futures_advisory.timeout` on first persist. |
| `EXTERNAL_AI_TIMEOUT_SECONDS` | `8` | Legacy per-call timeout (kept for compatibility). |
| `OPENROUTER_ANALYSIS_MODEL` | `openai/gpt-4o-mini` | OpenRouter model written into Hermes `fallback_providers` and `auxiliary.futures_advisory` by `sync_hf.py` on first persist. |
| `GOOGLE_ANALYSIS_MODEL` | `gemini-2.5-flash` | Gemini fallback model for the same chains. |
| `HF_ANALYSIS_MODEL` | `meta-llama/Llama-3.1-8B-Instruct` | Hugging Face fallback model for the same chains. |
| `HERMES_OPENROUTER_FALLBACK_MODEL` | none | Optional override that takes precedence over `OPENROUTER_ANALYSIS_MODEL` for `fallback_providers`. |
| `HERMES_GOOGLE_FALLBACK_MODEL` | none | Optional override that takes precedence over `GOOGLE_ANALYSIS_MODEL` for `fallback_providers`. |
| `HERMES_HF_FALLBACK_MODEL` | none | Optional override that takes precedence over `HF_ANALYSIS_MODEL` for `fallback_providers`. |
Advisory is implemented via Hermes `agent.auxiliary_client.async_call_llm` with auxiliary task **`futures_advisory`** (registered by `plugins/futures_trading/`). Parsed output follows `external_ai/advisory_schema.py`. Advisory output cannot change the deterministic plan, risk approval, or execution gates.
`scripts/sync_hf.py` persists `fallback_providers` and `auxiliary.futures_advisory.fallback_chain` into Hermes `config.yaml` on first boot (or when an obsolete chain such as `openrouter/free` is detected). After that, set `HERMES_PRESERVE_FALLBACK_PROVIDERS=true` so operator/Hermes-UI edits are not overwritten each boot.
Hermes-wide auxiliary provider fallback (OpenRouter → Google → main model) for built-in tasks (`compression`, `title_generation`, `web_extract`) may still be configured when `HERMES_MANAGE_AUXILIARY_FALLBACKS=true`.
Analysis model env vars are read by `scripts/sync_hf.py` when building the initial advisory chain. They are **not** read directly by `external_ai/advisory.py`, which routes through Hermes auxiliary task routing only.
**Deprecated (ignored):** `EXTERNAL_AI_PROVIDER_ORDER`, `EXTERNAL_AI_PROVIDER_TIMEOUT_SECONDS` — pre-migration direct-chain knobs with no runtime consumer.
## Telegram webhook
| Variable | Default | Purpose |
|---|---|---|
| `TELEGRAM_ENABLED` | `false` | Enable webhook adapter. |
| `TELEGRAM_MODE` | `webhook` | Must remain webhook mode. |
| `TELEGRAM_PUBLIC_BASE_URL` | Space URL | Webhook target base. |
| `TELEGRAM_WEBHOOK_PATH` | `/api/telegram/webhook` | Webhook path. |
| `TELEGRAM_WEBHOOK_SECRET` | none | Telegram secret-token header value. |
| `TELEGRAM_BOOTSTRAP_SECRET` | none | One-time owner claim secret. |
| `TELEGRAM_ALLOWED_USER_IDS` | empty | Comma-separated authorized IDs. |
| `TELEGRAM_BOT_TOKEN` | none | Telegram bot token. |
| `TELEGRAM_PROXY_URL` | empty | Optional direct Bot API proxy. |
| `TELEGRAM_RELAY_URL` | empty | Optional proactive relay. |
| `TELEGRAM_RELAY_SECRET` | empty | HMAC relay secret. |
| `TELEGRAM_STATE_PATH` | `/opt/data/telegram_state.json` | Persisted owner/watchlist state. |
| `TELEGRAM_ALERTS_ENABLED` | `false` | External-scheduler alert evaluation status. |
| `TELEGRAM_COMMAND_RATE_LIMIT` | `10` | Commands per user per minute. |
| `TELEGRAM_SCAN_MAX_SYMBOLS` | `300` | Maximum verified catalog candidates. |
| `TELEGRAM_SCAN_SHORTLIST_SIZE` | `20` | Deterministic shortlist size. |
| `TELEGRAM_SCAN_RESULT_COUNT` | `10` | Displayed result count. |
| `TELEGRAM_SCAN_MAX_CONCURRENCY` | `4` | Analysis concurrency. |
## MCP isolation
| Variable | Default | Requirement |
|---|---|---|
| `LINEAR_MCP_ENABLED` | `false` | Keep unchanged unless separately approved. |
| `UNREAL_ENGINE_MCP_ENABLED` | `false` | Keep disabled unless separately approved. |
## Runtime integrity paths
Advanced overrides used by diagnostics:
```text
HERMES_FUTURES_OVERLAY_MANIFEST
HERMES_OVERLAY_SOURCE
HERMES_SYNC_SCRIPT
```
These should normally use their runtime defaults.
### Cold-start and provider fallback controls
| Variable | Default | Purpose |
|---|---:|---|
| `DS4_TIMEOUT_S` | `6` | Fast-path DS4 request timeout. |
| `DS4_WAKE_TIMEOUT_S` | `25` | One extended retry used only after a retryable DS4 cold-start failure. |
| `HERMES_MAX_CONCURRENT_SESSIONS` | `1` | Resource-safe active session cap written to `config.yaml`. |
| `HERMES_MANAGE_AUXILIARY_FALLBACKS` | `true` | Configure OpenRouter → Google → main-model fallback for Hermes text auxiliary tasks. |
| `HERMES_PRESERVE_FALLBACK_PROVIDERS` | `true` (Space) | Preserve operator/Hermes-UI `fallback_providers` and `auxiliary.futures_advisory` after initial persist; obsolete chains are still refreshed. |
HTTP 402 is terminal only for the current advisory provider. It is not retried against the same provider and the next configured provider is attempted within the total advisory deadline.
|