tensorcode 0.1.0a1__py3-none-any.whl

tensorcode/expectation.py

@@ -0,0 +1,270 @@
+"""Expectations, and the prediction errors that follow from them.
+
+A modality feature on a parsed frame ("an announcement *should* appear") is inert: it
+records that someone said "should" and predicts nothing. An expectation here is a
+commitment — a cue, what should then hold, and how sure — which means it can be *wrong*,
+and being wrong is the useful part:
+
+* :func:`check` compares what was expected against what was observed and, on a mismatch,
+  writes a :class:`Violation` claim naming both sides and their provenance;
+* a violation is a claim like any other, so attention (``awareness``) can be seeded from
+  it and rules can fire on it — surprise becomes a first-class input rather than a log line;
+* :class:`Predictor` learns the probability from its own record of hits and misses, so the
+  number on an expectation is a frequency with a named basis rather than a hand-set prior.
+
+Nothing here guesses: an expectation with too little evidence reports
+:class:`~tensorcode.outcomes.Unknown` rather than a made-up probability.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from math import exp, log, log2
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Iterable, Mapping, Sequence
+
+from .outcomes import Score, Unknown, Verdict
+from .records import Claim, Evidence, Ref, Store
+
+MIN_TRIALS = 3  # below this, a frequency is not a probability worth reporting
+
+
+def _digest(payload: Any) -> str:
+    return hashlib.sha256(json.dumps(payload, sort_keys=True, default=str).encode()).hexdigest()[:12]
+
+
+@dataclass(frozen=True)
+class Expectation:
+    """If ``cue`` happens, ``predicted`` should hold afterwards, with probability ``p``."""
+
+    cue: str  # a description of the triggering act or event, e.g. "click:Send message"
+    predicted: tuple[tuple[str, Any], ...]  # (aspect, value) pairs that should be observed
+    p: Score | None = None
+    scope: Ref | None = None
+    source: str = "stated"  # "stated" (someone said so) | "learned" (from its own record)
+
+    @property
+    def ref(self) -> Ref:
+        return Ref(f"expectation:{_digest([self.cue, list(self.predicted), self.source])}")
+
+    def describe(self) -> str:
+        body = ", ".join(f"{a}={v!r}" for a, v in self.predicted)
+        odds = f" p={self.p.value:.2f}" if self.p else ""
+        return f"after {self.cue}: {body}{odds}"
+
+
+@dataclass(frozen=True)
+class Violation:
+    """A prediction error: what was expected, what happened, and how surprising it was."""
+
+    expectation: Expectation
+    aspect: str
+    expected: Any
+    observed: Any
+    surprise: float  # -log2(p assigned to what actually happened), 0 when unsurprising
+
+    @property
+    def ref(self) -> Ref:
+        return Ref(f"violation:{_digest([self.expectation.ref.id, self.aspect, str(self.expected), str(self.observed)])}")
+
+    def describe(self) -> str:
+        return f"{self.aspect}: expected {self.expected!r}, observed {self.observed!r} (surprise {self.surprise:.2f} bits)"
+
+
+def expect(mind: Store, expectation: Expectation, *, source: Ref, observed_at: datetime | None = None,
+           method: str = "expectation") -> Ref:
+    """Record an expectation as claims, so it can be inspected, cited and retracted."""
+    at = observed_at or datetime.now(timezone.utc)
+    ref = expectation.ref
+    evidence = Evidence(source=source, observed_at=at, method=method, confidence=expectation.p)
+    mind.tell(Claim(ref, "is_a", "expectation", scope=expectation.scope), evidence)
+    mind.tell(Claim(ref, "cue", expectation.cue, scope=expectation.scope), evidence)
+    mind.tell(Claim(ref, "held_because", expectation.source, scope=expectation.scope), evidence)
+    for aspect, value in expectation.predicted:
+        mind.tell(Claim(ref, f"predicts:{aspect}", value, scope=expectation.scope), evidence)
+    return ref
+
+
+def check(mind: Store, expectation: Expectation, observed: Mapping[str, Any], *, source: Ref,
+          observed_at: datetime | None = None) -> tuple[Verdict, tuple[Violation, ...]]:
+    """Compare an expectation against what was observed; record any prediction error.
+
+    Returns a verdict and the violations. An aspect the observation does not mention is
+    ``unknown``, not a violation: unseen is not disconfirmed.
+    """
+    at = observed_at or datetime.now(timezone.utc)
+    violations: list[Violation] = []
+    unseen: list[str] = []
+    for aspect, value in expectation.predicted:
+        if aspect not in observed:
+            unseen.append(aspect)
+            continue
+        got = observed[aspect]
+        if got != value:
+            p = expectation.p.value if expectation.p else 0.5
+            surprise = -log2(max(1e-6, 1.0 - p))
+            violations.append(Violation(expectation, aspect, value, got, surprise))
+    for violation in violations:
+        mind.tell(
+            Claim(violation.ref, "is_a", "violation"),
+            Evidence(source=source, observed_at=at, method="prediction-error", derived_from=()),
+        )
+        for predicate, value in (("of", expectation.ref), ("aspect", violation.aspect),
+                                 ("expected", violation.expected), ("observed", violation.observed),
+                                 ("surprise", violation.surprise)):
+            mind.tell(Claim(violation.ref, predicate, value), Evidence(source=source, observed_at=at, method="prediction-error"))
+    if violations:
+        return Verdict("fails", tuple(v.describe() for v in violations), (expectation.ref,)), tuple(violations)
+    if unseen and len(unseen) == len(expectation.predicted):
+        return Verdict("unknown", (f"nothing observed about {', '.join(unseen)}",), (expectation.ref,)), ()
+    return Verdict("holds", (expectation.describe(),), (expectation.ref,)), ()
+
+
+# ------------------------------------------------------------------ learning
+
+
+@dataclass
+class Predictor:
+    """Learns what follows a cue from its own hits and misses.
+
+    The probability it reports is a smoothed frequency over trials it actually saw, with
+    the basis naming the record it came from. Below :data:`MIN_TRIALS` it reports
+    ``Unknown`` instead of a number, because three coin flips are not a calibration.
+    """
+
+    name: str = "expectation/observed"
+    counts: dict[tuple[str, str], Counter] = field(default_factory=lambda: defaultdict(Counter))
+    trials: dict[tuple[str, str], int] = field(default_factory=lambda: defaultdict(int))
+
+    def observe(self, cue: str, aspect: str, value: Any) -> None:
+        key = (cue, aspect)
+        self.counts[key][_hashable(value)] += 1
+        self.trials[key] += 1
+
+    def predict(self, cue: str, aspect: str) -> tuple[Any, Score] | Unknown:
+        """The most frequent outcome for this cue and aspect, with its frequency."""
+        key = (cue, aspect)
+        trials = self.trials.get(key, 0)
+        if trials < MIN_TRIALS:
+            return Unknown("too_few_trials", f"{trials} observations of {aspect} after {cue}")
+        value, hits = self.counts[key].most_common(1)[0]
+        # Laplace over the outcomes seen *and one that has not been*: with a single observed
+        # outcome the seen-only denominator cancels and twenty hits would report certainty,
+        # which is the failure this smoothing exists to prevent.
+        outcomes = max(2, len(self.counts[key]))
+        p = (hits + 1) / (trials + outcomes)
+        return value, Score(p, "probability", basis=f"{self.name}:{cue}/{aspect}@{trials}")
+
+    def expectation(self, cue: str, aspects: Iterable[str]) -> Expectation | Unknown:
+        """An expectation over several aspects, at the weakest of their probabilities."""
+        predicted: list[tuple[str, Any]] = []
+        weakest: Score | None = None
+        for aspect in aspects:
+            got = self.predict(cue, aspect)
+            if isinstance(got, Unknown):
+                return got
+            value, score = got
+            predicted.append((aspect, value))
+            if weakest is None or score.value < weakest.value:
+                weakest = score
+        if not predicted:
+            return Unknown("nothing_to_predict", cue)
+        return Expectation(cue, tuple(predicted), weakest, source="learned")
+
+
+def _hashable(value: Any) -> Any:
+    if isinstance(value, (list, tuple)):
+        return tuple(_hashable(v) for v in value)
+    if isinstance(value, dict):
+        return tuple(sorted((k, _hashable(v)) for k, v in value.items()))
+    if isinstance(value, set):
+        return tuple(sorted(_hashable(v) for v in value))
+    return value
+
+
+# -------------------------------------------------------------- probability
+
+
+def combine(scores: Sequence[Score], *, assume: str = "independent") -> Score | Unknown:
+    """Pool several probabilities about one proposition, naming the assumption used.
+
+    Independent evidence pools in log-odds. That assumption is usually false — two sources
+    reading the same notice are one source — so it is written into the basis rather than
+    left implicit, and a caller that cannot justify it should not use the number.
+
+    Refuses when any input is not a calibrated probability: a similarity and a vote share do
+    not pool into a probability, and pretending they do is how a confident wrong number gets
+    made.
+    """
+    scores = list(scores)
+    if not scores:
+        return Unknown("no_evidence", "nothing to combine")
+    wrong = [s.kind for s in scores if s.kind != "probability"]
+    if wrong:
+        return Unknown("not_probabilities", f"cannot pool {', '.join(sorted(set(wrong)))} into a probability")
+    if assume != "independent":
+        return Unknown("unsupported_assumption", f"only independent pooling is implemented, not {assume!r}")
+    total = 0.0
+    for score in scores:
+        p = min(max(score.value, 1e-6), 1 - 1e-6)
+        total += log(p / (1 - p))
+    pooled = 1 / (1 + exp(-total))
+    bases = "+".join(sorted({s.basis for s in scores if s.basis}))
+    return Score(pooled, "probability", basis=f"pooled(independent,n={len(scores)}):{bases}"[:200])
+
+
+def disagreement(scores: Sequence[Score]) -> float:
+    """How far apart the evidence is, as the spread of its probabilities.
+
+    Pooling hides this: two sources at 0.1 and 0.9 pool to 0.5, and so do two at 0.5. A
+    caller that needs to know whether its belief is settled or contested needs the spread as
+    well as the pooled number.
+    """
+    values = [s.value for s in scores]
+    return (max(values) - min(values)) if values else 0.0
+
+
+@dataclass(frozen=True)
+class Calibration:
+    """How well stated probabilities matched what happened."""
+
+    bins: tuple[tuple[float, float, int], ...]  # (stated, observed, n) per occupied bin
+    ece: float  # expected calibration error: average gap, weighted by how often each bin was used
+    n: int
+
+    def describe(self) -> str:
+        rows = ", ".join(f"{stated:.2f}→{observed:.2f}({count})" for stated, observed, count in self.bins)
+        return f"ECE {self.ece:.3f} over {self.n}: {rows}"
+
+
+def calibration(pairs: Sequence[tuple[float, bool]], *, bins: int = 10) -> Calibration | Unknown:
+    """Bin stated probabilities against observed frequencies."""
+    if not pairs:
+        return Unknown("no_predictions", "nothing to calibrate")
+    buckets: dict[int, list[tuple[float, bool]]] = defaultdict(list)
+    for p, hit in pairs:
+        buckets[min(bins - 1, int(p * bins))].append((p, hit))
+    rows: list[tuple[float, float, int]] = []
+    error = 0.0
+    for index in sorted(buckets):
+        group = buckets[index]
+        stated = sum(p for p, _ in group) / len(group)
+        observed = sum(1 for _, hit in group if hit) / len(group)
+        rows.append((round(stated, 4), round(observed, 4), len(group)))
+        error += len(group) * abs(stated - observed)
+    return Calibration(tuple(rows), round(error / len(pairs), 4), len(pairs))
+
+
+def surprises(mind: Store, *, since: datetime | None = None, least: float = 0.0) -> list[Claim]:
+    """Violations on record, most surprising first — what attention should be drawn to."""
+    out: list[tuple[float, Claim]] = []
+    for record in mind.claims(predicate="surprise"):
+        if since is not None and all(e.observed_at < since for e in record.evidence):
+            continue
+        value = record.claim.object
+        if isinstance(value, (int, float)) and value >= least:
+            out.append((float(value), record.claim))
+    return [claim for _, claim in sorted(out, key=lambda pair: -pair[0])]

tensorcode/frames.py

@@ -0,0 +1,232 @@
+"""Three orientations over the same claims: what it is, where it is, how it was known.
+
+The store indexes claims by subject, predicate and scope — all *semantic*. That is not
+enough for a mind that has a body: "what is next to the pointer" and "what did I see with
+my eyes rather than read in a tree" are ordinary questions, and answering them by scanning
+everything is what makes them feel impossible.
+
+    semantic   (subject, predicate)                what it is about
+    spatial    (window, region, box)               where it is, relative to the screen and the pointer
+    modality   (pixels, structure, text, hearsay)  how it came to be known
+
+The same claim sits in all three. That is the point: awareness spreading in one frame pulls
+in neighbours from the others (``Frames.links`` feeds ``awareness.Awareness``), which is
+what makes nucleation cross modalities. Where two modalities disagree about the same thing,
+``disagreements`` reports it rather than letting the stronger index win silently.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Any, Callable, Iterable
+
+from .records import ClaimRecord, Ref, Store
+
+#: how a claim came to be known, from its evidence's method and source
+MODALITIES = ("pixels", "structure", "text", "hearsay", "inference", "other")
+
+_MODALITY_PATTERNS = (
+    ("pixels", re.compile(r"ocr|pixel|vision|screenshot|segment", re.I)),
+    ("structure", re.compile(r"dom|scene|atspi|accessib|ax\b|uia|tree", re.I)),
+    ("hearsay", re.compile(r"hearsay|heard|told|said|rumou?r", re.I)),
+    ("inference", re.compile(r"derive|rule|infer", re.I)),
+    ("text", re.compile(r"parse|text|read|grammar|utterance|note", re.I)),
+)
+
+
+def modality_of(rec: ClaimRecord) -> tuple[str, ...]:
+    """Which modalities this claim rests on, in a fixed order (a claim may have several)."""
+    found: set[str] = set()
+    for e in rec.evidence:
+        blob = f"{e.method or ''} {e.source.id}"
+        for name, pattern in _MODALITY_PATTERNS:
+            if pattern.search(blob):
+                found.add(name)
+                break
+        else:
+            found.add("other")
+    return tuple(m for m in MODALITIES if m in found)
+
+
+@dataclass(frozen=True)
+class Place:
+    """Where something is, in screen terms. ``None`` fields are simply unknown."""
+
+    window: str | None = None
+    region: str | None = None
+    box: tuple[int, int, int, int] | None = None  # x, y, w, h
+
+    @property
+    def center(self) -> tuple[float, float] | None:
+        if self.box is None:
+            return None
+        x, y, w, h = self.box
+        return (x + w / 2, y + h / 2)
+
+    def distance(self, other: Place | tuple[float, float]) -> float | None:
+        """Pixels between centres, or ``None`` when either side has no box."""
+        here = self.center
+        there = other if isinstance(other, tuple) else other.center
+        if here is None or there is None:
+            return None
+        return ((here[0] - there[0]) ** 2 + (here[1] - there[1]) ** 2) ** 0.5
+
+    def near(self, other: Place | tuple[float, float], slack: float = 120.0) -> bool:
+        d = self.distance(other)
+        return d is not None and d <= slack
+
+    @property
+    def known(self) -> bool:
+        return self.window is not None or self.region is not None or self.box is not None
+
+
+def place_of(rec: ClaimRecord, mind: Store) -> Place:
+    """Read a place off the claim's subject: its entity payload's geometry, or ``in``/``at`` claims."""
+    window = region = box = None
+    payload = mind.entities.get(rec.claim.subject)
+    if payload is not None:
+        raw = getattr(payload, "box", None)
+        if isinstance(raw, (list, tuple)) and len(raw) == 4 and all(isinstance(v, (int, float)) for v in raw):
+            box = tuple(int(v) for v in raw)  # type: ignore[assignment]
+        section = getattr(payload, "section", None)
+        if isinstance(section, str) and section:
+            window = section
+    if rec.claim.predicate in ("in", "in_table") and isinstance(rec.claim.object, str):
+        region = rec.claim.object
+    if rec.claim.predicate == "at" and isinstance(rec.claim.object, (list, tuple)) and len(rec.claim.object) == 4:
+        box = tuple(int(v) for v in rec.claim.object)  # type: ignore[assignment]
+    return Place(window, region, box)
+
+
+@dataclass(frozen=True)
+class Binding:
+    """One claim, seen from all three frames at once."""
+
+    claim_id: str
+    subject: Ref
+    predicate: str
+    place: Place
+    modality: tuple[str, ...]
+
+
+@dataclass(frozen=True)
+class Disagreement:
+    """Two live claims about the same thing, from different modalities, with different objects."""
+
+    subject: Ref
+    predicate: str
+    readings: tuple[tuple[str, Any, tuple[str, ...]], ...]  # (claim id, object, modalities)
+
+    def describe(self) -> str:
+        parts = ", ".join(f"{obj!r} via {'+'.join(mods) or 'unknown'}" for _, obj, mods in self.readings)
+        return f"{self.subject} {self.predicate}: {parts}"
+
+
+class Frames:
+    """Three indexes over one mind, rebuilt when the store's revision moves."""
+
+    def __init__(self, mind: Store, *, modality: Callable[[ClaimRecord], tuple[str, ...]] = modality_of,
+                 place: Callable[[ClaimRecord, Store], Place] = place_of) -> None:
+        self.mind = mind
+        self._modality_of, self._place_of = modality, place
+        self._bindings: dict[str, Binding] = {}
+        self._by_modality: dict[str, set[str]] = {}
+        self._by_window: dict[str, set[str]] = {}
+        self._by_region: dict[str, set[str]] = {}
+        self._placed: list[tuple[str, Place]] = []
+        self._grid: dict[tuple[int, int], list[str]] = {}  # coarse cells, so adjacency is a lookup
+        self._cell = 128
+        self._at = -1
+
+    def index(self) -> None:
+        if self._at == self.mind.revision:
+            return
+        self._bindings, self._by_modality, self._by_window, self._by_region, self._placed = {}, {}, {}, {}, []
+        self._grid = {}
+        for cid, rec in sorted(self.mind._claims.items()):
+            if rec.retracted:
+                continue
+            mods = self._modality_of(rec)
+            where = self._place_of(rec, self.mind)
+            self._bindings[cid] = Binding(cid, rec.claim.subject, rec.claim.predicate, where, mods)
+            for m in mods:
+                self._by_modality.setdefault(m, set()).add(cid)
+            if where.window:
+                self._by_window.setdefault(where.window, set()).add(cid)
+            if where.region:
+                self._by_region.setdefault(where.region, set()).add(cid)
+            if where.box is not None:
+                self._placed.append((cid, where))
+                cx, cy = where.center  # type: ignore[misc]
+                self._grid.setdefault((int(cx // self._cell), int(cy // self._cell)), []).append(cid)
+        self._at = self.mind.revision
+
+    # -- the three frames
+
+    def binding(self, claim: Any) -> Binding | None:
+        self.index()
+        return self._bindings.get(claim if isinstance(claim, str) else claim.id)
+
+    def semantic(self, subject: Ref | None = None, predicate: str | None = None) -> list[ClaimRecord]:
+        return self.mind.claims(subject=subject, predicate=predicate)
+
+    def spatial(self, *, window: str | None = None, region: str | None = None,
+                near: Place | tuple[float, float] | None = None, slack: float = 120.0) -> list[ClaimRecord]:
+        """Claims located in a window or region, or within ``slack`` pixels of a point."""
+        self.index()
+        ids: set[str] | None = None
+        if window is not None:
+            ids = set(self._by_window.get(window, ()))
+        if region is not None:
+            ids = set(self._by_region.get(region, ())) if ids is None else ids & self._by_region.get(region, set())
+        if near is not None:
+            close = {cid for cid, place in self._placed if place.near(near, slack)}
+            ids = close if ids is None else ids & close
+        chosen = sorted(ids if ids is not None else self._bindings)
+        return [self.mind._claims[cid] for cid in chosen if cid in self.mind._claims and not self.mind._claims[cid].retracted]
+
+    def modality(self, kind: str) -> list[ClaimRecord]:
+        self.index()
+        return [self.mind._claims[cid] for cid in sorted(self._by_modality.get(kind, ()))
+                if not self.mind._claims[cid].retracted]
+
+    # -- cross-frame
+
+    def disagreements(self) -> list[Disagreement]:
+        """Where modalities conflict about one (subject, predicate). Nothing is resolved here."""
+        self.index()
+        groups: dict[tuple[Ref, str], list[tuple[str, Any, tuple[str, ...]]]] = {}
+        for cid, b in sorted(self._bindings.items()):
+            rec = self.mind._claims[cid]
+            groups.setdefault((b.subject, b.predicate), []).append((cid, rec.claim.object, b.modality))
+        out = []
+        for (subject, predicate), readings in sorted(groups.items(), key=lambda kv: (kv[0][0].id, kv[0][1])):
+            objects = {repr(obj) for _, obj, _ in readings}
+            modalities = {mods for _, _, mods in readings}
+            if len(objects) > 1 and len(modalities) > 1:
+                out.append(Disagreement(subject, predicate, tuple(readings)))
+        return out
+
+    def links(self, claim_id: str, mind: Store, *, slack: float = 80.0, spatial_weight: float = 0.6,
+              modality_weight: float = 0.25) -> Iterable[tuple[str, str, float]]:
+        """Extra adjacency for awareness: what is beside this on screen, and what was seen with it."""
+        self.index()
+        b = self._bindings.get(claim_id)
+        if b is None:
+            return ()
+        out: list[tuple[str, str, float]] = []
+        if b.place.box is not None:
+            cx, cy = b.place.center  # type: ignore[misc]
+            reach = int(slack // self._cell) + 1
+            cell_x, cell_y = int(cx // self._cell), int(cy // self._cell)
+            for dx in range(-reach, reach + 1):
+                for dy in range(-reach, reach + 1):
+                    for cid in self._grid.get((cell_x + dx, cell_y + dy), ()):
+                        if cid != claim_id and self._bindings[cid].place.near(b.place, slack):
+                            out.append((cid, "spatial", spatial_weight))
+        if b.place.window:
+            for cid in sorted(self._by_window.get(b.place.window, ()))[:64]:
+                if cid != claim_id:
+                    out.append((cid, "window", modality_weight))
+        return list(dict.fromkeys(out))

tensorcode/language/__init__.py

@@ -0,0 +1,36 @@
+"""Symbolic language understanding and generation: one grammar, both directions.
+
+    from tensorcode.language import ENGLISH, understand, realize, Context, resolve, to_claims
+
+    got = understand(ENGLISH, "Anem said the north field failed")
+    got.meanings          # (Frame('say', {speaker/subject, content: Frame('fail', ...)}),)
+    got.skipped           # words no constituent claimed, reported not guessed
+    got.ambiguous         # two readings of equal score survive as two readings
+
+    to_claims(frame, source=Ref("agent:anem"))   # reported speech lands in its own scope
+    realize(ENGLISH, frame)                      # say it again with the same grammar
+
+No model is called anywhere in this package, and it has no dependencies outside
+the standard library.
+"""
+
+from .chart import Chart, Node, Reading, Understanding, build_chart, cover, tokenize, understand, unquote
+from .discourse import Context, resolve, unresolved
+from .english import ENGLISH, ENGLISH_LEXICON
+from .features import FVar, ground, unify
+from .generate import realize, round_trip
+from .grammar import (
+    Ask, Attach, Build, Cat, Coord, Ent, Entry, Grammar, Head, Lexicon, Lit, Locative, Merge, Order, Production,
+    Qualify, Terminal, inflect, production, words,
+)
+from .grammar import OpenClass, guess_entries
+from .semantics import Entity, Frame, Question, Request, to_claims
+
+__all__ = [
+    "Ask", "Attach", "Build", "Cat", "Chart", "Context", "Coord", "ENGLISH", "ENGLISH_LEXICON", "Ent", "Entity",
+    "Entry", "FVar", "Frame", "Grammar", "Head", "Lexicon", "Lit", "Locative", "Merge", "Node", "Order",
+    "OpenClass", "Production", "Qualify", "Question", "Reading", "Request", "Terminal", "Understanding",
+    "build_chart", "guess_entries",
+    "cover", "ground", "inflect", "production", "realize", "resolve", "round_trip", "to_claims", "tokenize",
+    "unify", "unquote", "unresolved", "understand", "words",
+]