pdm-memory 0.1.2__py3-none-any.whl

pdm_memory/__init__.py

@@ -0,0 +1,22 @@
+"""
+pdm_memory — Pressure-Driven Memory SDK
+========================================
+
+The public surface of the SDK:
+
+    from pdm_memory import Memory
+
+    mem = Memory(store="./my_app.db")
+    mem.save("User prefers metric units", source="chat")
+    hits = mem.recall("how should I format this?", k=5)
+
+    from pdm_memory.integrations import wrap_openai, wrap_anthropic
+
+See README.md for full documentation.
+"""
+
+from pdm_memory.memory import Memory
+from pdm_memory.core.signature import MemoryHit, DrawerInfo
+
+__version__ = "0.1.0"
+__all__ = ["Memory", "MemoryHit", "DrawerInfo", "__version__"]

pdm_memory/auth/__init__.py

@@ -0,0 +1,4 @@
+"""pdm_memory.auth package."""
+from pdm_memory.auth.jwt_handler import JWTAuth
+
+__all__ = ["JWTAuth"]

pdm_memory/auth/jwt_handler.py

@@ -0,0 +1,119 @@
+"""
+JWT Auth Handler — Task 2.2
+
+Manages Bearer token authentication for cloud storage requests.
+Optionally handles refresh-token flows automatically on 401.
+
+Usage:
+    auth = JWTAuth(token="eyJ...", refresh_token="eyJ...", refresh_url="https://api.azus.ai/api/v1/accounts/auth/refresh/")
+    headers = auth.headers()
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class JWTAuth:
+    """
+    JWT Bearer token handler.
+
+    Args:
+        token:         JWT access token (required).
+        refresh_token: Optional refresh token for automatic renewal.
+        refresh_url:   URL to POST refresh token to (companion_api endpoint).
+        expire_buffer: Refresh this many seconds before expiry (default 60s).
+    """
+
+    def __init__(
+        self,
+        token: str,
+        refresh_token: Optional[str] = None,
+        refresh_url: Optional[str] = None,
+        expire_buffer: int = 60,
+    ) -> None:
+        self._token = token
+        self._refresh_token = refresh_token
+        self._refresh_url = refresh_url
+        self._expire_buffer = expire_buffer
+        self._expires_at: Optional[float] = self._decode_exp(token)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def token(self) -> str:
+        return self._token
+
+    def headers(self) -> Dict[str, str]:
+        """Return Authorization headers for an HTTP request."""
+        return {"Authorization": f"Bearer {self._token}"}
+
+    def refresh(self) -> bool:
+        """
+        Attempt to refresh the access token using the refresh token.
+
+        Returns True on success, False if refresh not possible or failed.
+        """
+        if not self._refresh_token or not self._refresh_url:
+            return False
+        try:
+            import httpx
+            resp = httpx.post(
+                self._refresh_url,
+                json={"refresh": self._refresh_token},
+                timeout=10,
+            )
+            resp.raise_for_status()
+            data = resp.json()
+            new_token = data.get("access")
+            if new_token:
+                self._token = new_token
+                self._expires_at = self._decode_exp(new_token)
+                logger.debug("[JWTAuth] Token refreshed successfully")
+                return True
+        except Exception as e:
+            logger.warning("[JWTAuth] Token refresh failed: %s", e)
+        return False
+
+    def is_expired(self) -> bool:
+        """Return True if token is expired or within expire_buffer seconds of expiry."""
+        if self._expires_at is None:
+            return False  # Unknown expiry — assume valid
+        return time.time() >= (self._expires_at - self._expire_buffer)
+
+    def ensure_fresh(self) -> None:
+        """Refresh token if expired. Raises RuntimeError if refresh fails."""
+        if self.is_expired():
+            if not self.refresh():
+                raise RuntimeError(
+                    "PDM cloud auth: access token is expired and could not be refreshed. "
+                    "Please provide a new token via Memory(token=...)."
+                )
+
+    # ------------------------------------------------------------------
+    # Private
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _decode_exp(token: str) -> Optional[float]:
+        """Decode the 'exp' claim from a JWT without validating the signature."""
+        try:
+            import base64
+            import json
+            parts = token.split(".")
+            if len(parts) != 3:
+                return None
+            payload = parts[1]
+            # Add padding
+            payload += "=" * (4 - len(payload) % 4)
+            decoded = base64.urlsafe_b64decode(payload)
+            claims = json.loads(decoded)
+            return float(claims.get("exp", 0)) or None
+        except Exception:
+            return None

pdm_memory/bench.py

@@ -0,0 +1,5 @@
+"""Entry point for: python -m pdm_memory.bench"""
+from pdm_memory.tools.bench import main
+
+if __name__ == "__main__":
+    main()

pdm_memory/core/__init__.py

@@ -0,0 +1 @@
+"""pdm_memory.core package."""

pdm_memory/core/math.py

@@ -0,0 +1,329 @@
+"""
+PDM Core Math — Pure Python, zero external dependencies.
+
+All formulas are ported faithfully from companion_api/pdm/kernel.py
+and companion_api/pdm/models.py.  No Django, no ORM, no Celery.
+
+Formula reference:
+  effective_spike = min(100, P_magnitude × (t_persistence/30) × phase_privilege)
+  decay_factor    = 1 - exp(-λ × t)     where λ = ln2 / half_life
+  V               = (correct + 1) / (total + 2)   [Laplace smoothing]
+  P_effective     = P × V × (1 - decay_factor) × intent_weight × quality × comparator
+  incremental_decay: new_p = p * (decay_rate ** days_elapsed)   (no-scheduler version)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict, List, Optional
+
+
+# ---------------------------------------------------------------------------
+# Domain half-lives (ported from kernel.py DOMAIN_HALF_LIVES)
+# ---------------------------------------------------------------------------
+
+DOMAIN_HALF_LIVES: Dict[str, float] = {
+    "market_signal": 1.0,    # 1 day
+    "pattern": 14.0,         # 2 weeks
+    "structural": 90.0,      # 3 months
+    "core_fact": 365.0,      # 1 year
+    "reminder": 7.0,         # 1 week
+    "insight": 30.0,         # 1 month
+    "warning": 3.0,          # 3 days
+}
+
+DEFAULT_HALF_LIFE: float = 30.0
+
+# Pressure constants
+P_MAX: float = 100.0
+P_FLOOR: float = 0.0
+
+# Decay trigger — signatures below this are eligible for deletion
+DECAY_DELETE_THRESHOLD: float = 30.0
+
+# Default decay multiplier (10% pressure loss per cycle)
+DEFAULT_DECAY_RATE: float = 0.9
+
+
+# ---------------------------------------------------------------------------
+# Task 1.3: Core formulas (Django-free)
+# ---------------------------------------------------------------------------
+
+
+def calculate_effective_spike(
+    p_magnitude: float,
+    t_persistence: float,
+    phase_privilege: float = 1.0,
+) -> float:
+    """
+    Calculate effective_spike = p_magnitude × (t_persistence / 30) × phase_privilege.
+    Capped at 100.
+
+    Args:
+        p_magnitude:    Raw pressure (0–100).
+        t_persistence:  How many days the memory stays relevant.
+        phase_privilege: Nesting/context multiplier, typically 1.0.
+
+    Returns:
+        effective_spike in [0, 100].
+    """
+    raw = p_magnitude * (t_persistence / 30.0) * phase_privilege
+    return min(P_MAX, max(P_FLOOR, raw))
+
+
+def calculate_decay_factor(
+    days_since_retrieved: float,
+    half_life: float = DEFAULT_HALF_LIFE,
+) -> float:
+    """
+    Exponential decay factor based on time since last retrieval.
+
+    decay_factor = 1 - exp(-λ × t)   where λ = ln2 / half_life
+
+    A decay_factor close to 0 means the memory is fresh (little decay).
+    A decay_factor close to 1 means the memory is very stale.
+
+    Args:
+        days_since_retrieved: Days since this memory was last accessed.
+        half_life:            Domain-specific half-life in days.
+
+    Returns:
+        decay_factor in [0, 1].
+    """
+    half_life = max(0.1, half_life)
+    lam = math.log(2) / half_life
+    return 1.0 - math.exp(-lam * days_since_retrieved)
+
+
+def calculate_v(correct: int, total: int) -> float:
+    """
+    Validation Coefficient with Laplace smoothing.
+    V = (correct + 1) / (total + 2)
+
+    Range: 0.33 (no history) → approaching 1.0 (perfect accuracy).
+
+    Args:
+        correct: Number of correct predictions.
+        total:   Total predictions made.
+
+    Returns:
+        V in [0.33, 1.0].
+    """
+    return round((correct + 1) / (total + 2), 6)
+
+
+def calculate_intent_weight(
+    intent_tags: List[str],
+    query: Optional[str] = None,
+) -> float:
+    """
+    Intent match weight: 0.8 base + 0.2 boost proportional to tag-query overlap.
+
+    Args:
+        intent_tags: Tags associated with the memory.
+        query:       The recall query string.
+
+    Returns:
+        Weight in [0.8, 1.0] — 1.0 when query is absent or all tags match.
+    """
+    if not query or not intent_tags:
+        return 1.0
+    query_lower = query.lower()
+    matches = sum(1 for tag in intent_tags if tag.lower() in query_lower)
+    return round(0.8 + 0.2 * (matches / len(intent_tags)), 6)
+
+
+def calculate_p_effective(
+    p_magnitude: float,
+    v: float = 0.75,
+    decay_factor: float = 0.0,
+    intent_weight: float = 1.0,
+    quality: float = 0.80,
+    comparator: float = 1.0,
+) -> float:
+    """
+    P_effective — the live pressure value used for retrieval ranking.
+
+    P_eff = P_magnitude × V × (1 - decay_factor) × intent_weight × quality × comparator
+
+    Args:
+        p_magnitude:  Raw stored pressure (0–100).
+        v:            Validation coefficient (Laplace, 0.33–1.0).
+        decay_factor: Exponential decay (0=fresh, 1=fully decayed).
+        intent_weight: Tag-query match weight (0.8–1.0).
+        quality:      Signal quality score (0–1), default 0.80.
+        comparator:   Optional UCA-style proxy multiplier (0.85–1.15).
+
+    Returns:
+        P_effective in [0, 100].
+    """
+    p_eff = (
+        p_magnitude
+        * v
+        * (1.0 - decay_factor)
+        * intent_weight
+        * quality
+        * comparator
+    )
+    return round(min(P_MAX, max(P_FLOOR, p_eff)), 6)
+
+
+# ---------------------------------------------------------------------------
+# Task 1.4: Incremental decay (no Celery — computed on every recall())
+# ---------------------------------------------------------------------------
+
+
+def calculate_incremental_decay(
+    p_magnitude: float,
+    days_elapsed: float,
+    t_persistence: float,
+    phase_privilege: float = 1.0,
+    decay_per_day: float = DEFAULT_DECAY_RATE,
+) -> tuple[float, float]:
+    """
+    Compute decayed p_magnitude and effective_spike without a scheduler.
+
+    Decay only fires after t_persistence days.  If days_elapsed ≤ t_persistence,
+    the memory is within its guaranteed persistence window — no decay applied.
+
+    Formula:
+        If days_elapsed > t_persistence:
+            decayed_p = p_magnitude × decay_per_day^(days_elapsed - t_persistence)
+        else:
+            decayed_p = p_magnitude  (still in persistence window)
+
+    Args:
+        p_magnitude:    Current stored pressure.
+        days_elapsed:   Days since the memory was created (or last decayed).
+        t_persistence:  Guaranteed persistence window in days.
+        phase_privilege: Phase multiplier for effective_spike.
+        decay_per_day:  Multiplier per day past persistence (default 0.9 = 10% loss/day).
+
+    Returns:
+        Tuple (decayed_p_magnitude, new_effective_spike).
+    """
+    if days_elapsed <= t_persistence:
+        new_p = p_magnitude
+    else:
+        days_past = days_elapsed - t_persistence
+        new_p = p_magnitude * (decay_per_day ** days_past)
+
+    new_p = max(0.0, min(P_MAX, new_p))
+    new_spike = calculate_effective_spike(new_p, t_persistence, phase_privilege)
+    return round(new_p, 6), round(new_spike, 6)
+
+
+# ---------------------------------------------------------------------------
+# Task 1.3: Temporal geometry (PDM-T), ported from models.py
+# ---------------------------------------------------------------------------
+
+
+def calculate_temporal_geometry(
+    c_base: float,
+    s_base: float,
+    p_base: float,          # p_magnitude / 100.0
+    urgency_rate: float,
+    t_remaining_days: float,
+    persist_days: float,
+    decay_rate: float = 0.05,
+    temporal_weight: float = 1.0,
+) -> dict:
+    """
+    PDM-T Temporal Deformation Geometry.
+
+    Pre-deadline:
+        C_T = c_base × (1 + persist / T_remaining)
+        S_T = s_base / (1 + urgency_rate × (1 - T_remaining / persist))
+        P_T = p_base × urgency_rate^(1 / T_remaining_days)
+        E_T = C_T × transmission × P_T   (normalized via asymptotic scaling)
+
+    Post-deadline:
+        E_T = 0, weight decays by decay_rate per day past deadline.
+
+    Args:
+        c_base:          Initial curvature (0–1).
+        s_base:          Initial membrane thickness (0–1).
+        p_base:          Normalized pressure (p_magnitude / 100).
+        urgency_rate:    Pressure multiplier ramp (1–10).
+        t_remaining_days: Days to deadline (negative = past deadline).
+        persist_days:    t_persistence value.
+        decay_rate:      Post-deadline fade rate per day.
+        temporal_weight: Current weight (decays post-deadline).
+
+    Returns:
+        dict with keys: c_temporal, s_temporal, p_temporal, e_temporal,
+                        is_urgent, temporal_weight, status.
+    """
+    if t_remaining_days <= 0:
+        days_past = abs(t_remaining_days)
+        new_weight = temporal_weight * (1 - decay_rate) ** days_past
+        return {
+            "c_temporal": 0.0,
+            "s_temporal": 1.0,
+            "p_temporal": 0.0,
+            "e_temporal": 0.0,
+            "is_urgent": False,
+            "temporal_weight": max(0.0, new_weight),
+            "status": "EXPIRED",
+        }
+
+    t_rem = max(0.1, t_remaining_days)
+    persist = max(1.0, persist_days)
+
+    c_t = min(5.0, c_base * (1 + persist / t_rem))
+    time_factor = max(0.0, min(1.0, 1 - (t_rem / persist)))
+    s_t = max(0.01, s_base / (1 + urgency_rate * time_factor))
+    p_t = min(10.0, p_base * (urgency_rate ** (1 / t_rem)))
+
+    transmission = 1.0 / s_t
+    raw_e_t = c_t * transmission * p_t
+    e_t = min(1.0, max(0.0, raw_e_t / (raw_e_t + 10.0)))
+
+    return {
+        "c_temporal": round(c_t, 4),
+        "s_temporal": round(s_t, 4),
+        "p_temporal": round(p_t, 4),
+        "e_temporal": round(e_t, 4),
+        "is_urgent": e_t > 0.75,
+        "temporal_weight": temporal_weight,
+        "status": "URGENT" if e_t > 0.75 else "ACTIVE",
+    }
+
+
+# ---------------------------------------------------------------------------
+# Domain / regime inference helpers (ported from kernel.py + TAS engine)
+# ---------------------------------------------------------------------------
+
+
+def infer_domain(tags: List[str]) -> str:
+    """Infer memory domain from intent tags."""
+    if not tags:
+        return "insight"
+    tag_str = " ".join(tags).lower()
+    if any(k in tag_str for k in ["market", "signal", "price", "trade", "stock"]):
+        return "market_signal"
+    if any(k in tag_str for k in ["pattern", "historical", "analogue"]):
+        return "pattern"
+    if any(k in tag_str for k in ["structure", "structural", "model"]):
+        return "structural"
+    if any(k in tag_str for k in ["remind", "deadline", "due", "by "]):
+        return "reminder"
+    if any(k in tag_str for k in ["warning", "risk", "danger"]):
+        return "warning"
+    if any(k in tag_str for k in ["fact", "law", "rule", "principle"]):
+        return "core_fact"
+    return "insight"
+
+
+def infer_regime(tags: List[str]) -> str:
+    """Infer question regime from intent tags."""
+    tag_str = " ".join(tags).lower()
+    if any(k in tag_str for k in ["trade", "stock", "market", "price"]):
+        return "trading"
+    if any(k in tag_str for k in ["code", "engineer", "deploy", "bug", "api"]):
+        return "engineering"
+    if any(k in tag_str for k in ["personal", "health", "family"]):
+        return "personal"
+    if any(k in tag_str for k in ["patent", "ip", "monetize", "license"]):
+        return "ip_monetize"
+    return "neutral"