Metadata-Version: 2.4
Name: promptolian
Version: 2.3.4
Summary: Drop-in SDK for Anthropic & OpenAI — compresses prompts transparently. CLI + REST API + Claude Code MCP.
Author-email: Maurizio Lospi <maurizio.lospi@gmail.com>
License: MIT
Project-URL: Homepage, https://promptolian.com
Project-URL: Repository, https://github.com/Maurizio-L/promptolian-public
Keywords: prompt,compression,llm,tokens,claude,chatgpt,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Provides-Extra: tiktoken
Requires-Dist: tiktoken>=0.6; extra == "tiktoken"
Provides-Extra: nlp
Requires-Dist: tiktoken>=0.6; extra == "nlp"
Requires-Dist: spacy>=3.7; extra == "nlp"
Provides-Extra: proxy
Requires-Dist: flask>=3.0; extra == "proxy"
Requires-Dist: flask-cors>=4.0; extra == "proxy"
Requires-Dist: httpx>=0.27; extra == "proxy"
Provides-Extra: proxy-cloud
Requires-Dist: flask>=3.0; extra == "proxy-cloud"
Requires-Dist: flask-cors>=4.0; extra == "proxy-cloud"
Requires-Dist: httpx>=0.27; extra == "proxy-cloud"
Requires-Dist: psycopg2-binary>=2.9; extra == "proxy-cloud"
Requires-Dist: stripe>=9.0; extra == "proxy-cloud"
Provides-Extra: sdk
Requires-Dist: anthropic>=0.25; extra == "sdk"
Provides-Extra: sdk-openai
Requires-Dist: openai>=1.0; extra == "sdk-openai"
Provides-Extra: server
Requires-Dist: flask>=3.0; extra == "server"
Requires-Dist: flask-cors>=4.0; extra == "server"
Provides-Extra: self-hosted
Requires-Dist: flask>=3.0; extra == "self-hosted"
Requires-Dist: flask-cors>=4.0; extra == "self-hosted"
Requires-Dist: tiktoken>=0.6; extra == "self-hosted"
Requires-Dist: spacy>=3.7; extra == "self-hosted"
Requires-Dist: httpx>=0.27; extra == "self-hosted"
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Requires-Dist: httpx>=0.27; extra == "mcp"
Provides-Extra: full
Requires-Dist: promptolian[tiktoken]; extra == "full"
Requires-Dist: promptolian[nlp]; extra == "full"
Requires-Dist: promptolian[server]; extra == "full"
Requires-Dist: promptolian[mcp]; extra == "full"
Requires-Dist: stripe>=9.0; extra == "full"
Requires-Dist: psycopg2-binary>=2.9; extra == "full"

# Promptolian — Context Reliability Proxy for AI Agents

> Proxy layer for AI agents — keeps context intact across long conversations and eliminates redundant token costs. One line to add, zero changes to your agent logic.

**[promptolian.com](https://promptolian.com)** · [Pricing](https://promptolian.com/pricing.html) · [Dashboard](https://promptolian.com/dashboard.html) · [Docs](https://promptolian.com/docs.html)

---

## Install

```bash
pip install promptolian            # core (rule-based, no deps)
pip install "promptolian[proxy]"   # + transparent API proxy
pip install "promptolian[nlp]"     # + NLP compression (spacy)
pip install "promptolian[mcp]"     # + Claude Code MCP tool
pip install "promptolian[full]"    # everything
```

---

## Quick Start

```bash
# Transparent proxy at http://localhost:3002
python -m promptolian.proxy

# With automatic session reset at 70% of context window
python -m promptolian.proxy --reset-at 0.70

# With KV-sandwich compression (requires API key)
PROMPTOLIAN_API_KEY=your_key python -m promptolian.proxy --reset-at 0.70
```

Point your Anthropic or OpenAI client at `http://localhost:3002` — no other changes needed.

---

## What the proxy does

### Tool Result Compression

In agentic workflows, the same files get read multiple times, bash outputs repeat, and API responses recur across tool calls. The proxy deduplicates these automatically:

- **Exact repeat** → replaced with `[TOOL_CACHE_REF: same as call #N]` (~5 tokens instead of thousands)
- **Similar content** → replaced with a compact diff showing only what changed

Benchmark across 9 synthetic agentic sessions: **34.6% token savings on tool outputs, 99% fact retention**.

Works transparently for both Anthropic (`type=tool_result`) and OpenAI (`role=tool`) message formats. No configuration needed — fires automatically on every request.

Response header: `X-Promptolian-Tool-Tokens-Saved: <n>`

---

### Session Reset

The proxy tracks cumulative token usage per session. When usage approaches the model's context window limit, it automatically compresses the conversation history and starts a fresh session — injecting the compressed context as a system prompt. The provider never sees a context long enough to trigger their own native compression.

```bash
python -m promptolian.proxy --reset-at 0.70   # reset at 70% of context window
```

Two compression modes depending on your setup:

| Setup | Compression quality |
|---|---|
| No API key | Session reset disabled |
| `PROMPTOLIAN_API_KEY` set | KV-sandwich via cloud (4.26/5 quality score) |
| Run from source | KV-sandwich locally |

Response header: `X-Promptolian-Reset: true` when a reset occurs.

---

### Tool Schema Caching

The proxy adds `cache_control` to tool schemas and re-injects them on subsequent calls. Anthropic bills cached tokens at 10%.

```
Without proxy: 500 calls/day × 5 tools × 120 tok × 30 days = 9M tok/mo → $27.00
With proxy:    9M tok × 10% cache rate                       = 900K tok/mo → $2.70
```

---

## Context Engine (KV-sandwich)

KV-sandwich architecture — preserves what matters, compresses what doesn't:

- **HEAD** (first 2 turns): verbatim — session framing preserved
- **MIDDLE**: entity-encoded + compressed — redundant tokens removed
- **TAIL** (last 4 turns): verbatim — recent facts + task state intact

Benchmark results (25 sessions, Factory.ai 6-dimension scoring):

| | Promptolian | Anthropic built-in | OpenAI built-in |
|---|---|---|---|
| Quality score | **4.26 / 5** | 3.44 / 5 | 3.35 / 5 |
| Compression | 21.8% | 98.7% | 99.3% |

Requires a `PROMPTOLIAN_API_KEY` (cloud) or running from source.

---

## Free vs Paid

| Feature | Free (no key) | Paid (API key) |
|---|---|---|
| Tool result REF/DIFF compression | Yes | Yes |
| Tool schema caching | Yes | Yes |
| Rule-based `compress_prompt` (MCP) | Yes | Yes |
| KV-sandwich context compression | — | Yes |
| Session reset with full quality | — | Yes |

Get a key at [promptolian.com/pricing](https://promptolian.com/pricing.html) — Solo $9/mo, Team $49/mo.

---

## Claude Code — MCP Integration

```bash
pip install "promptolian[mcp]"
```

Add to `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "promptolian": {
      "command": "promptolian-mcp"
    }
  }
}
```

Restart Claude Code. Tools available: `compress_prompt`, `compress_tools_schema`, `compression_stats`.

---

## Plans

| Plan | Price | Sessions | Keys |
|---|---|---|---|
| Free | $0 | SQLite · self-hosted | — |
| Solo | $9/mo | PostgreSQL · always-on | 1 |
| Team | $49/mo | PostgreSQL · always-on | Up to 10 |

→ [promptolian.com/pricing.html](https://promptolian.com/pricing.html)
