# Hermes ⇄ Trader Strategy Contract (v0.1)

This document defines what Hermes needs from Trader-managed strategies in order to make selection decisions.

## Scope

- Trader runs the strategies.
- Hermes selects which configured strategy is active for each account and market.
- A strategy is bound to a specific account and market.
- Hermes queries strategies to see the available options for that account-market pair.
- Trader may turn strategies on or off when instructed by Hermes.
- Trader does not decide the global strategy choice on its own.

## What a strategy represents

A strategy is an account-market specific operating mode.
It is not a generic idea detached from venue, balance, or market context.

## Required strategy bindings

Each configured strategy must be tied to:
- `strategy_id`
- `account_id`
- `market`
- `base_currency`
- `quote_currency`
- `enabled_state`

Hermes should be able to ask, for a given account and market, which strategies exist and whether they are currently enabled.

## What Hermes needs from a strategy

When Hermes queries a strategy, it must receive the information below.

### Identity and binding
- `strategy_id`
- `strategy_name`
- `account_id`
- `market`
- `base_currency`
- `quote_currency`
- `enabled_state`
- `mode`

### Balance and exposure
- `account_balance`
- `available_balance`
- `base_position`
- `quote_position`
- `open_orders`
- `reserved_balance`
- `exposure`
- `free_margin` where relevant

### Market suitability
- `expected_market_regime`
- `avoided_market_regime`
- `risk_profile`
- `liquidity_expectation`
- `event_risk_expectation`
- `volatility_expectation`

### Live operating state
- `status`
- `recent_changes`
- `decision_history`
- `current_intent`
- `last_transition`
- `last_update`
- `uncertainty`
- `confidence`

### Execution feedback
- `fills`
- `slippage`
- `latency`
- `rejections`
- `execution_quality`
- `stress`
- `venue_health`

### Strategy explanation
- `current_reason`
- `key_drivers`
- `warnings`
- `constraints`

## Hermes decision inputs

Hermes should decide using the returned strategy snapshot plus external market information.
The minimum decision inputs are:
- market regime
- liquidity state
- event risk
- sentiment pressure
- current strategy state
- balance and exposure state
- execution quality
- confidence and uncertainty
- recent changes

## Strategy response shape

A strategy query should return a compact structured snapshot with nested sections. Only information that changes Hermes decisions should be included.

Example:

```json
{
  "identity": {
    "strategy_id": "btc-vienna-trend-1",
    "strategy_name": "trend_following",
    "account_id": "acc-01",
    "market": "BTC/USD",
    "base_currency": "BTC",
    "quote_currency": "USD"
  },
  "control": {
    "enabled_state": "on",
    "mode": "active"
  },
  "fit": {
    "expected_market_regime": "trend",
    "avoided_market_regime": "range",
    "risk_profile": "medium",
    "liquidity_expectation": "normal",
    "event_risk_expectation": "low",
    "volatility_expectation": "moderate"
  },
  "position": {
    "account_balance": {
      "base": 0.42,
      "quote": 18500.0
    },
    "available_balance": {
      "base": 0.12,
      "quote": 9400.0
    },
    "base_position": 0.30,
    "quote_position": 0.0,
    "reserved_balance": 1200.0,
    "open_orders": 2,
    "exposure": "long",
    "free_margin": 8200.0
  },
  "state": {
    "status": "running",
    "recent_changes": ["scaled in", "trimmed exposure"],
    "decision_history": ["held", "added", "held"],
    "current_intent": "follow upward structure",
    "last_transition": "2026-04-15T18:10:00Z",
    "last_update": "2026-04-15T18:25:00Z"
  },
  "assessment": {
    "confidence": 0.78,
    "uncertainty": "low",
    "current_reason": "trend intact, balance sufficient, execution stable",
    "key_drivers": ["trend", "balance", "liquidity"],
    "warnings": ["minimum_hold_minutes=15"]
  },
  "execution": {
    "fills": 12,
    "slippage": 0.0012,
    "latency": "normal",
    "rejections": 0,
    "execution_quality": "good",
    "stress": "low",
    "venue_health": "good"
  }
}
```

## Strategy modes

A strategy may expose modes, but modes are not separate strategies.
Examples:
- slow trend
- strong trend
- cautious mean reversion
- high-volatility breakout

## Enabled and disabled state

Hermes must be able to see whether a strategy is:
- `on`
- `off`
- `paused`
- `error`
- `observe`
- `active`

Trader may manage those states internally, but Hermes needs a clear readback of them.

## Control responsibility

Hermes may instruct Trader to:
- switch a strategy on
- switch a strategy off
- keep a strategy on
- keep a strategy off
- shift risk mode
- pause a strategy
- resume a strategy

Trader should not invent a strategy decision that conflicts with Hermes without an explicit safety reason.

## Selection rules

Hermes selects strategies per account-market combination using:
- regime fit
- balance and exposure fit
- execution quality
- current confidence
- current uncertainty
- recent state changes
- event pressure
- liquidity quality

## Strategy taxonomy

Keep the strategy set small and orthogonal:
- `idle`
- `defensive`
- `trend_following`
- `mean_reversion`
- `grid`
- `breakout`
- `event_driven`

## First implementation order

1. Make the query result shape exact.
2. Make balance and exposure mandatory in strategy snapshots.
3. Make strategy bindings explicit per account and market.
4. Keep Hermes control limited to on/off and risk posture.
5. Implement `idle` and `defensive` first.
6. Implement `trend_following` and `mean_reversion` next.
7. Add `grid`, `breakout`, and `event_driven` after the core set is stable.
8. Add tests for balance reporting, selection inputs, and enable/disable control.

## Versioning

This is v0.1.
Future changes should stay focused on the information Hermes needs to make better decisions, not on exposing implementation detail.