pal-code 0.1.0__py3-none-any.whl

pal/memory/pipeline.py

@@ -0,0 +1,122 @@
+"""
+Persistent, cross-session agent memory (AIOS section 3.5) -- distinct
+from context_manager's ContextPager, which only pages within ONE open
+conversation and forgets everything when the process exits.
+
+Composes MemoryManager (RAM cache + block-limit-triggered LRU-K
+eviction -- see components/manager.py, components/lru_k.py) with
+lightweight relevance scoring for retrieve(). Disk persistence for the
+manager's swaps is provided either by a private, unscoped local store
+(components/storage_manager.py, the default) or -- when this Pipeline
+is given an agent_id and a shared StorageManagerPipeline -- by the
+general-purpose, agent-scoped Storage Manager (AIOS section 3.6, see
+pal/storage_manager/), matching "the memory manager calls the
+storage manager to swap the data into the disk... based on the agent ID
+passed from the memory manager."
+"""
+import time
+from pathlib import Path
+from typing import Optional
+
+from pal.context_manager.utils.relevance import embedding_similarity, recency_score
+from pal.memory.components.manager import MemoryManager
+from pal.memory.components.note import MemoryNote
+from pal.memory.components.storage_manager import StorageManager
+from pal.memory.utils.keyword_overlap import keyword_overlap
+
+_DEFAULT_STORE_ROOT = Path.home() / ".pal" / "memory"
+
+
+class MemoryPipeline:
+    """
+    add(content) -> writes a new note through the MemoryManager (RAM
+      cache + durable disk persistence, LRU-K eviction once the RAM
+      cache nears block_limit).
+    retrieve(query, top_k) -> scores every persisted note (RAM- or
+      disk-resident) by embedding similarity (or keyword overlap if
+      embeddings unavailable) blended with recency. Scoring has to
+      inspect every note's content regardless of tier -- this is a
+      lightweight, non-indexed store, there's no cheaper way to rank
+      relevance -- but only the notes that make the returned top_k are
+      actually READ through the manager, which is what counts as an
+      access for LRU-K and may swap a disk-resident note back into RAM.
+    """
+
+    def __init__(
+        self,
+        store_path: Optional[str] = None,
+        block_limit: int = 200,
+        high_water_mark: float = 0.8,
+        lru_k: int = 2,
+        agent_id: Optional[str] = None,
+        storage_manager=None,
+    ):
+        if storage_manager is not None:
+            # Central, agent-scoped Storage Manager (AIOS 3.6) -- the
+            # memory manager's swaps go through the same backend an
+            # agent's own SDK calls would use, scoped by agent_id.
+            from pal.storage_manager.utils.memory_adapter import AgentScopedMemoryStorage
+            self.storage = AgentScopedMemoryStorage(storage_manager, agent_id or "default")
+        else:
+            # Standalone fallback -- a private, unscoped local JSON-
+            # per-note store. Used when this Pipeline isn't wired into
+            # a broader orchestrator/StorageManagerPipeline (e.g. the
+            # standalone webapp).
+            root = Path(store_path) if store_path else _DEFAULT_STORE_ROOT
+            self.storage = StorageManager(root)
+
+        self.manager = MemoryManager(self.storage, block_limit=block_limit, high_water_mark=high_water_mark, k=lru_k)
+
+    def add(self, content: str, session_id: Optional[str] = None, tags: Optional[list[str]] = None) -> MemoryNote:
+        note = MemoryNote(content=content, session_id=session_id, tags=tags)
+        self.manager.write(note)
+        return note
+
+    def retrieve(self, query: str, top_k: int = 3, min_score: float = 0.05) -> list[MemoryNote]:
+        all_notes = self.storage.read_all()
+        if not all_notes:
+            return []
+
+        contents = [n.content for n in all_notes]
+        sims = embedding_similarity(query, contents)
+
+        # embedding_similarity returns all-zero if sentence-transformers
+        # isn't installed -- fall back to keyword overlap in that case.
+        if all(s == 0.0 for s in sims):
+            sims = [keyword_overlap(query, c) for c in contents]
+
+        now = time.time()
+        scored = []
+        for note, sim in zip(all_notes, sims):
+            rec = recency_score(note.timestamp, now)
+            # 70% relevance, 30% recency -- relevance should dominate for
+            # memory retrieval (unlike hot/cold conversation paging,
+            # where recency matters more).
+            score = 0.7 * sim + 0.3 * rec
+            scored.append((score, note))
+
+        scored.sort(key=lambda x: x[0], reverse=True)
+        top_ids = [note.id for score, note in scored if score >= min_score][:top_k]
+
+        # read() (not the scored `note` objects directly) so this
+        # registers as a real access for LRU-K and can swap a
+        # disk-only note into RAM.
+        results = [self.manager.read(nid) for nid in top_ids]
+        return [r for r in results if r is not None]
+
+    def clear(self) -> None:
+        for note_id in list(self.storage.list_ids()):
+            self.manager.delete(note_id)
+
+    def stats(self) -> dict:
+        """RAM/disk split and cache pressure -- useful for observing the
+        LRU-K eviction behavior directly rather than just its effects."""
+        return {
+            "ram_count": len(self.manager.ram),
+            "disk_count": len(self.storage.list_ids()),
+            "usage_ratio": round(self.manager.usage_ratio(), 3),
+            "block_limit": self.manager.block_limit,
+        }
+
+    def __len__(self) -> int:
+        return len(self.storage.list_ids())

pal/memory/utils/__init__.py

@@ -0,0 +1,3 @@
+from pal.memory.utils.keyword_overlap import keyword_overlap
+
+__all__ = ["keyword_overlap"]

pal/memory/utils/keyword_overlap.py

@@ -0,0 +1,3 @@
+from pal.context_manager.utils.relevance import keyword_overlap
+
+__all__ = ["keyword_overlap"]

pal/memory_tracker/__init__.py

@@ -0,0 +1,3 @@
+from pal.memory_tracker.pipeline import MemoryTracker, dir_bytes, process_memory
+
+__all__ = ["MemoryTracker", "dir_bytes", "process_memory"]

pal/memory_tracker/components/process.py

@@ -0,0 +1,56 @@
+"""How much memory this process uses, as best the platform allows. Never raises: anything unavailable is None."""
+from __future__ import annotations
+
+import sys
+
+
+def process_memory() -> dict:
+    """{"rss_mb", "peak_rss_mb", "source"}. Tries psutil, then the Unix `resource` module, then Windows' own API (ctypes)."""
+    try:
+        import psutil
+        p = psutil.Process()
+        rss = p.memory_info().rss
+        return {"rss_mb": round(rss / 1048576, 1), "peak_rss_mb": None, "source": "psutil"}
+    except Exception:  # noqa: BLE001  (not installed, or not allowed)
+        pass
+    try:
+        import resource
+        peak = resource.getrusage(resource.RUSAGE_SELF).ru_maxrss
+        peak_mb = peak / 1048576 if sys.platform == "darwin" else peak / 1024        # macOS reports bytes, Linux kilobytes
+        return {"rss_mb": None, "peak_rss_mb": round(peak_mb, 1), "source": "resource"}
+    except Exception:  # noqa: BLE001  (Windows has no `resource`)
+        pass
+    if sys.platform == "win32":                                                      # not tested outside Windows
+        try:
+            import ctypes
+            from ctypes import wintypes
+
+            class Counters(ctypes.Structure):
+                _fields_ = [("cb", wintypes.DWORD), ("PageFaultCount", wintypes.DWORD), ("PeakWorkingSetSize", ctypes.c_size_t),
+                            ("WorkingSetSize", ctypes.c_size_t), ("QuotaPeakPagedPoolUsage", ctypes.c_size_t), ("QuotaPagedPoolUsage", ctypes.c_size_t),
+                            ("QuotaPeakNonPagedPoolUsage", ctypes.c_size_t), ("QuotaNonPagedPoolUsage", ctypes.c_size_t),
+                            ("PagefileUsage", ctypes.c_size_t), ("PeakPagefileUsage", ctypes.c_size_t)]
+            c = Counters()
+            c.cb = ctypes.sizeof(c)
+            handle = ctypes.windll.kernel32.GetCurrentProcess()  # type: ignore[attr-defined]
+            if ctypes.windll.psapi.GetProcessMemoryInfo(handle, ctypes.byref(c), c.cb):  # type: ignore[attr-defined]
+                return {"rss_mb": round(c.WorkingSetSize / 1048576, 1), "peak_rss_mb": round(c.PeakWorkingSetSize / 1048576, 1), "source": "win32"}
+        except Exception:  # noqa: BLE001
+            pass
+    return {"rss_mb": None, "peak_rss_mb": None, "source": "unavailable"}
+
+
+def dir_bytes(path, limit_files: int = 20000) -> int:
+    """The size of a folder in bytes, counting at most `limit_files` files (a stats call must stay quick)."""
+    import os
+    total = seen = 0
+    for root, _dirs, files in os.walk(path):
+        for f in files:
+            try:
+                total += os.path.getsize(os.path.join(root, f))
+            except OSError:
+                pass
+            seen += 1
+            if seen >= limit_files:
+                return total
+    return total

pal/memory_tracker/pipeline.py

@@ -0,0 +1,44 @@
+"""The Memory Tracker: how much memory is the system using, and where?
+
+Components that hold something (the Notes Manager's notes, the open sessions, the knowledge graph's projects, the storage folder) register a
+gauge here: a small function that reports their numbers. `snapshot()` calls them all and adds the process's own memory, so one look shows
+what is using memory and how full the caches are. A gauge that fails is reported as an error, never raised: tracking must not break the chat.
+It also counts how many remembered notes were recalled into each turn.
+"""
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from pal.memory_tracker.components.process import dir_bytes, process_memory
+
+
+class MemoryTracker:
+    def __init__(self) -> None:
+        self._gauges: dict[str, Callable[[], Any]] = {}
+
+    def register(self, name: str, gauge: Callable[[], Any]) -> None:
+        """Add (or replace) a gauge: a no-argument function returning a number or a dict of numbers."""
+        self._gauges[name] = gauge
+
+    def snapshot(self) -> dict:
+        out: dict = {}
+        for name, gauge in self._gauges.items():
+            try:
+                out[name] = gauge()
+            except Exception as e:  # noqa: BLE001
+                out[name] = {"error": type(e).__name__}
+        out["process"] = process_memory()
+        return out
+
+    @staticmethod
+    def note_hits(turn, hits: int) -> None:
+        """Record how many remembered notes were recalled into this turn's request."""
+        turn.memory_hits = int(hits)
+
+    @staticmethod
+    def summarize(turns: Iterable) -> dict:
+        return {"memory_hits": sum(t.memory_hits for t in turns)}
+
+
+__all__ = ["MemoryTracker", "dir_bytes", "process_memory"]

pal/metrics/__init__.py

@@ -0,0 +1,4 @@
+from pal.metrics.components.collector import MetricsCollector, RequestMetric, TurnMetric
+from pal.metrics.pipeline import MetricsPipeline
+
+__all__ = ["MetricsPipeline", "MetricsCollector", "RequestMetric", "TurnMetric"]

pal/metrics/components/__init__.py

@@ -0,0 +1,4 @@
+from pal.metrics.components.collector import MetricsCollector, RequestMetric, TurnMetric
+from pal.metrics.components.exporter import export_json
+
+__all__ = ["MetricsCollector", "RequestMetric", "TurnMetric", "export_json"]

pal/metrics/components/collector.py

@@ -0,0 +1,140 @@
+from __future__ import annotations
+
+import threading
+import time
+from collections import deque
+from dataclasses import asdict, dataclass, field
+
+from pal.latency_tracker import LatencyTracker
+from pal.memory_tracker import MemoryTracker
+from pal.token_tracker import TokenTracker
+
+
+@dataclass
+class RequestMetric:
+    """Legacy per-request record used by the older Pipeline/experiments."""
+
+    timestamp: float
+    tokens_naive: int
+    tokens_optimized: int
+    latency: float
+    cache_hit: bool
+
+    @property
+    def tokens_saved(self) -> int:
+        return max(0, self.tokens_naive - self.tokens_optimized)
+
+
+@dataclass
+class TurnMetric:
+    """One chat turn. Latencies are seconds. `saved_*` are estimates (chars/4 unless the provider
+    counter is on): what a naive client would have sent minus what was sent."""
+
+    route: str                      # "api" | "local" | "tool"
+    session: str = ""
+    provider: str = ""
+    model: str = ""
+    latency_total: float = 0.0
+    latency_local: float = 0.0      # routing, input savers, local answer
+    latency_api: float = 0.0        # API calls, tool rounds included
+    latency_tools: float = 0.0
+    input_tokens: int = 0           # billed by the API (0 for local/tool turns)
+    output_tokens: int = 0
+    local_tokens: int = 0
+    saved_savers: int = 0
+    saved_paging: int = 0
+    saved_graph: int = 0
+    saved_documents: int = 0
+    api_calls: int = 0
+    tool_calls: int = 0
+    memory_hits: int = 0
+    escalated: bool = False
+    wait_local: float = 0.0           # seconds this turn's local jobs waited in the local scheduler
+    wait_api: float = 0.0             # seconds its API calls waited in the API line
+    local_pauses: int = 0             # times a higher-priority job paused one of its local jobs
+    compressed_turns: int = 0         # old assistant replies shown compressed this turn
+    compression_saved: int = 0        # tokens that compression saved versus showing those turns in full
+    cost_usd: float = 0.0             # what the API calls cost (LiteLLM's price table); 0 when the model has no known price
+    saved_cost_usd: float = 0.0       # estimated tokens saved x the model's input price
+    fallback: str = ""                # "provider/model" when the fallback model answered
+    fallback_reason: str = ""         # what failed first, e.g. RateLimitError
+    stage_seconds: dict = field(default_factory=dict)   # where this turn's time went, by stage (see latency_tracker)
+    error: str = ""
+    timestamp: float = field(default_factory=time.time)
+
+    @property
+    def saved_total(self) -> int:
+        return self.saved_savers + self.saved_paging + self.saved_graph + self.saved_documents
+
+
+class MetricsCollector:
+    """Thread-safe, bounded: keeps the most recent `max_records` records of each kind."""
+
+    def __init__(self, max_records: int = 1000, tokens: TokenTracker | None = None, latency: LatencyTracker | None = None,
+                 memory: MemoryTracker | None = None):
+        self.tokens, self.latency, self.memory = tokens or TokenTracker(), latency or LatencyTracker(), memory or MemoryTracker()
+        self._lock = threading.Lock()
+        self.records: deque[RequestMetric] = deque(maxlen=max_records)
+        self.turns: deque[TurnMetric] = deque(maxlen=max_records)
+        self.total_turns = 0
+
+    def record(self, tokens_naive: int, tokens_optimized: int, latency: float, cache_hit: bool):
+        with self._lock:
+            self.records.append(RequestMetric(time.time(), tokens_naive, tokens_optimized, latency, cache_hit))
+
+    def record_turn(self, turn: TurnMetric) -> None:
+        with self._lock:
+            self.turns.append(turn)
+            self.total_turns += 1
+
+    def reset(self) -> None:
+        with self._lock:
+            self.records.clear()
+            self.turns.clear()
+            self.total_turns = 0
+
+    def snapshot(self) -> tuple[list[RequestMetric], list[TurnMetric]]:
+        with self._lock:
+            return list(self.records), list(self.turns)
+
+    def summary(self, cache_overhead_bytes: int = 0) -> dict:
+        records, _ = self.snapshot()
+        if not records:
+            return {"requests": 0}
+        total_saved = sum(r.tokens_saved for r in records)
+        avg_latency = sum(r.latency for r in records) / len(records)
+        hit_rate = sum(1 for r in records if r.cache_hit) / len(records)
+        # ~4 bytes per token as a rough common scale for cache overhead vs tokens saved
+        return {
+            "requests": len(records),
+            "total_tokens_saved": total_saved,
+            "avg_latency_sec": round(avg_latency, 4),
+            "cache_hit_rate": round(hit_rate, 4),
+            "cache_overhead_bytes": cache_overhead_bytes,
+            "cache_pays_for_itself": cache_overhead_bytes <= total_saved * 4,
+        }
+
+    def chat_summary(self, session: str | None = None) -> dict:
+        """The turns added up, by the three trackers: tokens (and savings, cost), latency (and where the time went), memory."""
+        _, turns = self.snapshot()
+        if session:
+            turns = [t for t in turns if t.session == session[:8]]
+        if not turns:
+            return {"turns": 0}
+        api_turns = [t for t in turns if t.route == "api"]
+        return {
+            "turns": len(turns),
+            "turns_recorded": self.total_turns,
+            "api_calls_avoided": len(turns) - len(api_turns),
+            **self.tokens.summarize(turns),
+            **self.latency.summarize(turns),
+            **self.memory.summarize(turns),
+            "fallbacks": sum(1 for t in turns if t.fallback),
+            "tool_calls": sum(t.tool_calls for t in turns),
+            "escalations": sum(1 for t in turns if t.escalated),
+            "errors": sum(1 for t in turns if t.error),
+        }
+
+    def turn_dicts(self) -> list[dict]:
+        _, turns = self.snapshot()
+        return [{**asdict(t), "saved_total": t.saved_total} for t in turns]

pal/metrics/components/exporter.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from pal.metrics.components.collector import MetricsCollector
+
+
+def export_json(collector: MetricsCollector, path: str | os.PathLike) -> None:
+    records, _ = collector.snapshot()
+    data = {
+        "summary": collector.summary(),
+        "chat": collector.chat_summary(),
+        "turns": collector.turn_dicts(),
+        "records": [
+            {
+                "timestamp": r.timestamp,
+                "tokens_naive": r.tokens_naive,
+                "tokens_optimized": r.tokens_optimized,
+                "tokens_saved": r.tokens_saved,
+                "latency": r.latency,
+                "cache_hit": r.cache_hit,
+            }
+            for r in records
+        ],
+    }
+    Path(path).write_text(json.dumps(data, indent=2), encoding="utf-8")

pal/metrics/pipeline.py

@@ -0,0 +1,49 @@
+from __future__ import annotations
+
+import logging
+import os
+
+from pal.metrics.components.collector import MetricsCollector, TurnMetric
+from pal.metrics.components.exporter import export_json
+
+log = logging.getLogger(__name__)
+
+
+class MetricsPipeline:
+    def __init__(self, max_records: int = 1000, enabled: bool = True):
+        self.enabled = enabled
+        self.collector = MetricsCollector(max_records=max_records)
+        self.tokens, self.latency, self.memory = self.collector.tokens, self.collector.latency, self.collector.memory     # the three trackers
+
+    # legacy per-request API (older Pipeline and experiments)
+    def record(self, tokens_naive: int, tokens_optimized: int, latency: float, cache_hit: bool) -> None:
+        self.collector.record(tokens_naive, tokens_optimized, latency, cache_hit)
+
+    def record_turn(self, turn: TurnMetric) -> None:
+        if not self.enabled:
+            return
+        self.collector.record_turn(turn)
+        log.info(
+            "turn route=%s provider=%s model=%s total=%.2fs local=%.2fs api=%.2fs in=%d out=%d saved~%d tools=%d%s",
+            turn.route, turn.provider or "-", turn.model or "-", turn.latency_total, turn.latency_local,
+            turn.latency_api, turn.input_tokens, turn.output_tokens, turn.saved_total, turn.tool_calls,
+            f" error={turn.error}" if turn.error else "")
+
+    def summary(self, cache_overhead_bytes: int = 0) -> dict:
+        return self.collector.summary(cache_overhead_bytes=cache_overhead_bytes)
+
+    def chat_summary(self, session: str | None = None) -> dict:
+        return self.collector.chat_summary(session)
+
+    def turns(self) -> list[dict]:
+        return self.collector.turn_dicts()
+
+    def reset(self) -> None:
+        self.collector.reset()
+
+    def export_json(self, path: str | os.PathLike) -> None:
+        export_json(self.collector, path)
+
+    @property
+    def records(self):
+        return self.collector.records

pal/metrics/utils/__init__.py

@@ -0,0 +1,2 @@
+"""No shared utilities yet for metrics -- reserved for future
+aggregation/formatting helpers shared across exporters."""

pal/notes_manager/__init__.py

@@ -0,0 +1,5 @@
+from pal.notes_manager.components.privacy import looks_secret
+from pal.notes_manager.components.recall import Recall, build_recall
+from pal.notes_manager.pipeline import NotesManager
+
+__all__ = ["NotesManager", "Recall", "build_recall", "looks_secret"]

pal/notes_manager/components/privacy.py

@@ -0,0 +1,14 @@
+"""What is never kept as a note: anything that looks like a secret (API keys, tokens, passwords, private keys, long hashes)."""
+from __future__ import annotations
+
+import re
+
+_SECRET = re.compile(
+    r"sk-[A-Za-z0-9_\-]{16,}|AKIA[0-9A-Z]{16}|gh[pousr]_[A-Za-z0-9]{20,}|xox[baprs]-[A-Za-z0-9-]{10,}"
+    r"|eyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}|-----BEGIN [A-Z ]*PRIVATE KEY-----"
+    r"|(?i:password|passwd|secret|token|api[_ -]?key)\s*[:=]\s*\S{4,}"
+    r"|\b[A-Fa-f0-9]{40,}\b|\b[A-Za-z0-9+/]{48,}={0,2}(?=\s|$)")
+
+
+def looks_secret(text: str) -> bool:
+    return bool(_SECRET.search(text))

pal/notes_manager/components/recall.py

@@ -0,0 +1,31 @@
+"""Recall: which notes from OTHER sessions go into one request, within a token budget."""
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass
+
+
+@dataclass
+class Recall:
+    text: str      # the <memory> block to add to the request
+    hits: int      # how many notes are in it
+    tokens: int    # what they cost
+
+
+def build_recall(notes, session_id: str, limit: int, budget_tokens: int, count: Callable[[str], int]) -> Recall | None:
+    """The best matching notes written by other sessions (this session's own messages are already in the history), at most `limit` of
+    them and within `budget_tokens`. None when nothing fits."""
+    lines: list[str] = []
+    used = 0
+    for n in notes:
+        if n.session_id == session_id:
+            continue
+        line = f"- {n.content}"
+        cost = count(line)
+        if used + cost > budget_tokens or len(lines) >= limit:
+            continue
+        lines.append(line)
+        used += cost
+    if not lines:
+        return None
+    return Recall("<memory>\nEarlier messages from this user, from other sessions:\n" + "\n".join(lines) + "\n</memory>", len(lines), used)

pal/notes_manager/components/tidy.py

@@ -0,0 +1,28 @@
+"""Tidy: merging duplicate and near-duplicate notes. No model is involved."""
+from __future__ import annotations
+
+from collections.abc import Callable, Generator
+from contextlib import AbstractContextManager
+
+
+def tidy_steps(memory, lock: AbstractContextManager, near: float = 0.9, batch: int = 100,
+               on_removed: Callable[[str], None] | None = None) -> Generator[None, None, int]:
+    """Merge duplicate and near-duplicate notes, keeping the one that was used most (then the newest). A generator that yields every
+    `batch` notes, so a scheduler can pause it between batches; it returns how many notes were removed."""
+    notes = sorted(memory.storage.read_all(), key=lambda n: (-n.retrieval_count, -n.timestamp))
+    kept: list[set] = []
+    removed = 0
+    for i, n in enumerate(notes):
+        words = set(" ".join(n.content.lower().split()).split())
+        duplicate = any(len(words | k) and len(words & k) / len(words | k) >= near for k in kept) if len(words) >= 3 else False
+        if duplicate:
+            with lock:
+                memory.manager.delete(n.id)
+            removed += 1
+            if on_removed:
+                on_removed(n.id)
+        else:
+            kept.append(words)
+        if (i + 1) % batch == 0:
+            yield
+    return removed