agentfit-py

Fit your messages into the LLM context window. Token-aware truncation with multiple strategies, pluggable tokenizers. Zero runtime dependencies.

Python port of @mukundakatta/agentfit. The JS sibling has the full design notes; this README sticks to the Python API.

Install

pip install agentfit-py

Usage

from agentfit import count, fit, OverBudgetError

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user",   "content": "Hello there!"},
    {"role": "assistant", "content": "Hi! How can I help?"},
    {"role": "user",   "content": "Tell me a long story..."},
]

# Estimate tokens (heuristic; pass `tokenizer=...` to plug in tiktoken etc.)
count(messages, model="claude-sonnet-4-6")   # -> int

# Drop messages until under budget. System message + recent N are preserved.
result = fit(
    messages,
    max_tokens=8000,
    model="claude-sonnet-4-6",
    strategy="drop-oldest",      # or "drop-middle" / "priority"
    preserve_system=True,
    preserve_last_n=2,
)

result.messages   # list[dict]  -- survived
result.dropped    # list[dict]  -- removed
result.tokens     # {"before": int, "after": int, "budget": int}
result.fit        # True iff under budget

If the budget can't be reached even after dropping all non-protected messages, fit() raises OverBudgetError (carries the partial result). Use on_over_budget="return-partial" to return the over-budget result instead with fit=False.

Strategies

Custom tokenizer

Pass any Callable[[str], int]. Example with tiktoken:

import tiktoken
enc = tiktoken.get_encoding("cl100k_base")
fit(messages, max_tokens=8000, tokenizer=lambda s: len(enc.encode(s)))

API differences from the JS sibling

• count() and fit() use Python keyword args (max_tokens=, preserve_system=, etc.) instead of the JS options object.
• fit() returns a FitResult dataclass instead of a plain object.
• No wrapFetch / monkey-patching equivalents -- not needed in Python.

See the JS sibling's README for the full design notes and broader algorithmic reasoning.