# Argus MCP paper

## Purpose

Argus MCP is a read-only market context service for the trader27 stack.

It does not make trading decisions and it does not dispatch actions.
Its job is to observe cross-market conditions and publish a compact, explainable description of the current environment so Hermes MCP can reason better.

In short:
- Argus senses
- Hermes interprets and decides
- Trader executes

## What Argus provides

Argus exposes two read-only products:
- `get_snapshot()`
- `get_regime()`

### Snapshot

The snapshot is the rich payload.
It contains:
- `snapshot_id`
- `generated_at`
- `regime`
- `confidence`
- `summary`
- `components`
- `signals`
- `impacts`
- `source_status`

Use the snapshot when Hermes wants the full evidence trail.

### Regime

The regime payload is the compact payload.
It contains:
- `snapshot_id`
- `generated_at`
- `regime`
- `confidence`
- `summary`
- `components`

Use the regime payload when Hermes wants a small, decision-friendly context object.

## Provider policy

### Finnhub

Finnhub is the primary live source.
Use it for the fast layer and for most ETF, equity, volatility, transport, and crypto proxies.

### Twelve Data

Twelve Data is optional slow enrichment only.
Use it only where Finnhub is missing something useful.
It should be treated as sparse context, not the primary engine.

Current policy:
- long cache time, 3 hours
- avoid frequent refreshes
- prefer it only for selective fallback or enrichment symbols

This means Argus should still remain useful even if Twelve Data is removed.

### Metals MCP

Metals MCP is the dedicated hard-asset source.
Use it for spot metals context and for the precious-metal leg of real-asset pressure.
It should be cached and treated as read-only context, not as a decision engine.

## Current signal domains

### 1. Risk appetite

Purpose:
measure speculative participation and growth leadership.

Current proxies:
- `QQQ`
- `SPY`
- `XLK`
- `SMH`
- `BTCUSD`
- `ETHUSD`

### 2. Stress

Purpose:
measure volatility and defensive positioning.

Current proxies:
- `VXX`
- `UVXY`
- `TLT`
- inverse contribution from `HYG`

### 3. Liquidity

Purpose:
measure whether conditions are supportive or tightening.

Current proxies:
- `UUP`
- `HYG`
- confirming support from `QQQ` and `BTCUSD`

### 4. Real asset pressure

Purpose:
measure hard-asset, inflation, and commodity pressure.

Current proxies:
- `GLD`
- `XAU`
- `XAG`
- `XPT`
- `XPD`
- `XLE`
- `USO`

### 5. Transport pressure

Purpose:
measure supply chain, freight, airline, logistics, and shipping stress.
Transport weakness contributes to fear and stress because it can imply deteriorating demand, strained supply lines, or both.

Current proxies:
- `IYT`
- `JETS`
- `ZIM`
- `SBLK`
- `DHT`
- `CHRW`

## Reported states

Argus currently emits these regime states:
- `risk_on`
- `risk_off`
- `stress`
- `compression`
- `real_asset_inflation`
- `neutral`
- `no_data`

### Meanings

#### risk_on
Speculative participation and liquidity are supportive.
Useful for Hermes as a tailwind for breakout or active directional behavior.

#### risk_off
Defensive positioning is building.
Useful for Hermes as a warning against aggressive participation.

#### stress
Volatility and transport or macro strain dominate.
Useful for Hermes as a caution state with elevated fear and fragility.

#### compression
Signals are subdued, range-like, and not strongly directional.
Useful for Hermes as a favorable background for grid or mean-reverting logic.

#### real_asset_inflation
Hard assets and commodities are leading relative to financial assets.
Useful for Hermes as a sign that nominal risk may be mixed even if headline stress is not extreme.

#### neutral
Signals are mixed and the top regime is not clearly separated.
Useful for Hermes as a low-conviction state.

#### no_data
Not enough inputs are available.
Useful for Hermes as a degraded mode signal.

## How Hermes should use Argus

Hermes should use Argus as context, not as a command channel.

Recommended pattern:
1. read `regime`
2. read `confidence`
3. read `components`
4. optionally inspect `snapshot` for evidence details

### Suggested Hermes interpretation rules

- `compression` + `range_bound` + `macro_stress_low`
  - favor grid or range-harvesting logic
- `risk_on` + `tech_leadership` + `liquidity_supportive`
  - allow stronger directional bias, but still respect local trader evidence
- `stress` + `transport_stress`
  - reduce aggression, widen caution, avoid trusting short-term noise
- `real_asset_inflation` + `gold_bid` + `energy_pressure_up`
  - treat the market as late-cycle or inflation-sensitive, not cleanly bullish
- `neutral` or `low_confidence`
  - avoid overreacting to Argus alone

## Design principles

- keep the public surface small
- keep the output explainable
- prefer a few strong proxies over symbol sprawl
- prefer cached, auditable data over rate-limit churn
- let Hermes make decisions, not Argus

## Next likely improvements

- continue tuning transport versus stress weights
- evaluate whether Twelve Data should remain enabled at all
- later integrate metals-mcp or another dedicated hard-asset source for gold and related signals
- stabilize the state enum contract before deeper Hermes integration