Metadata-Version: 2.4
Name: powerailabs-contextkit
Version: 0.3.0
Summary: Assemble: declare prioritized, pinnable context blocks; pack them to a token budget with an inspectable receipt.
Author: Raghav Mishra
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: powerailabs-core<0.2,>=0.1
Provides-Extra: squeeze
Requires-Dist: powerailabs-squeeze<0.2,>=0.1; extra == 'squeeze'
Description-Content-Type: text/markdown

# powerailabs-contextkit

Treat the context window like a packed suitcase, not a string you concatenate. Declare blocks
with priorities and eviction rules; contextkit fits them to a token budget and tells you exactly
what it kept, shrank, and dropped.

**Every assembled prompt comes with a receipt.**

![status](https://img.shields.io/badge/status-building-yellow) ![license](https://img.shields.io/badge/license-MIT-blue)

🚧 building (v0) · `pip install powerailabs-contextkit` · `from powerailabs.contextkit import Context, Block`

```python
from powerailabs.contextkit import Context, Block

ctx = Context(budget_tokens=8000, model="claude-opus-4-8", reserve_output=1000)
ctx.add(Block(system_prompt, priority=10, pin=True, role="system"))
ctx.add(Block(retrieved_docs, priority=5, evict="compress"))   # uses squeeze if installed
ctx.add(Block(chat_history, priority=3, evict="drop_oldest"))
ctx.add(Block(user_msg, priority=9, pin=True, role="user"))

messages = ctx.assemble()      # provider-ready messages, guaranteed within budget
print(ctx.report())            # the receipt: kept / truncated / dropped + token math
#   [kept      ] system    42->42tok
#   [compressed] user      3120->980tok
#   [dropped   ] user      610->0tok   # chat_history didn't fit
preview = ctx.whatif(budget_tokens=4000)   # same inputs, tighter budget, no commit
```

**Inbound:** call contextkit *before* the model call to build the messages you send — it applies
whenever you assemble the prompt yourself. Assembly is deterministic (stable sort by pinned →
priority → insertion). `evict="compress"` wires in `powerailabs-contextkit[squeeze]` by shape (no
import); without it, `compress` falls back to `truncate`. The `report()` decisions flow onto
core's event stream, so `acttrace` records what context the model actually saw.

See [`docs/contextkit.md`](../../docs/contextkit.md). *Part of the PowerAI Labs stack — github.com/PowerAI-Labs/powerailabs.*
