# litellm-wzrd-momentum

Velocity-aware model routing callback for [LiteLLM](https://docs.litellm.ai/). Routes to the model the ecosystem is converging on using real-time WZRD attention signals. Optionally earns CCM tokens by reporting inference outcomes.

## Install

```bash
pip install litellm-wzrd-momentum
```

## Usage

```python
import litellm
from litellm_wzrd_momentum import WzrdCallback

litellm.callbacks = [WzrdCallback()]
```

Every LiteLLM completion call now fetches the latest velocity signal, ranks models by momentum, and exposes the top pick via `kwargs["wzrd_signal"]`. No config required -- works out of the box with the free signal tier.

### Standalone (no LiteLLM)

```python
from litellm_wzrd_momentum import pick_model

signal = {"models": [{"model": "gpt-4o", "trend": "surging", "score": 0.9, "confidence": "normal"}]}
print(pick_model(signal))  # "gpt-4o"
```

### Earn CCM

Install with the earn extra and point to your agent keypair:

```bash
pip install 'litellm-wzrd-momentum[earn]'
export WZRD_AGENT_KEYPAIR_PATH=~/.config/wzrd/keypair.json
```

The callback reports inference outcomes to the WZRD protocol. Reports accumulate into merkle roots and become claimable CCM.

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `WZRD_PREMIUM` | `false` | Set `true` for enriched signal (trend, confidence, score) |
| `WZRD_CAPABILITY` | - | Filter models by capability: `code`, `chat`, `reasoning`, `vision` |
| `WZRD_AGENT_KEYPAIR_PATH` | - | Ed25519 keypair path for CCM earning via inference reports |
| `WZRD_EARN_ENABLED` | `true` | Set `false` to disable reporting (signal routing still works) |

## Signal API

Live velocity signals powering the router:

- **Free**: `GET https://api.twzrd.xyz/v1/signals/momentum`
- **Premium**: `GET https://api.twzrd.xyz/v1/signals/momentum/premium`
- **Filtered**: append `?capability=code` (or `chat`, `reasoning`, `vision`)

Signals refresh every 300s from 4-platform ingestion (HuggingFace, GitHub, ArtificialAnalysis, OpenRouter).

## How Ranking Works

Models are scored by a composite of:

- **Trend** -- surging (+3), accelerating (+2), stable (0), decelerating (-1), cooling (-2)
- **Score** -- normalized velocity (0-1), weighted at 0.3x
- **Confidence** -- normal (1x), low (0.5x), insufficient (0x)

The top-ranked model is surfaced as `kwargs["wzrd_signal"]["top_model"]` in LiteLLM callbacks.

## License

MIT
