diff --git a/CHANGELOG.md b/CHANGELOG.md index 718d44d..672658a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index 8d926f0..e4b8b4b 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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**, diff --git a/VERSION b/VERSION index a6c2798..49e0a31 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -1.23.0 +1.23.1 diff --git a/blockrun_llm/__init__.py b/blockrun_llm/__init__.py index 30b49ae..c6fdc2a 100644 --- a/blockrun_llm/__init__.py +++ b/blockrun_llm/__init__.py @@ -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", diff --git a/blockrun_llm/client.py b/blockrun_llm/client.py index 5c0332f..9d3d717 100644 --- a/blockrun_llm/client.py +++ b/blockrun_llm/client.py @@ -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"]) @@ -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"]) diff --git a/blockrun_llm/decisions.py b/blockrun_llm/decisions.py index c9b757a..58108ba 100644 --- a/blockrun_llm/decisions.py +++ b/blockrun_llm/decisions.py @@ -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]], @@ -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], diff --git a/blockrun_llm/solana_client.py b/blockrun_llm/solana_client.py index ab6aa91..79309ed 100644 --- a/blockrun_llm/solana_client.py +++ b/blockrun_llm/solana_client.py @@ -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"]) @@ -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"]) diff --git a/blockrun_llm/types.py b/blockrun_llm/types.py index 9a18c95..440d33a 100644 --- a/blockrun_llm/types.py +++ b/blockrun_llm/types.py @@ -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") diff --git a/pyproject.toml b/pyproject.toml index 042978a..137e127 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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" diff --git a/tests/unit/test_decisions_and_search.py b/tests/unit/test_decisions_and_search.py index f8e1119..012019d 100644 --- a/tests/unit/test_decisions_and_search.py +++ b/tests/unit/test_decisions_and_search.py @@ -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