Metadata-Version: 2.4
Name: prompt-token-trim-py
Version: 0.1.0
Summary: Trim prompt messages to fit a token budget while preserving priority. Python port of @mukundakatta/prompt-token-trim.
Project-URL: Homepage, https://github.com/MukundaKatta/prompt-token-trim-py
Project-URL: Issues, https://github.com/MukundaKatta/prompt-token-trim-py/issues
Project-URL: Source, https://github.com/MukundaKatta/prompt-token-trim-py
Project-URL: JS sibling, https://www.npmjs.com/package/@mukundakatta/prompt-token-trim
Author-email: Mukunda Katta <mukunda.vjcs6@gmail.com>
License: MIT
License-File: LICENSE
Keywords: agents,ai,evals,llm,prompts,rag,tokens,trim
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 :: Only
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# prompt-token-trim-py

[![PyPI](https://img.shields.io/pypi/v/prompt-token-trim-py.svg)](https://pypi.org/project/prompt-token-trim-py/)
[![Python](https://img.shields.io/pypi/pyversions/prompt-token-trim-py.svg)](https://pypi.org/project/prompt-token-trim-py/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**Trim prompt messages to fit a token budget while preserving priority.** Sort messages by `priority` (descending), accept each if it fits, then re-emit them in original order. Zero runtime dependencies.

Python port of [@mukundakatta/prompt-token-trim](https://www.npmjs.com/package/@mukundakatta/prompt-token-trim).

> Note: see also [agentfit-py](https://github.com/MukundaKatta/agentfit-py). They look similar; this one is **message-level priority trimming** (drop a single message if it doesn't fit). agentfit-py is **whole-history strategy fitting** (drop-oldest, drop-middle, priority, with system-message preservation and partial-result modes).

## Install

```bash
pip install prompt-token-trim-py
```

## Quick start

```python
from prompt_token_trim import trim

messages = [
    {"role": "system", "content": "You are a helpful assistant.", "priority": 10},
    {"role": "user",   "content": "Tell me about Pluto.",          "priority": 5},
    {"role": "assistant", "content": "Pluto is a dwarf planet.",   "priority": 5},
    {"role": "user",   "content": "And Mars?",                     "priority": 1},
]

result = trim(messages, budget=20, preserve_system=True)

result.messages  # list[dict] in original order, kept under budget
result.tokens    # int -- tokens consumed
result.dropped   # int -- count of messages dropped
```

## API

### `trim(messages, budget, *, preserve_system=True) -> TrimResult`

* `messages`: list of dicts with `role`, `content`, optional `priority` (defaults to `0`).
* `budget`: token budget (`ceil(len(content) / 4)` heuristic per message).
* `preserve_system`: keep all `role == "system"` messages even if they don't fit (they consume budget anyway). Defaults to `True`.

`TrimResult` is a dataclass with:

* `messages`: kept messages, in their original order.
* `tokens`: total tokens consumed.
* `dropped`: count of messages that did not survive.

The JS sibling exposes `trimMessages({maxTokens})` -- the `trim_messages(messages, *, max_tokens=...)` alias is provided for parity.

## License

MIT
