Metadata-Version: 2.4
Name: litellm-wzrd-momentum
Version: 0.3.1
Summary: Velocity-aware model routing callback for LiteLLM. Routes via WZRD attention signals, earns CCM.
Author-email: twzrd <twzrd@twzrd.xyz>
License-Expression: MIT
Project-URL: Homepage, https://github.com/twzrd-sol/litellm-wzrd-momentum
Project-URL: Documentation, https://github.com/twzrd-sol/litellm-wzrd-momentum#readme
Project-URL: Signal API, https://api.twzrd.xyz/v1/signals/momentum
Project-URL: WZRD Protocol, https://twzrd.xyz
Keywords: litellm,llm,routing,momentum,wzrd,ai,model-selection,velocity
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.24
Provides-Extra: litellm
Requires-Dist: litellm>=1.0; extra == "litellm"
Provides-Extra: earn
Requires-Dist: wzrd-client>=0.5.5; extra == "earn"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"

# 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
