Metadata-Version: 2.4
Name: langchain-wzrd
Version: 0.3.1
Summary: WZRD velocity-aware model selection, inference, and earn-loop tooling for LangChain.
License-Expression: MIT
Project-URL: Homepage, https://twzrd.xyz
Project-URL: Signal API, https://api.twzrd.xyz/v1/signals/momentum
Project-URL: Source, https://github.com/twzrd-sol/wzrd-final/tree/main/integrations/langchain-wzrd
Keywords: langchain,llm,routing,wzrd,model-selection,velocity,tools
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: langchain-core>=0.2
Requires-Dist: httpx>=0.24
Requires-Dist: wzrd-client>=1.3.0
Provides-Extra: chat
Requires-Dist: langchain-openai>=0.1; extra == "chat"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"

# langchain-wzrd

LangChain tools for WZRD velocity signals. Real-time model selection across 100+ LLMs.

## Install

```bash
pip install langchain-wzrd
```

## Quickstart: earn CCM with a LangChain agent (one run, ~6 minutes)

This walks you from `pip install` to a LangChain ReAct agent earning $CCM on
Solana mainnet — no wallet extension, no seed phrase to copy, no faucet to
visit. The whole run takes about 6 minutes end-to-end, most of which is the
script waiting 5 minutes for the WZRD global merkle root to publish so your
rewards become claimable.

### What you'll see

A LangGraph ReAct agent whose reasoning brain is velocity-picked from free
OpenRouter models. The agent calls two WZRD tools: `WzrdModelPicker` to read
live model momentum, and `WzrdEarnTool` (with `max_cycles=2`) to run the
full earn loop: cycle 1 registers a fresh agent keypair and earns into
`reward_bonuses`, the script waits 5 minutes for the publisher to fold the
bonuses into the next global root, then cycle 2 claims the CCM to your
wallet. On first run, the WZRD server auto-funds the fresh keypair with gas
SOL, so you never need to touch a wallet UI or visit a faucet.

### 1. Install

```bash
pip install 'langchain-wzrd[chat]' langgraph
```

### 2. Get a free OpenRouter key

Sign up at <https://openrouter.ai/keys> (no credit card needed for the free
models the example uses). Then:

```bash
export OPENROUTER_API_KEY=sk-or-v1-...
```

### 3. Run

```bash
curl -O https://raw.githubusercontent.com/twzrd-sol/wzrd-final/main/integrations/langchain-wzrd/examples/earn_agent.py
python earn_agent.py
```

That's it. No keypair generation. No faucet visit. The script:

1. Velocity-picks an agent brain from live OpenRouter free models
2. Auto-generates `~/.config/solana/wzrd-agent.json` (deliberately refuses to
   touch your `~/.config/solana/id.json`)
3. Authenticates with the WZRD oracle, which auto-grants gas SOL to the
   fresh keypair in the background so claims are truly gasless
4. Runs cycle 1: reports a server-witnessed inference, earning into
   `reward_bonuses` (a 1,000 CCM signup bonus + ~200 CCM per verified
   inference)
5. **Waits ~5 minutes** while the global merkle root publisher folds the
   fresh bonuses into the next on-chain root
6. Runs cycle 2: the claim path now sees published allocations and
   claims the CCM to your wallet via gasless relay
7. Prints the wallet pubkey, the claim transaction signature, and
   verification commands

### 4. Verify

```bash
wzrd wallet      # shows your auto-generated keypair + balances
wzrd balance     # shows CCM balance and lifetime earnings
```

Or paste the wallet pubkey into [Solscan](https://solscan.io/) to see the
auto-grant transactions and CCM token balance directly on-chain.

### What's the magic?

- **No wallet UI**: `wzrd-client` auto-generates a dedicated agent keypair on
  first run and explicitly refuses to use `~/.config/solana/id.json`, so your
  main wallet is never touched.
- **No faucet**: the WZRD server's `onboard_new_agent` flow auto-grants gas
  SOL to fresh keypairs in the background. The gas grant uses an idempotency
  lock so you only get one per pubkey. Claims are truly gasless, so the
  tiny SOL grant is all you ever need.
- **No model selection**: every cycle, the agent reads
  `https://api.twzrd.xyz/v1/signals/momentum` and picks the top model by
  composite trend × velocity × confidence.
- **No transaction building**: `WzrdEarnTool` wraps `wzrd.run_loop()`, which
  handles auth, inference, reporting, and claim-via-gasless-relay all in
  one function. The LangChain agent just decides when to call it.

Source: [`examples/earn_agent.py`](examples/earn_agent.py)

## Tools

### WzrdModelPicker (free, zero config)

Returns the best model for a task based on live adoption velocity.

```python
from langchain_wzrd import WzrdModelPicker
from langchain.agents import initialize_agent, AgentType
from langchain_openai import ChatOpenAI

tools = [WzrdModelPicker()]
llm = ChatOpenAI(model="gpt-4o-mini")
agent = initialize_agent(tools, llm, agent=AgentType.ZERO_SHOT_REACT_DESCRIPTION)
agent.run("What's the best model for code generation right now?")
```

With LangGraph:

```python
from langchain_wzrd import WzrdModelPicker
from langgraph.prebuilt import create_react_agent

tools = [WzrdModelPicker()]
agent = create_react_agent(llm, tools)
result = agent.invoke({"messages": [("user", "Which model has the most momentum?")]})
```

### WzrdInference (paid, requires API key)

Runs inference through WZRD's oracle. Auto-selects the top velocity model if none specified.

```python
from langchain_wzrd import WzrdInference

tools = [WzrdInference(api_key="your-key")]
# or set WZRD_API_KEY env var and use WzrdInference() with no args
```

### ChatWZRD (velocity-routed ChatModel)

Drop-in ChatModel that auto-routes every call to the top velocity model.

```python
from langchain_wzrd import ChatWZRD

llm = ChatWZRD(task="code", openai_api_key="sk-or-...")
response = llm.invoke("Write a Python sort function")
```

## How it works

Signals are cached for 60s. The free momentum endpoint requires no auth.
Models are ranked by a composite of trend direction, velocity score, and confidence.
