Metadata-Version: 2.4
Name: wzrd-client
Version: 1.1.0
Summary: Python client for the WZRD velocity oracle. Reads AI model adoption signals from 4 platforms. Agents stream CCM on Solana by reporting picks.
Author-email: twzrd <twzrd@twzrd.xyz>
License-Expression: MIT
Project-URL: Homepage, https://twzrd.xyz
Project-URL: Repository, https://github.com/twzrd-sol/wzrd-velocity
Project-URL: Signal API, https://api.twzrd.xyz/v1/signals/momentum
Project-URL: PyPI, https://pypi.org/project/wzrd-client/
Keywords: solana,ai,llm,model-routing,agent,oracle,velocity,inference,openrouter,huggingface,switchboard,ccm,rewards
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: solders>=0.26

# wzrd-client

**Which AI model should your agent use right now?** WZRD tracks real-time developer adoption across HuggingFace, GitHub, OpenRouter, and ArtificialAnalysis. 100+ models. Updated every 5 minutes. Free.

```bash
pip install wzrd-client
```

## Pick a model (zero config)

```python
import wzrd

model = wzrd.pick("code")           # → "Qwen/Qwen3.5-35B-A3B"
details = wzrd.pick_details("code") # trend, score, confidence
top_3 = wzrd.shortlist("code", 3)   # ranked list
```

No API key. No account. Works immediately.

**Task types**: `code`, `chat`, `reasoning`, `math`, `multilingual` — or any string (falls back to general ranking).

## Earn CCM tokens (optional)

Agents that report which model they picked — and what happened — earn CCM tokens on Solana. The usage data makes the signal better, so WZRD pays for it.

```python
wzrd.run_loop(keypair_path="~/.config/solana/id.json")
# authenticates → picks models → runs inference → reports → claims CCM
```

**CCM** (Concentrated Compute Merit) is a Solana token earned by contributing to the velocity oracle. It's not bought — it's earned through verified participation. Agents claim CCM through a gasless relay (no SOL needed for claiming).

**What you need to earn**: A Solana keypair (`solana-keygen new` if you don't have one). That's it.

## Why use this?

- **Save money**: Models change weekly. The one you hardcoded last month might be 10x more expensive than the trending alternative.
- **Better results**: Momentum is a leading indicator. Models gaining adoption fast are usually improving fast.
- **Get paid**: Your usage reports make the oracle more accurate. WZRD pays for that with CCM tokens.

## Raw API

```text
GET https://api.twzrd.xyz/v1/signals/momentum
```

Premium data (velocity EMA, acceleration, quality): set `WZRD_API_URL=https://api.twzrd.xyz/v1/signals/momentum/premium`

## Use as a routing prior

Read the oracle before calling an inference provider:

```python
model = wzrd.pick("code")
models = wzrd.shortlist("chat")
details = wzrd.pick_details("reasoning")
```

Works with any provider. Pass the result to OpenRouter, OpenAI, Anthropic, HuggingFace, or your own router.

## Candidate-aware routing

```python
model = wzrd.pick(
    "code",
    candidates=[
        "openrouter/qwen/qwen3.5-9b",
        "openrouter/qwen/qwen3.5-35b-a3b",
        "anthropic/claude-sonnet-4.6",
    ],
)
```

## Optional rewards while reporting

If you want an agent to authenticate, report routing decisions, and participate in WZRD rewards:

```python
import wzrd

choice = wzrd.pick_details("code")

agent = wzrd.WZRDAgent.from_env()
session = agent.authenticate()
receipt = agent.report_pick(choice, quality_score=0.9, latency_ms=1200)
reward_status = agent.earned()

print(session.pubkey)
print(receipt["contribution_id"])
print(reward_status["signup_bonus_ccm"])
```

No manual onboarding is required. Agents can authenticate with their own Solana keypair, report real routing decisions, and claim rewards through the gasless relay when available.

## Router wrapper

If you want a thin client wrapper, use `WZRDRouter` from `wzrd.router`.
It only wraps clients that expose `client.chat.completions.create(...)`.
Explicit model names pass through unchanged. To trigger WZRD routing, pass `model=None` or a task sentinel like `model="code"` or `model="chat"`.

## Automatic reward loop

```python
import wzrd

wzrd.run_loop()  # picks, reports, checks rewards, claims when available
```

`run_loop()` is the batteries-included path for unattended reporting. It uses the public momentum feed by default and can be pointed at premium explicitly via `WZRD_API_URL`.

## Agent auth

`WZRDAgent.authenticate()` signs the exact server challenge message and sends the signature in the Solana base58 format the API expects. Keypair loading supports:

- `~/.config/solana/id.json`
- `WZRD_AGENT_KEYPAIR_PATH` or `SOLANA_KEYPAIR_PATH`
- `WZRD_AGENT_KEYPAIR` or `SOLANA_KEYPAIR` as a base58 secret or JSON byte array

Authenticated helpers:

- `agent.challenge()` returns the nonce + message format
- `agent.authenticate()` stores the Bearer token on the client
- `agent.status()` reads `/v1/agent/status`
- `agent.earned()` reads `/v1/agent/earned` and surfaces signup bonus + reward status
- `agent.report(...)` posts a manual contribution
- `agent.report_pick(choice, ...)` reports a `pick_details()` result with WZRD metadata attached

The signup bonus is recorded on first auth, then becomes claimable after the next merkle publication cycle.

## Environment variables

- `WZRD_API_URL`: signal endpoint override. Defaults to the public momentum feed.
- `WZRD_API_BASE_URL`: API root for agent auth/report calls
- `WZRD_AGENT_TOKEN`: existing Bearer token for `WZRDAgent`
- `WZRD_AGENT_KEYPAIR_PATH`: path to Solana JSON keypair
- `WZRD_AGENT_KEYPAIR`: Solana base58 secret or JSON byte array
- `WZRD_TIMEOUT_SECONDS`: request timeout
- `WZRD_CACHE_TTL_SECONDS`: cache TTL for fetched signals
- `WZRD_FEED_LIMIT`: number of feed rows to request

## Verify on-chain

WZRD data is published to 9 Switchboard pull oracle feeds on Solana mainnet (7 velocity + 2 price). You can verify any signal independently:

```bash
# Query the Qwen 3.5 9B velocity feed directly on-chain
solana account AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S --output json

# Or view on Solscan:
# https://solscan.io/account/AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S
```

Sample feeds (quote accounts):
| Model | Address |
|-------|---------|
| Qwen 3.5 9B | `AepiFwnbfCvXwA5gtAysMaxoqdwsGiYCN6gFBLGqZf1S` |
| Llama 3.3 70B | `6EgRwhE6db1Aqsxzmp9wj6QH2y5ZEji1xe1YdovwmD9g` |
| Kimi K2.5 | `5xmwRtTgcCz6R2KapxpEXVjCNcZCpe24DnCC295S769w` |
| Qwen3-Coder-Next | `g3RRSmg4PJjDNCq3jkTutMB8431UMMtRTNBRpc7UfVV` |

Full feed registry with all 7 velocity + 2 price feeds is available via `wzrd.oracle.list_feeds()`.

## What it returns

- `pick()` returns a model name string
- `pick_details()` returns a structured record
- `shortlist()` returns ranked records
- `compare()` explains the relative signal strength between two models
- `WZRDAgent` authenticates an agent wallet and reports contributions for rewards
