SpellSpeak Audience rc1

.gitattributes

@@ -0,0 +1,35 @@
+*.7z filter=lfs diff=lfs merge=lfs -text
+*.arrow filter=lfs diff=lfs merge=lfs -text
+*.bin filter=lfs diff=lfs merge=lfs -text
+*.bz2 filter=lfs diff=lfs merge=lfs -text
+*.ckpt filter=lfs diff=lfs merge=lfs -text
+*.ftz filter=lfs diff=lfs merge=lfs -text
+*.gz filter=lfs diff=lfs merge=lfs -text
+*.h5 filter=lfs diff=lfs merge=lfs -text
+*.joblib filter=lfs diff=lfs merge=lfs -text
+*.lfs.* filter=lfs diff=lfs merge=lfs -text
+*.mlmodel filter=lfs diff=lfs merge=lfs -text
+*.model filter=lfs diff=lfs merge=lfs -text
+*.msgpack filter=lfs diff=lfs merge=lfs -text
+*.npy filter=lfs diff=lfs merge=lfs -text
+*.npz filter=lfs diff=lfs merge=lfs -text
+*.onnx filter=lfs diff=lfs merge=lfs -text
+*.ot filter=lfs diff=lfs merge=lfs -text
+*.parquet filter=lfs diff=lfs merge=lfs -text
+*.pb filter=lfs diff=lfs merge=lfs -text
+*.pickle filter=lfs diff=lfs merge=lfs -text
+*.pkl filter=lfs diff=lfs merge=lfs -text
+*.pt filter=lfs diff=lfs merge=lfs -text
+*.pth filter=lfs diff=lfs merge=lfs -text
+*.rar filter=lfs diff=lfs merge=lfs -text
+*.safetensors filter=lfs diff=lfs merge=lfs -text
+saved_model/**/* filter=lfs diff=lfs merge=lfs -text
+*.tar.* filter=lfs diff=lfs merge=lfs -text
+*.tar filter=lfs diff=lfs merge=lfs -text
+*.tflite filter=lfs diff=lfs merge=lfs -text
+*.tgz filter=lfs diff=lfs merge=lfs -text
+*.wasm filter=lfs diff=lfs merge=lfs -text
+*.xz filter=lfs diff=lfs merge=lfs -text
+*.zip filter=lfs diff=lfs merge=lfs -text
+*.zst filter=lfs diff=lfs merge=lfs -text
+*tfevents* filter=lfs diff=lfs merge=lfs -text

MANIFEST.json

@@ -0,0 +1,86 @@
+{
+ "name": "SpellSpeak Audience",
+ "release": "rc1",
+ "package": "spellspeak-audience-rc1.2",
+ "created": "2026-10-08T21:35:48Z",
+ "model_run": "addr-r2b-ettin-32m-tt-s1",
+ "inputs": "addressee-tt-0.5",
+ "files": {
+  "README.md": {
+   "bytes": 9609,
+   "sha256": "e8f614b475a64b57b6bac573093386a98e1f2156c5ecf8f3bdd08f9956fdd35b"
+  },
+  "config.json": {
+   "bytes": 342,
+   "sha256": "4dcd9366bce0f930750d01b57f79503eb8b9d87b254a81c190be0085b7380832"
+  },
+  "encoder.onnx": {
+   "bytes": 127960962,
+   "sha256": "7960e1bc311030450d9e6648829c6f5a82e392c502b7853987e89dc2feb62de5"
+  },
+  "example.py": {
+   "bytes": 2799,
+   "sha256": "e4b5687cbfad34eb3802608848d34dc7a6505e43093827a4f53fc3193c92f39b"
+  },
+  "head.onnx": {
+   "bytes": 3684676,
+   "sha256": "cb21b22f047d798148da89922b352dd3247840afb3828de6e0aa1e964e798f83"
+  },
+  "requirements.txt": {
+   "bytes": 270,
+   "sha256": "7ca7dcd5aa19a996d459ef0ab9f8e43f61d814931525369e57664044e66d72db"
+  },
+  "runtime/contracts/__init__.py": {
+   "bytes": 0,
+   "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  },
+  "runtime/contracts/schemas/__init__.py": {
+   "bytes": 0,
+   "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  },
+  "runtime/contracts/schemas/addressee.py": {
+   "bytes": 6998,
+   "sha256": "fb8fda50516f446bcc368e362dcf799b70f09a8ca1a18c1ebb5c912999695b8c"
+  },
+  "runtime/contracts/schemas/person_card.py": {
+   "bytes": 4049,
+   "sha256": "7d40834f7a3dd088fce5a5489f421ed6b6d4bc8f51c50cd89363b81aad132b28"
+  },
+  "runtime/harness/__init__.py": {
+   "bytes": 0,
+   "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+  },
+  "runtime/harness/addressee/__init__.py": {
+   "bytes": 613,
+   "sha256": "34bb4062a62803b2aa67fbc1b24e54efd0e198a2d978e419a9dcec99725846b1"
+  },
+  "runtime/harness/addressee/bands.py": {
+   "bytes": 3176,
+   "sha256": "ffbc520ee544ebc2fea6a25fb99b2d6edd3232a339a6d49b85a96a16de5db5d8"
+  },
+  "runtime/harness/addressee/classifier.py": {
+   "bytes": 7462,
+   "sha256": "36f65ff68b6b5e39d0650cf9001d9f46c10fee79a34df3c06aba30c3ba814941"
+  },
+  "runtime/harness/addressee/evidence.py": {
+   "bytes": 8048,
+   "sha256": "881c8f75aca1df4fe16bbcf2a5ce24621865937c697e12fe3cb3c4204df3a47b"
+  },
+  "runtime/harness/addressee/features.py": {
+   "bytes": 4513,
+   "sha256": "306388bfc4c0de5d2ce43f03846aede49ad205b016e9a9ca3b8153935fa55b86"
+  },
+  "runtime/harness/addressee/render.py": {
+   "bytes": 4314,
+   "sha256": "7474955c00e10abc53edfde258b6621d1e9cf1a64ad8900f54f6ed9f83337f24"
+  },
+  "runtime/harness/addressee/rules.py": {
+   "bytes": 11985,
+   "sha256": "4bb6bbf3557c928ae958737293e9dace118261e7b2e29fcac95367cbde03bac4"
+  },
+  "tokenizer.json": {
+   "bytes": 3583325,
+   "sha256": "82d1ca5ef2019321c91a01b78653345e6fe8ef25a38b7d83f7857c380649c7cf"
+  }
+ }
+}

README.md

@@ -0,0 +1,130 @@
+---
+license: apache-2.0
+language:
+  - en
+library_name: onnx
+pipeline_tag: text-classification
+base_model: jhu-clsp/ettin-encoder-32m
+tags:
+  - onnx
+  - voice-agents
+  - conversational-ai
+  - multi-agent
+  - multi-party-conversation
+  - addressee-detection
+  - speech
+  - real-time
+  - pipecat
+  - npc
+  - dialogue
+---
+
+# SpellSpeak Audience · RC1
+
+When several AI characters listen to the same person, as in a game, an interactive story or any other multi-character voice experience, the application has to know who each line is for before any character answers or reacts. A name or a description often settles it, but much of what people say names nobody: "Hello.", "Who are you?", "You lied to me.". The language model voicing each character could guess, but only by reading every character's context for every line. That adds latency, the characters can disagree, and a wrong guess is heard at once.
+
+SpellSpeak Audience treats the question as classification by a small model. One pass reads the line, a card for each character present (what the speaker can see of them) and, when the application knows it, where each one stands. It returns, for each character, how likely it is that the line is for them. It also returns whether the evidence leaves it unclear and whether the line is for the whole group. It scores. The application decides. Its constraints are millisecond inference on a CPU, typed or transcribed speech, and an honest "unclear", so that a character can ask "Who, me?" instead of taking offence at a line that may not have been meant for them.
+
+[Try it in your browser](https://huggingface.co/spaces/spellspeak/audience-demo) · [Examples and source](https://github.com/spellspeak/models/tree/main/audience)
+
+| | |
+|---|---|
+| **Released** | 2026-10-08 · rc1 (package `spellspeak-audience-rc1.2`, model run `addr-r2b-ettin-32m-tt-s1`) |
+| **What it does** | Works out who a player's line is for: one person, several named on purpose, the whole group, or unclear |
+| **Size** | About 33M parameters · 135 MB ONNX (fp32) in two graphs: a 128 MB encoder and a 3.7 MB head |
+| **Speed** | p95 per line on 4 CPU threads (Apple M1 Max): 6.0 ms for 1 person, 6.4 for 2, 6.9 for 4, 7.1 for 8. On 1 thread: 11 to 13 ms. The first line of a scene also encodes everyone's card: 14 ms for 1 person to 62 ms for 8; cards are then cached |
+| **Runtime** | ONNX Runtime and tokenizers, on CPU. A Python reference runtime ships with it, including the function that turns positions into the spatial facts and an instant rules baseline |
+| **Files** | `encoder.onnx`, `head.onnx`, `tokenizer.json` and `config.json`, with the reference runtime (`runtime/`), `example.py` and `requirements.txt`. `MANIFEST.json` lists every file with its size and sha256 |
+| **Licence** | Apache-2.0 |
+
+## Quick start
+
+```bash
+pip install -U huggingface_hub
+hf download spellspeak/audience --revision rc1 --local-dir spellspeak-audience
+cd spellspeak-audience
+pip install -r requirements.txt
+python example.py
+```
+
+The example puts a barkeep, an elf mercenary and an old sailor in a room, with the player facing the elf. It asks who three lines are for, with and without the spatial facts:
+
+```
+'You in the red hat, another round.'   with facts  tomas (0.99)
+'You in the red hat, another round.'   text only   tomas (1.00)
+'Hello.'                               with facts  wren (0.99)
+'Hello.'                               text only   the whole group (0.99)
+'You lied to me.'                      with facts  wren (0.96)
+'You lied to me.'                      text only   unclear (0.99): a 'Who, me?' moment
+```
+
+In your own code, with the downloaded folder as the working directory:
+
+```python
+import sys
+sys.path.insert(0, "runtime")
+
+from contracts.schemas.addressee import AddresseeRequest
+from contracts.schemas.person_card import PersonCard
+from harness.addressee.classifier import load_classifier
+
+model = load_classifier(".")  # the folder with encoder.onnx, head.onnx, tokenizer.json and config.json
+people = [
+    PersonCard(id="tomas", label="Tomas", aliases=["the barkeep"], features=[{"key": "headwear", "value": "red hat"}]),
+    PersonCard(id="wren", label="Wren", features=[{"key": "role", "value": "mercenary"}]),
+]
+answer = model.answer(AddresseeRequest(text="You in the red hat, another round.", present=people))
+print(answer.top())                       # tomas
+print(answer.addressed)                   # one probability per person: tomas 0.996, wren 0.00003
+print(answer.unclear, answer.to_group)    # both near 0: the words pick out one person
+```
+
+## Input and output
+
+The runtime calls the person speaking the player. Everyone who might be addressed gets a card.
+
+- **Input:** the player's line, typed or from speech to text, with the line before it. Then everyone present (tested up to 8 people), one card each. A card holds a label ("Tomas", or "the barkeep" when the player would not know the name), aliases, and open `key: value` features for what the player can see. The game chooses its own keys: role, clothing, what someone holds or is doing, where they stand. A card is read up to 96 tokens, the line up to 64.
+- **Optional facts per person:** distance (near, mid-range, far), in view, in the player's group, following the player, has asked the player something, spoke with the player last. `bands.py` turns positions and facings into these. Up to four earlier lines of the conversation say who spoke to whom.
+- **Per person:** the probability that the line is for them.
+- **Per line:** `unclear` (the evidence fits several people, so nobody should take it personally yet) and `to_group` (the line is for everyone the player is talking with).
+
+The rules it learned:
+- A name, an alias or a description that fits one person picks them out, whatever the player is looking at.
+- A bare answer goes to whoever asked.
+- A simple, harmless line ("Hello.", "Who are you?", "Thanks.") is never unclear. A line that carries the conversation on stays with the person the player was talking with. An opener goes to the person the player is looking at, else the conversation partner, else the one person nearby, else the whole group.
+- A line with consequences that names nobody ("You lied to me.") is unclear unless the signals agree on one person.
+
+## Performance (held-out test set, committee-checked labels)
+
+| Measure | Result |
+|---|---|
+| Whole answer right (people, unclear and group), main test (3,294 lines) | 91.6% (95% interval 90.6 to 92.5). Rules baseline 86.4% |
+| Simple lines such as "Hello." and "Who are you?" (1,193 lines) | 91.7% right; called unclear 0.7% |
+| A wrong person scored 0.8 or more on a clear line | 1.3% |
+| Top person, text only / with spatial facts | 98.6% / 91.1% |
+| Lines that should be unclear, caught | 83.4% |
+| Clear lines called unclear | 1.0% |
+| Facts that contradict a unique description, words followed | 90.2% |
+| Spatial facts drawn the way a game makes them (2,044 lines) | 96.5% right; top person 98.2% |
+| Game settings never seen in training (919 lines) | 90.0% right |
+| Lines worded unlike their construction, labelled by the committee (488 lines) | 64.3% right |
+| Hand-written worked examples / hand-placed spatial scenes | 42 of 44 / 74 of 76 |
+| Calibration error: person, unclear, group | 0.011, 0.005, 0.007 |
+| For scale: a large language model asked the same questions | 63.8% right on 1,686 committee-labelled test lines (this model 89.0% on the same lines) |
+
+## How it was made
+
+- **Model:** Ettin-32M (`jhu-clsp/ettin-encoder-32m` at 1b8ba06, MIT) in two towers. Each person's card is encoded once, and the line once per utterance. A small head scores each person from the two, their spatial facts and conversation state, and the word-match signals of the rules baseline.
+- **Scenes:** 41,989 scenes built by code in 18 game settings, each with a known answer from written rules of evidence. Lines and casts were written for this project by Qwen3.8-27B (Apache-2.0). The scenes include 12,730 of greetings, simple questions and lines with consequences, and openers said right after a conversation. Each line also has a text-only twin and some a speech-to-text twin.
+- **Labels:** the construction's answer. On dev and test it is checked by the majority vote of a committee of three large language models, which agreed on 88% to 97% of lines. Lines whose words broke their brief take the committee's label.
+- **Spatial facts:** drawn from positions through the bands function. A third of the training lines get fresh facts each epoch.
+
+## Use and limits
+
+- **Use it** to decide who answers a line and whose feelings it may change. Treat `unclear` as a cue for "Who, me?" and hold any change in feeling until the player makes the target clear. **Do not use it** to judge real people.
+- **English only.** Up to 8 people and four lines of history.
+- **It misses things.** About one line in six that should be unclear is given to a person. An opener right after a conversation ("And what's your name?") is ambiguous: the committee disagreed with the rule on 22% of those. It does not know that "check this wound" means the doctor.
+- **Spatial facts depend on the game's band edges.** Tune them for each game (`BandConfig` in `bands.py`).
+- **It has not met real players yet.** It was tested on generated and hand-written lines in game settings, not on logs from real players or from other multi-character settings.
+
+The numbers come from the training repository's reports for this release (`2026-10-08-addr-r2-simple-lines.md` and `2026-10-08-addr-first-models.md`, at git tag `spellspeak-audience-rc1`). That repository is private.

config.json

@@ -0,0 +1,16 @@
+{
+ "run_id": "addr-r2b-ettin-32m-tt-s1",
+ "arch": "twotower",
+ "encoder": "ettin-32m",
+ "repo": "jhu-clsp/ettin-encoder-32m",
+ "rev": "1b8ba06455dd44f80fc9c1ca9e22806157a57379",
+ "max_len": 512,
+ "card_len": 96,
+ "line_len": 64,
+ "temperatures": {
+  "person": 1.0,
+  "unclear": 1.9,
+  "group": 1.55
+ },
+ "render_version": "addressee-tt-0.5"
+}

encoder.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7960e1bc311030450d9e6648829c6f5a82e392c502b7853987e89dc2feb62de5
+size 127960962

example.py

@@ -0,0 +1,56 @@
+"""Ask SpellSpeak Audience who a line is for.
+
+    pip install -r requirements.txt
+    python example.py
+
+The model files (encoder.onnx, head.onnx, tokenizer.json, config.json) are read from this folder. Without them, as in
+a git checkout, they are downloaded once from Hugging Face (spellspeak/audience, release rc1).
+"""
+import pathlib
+import sys
+
+HERE = pathlib.Path(__file__).resolve().parent
+sys.path.insert(0, str(HERE / "runtime"))
+
+from contracts.schemas.addressee import AddresseeRequest  # noqa: E402
+from contracts.schemas.person_card import PersonCard  # noqa: E402
+from harness.addressee.bands import Pose, bands  # noqa: E402
+from harness.addressee.classifier import load_classifier  # noqa: E402
+
+MODEL_FILES = ["encoder.onnx", "head.onnx", "tokenizer.json", "config.json"]
+model_dir = HERE
+if not all((HERE / f).exists() for f in MODEL_FILES):
+    from huggingface_hub import snapshot_download
+
+    model_dir = snapshot_download("spellspeak/audience", revision="rc1", allow_patterns=MODEL_FILES)
+model = load_classifier(model_dir, threads=4)
+
+# What the player can see of each person. Keys are open: a game uses its own.
+people = [
+    PersonCard(id="tomas", label="Tomas", aliases=["barkeep"],
+               features=[{"key": "role", "value": "barkeep"}, {"key": "headwear", "value": "red hat"},
+                         {"key": "holding", "value": "a tankard"}]),
+    PersonCard(id="wren", label="Wren", features=[{"key": "role", "value": "mercenary"}, {"key": "race", "value": "elf"},
+                                                  {"key": "carrying", "value": "a longbow"}]),
+    PersonCard(id="oskar", label="the old sailor", features=[{"key": "build", "value": "stout"},
+                                                             {"key": "holding", "value": "a pipe"}]),
+]
+
+# Where everyone stands (metres) and faces (degrees), turned into the facts the model reads. The player faces Wren.
+facts = bands(Pose(0.0, 0.0, 90.0), {"tomas": Pose(-6.0, 5.0, -40.0), "wren": Pose(0.5, 2.0, -100.0), "oskar": Pose(5.0, 4.0, 180.0)})
+with_facts = [p.model_copy(update={"spatial": facts[p.id].spatial}) for p in people]
+
+
+def reading(a) -> str:
+    """One way a game might read the scores: unclear first, then the whole group, then the top person."""
+    if a.unclear >= 0.5:
+        return f"unclear ({a.unclear:.2f}): a 'Who, me?' moment"
+    if a.to_group >= 0.5:
+        return f"the whole group ({a.to_group:.2f})"
+    top = max(a.addressed, key=a.addressed.get)
+    return f"{top} ({a.addressed[top]:.2f})"
+
+
+for text in ("You in the red hat, another round.", "Hello.", "You lied to me."):
+    for mode, cards in (("with facts", with_facts), ("text only", people)):
+        print(f"{text!r:38} {mode:10}  {reading(model.answer(AddresseeRequest(text=text, present=cards)))}")

head.onnx

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:cb21b22f047d798148da89922b352dd3247840afb3828de6e0aa1e964e798f83
+size 3684676

requirements.txt

@@ -0,0 +1,6 @@
+# SpellSpeak Audience runtime. Tested with onnxruntime 1.30.0, tokenizers 0.23.2, numpy 2.2.6, pydantic 2.13.5.
+onnxruntime>=1.24
+tokenizers>=0.23
+numpy>=2.0
+pydantic>=2.6
+huggingface_hub>=0.30  # only for example.py to fetch the model files when they are not beside it

runtime/contracts/schemas/addressee.py

@@ -0,0 +1,158 @@
+"""Addressee 0.1: who a player line was said to.
+
+The harness sends a request: the player's line, a card for each person present (contracts/schemas/person_card.py)
+and the last few lines of the conversation. The model answers with one probability per person, a probability
+that the words and facts do not pick anyone out (`unclear`), and a probability that the line is for the whole
+group the player is talking with (`to_group`). It scores; it never decides: the harness decides who speaks.
+
+Labels (`AddresseeLabel`) are what the rules of evidence (harness/addressee/evidence.py) give. A clear line lists
+who it was said to. A vague line lists who it could have been said to, so a model can learn that "You lied to me."
+with three people present is a third each, and the harness can play "Who, me?" instead of guessing.
+"""
+from __future__ import annotations
+
+import pathlib
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator
+
+from contracts.schemas.person_card import CardId, PersonCard
+
+SCHEMA_VERSION = "addressee-0.1"
+PLAYER = "player"
+
+MAX_PRESENT = 8   # the snapshot's `present` cap (contracts/schemas/vocab.py)
+MAX_HISTORY = 4   # the last few lines of the conversation
+
+LineText = Annotated[str, StringConstraints(min_length=1, max_length=400)]
+Probability = Annotated[float, Field(ge=0.0, le=1.0)]
+Who = Annotated[str, StringConstraints(pattern=r"^[a-z0-9][a-z0-9_.:-]*$", max_length=64)]  # a card id or "player"
+
+# How the line picks out who it is for (the rules of evidence). The benchmark slices on these.
+Kind = Literal["name", "alias", "role", "appearance", "item", "activity", "place", "neighbour", "several", "group",
+               "answer", "continuation", "correction", "switch", "vague", "nobody",
+               "greeting", "question"]  # rule 5: simple harmless lines
+KINDS: tuple[str, ...] = Kind.__args__
+# What the spatial facts do in this example.
+SpatialPattern = Literal["none", "agree", "contradict", "decide", "conflict", "neutral"]
+SPATIAL_PATTERNS: tuple[str, ...] = SpatialPattern.__args__
+
+
+class Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class HistoryLine(Strict):
+    """An earlier line in this conversation, oldest first. `to` empty: said to the room, or not known."""
+
+    speaker: Who
+    to: list[Who] = Field(default=[], max_length=MAX_PRESENT)
+    text: LineText
+
+
+class AddresseeRequest(Strict):
+    """What the harness sends: the player's line, the people present, and the last few lines."""
+
+    speaker: Literal["player"] = PLAYER
+    text: LineText
+    present: list[PersonCard] = Field(min_length=1, max_length=MAX_PRESENT)
+    history: list[HistoryLine] = Field(default=[], max_length=MAX_HISTORY)
+
+    @model_validator(mode="after")
+    def _people(self) -> "AddresseeRequest":
+        ids = [c.id for c in self.present]
+        if len(set(ids)) != len(ids):
+            raise ValueError("present ids must be distinct")
+        known = set(ids) | {PLAYER}
+        for h in self.history:
+            if h.speaker not in known or any(t not in known for t in h.to):
+                raise ValueError("history lines name only the player and people present")
+            if h.speaker in h.to:
+                raise ValueError("a history line is not said to its own speaker")
+        return self
+
+    def card(self, cid: str) -> PersonCard:
+        return next(c for c in self.present if c.id == cid)
+
+    @property
+    def ids(self) -> list[str]:
+        return [c.id for c in self.present]
+
+    @property
+    def has_spatial(self) -> bool:
+        return any(c.spatial is not None and not c.spatial.empty for c in self.present)
+
+    def text_only(self) -> "AddresseeRequest":
+        """The same request with every spatial fact removed (the text-only input mode)."""
+        return self.model_copy(update={"present": [c.without_spatial() for c in self.present]})
+
+
+class AddresseeAnswer(Strict):
+    """What the model returns. `addressed` has exactly one entry per person present."""
+
+    addressed: dict[CardId, Probability]
+    unclear: Probability
+    to_group: Probability
+
+    def top(self) -> str:
+        return max(self.addressed, key=self.addressed.get)
+
+
+class AddresseeLabel(Strict):
+    """The answer the rules of evidence give. Clear: who it was said to. Vague: who it could have been said to."""
+
+    addressed: list[CardId] = Field(min_length=1, max_length=MAX_PRESENT)
+    vague: bool = False
+    group: bool = False
+
+    @model_validator(mode="after")
+    def _shape(self) -> "AddresseeLabel":
+        if len(set(self.addressed)) != len(self.addressed):
+            raise ValueError("addressed ids must be distinct")
+        if self.vague and self.group:
+            raise ValueError("a group line is clear: everyone in the group")
+        if self.vague and len(self.addressed) < 2:
+            raise ValueError("a vague line lists at least two people it could be for")
+        return self
+
+    def targets(self, ids: list[str]) -> dict[str, float]:
+        """Per-person training targets: 1 for each addressed person; 1/k for each of k candidates when vague."""
+        share = 1.0 / len(self.addressed) if self.vague else 1.0
+        return {i: (share if i in self.addressed else 0.0) for i in ids}
+
+
+class AddresseeRecord(Strict):
+    """A labelled line: the request, its label, and how the line picks its people out. Worked examples,
+    constructed lines, committee labels and the spatial suite all use this record."""
+
+    schema_version: Literal["addressee-0.1"] = SCHEMA_VERSION
+    line_id: Annotated[str, StringConstraints(pattern=r"^[a-z0-9][a-z0-9_.:-]*$", max_length=120)]
+    request: AddresseeRequest
+    label: AddresseeLabel
+    kind: Kind
+    spatial: SpatialPattern = "none"
+    label_source: Literal["guide", "construction", "committee", "person", "model"] = "guide"
+    slices: list[Annotated[str, StringConstraints(pattern=r"^[a-z0-9_]+$")]] = []
+    notes: str | None = None
+
+    @model_validator(mode="after")
+    def _consistent(self) -> "AddresseeRecord":
+        ids = set(self.request.ids)
+        if not set(self.label.addressed) <= ids:
+            raise ValueError(f"label names people not present: {sorted(set(self.label.addressed) - ids)}")
+        if len(ids) == 1 and self.label.vague:
+            raise ValueError("with one person present a line is never vague (rule 1)")
+        if (self.spatial == "none") == self.request.has_spatial:
+            raise ValueError("spatial is `none` exactly when no card carries a spatial fact")
+        return self
+
+
+EXAMPLES_PATH = pathlib.Path(__file__).resolve().parent / "examples" / "addressee-0.1.examples.yaml"
+
+
+def load_examples() -> list[AddresseeRecord]:
+    """The worked examples (examples/ next to this file, not part of a release). The file defines its cards once
+    under `cards` and reuses them with YAML anchors."""
+    import yaml
+
+    return [AddresseeRecord.model_validate(r) for r in yaml.safe_load(EXAMPLES_PATH.read_text())["examples"]]

runtime/contracts/schemas/person_card.py

@@ -0,0 +1,94 @@
+"""Person card 0.1: what the player can see of one person in the scene.
+
+A card is how the addressee model knows who is who. It holds only what the player could see or would call
+someone, never what is true but hidden: a disguised elf is `race: human`, and a hood up makes `hair: hidden`.
+
+- `label` is what the player would call them. The player may not know the name, so "the barkeep" is a valid
+  label. `aliases` hold the other names they answer to (nicknames, titles, what the locals say). `id` is the
+  harness's handle and is never shown to the model.
+- `features` is an open list of `key: value` pairs; the set of keys is not fixed. The model reads them as text.
+  `CORE_KEYS` are recommended, and the ones a harness can later fill from the engine. A game adds any key it
+  likes. A value may be `hidden` (the player cannot see it) or `unknown`.
+- `spatial` is optional, and every fact in it is optional. It is a closed set of plain bands, never raw engine
+  numbers. `harness/addressee/bands.py` turns positions into these bands.
+"""
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, StringConstraints, model_validator
+
+SCHEMA_VERSION = "person-card-0.1"
+
+CardId = Annotated[str, StringConstraints(pattern=r"^[a-z0-9][a-z0-9_.:-]*$", max_length=64)]
+Label = Annotated[str, StringConstraints(min_length=1, max_length=40, strip_whitespace=True)]
+FeatureKey = Annotated[str, StringConstraints(min_length=1, max_length=32, strip_whitespace=True)]
+FeatureValue = Annotated[str, StringConstraints(min_length=1, max_length=80, strip_whitespace=True)]
+
+# Recommended keys. Open: a card may use none of them and any others.
+CORE_KEYS: tuple[str, ...] = (
+    "role", "race", "presents as", "age", "build", "marks", "hair", "facial hair", "headwear", "clothing", "insignia",
+    "holding", "carrying", "doing", "posture", "condition", "near", "with",
+)
+HIDDEN, UNKNOWN = "hidden", "unknown"
+
+MAX_FEATURES = 16
+MAX_ALIASES = 4
+
+Distance = Literal["near", "mid", "far"]
+DISTANCES: tuple[str, ...] = Distance.__args__
+
+
+class Strict(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+
+class Feature(Strict):
+    key: FeatureKey
+    value: FeatureValue
+
+    @property
+    def visible(self) -> bool:
+        return self.value.lower() not in (HIDDEN, UNKNOWN)
+
+
+class SpatialFacts(Strict):
+    """What the game knows about where this person is relative to the player, in bands. None: not known."""
+
+    distance: Distance | None = None
+    in_view: bool | None = None              # inside the player's gaze cone when they started speaking
+    in_group: bool | None = None             # in the player's current conversation group
+    following: bool | None = None            # following the player
+    asked_you: bool | None = None            # has a question waiting for the player's answer
+    last_spoke_with_you: bool | None = None  # the last person the player was talking with
+
+    @property
+    def empty(self) -> bool:
+        return all(v is None for v in self.model_dump().values())
+
+
+class PersonCard(Strict):
+    id: CardId
+    label: Label
+    aliases: list[Label] = Field(default=[], max_length=MAX_ALIASES)
+    features: list[Feature] = Field(default=[], max_length=MAX_FEATURES)
+    spatial: SpatialFacts | None = None
+
+    @model_validator(mode="after")
+    def _names(self) -> "PersonCard":
+        names = [self.label.lower()] + [a.lower() for a in self.aliases]
+        if len(set(names)) != len(names):
+            raise ValueError("aliases must differ from the label and from each other")
+        if self.id == "player":
+            raise ValueError("`player` is reserved for the player, who has no card")
+        return self
+
+    def feature(self, key: str) -> list[str]:
+        return [f.value for f in self.features if f.key.lower() == key.lower()]
+
+    @property
+    def names(self) -> list[str]:
+        return [self.label, *self.aliases]
+
+    def without_spatial(self) -> "PersonCard":
+        return self.model_copy(update={"spatial": None})

runtime/harness/addressee/__init__.py

@@ -0,0 +1,9 @@
+"""The addressee model (released as SpellSpeak Audience): who a player's line was said to.
+
+- `render`: how the single-pass model reads a request (addressee-input-0.1), shared by training and the runtime.
+- `features`: the cached-cards model's inputs (addressee-tt-0.5), shared by training and the runtime.
+- `classifier`: the model at run time, on ONNX Runtime.
+- `evidence`: the rules of evidence as code, shared by the data generator and the rules baseline.
+- `rules`: the rules baseline, the floor and the harness's instant fallback.
+- `bands`: positions and facings to the spatial facts the model reads.
+"""

runtime/harness/addressee/bands.py

@@ -0,0 +1,71 @@
+"""Positions to spatial facts: the one piece of harness logic a scene demo needs.
+
+A game knows where everyone stands and which way they face. The addressee model reads plain bands instead
+(contracts/schemas/person_card.py `SpatialFacts`), so it is never tied to one game's units. This turns poses
+into those bands. Band edges are per game (`BandConfig`); a heatmap of the answers over the floor helps tune them.
+
+Coordinates are any flat 2D frame in metres. Facing is in degrees in the same frame (`atan2(dy, dx)`), so the
+handedness of the frame does not matter. The player's facing is read when they start speaking, not when they stop.
+
+The group rule here is a placeholder: an explicit group from the game wins; otherwise a person is in the group
+when they stand within `group_m` of the player, in front of them, and face them. Anyone following the player is in
+the group. A real game should use its own conversation state.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+
+from contracts.schemas.person_card import SpatialFacts
+
+
+@dataclass(frozen=True)
+class Pose:
+    x: float
+    y: float
+    facing: float = 0.0  # degrees
+
+
+@dataclass(frozen=True)
+class BandConfig:
+    near_m: float = 3.0               # conversation distance
+    mid_m: float = 8.0                # across a room
+    earshot_m: float = 15.0           # beyond this a person cannot hear the line and is left out of the request
+    gaze_half_angle_deg: float = 20.0
+    group_m: float = 2.5
+    group_facing_deg: float = 60.0
+
+
+@dataclass(frozen=True)
+class Band:
+    spatial: SpatialFacts
+    can_hear: bool
+    distance_m: float
+    angle_deg: float  # from the player's facing to the person, 0 to 180
+
+
+def _angle(a: float, b: float) -> float:
+    d = (a - b + 180.0) % 360.0 - 180.0
+    return abs(d)
+
+
+def bands(player: Pose, people: dict[str, Pose], cfg: BandConfig = BandConfig(), *, group: set[str] | None = None,
+          following: set[str] = frozenset(), asked: set[str] = frozenset(), last_spoke: str | None = None) -> dict[str, Band]:
+    out = {}
+    for pid, p in people.items():
+        dx, dy = p.x - player.x, p.y - player.y
+        dist = math.hypot(dx, dy)
+        toward = math.degrees(math.atan2(dy, dx)) if dist > 1e-9 else player.facing
+        angle = _angle(toward, player.facing)
+        distance = "near" if dist <= cfg.near_m else "mid" if dist <= cfg.mid_m else "far"
+        if group is not None:
+            in_group = pid in group
+        else:
+            back = math.degrees(math.atan2(-dy, -dx))  # from the person toward the player
+            in_group = dist <= cfg.group_m and angle <= 90.0 and _angle(p.facing, back) <= cfg.group_facing_deg
+        in_group = in_group or pid in following
+        out[pid] = Band(spatial=SpatialFacts(distance=distance, in_view=angle <= cfg.gaze_half_angle_deg, in_group=in_group,
+                                             following=pid in following, asked_you=pid in asked,
+                                             last_spoke_with_you=pid == last_spoke),
+                        can_hear=dist <= cfg.earshot_m, distance_m=round(dist, 3), angle_deg=round(angle, 2))
+    return out

runtime/harness/addressee/classifier.py

@@ -0,0 +1,145 @@
+"""The addressee model at run time: ONNX Runtime on the CPU, no torch.
+
+A model folder holds `model.onnx` (encoder and heads in one graph; inputs input_ids, attention_mask and the
+per-person marker masks; outputs one logit per person, the unclear logit and the group logit), `tokenizer.json` and
+`config.json` (temperatures fitted on dev, max length, render version). One encoder pass per line, whatever the number
+of people. The input is rendered by `harness/addressee/render.py`, the same code training used.
+"""
+from __future__ import annotations
+
+import json
+import math
+import pathlib
+import time
+
+from contracts.schemas.addressee import AddresseeAnswer, AddresseeRequest
+from harness.addressee.render import RENDER_VERSION, render, span_mask
+
+
+def _sigmoid(x: float) -> float:
+    return 1.0 / (1.0 + math.exp(-x)) if x >= 0 else math.exp(x) / (1.0 + math.exp(x))
+
+
+class AddresseeClassifier:
+    def __init__(self, model_dir: str | pathlib.Path, onnx_file: str = "model.onnx", threads: int = 4):
+        import numpy as np
+        import onnxruntime as ort
+        from tokenizers import Tokenizer
+
+        self.np = np
+        d = pathlib.Path(model_dir)
+        self.config = json.loads((d / "config.json").read_text())
+        if self.config.get("render_version", RENDER_VERSION) != RENDER_VERSION:
+            raise ValueError(f"model expects {self.config['render_version']}, the runtime renders {RENDER_VERSION}")
+        self.tok = Tokenizer.from_file(str(d / "tokenizer.json"))
+        self.tok.enable_truncation(self.config["max_len"])
+        self.tok.no_padding()
+        so = ort.SessionOptions()
+        so.intra_op_num_threads = threads
+        so.inter_op_num_threads = 1
+        self.sess = ort.InferenceSession(str(d / onnx_file), so, providers=["CPUExecutionProvider"])
+        self.temps = self.config["temperatures"]
+
+    def logits(self, req: AddresseeRequest) -> tuple[list[float], float, float]:
+        np = self.np
+        text, spans = render(req)
+        enc = self.tok.encode(text)
+        sm = np.asarray(span_mask(enc.offsets, spans), dtype=np.float32)
+        lp, lu, lg = self.sess.run(None, {"input_ids": np.asarray([enc.ids], dtype=np.int64),
+                                          "attention_mask": np.asarray([enc.attention_mask], dtype=np.int64),
+                                          "span_mask": sm})
+        return [float(x) for x in lp.reshape(-1)], float(lu.reshape(-1)[0]), float(lg.reshape(-1)[0])
+
+    def answer(self, req: AddresseeRequest) -> AddresseeAnswer:
+        lp, lu, lg = self.logits(req)
+        t = self.temps
+        return AddresseeAnswer(addressed={pid: _sigmoid(x / t["person"]) for pid, x in zip(req.ids, lp)},
+                               unclear=_sigmoid(lu / t["unclear"]), to_group=_sigmoid(lg / t["group"]))
+
+    def timed(self, req: AddresseeRequest) -> tuple[AddresseeAnswer, float]:
+        t0 = time.perf_counter()
+        a = self.answer(req)
+        return a, (time.perf_counter() - t0) * 1000
+
+
+class CachedCardsClassifier:
+    """The cached-cards model (addressee-tt-0.1) at run time. Two ONNX graphs: `encoder.onnx` encodes a card's text
+    (without facts; the result is kept per card text) and, per utterance, the player's line; `head.onnx` scores each
+    person from the line, their cached card and their facts and conversation vector."""
+
+    def __init__(self, model_dir: str | pathlib.Path, threads: int = 4):
+        import numpy as np
+        import onnxruntime as ort
+        from tokenizers import Tokenizer
+
+        from harness.addressee.features import TT_VERSION
+
+        self.np = np
+        d = pathlib.Path(model_dir)
+        self.config = json.loads((d / "config.json").read_text())
+        if self.config.get("render_version") != TT_VERSION:
+            raise ValueError(f"model expects {self.config.get('render_version')}, the runtime renders {TT_VERSION}")
+        self.card_tok = Tokenizer.from_file(str(d / "tokenizer.json"))
+        self.card_tok.enable_truncation(self.config["card_len"])
+        self.card_tok.no_padding()
+        self.line_tok = Tokenizer.from_file(str(d / "tokenizer.json"))
+        self.line_tok.enable_truncation(self.config["line_len"])
+        self.line_tok.no_padding()
+        so = ort.SessionOptions()
+        so.intra_op_num_threads = threads
+        so.inter_op_num_threads = 1
+        self.enc = ort.InferenceSession(str(d / "encoder.onnx"), so, providers=["CPUExecutionProvider"])
+        self.head = ort.InferenceSession(str(d / "head.onnx"), so, providers=["CPUExecutionProvider"])
+        self.temps = self.config["temperatures"]
+        self.cache: dict[str, tuple] = {}
+
+    def card(self, text: str) -> tuple:
+        """(token states, projected token states) for one card text, from the cache or encoded now."""
+        hit = self.cache.get(text)
+        if hit is None:
+            np = self.np
+            enc = self.card_tok.encode(text)
+            g, gp, _ = self.enc.run(None, {"ids": np.asarray([enc.ids], dtype=np.int64),
+                                           "mask": np.asarray([enc.attention_mask], dtype=np.int64)})
+            hit = (g[0], gp[0])
+            self.cache[text] = hit
+        return hit
+
+    def logits(self, req: AddresseeRequest) -> tuple[list[float], float, float]:
+        from harness.addressee.features import card_only, line_features, line_input, person_features
+
+        np = self.np
+        cached = [self.card(card_only(c)) for c in req.present]
+        L = max(g.shape[0] for g, _ in cached)
+        d, k = cached[0][0].shape[1], cached[0][1].shape[1]
+        g = np.zeros((len(cached), L, d), dtype=np.float32)
+        gp = np.zeros((len(cached), L, k), dtype=np.float32)
+        cm = np.zeros((len(cached), L), dtype=np.int64)
+        for i, (a, b) in enumerate(cached):
+            g[i, :a.shape[0]], gp[i, :b.shape[0]], cm[i, :a.shape[0]] = a, b, 1
+        text, cur_len = line_input(req)
+        enc = self.line_tok.encode(text)
+        cur = np.asarray([[1.0 if (b > a and b <= cur_len) else 0.0 for a, b in enc.offsets]], dtype=np.float32)
+        h, hp, q = self.enc.run(None, {"ids": np.asarray([enc.ids], dtype=np.int64),
+                                       "mask": np.asarray([enc.attention_mask], dtype=np.int64)})
+        lp, lu, lg = self.head.run(None, {
+            "q": q, "h": h, "hp": hp, "cur": cur, "g": g, "gp": gp, "card_mask": cm,
+            "pfeat": np.asarray(person_features(req), dtype=np.float32), "lfeat": np.asarray([line_features(req)], dtype=np.float32)})
+        return [float(x) for x in lp.reshape(-1)], float(lu.reshape(-1)[0]), float(lg.reshape(-1)[0])
+
+    def answer(self, req: AddresseeRequest) -> AddresseeAnswer:
+        lp, lu, lg = self.logits(req)
+        t = self.temps
+        return AddresseeAnswer(addressed={pid: _sigmoid(x / t["person"]) for pid, x in zip(req.ids, lp)},
+                               unclear=_sigmoid(lu / t["unclear"]), to_group=_sigmoid(lg / t["group"]))
+
+    def timed(self, req: AddresseeRequest) -> tuple[AddresseeAnswer, float]:
+        t0 = time.perf_counter()
+        a = self.answer(req)
+        return a, (time.perf_counter() - t0) * 1000
+
+
+def load_classifier(model_dir: str | pathlib.Path, threads: int = 4):
+    """The right runtime for an exported model folder: cached cards when it has a card encoder, else single pass."""
+    d = pathlib.Path(model_dir)
+    return CachedCardsClassifier(d, threads) if (d / "head.onnx").exists() else AddresseeClassifier(d, threads=threads)

runtime/harness/addressee/evidence.py

@@ -0,0 +1,138 @@
+"""The rules of evidence as code: who a line is for, given what its words pick out and what the game knows.
+
+Two callers: the data generator, which knows by construction what the words of a line pick out and asks for the
+label, and the rules baseline (harness/addressee/rules.py), which guesses what the words pick out from the text.
+Both then go through `resolve`, so a constructed label and the baseline's answer follow the same rules.
+
+The rules, strongest first:
+
+1. One person present: the line is for them.
+2. Words for the whole group ("right, listen to me"): everyone in the player's group when the facts say who that
+   is, otherwise everyone present.
+3. Words that pick out people: one person, or a set named on purpose ("you two", "Tomas and Wren"), is clear. A
+   description that fits several people is broken only by the other evidence agreeing on one of them; else vague
+   among those it fits.
+4. Words that pick out no one ("You lied to me.", "Yes."): a bare answer goes to whoever asked. Otherwise the other signals
+   must agree: who the player was talking with, the one person near and in view, the one person in the group, the
+   one person near (or, with nobody near, the one person at mid range). Agreement on one person is clear.
+   Disagreement is vague among them. No signal is vague among everyone not known to be far away.
+5. A simple, harmless line with no name or description (a greeting, small talk, a simple question, a thank-you).
+   After a bare answer: a line that carries on the conversation (a reply, a thank-you, a goodbye, a follow-up) goes to
+   the one the player was talking with. Otherwise (an opener: "Hello.", "Who are you?"): the person the player is
+   looking at within mid range (the nearest of them), else the one the player was talking with, else the one person
+   in the group, else the one person near (or at mid range), else the whole group. Never vague: nobody says
+   "Who, me?" to a hello. Someone far away in view is not "looked at".
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from contracts.schemas.addressee import PLAYER, AddresseeLabel, AddresseeRequest
+from contracts.schemas.person_card import PersonCard
+
+
+@dataclass(frozen=True)
+class Evidence:
+    """What the words and the conversation say, before the spatial facts are read."""
+
+    words: frozenset[str] = frozenset()   # ids the words pick out; empty: the words pick out no one
+    words_set: bool = False                # the words name all of `words` on purpose ("you two", "Tomas and Wren")
+    words_group: bool = False              # the words are for the whole group ("listen to me", "evening, all")
+    asker: str | None = None               # who has a question waiting for the player's answer
+    partner: str | None = None             # who the player was talking with
+    benign: bool = False                   # a simple, harmless line: greeting, small talk, simple question (rule 5)
+    follows: bool = False                  # it carries on the conversation (a reply, thanks, a follow-up), not an opener
+
+
+def _f(c: PersonCard, name: str):
+    return getattr(c.spatial, name) if c.spatial is not None else None
+
+
+def history_signals(req: AddresseeRequest) -> tuple[str | None, str | None]:
+    """(asker, partner) from the history text and the facts. The last line decides: an NPC's question to the player
+    makes them the asker; any line between the player and exactly one person makes that person the partner. A fact
+    on exactly one card (asked_you, last_spoke_with_you) counts the same when the history says nothing."""
+    asker = partner = None
+    if req.history:
+        last = req.history[-1]
+        if last.speaker != PLAYER and (last.to == [PLAYER] or (not last.to and len(req.present) == 1)):
+            partner = last.speaker
+            if last.text.rstrip().rstrip('"\'').endswith("?"):
+                asker = last.speaker
+        elif last.speaker == PLAYER and len(last.to) == 1:
+            partner = last.to[0]
+    if asker is None:
+        asked = [c.id for c in req.present if _f(c, "asked_you") is True]
+        asker = asked[0] if len(asked) == 1 else None
+    if partner is None:
+        spoke = [c.id for c in req.present if _f(c, "last_spoke_with_you") is True]
+        partner = spoke[0] if len(spoke) == 1 else None
+    return asker, partner
+
+
+def _one(ids: list[str]) -> str | None:
+    return ids[0] if len(ids) == 1 else None
+
+
+def spatial_signals(req: AddresseeRequest, among: list[str] | None = None) -> dict[str, str | None]:
+    """The one person each spatial signal points to, or None. `among` limits the people considered."""
+    cards = [c for c in req.present if among is None or c.id in among]
+    near = [c.id for c in cards if _f(c, "distance") == "near"]
+    mid = [c.id for c in cards if _f(c, "distance") == "mid"]
+    return {
+        "gaze": _one([c.id for c in cards if _f(c, "in_view") is True and (among is not None or _f(c, "distance") == "near")]),
+        "group": _one([c.id for c in cards if _f(c, "in_group") is True]),
+        # A line said to no one in particular could be for anyone, unless only one person is within a moderate radius.
+        "nearby": _one(near) if near else _one(mid),
+    }
+
+
+def _ordered(req: AddresseeRequest, ids) -> list[str]:
+    ids = set(ids)
+    return [c.id for c in req.present if c.id in ids]
+
+
+def _agree(req: AddresseeRequest, signals: list[str | None], fallback: list[str]) -> AddresseeLabel:
+    pointed = _ordered(req, {s for s in signals if s is not None})
+    if len(pointed) == 1:
+        return AddresseeLabel(addressed=pointed)
+    if len(pointed) >= 2:
+        return AddresseeLabel(addressed=pointed, vague=True)
+    return AddresseeLabel(addressed=fallback, vague=True) if len(fallback) >= 2 else AddresseeLabel(addressed=fallback)
+
+
+def resolve(req: AddresseeRequest, ev: Evidence) -> AddresseeLabel:
+    ids = req.ids
+    if len(ids) == 1:                                                     # rule 1
+        return AddresseeLabel(addressed=ids, group=ev.words_group)
+    if ev.words_group:                                                    # rule 2
+        grouped = [c.id for c in req.present if _f(c, "in_group") is True]
+        return AddresseeLabel(addressed=grouped or ids, group=True)
+    words = _ordered(req, ev.words)
+    if len(words) == 1 or (words and ev.words_set):                       # rule 3, clear
+        return AddresseeLabel(addressed=words)
+    asker, partner = history_signals(req)
+    if words:                                                             # rule 3, a description that fits several
+        sp = spatial_signals(req, among=words)
+        inside = [s if s in words else None for s in (asker, partner, sp["gaze"], sp["group"])]
+        return _agree(req, inside, words)
+    if asker is not None:                                                 # rule 4, a bare answer
+        return AddresseeLabel(addressed=[asker])
+    sp = spatial_signals(req)
+    if ev.benign:                                                         # rule 5, a simple harmless line
+        if ev.follows and partner is not None:
+            return AddresseeLabel(addressed=[partner])
+        rank = {"near": 0, "mid": 1, None: 2}
+        looked = [c for c in req.present if _f(c, "in_view") is True and _f(c, "distance") != "far"]
+        if looked:
+            best = min(rank[_f(c, "distance")] for c in looked)
+            nearest = [c.id for c in looked if rank[_f(c, "distance")] == best]
+            if len(nearest) == 1:
+                return AddresseeLabel(addressed=nearest)
+        for who in (partner, sp["group"], sp["nearby"]):
+            if who is not None:
+                return AddresseeLabel(addressed=[who])
+        grouped = [c.id for c in req.present if _f(c, "in_group") is True]
+        return AddresseeLabel(addressed=grouped or ids, group=True)
+    not_far = [c.id for c in req.present if _f(c, "distance") != "far"]
+    return _agree(req, [partner, sp["gaze"], sp["group"], sp["nearby"]], not_far if len(not_far) >= 2 else ids)

runtime/harness/addressee/features.py

@@ -0,0 +1,85 @@
+"""Inputs for the cached-cards addressee model (`TT_VERSION`). Shared by training and the runtime.
+
+The single-pass model reads every card with every line (harness/addressee/render.py), which cost 18 to 65 ms on our
+test Mac for one to eight people. This model splits the work:
+
+- A card's text, without its spatial facts, is encoded once and cached. It changes only when what the player can see
+  of that person changes (an item picked up, a hood raised, walking over to the fire).
+- The player's line is encoded on every utterance, with the line before it as context: a few dozen tokens.
+- The spatial facts and the conversation state become a small vector per person, so moving people around never
+  re-encodes anything.
+
+Per-person vector (PERSON_DIM): distance near, mid, far, unknown; in view yes, no, unknown; in group yes, no, unknown;
+following; asked you (fact); spoke with you last (fact); the last history line was theirs to the player; it was a
+question; the player's last line was to them; they spoke at all in the history; the player spoke to them at all;
+one over the number of people present; then the rules baseline's word matcher and answer: their name or alias used
+to call them, only mentioned, their best feature match (share of three words), they have the top match, pointed at by
+who they are with, the rules' probability for them.
+Line vector (LINE_DIM): number of people present (one-hot, 1 to 8), any spatial fact known, any history; group words,
+pair words ("you two"), the rules call the line unclear, the rules call it a group line; a simple harmless line and an
+opener by the word lists (rule 5 in harness/addressee/evidence.py).
+"""
+from __future__ import annotations
+
+from contracts.schemas.addressee import PLAYER, AddresseeRequest
+from contracts.schemas.person_card import PersonCard
+from harness.addressee.render import card_text
+
+TT_VERSION = "addressee-tt-0.5"
+PERSON_DIM = 25
+LINE_DIM = 16
+
+
+def card_only(c: PersonCard) -> str:
+    """The cached part of a card: what the player can see, without where the person is."""
+    return card_text(c.without_spatial())
+
+
+def line_input(req: AddresseeRequest) -> tuple[str, int]:
+    """The text the line encoder reads and the character length of the current line within it. Names of earlier
+    speakers are left out: who said what is in the per-person vector, so a name in the history is never mistaken for
+    a name in the line."""
+    cur = f"\"{req.text}\""
+    if req.history:
+        return cur + f" Before: \"{req.history[-1].text}\"", len(cur)
+    return cur, len(cur)
+
+
+def _three(v: bool | None) -> list[float]:
+    return [1.0 if v is True else 0.0, 1.0 if v is False else 0.0, 1.0 if v is None else 0.0]
+
+
+def person_features(req: AddresseeRequest) -> list[list[float]]:
+    from harness.addressee.rules import match_signals, rules_answer
+
+    per, _ = match_signals(req)
+    rules = rules_answer(req).addressed
+    last = req.history[-1] if req.history else None
+    player_last = next((h for h in reversed(req.history) if h.speaker == PLAYER), None)
+    n = len(req.present)
+    out = []
+    for c in req.present:
+        s = c.spatial
+        d = s.distance if s else None
+        v = [1.0 if d == "near" else 0.0, 1.0 if d == "mid" else 0.0, 1.0 if d == "far" else 0.0, 1.0 if d is None else 0.0]
+        v += _three(s.in_view if s else None) + _three(s.in_group if s else None)
+        v += [float(bool(s and s.following)), float(bool(s and s.asked_you)), float(bool(s and s.last_spoke_with_you))]
+        theirs = last is not None and last.speaker == c.id and (PLAYER in last.to or not last.to)
+        v += [float(theirs), float(theirs and last.text.rstrip().rstrip('"\'').endswith("?")),
+              float(player_last is not None and player_last.to == [c.id]),
+              float(any(h.speaker == c.id for h in req.history)),
+              float(any(h.speaker == PLAYER and c.id in h.to for h in req.history)),
+              1.0 / n]
+        v += [*per[len(out)], rules[c.id]]
+        out.append(v)
+    return out
+
+
+def line_features(req: AddresseeRequest) -> list[float]:
+    from harness.addressee.rules import match_signals, rules_answer
+
+    n = min(len(req.present), 8)
+    _, (group_words, pair_words, simple, opener) = match_signals(req)
+    ra = rules_answer(req)
+    return [1.0 if i == n else 0.0 for i in range(1, 9)] + [float(req.has_spatial), float(bool(req.history)),
+                                                           group_words, pair_words, ra.unclear, ra.to_group, simple, opener]

runtime/harness/addressee/render.py

@@ -0,0 +1,100 @@
+"""How the addressee model reads a request (render addressee-input-0.1). Shared by training and the runtime.
+
+Everyone present comes first, one bracketed marker each holding what the player can see of them and, when the game
+knows, where they are. Then the player's line. Then the history, newest first, so truncation cuts the oldest line
+and never a person or the line itself:
+
+    People: [Tomas (the barkeep). role: barkeep; headwear: red hat; holding: a tankard. near you, in view, spoke with
+    you last] [Wren. role: mercenary; hair: hidden. mid-range, out of view]. The player: "You in the red hat, a word."
+    Before: Tomas to the player: "Another round?" | The player to Tomas: "Go on then."
+
+A person's head reads the tokens of their marker, brackets included. Features keep the caller's order; a card over
+`MAX_CARD_CHARS` loses features from the end, so put the most telling features first.
+Spatial facts are never cut. Unknown facts are left out; known negatives that matter are said ("out of view").
+"""
+from __future__ import annotations
+
+from contracts.schemas.addressee import PLAYER, AddresseeRequest, HistoryLine
+from contracts.schemas.person_card import PersonCard, SpatialFacts
+
+
+def span_mask(offsets: list[tuple[int, int]], spans: list[tuple[int, int]]) -> list[list[float]]:
+    """Per target, which tokens belong to its marker (special tokens have empty offsets and never do). The same mask as
+    the line classifier's (harness/expression/render.py), kept here so this runtime stands alone."""
+    rows = []
+    for a, b in spans:
+        row = [1.0 if (t > s and s >= a and t <= b) else 0.0 for s, t in offsets]
+        if not any(row):
+            row[0] = 1.0
+        rows.append(row)
+    return rows
+
+
+RENDER_VERSION = "addressee-input-0.1"
+MAX_CARD_CHARS = 240
+
+DISTANCE_WORDS = {"near": "near you", "mid": "mid-range", "far": "far away"}
+
+
+def spatial_words(s: SpatialFacts | None) -> list[str]:
+    if s is None:
+        return []
+    out = []
+    if s.distance is not None:
+        out.append(DISTANCE_WORDS[s.distance])
+    if s.in_view is not None:
+        out.append("in view" if s.in_view else "out of view")
+    if s.in_group is not None:
+        out.append("in your group" if s.in_group else "not in your group")
+    if s.following:
+        out.append("following you")
+    if s.asked_you:
+        out.append("asked you something")
+    if s.last_spoke_with_you:
+        out.append("spoke with you last")
+    return out
+
+
+def card_text(c: PersonCard, max_chars: int = MAX_CARD_CHARS) -> str:
+    """The inside of one person's marker."""
+    head = c.label + (f" ({', '.join(c.aliases)})" if c.aliases else "")
+    tail = ", ".join(spatial_words(c.spatial))
+    budget = max_chars - len(head) - (len(tail) + 2 if tail else 0)
+    feats: list[str] = []
+    used = 0
+    for f in c.features:
+        piece = f"{f.key}: {f.value}"
+        if used + len(piece) + 2 > budget:
+            break
+        feats.append(piece)
+        used += len(piece) + 2
+    text = head + (". " + "; ".join(feats) if feats else "")
+    return text + (". " + tail if tail else "")
+
+
+def who(req: AddresseeRequest, pid: str) -> str:
+    return "the player" if pid == PLAYER else req.card(pid).label
+
+
+def history_text(req: AddresseeRequest, h: HistoryLine) -> str:
+    to = " and ".join(who(req, t) for t in h.to)
+    speaker = who(req, h.speaker)
+    speaker = speaker[0].upper() + speaker[1:]
+    return f"{speaker}{' to ' + to if to else ''}: \"{h.text}\""
+
+
+def render(req: AddresseeRequest, order: list[str] | None = None) -> tuple[str, list[tuple[int, int]]]:
+    """The input text and, per person in `req.present` order, the character span of their marker (brackets
+    included). `order` is the order the people are written in (training shuffles it); default: as given."""
+    order = order or req.ids
+    if sorted(order) != sorted(req.ids):
+        raise ValueError("order must be a permutation of the people present")
+    text, at = "People:", {}
+    for pid in order:
+        start = len(text) + 1
+        text += f" [{card_text(req.card(pid))}]"
+        at[pid] = (start, len(text))
+    text += f". The player: \"{req.text}\""
+    if req.history:
+        text += " Before: " + " | ".join(history_text(req, h) for h in reversed(req.history))
+    return text, [at[pid] for pid in req.ids]

runtime/harness/addressee/rules.py

@@ -0,0 +1,212 @@
+"""The rules baseline: word matching plus the rules of evidence (harness/addressee/evidence.py). No model.
+
+It is the floor every model is compared against, the scene demo's first engine, and the harness's instant fallback.
+What the words pick out is guessed from the text:
+
+1. Names: a person's label or alias used to call them: at the start, after a greeting or "hey", or set off by commas
+   ("Tomas, another round", "Oi, barkeep!"). A name the line only talks about ("tell Wren", "talking to the mechanic")
+   is not a call. Two or more calls are a set named on purpose ("Tomas, Wren, a word").
+1b. Neighbours: "you, talking to the barkeep" points at whoever's card says they are with the barkeep.
+2. Group words with no name: "everyone", "anyone", "someone", "all of you", "you guys", "you lot", "listen up". "You
+   two" and "both of you" are the two people present when there are two, otherwise the group (rule 2).
+3. Descriptions: content words of each visible feature value found in the line ("red hat" in "you in the red hat").
+   The person or people with the most matching words are picked out. A word matches a longer one it starts
+   ("fire" and "fireplace") when it has four letters or more.
+
+Then `evidence.resolve` applies the rules of evidence with the history and the spatial facts. Known limits: no fuzzy
+match for misheard names, and any shared content word counts as a description, even an incidental one.
+"""
+from __future__ import annotations
+
+import re
+
+from contracts.schemas.addressee import AddresseeAnswer, AddresseeLabel, AddresseeRequest
+from harness.addressee.evidence import Evidence, resolve
+
+STOP = frozenset("""a an the of and or to in on at by with from for as is are was were be been it its this that these those
+there here you your yours you're ya ye u i me my mine we us our he him his she her hers they them their one ones who what
+which where when how why do does did not no yes so but if then than just very too some any all also over up down out
+into onto off about around near next behind front back side left right old new big small little bit lot""".split())
+# Words that, with no name in the line, address the whole group.
+GROUP = re.compile(r"\b(everyone|everybody|anyone|anybody|someone|somebody|all of you|you all|y'?all|you lot|you people|"
+                   r"you guys|guys|folks|lads|gents|listen up|listen to me|gather round|(morning|evening|afternoon|hello|hi|hey|night),? all)\b", re.I)
+PAIR = re.compile(r"\b(you two|both of you|you both|the pair of you|the two of you)\b", re.I)
+# Simple, harmless lines (rule 5): greetings, small talk, simple questions, thanks, polite requests.
+SIMPLE = re.compile(r"\b(hello|hi|hiya|hey there|hey|howdy|greetings|good (morning|afternoon|evening|day|night)|morning|evening|"
+                    r"afternoon|well met|ahoy|yo|g'?day|what'?s up|who are you|what'?s your name|what is your name|who'?s this|"
+                    r"what is this place|what'?s this place|where am i|where'?s|where is|what do you (do|sell|have|want|need)|how much|"
+                    r"can you help|could you help|can i ask|excuse me|pardon|how are you|how'?s it going|how do you do|"
+                    r"(nice|pleased|good) to meet|what'?s going on|what happened|any news|what'?s new|got a (minute|moment|sec)|"
+                    r"do you know|have you seen|can i (buy|get|have)|i'?d like|thanks|thank you|cheers|much obliged|goodbye|bye|"
+                    r"see you|farewell|take care|nice (weather|day|place)|(is|are) \w+ (around|here|about|in))\b", re.I)
+# Words that give a line consequences (rule 4): insults, threats, accusations, orders to go away.
+HOSTILE = re.compile(r"\b(idiot|moron|fool|stupid|dumb|useless|worthless|pathetic|scum|bastard|damn|shut up|get out|go away|"
+                     r"piss|crap|ugly|loser|coward|liar|lied|lying|thief|stole|steal|kill|gut|hurt|smash|break your|fuck|shit|"
+                     r"wanker|git|prat|twit|clown|filthy|disgusting|stink|lazy|move it|out of my way|hate|rat|pig|wretch)\b", re.I)
+
+
+# Lines that open an exchange rather than carry one on (rule 5): greetings and introductions.
+OPENER = re.compile(r"\b(hello|hi|hiya|hey there|hey|howdy|greetings|good (morning|afternoon|evening|day)|well met|ahoy|g'?day|"
+                    r"who are you|who'?s this|what'?s your name|what is your name|(nice|pleased|good) to meet|excuse me|pardon me|"
+                    r"sorry to bother|got a (minute|moment|sec)|have you got a (minute|moment))\b", re.I)
+
+
+def is_opener(text: str) -> bool:
+    """A line that opens an exchange (a greeting, "who are you?"), not one that carries the conversation on."""
+    return bool(OPENER.search(text))
+
+
+def is_simple(text: str) -> bool:
+    """A simple, harmless line (rule 5): simple words or a short question, and nothing hostile."""
+    if HOSTILE.search(text):
+        return False
+    short_question = text.rstrip().endswith("?") and len(_words(text)) <= 8
+    return bool(SIMPLE.search(text)) or short_question
+WORD = re.compile(r"[a-z0-9']+")
+
+
+def _words(text: str) -> list[str]:
+    return [w.strip("'") for w in WORD.findall(text.lower()) if w.strip("'")]
+
+
+def _content(text: str) -> set[str]:
+    return {w for w in _words(text) if w not in STOP and len(w) > 1}
+
+
+def _match(a: str, b: str) -> bool:
+    if a == b:
+        return True
+    short, long_ = sorted((a, b), key=len)
+    return len(short) >= 4 and long_.startswith(short)
+
+
+def _name_hit(name: str, line_words: list[str]) -> bool:
+    parts = _words(name)
+    if parts and parts[0] == "the" and len(parts) > 1:
+        parts = parts[1:]
+    n = len(parts)
+    return n > 0 and any(line_words[i:i + n] == parts for i in range(len(line_words) - n + 1))
+
+
+# Words that may come before a name that calls someone ("Hey, Tomas", "Excuse me Tomas", "Good morning, Tomas").
+LEAD = frozenset("""hey oi hi hello excuse me sorry right ok okay well listen look yo ah um uh so and now please thanks thank you
+dear good morning evening afternoon night sir madam ma'am miss mister oh""".split())
+# Phrases that point at someone by who they are with ("you, talking to the mechanic").
+NEIGHBOUR = re.compile(r"\b(talking to|talking with|chatting with|chatting to|speaking to|speaking with|sitting with|standing with|"
+                       r"next to|beside|with)\s+(the\s+)?$", re.I)
+
+
+def name_use(name: str, text: str) -> str | None:
+    """How the line uses a name: "call" when it calls that person (at the start, after a greeting or "hey", or set
+    off by commas or at the end after a comma), "mention" when it only talks about them ("tell Wren", "talking to the
+    mechanic"), None when the name is absent (rule 3)."""
+    parts = _words(name)
+    if parts and parts[0] == "the" and len(parts) > 1:
+        parts = parts[1:]
+    if not parts:
+        return None
+    pattern = re.compile(r"\b" + r"\W+".join(re.escape(x) for x in parts) + r"\b", re.I)
+    use = None
+    for m in pattern.finditer(text):
+        before, after = text[:m.start()], text[m.end():]
+        b = before.rstrip()
+        b = re.sub(r"\bthe$", "", b, flags=re.I).rstrip() if re.search(r"\bthe$", b, re.I) else b
+        clause = re.split(r"[,.!?;:]", b)[-1]  # only the words since the last comma or full stop count as a lead-in
+        lead = all(w in LEAD for w in _words(clause))
+        opens = (not b) or b[-1] in ",!.?:;" or lead
+        closes = (not after.strip()) or after.lstrip()[:1] in ",!.?:;"
+        if NEIGHBOUR.search(before):
+            use = use or "mention"
+        elif opens and (closes or lead or not b):
+            return "call"
+        else:
+            use = "mention"
+    return use
+
+
+def _neighbour_of(c, req: AddresseeRequest, text: str) -> bool:
+    """The line points at `c` by who they are with: "talking to the barkeep" and c's card says they are talking to
+    Tomas, whose alias is the barkeep."""
+    withs = [f.value for f in c.features if f.key.lower() == "with" and f.visible]
+    if not withs:
+        return False
+    for other in req.present:
+        if other.id == c.id:
+            continue
+        if any(any(_name_hit(nm, _words(w)) for nm in other.names) for w in withs):
+            for nm in other.names:
+                parts = _words(nm)
+                if parts and parts[0] == "the" and len(parts) > 1:
+                    parts = parts[1:]
+                m = re.search(r"\b" + r"\W+".join(re.escape(x) for x in parts) + r"\b", text, re.I) if parts else None
+                if m and NEIGHBOUR.search(text[:m.start()]):
+                    return True
+    return False
+
+
+def words_evidence(req: AddresseeRequest) -> Evidence:
+    line = _words(req.text)
+    benign = is_simple(req.text)
+    follows = benign and not is_opener(req.text)
+    named = [c.id for c in req.present if any(name_use(n, req.text) == "call" for n in c.names)]
+    if named:
+        return Evidence(words=frozenset(named), words_set=len(named) > 1, benign=benign, follows=follows)
+    neighbours = [c.id for c in req.present if _neighbour_of(c, req, req.text)]
+    if len(neighbours) == 1:
+        return Evidence(words=frozenset(neighbours), benign=benign, follows=follows)
+    if PAIR.search(req.text):
+        if len(req.present) == 2:
+            return Evidence(words=frozenset(req.ids), words_set=True, benign=benign, follows=follows)
+        return Evidence(words_group=True, benign=benign, follows=follows)
+    if GROUP.search(req.text):
+        return Evidence(words_group=True, benign=benign, follows=follows)
+    line_content = {w for w in line if w not in STOP}
+    scores = {}
+    for c in req.present:
+        best = 0
+        for f in c.features:
+            if not f.visible:
+                continue
+            best = max(best, sum(1 for w in _content(f.value) if any(_match(w, lw) for lw in line_content)))
+        scores[c.id] = best
+    top = max(scores.values())
+    if top == 0:
+        return Evidence(benign=benign, follows=follows)
+    return Evidence(words=frozenset(i for i, s in scores.items() if s == top), benign=benign, follows=follows)
+
+
+def rules_label(req: AddresseeRequest) -> AddresseeLabel:
+    return resolve(req, words_evidence(req))
+
+
+def answer_from_label(req: AddresseeRequest, label: AddresseeLabel) -> AddresseeAnswer:
+    """A label as an answer: certainty for a clear line, an even split among the candidates for a vague one."""
+    return AddresseeAnswer(addressed=label.targets(req.ids), unclear=1.0 if label.vague else 0.0,
+                           to_group=1.0 if label.group else 0.0)
+
+
+def rules_answer(req: AddresseeRequest) -> AddresseeAnswer:
+    return answer_from_label(req, rules_label(req))
+
+
+def match_signals(req: AddresseeRequest) -> tuple[list[tuple[float, ...]], tuple[float, float, float, float]]:
+    """The word matcher's raw signals, for the model to weigh: per person (name or alias used to call
+    them, only mentioned, best feature match as a share of three words, has the top feature match, pointed at by who
+    they are with), and for the line (group words, pair words, a simple harmless line, an opener)."""
+    line = _words(req.text)
+    line_content = {w for w in line if w not in STOP}
+    names, mentions, desc = [], [], []
+    for c in req.present:
+        uses = {name_use(n, req.text) for n in c.names}
+        names.append(1.0 if "call" in uses else 0.0)
+        mentions.append(1.0 if "mention" in uses and "call" not in uses else 0.0)
+        best = 0
+        for f in c.features:
+            if f.visible:
+                best = max(best, sum(1 for w in _content(f.value) if any(_match(w, lw) for lw in line_content)))
+        desc.append(best)
+    top = max(desc) if desc else 0
+    per = [(n, m, min(d, 3) / 3.0, 1.0 if d == top and d > 0 else 0.0, 1.0 if _neighbour_of(c, req, req.text) else 0.0)
+           for n, m, d, c in zip(names, mentions, desc, req.present)]
+    return per, (1.0 if GROUP.search(req.text) else 0.0, 1.0 if PAIR.search(req.text) else 0.0, 1.0 if is_simple(req.text) else 0.0,
+                 1.0 if is_opener(req.text) else 0.0)