tensorcode 0.1.0a1__py3-none-any.whl

tensorcode/semantics_bridge.py

@@ -0,0 +1,308 @@
+"""From a parsed sentence to the structures that make it usable.
+
+The grammar already recovers more than the projection keeps. "Anem has 12 sheep" parses
+with ``count=Entity(number, '12')`` inside the noun's features, and
+:func:`tensorcode.language.to_claims` then emits ``Anem have sheep`` — the number is
+dropped on the floor. Conditionals and causal connectives fare worse: both clauses parse,
+but they come back as two unrelated readings with the connective gone, so "if I press Send
+an announcement appears" is indistinguishable from two separate remarks.
+
+This module is the projection those structures deserve:
+
+* :func:`quantities_in` lifts numbers and their units out of the parse into
+  :class:`~tensorcode.quantity.Quantity` values;
+* :func:`link_in` recovers the connective from the surface string and pairs the readings it
+  joined, giving a conditional, a causal or a temporal link;
+* :func:`probability_in` reads adverbs of likelihood as an *uncalibrated* score, because
+  "probably" is not a calibrated number and must not pretend to be.
+
+Where it reads the surface string rather than the parse, that is a workaround for a gap in
+the grammar, not a design choice; ``needed_from_grammar`` lists them so the gaps stay
+visible instead of becoming permanent.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Iterable, Mapping, Sequence
+
+from .outcomes import Score, Unknown
+from .quantity import Quantity, Unit, normalize_unit
+from .records import Claim, Evidence, Ref, Store
+from .temporal import CONNECTIVES
+
+#: what the grammar drops and this module recovers from the surface string instead
+needed_from_grammar = (
+    "numerals are kept only as a `count` feature on the noun; to_claims discards them",
+    "conditionals return two unlinked readings; `if`/`then` is not in the parse",
+    "causal connectives (`because`, `so`, `caused ... to`) parse as a noun or a plain verb",
+    "temporal connectives (`before`, `after`, `while`) collapse the clauses into one frame",
+    "comparatives (`twice as much as`) drop below full coverage and lose the multiplier",
+    "adverbs of likelihood (`probably`) can become the predicate",
+)
+
+WORD_NUMBERS = {
+    "zero": 0, "one": 1, "two": 2, "three": 3, "four": 4, "five": 5, "six": 6, "seven": 7,
+    "eight": 8, "nine": 9, "ten": 10, "eleven": 11, "twelve": 12, "dozen": 12, "twenty": 20,
+    "thirty": 30, "forty": 40, "fifty": 50, "hundred": 100, "thousand": 1000,
+    "half": 0.5, "quarter": 0.25, "twice": 2, "double": 2, "triple": 3,
+}
+
+LIKELIHOOD = {
+    "certainly": 0.95, "definitely": 0.95, "surely": 0.9, "undoubtedly": 0.95,
+    "probably": 0.75, "likely": 0.75, "presumably": 0.7, "apparently": 0.6,
+    "maybe": 0.5, "perhaps": 0.5, "possibly": 0.4, "might": 0.4, "could": 0.4,
+    "unlikely": 0.2, "doubtfully": 0.15, "never": 0.02,
+}
+
+CAUSAL_CUES = {"because": "effect_first", "since": "effect_first", "as": "effect_first",
+               "so": "cause_first", "therefore": "cause_first", "thus": "cause_first",
+               "caused": "cause_first", "causes": "cause_first", "cause": "cause_first"}
+
+MONEY = {"$": "dollar", "€": "euro", "£": "pound_sterling"}
+_NUMBER = re.compile(r"(?P<sym>[$€£])?\s*(?P<num>\d+(?:[.,]\d+)?)\s*(?P<pct>%)?\s*(?P<unit>[a-zA-Z][a-zA-Z_-]*)?")
+
+
+@dataclass(frozen=True)
+class Mention:
+    """A quantity as it was said, with whatever the sentence attached it to."""
+
+    quantity: Quantity
+    of: str  # the noun it counted or measured, as written
+    owner: str | None = None  # the subject it was predicated of, when there is one
+    predicate: str | None = None
+    per: str | None = None  # the unit it was stated per, for rates
+
+    def describe(self) -> str:
+        head = f"{self.quantity}"
+        of = "" if normalize_unit(self.of) in str(self.quantity.unit) else f" of {self.of}"
+        return head + of + (f" ({self.owner} {self.predicate})" if self.owner else "")
+
+
+@dataclass(frozen=True)
+class Link:
+    """Two clauses and the relation the connective asserted between them."""
+
+    kind: str  # "conditional" | "causal" | "temporal"
+    relation: str  # "if_then" | "causes" | "before" | "after" | "during"
+    antecedent: Any  # a Frame (the if-side, the cause, the earlier event)
+    consequent: Any  # a Frame (the then-side, the effect, the later event)
+    cue: str
+
+    def describe(self) -> str:
+        left = getattr(self.antecedent, "describe", lambda: str(self.antecedent))()
+        right = getattr(self.consequent, "describe", lambda: str(self.consequent))()
+        return f"{self.kind}({self.relation}): {left} ⇒ {right} [“{self.cue}”]"
+
+
+# ----------------------------------------------------------------- quantities
+
+
+def _number_of(entity: Any) -> float | None:
+    text = getattr(entity, "text", None)
+    if text is None:
+        return None
+    word = str(text).strip().lower()
+    if word in WORD_NUMBERS:
+        return float(WORD_NUMBERS[word])
+    try:
+        return float(word.replace(",", ""))
+    except ValueError:
+        return None
+
+
+def quantities_in(frame: Any) -> list[Mention]:
+    """Every quantity the parse carries, with its unit and what it was said about.
+
+    Reads the ``count`` feature the grammar puts on a noun — the thing ``to_claims`` throws
+    away — and the ``per`` phrasing that makes a rate.
+    """
+    out: list[Mention] = []
+    for sub in frame.walk() if hasattr(frame, "walk") else [frame]:
+        subject = sub.roles.get("subject") if hasattr(sub, "roles") else None
+        owner = getattr(subject, "text", None)
+        for role, value in (sub.roles.items() if hasattr(sub, "roles") else ()):
+            for entity in _entities(value):
+                count = entity.features.get("count") if hasattr(entity, "features") else None
+                amount = _number_of(count) if count is not None else None
+                if amount is None:
+                    continue
+                # the noun feature carries the head word; the surface text carries a rate
+                # phrase ("coins per bushel"), which is the part that fixes the unit
+                written = str(entity.text or "")
+                noun = written if re.search(r"\bper\b|/", written) else str(entity.features.get("noun") or written)
+                head, per = _split_rate(noun)
+                unit = Unit.of(head)
+                if per:
+                    unit = unit / Unit.of(per)
+                out.append(Mention(Quantity(amount, unit), of=head, owner=owner if role != "subject" else None,
+                                   predicate=getattr(sub, "predicate", None), per=per))
+    return out
+
+
+def _entities(value: Any, depth: int = 0) -> Iterable[Any]:
+    if depth > 6:
+        return
+    if hasattr(value, "features") and hasattr(value, "text"):
+        yield value
+        for inner in value.features.values():
+            yield from _entities(inner, depth + 1)
+    elif isinstance(value, tuple):
+        for item in value:
+            yield from _entities(item, depth + 1)
+
+
+def _split_rate(noun: str) -> tuple[str, str | None]:
+    parts = re.split(r"\s+per\s+|\s*/\s*", noun.strip(), maxsplit=1)
+    if len(parts) == 2:
+        return parts[0].strip(), parts[1].strip()
+    return noun.strip(), None
+
+
+def quantities_in_text(text: str) -> list[Mention]:
+    """Quantities read straight off the string, for sentences the grammar does not cover.
+
+    Used by the arithmetic evaluation, where coverage matters more than structure. It is a
+    weaker reader than :func:`quantities_in` — it does not know what owns what.
+    """
+    out: list[Mention] = []
+    for match in _NUMBER.finditer(text):
+        raw = match.group("num").replace(",", "")
+        try:
+            amount = float(raw)
+        except ValueError:
+            continue
+        if match.group("pct"):
+            out.append(Mention(Quantity(amount, Unit.of("percent")), of="percent"))
+            continue
+        symbol, word = match.group("sym"), match.group("unit")
+        if symbol:
+            out.append(Mention(Quantity(amount, Unit.of(MONEY[symbol])), of=MONEY[symbol]))
+            continue
+        noun = normalize_unit(word) if word else "item"
+        out.append(Mention(Quantity(amount, Unit.of(noun)), of=noun))
+    return out
+
+
+# ---------------------------------------------------------------------- links
+
+
+def _overlap(frame: Any, span: str) -> int:
+    """How much of a frame's wording appears in a stretch of the sentence."""
+    words = set(re.findall(r"[a-z0-9]+", span.lower()))
+    score = 0
+    predicate = str(getattr(frame, "predicate", "") or "").lower()
+    if predicate and any(w.startswith(predicate[:4]) for w in words if len(predicate) >= 4):
+        score += 2
+    for entity in getattr(frame, "entities", lambda: ())():
+        text = str(getattr(entity, "text", "")).lower()
+        if text and text in words:
+            score += 1
+    return score
+
+
+def link_in(text: str, meanings: Sequence[Any]) -> Link | Unknown:
+    """The relation a connective asserted, and which reading sits on each side.
+
+    The connective comes from the string because the grammar drops it. Which clause is
+    which comes from matching each reading's wording against the two halves of the
+    sentence, so the direction of "because" is read, not assumed.
+    """
+    frames = [m for m in meanings if hasattr(m, "predicate")]
+    if len(frames) < 2:
+        return Unknown("one_reading", "a link needs two clauses; the parse gave fewer")
+    lowered = text.lower()
+
+    for cue in ("if",):
+        match = re.search(rf"\b{cue}\b", lowered)
+        if match:
+            left, right = _sides(text, match.end(), r"\bthen\b")
+            a, b = _assign(frames, left, right)
+            return Link("conditional", "if_then", a, b, cue)
+
+    for cue, orientation in CAUSAL_CUES.items():
+        match = re.search(rf"\b{cue}\b", lowered)
+        if match:
+            before_cue, after_cue = text[: match.start()], text[match.end():]
+            first, second = _assign(frames, before_cue, after_cue)
+            cause, effect = (second, first) if orientation == "effect_first" else (first, second)
+            return Link("causal", "causes", cause, effect, cue)
+
+    for cue in CONNECTIVES:
+        match = re.search(rf"\b{cue}\b", lowered)
+        if match:
+            relation = CONNECTIVES[cue]
+            before_cue, after_cue = text[: match.start()], text[match.end():]
+            first, second = _assign(frames, before_cue, after_cue)
+            if relation == "before":
+                return Link("temporal", "before", first, second, cue)
+            if relation == "after":
+                return Link("temporal", "before", second, first, cue)
+            return Link("temporal", "during", first, second, cue)
+    return Unknown("no_connective", "no linking word found in the sentence")
+
+
+def _sides(text: str, start: int, closer: str) -> tuple[str, str]:
+    rest = text[start:]
+    match = re.search(closer, rest.lower())
+    return (rest[: match.start()], rest[match.end():]) if match else (rest, text[:start])
+
+
+def _assign(frames: Sequence[Any], left: str, right: str) -> tuple[Any, Any]:
+    """Put the reading that matches the left span on the left, the other on the right."""
+    best_left = max(frames, key=lambda f: (_overlap(f, left), -_overlap(f, right)))
+    rest = [f for f in frames if f is not best_left] or list(frames)
+    best_right = max(rest, key=lambda f: _overlap(f, right))
+    return best_left, best_right
+
+
+# ---------------------------------------------------------------- likelihood
+
+
+def probability_in(text: str) -> Score | Unknown:
+    """An adverb of likelihood as an uncalibrated score, never a calibrated probability."""
+    for word in re.findall(r"[a-z]+", text.lower()):
+        if word in LIKELIHOOD:
+            return Score(LIKELIHOOD[word], "uncalibrated", basis="")
+    return Unknown("no_likelihood_adverb", "nothing in the sentence states how likely it is")
+
+
+# -------------------------------------------------------------------- claims
+
+
+def tell_mentions(mind: Store, mentions: Iterable[Mention], *, source: Ref, subject: Ref | None = None,
+                  observed_at: datetime | None = None, method: str = "bridge:quantity") -> list[Claim]:
+    """Record quantities as claims, keeping each number with its unit."""
+    at = observed_at or datetime.now(timezone.utc)
+    out: list[Claim] = []
+    for mention in mentions:
+        owner = subject or (Ref(f"entity:{mention.owner}") if mention.owner else Ref(f"entity:{mention.of}"))
+        predicate = mention.predicate or "amount"
+        claim = Claim(owner, predicate, mention.quantity)
+        mind.tell(claim, Evidence(source=source, observed_at=at, method=method))
+        out.append(claim)
+    return out
+
+
+def tell_link(mind: Store, link: Link, *, source: Ref, observed_at: datetime | None = None) -> Ref:
+    """Record a link between clauses as a claim about the relation itself.
+
+    A conditional is *not* asserted as its consequent: "if I press Send an announcement
+    appears" must never enter the world as "an announcement appears".
+    """
+    from .language.semantics import _mint  # the same event identity the projection uses
+
+    at = observed_at or datetime.now(timezone.utc)
+    evidence = Evidence(source=source, observed_at=at, method=f"bridge:{link.kind}")
+    antecedent, consequent = _mint(link.antecedent), _mint(link.consequent)
+    ref = Ref(f"link:{antecedent.id.split(':')[1]}-{consequent.id.split(':')[1]}")
+    mind.tell(Claim(ref, "is_a", link.kind), evidence)
+    mind.tell(Claim(ref, "relation", link.relation), evidence)
+    mind.tell(Claim(ref, "antecedent", antecedent), evidence)
+    mind.tell(Claim(ref, "consequent", consequent), evidence)
+    mind.tell(Claim(ref, "cue", link.cue), evidence)
+    mind.tell(Claim(antecedent, "is_a", getattr(link.antecedent, "predicate", "event")), evidence)
+    mind.tell(Claim(consequent, "is_a", getattr(link.consequent, "predicate", "event")), evidence)
+    return ref

tensorcode/social.py

@@ -0,0 +1,380 @@
+"""Social cognition: what two minds share, what the other one believes, and when to ask.
+
+Four structures, each answering a question the flat claim store cannot:
+
+* :class:`CommonGround` — what is *mutually manifest*: I said it, you said it, or we both
+  saw it. A reply can then mark what is new and lean on what is already shared, instead of
+  re-explaining. Grounding is itself claims, so ``explain`` reaches it.
+* :class:`OtherMind` — what I take *you* to believe, including where I think you are wrong.
+  A request presupposes things ("delete the report" presupposes a report); a presupposition
+  I can check and find false is a belief worth correcting, not just a fact to report.
+* :func:`ask_or_act` — clarification as a decision, not a reflex: ask only when the expected
+  cost of acting on the wrong reading exceeds the cost of a question. Both failure modes are
+  represented, because an assistant that always asks is as useless as one that never does.
+* :func:`indirect_reading` — intention inference gated by *affordance*. A statement or
+  question may imply a request, but only if its object is something I could act on: "I can't
+  find my invoice" is a request to look, "I can't find my keys" is not, and the difference is
+  not in the grammar.
+
+Nothing here calls a model. Everything is deterministic and carries provenance.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import math
+from collections.abc import Callable, Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+from .cognition import Fragment, Thought, integrate
+from .outcomes import Score, Unknown
+from .records import Claim, Ref, Store
+
+AGENT = Ref("agent:self")
+OTHER = Ref("person:user")
+
+#: how a claim came to be shared
+I_SAID = "i_said"
+YOU_SAID = "you_said"
+BOTH_SAW = "both_saw"
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _key(about: str, how: str) -> Ref:
+    return Ref(f"ground:{hashlib.sha256(f'{about}|{how}'.encode()).hexdigest()[:12]}")
+
+
+@dataclass(frozen=True)
+class Shared:
+    """One piece of common ground: what, how it became shared, when, how often mentioned."""
+
+    about: str  # the claim id it grounds
+    how: str  # I_SAID | YOU_SAID | BOTH_SAW
+    turn: int
+    mentions: int
+
+    @property
+    def mine(self) -> bool:
+        return self.how == I_SAID
+
+
+class CommonGround:
+    """The shared state between two minds, kept as claims so it can be explained.
+
+    Mutual manifestness is not symmetry of storage: a fact I hold is not shared until it was
+    said or jointly seen. ``status`` answers "does the other mind already have this, and how",
+    which is what lets a reply say "as I mentioned" rather than repeating itself.
+    """
+
+    def __init__(self, store: Store, *, me: Ref = AGENT, other: Ref = OTHER) -> None:
+        self.store, self.me, self.other = store, me, other
+
+    def add(self, about: str, how: str, turn: int, *, source: str | None = None) -> Thought:
+        """Record that a claim (by id) became shared, or was mentioned again."""
+        ref = _key(about, how)
+        before = self.mentions(about, how)
+        claims = [
+            (Claim(ref, "grounds", about), None),
+            (Claim(ref, "shared_via", how), None),
+            (Claim(ref, "mentioned", before + 1), None),
+            (Claim(ref, "turn", turn), None),
+        ]
+        if before:  # a repeat supersedes the old count rather than piling up
+            self.store.forget([r.id for r in self.store.claims(ref, "mentioned")])
+            self.store.forget([r.id for r in self.store.claims(ref, "turn")])
+        frag = Fragment(Ref(source or f"utterance:{turn}"), tuple(claims), method="grounding", observed_at=_now())
+        return integrate(self.store, frag)
+
+    def mentions(self, about: str, how: str | None = None) -> int:
+        hows = [how] if how else [I_SAID, YOU_SAID, BOTH_SAW]
+        total = 0
+        for h in hows:
+            found = self.store.claims(_key(about, h), "mentioned")
+            total += max((int(r.claim.object) for r in found), default=0)
+        return total
+
+    def status(self, about: str) -> Shared | None:
+        """How this claim is shared, preferring the strongest ground (jointly seen > said)."""
+        for how in (BOTH_SAW, YOU_SAID, I_SAID):
+            ref = _key(about, how)
+            said = self.store.claims(ref, "mentioned")
+            if said:
+                turn = max((int(r.claim.object) for r in self.store.claims(ref, "turn")), default=0)
+                return Shared(about, how, turn, max(int(r.claim.object) for r in said))
+        return None
+
+    def is_shared(self, about: str) -> bool:
+        return self.status(about) is not None
+
+    def new_to_other(self, about: str) -> bool:
+        """True when the other mind has not been given this, so a reply should state it plainly."""
+        return not self.is_shared(about)
+
+    def again(self, about: str) -> bool:
+        """True when I am about to say something I have already said: worth marking, not repeating.
+
+        Asks my own ground specifically — that you told me a thing is not a reason for me to
+        say "as I mentioned", and the strongest ground is not the relevant one here.
+        """
+        return self.mentions(about, I_SAID) >= 1
+
+    def told_me(self, turn_from: int = 0) -> list[Shared]:
+        """What the other mind told me, oldest first — the answer to "what did I tell you"."""
+        out = []
+        for rec in self.store.claims(predicate="shared_via", object=YOU_SAID):
+            about = next((r.claim.object for r in self.store.claims(rec.claim.subject, "grounds")), None)
+            st = self.status(str(about)) if about else None
+            if st and st.turn >= turn_from:
+                out.append(st)
+        return sorted(out, key=lambda s: s.turn)
+
+
+# --------------------------------------------------------------- other minds
+
+
+@dataclass(frozen=True)
+class Presupposition:
+    """Something a request takes for granted, and can therefore be wrong about."""
+
+    kind: str  # "exists" | "location" | "state" | "capability"
+    subject: str
+    detail: str = ""
+
+    def __str__(self) -> str:
+        return f"{self.kind}({self.subject}{', ' + self.detail if self.detail else ''})"
+
+
+@dataclass(frozen=True)
+class FalseBelief:
+    """A presupposition I checked and found false, with what to say instead."""
+
+    presupposition: Presupposition
+    truth: str
+    near: tuple[str, ...] = ()
+
+    def correction(self) -> str:
+        """A correction of the belief, not a bare report of absence."""
+        base = f"there's no {self.presupposition.subject}"
+        if self.presupposition.detail:
+            base += f" {self.presupposition.detail}"
+        if self.near:
+            joined = self.near[0] if len(self.near) == 1 else ", ".join(self.near[:-1]) + f" or {self.near[-1]}"
+            return f"{base} — did you mean {joined}?"
+        return f"{base}; {self.truth}" if self.truth else base
+
+
+class OtherMind:
+    """What I take the other mind to believe, see, and take for granted.
+
+    Two asymmetries matter. What they told me, they believe (until they say otherwise). What
+    is on a screen we both look at, they can see — but what sits inside a folder they never
+    opened, they cannot, so it is not shared context and a reply should not assume it.
+    """
+
+    def __init__(self, store: Store, *, who: Ref = OTHER, visible: Callable[[str], bool] | None = None) -> None:
+        self.store, self.who = store, who
+        self._visible = visible or (lambda _thing: False)
+
+    def believes(self, predicate: str) -> object | None:
+        found = self.store.claims(self.who, predicate)
+        return found[0].claim.object if found else None
+
+    def beliefs(self) -> dict[str, object]:
+        return {r.claim.predicate: r.claim.object for r in self.store.claims(self.who)}
+
+    def can_see(self, thing: str) -> bool:
+        return self._visible(thing)
+
+    def presupposes(self, slots: Mapping[str, object], rules: Mapping[str, str]) -> list[Presupposition]:
+        """What a request takes for granted, given which slots presuppose what.
+
+        ``rules`` maps a slot name to a presupposition kind, so the domain decides: a
+        ``target`` slot presupposes existence, a ``place`` slot presupposes a location.
+        """
+        out = []
+        for slot, kind in rules.items():
+            value = slots.get(slot)
+            if isinstance(value, str) and value and not value.startswith("@"):
+                detail = ""
+                if kind == "exists" and isinstance(slots.get("place"), str) and str(slots["place"]).startswith("~"):
+                    detail = f"in {slots['place']}"
+                out.append(Presupposition(kind, value, detail))
+        return out
+
+    def check(self, presupposition: Presupposition, *, exists: Callable[[str], bool],
+              neighbours: Callable[[str], Sequence[str]] = lambda _s: ()) -> FalseBelief | None:
+        """A presupposition I can check: return a false belief when it does not hold."""
+        if presupposition.kind not in ("exists", "location"):
+            return None
+        if exists(presupposition.subject):
+            return None
+        near = tuple(neighbours(presupposition.subject))[:3]
+        return FalseBelief(presupposition, truth="", near=near)
+
+
+def near_names(name: str, candidates: Iterable[str], *, limit: int = 3) -> list[str]:
+    """Names close enough that the other mind plausibly meant one of them.
+
+    Cognitively this is why a correction beats a bare "not found": a wrong name is usually a
+    near miss, and naming the near miss repairs the belief instead of ending the exchange.
+    """
+    target = name.lower()
+    stem = target.rsplit(".", 1)[0]
+    scored: list[tuple[float, str]] = []
+    for cand in candidates:
+        c = cand.lower().rstrip("/")
+        if c == target:
+            continue
+        c_stem = c.rsplit(".", 1)[0]
+        score = max(_ratio(target, c), _ratio(stem, c_stem))
+        if stem and (stem in c_stem or c_stem in stem):
+            score = max(score, 0.75)
+        if score >= 0.6:
+            scored.append((score, cand))
+    scored.sort(key=lambda s: (-s[0], s[1]))
+    return [c for _, c in scored[:limit]]
+
+
+def _ratio(a: str, b: str) -> float:
+    """Similarity by edit distance, normalized — small and dependency-free on purpose."""
+    if not a or not b:
+        return 0.0
+    prev = list(range(len(b) + 1))
+    for i, ca in enumerate(a, 1):
+        cur = [i]
+        for j, cb in enumerate(b, 1):
+            cur.append(min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (ca != cb)))
+        prev = cur
+    return 1.0 - prev[-1] / max(len(a), len(b))
+
+
+# ------------------------------------------------------------- clarification
+
+
+@dataclass(frozen=True)
+class Reading:
+    """One way to take an utterance, with how likely it is and what acting on it would cost."""
+
+    name: str
+    probability: float
+    description: str = ""
+    cost_if_wrong: float = 1.0
+
+
+@dataclass(frozen=True)
+class Clarification:
+    """A question worth asking, with the options it puts to the other mind."""
+
+    question: str
+    options: tuple[str, ...]
+    expected_gain: float
+    about: str = ""
+
+
+@dataclass(frozen=True)
+class Decision:
+    """Ask, act, or admit — and why, in numbers a reader can check."""
+
+    choose: str  # "act" | "ask" | "admit"
+    reading: Reading | None = None
+    clarification: Clarification | None = None
+    expected_gain: float = 0.0
+    reason: str = ""
+
+
+def uncertainty(readings: Sequence[Reading]) -> float:
+    """Entropy over readings, in bits: how undetermined the goal is."""
+    total = sum(max(r.probability, 0.0) for r in readings) or 1.0
+    bits = 0.0
+    for r in readings:
+        p = max(r.probability, 0.0) / total
+        if p > 0:
+            bits -= p * math.log2(p)
+    return bits
+
+
+def ask_or_act(readings: Sequence[Reading], *, ask_cost: float = 0.25, confident: float = 0.8,
+               question: str | None = None, about: str = "") -> Decision:
+    """Decide between acting on the best reading, asking, and admitting the goal is unclear.
+
+    The two failure modes are both priced: acting on the wrong reading costs ``cost_if_wrong``,
+    asking costs ``ask_cost`` (a turn of the other mind's patience). Asking wins only when the
+    expected cost it avoids exceeds that, which is what keeps a clarifying assistant from
+    becoming a tiresome one.
+    """
+    live = [r for r in readings if r.probability > 0]
+    if not live:
+        return Decision("admit", reason="no reading at all")
+    best = max(live, key=lambda r: r.probability)
+    total = sum(r.probability for r in live) or 1.0
+    p_best = best.probability / total
+    if p_best >= confident or len(live) == 1:
+        return Decision("act", reading=best, expected_gain=0.0, reason=f"one reading dominates (p={p_best:.2f})")
+    expected_loss = sum((r.probability / total) * r.cost_if_wrong for r in live if r is not best)
+    gain = expected_loss - ask_cost
+    if gain <= 0:
+        return Decision("act", reading=best, expected_gain=gain,
+                        reason=f"asking costs more than the risk ({expected_loss:.2f} vs {ask_cost:.2f})")
+    options = tuple(r.description or r.name for r in sorted(live, key=lambda r: -r.probability))
+    text = question or "Which did you mean?"
+    return Decision("ask", reading=best,
+                    clarification=Clarification(text, options, gain, about),
+                    expected_gain=gain, reason=f"{uncertainty(live):.2f} bits undetermined, {len(live)} readings")
+
+
+# ------------------------------------------------------ indirect and implied
+
+
+@dataclass(frozen=True)
+class Indirect:
+    """A request recovered from an utterance whose surface form is something else."""
+
+    surface: str  # "statement" | "question" | "complaint" | "wish"
+    act: str
+    slots: dict
+    strength: float
+    object_word: str = ""
+
+    def score(self) -> Score:
+        return Score(self.strength, "implicature", basis=f"{self.surface} form implying {self.act}")
+
+
+@dataclass(frozen=True)
+class Implication:
+    """A surface form that may imply an act, and what it needs to be believed."""
+
+    pattern: str  # a regex with an ``obj`` group where the thing acted on appears
+    surface: str
+    act: str
+    strength: float
+    slot: str = "target"
+
+
+def indirect_reading(text: str, implications: Sequence[Implication], *,
+                     in_domain: Callable[[str], bool], floor: float = 0.5) -> Indirect | Unknown:
+    """Read an indirect request, but only where the object is something I could act on.
+
+    The gate is the point. Form alone cannot tell "I can't find my invoice" (a request to
+    look) from "I can't find my keys" (not my business); what separates them is whether the
+    object falls inside what I can act on at all. So intention inference is constrained by
+    affordance, and an utterance about the world beyond my reach stays a remark.
+    """
+    import re
+
+    for imp in implications:
+        m = re.search(imp.pattern, text, re.I)
+        if not m:
+            continue
+        obj = (m.groupdict().get("obj") or "").strip(" .!?\"'")
+        if not obj:
+            continue
+        if not in_domain(obj):
+            return Unknown("not_my_domain", f"“{obj}” is not something I can act on, so I read that as a remark")
+        if imp.strength < floor:
+            continue
+        return Indirect(imp.surface, imp.act, {imp.slot: obj}, imp.strength, obj)
+    return Unknown("no_implicature", "no indirect reading fits this utterance")