promptbudget 0.1.0__tar.gz

promptbudget-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,93 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,tiktoken]"
+      - name: Test
+        run: pytest -q --cov=promptbudget --cov-report=term-missing
+
+  package:
+    # Catches packaging regressions that unit tests cannot see, such as a
+    # missing py.typed marker silently disabling type hints for consumers.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Build sdist and wheel
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+          python -m build
+
+      - name: Validate metadata renders on PyPI
+        run: twine check dist/*
+
+      - name: Assert py.typed ships in the wheel
+        run: |
+          python - <<'PY'
+          import glob, sys, zipfile
+          wheel = glob.glob("dist/*.whl")[0]
+          names = zipfile.ZipFile(wheel).namelist()
+          if not any(n.endswith("promptbudget/py.typed") for n in names):
+              sys.exit("py.typed missing from the wheel; PEP 561 consumers would lose all type hints")
+          print(f"py.typed present in {wheel}")
+          PY
+
+      - name: Install the built wheel and smoke-test it
+        run: |
+          python -m venv /tmp/smoke
+          /tmp/smoke/bin/pip install --quiet dist/*.whl
+          /tmp/smoke/bin/python - <<'PY'
+          from promptbudget import Item, Section, pack
+
+          result = pack(
+              [
+                  Section("system", "You are helpful.", priority=100),
+                  Section("history", [Item("x" * 50) for _ in range(10)], priority=10),
+              ],
+              budget=100,
+              reserved_output=10,
+          )
+          assert result.used_tokens <= 90, result.used_tokens
+          assert result.section("system").text
+          print("smoke test passed:", result.used_tokens, "tokens")
+          PY
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Ruff
+        run: ruff check .
+      - name: Ruff format
+        run: ruff format --check .
+      - name: Mypy
+        run: mypy

promptbudget-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,104 @@
+name: Release
+
+# Trigger by pushing a tag like v0.1.0. See RELEASING.md for the full
+# checklist -- this workflow assumes the version bump and changelog
+# entry are already committed before the tag is pushed.
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write   # to create the GitHub Release
+  id-token: write    # for PyPI trusted publishing (no API token needed)
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Verify the tag matches pyproject.toml
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PYPROJECT_VERSION=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG_VERSION" != "$PYPROJECT_VERSION" ]; then
+            echo "::error::Tag is v$TAG_VERSION but pyproject.toml says $PYPROJECT_VERSION. Fix one of them before releasing."
+            exit 1
+          fi
+
+      - name: Run the full test suite before shipping anything
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,tiktoken]"
+          pytest -q
+
+      - name: Build sdist and wheel
+        run: |
+          pip install build
+          python -m build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/promptbudget/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        # Requires a trusted publisher configured on pypi.org for this
+        # repo + workflow first. See RELEASING.md -- this step will fail
+        # until that one-time manual setup is done.
+
+  github-release:
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Extract this version's changelog section
+        id: notes
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          awk -v ver="$VERSION" '
+            $0 ~ "^## \\[" ver "\\]" { found=1; next }
+            found && /^## \[/ { exit }
+            found && /^\[.*\]: / { exit }
+            found { print }
+          ' CHANGELOG.md > release_notes.md
+          if [ ! -s release_notes.md ]; then
+            echo "::error::No CHANGELOG.md section found for version $VERSION. Add one before tagging."
+            exit 1
+          fi
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          body_path: release_notes.md
+          files: dist/*
+          generate_release_notes: false

promptbudget-0.1.0/.gitignore

@@ -0,0 +1,17 @@
+.venv/
+venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.hypothesis/
+.coverage
+htmlcov/
+.DS_Store
+.idea/
+.vscode/
+.env

promptbudget-0.1.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+Nothing yet.
+
+## [0.1.0] - 2026-09-09
+
+Initial release.
+
+### Added
+
+- `pack()` / `ContextPacker`: allocate a fixed token budget across competing
+  `Section`s using declared priority, with ties broken deterministically by
+  section name.
+- `min_tokens` / `max_tokens` guarantees per section. Infeasible minimums
+  raise `BudgetTooSmallError` instead 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 raise `SectionOverflowError` if they genuinely cannot fit.
+- Tokenizer adapters: dependency-free `CharTokenizer` (default), any plain
+  `str -> int` callable, and an optional `TiktokenTokenizer` for exact
+  OpenAI-family counts.
+- `PackResult` audit trail: `used_tokens`, `remaining_tokens`, `complete`,
+  per-section `SectionReport`s, and a full `ItemDecision` for every item
+  with a human-readable reason. Serializes via `to_dict()` / `to_json()`.
+- Fully typed and PEP 561 compliant: a `py.typed` marker 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),
+  with `metadata` copied 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.
+
+[Unreleased]: https://github.com/mathewOracle/promptbudget/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mathewOracle/promptbudget/releases/tag/v0.1.0

promptbudget-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to promptbudget
+
+Thanks for taking a look. This is a small library on purpose, so the bar for
+what goes in is deliberately narrow.
+
+## Ground rules
+
+**The budget invariant is sacred.** No change may allow packed output to exceed
+the declared budget. If you can produce an input that breaks it, that is a
+high-priority bug — please open an issue with the reproducing input.
+
+**Determinism is a feature.** Identical inputs must produce byte-identical
+prompts. Anything relying on set iteration order, dict insertion luck, or
+unstable sorts will be rejected. Tie-breaks must be explicit.
+
+**Fail loudly, never silently.** When the request cannot be satisfied, raise a
+descriptive error. Quietly returning a prompt that violates a declared guarantee
+is the exact failure mode this library exists to prevent.
+
+## Adding a strategy
+
+This should not require touching the allocator. If it does, that is a design
+smell worth raising in an issue first.
+
+```python
+from promptbudget import Strategy, StrategyResult, register_strategy
+
+
+class MyStrategy(Strategy):
+    name = "my_strategy"
+
+    def apply(self, section, items, allocated, tokenizer, separator):
+        # Must never return items whose rendered cost exceeds `allocated`.
+        # Must emit exactly one ItemDecision per input item.
+        return StrategyResult(kept_items, decisions)
+
+
+register_strategy("my_strategy", MyStrategy())
+```
+
+Strategies that only differ in *eviction order* should subclass the shared
+`_ItemwiseStrategy` helper and implement `eviction_order` — the cost accounting,
+separator handling and pinned-item logic already live there exactly once. Please
+don't copy it.
+
+Every new strategy needs:
+
+1. A unit test showing the ordering it promises.
+2. Inclusion in `SAFE_STRATEGIES` in `tests/test_properties.py`, so the property
+   suite proves it respects the budget across generated inputs.
+3. A row in the strategy table in the README.
+
+## Adding a tokenizer
+
+Subclass `Tokenizer` and implement `count`. You get a correct binary-search
+`truncate` for free — only override it if the underlying tokenizer can slice
+token ids directly, which is faster and exact.
+
+New tokenizers must stay **optional dependencies**. The core installs with none,
+and that is a promise to users, not an accident.
+
+## Running things
+
+```bash
+pip install -e ".[dev]"
+pytest                    # unit + property tests + README doctests
+ruff check . && ruff format --check .
+mypy
+```
+
+CI runs on Python 3.9 through 3.13. Please make sure it is green before asking
+for a review.
+
+## Pull requests
+
+- One logical change per PR.
+- Explain *why*, and say what you ruled out. Reviewers care more about the
+  discarded alternatives than the chosen one.
+- New behaviour needs a test that fails without your change. Verify that by
+  reverting the source and watching it go red.
+- Add an entry under `## [Unreleased]` in [CHANGELOG.md](CHANGELOG.md) for
+  anything a user of the library would notice -- new behaviour, a fixed bug,
+  a changed default. Pure refactors and test-only changes don't need one.
+- If you used an AI tool, that's fine -- but you must understand the code well
+  enough to defend every line in review. You are the author; the tool is not.
+
+## Reporting bugs
+
+The most useful bug report contains a `pack()` call, the inputs, what you
+expected, and what you got. Since packing is a pure function of its arguments,
+that is almost always enough to reproduce it exactly.

promptbudget-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mathew Kadambatt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

promptbudget-0.1.0/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.5
+Name: promptbudget
+Version: 0.1.0
+Summary: Deterministic context-window budgeting for LLM prompts, with a full audit trail of every token decision.
+Project-URL: Homepage, https://github.com/mathewOracle/promptbudget
+Project-URL: Repository, https://github.com/mathewOracle/promptbudget
+Project-URL: Issues, https://github.com/mathewOracle/promptbudget/issues
+Author-email: Mathew Kadambatt <49642721+mathewOracle@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: ai,budget,context-window,llm,prompt,prompt-engineering,rag,tokenizer,tokens
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0; extra == 'dev'
+Requires-Dist: mypy>=1.8; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: tiktoken
+Requires-Dist: tiktoken>=0.5; extra == 'tiktoken'
+Description-Content-Type: text/markdown
+
+# promptbudget
+
+**Deterministic context-window budgeting for LLM prompts — with a full audit trail of every token decision.**
+
+[![CI](https://github.com/mathewOracle/promptbudget/actions/workflows/ci.yml/badge.svg)](https://github.com/mathewOracle/promptbudget/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/promptbudget)](https://pypi.org/project/promptbudget/)
+[![Python](https://img.shields.io/badge/python-3.9%2B-blue)](https://pypi.org/project/promptbudget/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+[![Typed](https://img.shields.io/badge/typing-strict-blue)](https://peps.python.org/pep-0561/)
+
+Your system prompt, tool schemas, chat history and retrieved chunks are all competing
+for the same context window. Most codebases resolve that fight with a `while
+total > limit: messages.pop(0)` loop buried in a helper — which silently evicts the
+one document the answer depended on, and leaves you no way to find out.
+
+`promptbudget` makes that allocation an explicit, testable, auditable decision.
+
+```python
+from promptbudget import Section, Item, pack
+
+result = pack(
+    [
+        Section("system", SYSTEM_PROMPT, priority=100, strategy="all_or_nothing"),
+        Section("tools", tool_schemas, priority=90, min_tokens=2_000),
+        Section("history", messages, priority=50, strategy="drop_oldest"),
+        Section("retrieval", chunks, priority=40, strategy="lowest_score_first"),
+        Section("scratchpad", notes, priority=10, max_tokens=1_000),
+    ],
+    budget=128_000,
+    reserved_output=4_000,
+)
+
+send(result.text)
+
+for d in result.dropped():
+    log.info("%s[%d] %s: %s", d.section, d.index, d.action.value, d.reason)
+```
+
+```
+retrieval[7] dropped: lowest relevance score, evicted first to fit the section allocation
+scratchpad[0] truncated: cut to the tokens remaining in the section allocation
+```
+
+## Why this exists
+
+| The usual approach | What goes wrong |
+|---|---|
+| `messages[-10:]` | Breaks the moment one message is huge |
+| `while tokens > limit: pop(0)` | No priorities, no guarantees, drops pinned context |
+| Framework-native trimming | Handles chat history only — not tools, RAG chunks and history *together* |
+| Retry on `context_length_exceeded` | Pays for a failed call, and still doesn't decide *what* to shed |
+| All of the above | Cannot answer "why is that chunk missing from my prompt?" |
+
+Existing tools each cover a slice: LangChain's `trim_messages` trims message lists,
+LLMLingua compresses text, `tiktoken` counts tokens. None of them arbitrate a fixed
+budget across several sections with declared guarantees and tell you what they did.
+
+## Install
+
+```bash
+pip install promptbudget                 # zero dependencies
+pip install "promptbudget[tiktoken]"     # exact OpenAI-family token counts
+```
+
+Python 3.9+. The core has **no runtime dependencies**.
+
+## Core ideas
+
+### Sections compete; priority decides who wins
+
+Sections are served highest priority first. Ties break on name, so identical inputs
+always produce an identical prompt — the same reason you pin dependency versions.
+
+Rendering follows *your* list order, not priority order. Priority decides who gets
+tokens; you decide what the prompt reads like.
+
+### Guarantees are kept or the call fails
+
+```python
+Section("tools", tool_schemas, priority=90, min_tokens=2_000)
+```
+
+`min_tokens` is reserved before any lower-priority section is served — a greedy
+high-priority section cannot eat tokens promised downstream. If the minimums
+collectively don't fit, you get `BudgetTooSmallError` rather than a prompt that
+quietly violates one:
+
+```
+BudgetTooSmallError: Guaranteed minimums require 6000 tokens but only 4000 are
+available (budget=8000, reserved_output=4000). Lower a min_tokens value, raise
+the budget, or reduce reserved_output.
+```
+
+`max_tokens` is the mirror image: a cap, so a runaway history can't crowd out retrieval
+even when the window is empty.
+
+### Reserve room for the reply
+
+```python
+pack(sections, budget=128_000, reserved_output=4_000)
+```
+
+Forgetting the model's own output is the most common way to get a context-length
+error from a prompt that "obviously fits". Reserved tokens are never offered to a section.
+
+### Strategies decide what gets shed
+
+| Strategy | Behaviour | Use for |
+|---|---|---|
+| `"truncate"` *(default)* | Cuts the tail of the overflowing item | Prose, scratchpads |
+| `"drop_oldest"` | Evicts from the front | Chat history |
+| `"drop_newest"` | Evicts from the back | Append-only logs |
+| `"lowest_score_first"` | Evicts least-relevant items | RAG chunks |
+| `"all_or_nothing"` | Delivers intact or raises | System prompts, tool schemas |
+
+Pin anything that must survive:
+
+```python
+Item("The user's actual question", pinned=True)
+```
+
+Pinned items are never dropped or cut. If a pinned item genuinely cannot fit, you get
+`SectionOverflowError` — a loud failure beats a mangled prompt.
+
+Bring your own by subclassing `Strategy`:
+
+```python
+from promptbudget import Strategy, StrategyResult, register_strategy
+
+
+class DeduplicateThenTruncate(Strategy):
+    name = "dedupe"
+
+    def apply(
+        self, section, items, allocated, tokenizer, separator
+    ): ...  # return StrategyResult(items, decisions)
+
+
+register_strategy("dedupe", DeduplicateThenTruncate())
+```
+
+### Any tokenizer, or none
+
+```python
+from promptbudget import TiktokenTokenizer, pack
+
+pack(sections, budget=128_000, tokenizer=TiktokenTokenizer("gpt-4o"))
+pack(sections, budget=8_000, tokenizer=lambda text: len(text) // 4)  # any str -> int
+pack(sections, budget=8_000)  # built-in heuristic
+```
+
+The allocator never imports a tokenizer directly — it talks to the `Tokenizer`
+interface, so HuggingFace, a provider SDK, or your own estimator all drop straight in.
+
+### The result explains itself
+
+```python
+result.text  # the fitted prompt
+result.used_tokens  # what it actually costs
+result.remaining_tokens  # headroom left
+result.complete  # True when nothing was lost
+result.dropped()  # every item that lost content, and why
+result.section("rag")  # per-section accounting
+result.to_json(indent=2)  # structured logging, ready to ship
+```
+
+Because packing is a pure function returning a plain value, you can assert on it:
+
+```python
+def test_the_user_question_always_survives():
+    result = pack(sections, budget=4_000)
+    assert "user_question" not in {d.section for d in result.dropped()}
+```
+
+## Guarantees
+
+Verified by property-based tests across hundreds of generated inputs
+([`tests/test_properties.py`](tests/test_properties.py)):
+
+- The output **never** exceeds the budget.
+- Reserved output tokens are **never** consumed.
+- `max_tokens` caps are **never** breached.
+- Identical inputs produce **byte-identical** prompts.
+- Every item receives **exactly one** decision — nothing vanishes unrecorded.
+- `complete` never lies about dropped content.
+
+## Development
+
+```bash
+git clone https://github.com/mathewOracle/promptbudget && cd promptbudget
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest && ruff check . && mypy
+```
+
+Contributions welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). New strategies are
+especially welcome, and shouldn't require touching the allocator at all.
+
+See [CHANGELOG.md](CHANGELOG.md) for release history and
+[RELEASING.md](RELEASING.md) for how versions get published.
+
+## License
+
+MIT — see [LICENSE](LICENSE).