pyagent-context 0.1.0__py3-none-any.whl

pyagent_context/__init__.py

@@ -0,0 +1,29 @@
+"""PyAgent Context — three-tier memory with trust-aware context ledger."""
+
+from pyagent_context.compression import CompressionPolicy, ContextCompressor
+from pyagent_context.item import ContextItem, Sensitivity, TrustLevel
+from pyagent_context.ledger import ContextLedger
+from pyagent_context.lifecycle import ContextLifecycle
+from pyagent_context.memory.semantic import InMemorySemanticStore, SemanticMemoryProtocol
+from pyagent_context.memory.session import SessionMemory
+from pyagent_context.memory.working import WorkingMemory
+from pyagent_context.redaction import ContextRedactor
+from pyagent_context.retrieval import ScoredItem, TrustAwareRetriever
+
+__all__ = [
+    "CompressionPolicy",
+    "ContextCompressor",
+    "ContextItem",
+    "ContextLedger",
+    "ContextLifecycle",
+    "ContextRedactor",
+    "InMemorySemanticStore",
+    "ScoredItem",
+    "SemanticMemoryProtocol",
+    "Sensitivity",
+    "SessionMemory",
+    "TrustAwareRetriever",
+    "TrustLevel",
+    "WorkingMemory",
+]
+__version__ = "0.1.0"

pyagent_context/compression.py

@@ -0,0 +1,132 @@
+"""ContextCompressor: compression policies for context ledger management."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import TYPE_CHECKING
+
+from pyagent_context.item import ContextItem, TrustLevel
+from pyagent_context.ledger import ContextLedger
+
+if TYPE_CHECKING:
+    pass
+
+
+class CompressionPolicy(StrEnum):
+    """Available compression strategies."""
+
+    NONE = "none"
+    FIFO = "fifo"                               # drop oldest items
+    SEMANTIC_LOSSLESS = "semantic_lossless"      # compress text, keep Knowledge block
+    SAWTOOTH = "sawtooth"                        # compress to floor, grow again
+
+
+class ContextCompressor:
+    """Apply compression policies to a ContextLedger.
+
+    The compressor monitors token usage and compresses when a threshold
+    is reached.
+
+    Args:
+        policy: Compression strategy.
+        threshold_tokens: Token count that triggers compression.
+        floor_tokens: Token target after compression (for SAWTOOTH/FIFO).
+        preserve_trust: Items at or above this trust level are never dropped.
+    """
+
+    def __init__(
+        self,
+        policy: CompressionPolicy = CompressionPolicy.FIFO,
+        threshold_tokens: int = 10_000,
+        floor_tokens: int = 5_000,
+        preserve_trust: TrustLevel = TrustLevel.VERIFIED,
+    ) -> None:
+        self._policy = policy
+        self._threshold = threshold_tokens
+        self._floor = floor_tokens
+        self._preserve_trust = preserve_trust
+
+    @property
+    def policy(self) -> CompressionPolicy:
+        return self._policy
+
+    def should_compress(self, ledger: ContextLedger) -> bool:
+        """Check if the ledger's token count exceeds the threshold."""
+        if self._policy == CompressionPolicy.NONE:
+            return False
+        return ledger.total_tokens >= self._threshold
+
+    def compress(self, ledger: ContextLedger) -> ContextLedger:
+        """Apply the compression policy and return a new (compressed) ledger.
+
+        The original ledger is not mutated.
+        """
+        if self._policy == CompressionPolicy.NONE:
+            return ledger
+        if self._policy == CompressionPolicy.FIFO:
+            return self._compress_fifo(ledger)
+        if self._policy == CompressionPolicy.SEMANTIC_LOSSLESS:
+            return self._compress_semantic(ledger)
+        if self._policy == CompressionPolicy.SAWTOOTH:
+            return self._compress_sawtooth(ledger)
+        return ledger
+
+    def _compress_fifo(self, ledger: ContextLedger) -> ContextLedger:
+        """Drop oldest items until under floor, preserving high-trust items."""
+        items = list(ledger.items)
+        tokens = ledger.total_tokens
+
+        # Remove from front (oldest) until under floor
+        new_items: list[ContextItem] = []
+        for item in items:
+            if tokens <= self._floor:
+                new_items.append(item)
+            elif item.trust_level >= self._preserve_trust:
+                new_items.append(item)  # keep high-trust
+            else:
+                tokens -= item.token_estimate  # drop
+
+        return ContextLedger(items=new_items)
+
+    def _compress_semantic(self, ledger: ContextLedger) -> ContextLedger:
+        """Compress item content text while preserving verified items unchanged.
+
+        Uses simple sentence extraction — for full compression, integrate
+        ``MessageCompressor`` from ``pyagent-compress``.
+        """
+        items = list(ledger.items)
+        new_items: list[ContextItem] = []
+
+        for item in items:
+            if item.trust_level >= self._preserve_trust:
+                new_items.append(item)
+            else:
+                # Simple compression: keep first sentence only
+                sentences = item.content.split(". ")
+                compressed = sentences[0] + ("." if len(sentences) > 1 else "")
+                new_item = ContextItem(
+                    content=compressed,
+                    source=item.source,
+                    timestamp=item.timestamp,
+                    trust_level=item.trust_level,
+                    sensitivity=item.sensitivity,
+                    expires_at=item.expires_at,
+                    derived_from=item.id,
+                )
+                new_items.append(new_item)
+
+        return ContextLedger(items=new_items)
+
+    def _compress_sawtooth(self, ledger: ContextLedger) -> ContextLedger:
+        """Compress to floor, then allow growth again.
+
+        Combines FIFO eviction with semantic compression for remaining items.
+        """
+        # First pass: FIFO eviction
+        fifo_result = self._compress_fifo(ledger)
+
+        # If still over floor, apply semantic compression
+        if fifo_result.total_tokens > self._floor:
+            return self._compress_semantic(fifo_result)
+
+        return fifo_result

pyagent_context/item.py

@@ -0,0 +1,132 @@
+"""ContextItem: content + metadata with trust, sensitivity, and lifecycle."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from dataclasses import dataclass, field
+from enum import StrEnum
+
+
+class TrustLevel(StrEnum):
+    """Trust classification for context items."""
+
+    VERIFIED = "verified"       # from trusted source, validated
+    INFERRED = "inferred"       # LLM-generated, not validated
+    USER_PROVIDED = "user"      # direct user input
+    EXTERNAL = "external"       # from tool/API call
+
+    def __ge__(self, other: TrustLevel) -> bool:
+        order = {TrustLevel.INFERRED: 0, TrustLevel.EXTERNAL: 1, TrustLevel.USER_PROVIDED: 2, TrustLevel.VERIFIED: 3}
+        return order.get(self, 0) >= order.get(other, 0)
+
+    def __gt__(self, other: TrustLevel) -> bool:
+        return self != other and self.__ge__(other)
+
+    def __le__(self, other: TrustLevel) -> bool:
+        return other.__ge__(self)
+
+    def __lt__(self, other: TrustLevel) -> bool:
+        return self != other and self.__le__(other)
+
+
+# Numeric ordering for scoring
+TRUST_ORDER: dict[TrustLevel, int] = {
+    TrustLevel.INFERRED: 0,
+    TrustLevel.EXTERNAL: 1,
+    TrustLevel.USER_PROVIDED: 2,
+    TrustLevel.VERIFIED: 3,
+}
+
+
+class Sensitivity(StrEnum):
+    """Data sensitivity classification."""
+
+    PUBLIC = "public"
+    INTERNAL = "internal"
+    CONFIDENTIAL = "confidential"
+    RESTRICTED = "restricted"
+
+
+SENSITIVITY_ORDER: dict[Sensitivity, int] = {
+    Sensitivity.PUBLIC: 0,
+    Sensitivity.INTERNAL: 1,
+    Sensitivity.CONFIDENTIAL: 2,
+    Sensitivity.RESTRICTED: 3,
+}
+
+
+@dataclass
+class ContextItem:
+    """A single piece of context with trust and lifecycle metadata.
+
+    Attributes:
+        content: The text content.
+        source: Origin — agent name, tool name, or ``"user"``.
+        timestamp: Creation time (``time.time()``).
+        trust_level: How much to trust this item.
+        sensitivity: Data classification for redaction decisions.
+        expires_at: Expiration timestamp, or ``None`` for never.
+        derived_from: Parent item ID if this was derived from another.
+        token_estimate: Rough token count (``len(content) // 4``).
+    """
+
+    content: str
+    source: str
+    timestamp: float = field(default_factory=time.time)
+    trust_level: TrustLevel = TrustLevel.INFERRED
+    sensitivity: Sensitivity = Sensitivity.INTERNAL
+    expires_at: float | None = None
+    derived_from: str | None = None
+    token_estimate: int = 0
+    _id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+
+    def __post_init__(self) -> None:
+        if self.token_estimate == 0:
+            self.token_estimate = max(1, len(self.content) // 4)
+
+    @property
+    def id(self) -> str:
+        return self._id
+
+    @property
+    def is_expired(self) -> bool:
+        """Check if this item has passed its expiry time."""
+        if self.expires_at is None:
+            return False
+        return time.time() > self.expires_at
+
+    @property
+    def age_seconds(self) -> float:
+        """Time since creation in seconds."""
+        return time.time() - self.timestamp
+
+    def to_dict(self) -> dict:
+        """Serialize to a JSON-compatible dict."""
+        return {
+            "id": self._id,
+            "content": self.content,
+            "source": self.source,
+            "timestamp": self.timestamp,
+            "trust_level": self.trust_level.value,
+            "sensitivity": self.sensitivity.value,
+            "expires_at": self.expires_at,
+            "derived_from": self.derived_from,
+            "token_estimate": self.token_estimate,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ContextItem:
+        """Deserialize from a dict."""
+        item = cls(
+            content=data["content"],
+            source=data["source"],
+            timestamp=data["timestamp"],
+            trust_level=TrustLevel(data["trust_level"]),
+            sensitivity=Sensitivity(data["sensitivity"]),
+            expires_at=data.get("expires_at"),
+            derived_from=data.get("derived_from"),
+            token_estimate=data.get("token_estimate", 0),
+        )
+        item._id = data["id"]
+        return item

pyagent_context/ledger.py

@@ -0,0 +1,136 @@
+"""ContextLedger: append-only log of ContextItems with query, conversion, and snapshot."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from pyagent_patterns.base import Message
+from pyagent_context.item import ContextItem, TrustLevel, TRUST_ORDER
+
+
+class ContextLedger:
+    """Append-only ledger of context items.
+
+    Supports querying by trust level, age, and source. Converts items
+    to ``Message`` lists for use with patterns.
+
+    Args:
+        items: Optional initial items.
+    """
+
+    def __init__(self, items: list[ContextItem] | None = None) -> None:
+        self._items: list[ContextItem] = list(items) if items else []
+
+    def append(self, item: ContextItem) -> None:
+        """Add an item to the ledger."""
+        self._items.append(item)
+
+    def add(
+        self,
+        content: str,
+        source: str,
+        trust_level: TrustLevel = TrustLevel.INFERRED,
+        **kwargs: Any,
+    ) -> ContextItem:
+        """Create and append a new item in one step.
+
+        Returns:
+            The created ``ContextItem``.
+        """
+        item = ContextItem(content=content, source=source, trust_level=trust_level, **kwargs)
+        self._items.append(item)
+        return item
+
+    def query(
+        self,
+        *,
+        min_trust: TrustLevel | None = None,
+        max_age_seconds: float | None = None,
+        source: str | None = None,
+    ) -> list[ContextItem]:
+        """Filter items by trust level, age, and/or source.
+
+        Args:
+            min_trust: Only return items at or above this trust level.
+            max_age_seconds: Only return items newer than this.
+            source: Only return items from this source.
+
+        Returns:
+            Filtered list of items (chronological order).
+        """
+        now = time.time()
+        results: list[ContextItem] = []
+        for item in self._items:
+            if min_trust is not None and TRUST_ORDER.get(item.trust_level, 0) < TRUST_ORDER.get(min_trust, 0):
+                continue
+            if max_age_seconds is not None and (now - item.timestamp) > max_age_seconds:
+                continue
+            if source is not None and item.source != source:
+                continue
+            results.append(item)
+        return results
+
+    @property
+    def total_tokens(self) -> int:
+        """Sum of token estimates across all items."""
+        return sum(item.token_estimate for item in self._items)
+
+    def to_messages(self, max_tokens: int | None = None) -> list[Message]:
+        """Convert ledger items to a list of Messages.
+
+        If ``max_tokens`` is set, include items from most recent backward
+        until the budget is exhausted.
+
+        Args:
+            max_tokens: Optional token budget.
+
+        Returns:
+            List of ``Message`` objects.
+        """
+        if max_tokens is None:
+            return [
+                Message.assistant(item.content, name=item.source)
+                for item in self._items
+            ]
+
+        # Walk backward, accumulate until budget exhausted
+        selected: list[ContextItem] = []
+        budget = max_tokens
+        for item in reversed(self._items):
+            if item.token_estimate <= budget:
+                selected.append(item)
+                budget -= item.token_estimate
+            else:
+                break
+
+        selected.reverse()
+        return [Message.assistant(item.content, name=item.source) for item in selected]
+
+    def snapshot(self) -> dict:
+        """Serialize the full ledger to a JSON-compatible dict."""
+        return {
+            "items": [item.to_dict() for item in self._items],
+            "total_tokens": self.total_tokens,
+            "count": len(self._items),
+        }
+
+    @classmethod
+    def from_snapshot(cls, data: dict) -> ContextLedger:
+        """Restore a ledger from a snapshot dict."""
+        items = [ContextItem.from_dict(d) for d in data["items"]]
+        return cls(items=items)
+
+    @property
+    def items(self) -> list[ContextItem]:
+        return list(self._items)
+
+    def __len__(self) -> int:
+        return len(self._items)
+
+    def __bool__(self) -> bool:
+        return len(self._items) > 0
+
+    def clear(self) -> None:
+        """Remove all items."""
+        self._items.clear()

pyagent_context/lifecycle.py

@@ -0,0 +1,157 @@
+"""ContextLifecycle: expiration sweep, consolidation, and freshness decay."""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+
+from pyagent_context.item import ContextItem
+from pyagent_context.ledger import ContextLedger
+
+
+class ContextLifecycle:
+    """Manage the lifecycle of context items.
+
+    Provides:
+    - **Expiry sweep**: remove items past their ``expires_at``.
+    - **Freshness decay**: reduce token budgets for old items.
+    - **Consolidation**: merge items from the same source with similar content.
+
+    Args:
+        consolidation_threshold: Minimum keyword overlap ratio (0.0–1.0)
+            to consider two items similar enough to merge.
+    """
+
+    def __init__(self, consolidation_threshold: float = 0.6) -> None:
+        self._consolidation_threshold = consolidation_threshold
+
+    def sweep_expired(self, ledger: ContextLedger) -> tuple[ContextLedger, list[ContextItem]]:
+        """Remove expired items from the ledger.
+
+        Args:
+            ledger: The context ledger.
+
+        Returns:
+            Tuple of (new ledger without expired items, list of expired items).
+        """
+        now = time.time()
+        kept: list[ContextItem] = []
+        expired: list[ContextItem] = []
+
+        for item in ledger.items:
+            if item.expires_at is not None and now > item.expires_at:
+                expired.append(item)
+            else:
+                kept.append(item)
+
+        return ContextLedger(items=kept), expired
+
+    def apply_freshness_decay(
+        self,
+        ledger: ContextLedger,
+        half_life_seconds: float = 3600.0,
+        min_tokens: int = 1,
+    ) -> ContextLedger:
+        """Reduce token estimates based on age.
+
+        Older items get smaller token budgets, making them less likely
+        to survive compression. Items retain at least ``min_tokens``.
+
+        Args:
+            ledger: The context ledger.
+            half_life_seconds: Seconds for token estimate to halve.
+            min_tokens: Minimum token estimate after decay.
+
+        Returns:
+            New ledger with decayed token estimates.
+        """
+        import math
+
+        now = time.time()
+        new_items: list[ContextItem] = []
+
+        for item in ledger.items:
+            age = now - item.timestamp
+            decay_factor = math.exp(-age / half_life_seconds) if half_life_seconds > 0 else 1.0
+            decayed_tokens = max(min_tokens, int(item.token_estimate * decay_factor))
+
+            new_item = ContextItem(
+                content=item.content,
+                source=item.source,
+                timestamp=item.timestamp,
+                trust_level=item.trust_level,
+                sensitivity=item.sensitivity,
+                expires_at=item.expires_at,
+                derived_from=item.derived_from,
+                token_estimate=decayed_tokens,
+            )
+            new_item._id = item.id
+            new_items.append(new_item)
+
+        return ContextLedger(items=new_items)
+
+    def consolidate(self, ledger: ContextLedger) -> ContextLedger:
+        """Merge similar items from the same source.
+
+        When two items from the same source have high keyword overlap,
+        they are merged into one with combined content and the higher
+        trust level.
+
+        Args:
+            ledger: The context ledger.
+
+        Returns:
+            New ledger with consolidated items.
+        """
+        by_source: dict[str, list[ContextItem]] = defaultdict(list)
+        for item in ledger.items:
+            by_source[item.source].append(item)
+
+        consolidated: list[ContextItem] = []
+
+        for source, items in by_source.items():
+            merged_indices: set[int] = set()
+
+            for i, item_a in enumerate(items):
+                if i in merged_indices:
+                    continue
+                merged_content = item_a.content
+                best_trust = item_a.trust_level
+                latest_time = item_a.timestamp
+
+                for j in range(i + 1, len(items)):
+                    if j in merged_indices:
+                        continue
+                    item_b = items[j]
+                    if self._similarity(item_a.content, item_b.content) >= self._consolidation_threshold:
+                        merged_content = f"{merged_content}\n{item_b.content}"
+                        if item_b.trust_level > best_trust:
+                            best_trust = item_b.trust_level
+                        latest_time = max(latest_time, item_b.timestamp)
+                        merged_indices.add(j)
+
+                new_item = ContextItem(
+                    content=merged_content,
+                    source=source,
+                    timestamp=latest_time,
+                    trust_level=best_trust,
+                    sensitivity=item_a.sensitivity,
+                    expires_at=item_a.expires_at,
+                    derived_from=item_a.id,
+                )
+                consolidated.append(new_item)
+
+        # Sort by timestamp to maintain chronological order
+        consolidated.sort(key=lambda x: x.timestamp)
+        return ContextLedger(items=consolidated)
+
+    @staticmethod
+    def _similarity(text_a: str, text_b: str) -> float:
+        """Keyword overlap ratio (Jaccard-like)."""
+        words_a = set(text_a.lower().split())
+        words_b = set(text_b.lower().split())
+        if not words_a or not words_b:
+            return 0.0
+        intersection = words_a & words_b
+        union = words_a | words_b
+        return len(intersection) / len(union)

pyagent_context/memory/__init__.py

@@ -0,0 +1,12 @@
+"""Three-tier memory: working, session, and semantic."""
+
+from pyagent_context.memory.working import WorkingMemory
+from pyagent_context.memory.session import SessionMemory
+from pyagent_context.memory.semantic import SemanticMemoryProtocol, InMemorySemanticStore
+
+__all__ = [
+    "InMemorySemanticStore",
+    "SemanticMemoryProtocol",
+    "SessionMemory",
+    "WorkingMemory",
+]