nodus-context 0.1.0__tar.gz

nodus_context-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shawn Knight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nodus_context-0.1.0/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: nodus-context
+Version: 0.1.0
+Summary: LLM context window management: token budget, compaction strategies, tool result guards
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-context
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-context
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.5.0; extra == "tiktoken"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# nodus-context
+
+**LLM context window management: token budget, compaction strategies, and
+tool result guards for AI systems.**
+
+Keeps agent conversations within finite LLM context windows without manual
+message pruning. No required external dependencies — token counting uses a
+word-count estimate by default; install `tiktoken` for accurate counts.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-context
+
+# With accurate tiktoken-based token counting:
+pip install "nodus-context[tiktoken]"
+```
+
+---
+
+## What it provides
+
+| Component | Purpose |
+|---|---|
+| `ContextBudget` | Token budget with utilization tracking and overflow detection |
+| `ContextMessage` | Normalized message (role, content, token count) |
+| `ContextWindow` | Message list with budget enforcement and compaction |
+| `DropToolInternalsStrategy` | Remove intermediate tool calls, keep final pairs |
+| `SummarizeStrategy` | Keep head + tail, replace middle with a summary message |
+| `estimate_tokens` / `count_tokens` | Word-estimate or tiktoken-accurate counting |
+
+---
+
+## Quick start
+
+```python
+from nodus_context import ContextWindow, ContextBudget, ROLE_USER, ROLE_ASSISTANT
+
+budget = ContextBudget(max_tokens=8192)
+window = ContextWindow(budget=budget)
+
+window.add(ROLE_USER, "What is the capital of France?")
+window.add(ROLE_ASSISTANT, "The capital of France is Paris.")
+
+messages = window.messages()   # list of ContextMessage
+print(f"Using {budget.used}/{budget.max_tokens} tokens")
+```
+
+---
+
+## ContextBudget
+
+```python
+from nodus_context import ContextBudget
+
+budget = ContextBudget(max_tokens=4096, reserve_tokens=512)
+budget.add(150)                # record token usage
+budget.utilization             # float 0.0–1.0
+budget.available               # tokens remaining (respects reserve)
+budget.is_over_budget          # True if used > max_tokens
+budget.reset()
+```
+
+---
+
+## ContextWindow
+
+```python
+from nodus_context import ContextWindow, ContextBudget, DropToolInternalsStrategy
+
+window = ContextWindow(
+    budget=ContextBudget(max_tokens=8192),
+    compaction_strategy=DropToolInternalsStrategy(),
+    compaction_threshold=0.85,   # compact when 85% full
+)
+
+window.add(role, content)         # adds message, tracks tokens
+window.add_raw(context_message)   # add pre-built ContextMessage
+window.messages()                 # current message list
+window.compact()                  # trigger compaction manually
+window.guard_tool_results(n=2)    # keep only the last n tool result pairs
+window.token_count                # current total
+window.message_count
+```
+
+Compaction runs automatically when `utilization >= compaction_threshold`.
+
+---
+
+## Compaction strategies
+
+### DropToolInternalsStrategy
+
+Removes intermediate `tool_use` / `tool_result` pairs, keeping only the
+final `n` pairs. Reduces context without losing the outcome.
+
+```python
+from nodus_context import DropToolInternalsStrategy
+strategy = DropToolInternalsStrategy(keep_last_n_pairs=1)
+```
+
+### SummarizeStrategy
+
+Keeps the first `head_count` and last `tail_count` messages; replaces
+everything in between with a single summary message.
+
+```python
+from nodus_context import SummarizeStrategy
+strategy = SummarizeStrategy(
+    head_count=2,
+    tail_count=4,
+    summary_fn=lambda msgs: "Summary of intermediate steps.",
+)
+```
+
+`summary_fn` can call an LLM — any callable that takes a list of
+`ContextMessage` and returns a string.
+
+---
+
+## Token counting
+
+```python
+from nodus_context import estimate_tokens, count_tokens
+
+estimate_tokens("Hello, world!")   # fast word-count estimate (no dep)
+count_tokens("Hello, world!")      # tiktoken if installed, else estimate
+```
+
+Install `nodus-context[tiktoken]` for accurate counts.
+
+---
+
+## Role constants
+
+```python
+from nodus_context import (
+    ROLE_USER, ROLE_ASSISTANT, ROLE_SYSTEM,
+    ROLE_TOOL_USE, ROLE_TOOL_RESULT, ROLE_THINKING,
+)
+```
+
+---
+
+## Design
+
+- **No required dependencies.** Token estimation uses `~4 chars per token`
+  heuristic. Accurate counting requires `tiktoken` (optional extra).
+- **Protocol-based strategies.** Any callable satisfying `CompactionStrategy`
+  works — no inheritance needed.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nodus_context-0.1.0/README.md

@@ -0,0 +1,169 @@
+# nodus-context
+
+**LLM context window management: token budget, compaction strategies, and
+tool result guards for AI systems.**
+
+Keeps agent conversations within finite LLM context windows without manual
+message pruning. No required external dependencies — token counting uses a
+word-count estimate by default; install `tiktoken` for accurate counts.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-context
+
+# With accurate tiktoken-based token counting:
+pip install "nodus-context[tiktoken]"
+```
+
+---
+
+## What it provides
+
+| Component | Purpose |
+|---|---|
+| `ContextBudget` | Token budget with utilization tracking and overflow detection |
+| `ContextMessage` | Normalized message (role, content, token count) |
+| `ContextWindow` | Message list with budget enforcement and compaction |
+| `DropToolInternalsStrategy` | Remove intermediate tool calls, keep final pairs |
+| `SummarizeStrategy` | Keep head + tail, replace middle with a summary message |
+| `estimate_tokens` / `count_tokens` | Word-estimate or tiktoken-accurate counting |
+
+---
+
+## Quick start
+
+```python
+from nodus_context import ContextWindow, ContextBudget, ROLE_USER, ROLE_ASSISTANT
+
+budget = ContextBudget(max_tokens=8192)
+window = ContextWindow(budget=budget)
+
+window.add(ROLE_USER, "What is the capital of France?")
+window.add(ROLE_ASSISTANT, "The capital of France is Paris.")
+
+messages = window.messages()   # list of ContextMessage
+print(f"Using {budget.used}/{budget.max_tokens} tokens")
+```
+
+---
+
+## ContextBudget
+
+```python
+from nodus_context import ContextBudget
+
+budget = ContextBudget(max_tokens=4096, reserve_tokens=512)
+budget.add(150)                # record token usage
+budget.utilization             # float 0.0–1.0
+budget.available               # tokens remaining (respects reserve)
+budget.is_over_budget          # True if used > max_tokens
+budget.reset()
+```
+
+---
+
+## ContextWindow
+
+```python
+from nodus_context import ContextWindow, ContextBudget, DropToolInternalsStrategy
+
+window = ContextWindow(
+    budget=ContextBudget(max_tokens=8192),
+    compaction_strategy=DropToolInternalsStrategy(),
+    compaction_threshold=0.85,   # compact when 85% full
+)
+
+window.add(role, content)         # adds message, tracks tokens
+window.add_raw(context_message)   # add pre-built ContextMessage
+window.messages()                 # current message list
+window.compact()                  # trigger compaction manually
+window.guard_tool_results(n=2)    # keep only the last n tool result pairs
+window.token_count                # current total
+window.message_count
+```
+
+Compaction runs automatically when `utilization >= compaction_threshold`.
+
+---
+
+## Compaction strategies
+
+### DropToolInternalsStrategy
+
+Removes intermediate `tool_use` / `tool_result` pairs, keeping only the
+final `n` pairs. Reduces context without losing the outcome.
+
+```python
+from nodus_context import DropToolInternalsStrategy
+strategy = DropToolInternalsStrategy(keep_last_n_pairs=1)
+```
+
+### SummarizeStrategy
+
+Keeps the first `head_count` and last `tail_count` messages; replaces
+everything in between with a single summary message.
+
+```python
+from nodus_context import SummarizeStrategy
+strategy = SummarizeStrategy(
+    head_count=2,
+    tail_count=4,
+    summary_fn=lambda msgs: "Summary of intermediate steps.",
+)
+```
+
+`summary_fn` can call an LLM — any callable that takes a list of
+`ContextMessage` and returns a string.
+
+---
+
+## Token counting
+
+```python
+from nodus_context import estimate_tokens, count_tokens
+
+estimate_tokens("Hello, world!")   # fast word-count estimate (no dep)
+count_tokens("Hello, world!")      # tiktoken if installed, else estimate
+```
+
+Install `nodus-context[tiktoken]` for accurate counts.
+
+---
+
+## Role constants
+
+```python
+from nodus_context import (
+    ROLE_USER, ROLE_ASSISTANT, ROLE_SYSTEM,
+    ROLE_TOOL_USE, ROLE_TOOL_RESULT, ROLE_THINKING,
+)
+```
+
+---
+
+## Design
+
+- **No required dependencies.** Token estimation uses `~4 chars per token`
+  heuristic. Accurate counting requires `tiktoken` (optional extra).
+- **Protocol-based strategies.** Any callable satisfying `CompactionStrategy`
+  works — no inheritance needed.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nodus_context-0.1.0/nodus_context/__init__.py

@@ -0,0 +1,56 @@
+"""nodus-context — LLM context window management.
+
+Token budget tracking, message lifecycle, and compaction strategies for AI systems
+that need to stay within finite LLM context windows.
+
+Core types:
+    ContextMessage       — one message (role, content, token_count)
+    ContextBudget        — token budget (max, usage, utilization, overflow check)
+    ContextWindow        — message list with budget enforcement + compaction
+
+Token counting:
+    estimate_tokens      — word-count estimate (~4 chars per token, no dep)
+    count_tokens         — accurate via tiktoken if installed, else estimate
+
+Compaction strategies:
+    CompactionStrategy   — protocol any strategy must satisfy
+    DropToolInternalsStrategy — remove tool_use/tool_result except final pairs
+    SummarizeStrategy    — keep head + tail, replace middle with summary
+
+Role constants:
+    ROLE_USER, ROLE_ASSISTANT, ROLE_SYSTEM,
+    ROLE_TOOL_USE, ROLE_TOOL_RESULT, ROLE_THINKING
+"""
+from .budget import ContextBudget, count_tokens, estimate_tokens
+from .message import (
+    ROLE_ASSISTANT,
+    ROLE_SYSTEM,
+    ROLE_THINKING,
+    ROLE_TOOL_RESULT,
+    ROLE_TOOL_USE,
+    ROLE_USER,
+    ContextMessage,
+)
+from .strategies import CompactionStrategy, DropToolInternalsStrategy, SummarizeStrategy
+from .window import ContextWindow
+
+__all__ = [
+    # Core types
+    "ContextMessage",
+    "ContextBudget",
+    "ContextWindow",
+    # Token counting
+    "estimate_tokens",
+    "count_tokens",
+    # Strategies
+    "CompactionStrategy",
+    "DropToolInternalsStrategy",
+    "SummarizeStrategy",
+    # Role constants
+    "ROLE_USER",
+    "ROLE_ASSISTANT",
+    "ROLE_SYSTEM",
+    "ROLE_TOOL_USE",
+    "ROLE_TOOL_RESULT",
+    "ROLE_THINKING",
+]

nodus_context-0.1.0/nodus_context/budget.py

@@ -0,0 +1,97 @@
+"""ContextBudget — track token usage against a finite context window."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass
+class ContextBudget:
+    """Token budget for one LLM context window.
+
+    Attributes
+    ----------
+    max_tokens:         Hard limit for the context window.
+    warning_threshold:  Fraction of capacity (0–1) at which ``is_warning``
+                        becomes True.  Default: 0.80 (80 % full).
+    current_usage:      Running total of tokens charged so far.
+    """
+
+    max_tokens: int
+    warning_threshold: float = 0.80
+    current_usage: int = 0
+
+    @property
+    def remaining(self) -> int:
+        return max(0, self.max_tokens - self.current_usage)
+
+    @property
+    def utilization(self) -> float:
+        """Fraction of max_tokens used (0.0–1.0+)."""
+        if self.max_tokens <= 0:
+            return 1.0
+        return self.current_usage / self.max_tokens
+
+    @property
+    def is_warning(self) -> bool:
+        return self.utilization >= self.warning_threshold
+
+    @property
+    def is_full(self) -> bool:
+        return self.current_usage >= self.max_tokens
+
+    def would_overflow(self, tokens: int) -> bool:
+        """True if adding *tokens* would exceed max_tokens."""
+        return (self.current_usage + tokens) > self.max_tokens
+
+    def charge(self, tokens: int) -> None:
+        """Increase current_usage by *tokens*."""
+        self.current_usage += tokens
+
+    def release(self, tokens: int) -> None:
+        """Decrease current_usage by *tokens* (clamped to 0)."""
+        self.current_usage = max(0, self.current_usage - tokens)
+
+    def reset(self) -> None:
+        self.current_usage = 0
+
+
+# ── Token counting helpers ─────────────────────────────────────────────────────
+
+def estimate_tokens(content: Any) -> int:
+    """Word-count estimate: ~4 characters per token.  No external dependencies."""
+    if content is None:
+        return 0
+    if isinstance(content, str):
+        chars = len(content)
+        return max(1, chars // 4) if chars > 0 else 0
+    if isinstance(content, (list, tuple)):
+        return sum(estimate_tokens(item) for item in content)
+    if isinstance(content, dict):
+        return sum(
+            estimate_tokens(k) + estimate_tokens(v) for k, v in content.items()
+        )
+    return max(1, len(str(content)) // 4)
+
+
+def count_tokens(content: Any, *, model: str | None = None) -> int:
+    """Return accurate token count via tiktoken when installed; else estimate.
+
+    Args:
+        content: The text or content object to count.
+        model:   Optional model name for tiktoken encoding selection.
+    """
+    try:
+        import tiktoken  # noqa: PLC0415
+
+        enc_name = "cl100k_base"
+        if model:
+            try:
+                enc = tiktoken.encoding_for_model(model)
+                return len(enc.encode(str(content)))
+            except KeyError:
+                pass
+        enc = tiktoken.get_encoding(enc_name)
+        return len(enc.encode(str(content)))
+    except ImportError:
+        return estimate_tokens(content)

nodus_context-0.1.0/nodus_context/message.py

@@ -0,0 +1,32 @@
+"""ContextMessage — a single message in an LLM context window."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+# Valid role values (not enforced — kept as documentation)
+ROLE_USER       = "user"
+ROLE_ASSISTANT  = "assistant"
+ROLE_SYSTEM     = "system"
+ROLE_TOOL_USE   = "tool_use"
+ROLE_TOOL_RESULT = "tool_result"
+ROLE_THINKING   = "thinking"
+
+
+@dataclass
+class ContextMessage:
+    """One message in an LLM context window.
+
+    Attributes
+    ----------
+    role:         Sender role — see ROLE_* constants.
+    content:      Message content (str or list of content blocks).
+    token_count:  Estimated or measured token count.  None = unknown; the
+                  window computes an estimate lazily when needed.
+    message_id:   Optional ID linking a tool_result to its tool_use block.
+    """
+
+    role: str
+    content: Any
+    token_count: int | None = None
+    message_id: str | None = None

nodus_context-0.1.0/nodus_context/strategies.py

@@ -0,0 +1,121 @@
+"""Compaction strategies for reducing context window token usage."""
+from __future__ import annotations
+
+from typing import Callable, Optional
+from .message import (
+    ROLE_ASSISTANT,
+    ROLE_SYSTEM,
+    ROLE_THINKING,
+    ROLE_TOOL_RESULT,
+    ROLE_TOOL_USE,
+    ROLE_USER,
+    ContextMessage,
+)
+
+try:
+    from typing import Protocol, runtime_checkable
+except ImportError:
+    from typing_extensions import Protocol, runtime_checkable  # type: ignore[assignment]
+
+
+@runtime_checkable
+class CompactionStrategy(Protocol):
+    """Protocol for context compaction strategies."""
+
+    def compact(self, messages: list[ContextMessage]) -> list[ContextMessage]:
+        """Return a reduced list of messages preserving semantic meaning."""
+        ...
+
+
+class DropToolInternalsStrategy:
+    """Remove ``tool_use`` and ``tool_result`` blocks except the final pairs.
+
+    Preserves all ``user`` and ``assistant`` turns as well as ``system``
+    and ``thinking`` blocks.  Does NOT call any LLM.
+
+    Args:
+        keep_last_pairs: Number of final tool_use/tool_result pairs to keep.
+    """
+
+    def __init__(self, keep_last_pairs: int = 1) -> None:
+        self.keep_last_pairs = max(0, keep_last_pairs)
+
+    def compact(self, messages: list[ContextMessage]) -> list[ContextMessage]:
+        tool_result_indices = [
+            i for i, m in enumerate(messages) if m.role == ROLE_TOOL_RESULT
+        ]
+        if len(tool_result_indices) <= self.keep_last_pairs:
+            return messages
+
+        keep_from = tool_result_indices[-self.keep_last_pairs] if self.keep_last_pairs else None
+
+        # IDs of tool_use blocks linked to kept tool_results
+        kept_ids: set[str] = set()
+        if keep_from is not None:
+            for m in messages[keep_from:]:
+                if m.role == ROLE_TOOL_RESULT and m.message_id:
+                    kept_ids.add(m.message_id)
+
+        result: list[ContextMessage] = []
+        for i, m in enumerate(messages):
+            if m.role == ROLE_TOOL_RESULT:
+                if keep_from is not None and i >= keep_from:
+                    result.append(m)
+                # else: drop
+            elif m.role == ROLE_TOOL_USE:
+                if m.message_id and m.message_id in kept_ids:
+                    result.append(m)
+                elif keep_from is not None and i >= keep_from:
+                    result.append(m)
+                # else: drop
+            else:
+                result.append(m)
+        return result
+
+
+class SummarizeStrategy:
+    """Keep the first *keep_first* and last *keep_last* messages; summarize the middle.
+
+    The middle messages are replaced with a single ``assistant`` block containing
+    the text returned by ``summary_fn``.  When ``summary_fn`` is None the middle
+    is replaced with a placeholder.
+
+    Args:
+        keep_first:  Number of messages to keep at the start (e.g. system prompt).
+        keep_last:   Number of messages to keep at the end (recent context).
+        summary_fn:  Callable that receives the dropped messages and returns a
+                     summary string.  When None a placeholder is used.
+    """
+
+    def __init__(
+        self,
+        keep_first: int = 2,
+        keep_last: int = 10,
+        summary_fn: Optional[Callable[[list[ContextMessage]], str]] = None,
+    ) -> None:
+        self.keep_first = max(0, keep_first)
+        self.keep_last = max(0, keep_last)
+        self.summary_fn = summary_fn
+
+    def compact(self, messages: list[ContextMessage]) -> list[ContextMessage]:
+        total = len(messages)
+        if total <= self.keep_first + self.keep_last:
+            return messages
+
+        head = messages[: self.keep_first]
+        tail = messages[total - self.keep_last :]
+        middle = messages[self.keep_first : total - self.keep_last]
+
+        if not middle:
+            return messages
+
+        if self.summary_fn is not None:
+            summary_text = self.summary_fn(middle)
+        else:
+            summary_text = (
+                f"[{len(middle)} earlier messages summarized — "
+                f"approximately {sum((m.token_count or 0) for m in middle)} tokens]"
+            )
+
+        summary_msg = ContextMessage(role=ROLE_ASSISTANT, content=summary_text)
+        return head + [summary_msg] + tail

nodus_context-0.1.0/nodus_context/window.py

@@ -0,0 +1,139 @@
+"""ContextWindow — manages a list of ContextMessages within a ContextBudget."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .budget import ContextBudget, estimate_tokens
+from .message import ROLE_TOOL_RESULT, ROLE_TOOL_USE, ContextMessage
+
+if TYPE_CHECKING:
+    from .strategies import CompactionStrategy
+
+
+class ContextWindow:
+    """Ordered list of ``ContextMessage`` objects with budget enforcement.
+
+    Usage::
+
+        budget = ContextBudget(max_tokens=128_000)
+        window = ContextWindow(budget)
+        window.add_force(ContextMessage(role="system", content="You are helpful."))
+        added = window.add(ContextMessage(role="user", content="Hello"))
+        if not added:
+            # window is full — compact before adding
+            window.compact(DropToolInternalsStrategy())
+    """
+
+    def __init__(self, budget: ContextBudget) -> None:
+        self._budget = budget
+        self._messages: list[ContextMessage] = []
+
+    # ── Adding messages ────────────────────────────────────────────────────────
+
+    def add(self, message: ContextMessage) -> bool:
+        """Add *message* only if it fits within the budget.
+
+        Returns False and does NOT add the message if adding it would overflow.
+        Token count is estimated lazily if ``message.token_count`` is None.
+        """
+        tokens = self._resolve_tokens(message)
+        if self._budget.would_overflow(tokens):
+            return False
+        message = _with_token_count(message, tokens)
+        self._messages.append(message)
+        self._budget.charge(tokens)
+        return True
+
+    def add_force(self, message: ContextMessage) -> None:
+        """Add *message* regardless of budget (for system prompts, required context).
+
+        Charges the tokens but does NOT block on overflow.
+        """
+        tokens = self._resolve_tokens(message)
+        message = _with_token_count(message, tokens)
+        self._messages.append(message)
+        self._budget.charge(tokens)
+
+    # ── Reading ────────────────────────────────────────────────────────────────
+
+    def messages(self) -> list[ContextMessage]:
+        """Return the current message list (live reference — do not mutate)."""
+        return self._messages
+
+    def snapshot(self) -> list[ContextMessage]:
+        """Return a shallow copy of the message list."""
+        return list(self._messages)
+
+    def budget(self) -> ContextBudget:
+        return self._budget
+
+    def __len__(self) -> int:
+        return len(self._messages)
+
+    # ── Compaction ─────────────────────────────────────────────────────────────
+
+    def compact(self, strategy: "CompactionStrategy") -> int:
+        """Run *strategy* and return the number of tokens freed.
+
+        The strategy receives the full message list and returns a reduced list.
+        ``current_usage`` is recomputed from the surviving messages.
+        """
+        before = self._budget.current_usage
+        self._messages = strategy.compact(list(self._messages))
+        new_usage = sum(
+            self._resolve_tokens(m) for m in self._messages
+        )
+        self._budget.current_usage = new_usage
+        freed = before - new_usage
+        return max(0, freed)
+
+    def guard_tool_results(self, keep_last: int = 3) -> int:
+        """Drop ``tool_result`` messages beyond the most recent *keep_last*.
+
+        Preserves all ``user`` and ``assistant`` turns.  Drops the matching
+        ``tool_use`` block for each dropped ``tool_result`` when possible.
+
+        Returns the number of tokens freed.
+        """
+        # Collect tool_result indices in order
+        result_indices = [
+            i for i, m in enumerate(self._messages) if m.role == ROLE_TOOL_RESULT
+        ]
+        if len(result_indices) <= keep_last:
+            return 0
+
+        drop_indices = set(result_indices[: -keep_last])
+
+        # Also drop the matching tool_use for each dropped tool_result
+        ids_to_drop = {
+            self._messages[i].message_id
+            for i in drop_indices
+            if self._messages[i].message_id
+        }
+        for i, m in enumerate(self._messages):
+            if m.role == ROLE_TOOL_USE and m.message_id in ids_to_drop:
+                drop_indices.add(i)
+
+        freed = sum(
+            self._resolve_tokens(self._messages[i]) for i in drop_indices
+        )
+        self._messages = [
+            m for i, m in enumerate(self._messages) if i not in drop_indices
+        ]
+        self._budget.release(freed)
+        return freed
+
+    # ── Private ────────────────────────────────────────────────────────────────
+
+    def _resolve_tokens(self, message: ContextMessage) -> int:
+        if message.token_count is not None:
+            return message.token_count
+        return estimate_tokens(message.content)
+
+
+def _with_token_count(message: ContextMessage, count: int) -> ContextMessage:
+    """Return message with token_count filled in (no-op if already set)."""
+    if message.token_count is not None:
+        return message
+    from dataclasses import replace
+    return replace(message, token_count=count)

nodus_context-0.1.0/nodus_context.egg-info/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.4
+Name: nodus-context
+Version: 0.1.0
+Summary: LLM context window management: token budget, compaction strategies, tool result guards
+Author: Shawn Knight
+License: MIT
+Project-URL: Homepage, https://github.com/Masterplanner25/nodus-context
+Project-URL: Repository, https://github.com/Masterplanner25/nodus-context
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.5.0; extra == "tiktoken"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Dynamic: license-file
+
+# nodus-context
+
+**LLM context window management: token budget, compaction strategies, and
+tool result guards for AI systems.**
+
+Keeps agent conversations within finite LLM context windows without manual
+message pruning. No required external dependencies — token counting uses a
+word-count estimate by default; install `tiktoken` for accurate counts.
+
+> **Status:** v0.1.0 — prepared, not yet published.
+
+---
+
+## Install
+
+```bash
+pip install nodus-context
+
+# With accurate tiktoken-based token counting:
+pip install "nodus-context[tiktoken]"
+```
+
+---
+
+## What it provides
+
+| Component | Purpose |
+|---|---|
+| `ContextBudget` | Token budget with utilization tracking and overflow detection |
+| `ContextMessage` | Normalized message (role, content, token count) |
+| `ContextWindow` | Message list with budget enforcement and compaction |
+| `DropToolInternalsStrategy` | Remove intermediate tool calls, keep final pairs |
+| `SummarizeStrategy` | Keep head + tail, replace middle with a summary message |
+| `estimate_tokens` / `count_tokens` | Word-estimate or tiktoken-accurate counting |
+
+---
+
+## Quick start
+
+```python
+from nodus_context import ContextWindow, ContextBudget, ROLE_USER, ROLE_ASSISTANT
+
+budget = ContextBudget(max_tokens=8192)
+window = ContextWindow(budget=budget)
+
+window.add(ROLE_USER, "What is the capital of France?")
+window.add(ROLE_ASSISTANT, "The capital of France is Paris.")
+
+messages = window.messages()   # list of ContextMessage
+print(f"Using {budget.used}/{budget.max_tokens} tokens")
+```
+
+---
+
+## ContextBudget
+
+```python
+from nodus_context import ContextBudget
+
+budget = ContextBudget(max_tokens=4096, reserve_tokens=512)
+budget.add(150)                # record token usage
+budget.utilization             # float 0.0–1.0
+budget.available               # tokens remaining (respects reserve)
+budget.is_over_budget          # True if used > max_tokens
+budget.reset()
+```
+
+---
+
+## ContextWindow
+
+```python
+from nodus_context import ContextWindow, ContextBudget, DropToolInternalsStrategy
+
+window = ContextWindow(
+    budget=ContextBudget(max_tokens=8192),
+    compaction_strategy=DropToolInternalsStrategy(),
+    compaction_threshold=0.85,   # compact when 85% full
+)
+
+window.add(role, content)         # adds message, tracks tokens
+window.add_raw(context_message)   # add pre-built ContextMessage
+window.messages()                 # current message list
+window.compact()                  # trigger compaction manually
+window.guard_tool_results(n=2)    # keep only the last n tool result pairs
+window.token_count                # current total
+window.message_count
+```
+
+Compaction runs automatically when `utilization >= compaction_threshold`.
+
+---
+
+## Compaction strategies
+
+### DropToolInternalsStrategy
+
+Removes intermediate `tool_use` / `tool_result` pairs, keeping only the
+final `n` pairs. Reduces context without losing the outcome.
+
+```python
+from nodus_context import DropToolInternalsStrategy
+strategy = DropToolInternalsStrategy(keep_last_n_pairs=1)
+```
+
+### SummarizeStrategy
+
+Keeps the first `head_count` and last `tail_count` messages; replaces
+everything in between with a single summary message.
+
+```python
+from nodus_context import SummarizeStrategy
+strategy = SummarizeStrategy(
+    head_count=2,
+    tail_count=4,
+    summary_fn=lambda msgs: "Summary of intermediate steps.",
+)
+```
+
+`summary_fn` can call an LLM — any callable that takes a list of
+`ContextMessage` and returns a string.
+
+---
+
+## Token counting
+
+```python
+from nodus_context import estimate_tokens, count_tokens
+
+estimate_tokens("Hello, world!")   # fast word-count estimate (no dep)
+count_tokens("Hello, world!")      # tiktoken if installed, else estimate
+```
+
+Install `nodus-context[tiktoken]` for accurate counts.
+
+---
+
+## Role constants
+
+```python
+from nodus_context import (
+    ROLE_USER, ROLE_ASSISTANT, ROLE_SYSTEM,
+    ROLE_TOOL_USE, ROLE_TOOL_RESULT, ROLE_THINKING,
+)
+```
+
+---
+
+## Design
+
+- **No required dependencies.** Token estimation uses `~4 chars per token`
+  heuristic. Accurate counting requires `tiktoken` (optional extra).
+- **Protocol-based strategies.** Any callable satisfying `CompactionStrategy`
+  works — no inheritance needed.
+
+---
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -q
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

nodus_context-0.1.0/nodus_context.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+nodus_context/__init__.py
+nodus_context/budget.py
+nodus_context/message.py
+nodus_context/strategies.py
+nodus_context/window.py
+nodus_context.egg-info/PKG-INFO
+nodus_context.egg-info/SOURCES.txt
+nodus_context.egg-info/dependency_links.txt
+nodus_context.egg-info/requires.txt
+nodus_context.egg-info/top_level.txt
+tests/test_budget.py
+tests/test_strategies.py
+tests/test_window.py

nodus_context-0.1.0/nodus_context.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nodus_context-0.1.0/nodus_context.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+pytest>=8.0
+
+[tiktoken]
+tiktoken>=0.5.0

nodus_context-0.1.0/nodus_context.egg-info/top_level.txt

@@ -0,0 +1 @@
+nodus_context

nodus_context-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=80", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nodus-context"
+version = "0.1.0"
+description = "LLM context window management: token budget, compaction strategies, tool result guards"
+authors = [{ name = "Shawn Knight" }]
+license = { text = "MIT" }
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[project.optional-dependencies]
+tiktoken = ["tiktoken>=0.5.0"]
+dev = ["pytest>=8.0"]
+
+[project.urls]
+Homepage = "https://github.com/Masterplanner25/nodus-context"
+Repository = "https://github.com/Masterplanner25/nodus-context"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["nodus_context*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

nodus_context-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

nodus_context-0.1.0/tests/test_budget.py

@@ -0,0 +1,82 @@
+from nodus_context import ContextBudget, estimate_tokens, count_tokens
+
+
+def test_initial_state():
+    b = ContextBudget(max_tokens=1000)
+    assert b.current_usage == 0
+    assert b.remaining == 1000
+    assert b.utilization == 0.0
+    assert not b.is_warning
+    assert not b.is_full
+
+
+def test_charge_and_release():
+    b = ContextBudget(max_tokens=1000)
+    b.charge(400)
+    assert b.current_usage == 400
+    assert b.remaining == 600
+    b.release(200)
+    assert b.current_usage == 200
+    b.release(9999)   # clamp to 0
+    assert b.current_usage == 0
+
+
+def test_utilization():
+    b = ContextBudget(max_tokens=1000)
+    b.charge(800)
+    assert abs(b.utilization - 0.8) < 0.001
+
+
+def test_is_warning_at_threshold():
+    b = ContextBudget(max_tokens=1000, warning_threshold=0.8)
+    b.charge(799)
+    assert not b.is_warning
+    b.charge(1)
+    assert b.is_warning
+
+
+def test_is_full():
+    b = ContextBudget(max_tokens=100)
+    b.charge(100)
+    assert b.is_full
+    b.charge(1)
+    assert b.is_full   # still full (over limit)
+
+
+def test_would_overflow():
+    b = ContextBudget(max_tokens=100)
+    b.charge(90)
+    assert not b.would_overflow(10)
+    assert b.would_overflow(11)
+
+
+def test_reset():
+    b = ContextBudget(max_tokens=100)
+    b.charge(50)
+    b.reset()
+    assert b.current_usage == 0
+
+
+# ── estimate_tokens ────────────────────────────────────────────────────────────
+
+def test_estimate_none():
+    assert estimate_tokens(None) == 0
+
+
+def test_estimate_string():
+    assert estimate_tokens("hello world") > 0
+
+
+def test_estimate_empty_string():
+    assert estimate_tokens("") == 0
+
+
+def test_estimate_list():
+    result = estimate_tokens(["hello", "world"])
+    assert result > 0
+
+
+def test_count_tokens_falls_back_to_estimate():
+    # Without tiktoken installed, should still return something > 0
+    result = count_tokens("hello world")
+    assert result > 0

nodus_context-0.1.0/tests/test_strategies.py

@@ -0,0 +1,97 @@
+from nodus_context import (
+    ContextMessage,
+    DropToolInternalsStrategy,
+    SummarizeStrategy,
+)
+from nodus_context.message import (
+    ROLE_ASSISTANT,
+    ROLE_TOOL_RESULT,
+    ROLE_TOOL_USE,
+    ROLE_USER,
+)
+
+
+def _msg(role, content="x", token_count=10, message_id=None):
+    return ContextMessage(role=role, content=content,
+                          token_count=token_count, message_id=message_id)
+
+
+# ── DropToolInternalsStrategy ─────────────────────────────────────────────────
+
+def test_drop_tool_internals_keeps_last_pair():
+    msgs = [
+        _msg(ROLE_USER),
+        _msg(ROLE_TOOL_USE, message_id="a"),
+        _msg(ROLE_TOOL_RESULT, message_id="a"),
+        _msg(ROLE_TOOL_USE, message_id="b"),
+        _msg(ROLE_TOOL_RESULT, message_id="b"),
+        _msg(ROLE_ASSISTANT),
+    ]
+    result = DropToolInternalsStrategy(keep_last_pairs=1).compact(msgs)
+    result_roles = [m.role for m in result]
+    # Should keep user, last tool pair, assistant
+    assert ROLE_USER in result_roles
+    assert ROLE_ASSISTANT in result_roles
+    tool_results = [m for m in result if m.role == ROLE_TOOL_RESULT]
+    assert len(tool_results) == 1
+    assert tool_results[0].message_id == "b"
+
+
+def test_drop_tool_internals_noop_when_within_limit():
+    msgs = [_msg(ROLE_TOOL_RESULT, message_id="a")]
+    result = DropToolInternalsStrategy(keep_last_pairs=2).compact(msgs)
+    assert result == msgs
+
+
+def test_drop_tool_internals_zero_keep():
+    msgs = [
+        _msg(ROLE_USER),
+        _msg(ROLE_TOOL_USE, message_id="a"),
+        _msg(ROLE_TOOL_RESULT, message_id="a"),
+    ]
+    result = DropToolInternalsStrategy(keep_last_pairs=0).compact(msgs)
+    assert all(m.role not in (ROLE_TOOL_USE, ROLE_TOOL_RESULT) for m in result)
+
+
+def test_preserves_user_and_assistant():
+    msgs = [
+        _msg(ROLE_USER, content="q"),
+        _msg(ROLE_TOOL_USE, message_id="x"),
+        _msg(ROLE_TOOL_RESULT, message_id="x"),
+        _msg(ROLE_ASSISTANT, content="a"),
+    ]
+    result = DropToolInternalsStrategy(keep_last_pairs=0).compact(msgs)
+    roles = [m.role for m in result]
+    assert ROLE_USER in roles
+    assert ROLE_ASSISTANT in roles
+
+
+# ── SummarizeStrategy ─────────────────────────────────────────────────────────
+
+def test_summarize_replaces_middle():
+    msgs = [_msg(ROLE_USER, content=f"msg{i}") for i in range(15)]
+    result = SummarizeStrategy(keep_first=2, keep_last=3).compact(msgs)
+    # head (2) + summary (1) + tail (3) = 6
+    assert len(result) == 6
+    # summary is in position 2
+    assert result[2].role == ROLE_ASSISTANT
+    assert "summarized" in result[2].content.lower()
+
+
+def test_summarize_noop_when_small():
+    msgs = [_msg(ROLE_USER) for _ in range(4)]
+    result = SummarizeStrategy(keep_first=2, keep_last=3).compact(msgs)
+    assert result == msgs
+
+
+def test_summarize_custom_fn():
+    msgs = [_msg(ROLE_USER, content=f"m{i}", token_count=5) for i in range(10)]
+    fn_called = []
+
+    def my_fn(dropped):
+        fn_called.extend(dropped)
+        return "custom summary"
+
+    result = SummarizeStrategy(keep_first=1, keep_last=2, summary_fn=my_fn).compact(msgs)
+    assert len(fn_called) > 0
+    assert result[1].content == "custom summary"

nodus_context-0.1.0/tests/test_window.py

@@ -0,0 +1,98 @@
+import pytest
+from nodus_context import ContextBudget, ContextMessage, ContextWindow, DropToolInternalsStrategy
+from nodus_context.message import ROLE_TOOL_RESULT, ROLE_TOOL_USE
+
+
+def _msg(role="user", content="hello", token_count=10, message_id=None):
+    return ContextMessage(role=role, content=content, token_count=token_count, message_id=message_id)
+
+
+def _window(max_tokens=1000):
+    return ContextWindow(ContextBudget(max_tokens=max_tokens))
+
+
+# ── add / add_force ───────────────────────────────────────────────────────────
+
+def test_add_returns_true_when_space():
+    w = _window(1000)
+    assert w.add(_msg(token_count=10)) is True
+    assert len(w) == 1
+
+
+def test_add_returns_false_when_full():
+    w = _window(max_tokens=5)
+    assert w.add(_msg(token_count=10)) is False
+    assert len(w) == 0
+
+
+def test_add_charges_budget():
+    w = _window(1000)
+    w.add(_msg(token_count=50))
+    assert w.budget().current_usage == 50
+
+
+def test_add_force_ignores_overflow():
+    w = _window(max_tokens=5)
+    w.add_force(_msg(token_count=100))
+    assert len(w) == 1
+    assert w.budget().current_usage == 100
+
+
+def test_add_estimates_tokens_when_missing():
+    w = _window(1000)
+    msg = ContextMessage(role="user", content="hello world test")
+    added = w.add(msg)
+    assert added is True
+    assert w.budget().current_usage > 0
+
+
+# ── snapshot ──────────────────────────────────────────────────────────────────
+
+def test_snapshot_is_copy():
+    w = _window(1000)
+    w.add(_msg())
+    snap = w.snapshot()
+    snap.clear()
+    assert len(w) == 1  # original unchanged
+
+
+# ── compact ───────────────────────────────────────────────────────────────────
+
+def test_compact_returns_tokens_freed():
+    w = _window(1000)
+    for _ in range(5):
+        w.add(_msg(role=ROLE_TOOL_USE, content="call", token_count=20, message_id="id1"))
+        w.add(_msg(role=ROLE_TOOL_RESULT, content="result", token_count=20, message_id="id1"))
+    freed = w.compact(DropToolInternalsStrategy(keep_last_pairs=1))
+    assert freed > 0
+
+
+def test_compact_reduces_message_count():
+    w = _window(10000)
+    w.add(_msg(role="user", token_count=10))
+    for _ in range(4):
+        w.add(_msg(role=ROLE_TOOL_USE, content="c", token_count=10, message_id=f"id{_}"))
+        w.add(_msg(role=ROLE_TOOL_RESULT, content="r", token_count=10, message_id=f"id{_}"))
+    before = len(w)
+    w.compact(DropToolInternalsStrategy(keep_last_pairs=1))
+    assert len(w) < before
+
+
+# ── guard_tool_results ────────────────────────────────────────────────────────
+
+def test_guard_tool_results_keeps_last():
+    w = _window(10000)
+    for i in range(5):
+        w.add(_msg(role=ROLE_TOOL_USE, token_count=10, message_id=f"id{i}"))
+        w.add(_msg(role=ROLE_TOOL_RESULT, token_count=10, message_id=f"id{i}"))
+    freed = w.guard_tool_results(keep_last=2)
+    assert freed > 0
+    result_msgs = [m for m in w.messages() if m.role == ROLE_TOOL_RESULT]
+    assert len(result_msgs) == 2
+
+
+def test_guard_noop_when_within_limit():
+    w = _window(10000)
+    w.add(_msg(role=ROLE_TOOL_RESULT, token_count=10, message_id="id1"))
+    freed = w.guard_tool_results(keep_last=3)
+    assert freed == 0