Metadata-Version: 2.4
Name: promptolian
Version: 2.3.0
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-lospi/promptolian
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)

---

## Quick Start (dev)

```bash
# 1. Setup (run once)
bash ~/promptly/workspace.sh

# 2. Start public API at http://localhost:3001
cd ~/promptly/public/api && python3 api.py

# 3. Start transparent proxy at http://localhost:3002
python -m promptolian.proxy
# or: python -m promptolian.proxy --compress   (+ context history compression)

# 4. Full dev workspace (tmux — API + proxy + website + monitor)
~/promptly/workspace.sh
```

---

## Project Structure

```
~/promptly/
│
├── public/                        ← Public git submodule (promptolian.com)
│   ├── website/
│   │   ├── index.html             ← Landing page
│   │   ├── pricing.html           ← Pricing + ROI calculator
│   │   ├── benchmarks.html        ← Context quality benchmark results
│   │   └── docs.html              ← Integration docs
│   ├── api/
│   │   ├── api.py                 ← Flask REST API (port 3001)
│   │   └── context_engine.py      ← KV-sandwich context compression pipeline
│   └── promptolian/
│       ├── proxy.py               ← Transparent proxy (port 3002)
│       └── __main__.py            ← CLI entry point
│
├── tools/
│   ├── hooks/                     ← Claude Code compression hooks
│   ├── scripts/
│   │   ├── benchmark_compression.py  ← 25-session quality benchmark (Factory.ai methodology)
│   │   ├── build_sessions_50.py      ← Session data builder for benchmarks
│   │   ├── article_draft.md          ← Article: "Your AI Agent Is Forgetting Things"
│   │   ├── gen_article_cover.py      ← Cover image generator (PIL)
│   │   └── article_images/           ← cover_article.png, kv_sandwich.svg, ...
│   ├── audit/
│   │   └── fact_retention_check.py   ← Regex-only fact retention auditor (OSS)
│   ├── dev/                       ← Local dev utilities
│   └── reports/                   ← Roadmap, schemas, onboarding docs
│
├── services/                      ← Production Flask server + dashboard
│
├── tests/
│   ├── test_engine.py             ← Engine tests
│   ├── test_context_engine.py     ← Context engine tests
│   └── test_api.py                ← API endpoint tests
│
└── monitor.py                     ← Live DB stats + fix tracker
```

---

## Context Engine

`public/api/context_engine.py` — KV-sandwich architecture:

- **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% |

---

## Tool Schema Caching (proxy)

The transparent 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
```

---

## Tests

```bash
# Run all tests
python3 -m pytest tests/ -v

# By module
python3 -m pytest tests/test_context_engine.py
python3 -m pytest tests/test_api.py
```

---

## Fact Retention Audit (OSS)

```bash
python3 tools/audit/fact_retention_check.py session.json --verbose --threshold 80
```

Regex-only (no LLM). Extracts numbers, URLs, key=value pairs, hostnames from session messages, checks survival rate after compression. Exit 0 = pass, 1 = below threshold.

---

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

---

## Tech Stack

| Layer | Tool |
|-------|------|
| Context engine | Python (rule-based, no LLM) |
| Proxy | Python / Flask |
| Public API | Flask + Flask-CORS |
| Database (local) | SQLite |
| Database (prod) | PostgreSQL (Railway) |
| Payments | Stripe |
| Website hosting | Vercel |

---

*Last updated: 2026-05-27 · Maurito · Zürich*
