Metadata-Version: 2.5
Name: cap-shield
Version: 0.2.0
Summary: Context selection and compression for AI agents — measured, not estimated
Project-URL: Homepage, https://cap-shield-robin.fly.dev
Project-URL: Documentation, https://cap-shield-robin.fly.dev/docs/quickstart
Author: Robin Lidberg
License: MIT
Keywords: agents,ai,compression,context,llm,memory,rag,retrieval,tokens
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Requires-Dist: httpx>=0.24
Description-Content-Type: text/markdown

# cap-shield

Context selection for AI agents. **Measured, not estimated.**

```bash
pip install cap-shield
```

```python
from cap_shield import CapShield

cap = CapShield(api_key="cap_live_...")

cap.remember("support", "Customer reports a delayed parcel, order 4471")
ctx = cap.context("support", "what did the customer complain about?")

print(ctx.text)              # send this to your model
print(ctx.saving_pct, "%")   # how much you did not send
print(ctx.left_behind)       # ...and how many entries were left behind
```

## What this does

Your agent's history grows every turn, and the whole thing is billed on
every call. This selects what answers the question and leaves the rest.

Measured on our corpus with `cl100k_base`: **80.5 %** of context not sent
at a 1000-token budget. Measured on LongMemEval-S, 500 questions:
**93.8 %** retrieval recall against **51.9 %** for word matching.

That second number is the one that matters. A saving is worthless if what
was dropped is what your agent needed — so we publish both.

## What this does not do

It does not call your model. `ctx.text` goes to Claude, GPT or whatever
you use. This library never sees your model provider's keys.

It is not a proxy. Your uptime does not depend on ours for the model call
itself.

## Measure before you commit

**No account, no key:**

```python
from cap_shield import measure, print_measurement

print_measurement(measure(
    texts=["...your actual messages..."],
    query="what your agent would search for"))
```

Runs on your own traffic and stores nothing — the text is compressed in
memory, the numbers computed, and everything discarded. No dictionary is
trained on it.

Rate limited to 20 measurements per hour per IP. Enough to evaluate, not
enough to use the service for free.

## Two mechanisms, deliberately separate

`context()` saves **tokens** — what your model is billed for.
`pack()` saves **bytes** — bandwidth and storage. The packet is
decompressed before the model sees it, so it saves no tokens.

Conflating them is the most common misunderstanding about this product.

## Full documentation

<https://cap-shield-robin.fly.dev/docs/quickstart>
