Metadata-Version: 2.4
Name: convopack
Version: 0.1.0
Summary: Framework-agnostic, provider-agnostic context-window packer for LLM chat history.
Project-URL: Homepage, https://github.com/mrrobi/convopack
Project-URL: Repository, https://github.com/mrrobi/convopack
Project-URL: Issues, https://github.com/mrrobi/convopack/issues
Project-URL: Changelog, https://github.com/mrrobi/convopack/blob/main/CHANGELOG.md
Author-email: Mrrobi <mrrobi040@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: anthropic,chat,context-window,llm,memory,openai,prompt,tokenizer
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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
Provides-Extra: all
Requires-Dist: anthropic>=0.40; extra == 'all'
Requires-Dist: tiktoken>=0.7; extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: anthropic>=0.40; extra == 'dev'
Requires-Dist: hypothesis>=6; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: tiktoken>=0.7; extra == 'dev'
Provides-Extra: tiktoken
Requires-Dist: tiktoken>=0.7; extra == 'tiktoken'
Description-Content-Type: text/markdown

# convopack

Framework-agnostic, provider-agnostic context-window packer for LLM chat history.

> **Status:** pre-alpha. API may change before `0.1.0`.

## Why

LLM apps accumulate messages until they overflow the model's context window. Existing fixes are framework-locked (LangChain, LangGraph), provider-specific (Anthropic context-management beta), or designed for long-term semantic memory rather than turn-by-turn packing (mem0).

`convopack` is a small, focused library that takes a conversation history and a token budget and returns the largest tail that fits, while:

- preserving `tool_use` / `tool_result` pairs atomically,
- normalising message shapes across OpenAI, Anthropic, and Gemini,
- letting you plug in any tokenizer or summariser,
- staying async-friendly and zero-dependency at the core.

## Install

```bash
pip install convopack                 # core only
pip install "convopack[tiktoken]"     # + OpenAI tokenizer
pip install "convopack[anthropic]"    # + Anthropic tokenizer
pip install "convopack[all]"          # everything
```

## Quickstart

```python
from convopack import Packer, Recency

packer = Packer(
    budget=8000,
    tokenizer="tiktoken:gpt-4o",
    strategy=Recency(),
    pin=["system", "first_user"],
)

packed = packer.pack(messages)        # list[dict] in, list[dict] out
```

## Strategies

| Strategy        | When to use                                              |
| --------------- | -------------------------------------------------------- |
| `Recency`       | Keep the tail that fits. Cheapest, no LLM call.          |
| `SummaryEvict`  | Summarise evicted turns into a single system message.    |
| `Importance`    | Score each turn yourself; drop the lowest until it fits. |
| `SemanticDedup` | Remove near-duplicate turns first.                       |

## Comparison

| Feature                       | convopack | LangChain `trim_messages` | mem0          | Anthropic native |
| ----------------------------- | --------- | ------------------------- | ------------- | ---------------- |
| Framework-free                | yes       | no                        | no            | yes              |
| Multi-provider message shapes | yes       | partial                   | n/a           | no               |
| Tool-call pair safety         | yes       | no                        | n/a           | yes (one type)   |
| Pluggable strategy            | yes       | no                        | n/a           | no               |
| Async summariser              | yes       | no                        | n/a           | n/a              |
| Scope                         | per-turn  | per-turn                  | cross-session | per-turn         |

## License

MIT
