kayariyan28/ctxbudgeter

When you build AI agents, one of the hardest problems is managing what goes into each prompt. Language models have a limited context window, meaning you can only fit so many tokens (roughly, word pieces) in a single call. ctxbudgeter is a Python library that sits between your agent code and the AI model and decides, deterministically and with full audit trail, exactly which pieces of information to include, drop, compress, or mark for caching in each call. You give it a token budget and a collection of items: system instructions, documents, code files, memory notes, tool results, and the user's current request. Each item gets a priority and optional flags like required or cache-stable. When you compile the pack, the library selects what fits within the budget, explains why each item was included or excluded, and produces a context object ready to send to the model. Nothing is resolved at random, every run with the same inputs produces the same output, which makes it testable. The library includes a pytest-style assertion layer so you can write tests that check whether your context pack always includes certain required items, never includes sensitive data, stays under a token limit, and maintains a minimum quality score. It also provides cache-aware adapters that automatically set the right caching fields for Anthropic, OpenAI, LangChain, and PydanticAI. It works with LangGraph, CrewAI, PydanticAI, and your own agent loops. The core makes no AI calls itself, it runs locally and fast. The full README is longer than what was provided.