promptolian 2.3.4

Drop-in SDK for Anthropic & OpenAI — compresses prompts transparently. CLI + REST API + Claude Code MCP.

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 · Pricing · Dashboard · Docs

---

Install

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

# 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.

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 — Solo $9/mo, Team $49/mo.

---

Claude Code — MCP Integration

pip install "promptolian[mcp]"

Add to ~/.claude/settings.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