tensorcode 0.1.0a1__py3-none-any.whl

tensorcode/control.py

@@ -0,0 +1,291 @@
+"""Control and volition: what to pursue, what to set aside, and when to stop trying.
+
+A mind that can only run the oldest request to completion has no control, only a queue. Three
+things are missing from a queue, and each is a claim here rather than a Python variable:
+
+* **a task set with suspended goals.** Interrupting a goal should not destroy it. Everything a
+  half-finished goal needs is already in the store (its frame, its position, its bindings), so
+  suspension is a *state change*, not a save: :func:`suspend` marks it and :func:`resume` marks
+  it back, and the work already done is still there. Dropping a goal throws that away; the only
+  reason to drop is that nobody will ever want it again.
+* **arbitration among live goals.** A static priority number cannot express that one goal is
+  nearly finished, that another has been waiting since three turns ago, or that switching away
+  from the one in progress costs something. :func:`arbitrate` scores goals on value, urgency
+  (which *ages*, so nothing starves) and cost-to-go, with hysteresis for the goal in hand, and
+  records why it chose — so a choice can be argued with.
+* **effort allocation.** A retry cap is a constant standing in for a judgement: is another
+  attempt worth its cost? :func:`should_try_again` makes that judgement from the frequencies a
+  :class:`~tensorcode.expectation.Predictor` actually observed, and refuses to invent a number
+  when it has too few — an unmeasured prior is stated with its basis, never smuggled in as 3.
+
+What this module will not do: guess. A goal with no declared value is worth
+:attr:`Stance.value_default` and says so; an effort decision with no evidence reports the prior
+it used; an attempt that *may already have taken effect* stops, because the cost of repeating an
+effect is not comparable to the cost of one more try.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Iterable, Mapping, Sequence
+
+from .expectation import Predictor
+from .outcomes import Score, Unknown, Verdict
+from .records import Claim, Evidence, Patch, Ref, Retract, Store, Tell
+
+#: a goal is in exactly one of these; the first two are live
+ACTIVE, SUSPENDED, DONE, FAILED, ABANDONED = "active", "suspended", "done", "failed", "abandoned"
+LIVE = (ACTIVE, SUSPENDED)
+
+
+def _now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+def _source(source: str) -> Ref:
+    """A source name as a Ref. Callers name themselves ("arbitrate"); refs need a kind."""
+    return Ref(source if ":" in source else f"decision:{source}")
+
+
+def _set(mind: Store, subject: Ref, predicate: str, value: object, source: str) -> None:
+    """Replace a subject's single current value, keeping the retraction visible."""
+    old = [r for r in mind.claims(subject, predicate)]
+    if len(old) == 1 and old[0].claim.object == value:
+        return
+    edits: list = [Retract(r.id, "superseded") for r in old]
+    edits.append(Tell(Claim(subject, predicate, value), (Evidence(_source(source), _now(), method="control"),)))
+    commit = mind.apply(Patch(tuple(edits), mind.revision))
+    mind.forget(commit.retracted)
+
+
+def _one(mind: Store, subject: Ref, predicate: str, default: object = None) -> object:
+    found = [r.claim.object for r in mind.claims(subject, predicate)]
+    return found[0] if found else default
+
+
+# ------------------------------------------------------------------ the task set
+
+
+def declare(mind: Store, goal: Ref, *, what: str, source: str, value: float | None = None,
+            cost_to_go: float | None = None, deadline: float | None = None) -> None:
+    """Enter a goal in the task set. ``what`` is how it will be described when arbitrating."""
+    _set(mind, goal, "goal:what", what, source)
+    _set(mind, goal, "goal:state", ACTIVE, source)
+    _set(mind, goal, "goal:since", 0.0, source)
+    if value is not None:
+        _set(mind, goal, "goal:value", float(value), source)
+    if cost_to_go is not None:
+        _set(mind, goal, "goal:cost_to_go", float(cost_to_go), source)
+    if deadline is not None:
+        _set(mind, goal, "goal:deadline", float(deadline), source)
+
+
+def weigh(mind: Store, goal: Ref, *, source: str, what: str | None = None, value: float | None = None,
+          urgency: float | None = None, cost_to_go: float | None = None, deadline: float | None = None) -> None:
+    """Give a goal the weights arbitration needs, without claiming its lifecycle.
+
+    A mind that already tracks whether a task is running (as a request status, a plan state,
+    anything) should use this rather than :func:`declare`: two sources of truth for one goal's
+    state is how a suspended task ends up both asleep and running.
+    """
+    for predicate, given in (("goal:what", what), ("goal:value", value), ("goal:urgency", urgency),
+                             ("goal:cost_to_go", cost_to_go), ("goal:deadline", deadline)):
+        if given is not None:
+            _set(mind, goal, predicate, given if predicate == "goal:what" else float(given), source)
+
+
+def waiting_since(mind: Store, goal: Ref, at: float, reason: str, *, source: str) -> None:
+    """Record that a goal has been waiting, and why — the input to aging, without owning state."""
+    _set(mind, goal, "goal:suspended_because", reason, source)
+    _set(mind, goal, "goal:suspended_at", float(at), source)
+
+
+def suspend(mind: Store, goal: Ref, reason: str, *, source: str, at: float = 0.0) -> None:
+    """Set a goal aside without losing it. Its progress stays exactly where it was."""
+    _set(mind, goal, "goal:state", SUSPENDED, source)
+    waiting_since(mind, goal, at, reason, source=source)
+
+
+def resume(mind: Store, goal: Ref, *, source: str) -> None:
+    _set(mind, goal, "goal:state", ACTIVE, source)
+    _set(mind, goal, "goal:resumed", True, source)
+
+
+def settle(mind: Store, goal: Ref, state: str, *, source: str) -> None:
+    """Finish a goal: done, failed, or abandoned (the only state that discards progress)."""
+    if state not in (DONE, FAILED, ABANDONED):
+        raise ValueError(f"not an ending state: {state!r}")
+    _set(mind, goal, "goal:state", state, source)
+
+
+def state_of(mind: Store, goal: Ref) -> str:
+    return str(_one(mind, goal, "goal:state", ACTIVE))
+
+
+def task_set(mind: Store, *, state: str | tuple[str, ...] = LIVE) -> list[Ref]:
+    """Goals in the given state(s), oldest declaration first."""
+    want = (state,) if isinstance(state, str) else tuple(state)
+    return [r.claim.subject for r in mind.claims(predicate="goal:state") if r.claim.object in want]
+
+
+def progress_kept(mind: Store, goal: Ref, predicates: Iterable[str]) -> dict:
+    """What a suspended goal still holds — the evidence that resuming is not restarting."""
+    return {p: _one(mind, goal, p) for p in predicates if _one(mind, goal, p) is not None}
+
+
+# ------------------------------------------------------------------ arbitration
+
+
+@dataclass(frozen=True)
+class Stance:
+    """How this mind weighs its goals against each other.
+
+    ``stickiness`` is hysteresis: the goal in hand keeps an advantage, so a near-tie does not
+    make the mind thrash between two goals and finish neither. ``aging`` is what stops a
+    cheap-first rule from starving an expensive goal forever.
+    """
+
+    stickiness: float = 0.35
+    aging: float = 0.05
+    cost_weight: float = 0.15
+    value_default: float = 1.0
+    urgency_default: float = 0.0
+
+
+@dataclass(frozen=True)
+class Choice:
+    """Which goal to pursue, what it scored, and what it beat."""
+
+    goal: Ref | None
+    why: str
+    score: float = 0.0
+    alternatives: tuple[tuple[Ref, float], ...] = ()
+
+    def describe(self) -> str:
+        if self.goal is None:
+            return f"nothing to pursue: {self.why}"
+        others = ", ".join(f"{g.id}@{s:.2f}" for g, s in self.alternatives)
+        return f"{self.goal.id}@{self.score:.2f} — {self.why}" + (f" (over {others})" if others else "")
+
+
+def urgency(mind: Store, goal: Ref, *, stance: Stance, now: float = 0.0) -> float:
+    """How pressing this goal is: what was declared, plus what waiting has added.
+
+    Aging is the honest part. Without it, ordering by cost finishes short goals first and a long
+    goal can wait forever; with it, a goal's urgency rises for as long as it is passed over, so
+    the worst case is bounded by how long you are willing to let something wait.
+    """
+    base = float(_one(mind, goal, "goal:urgency", stance.urgency_default))
+    waited = max(0.0, now - float(_one(mind, goal, "goal:suspended_at", now)))
+    deadline = _one(mind, goal, "goal:deadline")
+    pressure = 0.0
+    if isinstance(deadline, (int, float)) and deadline > now:
+        pressure = 1.0 / max(1e-6, float(deadline) - now)
+    return base + stance.aging * waited + pressure
+
+
+def score_goal(mind: Store, goal: Ref, *, stance: Stance, now: float = 0.0, current: Ref | None = None) -> float:
+    value = float(_one(mind, goal, "goal:value", stance.value_default))
+    cost = float(_one(mind, goal, "goal:cost_to_go", 0.0))
+    score = value + urgency(mind, goal, stance=stance, now=now) - stance.cost_weight * cost
+    if current is not None and goal == current:
+        score += stance.stickiness
+    return score
+
+
+def arbitrate(mind: Store, *, stance: Stance = Stance(), now: float = 0.0, current: Ref | None = None,
+              among: Sequence[Ref] | None = None, source: str = "arbitrate") -> Choice:
+    """Choose the goal to pursue now, and record the choice with its reasons."""
+    goals = list(among) if among is not None else task_set(mind, state=ACTIVE)
+    if not goals:
+        return Choice(None, "the task set holds no active goal")
+    scored = sorted(((score_goal(mind, g, stance=stance, now=now, current=current), g) for g in goals), key=lambda p: (-p[0], p[1].id))
+    best_score, best = scored[0]
+    parts = [f"value {float(_one(mind, best, 'goal:value', stance.value_default)):.2f}"]
+    if (u := urgency(mind, best, stance=stance, now=now)):
+        parts.append(f"urgency {u:.2f}")
+    if (c := float(_one(mind, best, "goal:cost_to_go", 0.0))):
+        parts.append(f"cost {c:.0f}")
+    if current is not None and best == current:
+        parts.append("in progress")
+    why = ", ".join(parts)
+    _set(mind, best, "goal:chosen_because", why, source)
+    return Choice(best, why, best_score, tuple((g, s) for s, g in scored[1:]))
+
+
+# ------------------------------------------------------------------ effort
+
+
+#: how an attempt turned out, for deciding whether to make another
+SUCCEEDED, TRANSIENT, AMBIGUOUS, REFUSED = "succeeded", "transient", "ambiguous", "refused"
+
+
+@dataclass(frozen=True)
+class Effort:
+    """What a goal is worth against what another attempt costs.
+
+    ``irreversible_cost`` is not a large number standing in for caution: an attempt whose effect
+    *may already have happened* is a different kind of act, because repeating it can double the
+    effect. Such an attempt is refused outright rather than priced.
+    """
+
+    value: float = 1.0
+    cost: float = 0.1
+    prior: Score | None = None  # used, and named, when there is too little evidence to measure
+    hard_cap: int = 12  # a bound on pathology, not the policy
+    irreversible_cost: float = float("inf")
+
+
+def should_try_again(history: Sequence[str], *, effort: Effort = Effort(), predictor: Predictor | None = None,
+                     cue: str = "attempt", aspect: str = "outcome") -> Verdict:
+    """Is one more attempt worth making, given how the previous ones went?
+
+    The verdict ``holds`` to try again, ``fails`` to stop, and carries the reasoning: an
+    expectation of success, where it came from, and what it was weighed against.
+    """
+    attempts = len(history)
+    if any(h == SUCCEEDED for h in history):
+        return Verdict("fails", ("already succeeded; another attempt would repeat the effect",))
+    if history and history[-1] == AMBIGUOUS:
+        return Verdict("fails", ("the last attempt may already have taken effect; repeating it could double it",))
+    if any(h == REFUSED for h in history):
+        return Verdict("fails", ("the attempt was refused, so trying again unchanged will be refused too",))
+    if attempts >= effort.hard_cap:
+        return Verdict("fails", (f"{attempts} attempts reached the hard cap {effort.hard_cap}",))
+    # the question is "will the next attempt succeed", so what is predicted is that one aspect.
+    # Predicting the *most likely outcome* instead would read a 60% chance of a transient failure
+    # as a 40% chance of success, which is only true when there are two outcomes; here there are
+    # three (succeeded, transient, ambiguous), so the binary aspect is what is recorded and read.
+    measured = predictor.predict(cue, f"{aspect}:succeeded") if predictor is not None else Unknown("no_predictor", "nothing observed")
+    if isinstance(measured, Unknown):
+        if effort.prior is None:
+            return Verdict("unknown", (f"no measured chance of success ({measured.reason}) and no prior was stated",))
+        p, basis = effort.prior.value, f"stated prior ({effort.prior.basis or 'unnamed'})"
+    else:
+        value, score = measured
+        p = score.value if value is True else max(0.0, 1.0 - score.value)
+        basis = f"measured {score.basis}"
+    worth = p * effort.value
+    if worth > effort.cost:
+        return Verdict("holds", (f"chance of success {p:.2f} ({basis}) × value {effort.value:.2f} = {worth:.2f} > cost {effort.cost:.2f}",))
+    return Verdict("fails", (f"chance of success {p:.2f} ({basis}) × value {effort.value:.2f} = {worth:.2f} ≤ cost {effort.cost:.2f}",))
+
+
+def observe_attempt(predictor: Predictor, outcome: str, *, cue: str = "attempt", aspect: str = "outcome") -> None:
+    """Record how an attempt went, so the next decision is made on frequencies rather than a constant.
+
+    Two things are recorded: the outcome itself, which is what a person reading the record wants,
+    and whether it succeeded, which is what :func:`should_try_again` asks about.
+    """
+    predictor.observe(cue, aspect, outcome)
+    predictor.observe(cue, f"{aspect}:succeeded", outcome == SUCCEEDED)
+
+
+__all__ = [
+    "ACTIVE", "SUSPENDED", "DONE", "FAILED", "ABANDONED", "LIVE",
+    "SUCCEEDED", "TRANSIENT", "AMBIGUOUS", "REFUSED",
+    "Stance", "Choice", "Effort",
+    "declare", "suspend", "resume", "settle", "state_of", "task_set", "progress_kept",
+    "urgency", "score_goal", "arbitrate", "should_try_again", "observe_attempt",
+]

tensorcode/cues.py

@@ -0,0 +1,192 @@
+"""Recall by cue, when the cue is not worded the way the memory was.
+
+``Memory.recall`` compares the cue with a rendered claim as bags of word n-grams. That works when
+the wording matches and falls off a cliff when it does not: "what is my cat" against
+``person:user cat 'Mackerel'`` shares a word, while "what did I name the animal" shares none, and
+the claim that answers it scores zero.
+
+The fix here is deliberately *not* a learned vector space. A sibling measurement found embeddings
+losing to plain token overlap on this repository's own recall tasks (0.005 vs 0.106 within a cycle,
+0.741 vs 0.944 within a subject), so the interesting question is not "can a model do better" but
+"what structure is token overlap throwing away". Three things, it turns out:
+
+**Roles.** A claim is not a sentence, it is a subject, a predicate and an object. A cue word that
+matches the predicate is worth far more than one matching some substring of the object, and a bag
+of n-grams cannot tell the difference.
+
+**Morphology.** "notes" and "note", "reading" and "read" are the same cue. Suffix stripping is
+crude and costs nothing.
+
+**The mind's own links.** Synonymy does not have to come from a hand-written list (which would only
+encode the answers to whatever test one was running) or a trained model. It can come from what the
+agent already believes: if the store holds ``fluffy is_a cat``, then a cue saying "cat" reaches a
+claim about Fluffy in one hop. Expansion is discounted per hop, so a direct hit always wins.
+
+What this cannot do is bridge words the agent has never seen related. That is the honest ceiling,
+and it is measured rather than argued: see ``eval/temporal_perception/paraphrase_recall.py``.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from typing import Any, Iterable, Sequence
+
+from .outcomes import Score
+from .records import ClaimRecord, Ref, Store
+
+STOP = frozenset("""a an the my our your his her their its is are was were be been am do does did
+what which who whom whose when where why how that this these those of in on at to for from with
+and or not no you i me we they it there here again please tell told say said know remember about
+had has have can could would should will shall may might must thing things stuff""".split())
+
+# claims whose object names the same thing as their subject: the hops worth taking
+LINKING = ("is_a", "label", "same_as", "means", "kind_of", "in", "part_of", "called", "aka")
+
+
+def words(text: str) -> list[str]:
+    return [w for w in re.split(r"[^\w']+", str(text).lower()) if w]
+
+
+def lemma(word: str) -> str:
+    """Enough morphology to make "notes" and "note" the same cue. Crude on purpose."""
+    for suffix, keep in (("ies", "y"), ("sses", "ss"), ("ches", "ch"), ("shes", "sh"), ("xes", "x"),
+                         ("ing", ""), ("ed", ""), ("s", "")):
+        if len(word) > len(suffix) + 2 and word.endswith(suffix):
+            return word[: -len(suffix)] + keep
+    return word
+
+
+def content(text: str) -> set[str]:
+    """The cue-bearing lemmas of a phrase: no stop words, no punctuation, no inflection.
+
+    Adjacent words are also joined, because a compound is written both ways and a predicate is one
+    token: "time zone" has to reach ``timezone``, and "notes folder" has to reach itself.
+    """
+    kept = [lemma(w) for w in words(text) if w not in STOP and len(w) > 1]
+    joined = {a + b for a, b in zip(kept, kept[1:])}
+    return (set(kept) | joined) - {""}
+
+
+def _ref_words(value: Any) -> set[str]:
+    """A ref carries words too: ``person:user`` is about a user, ``ui:Files/button/Open#1`` about Files."""
+    text = value.id if isinstance(value, Ref) else str(value)
+    return content(re.sub(r"[:/#]", " ", text))
+
+
+FIRST_PERSON = frozenset({"my", "mine", "our", "ours", "i", "me", "myself", "we", "us"})
+SELF_WORDS = frozenset({"user", "person", "me", "self", "you"})
+
+
+@dataclass(frozen=True)
+class RoleWeights:
+    """How much a match in each role is worth. Chosen on the training half only."""
+
+    predicate: float = 3.0
+    object: float = 2.0
+    subject: float = 1.0
+    hop_discount: float = 0.45  # one link away is worth less than half a direct hit
+    first_person: float = 1.5   # "my deadline" is a question about the asker, not about a label
+    off_topic_penalty: float = 0.6  # ... and a claim about something else answers it less well
+
+
+@dataclass
+class Hit:
+    record: ClaimRecord
+    score: Score
+    matched: tuple[str, ...] = ()
+    via: tuple[str, ...] = ()  # cue words reached through the store's own links
+
+    def why(self) -> str:
+        reason = f"matched {', '.join(self.matched) or 'nothing'}"
+        return reason + (f" (via {', '.join(self.via)})" if self.via else "")
+
+
+class Cues:
+    """A structural index over claims: role-wise lemma overlap, widened by the store's own links.
+
+    Built once per query batch rather than maintained: the cost is one pass over the claims, and a
+    live store changes under any index that tries to be clever about incremental updates.
+    """
+
+    def __init__(self, mind: Store, *, weights: RoleWeights | None = None,
+                 skip_scopes: Sequence[Ref | None] = (), skip_predicates: Iterable[str] = ()) -> None:
+        self.mind = mind
+        self.weights = weights or RoleWeights()
+        self.skip_scopes = tuple(skip_scopes)
+        self.skip_predicates = frozenset(skip_predicates)
+        self._synonyms: dict[str, set[str]] = {}
+        self._build_links()
+
+    def _build_links(self) -> None:
+        """Words the store itself says name the same thing, in one hop."""
+        for rec in self.mind.claims():
+            if rec.retracted or rec.claim.predicate not in LINKING:
+                continue
+            left, right = _ref_words(rec.claim.subject), _ref_words(rec.claim.object)
+            for a in left:
+                self._synonyms.setdefault(a, set()).update(right - {a})
+            for b in right:
+                self._synonyms.setdefault(b, set()).update(left - {b})
+
+    def expand(self, cue: set[str]) -> dict[str, str]:
+        """Cue lemmas one hop out, each remembering which cue word it came from."""
+        out: dict[str, str] = {}
+        for word in cue:
+            for near in self._synonyms.get(word, ()):  # noqa: B007 - small sets
+                if near not in cue:
+                    out.setdefault(near, word)
+        return out
+
+    def find(self, cue: str, k: int = 3, *, min_score: float = 0.05) -> list[Hit]:
+        direct = content(cue)
+        if not direct:
+            return []
+        # "what is my deadline" constrains the subject as surely as it names the predicate, and the
+        # stop-word list throws that away. Without it, a cue about "my time zone" is answered by a
+        # column header reading "Time", because a heading is a perfectly good match for one word.
+        about_me = bool(FIRST_PERSON & set(words(cue)))
+        indirect = self.expand(direct)
+        w = self.weights
+        best = w.predicate + w.object + w.subject
+        hits: list[Hit] = []
+        for rec in self.mind.claims():
+            if rec.retracted or rec.claim.scope in self.skip_scopes or rec.claim.predicate in self.skip_predicates:
+                continue
+            roles = ((w.predicate, content(rec.claim.predicate)),
+                     (w.object, _ref_words(rec.claim.object)),
+                     (w.subject, _ref_words(rec.claim.subject)))
+            total, matched, via = 0.0, set(), set()
+            for weight, bag in roles:
+                overlap = bag & direct
+                if overlap:
+                    total += weight
+                    matched |= overlap
+                    continue
+                reached = bag & set(indirect)
+                if reached:
+                    total += weight * w.hop_discount
+                    matched |= reached
+                    via |= {indirect[r] for r in reached}
+            if total <= 0:
+                continue
+            if about_me:
+                mine = bool(_ref_words(rec.claim.subject) & SELF_WORDS)
+                total += w.first_person if mine else -w.off_topic_penalty
+            # a claim that answers more of the cue outranks one that happens to match its commonest word
+            coverage = len(matched & (direct | set(indirect))) / len(direct)
+            value = (total / best) * (0.5 + 0.5 * min(1.0, coverage))
+            if value >= min_score:
+                hits.append(Hit(rec, Score(round(min(1.0, value), 4), "similarity"),
+                                tuple(sorted(matched)), tuple(sorted(via))))
+        hits.sort(key=lambda h: (-h.score.value, h.record.id))
+        return hits[:k]
+
+
+def exact_find(mind: Store, cue: str, k: int = 3) -> list[Hit]:
+    """The baseline that has no tolerance at all: the cue must contain the predicate verbatim."""
+    low = f" {cue.lower()} "
+    hits = [Hit(rec, Score(1.0, "similarity"), (rec.claim.predicate,))
+            for rec in mind.claims()
+            if not rec.retracted and rec.claim.predicate and f" {rec.claim.predicate.lower()} " in low]
+    return hits[:k]