pyagent-context 0.1.0__tar.gz → 0.2.3__tar.gz

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyagent-context
-Version: 0.1.0
+Version: 0.2.3
 Summary: Three-tier memory with trust-aware context ledger for multi-agent LLM systems
 Project-URL: Homepage, https://pyagent.org
 Project-URL: Repository, https://github.com/pyagent-core/pyagent
@@ -281,6 +281,200 @@ context_messages = ledger.to_messages(max_tokens=2000)
 ledger.add(result.output, "pipeline", TrustLevel.INFERRED)
 ```
 
+## Architecture — Three-Tier Memory Model
+
+```mermaid
+flowchart TD
+    subgraph Agent Interaction
+        A1[Agent 1] -->|append output| CL[ContextLedger]
+        CL -->|to_messages budget| A2[Agent 2 input]
+    end
+
+    subgraph Three-Tier Memory
+        CL --> WM[WorkingMemory — bounded deque, current turn]
+        CL --> SM[SessionMemory — JSON/SQLite, cross-turn persistence]
+        CL --> SEM[SemanticMemory — TF-IDF similarity, long-term recall]
+    end
+
+    subgraph Processing
+        CL --> CC[ContextCompressor — policy-based trimming]
+        CL --> TR[TrustAwareRetriever — ranked retrieval]
+        CL --> CR[ContextRedactor — sensitivity filtering]
+        CL --> LC[ContextLifecycle — expiry, decay, consolidation]
+    end
+```
+
+### Memory Tier Details
+
+| Tier | Class | Storage | Capacity | Eviction | Use Case |
+|------|-------|---------|----------|----------|----------|
+| **Working** | `WorkingMemory` | In-memory deque | `max_items` or `max_tokens` | Oldest-first when full | Current conversation turn |
+| **Session** | `SessionMemory` | JSON file or SQLite | Unlimited | Manual clear | Cross-turn persistence (multi-step workflows) |
+| **Semantic** | `InMemorySemanticStore` | In-memory TF-IDF index | Unlimited | Manual | Long-term recall via similarity search |
+
+### WorkingMemory Eviction
+
+When `WorkingMemory` reaches its `max_items` or `max_tokens` limit, the oldest items are evicted first. Utilization metrics are available:
+
+```python
+from pyagent_context import WorkingMemory
+
+wm = WorkingMemory(max_items=20, max_tokens=8000)
+wm.add(item)
+
+print(wm.utilization)     # 0.05 → 5% of max_items used
+print(wm.token_usage)     # current token estimate total
+print(len(wm))            # number of items in memory
+wm.clear()                # flush all items
+```
+
+### SessionMemory Backends
+
+```python
+from pyagent_context import SessionMemory
+
+# JSON backend — simple file-based persistence
+sm_json = SessionMemory(backend="json", path="session.json")
+
+# SQLite backend — more robust, concurrent-safe
+sm_sqlite = SessionMemory(backend="sqlite", path="session.db")
+
+sm_json.add(item)
+sm_json.save()            # persist to disk
+sm_json.load()            # reload from disk
+items = sm_json.retrieve(query="billing", top_k=5)
+```
+
+### SemanticMemory — TF-IDF Similarity Search
+
+The `InMemorySemanticStore` uses TF-IDF vectorization for similarity-based retrieval across the full context history:
+
+```python
+from pyagent_context import InMemorySemanticStore
+
+store = InMemorySemanticStore()
+store.add(item1)
+store.add(item2)
+store.add(item3)
+
+# Retrieve items most similar to the query
+results = store.search("billing question", top_k=3)
+for item, score in results:
+    print(f"[{score:.2f}] {item.content[:80]}...")
+```
+
+## ContextLedger — Token-Budgeted Message Conversion
+
+The `ContextLedger` is an append-only log that converts stored `ContextItem` objects into LLM-compatible messages with automatic token budgeting:
+
+```python
+from pyagent_context import ContextLedger, ContextItem, TrustLevel
+
+ledger = ContextLedger()
+ledger.append(ContextItem(content="Revenue was $25.2B", source="database", trust=TrustLevel.VERIFIED))
+ledger.append(ContextItem(content="Margin expanded to 17%", source="agent_1", trust=TrustLevel.INFERRED))
+
+# Convert to messages with a token budget
+# Higher-trust items are prioritized when budget is tight
+messages = ledger.to_messages(budget=4000)
+print(ledger.total_tokens())  # total token estimate across all items
+```
+
+## TrustAwareRetriever — Composite Scoring
+
+The retriever ranks items using a composite score of three signals:
+
+| Signal | Weight | Description |
+|--------|--------|-------------|
+| **Trust** | Configurable | `VERIFIED` > `INFERRED` > `USER_PROVIDED` > `UNVERIFIED` |
+| **Recency** | Half-life decay | Newer items score higher; decay rate is configurable |
+| **Relevance** | Keyword overlap | TF-IDF similarity between query and item content |
+
+```python
+from pyagent_context import TrustAwareRetriever
+
+retriever = TrustAwareRetriever(
+    trust_weight=0.4,
+    recency_weight=0.3,
+    relevance_weight=0.3,
+    half_life_hours=24.0,
+)
+results = retriever.retrieve(items, query="billing issue", top_k=5)
+```
+
+## Integration with pyagent-patterns
+
+Context flows between agents via the `ContextLedger`:
+
+```python
+from pyagent_patterns.base import Agent, MockLLM
+from pyagent_patterns.orchestration import Pipeline
+from pyagent_context import ContextLedger, ContextItem, TrustLevel
+
+ledger = ContextLedger()
+
+# Before agent execution: read context to prepend as system/user messages
+context_messages = ledger.to_messages(budget=4000)
+
+# After agent execution: write output as a new context item
+ledger.append(ContextItem(
+    content=result.output,
+    source="analyst",
+    trust=TrustLevel.INFERRED,
+))
+```
+
+In the hook-based integration model, agents automatically read from and write to the ledger when one is attached via `set_context()`.
+
+## Integration with pyagent-compress
+
+Two levels of compression work together:
+
+| Layer | Package | What It Compresses | How |
+|-------|---------|-------------------|-----|
+| **Message-level** | `pyagent-compress` | Individual agent outputs | Extractive: remove filler, rank sentences, keep top-N |
+| **Context-level** | `pyagent-context` | Accumulated context items | Policy-based: FIFO, semantic lossless, sawtooth |
+
+```python
+from pyagent_context import ContextCompressor, ContextLedger
+from pyagent_compress import MessageCompressor
+
+# Context compression: decide which items to keep
+compressor = ContextCompressor(policy="semantic_lossless")
+trimmed = compressor.compress(ledger.items(), target_tokens=4000)
+
+# Message compression: reduce verbosity of individual outputs
+msg_compressor = MessageCompressor(target_ratio=0.5)
+compressed = msg_compressor.compress(agent_output)
+```
+
+## Integration with pyagent-trace
+
+Context operations can be tracked via the `TraceEventBus`:
+
+- **Ledger writes** — When agents append items, trace events capture the source, trust level, and token count
+- **Memory tier transitions** — Working → session → semantic migrations emit trace events
+- **Retrieval** — Trust-aware retrieval results (scores, items selected) are logged for debugging
+- **Compression** — Context compression events show which items were kept/dropped and the token savings
+
+## Integration with pyagent-blueprint
+
+The `context` section of a blueprint YAML maps directly to context package configuration:
+
+```yaml
+context:
+  memory:
+    backend: sqlite
+    working_max_tokens: 128000
+  compression:
+    policy: semantic_lossless
+    target_ratio: 0.6
+  redaction:
+    max_sensitivity: internal
+```
+
+After `BlueprintCompiler.compile()`, these settings are available on the `RuntimeGraph` for the consumer to wire into agents.
+
 ## Full Documentation
 
-See [pyagent.dev](https://pyagent.dev) for full API reference and integration guides.
+See [pyagent.org](https://pyagent.org) for full API reference and integration guides.

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/README.md

@@ -250,6 +250,200 @@ context_messages = ledger.to_messages(max_tokens=2000)
 ledger.add(result.output, "pipeline", TrustLevel.INFERRED)
 ```
 
+## Architecture — Three-Tier Memory Model
+
+```mermaid
+flowchart TD
+    subgraph Agent Interaction
+        A1[Agent 1] -->|append output| CL[ContextLedger]
+        CL -->|to_messages budget| A2[Agent 2 input]
+    end
+
+    subgraph Three-Tier Memory
+        CL --> WM[WorkingMemory — bounded deque, current turn]
+        CL --> SM[SessionMemory — JSON/SQLite, cross-turn persistence]
+        CL --> SEM[SemanticMemory — TF-IDF similarity, long-term recall]
+    end
+
+    subgraph Processing
+        CL --> CC[ContextCompressor — policy-based trimming]
+        CL --> TR[TrustAwareRetriever — ranked retrieval]
+        CL --> CR[ContextRedactor — sensitivity filtering]
+        CL --> LC[ContextLifecycle — expiry, decay, consolidation]
+    end
+```
+
+### Memory Tier Details
+
+| Tier | Class | Storage | Capacity | Eviction | Use Case |
+|------|-------|---------|----------|----------|----------|
+| **Working** | `WorkingMemory` | In-memory deque | `max_items` or `max_tokens` | Oldest-first when full | Current conversation turn |
+| **Session** | `SessionMemory` | JSON file or SQLite | Unlimited | Manual clear | Cross-turn persistence (multi-step workflows) |
+| **Semantic** | `InMemorySemanticStore` | In-memory TF-IDF index | Unlimited | Manual | Long-term recall via similarity search |
+
+### WorkingMemory Eviction
+
+When `WorkingMemory` reaches its `max_items` or `max_tokens` limit, the oldest items are evicted first. Utilization metrics are available:
+
+```python
+from pyagent_context import WorkingMemory
+
+wm = WorkingMemory(max_items=20, max_tokens=8000)
+wm.add(item)
+
+print(wm.utilization)     # 0.05 → 5% of max_items used
+print(wm.token_usage)     # current token estimate total
+print(len(wm))            # number of items in memory
+wm.clear()                # flush all items
+```
+
+### SessionMemory Backends
+
+```python
+from pyagent_context import SessionMemory
+
+# JSON backend — simple file-based persistence
+sm_json = SessionMemory(backend="json", path="session.json")
+
+# SQLite backend — more robust, concurrent-safe
+sm_sqlite = SessionMemory(backend="sqlite", path="session.db")
+
+sm_json.add(item)
+sm_json.save()            # persist to disk
+sm_json.load()            # reload from disk
+items = sm_json.retrieve(query="billing", top_k=5)
+```
+
+### SemanticMemory — TF-IDF Similarity Search
+
+The `InMemorySemanticStore` uses TF-IDF vectorization for similarity-based retrieval across the full context history:
+
+```python
+from pyagent_context import InMemorySemanticStore
+
+store = InMemorySemanticStore()
+store.add(item1)
+store.add(item2)
+store.add(item3)
+
+# Retrieve items most similar to the query
+results = store.search("billing question", top_k=3)
+for item, score in results:
+    print(f"[{score:.2f}] {item.content[:80]}...")
+```
+
+## ContextLedger — Token-Budgeted Message Conversion
+
+The `ContextLedger` is an append-only log that converts stored `ContextItem` objects into LLM-compatible messages with automatic token budgeting:
+
+```python
+from pyagent_context import ContextLedger, ContextItem, TrustLevel
+
+ledger = ContextLedger()
+ledger.append(ContextItem(content="Revenue was $25.2B", source="database", trust=TrustLevel.VERIFIED))
+ledger.append(ContextItem(content="Margin expanded to 17%", source="agent_1", trust=TrustLevel.INFERRED))
+
+# Convert to messages with a token budget
+# Higher-trust items are prioritized when budget is tight
+messages = ledger.to_messages(budget=4000)
+print(ledger.total_tokens())  # total token estimate across all items
+```
+
+## TrustAwareRetriever — Composite Scoring
+
+The retriever ranks items using a composite score of three signals:
+
+| Signal | Weight | Description |
+|--------|--------|-------------|
+| **Trust** | Configurable | `VERIFIED` > `INFERRED` > `USER_PROVIDED` > `UNVERIFIED` |
+| **Recency** | Half-life decay | Newer items score higher; decay rate is configurable |
+| **Relevance** | Keyword overlap | TF-IDF similarity between query and item content |
+
+```python
+from pyagent_context import TrustAwareRetriever
+
+retriever = TrustAwareRetriever(
+    trust_weight=0.4,
+    recency_weight=0.3,
+    relevance_weight=0.3,
+    half_life_hours=24.0,
+)
+results = retriever.retrieve(items, query="billing issue", top_k=5)
+```
+
+## Integration with pyagent-patterns
+
+Context flows between agents via the `ContextLedger`:
+
+```python
+from pyagent_patterns.base import Agent, MockLLM
+from pyagent_patterns.orchestration import Pipeline
+from pyagent_context import ContextLedger, ContextItem, TrustLevel
+
+ledger = ContextLedger()
+
+# Before agent execution: read context to prepend as system/user messages
+context_messages = ledger.to_messages(budget=4000)
+
+# After agent execution: write output as a new context item
+ledger.append(ContextItem(
+    content=result.output,
+    source="analyst",
+    trust=TrustLevel.INFERRED,
+))
+```
+
+In the hook-based integration model, agents automatically read from and write to the ledger when one is attached via `set_context()`.
+
+## Integration with pyagent-compress
+
+Two levels of compression work together:
+
+| Layer | Package | What It Compresses | How |
+|-------|---------|-------------------|-----|
+| **Message-level** | `pyagent-compress` | Individual agent outputs | Extractive: remove filler, rank sentences, keep top-N |
+| **Context-level** | `pyagent-context` | Accumulated context items | Policy-based: FIFO, semantic lossless, sawtooth |
+
+```python
+from pyagent_context import ContextCompressor, ContextLedger
+from pyagent_compress import MessageCompressor
+
+# Context compression: decide which items to keep
+compressor = ContextCompressor(policy="semantic_lossless")
+trimmed = compressor.compress(ledger.items(), target_tokens=4000)
+
+# Message compression: reduce verbosity of individual outputs
+msg_compressor = MessageCompressor(target_ratio=0.5)
+compressed = msg_compressor.compress(agent_output)
+```
+
+## Integration with pyagent-trace
+
+Context operations can be tracked via the `TraceEventBus`:
+
+- **Ledger writes** — When agents append items, trace events capture the source, trust level, and token count
+- **Memory tier transitions** — Working → session → semantic migrations emit trace events
+- **Retrieval** — Trust-aware retrieval results (scores, items selected) are logged for debugging
+- **Compression** — Context compression events show which items were kept/dropped and the token savings
+
+## Integration with pyagent-blueprint
+
+The `context` section of a blueprint YAML maps directly to context package configuration:
+
+```yaml
+context:
+  memory:
+    backend: sqlite
+    working_max_tokens: 128000
+  compression:
+    policy: semantic_lossless
+    target_ratio: 0.6
+  redaction:
+    max_sensitivity: internal
+```
+
+After `BlueprintCompiler.compile()`, these settings are available on the `RuntimeGraph` for the consumer to wire into agents.
+
 ## Full Documentation
 
-See [pyagent.dev](https://pyagent.dev) for full API reference and integration guides.
+See [pyagent.org](https://pyagent.org) for full API reference and integration guides.

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyagent-context"
-version = "0.1.0"
+version = "0.2.3"
 description = "Three-tier memory with trust-aware context ledger for multi-agent LLM systems"
 readme = "README.md"
 requires-python = ">=3.11"

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/compression.py

@@ -3,22 +3,18 @@
 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
+    FIFO = "fifo"  # drop oldest items
+    SEMANTIC_LOSSLESS = "semantic_lossless"  # compress text, keep Knowledge block
+    SAWTOOTH = "sawtooth"  # compress to floor, grow again
 
 
 class ContextCompressor:

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/item.py

@@ -11,13 +11,18 @@ 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
+    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}
+        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:

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/ledger.py

@@ -6,7 +6,8 @@ import time
 from typing import Any
 
 from pyagent_patterns.base import Message
-from pyagent_context.item import ContextItem, TrustLevel, TRUST_ORDER
+
+from pyagent_context.item import TRUST_ORDER, ContextItem, TrustLevel
 
 
 class ContextLedger:
@@ -62,7 +63,9 @@ class ContextLedger:
         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):
+            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
@@ -89,10 +92,7 @@ class ContextLedger:
             List of ``Message`` objects.
         """
         if max_tokens is None:
-            return [
-                Message.assistant(item.content, name=item.source)
-                for item in self._items
-            ]
+            return [Message.assistant(item.content, name=item.source) for item in self._items]
 
         # Walk backward, accumulate until budget exhausted
         selected: list[ContextItem] = []

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/lifecycle.py

@@ -18,7 +18,7 @@ class ContextLifecycle:
     - **Consolidation**: merge items from the same source with similar content.
 
     Args:
-        consolidation_threshold: Minimum keyword overlap ratio (0.0–1.0)
+        consolidation_threshold: Minimum keyword overlap ratio (0.0-1.0)
             to consider two items similar enough to merge.
     """
 
@@ -123,7 +123,10 @@ class ContextLifecycle:
                     if j in merged_indices:
                         continue
                     item_b = items[j]
-                    if self._similarity(item_a.content, item_b.content) >= self._consolidation_threshold:
+                    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

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/memory/__init__.py

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

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/memory/semantic.py

@@ -4,10 +4,11 @@ from __future__ import annotations
 
 import math
 from collections import Counter
-from dataclasses import dataclass, field
-from typing import Protocol, runtime_checkable
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Protocol, runtime_checkable
 
-from pyagent_context.item import ContextItem
+if TYPE_CHECKING:
+    from pyagent_context.item import ContextItem
 
 
 @dataclass(frozen=True)
@@ -16,7 +17,7 @@ class SearchResult:
 
     Attributes:
         item: The matching context item.
-        score: Relevance score (0.0–1.0).
+        score: Relevance score (0.0-1.0).
     """
 
     item: ContextItem
@@ -60,18 +61,100 @@ class InMemorySemanticStore:
         self._items: dict[str, ContextItem] = {}
         self._tf_cache: dict[str, dict[str, float]] = {}
         self._stop_words = stop_words or {
-            "a", "an", "the", "is", "are", "was", "were", "be", "been",
-            "being", "have", "has", "had", "do", "does", "did", "will",
-            "would", "could", "should", "may", "might", "can", "shall",
-            "to", "of", "in", "for", "on", "with", "at", "by", "from",
-            "as", "into", "through", "during", "before", "after", "and",
-            "but", "or", "nor", "not", "so", "yet", "both", "either",
-            "neither", "each", "every", "all", "any", "few", "more",
-            "most", "other", "some", "such", "no", "only", "own", "same",
-            "than", "too", "very", "just", "because", "about", "between",
-            "it", "its", "this", "that", "these", "those", "i", "me",
-            "my", "we", "our", "you", "your", "he", "him", "his", "she",
-            "her", "they", "them", "their", "what", "which", "who",
+            "a",
+            "an",
+            "the",
+            "is",
+            "are",
+            "was",
+            "were",
+            "be",
+            "been",
+            "being",
+            "have",
+            "has",
+            "had",
+            "do",
+            "does",
+            "did",
+            "will",
+            "would",
+            "could",
+            "should",
+            "may",
+            "might",
+            "can",
+            "shall",
+            "to",
+            "of",
+            "in",
+            "for",
+            "on",
+            "with",
+            "at",
+            "by",
+            "from",
+            "as",
+            "into",
+            "through",
+            "during",
+            "before",
+            "after",
+            "and",
+            "but",
+            "or",
+            "nor",
+            "not",
+            "so",
+            "yet",
+            "both",
+            "either",
+            "neither",
+            "each",
+            "every",
+            "all",
+            "any",
+            "few",
+            "more",
+            "most",
+            "other",
+            "some",
+            "such",
+            "no",
+            "only",
+            "own",
+            "same",
+            "than",
+            "too",
+            "very",
+            "just",
+            "because",
+            "about",
+            "between",
+            "it",
+            "its",
+            "this",
+            "that",
+            "these",
+            "those",
+            "i",
+            "me",
+            "my",
+            "we",
+            "our",
+            "you",
+            "your",
+            "he",
+            "him",
+            "his",
+            "she",
+            "her",
+            "they",
+            "them",
+            "their",
+            "what",
+            "which",
+            "who",
         }
 
     def add(self, item: ContextItem) -> None:
@@ -118,7 +201,11 @@ class InMemorySemanticStore:
 
     def _tokenize(self, text: str) -> list[str]:
         words = text.lower().split()
-        return [w.strip(".,!?;:\"'()[]{}") for w in words if w.strip(".,!?;:\"'()[]{}") not in self._stop_words]
+        return [
+            w.strip(".,!?;:\"'()[]{}")
+            for w in words
+            if w.strip(".,!?;:\"'()[]{}") not in self._stop_words
+        ]
 
     def _compute_tf(self, text: str) -> dict[str, float]:
         tokens = self._tokenize(text)
@@ -146,8 +233,8 @@ class InMemorySemanticStore:
         if not common_keys:
             return 0.0
         dot = sum(a[k] * b[k] for k in common_keys)
-        mag_a = math.sqrt(sum(v ** 2 for v in a.values()))
-        mag_b = math.sqrt(sum(v ** 2 for v in b.values()))
+        mag_a = math.sqrt(sum(v**2 for v in a.values()))
+        mag_b = math.sqrt(sum(v**2 for v in b.values()))
         if mag_a == 0 or mag_b == 0:
             return 0.0
         return dot / (mag_a * mag_b)

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/memory/session.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import json
 import sqlite3
 from pathlib import Path
-from typing import Any
 
 from pyagent_context.item import ContextItem
 

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/memory/working.py

@@ -3,8 +3,10 @@
 from __future__ import annotations
 
 from collections import deque
+from typing import TYPE_CHECKING
 
-from pyagent_context.item import ContextItem
+if TYPE_CHECKING:
+    from pyagent_context.item import ContextItem
 
 
 class WorkingMemory:

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/redaction.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from pyagent_context.item import ContextItem, Sensitivity, SENSITIVITY_ORDER
+from pyagent_context.item import SENSITIVITY_ORDER, ContextItem, Sensitivity
 from pyagent_context.ledger import ContextLedger
 
 

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/src/pyagent_context/retrieval.py

@@ -1,13 +1,16 @@
-"""TrustAwareRetriever: score candidates by trust × recency × relevance."""
+"""TrustAwareRetriever: score candidates by trust x recency x relevance."""
 
 from __future__ import annotations
 
 import math
 import time
 from dataclasses import dataclass
+from typing import TYPE_CHECKING
 
-from pyagent_context.item import ContextItem, TRUST_ORDER
-from pyagent_context.ledger import ContextLedger
+from pyagent_context.item import TRUST_ORDER, ContextItem
+
+if TYPE_CHECKING:
+    from pyagent_context.ledger import ContextLedger
 
 
 @dataclass(frozen=True)
@@ -16,7 +19,7 @@ class ScoredItem:
 
     Attributes:
         item: The context item.
-        score: Composite score (0.0–1.0).
+        score: Composite score (0.0-1.0).
         trust_score: Trust component of the score.
         recency_score: Recency component of the score.
         relevance_score: Relevance component of the score.
@@ -92,9 +95,7 @@ class TrustAwareRetriever:
             relevance = self._keyword_relevance(item.content, query_words)
 
             score = (
-                self._w_trust * trust
-                + self._w_recency * recency
-                + self._w_relevance * relevance
+                self._w_trust * trust + self._w_recency * recency + self._w_relevance * relevance
             )
 
             if score >= min_score:

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/tests/test_compression.py

@@ -14,12 +14,14 @@ def _make_ledger(n: int, tokens_per_item: int = 100) -> ContextLedger:
     ledger = ContextLedger()
     for i in range(n):
         content = f"Item {i}: " + "x" * (tokens_per_item * 4)
-        ledger.append(ContextItem(
-            content=content,
-            source="test",
-            timestamp=time.time() - (n - i),
-            token_estimate=tokens_per_item,
-        ))
+        ledger.append(
+            ContextItem(
+                content=content,
+                source="test",
+                timestamp=time.time() - (n - i),
+                token_estimate=tokens_per_item,
+            )
+        )
     return ledger
 
 
@@ -54,18 +56,22 @@ def test_fifo_compress() -> None:
 
 def test_fifo_preserves_verified() -> None:
     ledger = ContextLedger()
-    ledger.append(ContextItem(
-        content="Verified fact",
-        source="test",
-        trust_level=TrustLevel.VERIFIED,
-        token_estimate=100,
-    ))
-    for i in range(9):
-        ledger.append(ContextItem(
-            content=f"Inferred {i}",
+    ledger.append(
+        ContextItem(
+            content="Verified fact",
             source="test",
+            trust_level=TrustLevel.VERIFIED,
             token_estimate=100,
-        ))
+        )
+    )
+    for i in range(9):
+        ledger.append(
+            ContextItem(
+                content=f"Inferred {i}",
+                source="test",
+                token_estimate=100,
+            )
+        )
 
     compressor = ContextCompressor(
         policy=CompressionPolicy.FIFO,
@@ -79,17 +85,21 @@ def test_fifo_preserves_verified() -> None:
 
 def test_semantic_lossless() -> None:
     ledger = ContextLedger()
-    ledger.append(ContextItem(
-        content="First sentence. Second sentence. Third sentence.",
-        source="test",
-        token_estimate=50,
-    ))
-    ledger.append(ContextItem(
-        content="Verified content stays intact",
-        source="test",
-        trust_level=TrustLevel.VERIFIED,
-        token_estimate=50,
-    ))
+    ledger.append(
+        ContextItem(
+            content="First sentence. Second sentence. Third sentence.",
+            source="test",
+            token_estimate=50,
+        )
+    )
+    ledger.append(
+        ContextItem(
+            content="Verified content stays intact",
+            source="test",
+            trust_level=TrustLevel.VERIFIED,
+            token_estimate=50,
+        )
+    )
 
     compressor = ContextCompressor(
         policy=CompressionPolicy.SEMANTIC_LOSSLESS,

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/tests/test_ledger.py

@@ -8,7 +8,9 @@ from pyagent_context.item import ContextItem, TrustLevel
 from pyagent_context.ledger import ContextLedger
 
 
-def _make_item(content: str, source: str = "agent", trust: TrustLevel = TrustLevel.INFERRED, age: float = 0.0) -> ContextItem:
+def _make_item(
+    content: str, source: str = "agent", trust: TrustLevel = TrustLevel.INFERRED, age: float = 0.0
+) -> ContextItem:
     return ContextItem(
         content=content,
         source=source,
@@ -44,7 +46,7 @@ def test_query_by_trust() -> None:
 def test_query_by_age() -> None:
     ledger = ContextLedger()
     ledger.append(_make_item("old", age=7200))  # 2 hours ago
-    ledger.append(_make_item("new", age=60))     # 1 minute ago
+    ledger.append(_make_item("new", age=60))  # 1 minute ago
 
     results = ledger.query(max_age_seconds=3600)
     assert len(results) == 1

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/tests/test_lifecycle.py

@@ -26,19 +26,23 @@ def test_sweep_expired() -> None:
 def test_freshness_decay() -> None:
     ledger = ContextLedger()
     # Old item: 2 hours ago
-    ledger.append(ContextItem(
-        content="old item",
-        source="s",
-        timestamp=time.time() - 7200,
-        token_estimate=100,
-    ))
+    ledger.append(
+        ContextItem(
+            content="old item",
+            source="s",
+            timestamp=time.time() - 7200,
+            token_estimate=100,
+        )
+    )
     # New item: just now
-    ledger.append(ContextItem(
-        content="new item",
-        source="s",
-        timestamp=time.time(),
-        token_estimate=100,
-    ))
+    ledger.append(
+        ContextItem(
+            content="new item",
+            source="s",
+            timestamp=time.time(),
+            token_estimate=100,
+        )
+    )
 
     lifecycle = ContextLifecycle()
     decayed = lifecycle.apply_freshness_decay(ledger, half_life_seconds=3600)
@@ -53,21 +57,27 @@ def test_freshness_decay() -> None:
 def test_consolidation() -> None:
     ledger = ContextLedger()
     # Two similar items from same source
-    ledger.append(ContextItem(
-        content="Python asyncio patterns for concurrency",
-        source="researcher",
-        trust_level=TrustLevel.INFERRED,
-    ))
-    ledger.append(ContextItem(
-        content="Python asyncio patterns for parallel tasks",
-        source="researcher",
-        trust_level=TrustLevel.VERIFIED,
-    ))
+    ledger.append(
+        ContextItem(
+            content="Python asyncio patterns for concurrency",
+            source="researcher",
+            trust_level=TrustLevel.INFERRED,
+        )
+    )
+    ledger.append(
+        ContextItem(
+            content="Python asyncio patterns for parallel tasks",
+            source="researcher",
+            trust_level=TrustLevel.VERIFIED,
+        )
+    )
     # Different source
-    ledger.append(ContextItem(
-        content="JavaScript React hooks",
-        source="frontend_agent",
-    ))
+    ledger.append(
+        ContextItem(
+            content="JavaScript React hooks",
+            source="frontend_agent",
+        )
+    )
 
     lifecycle = ContextLifecycle(consolidation_threshold=0.4)
     consolidated = lifecycle.consolidate(ledger)

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/tests/test_memory.py

@@ -3,16 +3,15 @@
 from __future__ import annotations
 
 import tempfile
-from pathlib import Path
 
-from pyagent_context.item import ContextItem, TrustLevel
-from pyagent_context.memory.working import WorkingMemory
-from pyagent_context.memory.session import SessionMemory
+from pyagent_context.item import ContextItem
 from pyagent_context.memory.semantic import InMemorySemanticStore
-
+from pyagent_context.memory.session import SessionMemory
+from pyagent_context.memory.working import WorkingMemory
 
 # ── WorkingMemory ─────────────────────────────────────────────────────
 
+
 def test_working_memory_add() -> None:
     wm = WorkingMemory(max_items=10, max_tokens=5000)
     item = ContextItem(content="hello", source="test")
@@ -48,6 +47,7 @@ def test_working_memory_utilization() -> None:
 
 # ── SessionMemory (JSON) ─────────────────────────────────────────────
 
+
 def test_session_memory_json_persist() -> None:
     with tempfile.TemporaryDirectory() as tmpdir:
         sm = SessionMemory("test-session", backend="json", storage_path=tmpdir)
@@ -73,6 +73,7 @@ def test_session_memory_json_clear() -> None:
 
 # ── SessionMemory (SQLite) ───────────────────────────────────────────
 
+
 def test_session_memory_sqlite_persist() -> None:
     with tempfile.TemporaryDirectory() as tmpdir:
         sm = SessionMemory("test-session", backend="sqlite", storage_path=tmpdir)
@@ -88,6 +89,7 @@ def test_session_memory_sqlite_persist() -> None:
 
 # ── InMemorySemanticStore ────────────────────────────────────────────
 
+
 def test_semantic_add_and_search() -> None:
     store = InMemorySemanticStore()
     store.add(ContextItem(content="Python asyncio event loop concurrency", source="docs"))
@@ -97,7 +99,9 @@ def test_semantic_add_and_search() -> None:
     results = store.search("Python async web")
     assert len(results) > 0
     # Python items should score higher
-    assert "python" in results[0].item.content.lower() or "python" in results[0].item.content.lower()
+    assert (
+        "python" in results[0].item.content.lower() or "python" in results[0].item.content.lower()
+    )
 
 
 def test_semantic_remove() -> None:

{pyagent_context-0.1.0 → pyagent_context-0.2.3}/tests/test_retrieval.py

@@ -27,18 +27,22 @@ def test_retrieval_ranks_by_relevance() -> None:
 def test_retrieval_ranks_by_trust() -> None:
     now = time.time()
     ledger = ContextLedger()
-    ledger.append(ContextItem(
-        content="Database connection pooling",
-        source="s",
-        trust_level=TrustLevel.INFERRED,
-        timestamp=now,
-    ))
-    ledger.append(ContextItem(
-        content="Database connection pooling",
-        source="s",
-        trust_level=TrustLevel.VERIFIED,
-        timestamp=now,
-    ))
+    ledger.append(
+        ContextItem(
+            content="Database connection pooling",
+            source="s",
+            trust_level=TrustLevel.INFERRED,
+            timestamp=now,
+        )
+    )
+    ledger.append(
+        ContextItem(
+            content="Database connection pooling",
+            source="s",
+            trust_level=TrustLevel.VERIFIED,
+            timestamp=now,
+        )
+    )
 
     retriever = TrustAwareRetriever(weight_trust=0.9, weight_relevance=0.05, weight_recency=0.05)
     results = retriever.retrieve(ledger, "database connection")
@@ -50,11 +54,13 @@ def test_retrieval_ranks_by_trust() -> None:
 
 def test_retrieval_excludes_expired() -> None:
     ledger = ContextLedger()
-    ledger.append(ContextItem(
-        content="expired item about Python",
-        source="s",
-        expires_at=time.time() - 10,
-    ))
+    ledger.append(
+        ContextItem(
+            content="expired item about Python",
+            source="s",
+            expires_at=time.time() - 10,
+        )
+    )
     ledger.append(ContextItem(content="active item about Python", source="s"))
 
     retriever = TrustAwareRetriever()