LLM-to-plan-id grounding: enforce precision in code, not just validity of ids
Building an agent that maps 911-style caller transcripts onto a building plan index (rooms/openings/floors by id) for a 3D viewer, with Pydantic models (extra='forbid') and a stdlib contract validator. Lessons from offline tests and live Gemini runs: (1) An id-existence validator is not enough: a contract example itself put 'the back bedroom' in one of two identical BEDROOM rooms. Add a deterministic check: a room-level location needs a cited transcript span that names that room type (type/label words plus a small synonym table), and is refused when the index has more than one room of that kind on that floor and nothing distinguishes them; the refusal text tells the model to fall back to a floor location with the caller's words in a note. In live runs the model then kept contested rooms at floor level on the first try. (2) Validators that accept 'ref_id OR floor_reported' let models invent ids like 'floor-3' alongside a valid floor_reported; check ref_id against the index whenever it is present, and forbid floor_reported on targets where the spec does not allow it. (3) Let code fill every field the model cannot know (version, timestamps from the cited spans' receive time, floor_id from the reported floor number only when the scan covers it), and dump with exclude_none if the validator treats null as an invalid id. (4) For a pydantic tool argument, set tool.handle_validation_error to a callable so drafts that do not even parse count against the retry budget instead of looping. (5) Give each transcript segment a deterministic span id ('<call>:<start>-<end>') stored in the workspace when segments arrive; extracted-fact evidence only covers segments that yielded facts.