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
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,21 @@ All notable changes to blockrun-llm will be documented in this file.

## Unreleased

## 1.23.1 — 2026-11-18

### Fixed
- **`decisions()` with `model="gemini-decision-1"`** now raises `ValueError`
before sending when a choice or a score level has no `description` string.
Gemini Decision 1 needs one on every item (an empty string is fine); the
gateway refused the request with a 400 before payment, so nothing was ever
charged, but the call failed with a less helpful message. `gpt-6-luna` is
unchanged. The README and docstring examples now give every choice a
`description`, so they work on both models.
- **Docs: a `score` answer can be fractional.** It is the probability-weighted
position on the rubric; Gemini Decision 1 spreads probability across levels
(1.43 on the README example) where luna answered 1. The README comment said
"index on the rubric".

## 1.23.0 — 2026-11-16

### Added
Expand Down
20 changes: 17 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -1089,15 +1089,17 @@ result = client.decisions(
[
{"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"},
"choices": [{"value": "billing", "description": "payments and refunds"},
{"value": "shipping", "description": "delivery"},
{"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
"levels": [{"label": "calm", "description": ""}, {"label": "annoyed", "description": ""},
{"label": "furious", "description": ""}]}, # 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)
print(result.answers[2]["score"]) # 1.0 (probability-weighted position on the rubric)
```

Only input tokens are billed. A wallet call pays the 402's quote: an
Expand All @@ -1110,6 +1112,18 @@ 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.

Pass `model="gemini-decision-1"` to use Google's Gemini Decision 1 (same price,
up to 1,000 questions). It needs a `description` string on every choice and every
score level; an empty string is fine. The SDK raises `ValueError` before sending
when one is missing. `gpt-6-luna` accepts descriptions too, so the example above
works on both models.

A `score` answer is the probability-weighted position on the rubric (0 = the
first level), so it can be fractional: Gemini answered the example above with
1.43 (2% calm, 53% annoyed, 45% furious) where luna, all on "annoyed", gave 1.
For a single level, take the entry in `probabilities` with the highest
probability, or round.

## Market Data (`PriceClient`)

Crypto, FX and commodity prices, OHLC history and symbol lists — all **free**,
Expand Down
2 changes: 1 addition & 1 deletion VERSION
Original file line number Diff line number Diff line change
@@ -1 +1 @@
1.23.0
1.23.1
2 changes: 1 addition & 1 deletion blockrun_llm/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@
create_wallet as generate_wallet, # User-friendly alias
)

__version__ = "1.23.0"
__version__ = "1.23.1"
__all__ = [
"DECISIONS_DEFAULT_MODEL",
"DEFAULT_API_KEY_URL",
Expand Down
8 changes: 6 additions & 2 deletions blockrun_llm/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -2470,7 +2470,9 @@ def decisions(
{"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"}]},
"choices": [{"value": "billing", "description": "payments and refunds"},
{"value": "shipping", "description": "delivery"},
{"value": "none", "description": "fits no team"}]},
],
)
print(result.answers[0]["probability"], result.answers[1]["choice"])
Expand Down Expand Up @@ -4423,7 +4425,9 @@ async def decisions(
{"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"}]},
"choices": [{"value": "billing", "description": "payments and refunds"},
{"value": "shipping", "description": "delivery"},
{"value": "none", "description": "fits no team"}]},
],
)
print(result.answers[0]["probability"], result.answers[1]["choice"])
Expand Down
17 changes: 17 additions & 0 deletions blockrun_llm/decisions.py
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,15 @@

_QUESTION_TYPES = ("predicate", "choice", "score")

#: Google's Decisions model. It needs a ``description`` string (empty is fine)
#: on every choice and every score level; the gateway refuses it with a 400
#: before payment otherwise (probed on sol.blockrun.ai 2026-11-18).
GEMINI_DECISIONS_MODEL = "gemini-decision-1"


def _is_gemini(model: str | None) -> bool:
return bool(model) and model.strip().removeprefix("google/") == GEMINI_DECISIONS_MODEL


def build_decisions_body(
input: str | Sequence[Mapping[str, Any]],
Expand Down Expand Up @@ -73,6 +82,14 @@ def build_decisions_body(
raise ValueError(
f"decisions: questions[{i}] (score) needs a non-empty levels list, lowest first"
)
if _is_gemini(model):
key = "choices" if q["type"] == "choice" else "levels" if q["type"] == "score" else None
for j, item in enumerate(q.get(key) or [] if key else []):
if not isinstance(item, Mapping) or not isinstance(item.get("description"), str):
raise ValueError(
f"decisions: questions[{i}].{key}[{j}].description must be a string for "
f'{GEMINI_DECISIONS_MODEL} (it may be empty: "")'
)
body: dict[str, Any] = {
"model": model or DECISIONS_DEFAULT_MODEL,
"input": input if isinstance(input, str) else [dict(m) for m in input],
Expand Down
8 changes: 6 additions & 2 deletions blockrun_llm/solana_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -3828,7 +3828,9 @@ def decisions(
{"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"}]},
"choices": [{"value": "billing", "description": "payments and refunds"},
{"value": "shipping", "description": "delivery"},
{"value": "none", "description": "fits no team"}]},
],
)
print(result.answers[0]["probability"], result.answers[1]["choice"])
Expand Down Expand Up @@ -5392,7 +5394,9 @@ async def decisions(
{"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"}]},
"choices": [{"value": "billing", "description": "payments and refunds"},
{"value": "shipping", "description": "delivery"},
{"value": "none", "description": "fits no team"}]},
],
)
print(result.answers[0]["probability"], result.answers[1]["choice"])
Expand Down
6 changes: 5 additions & 1 deletion blockrun_llm/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -965,7 +965,11 @@ class DecisionsResponse(BaseModel):
``{"type": "predicate", "name", "probability"}``,
``{"type": "choice", "name", "choice", "probabilities": [{"value", "probability"}], "confidence"}``
or ``{"type": "score", "name", "score", "probabilities": [{"value", "label", "probability"}],
"confidence"}``. Only input tokens are billed (``usage.output_tokens`` is 0).
"confidence"}``. A ``score`` is the probability-weighted position on the rubric
(0 = the first level) and can be fractional (Gemini Decision 1 answers 1.43
where a confident model answers 1); take the most probable entry in
``probabilities`` for a single level. Only input tokens are billed
(``usage.output_tokens`` is 0).
"""

model_config = ConfigDict(extra="allow")
Expand Down
2 changes: 1 addition & 1 deletion pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "hatchling.build"

[project]
name = "blockrun-llm"
version = "1.23.0"
version = "1.23.1"
description = "BlockRun SDK - Pay-per-request AI (LLM, Image, Video, Music, Voice) via x402 on Base and Solana"
readme = "README.md"
license = "MIT"
Expand Down
56 changes: 56 additions & 0 deletions tests/unit/test_decisions_and_search.py
Original file line number Diff line number Diff line change
Expand Up @@ -323,3 +323,59 @@ def test_smart_chat_completion_with_search_calls_an_xai_model(self):

assert result.model == "xai/grok-4.5"
assert json.loads(seen[0].content)["model"] == "xai/grok-4.5"


# gemini-decision-1 needs a `description` string (empty is fine) on every
# choice and every score level: sol and Base refuse it with a 400 before
# payment ("questions[0].choices[0].description must be a string (it may be
# empty)", probed 2026-11-18). luna takes descriptions too, so they are never
# wrong to send; the SDK only REQUIRES them for Gemini.
class TestGeminiDecisionDescriptions:
CHOICE = {
"type": "choice",
"name": "team",
"instructions": "Which team?",
"choices": [{"value": "billing", "description": "payments"}, {"value": "none"}],
}
SCORE = {
"type": "score",
"name": "anger",
"instructions": "How upset?",
"levels": [{"label": "calm", "description": ""}, {"label": "furious"}],
}

@pytest.mark.parametrize("model", ["gemini-decision-1", "google/gemini-decision-1"])
def test_gemini_choice_without_description_is_refused_before_sending(self, model):
with pytest.raises(ValueError, match=r"questions\[0\]\.choices\[1\]\.description"):
build_decisions_body("x", [self.CHOICE], model=model)

@pytest.mark.parametrize("model", ["gemini-decision-1", "google/gemini-decision-1"])
def test_gemini_level_without_description_is_refused_before_sending(self, model):
with pytest.raises(ValueError, match=r"questions\[0\]\.levels\[1\]\.description"):
build_decisions_body("x", [self.SCORE], model=model)

def test_gemini_with_every_description_passes_and_empty_is_fine(self):
q = [
{
**self.CHOICE,
"choices": [
{"value": "billing", "description": "payments"},
{"value": "none", "description": ""},
],
},
{
**self.SCORE,
"levels": [
{"label": "calm", "description": ""},
{"label": "furious", "description": "x"},
],
},
]
body = build_decisions_body("x", q, model="gemini-decision-1")
assert body["model"] == "gemini-decision-1"
assert body["questions"][0]["choices"][1]["description"] == ""

@pytest.mark.parametrize("model", [None, "gpt-6-luna", "openai/gpt-6-luna"])
def test_luna_does_not_require_descriptions(self, model):
body = build_decisions_body("x", [self.CHOICE, self.SCORE], model=model)
assert len(body["questions"]) == 2
Loading