promptolian 2.2.1__tar.gz

promptolian-2.2.1/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: promptolian
+Version: 2.2.1
+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*

promptolian-2.2.1/README.md

@@ -0,0 +1,148 @@
+# 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*

promptolian-2.2.1/promptolian/__init__.py

@@ -0,0 +1,17 @@
+"""Promptolian — prompt compression engine."""
+
+__version__ = "2.3.0"
+__author__  = "Maurizio Lospi"
+
+from .compress import compress, compress_messages, CompressionStats, count_tokens
+from .patch    import patch_anthropic, patch_openai, get_stats
+
+__all__ = [
+    "compress",
+    "compress_messages",
+    "CompressionStats",
+    "count_tokens",
+    "patch_anthropic",
+    "patch_openai",
+    "get_stats",
+]