apsimo 1.3.0__py3-none-any.whl

apsimo/beliefs/models.py

@@ -0,0 +1,67 @@
+"""Belief-maintenance data model."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional
+
+
+def beliefs_mode() -> str:
+    from apsimo.util.autonomy_preset import resolve
+    return resolve("COLONY_BELIEFS_MODE", ("off", "shadow", "live"), "shadow")
+
+
+def beliefs_supervised_live() -> bool:
+    """Is the 'supervised' rung unlocked for beliefs? At trust stage
+    ask_first the engine may perform REVERSIBLE mutations only
+    (supersession that preserves the old value on the superseded node, and
+    bounded stale-confidence decay) and records real (non-shadow) outcomes,
+    so the beliefs domain can build the track record ask_first -> act_first
+    graduation requires. Default off = today's exact behavior.
+
+    H1.2: delegates to the generic rung (self_model/supervised.py) —
+    COLONY_SUPERVISED_LIVE_DOMAINS=beliefs and the legacy
+    COLONY_BELIEFS_SUPERVISED_LIVE=1 are equivalent."""
+    from apsimo.self_model.supervised import supervised_enabled
+    return supervised_enabled("beliefs")
+
+
+def stale_ttl_days() -> float:
+    try:
+        return max(1.0, float(os.environ.get("COLONY_BELIEFS_STALE_DAYS", "90")))
+    except (TypeError, ValueError):
+        return 90.0
+
+
+_NORM_RE = re.compile(r"[^a-z0-9]+")
+
+
+def norm_value(v: Any) -> str:
+    """Comparison-normalized value: lowercase alphanumerics."""
+    return _NORM_RE.sub(" ", str(v or "").strip().lower()).strip()
+
+
+@dataclass
+class Claim:
+    """One structured belief: subject has predicate = value."""
+    subject: str
+    predicate: str
+    value: str
+    confidence: float = 0.5
+    ts: float = 0.0                 # when asserted/observed (epoch)
+    source: str = "inference"       # source-trust key
+    ref: str = ""                   # memory id / entity id it came from
+    scope: str = "graph"            # graph | world_model
+    meta: Dict[str, Any] = field(default_factory=dict)
+
+    def key(self) -> tuple:
+        return (norm_value(self.subject), norm_value(self.predicate))
+
+    def same_value(self, other: "Claim") -> bool:
+        a, b = norm_value(self.value), norm_value(other.value)
+        if a == b:
+            return True
+        # containment tolerance: "acme" vs "acme corp"
+        return bool(a and b and (a in b or b in a))

apsimo/beliefs/promotion.py

@@ -0,0 +1,41 @@
+"""Small, inspectable contract for promotion from evidence to useful memory.
+
+Usefulness is a model judgment, not a calibrated score or evidence of truth.
+Rejected candidates remain in the canonical source history for later search.
+"""
+from __future__ import annotations
+
+import re
+
+PROMOTION_VERSION = "memory-promotion-v1"
+MEMORY_KINDS = frozenset({
+    "preference", "personal_context", "relationship", "decision", "procedure", "substantive_event",
+})
+PROMOTION_PROMPT = '''Promote only information with a concrete future use. Include
+memory_kind and recall_reason in every item. memory_kind is preference,
+personal_context, relationship, decision, procedure, or substantive_event.
+recall_reason is a short explanation of how this information could help later,
+not a confidence score or a claim that it is true. Return no item for routine
+status, build/test status alone, acknowledgments, generic commentary, hypothetical
+examples, quoted instructions or temporary debugging output. Do not manufacture
+a future use just to fill the array. Short facts can be valuable. A mutable fact
+such as where keys were left, a planned appointment, a significant incident,
+an explicit correction, or a reusable fix can matter; do not discard these just
+because they can change. Preserve their time and attribution. A successful test
+run alone is not a significant incident or a reusable procedure. Concrete reported
+comparisons, failures, material constraints and observed tradeoffs can be
+substantive_event evidence when they inform later choices, even before anyone
+chooses an approach. Use decision only for a course actually chosen; an
+observation that could inform a decision is not itself a decision.'''
+
+
+def promotion_metadata(item: dict) -> dict | None:
+    """Require an explicit use judgment, without mistaking it for verification."""
+    kind, reason = item.get("memory_kind"), item.get("recall_reason")
+    if not isinstance(kind, str) or kind not in MEMORY_KINDS or not isinstance(reason, str):
+        return None
+    reason = re.sub(r"\s+", " ", reason).strip()
+    if not 12 <= len(reason) <= 240:
+        return None
+    return {"version": PROMOTION_VERSION, "memory_kind": kind,
+            "recall_reason": reason, "basis": "model_judgment_unverified"}

apsimo/beliefs/resolve.py

@@ -0,0 +1,58 @@
+"""Conflict resolution: recency > confidence > source-trust.
+
+Ties on all three axes (within epsilons) are genuinely unresolvable and go
+to the owner as an internal review initiative instead of a silent pick.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Dict, Optional, Tuple
+
+from apsimo.beliefs.models import Claim
+
+# Generic source-trust ranking. Deployment override:
+# COLONY_SOURCE_TRUST="owner:1.0,connector:0.7,inference:0.3"
+_DEFAULT_TRUST: Dict[str, float] = {
+    "owner": 1.0,
+    "user_assertion": 1.0,
+    "world_model": 0.7,
+    "connector": 0.7,
+    "conversation": 0.6,
+    "file": 0.6,
+    "tool_output": 0.5,
+    "inference": 0.35,
+}
+
+_RECENCY_EPS_SECS = 86400.0   # claims within a day are "equally recent"
+_CONF_EPS = 0.05
+_TRUST_EPS = 0.05
+
+
+def source_trust(source: str) -> float:
+    table = dict(_DEFAULT_TRUST)
+    raw = os.environ.get("COLONY_SOURCE_TRUST", "")
+    for part in raw.split(","):
+        if ":" in part:
+            k, _, v = part.partition(":")
+            try:
+                table[k.strip().lower()] = float(v)
+            except (TypeError, ValueError):
+                continue
+    return table.get((source or "").strip().lower(), 0.4)
+
+
+def pick_winner(a: Claim, b: Claim) -> Optional[Tuple[Claim, Claim]]:
+    """(winner, loser), or None when genuinely unresolvable.
+
+    Ordering: recency first (a clearly newer claim supersedes), then
+    confidence, then source trust.
+    """
+    if abs((a.ts or 0.0) - (b.ts or 0.0)) > _RECENCY_EPS_SECS:
+        return (a, b) if (a.ts or 0.0) > (b.ts or 0.0) else (b, a)
+    if abs(a.confidence - b.confidence) > _CONF_EPS:
+        return (a, b) if a.confidence > b.confidence else (b, a)
+    ta, tb = source_trust(a.source), source_trust(b.source)
+    if abs(ta - tb) > _TRUST_EPS:
+        return (a, b) if ta > tb else (b, a)
+    return None