Metadata-Version: 2.4
Name: promptolian
Version: 2.3.5
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

**AI agents burn tokens repeating themselves. Promptolian stops that — transparently, with one line of code.**

A local proxy that sits between your code and the Anthropic / OpenAI API. No SDK changes. No new abstractions. Just cheaper, more reliable agents.

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

---

## What it does

- **Deduplicates tool outputs** — when an agent reads the same file twice, the second read costs ~5 tokens instead of thousands
- **Prevents context wall failures** — resets the session automatically before the model hits its context limit, preserving what matters
- **Caches tool schemas** — Anthropic charges 10% for cached tokens; the proxy handles this for you

All free. No API key needed to start.

---

## Install

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

---

## Quick Start

```bash
python -m promptolian.proxy
```

Then change one line in your code:

```python
# Before
client = anthropic.Anthropic()

# After
client = anthropic.Anthropic(base_url="http://localhost:3002")
```

That's it. Every API call now goes through the proxy.

---

## Features

### Tool Result Compression (free)

In agentic workflows, the same files get read repeatedly, bash outputs recur, search results repeat. The proxy deduplicates automatically:

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

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

Works for both Anthropic (`tool_result`) and OpenAI (`role=tool`) formats. No configuration needed.

---

### Tool Schema Caching (free)

The proxy automatically adds `cache_control` to tool definitions. Anthropic charges 10% for cached tokens.

```
500 calls/day × 5 tools × 120 tokens × 30 days = 9M tokens/mo → $27
With caching:                                       900K tokens/mo → $2.70
```

---

### Session Reset (requires API key)

The proxy tracks token usage per session. When it approaches the model's context window limit, it compresses the conversation history and starts a fresh session — injecting the compressed context as a system prompt.

```bash
PROMPTOLIAN_API_KEY=your_key python -m promptolian.proxy --reset-at 0.70
```

Without a key, session reset is disabled and the proxy still runs with free features.

Compression quality benchmark (25 sessions, Factory.ai scoring):

| | Promptolian | Anthropic built-in | OpenAI built-in |
|---|---|---|---|
| Quality score | **4.26 / 5** | 3.44 / 5 | 3.35 / 5 |
| Tokens kept | 21.8% | 1.3% | 0.7% |

---

## Free vs Paid

| | Free | Paid |
|---|---|---|
| Tool result deduplication | Yes | Yes |
| Tool schema caching | Yes | Yes |
| Session reset + context compression | — | Yes |
| Compression quality score | — | 4.26 / 5 |

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

---

## Claude Code — MCP

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

Add to `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "promptolian": {
      "command": "promptolian-mcp"
    }
  }
}
```

Restart Claude Code. Adds `compress_prompt`, `compress_tools_schema`, and `compression_stats` tools.

---

## Health check

```bash
curl http://localhost:3002/proxy/health
```
