context-clipper ✂️
context-clipper is a lightweight, framework-agnostic Python library designed to solve LLM context window overflow and "lost in the middle" retrieval degradation.
Unlike naive sliding windows (messages[-10:]) that blindly drop critical system prompts or early user context, context-clipper treats the conversation window as a prioritized memory heap to intelligently shed low-priority noise or summarize intermediate turns without pulling in heavy frameworks like LangChain, LlamaIndex, or Pydantic.
✨ Why context-clipper?
- 🪶 Zero Bloat: Built using 100% pure Python standard libraries (
dataclasses,heapq,functools). No heavy framework dependencies. - 🎯 Accurate Token Counting: Uses
tiktokenwhen available (including ~4 tokens/message framing overhead) with graceful fallback to character heuristics. - 🔌 Standard API Compatibility: Accepts and returns standard Python lists of dictionaries matching OpenAI and Anthropic message formats.
- 🧠 3-Phase Waterfall Engine:
- Total Protection: Guarantees all
sticky=Truemessages (e.g., system instructions, core rules) are preserved. - Priority-Based Shedding: Uses a min-heap to drop lowest-priority items first (e.g., failed web searches or debug logs with
priority=0). - Rolling Middle-Summarization: Condenses intermediate conversational turns into a single summary message via your own custom LLM callback while preserving active recent tail turns.
- Total Protection: Guarantees all
📦 Installation
Install directly via pip:
pip install context-clipper
To include tiktoken for tokenizer-accurate counting:
pip install context-clipper[tiktoken]
🚀 Quickstart
Basic Priority Shedding
from context_clipper import pack
messages = [
# System instructions are sticky and cannot be dropped
{"role": "system", "content": "You are a helpful coding assistant.", "sticky": True, "priority": 100},
{"role": "user", "content": "How do I reverse a list in Python?", "priority": 1},
{"role": "assistant", "content": "You can use list.reverse() or [::-1].", "priority": 1},
# Low-priority tool error / noise that should be dropped first when budget is tight
{"role": "tool", "content": "Error 500: Search timeout", "priority": 0, "tool_call_id": "call_1"},
{"role": "user", "content": "Thanks! Now explain generator expressions.", "priority": 2}
]
# Pack the conversation into a 150-token window
packed_messages = pack(messages, max_tokens=150)
Rolling Middle-Summarization with Custom Callback
Pass any summarizer callback (OpenAI, Anthropic, local Ollama, etc.) to condense intermediate turns while keeping sticky prompts and recent turns intact:
from context_clipper import Clipper
def my_llm_summarizer(text: str) -> str:
# Call your preferred LLM provider here
return "User asked about list reversal; assistant provided reverse() and slice methods."
clipper = Clipper(max_tokens=150, summarizer_cb=my_llm_summarizer)
packed_messages = clipper.pack(messages)
print(packed_messages[1])
# {
# "role": "system",
# "content": "[Summary of older conversation: User asked about list reversal; assistant provided reverse() and slice methods.]"
# }
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Metadata
Release files for context-clipper 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| context_clipper-0.1.0.tar.gz | 12.6 kB | Without provenance | Details for context_clipper-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| context_clipper-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for context_clipper-0.1.0-py3-none-any.whl |
Total release size: 23.2 kB
Release files / context_clipper-0.1.0.tar.gz
| Download URL | context_clipper-0.1.0.tar.gz |
|---|---|
| Size | 12.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6e79f32d9c4710ab2b85c69f6647b6d3e800f61ef186a7c7e6aa87d634f5e620
|
|
BLAKE2b-256 checksum How to use checksums |
458c17dd2b780be351a04abbda50489ba768ada9826fd06dc72807ce107b7999
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.6
|
Release files / context_clipper-0.1.0-py3-none-any.whl
| Download URL | context_clipper-0.1.0-py3-none-any.whl |
|---|---|
| Size | 10.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
8134b993b3f5d1ca4644578308ccff328c496feace8d551e2983587358e56039
|
|
BLAKE2b-256 checksum How to use checksums |
7df9d3954b4405f744a08d9eff2da052eb99ae497b483569571cd11c75863d49
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.6
|
Security for context-clipper 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.