Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 5 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ Guidance for AI coding agents working with the BlockRun Python SDK.

## Project Overview

**blockrun-llm** is a Python SDK for pay-per-request access to AI models (GPT, Claude, Gemini, DeepSeek, NVIDIA) using API account credit or x402 wallets on Solana and Base. **Includes 8 fully-free NVIDIA-hosted models** — DeepSeek V4 Flash (1M ctx), Nemotron Nano Omni (vision), Qwen3 Next + Coder, Llama 4 Maverick, Mistral Small 4, plus `gpt-oss-120b/20b` (hidden from `/v1/models` but direct calls still work). Accessible via `routing_profile="free"` or any `nvidia/*` model id.
**blockrun-llm** is a Python SDK for pay-per-request access to AI models (GPT, Claude, Gemini, DeepSeek, NVIDIA) using API account credit or x402 wallets on Solana and Base. **Includes free models** ($0 in and out): the `free` routing profile ranks the ones in `FREE_TIERS` (`blockrun_llm/router_adapter.py`), and the README's Free Tier table lists the ones to pin by id. Some listed free ids are now answered by a different model; the README names them. Never hardcode a free-model list here: check the live catalog (`GET /v1/models`) instead.

**Package:** `blockrun-llm` (PyPI)
**Python:** >=3.9
Expand All @@ -20,7 +20,10 @@ blockrun-llm/
│ ├── client.py # LLMClient, AsyncLLMClient
│ ├── anthropic_client.py # AnthropicClient (official SDK wrapper)
│ ├── solana_client.py # SolanaLLMClient (Solana payments)
│ ├── router.py # ClawRouter smart routing
│ ├── router_core/ # Port of @blockrun/router-core (do not hand-edit; re-port from upstream)
│ ├── router_adapter.py # Catalog resolution, free profile, xai/*-only search routing
│ ├── router.py # Back-compat shim over router_core
│ ├── decisions.py # decisions() body check (POST /v1/decisions)
│ ├── image.py # Image generation client
│ ├── types.py # Pydantic models and type definitions
│ ├── validation.py # Input validation utilities
Expand Down
25 changes: 25 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,31 @@ All notable changes to blockrun-llm will be documented in this file.

## Unreleased

### Added
- **`decisions()`: typed judgments** on `LLMClient`, `AsyncLLMClient`,
`SolanaLLMClient` and `AsyncSolanaLLMClient` (`POST /v1/decisions`, OpenAI
Decisions-compatible, `gpt-6-luna`): `predicate` / `choice` / `score`
questions get one typed answer each (`DecisionsResponse`). Works with an API
key and with x402 on Base, Arc and Solana; only input tokens are billed
(live: $0.001045 on Solana for two questions). A malformed request raises
`ValueError` before anything is sent. Never served from the local cache.

### Fixed
- **Search on a non-xAI model is refused before sending.** `search=True`,
`search_parameters` (other than `mode: "off"`) or an `x_search` /
`web_search` tool on a non-`xai/*` model (or fallback) raised a paid-path
400 `SEARCH_UNSUPPORTED` from the gateway; it now raises `ValueError` with
nothing sent. The `chat()` / `chat_completion()` docstring examples used
`openai/gpt-5.2` with `search=True` and now use `xai/grok-4.7`.
- **`smart_chat_completion(..., search=True)` stays on `xai/*`.** The routed
chain is narrowed to its `xai/*` candidates; when it has none, it falls back
to the catalog's search-capable xAI models, cheapest first (`premium`: most
capable first), as the TypeScript SDK does. `routing_profile="free"` with
search raises `ValueError` (no free model serves search).
- `SurfClient`'s deprecation warning pointed at `LLMClient.price`, which does
not exist; it now names `PriceClient`, `LLMClient.pm` and
`LLMClient.defi` / `LLMClient.dex`.

### Docs
- **README model tables re-synced with the live catalog** (`GET /v1/models`,
2026-11-15). Added `anthropic/claude-fable-5.2`, `google/gemini-4-carbon`,
Expand Down
7 changes: 4 additions & 3 deletions CLAUDE.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# BlockRun LLM SDK (Python)

Python SDK for <!-- br:models.chatVisible -->91<!-- /br:models.chatVisible --> LLMs plus image/video/music/speech generation, standalone search, multi-chain RPC, and Pyth-backed market data — paid two ways: a BlockRun API key drawing on prepaid account credit, or USDC micropayments via x402 where the wallet signature is the authentication and the key never leaves your machine.
Python SDK for <!-- br:models.chatVisible -->91<!-- /br:models.chatVisible --> LLMs plus image/video/music/speech generation, standalone search, multi-chain RPC, free market data (crypto / FX / commodity daily closes), and typed judgments (`decisions()`) — paid two ways: a BlockRun API key drawing on prepaid account credit, or USDC micropayments via x402 where the wallet signature is the authentication and the key never leaves your machine.

## Commands

Expand All @@ -25,7 +25,7 @@ blockrun_llm/
├── x402.py # x402 payment protocol
├── poll_auth.py # Solana media-poll ownership proofs (x-poll-* headers)
├── router_core/ # Port of @blockrun/router-core (shared with the TS SDK + gateway)
├── router_adapter.py # Host glue: catalog ids, payment floors, free profile
├── router_adapter.py # Host glue: catalog ids, payment floors, free profile, xai/*-only search routing
├── router.py # Back-compat shim over router_core
├── types.py # Type definitions
├── validation.py # Input validation
Expand All @@ -37,7 +37,8 @@ blockrun_llm/
├── portrait.py # Virtual Portrait enrollment (AI characters)
├── realface.py # RealFace enrollment (real-person likeness)
├── search.py # Standalone Grok Live Search
├── price.py # Pyth market data (crypto/fx/commodity/stocks)
├── decisions.py # decisions() body check — typed judgments (POST /v1/decisions)
├── price.py # Market data: crypto/fx/commodity daily closes (free); stock lists (price/history 501)
├── rpc.py # Multi-chain JSON-RPC (Tatum gateway, 40+ chains)
└── anthropic_client.py # Anthropic-compatible client
```
Expand Down
47 changes: 45 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1070,6 +1070,46 @@ for url in result.citations or []:
print(url)
```

## Decisions — typed judgments (`decisions()`)

`decisions()` asks `gpt-6-luna` questions with a fixed answer space and gets one
typed answer per question instead of text: a `predicate` (probability that it
holds), a `choice` (one of your values, with per-value probabilities) or a
`score` (position on an ordered rubric). Request and response match OpenAI's
Decisions API. It is on `LLMClient`, `AsyncLLMClient`, `SolanaLLMClient` and
`AsyncSolanaLLMClient`, with an API key or a wallet.

```python
from blockrun_llm import LLMClient

client = LLMClient()

result = client.decisions(
"My card was charged twice for one order and nobody answers my emails.",
[
{"type": "predicate", "name": "urgent", "instructions": "Does this need a reply today?"},
{"type": "choice", "name": "team", "instructions": "Which team owns this?",
"choices": [{"value": "billing"}, {"value": "shipping"},
{"value": "none", "description": "fits no team"}]},
{"type": "score", "name": "anger", "instructions": "How upset is the writer?",
"levels": [{"label": "calm"}, {"label": "annoyed"}, {"label": "furious"}]}, # lowest first
],
)
print(result.answers[0]["probability"]) # 0.85
print(result.answers[1]["choice"]) # 'billing'
print(result.answers[2]["score"]) # 1 (index on the rubric)
```

Only input tokens are billed. A wallet call pays the 402's quote: an
upper-bound estimate of the input tokens plus the $0.001 transaction fee. With
an API key the account is billed on reported tokens. `input` is a string or
messages with text and inline `data:image/*` images (hosted image URLs are
refused); the gateway caps a call at 64 questions, 255 choices or levels each,
120,000 characters and 8 images, and refuses an over-limit request with a 400
before any payment. A malformed request (no questions, a duplicate name, a
choice without choices) raises `ValueError` before anything is sent. A `choice`
always picks one of your values, so give it a `none` value.

## Market Data (`PriceClient`)

Crypto, FX and commodity prices, OHLC history and symbol lists — all **free**,
Expand Down Expand Up @@ -1446,8 +1486,11 @@ from blockrun_llm import LLMClient

client = LLMClient()

# Live Search runs on xai/* models only; any other model answers
# 400 SEARCH_UNSUPPORTED.
# Live Search runs on xai/* models only. The SDK refuses search on any other
# model with a ValueError before anything is sent or paid (the gateway would
# answer 400 SEARCH_UNSUPPORTED). smart_chat_completion(..., search=True)
# routes to the catalog's search-capable xAI models: cheapest first, most
# capable first on routing_profile="premium".
# Simple: enable live search with search=True
response = client.chat(
"xai/grok-4.7",
Expand Down
4 changes: 4 additions & 0 deletions blockrun_llm/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,7 @@
list_models,
testnet_client,
)
from .decisions import DECISIONS_DEFAULT_MODEL
from .image import ImageClient
from .music import MusicClient
from .phone import PhoneClient
Expand Down Expand Up @@ -120,6 +121,7 @@
ChatCompletionChunk,
ChatMessage,
ChatResponse,
DecisionsResponse,
ImageData,
ImageModel,
ImageResponse,
Expand Down Expand Up @@ -200,6 +202,7 @@

__version__ = "1.22.3"
__all__ = [
"DECISIONS_DEFAULT_MODEL",
"DEFAULT_API_KEY_URL",
"ENV_API_KEY",
"ENV_API_KEY_URL",
Expand All @@ -225,6 +228,7 @@
"ChatCompletionChunk",
"ChatMessage",
"ChatResponse",
"DecisionsResponse",
"ImageClient",
"ImageData",
"ImageModel",
Expand Down
94 changes: 92 additions & 2 deletions blockrun_llm/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -61,9 +61,12 @@
resolve_api_key,
wallet_only,
)
from .decisions import build_decisions_body
from .router_adapter import (
BASE_MINIMUM_PAYMENT_USD,
build_model_pricing,
requests_search,
require_search_model,
route_with_catalog,
routing_profile_for_model,
routing_text,
Expand All @@ -81,6 +84,7 @@
APIError,
ChatCompletionChunk,
ChatResponse,
DecisionsResponse,
ImageResponse,
PaymentError,
RetiredEndpointError,
Expand Down Expand Up @@ -1117,6 +1121,7 @@ def smart_chat_completion(
tool_choice=tool_choice,
conversation_chars=view["conversation_chars"],
has_vision=view["has_vision"],
search=requests_search(search, search_parameters, tools),
minimum_payment_usd=BASE_MINIMUM_PAYMENT_USD,
)
response = self.chat_completion(
Expand Down Expand Up @@ -1217,7 +1222,7 @@ def chat(

# With xAI Live Search (for real-time X/Twitter data)
response = client.chat(
"openai/gpt-5.2",
"xai/grok-4.7",
"What are the latest posts from @blockrunai?",
search=True # Enable live search
)
Expand Down Expand Up @@ -1303,7 +1308,7 @@ def chat_completion(

# With xAI Live Search
result = client.chat_completion(
"openai/gpt-5.2",
"xai/grok-4.7",
[{"role": "user", "content": "Latest news about AI?"}],
search=True
)
Expand Down Expand Up @@ -1372,6 +1377,7 @@ def chat_completion(
body["top_p"] = top_p

# Handle xAI Live Search parameters
require_search_model([model, *(fallback_models or [])], search, search_parameters, tools)
if search_parameters is not None:
body["search_parameters"] = search_parameters
elif search is True:
Expand Down Expand Up @@ -1497,6 +1503,7 @@ def chat_completion_stream(
body["tools"] = tools
if tool_choice is not None:
body["tool_choice"] = tool_choice
require_search_model([model, *(fallback_models or [])], search, search_parameters, tools)
if search_parameters is not None:
body["search_parameters"] = search_parameters
elif search is True:
Expand Down Expand Up @@ -2432,6 +2439,46 @@ def search(
data = self._request_with_payment_raw("/v1/search", body)
return SearchResult(**data)

def decisions(
self,
input: str | list[dict[str, Any]],
questions: list[dict[str, Any]],
*,
model: str | None = None,
metadata: dict[str, str] | None = None,
) -> DecisionsResponse:
"""
Typed judgments (OpenAI Decisions-compatible, ``gpt-6-luna``): one typed
answer per question instead of text.

Each question has a fixed answer space: ``predicate`` (probability that
it holds), ``choice`` (one of your ``choices[].value``, with per-value
probabilities) or ``score`` (position on ``levels``, lowest first).
Only input tokens are billed. With a wallet the 402 quotes an
upper-bound estimate of them plus the $0.001 fee, and that quote
settles; with an API key the account pays the reported tokens. A request
over the gateway's limits is refused with a 400 before payment. A
``choice`` always picks one of your values: give it a ``none`` value.

Raises:
ValueError: on a malformed request, before anything is sent.

Example:
result = client.decisions(
"My card was charged twice for one order.",
[
{"type": "predicate", "name": "urgent",
"instructions": "Does this need a reply today?"},
{"type": "choice", "name": "team", "instructions": "Which team owns this?",
"choices": [{"value": "billing"}, {"value": "shipping"}, {"value": "none"}]},
],
)
print(result.answers[0]["probability"], result.answers[1]["choice"])
"""
body = build_decisions_body(input, questions, model=model, metadata=metadata)
data = self._request_with_payment_raw("/v1/decisions", body)
return DecisionsResponse(**data)

# ── Exa Web Search (Powered by Exa) ─────────────────────────────────────

def exa(self, path: str, body: dict[str, Any]) -> dict[str, Any]:
Expand Down Expand Up @@ -3327,6 +3374,7 @@ async def smart_chat_completion(
tool_choice=tool_choice,
conversation_chars=view["conversation_chars"],
has_vision=view["has_vision"],
search=requests_search(search, search_parameters, tools),
minimum_payment_usd=BASE_MINIMUM_PAYMENT_USD,
)
response = await self.chat_completion(
Expand Down Expand Up @@ -3449,6 +3497,7 @@ async def chat_completion(
body["top_p"] = top_p

# Handle xAI Live Search parameters
require_search_model([model, *(fallback_models or [])], search, search_parameters, tools)
if search_parameters is not None:
body["search_parameters"] = search_parameters
elif search is True:
Expand Down Expand Up @@ -3538,6 +3587,7 @@ async def chat_completion_stream(
body["tools"] = tools
if tool_choice is not None:
body["tool_choice"] = tool_choice
require_search_model([model, *(fallback_models or [])], search, search_parameters, tools)
if search_parameters is not None:
body["search_parameters"] = search_parameters
elif search is True:
Expand Down Expand Up @@ -4342,6 +4392,46 @@ async def search(
data = await self._request_with_payment_raw("/v1/search", body)
return SearchResult(**data)

async def decisions(
self,
input: str | list[dict[str, Any]],
questions: list[dict[str, Any]],
*,
model: str | None = None,
metadata: dict[str, str] | None = None,
) -> DecisionsResponse:
"""
Typed judgments (OpenAI Decisions-compatible, ``gpt-6-luna``): one typed
answer per question instead of text.

Each question has a fixed answer space: ``predicate`` (probability that
it holds), ``choice`` (one of your ``choices[].value``, with per-value
probabilities) or ``score`` (position on ``levels``, lowest first).
Only input tokens are billed. With a wallet the 402 quotes an
upper-bound estimate of them plus the $0.001 fee, and that quote
settles; with an API key the account pays the reported tokens. A request
over the gateway's limits is refused with a 400 before payment. A
``choice`` always picks one of your values: give it a ``none`` value.

Raises:
ValueError: on a malformed request, before anything is sent.

Example:
result = await client.decisions(
"My card was charged twice for one order.",
[
{"type": "predicate", "name": "urgent",
"instructions": "Does this need a reply today?"},
{"type": "choice", "name": "team", "instructions": "Which team owns this?",
"choices": [{"value": "billing"}, {"value": "shipping"}, {"value": "none"}]},
],
)
print(result.answers[0]["probability"], result.answers[1]["choice"])
"""
body = build_decisions_body(input, questions, model=model, metadata=metadata)
data = await self._request_with_payment_raw("/v1/decisions", body)
return DecisionsResponse(**data)

# ── Prediction Markets (Powered by Predexon) ────────────────────────────

async def pm(self, path: str, **params: Any) -> dict[str, Any]:
Expand Down
Loading
Loading