Add a pronoun rule option: most recent object or last clause's subject

translate_to_scene and extend_scene take pronouns="recent" (default, the
user's choice) or "subject": the subject of the most recent clause, else
the most recent object. In "the cat sat on the table. the apple lay beside
it", recent gives the table and subject the cat. The rule is kept in the
ledger, so extend_scene follows it unless given another; the reference
question records which rule chose it. The UI has an "'it' means" selector.

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

SPEC.md

@@ -113,11 +113,17 @@ on, `sentences` lists them). Within a sentence or across sentences:
   the one already mentioned" (default: the same cat), alternatives include "say
   'another cat' for a new one".
 - **"a/an/another <noun>"** always adds a new item.
-- **Pronouns** (it, he, she, they, him, her, them) refer to the most recent object,
-  leaving out the clause's own subject when the pronoun is its object ("the apple lay
-  beside it" can't mean the apple). Surfaced as "'it' = the table?", with the other
-  objects as alternatives, most recent first. A pronoun with nothing before it is an
-  error.
+- **Pronouns** (it, he, she, they, him, her, them) refer back by a rule, `pronouns`
+  on `translate_to_scene`/`extend_scene`, kept in the ledger:
+  - `"recent"` (default): the most recent object.
+  - `"subject"`: the subject of the most recent clause, else the most recent object.
+    Closer to how readers take "it": in "the cat sat on the table. the apple lay
+    beside it", `recent` gives the table, `subject` the cat.
+
+  Either way the clause's own subject is left out when the pronoun is its object ("the
+  apple lay beside it" can't mean the apple), and the choice is surfaced as "'it' = the
+  cat?" with the other objects as alternatives, most recent first. A pronoun with
+  nothing before it is an error.
 - Each reference question carries `binds: {token, to}`; relations record which token
   named each end (`tokens: {subject, object}`), so a reference can be rebound.
 - **`bind`** (a `refine_scene` change): `{"id": "q10", "bind": "n1"}` rebinds a
@@ -131,9 +137,9 @@ on, `sentences` lists them). Within a sentence or across sentences:
 | Tool | In → out |
 |---|---|
 | `check_words` | sentence, primitives → per-word status, missing words, completions |
-| `translate_to_scene` | sentence, primitives, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
+| `translate_to_scene` | sentence, primitives, seed, html, pronouns → ledger, PNG, GLB, mini HTML file, mini HTML text |
 | `refine_scene` | ledger, changes, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
-| `extend_scene` | ledger, sentence, primitives, seed, html → ledger, PNG, GLB, mini HTML file, mini HTML text |
+| `extend_scene` | ledger, sentence, primitives, seed, html, pronouns → ledger, PNG, GLB, mini HTML file, mini HTML text |
 | `simplify_item` | ledger, item id, html, rings, samples → report, rung PNGs, rung GLBs, mini HTML file, mini HTML text |
 | `papercraft_rings` | ledger, item id, rings, samples, height_cm → pieces report, PNG per A4 page (to look at), SVG per A4 page (mm, to print) |
 

app.py

@@ -116,7 +116,7 @@ def check_words(sentence: str, primitives_json: str = "{}") -> str:
 
 
 def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: str = "0",
-                       html: str = "url") -> tuple[str, str, str, str, str]:
+                       html: str = "url", pronouns: str = "recent") -> tuple[str, str, str, str, str]:
     """Translate an English sentence into a 3D scene.
 
     Produces the serial ledger (tokens in reading order, the items each word commits,
@@ -132,12 +132,16 @@ def translate_to_scene(sentence: str, primitives_json: str = "{}", seed: str = "
         html: "url" (default) returns the mini HTML as a file URL only; "inline" also returns
             its text (thousands of tokens: ask for it when building on the page); "skip" omits it.
             Iterate on the ledger and picture; the ledger can always re-create the page.
+        pronouns: Default referent for it/he/she/they: "recent" (default) = the most recent
+            object; "subject" = the subject of the most recent clause. Either way the choice is
+            an implied question with the other objects as alternatives. Kept in the ledger.
 
     Returns:
         (ledger JSON string, rendered PNG, GLB scene file, mini HTML file, mini HTML text or "").
     """
     try:
-        *rest, page = pipeline.translate(sentence, _json(primitives_json, "primitives_json", {}), _seed(seed))
+        *rest, page = pipeline.translate(sentence, _json(primitives_json, "primitives_json", {}), _seed(seed),
+                                         (pronouns or "recent").strip().lower())
         return (*rest, *_html_out(page, html))
     except Exception as e:
         _fail(e)
@@ -182,7 +186,7 @@ def refine_scene(ledger_json: str, changes_json: str = "[]", seed: str = "0",
 
 
 def extend_scene(ledger_json: str, sentence: str, primitives_json: str = "{}", seed: str = "0",
-                 html: str = "url") -> tuple[str, str, str, str, str]:
+                 html: str = "url", pronouns: str = "") -> tuple[str, str, str, str, str]:
     """Add the next sentence of a paragraph to an existing scene.
 
     Paragraphs are sentences plus bindings. "the cat" when a cat is already in the ledger,
@@ -197,13 +201,15 @@ def extend_scene(ledger_json: str, sentence: str, primitives_json: str = "{}", s
         primitives_json: JSON object mapping missing words to shapes, as in translate_to_scene.
         seed: Picks one of the configurations that satisfy the whole ledger.
         html: "url" (default), "inline" or "skip", as in translate_to_scene.
+        pronouns: "recent" or "subject", as in translate_to_scene; blank = the ledger's rule.
 
     Returns:
         (ledger JSON string, rendered PNG, GLB scene file, mini HTML file, mini HTML text or "").
     """
     try:
         ledger = _json(ledger_json, "ledger_json")
-        *rest, page = pipeline.extend(ledger, sentence, _json(primitives_json, "primitives_json", {}), _seed(seed))
+        *rest, page = pipeline.extend(ledger, sentence, _json(primitives_json, "primitives_json", {}), _seed(seed),
+                                      (pronouns or "").strip().lower() or None)
         return (*rest, *_html_out(page, html))
     except Exception as e:
         _fail(e)
@@ -390,6 +396,8 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
     with gr.Row():
         sentence = gr.Textbox(label="Sentence", placeholder="the cat sat and the lamp glowed", scale=4)
         seed = gr.Textbox(label="Configuration seed", value="0", scale=1)
+        pronoun_rule = gr.Radio(label="'it' means", choices=["recent", "subject"], value="recent", scale=1,
+                                info="recent: last object · subject: last clause's subject")
     status = gr.Markdown()
     suggest = gr.Radio(label="Suggestions", choices=[], interactive=True)
     with gr.Row():
@@ -439,13 +447,13 @@ with gr.Blocks(title="VisualLearningIdea") as demo:
         .then(_suggestions, words, [status, suggest, missing], api_visibility="private")
     suggest.select(_complete, [sentence, suggest], sentence, api_visibility="private")
     use_prim.click(_use_primitive, [primitives, missing, shape], primitives, api_visibility="private")
-    go.click(translate_to_scene, [sentence, primitives, seed, html_mode],
+    go.click(translate_to_scene, [sentence, primitives, seed, html_mode, pronoun_rule],
              [ledger, picture, model, scene_file, scene_html], api_name="translate_to_scene") \
         .then(_html_preview, scene_file, scene_preview, api_visibility="private")
     refine.click(refine_scene, [ledger, changes, seed, html_mode],
                  [ledger, picture, model, scene_file, scene_html], api_name="refine_scene") \
         .then(_html_preview, scene_file, scene_preview, api_visibility="private")
-    extend.click(extend_scene, [ledger, next_sentence, primitives, seed, html_mode],
+    extend.click(extend_scene, [ledger, next_sentence, primitives, seed, html_mode, pronoun_rule],
                  [ledger, picture, model, scene_file, scene_html], api_name="extend_scene") \
         .then(_html_preview, scene_file, scene_preview, api_visibility="private")
     simp.click(simplify_item, [ledger, item_id, html_mode, ring_count, ring_samples],

vli/grammar.py

@@ -17,6 +17,9 @@ from .lexicon import ASSET_TIERS, LEXICON, PRIMITIVE_SHAPES, TIERS
 DETERMINERS = {"the", "a", "an", "another"}
 NEW_DETERMINERS = {"a", "an", "another"}  # always introduce a new item
 PRONOUNS = {"it", "he", "she", "they", "him", "her", "them"}
+# What a pronoun means by default: the most recent object, or the subject of the most
+# recent clause (how readers usually take "it": the cat sat on the table; it ... = the cat).
+PRONOUN_RULES = ("recent", "subject")
 CONJUNCTIONS = {"and", "then"}
 COPULAS = {"is", "was", "are", "were"}
 
@@ -158,10 +161,13 @@ def _reference_question(qid, token, word, target, others, determiner=None):
             "binds": {"token": token["index"], "to": target["id"]}}
 
 
-def build_ledger(sentence, primitives=None, prior=None):
+def build_ledger(sentence, primitives=None, prior=None, pronouns="recent"):
     """The ledger for one sentence. With `prior` (an existing ledger), token indices
     continue after it and words can refer back to its objects; the result holds only
-    the new tokens, items and questions (extend_ledger merges them)."""
+    the new tokens, items and questions (extend_ledger merges them). `pronouns` picks
+    the default referent (PRONOUN_RULES); the other candidates stay as alternatives."""
+    if pronouns not in PRONOUN_RULES:
+        raise ValueError(f"pronouns must be one of {list(PRONOUN_RULES)}, got {pronouns!r}")
     primitives = parse_primitives(primitives)
     tokens = tokenize(sentence, primitives)
     unknown = [t["text"] for t in tokens if t["kind"] == "unknown"]
@@ -176,6 +182,7 @@ def build_ledger(sentence, primitives=None, prior=None):
     items, unresolved = [], []
     by_id = {i["id"]: i for i in prior["items"]} if prior else {}
     objects = [i for i in prior["items"] if i["kind"] == "object"] if prior else []  # in reading order
+    subjects = [r["subject"] for r in prior["items"] if r["kind"] == "relation"] if prior else []  # clause order
 
     def add_item(item, token):
         items.append(item)
@@ -211,7 +218,12 @@ def build_ledger(sentence, primitives=None, prior=None):
                     if not pool:
                         raise ValueError(f"'{t['text']}' refers to nothing yet: name the object first")
                     item = pool[-1]  # the most recent object it can mean
-                    q = _reference_question(f"q{t['index']}", t, t["text"], item, pool[-2::-1])
+                    if pronouns == "subject":
+                        ids = {o["id"]: o for o in pool}
+                        item = next((ids[s] for s in reversed(subjects) if s in ids), item)
+                    q = _reference_question(f"q{t['index']}", t, t["text"], item,
+                                            [o for o in reversed(pool) if o is not item])
+                    q["rule"] = pronouns
                     t["opens"].append(q["id"])
                     unresolved.append(q)
                 else:
@@ -272,6 +284,7 @@ def build_ledger(sentence, primitives=None, prior=None):
             raise ValueError(f"'{relation}' needs an object noun")
         if obj is subject:
             raise ValueError(f"'{verb_tok['text']}' would relate the {subject['word']} to itself")
+        subjects.append(subject["id"])
         add_item({"id": f"r{verb_tok['index']}", "kind": "relation", "relation": relation,
                   "subject": subject["id"], "object": obj["id"], "token": verb_tok["index"],
                   "tokens": {"subject": subject_tok, "object": obj_tok}, "frozen": False}, verb_tok)
@@ -287,19 +300,21 @@ def build_ledger(sentence, primitives=None, prior=None):
         unresolved.append({"id": "q_light", "token": None, "about": "light", "question": "what light?",
                            "default_chosen": "daylight", "implied": True,
                            "alternatives": ["rephrase: '<noun> shone' or '<noun> glowed'"]})
-    return {"version": 1, "sentence": sentence, "primitives": primitives,
+    return {"version": 1, "sentence": sentence, "primitives": primitives, "pronouns": pronouns,
             "tokens": tokens, "items": items, "unresolved": unresolved}
 
 
-def extend_ledger(ledger, sentence, primitives=None):
-    """Add a sentence to a ledger: the next sentence of a paragraph."""
+def extend_ledger(ledger, sentence, primitives=None, pronouns=None):
+    """Add a sentence to a ledger: the next sentence of a paragraph. `pronouns`
+    defaults to the rule the ledger was built with."""
     prims = {**ledger.get("primitives", {}), **parse_primitives(primitives)}
-    new = build_ledger(sentence, prims, prior=ledger)
+    pronouns = pronouns or ledger.get("pronouns", "recent")
+    new = build_ledger(sentence, prims, prior=ledger, pronouns=pronouns)
     lit = any(i.get("emits_light") for i in ledger["items"] + new["items"])
     unresolved = [q for q in ledger["unresolved"] + new["unresolved"] if not (lit and q["id"] == "q_light")]
     return {**ledger, "sentence": ledger["sentence"].rstrip(" .") + ". " + sentence.strip(),
             "sentences": ledger.get("sentences", [ledger["sentence"]]) + [sentence.strip()],
-            "primitives": prims, "tokens": ledger["tokens"] + new["tokens"],
+            "primitives": prims, "pronouns": pronouns, "tokens": ledger["tokens"] + new["tokens"],
             "items": ledger["items"] + new["items"], "unresolved": unresolved}
 
 

vli/pipeline.py

@@ -66,12 +66,12 @@ def outputs(ledger, seed):
     return json.dumps(ledger, indent=1), png, glb, html.scene_page(ledger, meshes, config)
 
 
-def translate(sentence, primitives=None, seed=0):
-    return outputs(build_ledger(sentence, primitives), seed)
+def translate(sentence, primitives=None, seed=0, pronouns="recent"):
+    return outputs(build_ledger(sentence, primitives, pronouns=pronouns), seed)
 
 
-def extend(ledger, sentence, primitives=None, seed=0):
-    return outputs(extend_ledger(ledger, sentence, primitives), seed)
+def extend(ledger, sentence, primitives=None, seed=0, pronouns=None):
+    return outputs(extend_ledger(ledger, sentence, primitives, pronouns), seed)
 
 
 def _bind(ledger, src, dst):