diff --git a/dokimi/changelog.d/20261117_140000_atoms-partial-message-fallback.md b/dokimi/changelog.d/20261117_140000_atoms-partial-message-fallback.md new file mode 100644 index 000000000..c3d8920c8 --- /dev/null +++ b/dokimi/changelog.d/20261117_140000_atoms-partial-message-fallback.md @@ -0,0 +1,3 @@ +### Fixed + +- **A partial atoms file with no usable message now says why the run stopped** — for a `no_price` or `permanent_error` stop, the refusal of `load_atoms_record` printed the block's `message` as it was, so a block with no message gave an empty slot (`is a partial atoms file: , so it ...`) and a blank, zero-width or non-text message gave junk. It now names the stop (`a call with no known price stopped the run`, `a permanent provider error stopped the run`) when the message is not text with a printable, non-space character; a real message is printed as before. (#833) diff --git a/dokimi/dokimi/novelty/atoms.py b/dokimi/dokimi/novelty/atoms.py index 8cf540706..a0a5a2770 100644 --- a/dokimi/dokimi/novelty/atoms.py +++ b/dokimi/dokimi/novelty/atoms.py @@ -30,6 +30,7 @@ from dokimi.atomic_write import write_text_atomic from dokimi.utils import InputError, read_json_input +from .atoms_refusal import partial_atoms_refusal from .batching import or_stop, retry_wording from .client import LLMClient, OutputTruncated, SpendCapReached, accepting from .spans import Span @@ -786,12 +787,7 @@ def load_atoms_record(path) -> tuple[list[Atom], list[Span], dict]: if isinstance(data, dict) and ("partial" in data or data.get("status") == "partial"): if not isinstance(partial := data.get("partial"), dict) or not partial: # no run writes this raise InputError(f"{path} is marked partial with no `partial` block: truncated or hand-edited") - if (reason := partial.get("reason")) in ("no_price", "permanent_error"): # a higher cap will not help - raise InputError(f"{path} is a partial atoms file: {partial.get('message', '')}, so it is not a finished atom set. " - + ("Drop --max-usd to run unmetered" if reason == "no_price" else "Fix the error and rerun")) - raise InputError(f"{path} is a partial atoms file: --max-usd stopped the run before it " - "finished, so it is not a finished atom set. Rerun with a higher " - "--max-usd, or without the cap") + raise InputError(partial_atoms_refusal(path, partial)) try: atoms, spans = _atoms_from_record(data) _check_bundle_shape(data.get("bundle")) diff --git a/dokimi/dokimi/novelty/atoms_refusal.py b/dokimi/dokimi/novelty/atoms_refusal.py new file mode 100644 index 000000000..c193b071a --- /dev/null +++ b/dokimi/dokimi/novelty/atoms_refusal.py @@ -0,0 +1,28 @@ +# Copyright (C) 2026 Intel Corporation +# SPDX-License-Identifier: Apache-2.0 + +"""The sentence that refuses a partial atoms file (``load_atoms_record``), by the reason the run stopped.""" + +from __future__ import annotations + +_STOPS = { + "no_price": ("a call with no known price stopped the run", "Drop --max-usd to run unmetered"), + "permanent_error": ("a permanent provider error stopped the run", "Fix the error and rerun"), +} + + +def partial_atoms_refusal(path, partial: dict) -> str: + """Why ``path``, an atoms file whose ``partial`` block is ``partial``, is not a finished atom set. + + A ``no_price`` or ``permanent_error`` block names its stop in ``message``; one whose message is not + text with a printable, non-space character gets the reason's own text. + Any other reason is a ``--max-usd`` stop. + """ + reason = partial.get("reason") + if not isinstance(reason, str) or (stop := _STOPS.get(reason)) is None: # a higher cap helps + return (f"{path} is a partial atoms file: --max-usd stopped the run before it finished, so it is " + "not a finished atom set. Rerun with a higher --max-usd, or without the cap") + message = partial.get("message") + if not isinstance(message, str) or not any(ch.isprintable() and not ch.isspace() for ch in message): + message = stop[0] + return f"{path} is a partial atoms file: {message}, so it is not a finished atom set. {stop[1]}" diff --git a/dokimi/tests/test_atoms_partial_status.py b/dokimi/tests/test_atoms_partial_status.py index 33d6a866a..e9bac610f 100644 --- a/dokimi/tests/test_atoms_partial_status.py +++ b/dokimi/tests/test_atoms_partial_status.py @@ -50,6 +50,49 @@ def test_a_partial_file_that_stopped_on_a_missing_price_says_so(tmp_path): load_atoms_record(path) +_NO_PRICE = "a call with no known price stopped the run" +_PERMANENT = "a permanent provider error stopped the run" +_ADVICE = {"no_price": "Drop --max-usd to run unmetered", "permanent_error": "Fix the error and rerun"} +_FALLBACK = {"no_price": _NO_PRICE, "permanent_error": _PERMANENT} +_MISSING = object() + + +@pytest.mark.parametrize("reason", ["no_price", "permanent_error"]) +@pytest.mark.parametrize("message", [_MISSING, "", " ", "\n\t", 5, None, ["x"], "\u200b"], + ids=["absent", "empty", "spaces", "whitespace", "int", "null", "list", "zero-width"]) +def test_a_partial_file_without_a_usable_message_names_its_stop(tmp_path, reason, message): + # docs/skill-novelty.md:1216-1217 (`probe` and the other atom readers refuse a partial atoms file) + path = tmp_path / "atoms.json" + block = {"reason": reason} if message is _MISSING else {"reason": reason, "message": message} + path.write_text(json.dumps({"status": "partial", "partial": block}), encoding="utf-8") + with pytest.raises(InputError) as exc: + load_atoms_record(path) + assert str(exc.value) == (f"{path} is a partial atoms file: {_FALLBACK[reason]}, " + f"so it is not a finished atom set. {_ADVICE[reason]}") + + +@pytest.mark.parametrize("reason", ["no_price", "permanent_error"]) +def test_a_partial_file_with_a_real_message_prints_it_as_is(tmp_path, reason): + # docs/skill-novelty.md:1216-1217 + path = tmp_path / "atoms.json" + path.write_text(json.dumps({"status": "partial", "partial": {"reason": reason, "message": " bad key "}}), + encoding="utf-8") + with pytest.raises(InputError) as exc: + load_atoms_record(path) + assert str(exc.value) == (f"{path} is a partial atoms file: bad key , so it is not a finished atom set. " + f"{_ADVICE[reason]}") + + +@pytest.mark.parametrize("reason", [["no_price"], {"a": 1}, 3, None]) +def test_a_partial_file_with_a_reason_that_is_not_text_is_a_cap_stop(tmp_path, reason): + # docs/skill-novelty.md:1216-1217 + path = tmp_path / "atoms.json" + path.write_text(json.dumps({"status": "partial", "partial": {"reason": reason, "message": "m"}}), + encoding="utf-8") + with pytest.raises(InputError, match="Rerun with a higher --max-usd"): + load_atoms_record(path) + + def test_a_finished_status_is_not_refused(tmp_path): path = tmp_path / "atoms.json" path.write_text(json.dumps({"atoms": [], "spans": [], "status": "complete"}), encoding="utf-8")