fix(docs): correct the Observation 'frozen' claim - the dataclass is frozen at the top level but the inner per-combatant/pair dicts are mutable copies; wording softened in the docstring and README (deep-freeze rejected: it would change the LLM contract and require touching pinned observation tests; copies are never read back by the engine, so policy mutation is already inert)

This commit is contained in:
2026-09-19 17:09:08 +02:00
parent 9459adee02
commit 2ee19d34e4
2 changed files with 10 additions and 4 deletions
+5 -2
View File
@@ -929,8 +929,11 @@ class Observation:
Built by the engine at the point of policy invocation; the snapshot is the
ONLY source of information for an ``LLMPolicy`` — it never exposes
``engine.*`` callables nor mutable references to live state. All collections
are copied (tuples/dicts) so the snapshot is frozen and JSON-serializable.
``engine.*`` callables nor mutable references to live state. All
collections are copies (tuples/dicts), never read back by the engine, so a
policy may mutate them freely without touching combat; the snapshot is
JSON-serializable (the top level is a frozen dataclass; the inner dicts are
plain mutable copies, not deep-frozen).
``combatants`` holds one dict per combatant in ``self._states`` order;
``pairs`` holds one dict per (acting combatant x each other combatant) with