langchain-turn-window 0.1.0__tar.gz

langchain_turn_window-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m pytest

langchain_turn_window-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+build/
+*.egg-info/
+resources/

langchain_turn_window-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-10-11
+
+### Added
+
+- `TurnWindowMiddleware`: LangChain agent middleware that keeps only the last N
+  human-anchored conversational turns before each model call, via
+  `wrap_model_call` and `awrap_model_call`.
+- `window_by_human_turns`: pure helper that returns the suffix of a message list
+  starting at the Nth-most-recent `HumanMessage`, without splitting an
+  `AIMessage` tool call from its `ToolMessage` response.

langchain_turn_window-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bharat Khanna
+
+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.

langchain_turn_window-0.1.0/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.5
+Name: langchain-turn-window
+Version: 0.1.0
+Summary: Model-agnostic LangChain middleware that keeps only the last N conversational turns, without splitting tool_call/tool_result pairs.
+Project-URL: Homepage, https://github.com/bharatkhanna-dev/langchain-turn-window
+Project-URL: Repository, https://github.com/bharatkhanna-dev/langchain-turn-window
+Project-URL: Issues, https://github.com/bharatkhanna-dev/langchain-turn-window/issues
+Author: Bharat Khanna
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,context-window,conversation-history,langchain,langgraph,middleware
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: langchain-core>=1.0.0
+Requires-Dist: langchain>=1.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langchain-turn-window
+
+A small, model-agnostic [LangChain](https://github.com/langchain-ai/langchain) agent middleware that keeps only the last **N conversational turns** before each model call — without ever splitting an `AIMessage` tool call from its `ToolMessage` response.
+
+## Why
+
+Every provider (OpenAI, Anthropic, Gemini, ...) rejects a request where a `tool_calls` entry has no matching tool result message. Naive history trimming — slicing by raw message count or token count — can easily cut the window in the middle of a tool-call/tool-result pair and break the request.
+
+`TurnWindowMiddleware` anchors the window on `HumanMessage` boundaries instead: it always starts the kept slice at the Nth-most-recent `HumanMessage`, which guarantees every `AIMessage` tool call inside the window still has its `ToolMessage` response attached.
+
+This is a lightweight alternative to LangChain's built-in `SummarizationMiddleware` (which needs an extra LLM call) or `context_editing` (which selectively clears old tool outputs) for the common case of "just bound the context to the last few turns."
+
+## Install
+
+```bash
+pip install langchain-turn-window
+```
+
+## Usage
+
+```python
+from langchain.agents import create_agent
+
+from langchain_turn_window import TurnWindowMiddleware
+
+agent = create_agent(
+    model="openai:gpt-4o",
+    tools=[...],
+    middleware=[
+        TurnWindowMiddleware(keep_last_turns=3),
+    ],
+)
+```
+
+`keep_last_turns` is the number of most-recent `HumanMessage` turns to retain. If the conversation has fewer turns than that, the full history passes through unchanged.
+
+## How it works
+
+`TurnWindowMiddleware` implements `wrap_model_call` / `awrap_model_call`. On every model call it:
+
+1. Finds the indexes of all `HumanMessage`s in `request.messages`.
+2. If there are fewer than `keep_last_turns` human turns, passes the messages through unchanged.
+3. Otherwise, slices the message list starting at the `keep_last_turns`-th-most-recent `HumanMessage` and forwards only that suffix to the model.
+
+The underlying pure function is also exported directly if you want to use it outside of middleware (e.g. in a custom node):
+
+```python
+from langchain_turn_window import window_by_human_turns
+
+windowed = window_by_human_turns(messages, n=3)
+```
+
+`window_by_human_turns` never mutates its input and returns the original list object unchanged when no trimming is needed (positive-`n` guard, empty list, or fewer human turns than `n`).
+
+## Configuration
+
+| Constructor arg | Default | Description |
+|---|---|---|
+| `keep_last_turns` | `3` | Number of most-recent human turns to keep. Must be `>= 1`. |
+
+## Limitations
+
+- Assumes a single-user conversational shape (one `HumanMessage` per turn). For multi-agent handoff patterns where turns aren't anchored on `HumanMessage`, this middleware is not the right fit as-is.
+- This is a hard trim, not a summary — content outside the window is dropped, not condensed. Combine with `SummarizationMiddleware` if you need older context preserved in compressed form.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

langchain_turn_window-0.1.0/README.md

@@ -0,0 +1,75 @@
+# langchain-turn-window
+
+A small, model-agnostic [LangChain](https://github.com/langchain-ai/langchain) agent middleware that keeps only the last **N conversational turns** before each model call — without ever splitting an `AIMessage` tool call from its `ToolMessage` response.
+
+## Why
+
+Every provider (OpenAI, Anthropic, Gemini, ...) rejects a request where a `tool_calls` entry has no matching tool result message. Naive history trimming — slicing by raw message count or token count — can easily cut the window in the middle of a tool-call/tool-result pair and break the request.
+
+`TurnWindowMiddleware` anchors the window on `HumanMessage` boundaries instead: it always starts the kept slice at the Nth-most-recent `HumanMessage`, which guarantees every `AIMessage` tool call inside the window still has its `ToolMessage` response attached.
+
+This is a lightweight alternative to LangChain's built-in `SummarizationMiddleware` (which needs an extra LLM call) or `context_editing` (which selectively clears old tool outputs) for the common case of "just bound the context to the last few turns."
+
+## Install
+
+```bash
+pip install langchain-turn-window
+```
+
+## Usage
+
+```python
+from langchain.agents import create_agent
+
+from langchain_turn_window import TurnWindowMiddleware
+
+agent = create_agent(
+    model="openai:gpt-4o",
+    tools=[...],
+    middleware=[
+        TurnWindowMiddleware(keep_last_turns=3),
+    ],
+)
+```
+
+`keep_last_turns` is the number of most-recent `HumanMessage` turns to retain. If the conversation has fewer turns than that, the full history passes through unchanged.
+
+## How it works
+
+`TurnWindowMiddleware` implements `wrap_model_call` / `awrap_model_call`. On every model call it:
+
+1. Finds the indexes of all `HumanMessage`s in `request.messages`.
+2. If there are fewer than `keep_last_turns` human turns, passes the messages through unchanged.
+3. Otherwise, slices the message list starting at the `keep_last_turns`-th-most-recent `HumanMessage` and forwards only that suffix to the model.
+
+The underlying pure function is also exported directly if you want to use it outside of middleware (e.g. in a custom node):
+
+```python
+from langchain_turn_window import window_by_human_turns
+
+windowed = window_by_human_turns(messages, n=3)
+```
+
+`window_by_human_turns` never mutates its input and returns the original list object unchanged when no trimming is needed (positive-`n` guard, empty list, or fewer human turns than `n`).
+
+## Configuration
+
+| Constructor arg | Default | Description |
+|---|---|---|
+| `keep_last_turns` | `3` | Number of most-recent human turns to keep. Must be `>= 1`. |
+
+## Limitations
+
+- Assumes a single-user conversational shape (one `HumanMessage` per turn). For multi-agent handoff patterns where turns aren't anchored on `HumanMessage`, this middleware is not the right fit as-is.
+- This is a hard trim, not a summary — content outside the window is dropped, not condensed. Combine with `SummarizationMiddleware` if you need older context preserved in compressed form.
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

langchain_turn_window-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langchain-turn-window"
+version = "0.1.0"
+description = "Model-agnostic LangChain middleware that keeps only the last N conversational turns, without splitting tool_call/tool_result pairs."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Bharat Khanna" }]
+keywords = ["langchain", "langgraph", "middleware", "agents", "context-window", "conversation-history"]
+classifiers = [
+"Development Status :: 4 - Beta",
+"Intended Audience :: Developers",
+"Programming Language :: Python :: 3",
+"Programming Language :: Python :: 3.10",
+"Programming Language :: Python :: 3.11",
+"Programming Language :: Python :: 3.12",
+"Programming Language :: Python :: 3.13",
+"Operating System :: OS Independent",
+"Topic :: Software Development :: Libraries :: Python Modules",
+"Typing :: Typed",
+]
+dependencies = [
+"langchain>=1.0.0",
+"langchain-core>=1.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+"pytest>=8.0.0",
+"pytest-asyncio>=0.24.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/bharatkhanna-dev/langchain-turn-window"
+Repository = "https://github.com/bharatkhanna-dev/langchain-turn-window"
+Issues = "https://github.com/bharatkhanna-dev/langchain-turn-window/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langchain_turn_window"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

langchain_turn_window-0.1.0/src/langchain_turn_window/__init__.py

@@ -0,0 +1,8 @@
+"""Model-agnostic conversational turn-windowing middleware for LangChain agents."""
+
+from .middleware import TurnWindowMiddleware
+from .windowing import window_by_human_turns
+
+__all__ = ["TurnWindowMiddleware", "window_by_human_turns"]
+
+__version__ = "0.1.0"

langchain_turn_window-0.1.0/src/langchain_turn_window/middleware.py

@@ -0,0 +1,39 @@
+"""LangChain agent middleware for retaining a bounded conversational window."""
+
+from collections.abc import Awaitable, Callable
+
+from langchain.agents.middleware import AgentMiddleware, ModelRequest, ModelResponse
+
+from .windowing import window_by_human_turns
+
+
+class TurnWindowMiddleware(AgentMiddleware):
+    """Keep only the most recent human-anchored turns for each model call."""
+
+    def __init__(self, keep_last_turns: int = 3) -> None:
+        """Initialize the middleware.
+
+        Args:
+            keep_last_turns: Number of most-recent human turns to retain.
+                Must be >= 1.
+        """
+        if keep_last_turns < 1:
+            raise ValueError("keep_last_turns must be >= 1")
+        super().__init__()
+        self.keep_last_turns = keep_last_turns
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        windowed = window_by_human_turns(request.messages, self.keep_last_turns)
+        return handler(request.override(messages=windowed))
+
+    async def awrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelResponse:
+        windowed = window_by_human_turns(request.messages, self.keep_last_turns)
+        return await handler(request.override(messages=windowed))

langchain_turn_window-0.1.0/src/langchain_turn_window/windowing.py

@@ -0,0 +1,32 @@
+"""Pure message-list windowing helpers, independent of any middleware framework."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from langchain_core.messages import HumanMessage
+
+
+def window_by_human_turns(messages: list[Any], n: int) -> list[Any]:
+    """Return a suffix window anchored to the last ``n`` HumanMessages.
+
+    Anchoring on a HumanMessage guarantees the slice never splits an
+    AIMessage tool_call from its ToolMessage. Returns ``messages`` unchanged
+    (same object) when ``n`` is non-positive or there are fewer than ``n``
+    human turns. Never mutates the input.
+
+    Args:
+        messages: Full message history, oldest first.
+        n: Number of most-recent human turns to keep.
+
+    Returns:
+        The suffix of ``messages`` starting at the nth-most-recent
+        ``HumanMessage``, or ``messages`` unchanged if trimming would have
+        no effect.
+    """
+    if n <= 0:
+        return messages
+    human_indexes = [i for i, m in enumerate(messages) if isinstance(m, HumanMessage)]
+    if not human_indexes or len(human_indexes) < n:
+        return messages
+    return messages[human_indexes[-n] :]

langchain_turn_window-0.1.0/tests/test_middleware.py

@@ -0,0 +1,65 @@
+"""Unit tests for TurnWindowMiddleware."""
+
+import pytest
+from langchain.agents.middleware import ModelRequest
+from langchain_core.messages import HumanMessage
+
+from langchain_turn_window import TurnWindowMiddleware
+
+
+def _human(i: int) -> HumanMessage:
+    return HumanMessage(content=f"human-{i}")
+
+
+def _make_request(messages) -> ModelRequest:
+    """Build a minimal ModelRequest for testing wrap_model_call in isolation."""
+    return ModelRequest(
+        model=None,
+        system_prompt=None,
+        messages=messages,
+        tool_choice=None,
+        tools=[],
+        response_format=None,
+        state=(),
+        runtime=None,
+    )
+
+
+def test_rejects_non_positive_keep_last_turns():
+    with pytest.raises(ValueError):
+        TurnWindowMiddleware(keep_last_turns=0)
+
+
+def test_wrap_model_call_forwards_windowed_messages():
+    middleware = TurnWindowMiddleware(keep_last_turns=1)
+    messages = [_human(1), _human(2), _human(3)]
+    request = _make_request(messages)
+
+    captured = {}
+
+    def handler(req: ModelRequest):
+        captured["messages"] = req.messages
+        return "ok"
+
+    result = middleware.wrap_model_call(request, handler)
+
+    assert result == "ok"
+    assert captured["messages"] == [_human(3)]
+
+
+@pytest.mark.asyncio
+async def test_awrap_model_call_forwards_windowed_messages():
+    middleware = TurnWindowMiddleware(keep_last_turns=2)
+    messages = [_human(1), _human(2), _human(3)]
+    request = _make_request(messages)
+
+    captured = {}
+
+    async def handler(req: ModelRequest):
+        captured["messages"] = req.messages
+        return "ok"
+
+    result = await middleware.awrap_model_call(request, handler)
+
+    assert result == "ok"
+    assert captured["messages"] == [_human(2), _human(3)]

langchain_turn_window-0.1.0/tests/test_windowing.py

@@ -0,0 +1,62 @@
+"""Unit tests for window_by_human_turns."""
+
+from langchain_core.messages import AIMessage, HumanMessage, ToolMessage
+
+from langchain_turn_window import window_by_human_turns
+
+
+def _human(i: int) -> HumanMessage:
+    return HumanMessage(content=f"human-{i}")
+
+
+def test_non_positive_n_returns_same_object():
+    messages = [_human(1), _human(2)]
+    assert window_by_human_turns(messages, 0) is messages
+    assert window_by_human_turns(messages, -1) is messages
+
+
+def test_empty_messages_returns_empty():
+    assert window_by_human_turns([], 3) == []
+
+
+def test_fewer_human_turns_than_n_returns_same_object():
+    messages = [_human(1), _human(2)]
+    assert window_by_human_turns(messages, 5) is messages
+
+
+def test_keeps_exact_number_of_requested_turns():
+    messages = [_human(1), _human(2), _human(3)]
+    windowed = window_by_human_turns(messages, 2)
+    assert windowed == [_human(2), _human(3)]
+
+
+def test_keeps_only_last_turn():
+    messages = [_human(1), _human(2), _human(3)]
+    windowed = window_by_human_turns(messages, 1)
+    assert windowed == [_human(3)]
+
+
+def test_does_not_split_tool_call_from_tool_message():
+    """The window must never start between an AIMessage tool_call and its ToolMessage."""
+    messages = [
+        _human(1),
+        AIMessage(content="", tool_calls=[{"name": "lookup", "args": {}, "id": "call_1"}]),
+        ToolMessage(content="result", tool_call_id="call_1"),
+        _human(2),
+        AIMessage(content="", tool_calls=[{"name": "lookup", "args": {}, "id": "call_2"}]),
+        ToolMessage(content="result-2", tool_call_id="call_2"),
+    ]
+    windowed = window_by_human_turns(messages, 1)
+    # Window starts at the last HumanMessage, so the in-flight tool call/result
+    # pair that follows it stays intact.
+    assert windowed[0] == _human(2)
+    assert isinstance(windowed[1], AIMessage)
+    assert isinstance(windowed[2], ToolMessage)
+    assert windowed[1].tool_calls[0]["id"] == windowed[2].tool_call_id
+
+
+def test_does_not_mutate_input():
+    messages = [_human(1), _human(2), _human(3)]
+    original = list(messages)
+    window_by_human_turns(messages, 1)
+    assert messages == original