Harden tool inputs against blank and junk values

Seeds are strings cast inside the tools (some MCP clients can't send
numbers); JSON arguments fall back to defaults when blank and name the
field when invalid; ledger tools say to translate first when empty.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

app.py

@@ -23,6 +23,26 @@ def _fail(e):
     raise gr.Error(str(e))
 
 
+def _json(text, name, default=None):
+    """Parse a JSON argument; blank -> default, junk -> a readable error."""
+    if not (text or "").strip():
+        if default is None:
+            raise ValueError(f"{name} is empty; translate a sentence first")
+        return default
+    try:
+        return json.loads(text)
+    except json.JSONDecodeError:
+        raise ValueError(f"{name} is not valid JSON")
+
+
+def _seed(value):
+    """Seeds arrive as strings (some MCP clients can't send numbers)."""
+    try:
+        return int(float(str(value).strip() or 0))
+    except ValueError:
+        raise ValueError(f"seed must be a whole number, got {value!r}")
+
+
 @spaces.GPU(duration=60)
 def generate_mesh(prompt):
     """GPU entry point for the generation tier (last in the fallback chain).
@@ -54,12 +74,12 @@ def check_words(sentence: str, primitives_json: str = "{}") -> str:
         "primitive_shapes", "completions"}.
     """
     try:
-        return json.dumps(_check_words(sentence, json.loads(primitives_json or "{}")))
+        return json.dumps(_check_words(sentence, _json(primitives_json, "primitives_json", {})))
     except Exception as e:
         _fail(e)
 
 
-def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: int = 0) -> tuple[str, str, str]:
+def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: str = "0") -> tuple[str, str, str]:
     """Translate an English sentence into a 3D scene.
 
     Produces the serial ledger (tokens in reading order, the items each word commits,
@@ -76,12 +96,12 @@ def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: int = 0
         (ledger JSON string, rendered PNG, GLB scene file).
     """
     try:
-        return pipeline.translate(sentence, json.loads(primitives_json or "{}"), int(seed))
+        return pipeline.translate(sentence, _json(primitives_json, "primitives_json", {}), _seed(seed))
     except Exception as e:
         _fail(e)
 
 
-def refine_scene(ledger_json: str, changes_json: str = "[]", seed: int = 0) -> tuple[str, str, str]:
+def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0") -> tuple[str, str, str]:
     """Refine a ledger: freeze some decisions and change the others, then re-render.
 
     Changes are a JSON list of:
@@ -102,9 +122,9 @@ def refine_scene(ledger_json: str, changes_json: str = "[]", seed: int = 0) -> t
         (ledger JSON string, rendered PNG, GLB scene file).
     """
     try:
-        ledger = json.loads(ledger_json)
-        pipeline.apply_changes(ledger, json.loads(changes_json or "[]"), int(seed))
-        return pipeline.outputs(ledger, int(seed))
+        ledger = _json(ledger_json, "ledger_json")
+        pipeline.apply_changes(ledger, _json(changes_json, "changes_json", []), _seed(seed))
+        return pipeline.outputs(ledger, _seed(seed))
     except Exception as e:
         _fail(e)
 
@@ -124,7 +144,7 @@ def simplify_item(ledger_json: str, item_id: str, check_recognition: bool = Fals
         (report JSON string, gallery of rung pictures, GLB file per rung).
     """
     try:
-        ledger = json.loads(ledger_json)
+        ledger = _json(ledger_json, "ledger_json")
         item = next((i for i in ledger["items"] if i["id"] == item_id), None)
         if item is None or item["kind"] != "object":
             raise ValueError(f"{item_id!r} is not an object item in this ledger")
@@ -152,7 +172,7 @@ def simplify_item(ledger_json: str, item_id: str, check_recognition: bool = Fals
         _fail(e)
 
 
-def describe_scene(ledger_json: str, seed: int = 0) -> str:
+def describe_scene(ledger_json: str, seed: str = "0") -> str:
     """Back-translate: render the ledger's scene and have a vision model describe it in English.
 
     Comparing the description with the original sentence checks the translation.
@@ -165,9 +185,9 @@ def describe_scene(ledger_json: str, seed: int = 0) -> str:
         JSON string: {"original", "back_translation", "nouns_recovered": {word: bool}}.
     """
     try:
-        ledger = json.loads(ledger_json)
+        ledger = _json(ledger_json, "ledger_json")
         meshes = pipeline.settle_all(ledger)
-        config = scene.configure(ledger, meshes, int(seed))
+        config = scene.configure(ledger, meshes, _seed(seed))
         png = scene.render_scene(ledger, meshes, config, os.path.join(tempfile.mkdtemp(), "scene.png"))
         text = vlm.describe(png)
         nouns = [i["word"] for i in ledger["items"] if i["kind"] == "object"]
@@ -206,7 +226,7 @@ def _complete(sentence, choice):
 
 
 def _use_primitive(primitives_json, word, shape):
-    prims = json.loads(primitives_json or "{}")
+    prims = _json(primitives_json, "primitives_json", {})
     if word:
         prims[word] = shape
     return json.dumps(prims)
@@ -219,7 +239,7 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
                 "verbs and prepositions are relations between meshes.")
     with gr.Row():
         sentence = gr.Textbox(label="Sentence", placeholder="the cat sat and the sun shone", scale=4)
-        seed = gr.Number(label="Configuration seed", value=0, precision=0, scale=1)
+        seed = gr.Textbox(label="Configuration seed", value="0", scale=1)
     status = gr.Markdown()
     suggest = gr.Radio(label="Suggestions", choices=[], interactive=True)
     with gr.Row():