Repository navigation
Releases
Releases · mathewOracle/promptbudget
v0.2.1
Fixed
__version__no longer drifts from the released version. 0.2.0 shipped
to PyPI whilepromptbudget.__version__still reported"0.1.0",
because the number was duplicated inpyproject.tomland
__init__.pyand the release checklist only ever updated the former.
It is now read from the installed package metadata, so
pyproject.tomlis the single source of truth, and a test asserts the
two agree rather than merely asserting the attribute is truthy.
v0.2.0
Added
pack_chat(): budget a conversation and get messages back rather than
one string. Chat models take role-tagged message lists, and the role is not
decoration -- it drives the chat template. Roles,name, and caller
metadata survive packing intact; content is byte-exact, including content
containing the separator.Message: a validated chat turn (system/user/assistant/tool).
Provider-style{"role", "content"}dicts are accepted anywhere a
Messageis, so existing message lists work unchanged.ChatResult: the packed messages plus the full underlying audit trail, with
to_openai()for the payload every major provider SDK accepts. Wraps rather
than subclassesPackResult-- a chat result has no.textto advertise.tokens_per_message: charge the per-message framing overhead providers bill
for, so the budget reflects the real invoice instead of visible text only.pin_last_user(defaultTrue): the most recent user message is protected
from eviction. Dropping the question being answered is never the intent.HuggingFaceTokenizer: exact counts for open-weights models (Llama, Mistral,
Qwen, Gemma). Truncation slices real token ids. Pass an already-loaded
tokenizer to skip the download entirely.AnthropicTokenizer: exact Claude counts via the API with per-string
caching, or a calibrated offline heuristic when no client is given. An API
failure degrades to the heuristic rather than taking the caller's packing
down with it.SectionReport.items: the items that survived packing, in render order.
Renderedtextis a lossy view -- once items are joined the boundaries are
gone -- and rebuilding messages by splitting on the separator would corrupt
any content legitimately containing it.
Notes
pack_chat()does not reimplement allocation. It maps messages onto
sections, calls the existingpack(), and maps the survivors back, so every
guarantee already proved forpack()holds for chat packing too. The
property tests assert them against both APIs.- Fully backwards compatible: no existing signature or behaviour changed.
v0.1.0
Initial release.
Added
pack()/ContextPacker: allocate a fixed token budget across competing
Sections using declared priority, with ties broken deterministically by
section name.min_tokens/max_tokensguarantees per section. Infeasible minimums
raiseBudgetTooSmallErrorinstead of silently violating one.reserved_output: hold back tokens for the model's reply so it is never
offered to a section.- Eviction strategies:
truncate(default),drop_oldest,drop_newest,
lowest_score_first,all_or_nothing. Custom strategies plug in via
Strategy+register_strategy()with no change to the allocator. - Pinned items (
Item(..., pinned=True)) that are never dropped or cut,
and raiseSectionOverflowErrorif they genuinely cannot fit. - Tokenizer adapters: dependency-free
CharTokenizer(default), any plain
str -> intcallable, and an optionalTiktokenTokenizerfor exact
OpenAI-family counts. PackResultaudit trail:used_tokens,remaining_tokens,complete,
per-sectionSectionReports, and a fullItemDecisionfor every item
with a human-readable reason. Serializes viato_dict()/to_json().- Fully typed and PEP 561 compliant: a
py.typedmarker ships in the
wheel, so type checkers in consuming projects honour these annotations. - Value semantics on
Item: hashable (usable in sets and as dict keys),
withmetadatacopied on construction so packing stays a pure function
and no caller dict can be mutated out from under you. - Eviction is linear in tokenizer calls, not quadratic -- token counts are
computed once and the running total maintained incrementally. Packing 400
messages costs 405 tokenizer calls rather than 80,603, and the gap widens
with size. - Zero runtime dependencies in the core install.