superlocalmemory 4.1.13 → 4.1.14

package/src/superlocalmemory/loops/models.py

@@ -1,152 +0,0 @@
-"""Immutable value types for SuperLocalMemory bounded loops.
-
-A *bounded loop* is an agent loop that terminates when an independent gate
-passes — never when the agent claims it is finished. This module holds the
-pure data types the loop engine reasons over.
-
-Design rules (kept deliberately strict):
-  * Standard-library imports only. No I/O, no framework, no side effects.
-  * Every dataclass is ``frozen=True`` — any attribute mutation raises
-    ``TypeError`` at runtime, so a lap result cannot be rewritten after the
-    gate has judged it.
-  * Timestamps are ISO-8601 strings supplied by the engine's clock, never
-    produced here with ``datetime.now()``.
-
-This is SuperLocalMemory's own realization of the bounded-loop concept; the
-loop-control discipline it encodes (gate-verified termination, enforced
-bounds, an advisory-only agent claim) is a general practice, reimplemented
-here against SLM's durable memory rather than a flat file.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-from enum import Enum
-from typing import Any, Optional
-
-
-class Rung(str, Enum):
-    """Autonomy rung governing how much a human stays in the loop.
-
-    ``L1`` report      — a human reads every verdict; the loop still exits on
-                         a passing gate but nothing is auto-approved.
-    ``L2`` assisted     — the agent acts but pauses for human approval before a
-                         passing gate is accepted as DONE.
-    ``L3`` unattended   — the agent acts autonomously; approval is derived from
-                         the bounds alone.
-
-    Subclassing ``(str, Enum)`` makes ``Rung.L2 == "L2"`` true and
-    ``Rung("L2")`` reconstruct the member, so a rung round-trips through JSON
-    or a CLI argument without a hand-written lookup table.
-    """
-
-    L1 = "L1"
-    L2 = "L2"
-    L3 = "L3"
-
-
-class Status(str, Enum):
-    """Terminal status of a bounded-loop run.
-
-    ``DONE``   — the gate passed and approval was granted or not required.
-    ``HALT``   — a safety bound tripped (iteration cap, no progress, budget).
-    ``PAUSE``  — the gate passed but required approval was not granted.
-    ``KILLED`` — an external kill switch tripped between laps.
-    ``ERROR``  — the runner or gate raised before a verdict was produced.
-    """
-
-    DONE = "DONE"
-    HALT = "HALT"
-    PAUSE = "PAUSE"
-    KILLED = "KILLED"
-    ERROR = "ERROR"
-
-
-@dataclass(frozen=True)
-class Bounds:
-    """The safety envelope a loop runs inside.
-
-    ``max_iterations``     hard cap on laps; required and must be >= 1.
-    ``no_progress_window`` consecutive no-change laps that trigger a HALT.
-    ``max_tokens``         cumulative token budget across laps, or ``None``.
-    ``max_wallclock_s``    wall-clock ceiling in seconds, or ``None``.
-    ``require_approval``    ``True``/``False`` forces the approval posture;
-                           ``None`` derives it from the rung (L1 -> no
-                           approval, L2/L3 -> approval required).
-    """
-
-    max_iterations: int
-    no_progress_window: int = 3
-    max_tokens: Optional[int] = None
-    max_wallclock_s: Optional[float] = None
-    require_approval: Optional[bool] = None
-
-    def __post_init__(self) -> None:
-        if self.max_iterations < 1:
-            raise ValueError("max_iterations must be >= 1")
-        if self.no_progress_window < 0:
-            raise ValueError("no_progress_window must be >= 0")
-        if self.max_tokens is not None and self.max_tokens < 0:
-            raise ValueError("max_tokens must be >= 0 when set")
-        if self.max_wallclock_s is not None and self.max_wallclock_s < 0:
-            raise ValueError("max_wallclock_s must be >= 0 when set")
-
-
-@dataclass(frozen=True)
-class Verdict:
-    """The independent gate's judgement of a single lap.
-
-    ``passed``   True only when the gate mechanically confirmed the goal.
-    ``detail``   human-readable one-line summary (required, non-empty).
-    ``evidence`` structured gate output (counts, tails, diffs). Defaults to a
-                 fresh dict per instance via ``default_factory`` so verdicts do
-                 not share one mutable dict.
-
-    ``passed=True`` is necessary but not sufficient for the loop to exit; the
-    engine still consults the approval rung.
-    """
-
-    passed: bool
-    detail: str
-    evidence: dict[str, Any] = field(default_factory=dict)
-
-
-@dataclass(frozen=True)
-class LapResult:
-    """What the runner reports after proposing one lap of work.
-
-    ``changed``            True if the runner altered the workspace/state.
-    ``agent_claimed_done`` the agent's own "I am finished" signal. Recorded for
-                           audit and **never** used to terminate the loop — the
-                           gate is the sole authority.
-    ``tokens``             tokens spent this lap (0 when unknown).
-    ``log``                short runner log for the lap.
-    """
-
-    changed: bool
-    agent_claimed_done: bool = False
-    tokens: int = 0
-    log: str = ""
-
-
-@dataclass(frozen=True)
-class Outcome:
-    """The final result of a bounded-loop run.
-
-    ``status``   terminal status.
-    ``reason``   short machine-friendly explanation ("gate-passed",
-                 "no-progress", "max-iterations", "awaiting-approval",
-                 "killed", or a gate/runner error string).
-    ``laps``     number of laps executed at termination.
-    ``run_id``   identifier used to locate this run's ledger in SLM memory.
-    """
-
-    status: Status
-    reason: str
-    laps: int
-    run_id: str
-
-    @property
-    def ok(self) -> bool:
-        """True only for a DONE outcome — the single success state."""
-        return self.status is Status.DONE

package/src/superlocalmemory/loops/rules.py

@@ -1,52 +0,0 @@
-"""Pure decision predicates for the bounded-loop engine.
-
-Every function here is a pure function of its arguments: same inputs give the
-same output, and nothing is mutated. The engine calls these to decide whether
-to stop, halt, or keep going; adapters never call them directly.
-
-Imports are limited to the standard library and the loop models.
-"""
-
-from __future__ import annotations
-
-from typing import Sequence
-
-from superlocalmemory.loops.models import Bounds, Rung, Verdict
-
-
-def stop_condition_met(verdict: Verdict) -> bool:
-    """Return True when the gate verdict means the loop may exit.
-
-    The rule is deliberately conservative: a loop is eligible to finish only
-    when the independent gate reports ``passed``. The agent's own opinion is
-    never consulted here — it is not even an argument.
-    """
-    return verdict.passed
-
-
-def no_progress(lap_changes: Sequence[bool], window: int) -> bool:
-    """Return True when the last ``window`` laps all made no change.
-
-    ``lap_changes`` is the ordered history of each lap's ``changed`` flag,
-    most-recent last. A window of ``0`` disables the check (a spinning agent
-    is then bounded only by the iteration cap). Fewer laps than the window
-    means "not enough evidence yet" and returns False.
-    """
-    if window <= 0:
-        return False
-    tail = lap_changes[-window:]
-    if len(tail) < window:
-        return False
-    return all(changed is False for changed in tail)
-
-
-def rung_requires_approval(rung: Rung, bounds: Bounds) -> bool:
-    """Return True when a human must approve a passing gate before DONE.
-
-    An explicit ``bounds.require_approval`` wins outright. When it is ``None``
-    the posture is derived from the rung: L1 exits without approval, while
-    L2 and L3 require it.
-    """
-    if bounds.require_approval is not None:
-        return bounds.require_approval
-    return rung in (Rung.L2, Rung.L3)

package/src/superlocalmemory/math/ebbinghaus.py

@@ -1,352 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V3 | https://qualixar.com | https://varunpratap.com
-
-"""Ebbinghaus forgetting curve — memory strength and retention.
-
-Implements the classic Ebbinghaus retention formula:
-
-    R(t) = e^(-t/S)
-
-where:
-    R = retention score in [0, 1]
-    t = hours since last access
-    S = memory strength (composite of access, importance, confirmations, emotion)
-
-Memory strength formula (ACT-R inspired):
-
-    S = alpha * log(1 + access_count)
-      + beta  * importance
-      + gamma * confirmation_count
-      + delta * emotional_salience
-
-Lifecycle zones are derived from retention score:
-    active   (R > 0.8)  -> weight 1.0
-    warm     (R > 0.5)  -> weight 0.7
-    cold     (R > 0.2)  -> weight 0.3
-    archive  (R > 0.05) -> weight 0.0
-    forgotten (R <= 0.05) -> weight 0.0
-
-References:
-    Ebbinghaus H (1885). Memory: A Contribution to Experimental Psychology.
-    Anderson J R & Lebiere C (1998). The Atomic Components of Thought. ACT-R.
-    Zhong W et al. (2024). MemoryBank: Enhancing Large Language Models with
-        Long-Term Memory. AAAI 2024.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-import logging
-import math
-from dataclasses import dataclass
-from datetime import UTC, datetime
-from typing import TYPE_CHECKING, TypedDict
-
-if TYPE_CHECKING:
-    from superlocalmemory.storage.database import DatabaseManager
-
-from superlocalmemory.core.config import ForgettingConfig
-
-logger = logging.getLogger(__name__)
-
-
-# ---------------------------------------------------------------------------
-# Data types
-# ---------------------------------------------------------------------------
-
-@dataclass(frozen=True)
-class MemoryStrength:
-    """Computed strength for a single memory."""
-
-    fact_id: str
-    strength: float             # S(m) in [S_MIN, S_MAX]
-    access_component: float     # alpha * log(1 + access_count)
-    importance_component: float  # beta * importance
-    confirmation_component: float  # gamma * confirmation_count
-    emotional_component: float    # delta * emotional_salience
-
-
-class FactRetentionInput(TypedDict):
-    """Input dict for batch retention computation. All keys are required."""
-
-    fact_id: str
-    access_count: int
-    importance: float              # PageRank score from fact_importance
-    confirmation_count: int        # Mapped from atomic_facts.evidence_count
-    emotional_salience: float      # Mapped from atomic_facts.emotional_valence
-    last_accessed_at: str          # ISO 8601 datetime string
-    trust_score: float             # Source trust in [0, 1]. Default 1.0.
-
-
-# ---------------------------------------------------------------------------
-# Lifecycle zone weights
-# ---------------------------------------------------------------------------
-
-_ZONE_WEIGHTS: dict[str, float] = {
-    "active": 1.0,
-    "warm": 0.7,
-    "cold": 0.3,
-    "archive": 0.0,
-    "forgotten": 0.0,
-}
-
-
-# ---------------------------------------------------------------------------
-# EbbinghausCurve
-# ---------------------------------------------------------------------------
-
-class EbbinghausCurve:
-    """Ebbinghaus forgetting curve with configurable strength formula.
-
-    Provides retention computation, memory strength calculation,
-    spaced repetition updates, lifecycle zone classification, and
-    batch processing for the forgetting scheduler.
-    """
-
-    __slots__ = ("_config",)
-
-    def __init__(self, config: ForgettingConfig) -> None:
-        self._config = config
-
-    def retention(self, hours_since_access: float, strength: float) -> float:
-        """Compute Ebbinghaus retention R(t) = e^(-t/S).
-
-        Args:
-            hours_since_access: Hours since last access. Negative treated as fresh.
-            strength: Memory strength S. Floored at min_strength.
-
-        Returns:
-            Retention score in [0.0, 1.0]. Never NaN, never Inf.
-        """
-        # HR-02: Validate negative time
-        if hours_since_access < 0:
-            return 1.0
-
-        # HR-03: Floor strength
-        s = max(self._config.min_strength, strength)
-
-        # Compute decay rate and retention
-        lambda_ = 1.0 / s
-        r = math.exp(-lambda_ * hours_since_access)
-
-        # NaN/Inf guard (A-MED-02) — MUST come before clamp
-        if math.isnan(r) or math.isinf(r):
-            logger.warning(
-                "retention(): NaN/Inf detected (lambda_=%f, t=%f), returning 0.0",
-                lambda_, hours_since_access,
-            )
-            return 0.0
-
-        # HR-02: Clamp to [0.0, 1.0]
-        return max(0.0, min(1.0, r))
-
-    def trust_modulated_retention(
-        self,
-        hours_since_access: float,
-        strength: float,
-        trust_score: float = 1.0,
-    ) -> float:
-        """Compute trust-weighted Ebbinghaus retention.
-
-        lambda_eff = lambda * (1 + kappa * (1 - trust))
-
-        Low-trust memories decay faster. When trust=1.0, identical to
-        standard retention. When trust=0.0, decay rate is (1+kappa)x faster.
-
-        Paper 3, Section 5.5: Trust-Weighted Forgetting.
-
-        Args:
-            hours_since_access: Hours since last access.
-            strength: Memory strength S.
-            trust_score: Source trust in [0, 1]. Default 1.0 (fully trusted).
-
-        Returns:
-            Retention score in [0.0, 1.0].
-        """
-        if hours_since_access < 0:
-            return 1.0
-
-        s = max(self._config.min_strength, strength)
-        tau = max(0.0, min(1.0, trust_score))
-        kappa = self._config.trust_kappa
-
-        # Trust-modulated decay rate
-        lambda_base = 1.0 / s
-        lambda_eff = lambda_base * (1.0 + kappa * (1.0 - tau))
-
-        r = math.exp(-lambda_eff * hours_since_access)
-
-        if math.isnan(r) or math.isinf(r):
-            return 0.0
-
-        return max(0.0, min(1.0, r))
-
-    def memory_strength(
-        self,
-        access_count: int,
-        importance: float,
-        confirmation_count: int,
-        emotional_salience: float,
-    ) -> float:
-        """Compute composite memory strength S(m).
-
-        S = alpha * log(1 + access_count)
-          + beta  * importance
-          + gamma * confirmation_count
-          + delta * emotional_salience
-
-        Args:
-            access_count: Number of times memory was accessed.
-            importance: PageRank importance score.
-            confirmation_count: Number of confirmations/evidence.
-            emotional_salience: Emotional strength [-1, 1].
-
-        Returns:
-            Clamped strength in [min_strength, max_strength].
-        """
-        cfg = self._config
-        a = cfg.alpha * math.log(1.0 + access_count)
-        b = cfg.beta * importance
-        c = cfg.gamma * confirmation_count
-        d = cfg.delta * emotional_salience
-        s = a + b + c + d
-
-        # HR-03: Clamp to bounds
-        return max(cfg.min_strength, min(cfg.max_strength, s))
-
-    def compute_strength(
-        self,
-        fact_id: str,
-        access_count: int,
-        importance: float,
-        confirmation_count: int,
-        emotional_salience: float,
-    ) -> MemoryStrength:
-        """Compute MemoryStrength dataclass for a single fact.
-
-        Returns:
-            MemoryStrength with all component scores.
-        """
-        cfg = self._config
-        a = cfg.alpha * math.log(1.0 + access_count)
-        b = cfg.beta * importance
-        c = cfg.gamma * confirmation_count
-        d = cfg.delta * emotional_salience
-        s = a + b + c + d
-        s = max(cfg.min_strength, min(cfg.max_strength, s))
-
-        return MemoryStrength(
-            fact_id=fact_id,
-            strength=s,
-            access_component=a,
-            importance_component=b,
-            confirmation_component=c,
-            emotional_component=d,
-        )
-
-    def spaced_repetition_update(
-        self, current_strength: float, hours_since_last_access: float,
-    ) -> float:
-        """Boost strength on re-access (spaced repetition effect).
-
-        Longer gaps between accesses produce larger boosts — this is the
-        spacing effect from cognitive science.
-
-        HR-07: Only INCREASES strength, never decreases.
-
-        Args:
-            current_strength: Current memory strength.
-            hours_since_last_access: Hours since last access.
-
-        Returns:
-            Updated strength, clamped to [min_strength, max_strength].
-        """
-        cfg = self._config
-        interval = math.log(1.0 + hours_since_last_access / 24.0)
-        boost = cfg.learning_rate * interval
-        s_new = current_strength + boost
-
-        # HR-03: Clamp
-        return max(cfg.min_strength, min(cfg.max_strength, s_new))
-
-    def lifecycle_zone(self, retention_score: float) -> str:
-        """Classify retention score into lifecycle zone.
-
-        Args:
-            retention_score: R in [0, 1].
-
-        Returns:
-            One of: 'active', 'warm', 'cold', 'archive', 'forgotten'.
-        """
-        if retention_score > 0.8:
-            return "active"
-        if retention_score > 0.5:
-            return "warm"
-        if retention_score > self._config.archive_threshold:
-            return "cold"
-        if retention_score > self._config.forget_threshold:
-            return "archive"
-        return "forgotten"
-
-    def lifecycle_weight(self, zone: str) -> float:
-        """Get retrieval weight for a lifecycle zone.
-
-        Args:
-            zone: Lifecycle zone name.
-
-        Returns:
-            Weight in [0.0, 1.0].
-        """
-        return _ZONE_WEIGHTS.get(zone, 0.0)
-
-    def batch_compute_retention(
-        self, facts: list[FactRetentionInput],
-    ) -> list[dict]:
-        """Compute retention for a batch of facts.
-
-        Args:
-            facts: List of FactRetentionInput dicts.
-
-        Returns:
-            List of dicts with fact_id, retention, strength, zone.
-        """
-        now = datetime.now(UTC)
-        results: list[dict] = []
-
-        for fact in facts:
-            access_count = fact["access_count"]
-            importance = fact["importance"]
-            confirmation_count = fact["confirmation_count"]
-            emotional_salience = fact["emotional_salience"]
-            last_accessed_at = fact["last_accessed_at"]
-
-            # Compute hours since last access
-            try:
-                last_dt = datetime.fromisoformat(last_accessed_at)
-                # Ensure timezone-aware
-                if last_dt.tzinfo is None:
-                    last_dt = last_dt.replace(tzinfo=UTC)
-                hours_since = (now - last_dt).total_seconds() / 3600.0
-            except (ValueError, TypeError):
-                hours_since = 0.0
-
-            strength = self.memory_strength(
-                access_count, importance, confirmation_count, emotional_salience,
-            )
-            trust = fact.get("trust_score", 1.0)
-            ret = self.trust_modulated_retention(hours_since, strength, trust)
-            zone = self.lifecycle_zone(ret)
-
-            results.append({
-                "fact_id": fact["fact_id"],
-                "retention": ret,
-                "strength": strength,
-                "zone": zone,
-                "access_count": access_count,
-                "last_accessed_at": last_accessed_at,
-            })
-
-        return results