superlocalmemory 4.1.13 → 4.1.15

package/src/superlocalmemory/retrieval/temporal_frame.py

@@ -1,102 +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
-
-"""Temporal-context injection helpers (Phase 4, T-inject).
-
-LLMs have no innate sense of time — a recalled fact reads the same whether it
-was stored an hour ago or two years ago. These pure helpers give every recalled
-memory a human-relative age label and give the whole result set a "temporal
-frame" header anchoring it to *now*, so the model can weigh recency and treat
-aged facts as possibly stale.
-
-Reuses ``time_window.parse_timestamp`` for tolerant timestamp parsing (SQLite
-space form, ISO ``T``/``Z``, date-only) — comparisons are always on parsed
-datetimes, never strings.
-
-Part of Qualixar | Author: Varun Pratap Bhardwaj
-License: AGPL-3.0-or-later
-"""
-
-from __future__ import annotations
-
-from datetime import datetime, timezone
-from typing import Iterable
-
-from superlocalmemory.retrieval.time_window import parse_timestamp
-
-__all__ = ["relative_age", "temporal_frame"]
-
-
-def _plural(n: int, unit: str) -> str:
-    return f"{n} {unit}" + ("" if n == 1 else "s")
-
-
-def relative_age(timestamp: str | None, now: datetime | None = None) -> str:
-    """Human-relative age of ``timestamp`` vs now, e.g. "3 days ago".
-
-    Returns "" when the timestamp is missing/unparseable. Future timestamps
-    (e.g. a referenced event date ahead of now) read as "in N …".
-    """
-    dt = parse_timestamp(timestamp)
-    if dt is None:
-        return ""
-    _now = now or datetime.now(timezone.utc)
-    if _now.tzinfo is None:
-        _now = _now.replace(tzinfo=timezone.utc)
-    secs = (_now - dt).total_seconds()
-    future = secs < 0
-    secs = abs(secs)
-
-    if secs < 45:
-        return "just now"
-    minutes = secs / 60.0
-    hours = minutes / 60.0
-    days = hours / 24.0
-    if minutes < 45:
-        phrase = _plural(round(minutes), "minute")
-    elif hours < 24:
-        phrase = _plural(round(hours), "hour")
-    elif days < 14:
-        phrase = _plural(round(days), "day")
-    elif days < 60:
-        phrase = _plural(round(days / 7.0), "week")
-    elif days < 365:
-        phrase = _plural(round(days / 30.0), "month")
-    else:
-        phrase = _plural(round(days / 365.0), "year")
-    return f"in {phrase}" if future else f"{phrase} ago"
-
-
-def temporal_frame(
-    timestamps: Iterable[str | None],
-    now: datetime | None = None,
-) -> str:
-    """A one-line "now" anchor + age span for a set of recalled timestamps.
-
-    Example: ``"Now: 2026-07-22T12:00:00+00:00. Recalled memories span 2 years
-    ago → just now. Treat undated or aged facts as possibly stale."``
-
-    With no dated timestamps, returns just the now-anchor + an undated note.
-    """
-    _now = now or datetime.now(timezone.utc)
-    if _now.tzinfo is None:
-        _now = _now.replace(tzinfo=timezone.utc)
-    now_iso = _now.replace(microsecond=0).isoformat()
-
-    dts = [d for d in (parse_timestamp(t) for t in timestamps) if d is not None]
-    if not dts:
-        return f"Now: {now_iso}. Recalled memories are undated."
-
-    oldest = min(dts)
-    newest = max(dts)
-    span = (
-        relative_age(oldest.isoformat(), _now)
-        if oldest == newest
-        else f"{relative_age(oldest.isoformat(), _now)} → "
-             f"{relative_age(newest.isoformat(), _now)}"
-    )
-    return (
-        f"Now: {now_iso}. Recalled memories span {span}. "
-        f"Treat undated or aged facts as possibly stale."
-    )

package/src/superlocalmemory/retrieval/temporal_utils.py

@@ -1,122 +0,0 @@
-# Copyright (c) 2026 Varun Pratap Bhardwaj / Qualixar
-# Licensed under AGPL-3.0-or-later - see LICENSE file
-# Part of SuperLocalMemory V4 | https://qualixar.com | https://varunpratap.com
-
-"""Temporal utility helpers for bi-temporal retrieval (Phase 4b).
-
-STORED TIMESTAMP FORMAT (empirically verified, Phase 4b):
-    The fact_temporal_validity table stores system_expired_at and valid_until
-    via datetime.now(timezone.utc).isoformat() which produces:
-        "YYYY-MM-DDTHH:MM:SS.microseconds+00:00"  (Python isoformat, +00:00 suffix)
-
-    normalize_as_of() outputs canonical datetime.isoformat() (preserving any
-    sub-second precision, same +00:00 suffix as the stored values) so that SQL
-    string comparisons ("system_expired_at <= as_of") are lexicographically
-    correct AND the inclusive boundary round-trips (audit P0/CRIT-1):
-
-        "2026-03-01T00:00:00.123456+00:00" <= "2026-06-01T00:00:00+00:00"
-        → first 10 chars "2026-03-01" < "2026-06-01" → TRUE  ✓
-
-    At sub-second boundary (same second, stored has micros):
-        "2024-01-01T12:00:00.123456+00:00" <= "2024-01-01T12:00:00+00:00"
-        → at pos 19: '.' (46) > '+' (43) → FALSE
-        Interpretation: stored supersession is 0.123456s AFTER as_of → fact
-        was still valid at that exact second. Semantically correct.
-
-    Contrast with SQLite strftime('%Y-%m-%dT%H:%M:%SZ', 'now') → "Z" suffix.
-    If as_of used "Z" suffix and stored uses "+00:00":
-        "2024-01-01T12:00:00.123456+00:00" <= "2024-01-01T12:00:00Z"
-        → at pos 19: '.' (46) < 'Z' (90) → TRUE
-        This would WRONGLY demote a fact whose supersession happened 0.123456s
-        AFTER as_of. Using "+00:00" avoids this error.
-"""
-
-from __future__ import annotations
-
-from datetime import datetime, timezone
-from typing import Optional
-
-
-def normalize_as_of(s: object) -> Optional[str]:
-    """Parse and normalize an as_of timestamp string to UTC ISO 8601.
-
-    Accepts:
-      - "2024-01-01T12:00:00Z"           → "2024-01-01T12:00:00+00:00"
-      - "2024-01-01T12:00:00+05:30"      → "2024-01-01T06:30:00+00:00"
-      - "2024-01-01"                      → "2024-01-01T00:00:00+00:00"
-      - "2024-01-01T12:00:00"            → "2024-01-01T12:00:00+00:00" (naive → UTC)
-      - "2024-01-01T12:00:00+00:00"      → "2024-01-01T12:00:00+00:00"
-
-    Returns None (not empty string) on invalid input so callers can
-    distinguish "no as_of" from "bad as_of" and reject or ignore accordingly.
-
-    Output format: canonical UTC ISO-8601 via datetime.isoformat():
-        - "YYYY-MM-DDTHH:MM:SS+00:00", OR
-          "YYYY-MM-DDTHH:MM:SS.ffffff+00:00" when the input carries sub-second
-          precision.
-        - Audit P0 (CRIT-1): sub-second precision is PRESERVED (not stripped) so
-          a caller can round-trip a real stored system_expired_at / valid_until
-          value — always written with microseconds by datetime.now(UTC).isoformat()
-          — and hit the inclusive boundary (`system_expired_at <= as_of`) EXACTLY.
-          Stripping microseconds made that boundary unreachable and silently
-          wrong on both temporal axes.
-        - +00:00 suffix matches the stored format so SQL string comparisons are
-          lexicographically correct (see module docstring for analysis).
-
-    Requirements:
-        Python >=3.11 (fromisoformat handles "Z" suffix natively). The
-        fallback .replace("Z", "+00:00") is kept for defensive compatibility.
-
-    Args:
-        s: Raw as_of string from user/HTTP/MCP/CLI input. May be None or
-           non-string; both return None (treated as "no as_of" by callers).
-
-    Returns:
-        Normalized UTC string "YYYY-MM-DDTHH:MM:SS+00:00", or None on error.
-    """
-    if not s or not isinstance(s, str):
-        return None
-    s = s.strip()
-    if not s:
-        return None
-
-    # Try ISO 8601 parse. Python 3.11 handles "Z" natively; the replace()
-    # makes this safe on any 3.x that might be used in tests.
-    for candidate in (s, s.replace("Z", "+00:00")):
-        try:
-            dt = datetime.fromisoformat(candidate)
-            # Naive datetime → assume UTC (documented assumption).
-            if dt.tzinfo is None:
-                dt = dt.replace(tzinfo=timezone.utc)
-            else:
-                dt = dt.astimezone(timezone.utc)
-            # Audit P0: isoformat() preserves microseconds when present so the
-            # value round-trips against microsecond-bearing stored timestamps.
-            return dt.isoformat()
-        except ValueError:
-            continue
-
-    # Date-only "YYYY-MM-DD" — treat as midnight UTC.
-    try:
-        dt = datetime.strptime(s[:10], "%Y-%m-%d").replace(tzinfo=timezone.utc)
-        return dt.isoformat()
-    except ValueError:
-        return None
-
-
-def normalize_strict_boundary(value: object, name: str) -> Optional[str]:
-    """Normalize an optional strict boundary or reject an invalid supplied value.
-
-    Unlike legacy ``as_of`` direct calls, explicit two-clock queries cannot
-    quietly degrade to current recall: doing so would make a malformed history
-    request appear authoritative.
-    """
-    if value is None or (isinstance(value, str) and not value.strip()):
-        return None
-    normalized = normalize_as_of(value)
-    if normalized is None:
-        raise ValueError(f"{name} must be an ISO-8601 timestamp")
-    return normalized
-
-
-__all__ = ("normalize_as_of", "normalize_strict_boundary")