Metadata-Version: 2.4
Name: wzrd-client
Version: 0.5.2
Summary: Which AI model should I use? WZRD picks the fastest-growing model in real time. Velocity signals from 4 platforms, on-chain oracle on Solana, earn CCM by reporting.
Author-email: twzrd <twzrd@twzrd.xyz>
License-Expression: MIT
Project-URL: Homepage, https://twzrd.xyz
Project-URL: Repository, https://github.com/twzrd-sol/wzrd-final
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,defi,ccm,earn,crypto
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 I use?** WZRD tells you — in real time.

```python
pip install wzrd-client
```

```python
import wzrd

model = wzrd.pick("code")  # → "Qwen/Qwen3.5-9B" (right now)
```

WZRD tracks adoption velocity of 100+ open-source AI models across HuggingFace, GitHub, OpenRouter, and ArtificialAnalysis. It measures which models developers are actually moving to — not benchmarks, not vibes, real momentum.

### Automatic earn loop

```python
import wzrd

wzrd.run_loop()  # picks, reports, earns CCM, claims — runs forever
```

One function turns any Python script into an earning agent on Solana. No SOL required for claims (gasless relay). CCM tokens accumulate in your wallet automatically.

### Use as a routing prior

```python
model = wzrd.pick("code")      # best model for code tasks
models = wzrd.shortlist("chat") # top 5 models for chat
details = wzrd.pick_details("reasoning")  # full signal with trend, confidence, score
```

Works with any inference provider. Pass the result to OpenRouter, OpenAI, Anthropic, HuggingFace — wherever you route your LLM calls.

### On-chain oracle

15 Switchboard feeds on Solana mainnet. Any program can read model velocity data. 2 price feeds (CCM/USD, vLOFI/USD) for DeFi composability.

## Earn CCM While Routing

The full self-serve loop is:

```python
import wzrd

choice = wzrd.pick_details("code")

agent = wzrd.WZRDAgent.from_env()
agent.authenticate()
agent.report_pick(choice, quality_score=0.9)

print(agent.earned()["signup_bonus_ccm"])
```

No manual onboarding. No founder approval. An agent can discover the package, authenticate with its own Solana keypair, report real routing decisions, and enter the CCM reward loop on its own.

## 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"`.

## Install

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

## Quick start

```python
import wzrd

model = wzrd.pick("code")
print(model)
```

## Agent auth and CCM loop

If you want an agent to authenticate, report routing decisions, and enter the CCM reward loop:

```python
import wzrd

choice = wzrd.pick_details("code")

agent = wzrd.WZRDAgent.from_env()
session = agent.authenticate()  # uses ~/.config/solana/id.json by default
status = agent.status()
receipt = agent.report_pick(choice, quality_score=0.9, latency_ms=1200)

print(session.pubkey)
print(status["next_step"])
print(receipt["contribution_id"])
```

`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 both signup bonus + signal rewards
- `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.

Candidate-aware routing:

```python
import wzrd

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

If you want the metadata for logging or telemetry, use:

```python
choice = wzrd.pick_details("code")
print(choice.model, choice.score, choice.trend, choice.confidence)
```

## Environment variables

- `WZRD_API_URL`: signal endpoint override
- `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

## 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 into the CCM loop
