Universal token compressor for AI agents — MCP, OpenAI, LangChain, CLI. 50+ languages, zero ML models.
Project description
Synthelion — Universal Token Compressor and Prompt Manager for AI Agents
Supports 50+ languages out of the box. No AI model required. No configuration.
"Why use many tokens when few tokens do trick?" — A caveman (and your wallet).
Why Synthelion?
Every token sent to a model costs money and time. Synthelion removes the words that carry no meaning — articles, prepositions, conjunctions, auxiliary verbs — and reduces inflected words to their base form. The model receives exactly the same information, just without the grammatical packaging.
Before / After
English prose — 20 tokens → 7 tokens (−65%)
Before: I would like to know if it is possible to receive information about
cheap restaurants in Rome.
After: know possible receive information cheap restaurant Rome
Italian prose — 17 tokens → 8 tokens (−52%)
Before: Vorrei sapere se è possibile ricevere informazioni sui ristoranti
economici a Roma, per favore.
After: sapere possibile ricevere informazione ristorante economico Roma
JSON array — 256 tokens → 80 tokens (−69%)
// Before: full JSON with repeated keys on every object
[{"name":"Alice","age":30,"city":"Rome"},{"name":"Bob","age":25,"city":"Milan"},…]
// After: lossless markdown table
| name | age | city |
| ----- | --- | ----- |
| Alice | 30 | Rome |
| Bob | 25 | Milan |
HTML page — 192 tokens → 58 tokens (−70%)
// Before: full HTML with tags, attributes, scripts
<html><head>…</head><body><div class="…"><p>Visit Rome today…</p></div></body></html>
// After: clean extracted text, then NLP-compressed
Visit Rome today enjoy ancient history food culture
Benchmark — token savings by content type
Measured on GPT-4 token counts with real inputs.
NLP compression
| Content | Original tokens | Light | Semantic | Aggressive |
|---|---|---|---|---|
| Prose EN | 92 | −35.9% | −34.8% | −34.8% |
| Prose IT | 93 | −23.7% | −28.0% | −51.6% |
| Prose DE | 81 | −25.9% | −28.4% | −35.8% |
| Prose FR | 65 | −33.8% | −32.3% | −38.5% |
| Prose ES | 51 | −27.5% | −19.6% | −27.5% |
| JSON array | 256 | −66.8% | −68.8% | −68.8% |
| Git diff | 196 | −51.0% | −58.2% | −58.2% |
| Build log | 207 | −32.4% | −62.3% | −62.3% |
| Markdown table | 158 | −60.8% | −64.6% | −64.6% |
| HTML page | 192 | −45.3% | −49.0% | −50.0% |
| Source code | 249 | −41.0% | −41.0% | −41.0% |
Content router (Balanced profile — auto-selects the best strategy)
| Content | Original | After | Saved | Strategy |
|---|---|---|---|---|
| Prose EN | 92 | 60 | −34.8% | NlpCompression |
| JSON array | 256 | 134 | −47.7% | JsonCrush:MarkdownTable |
| Git diff | 196 | 137 | −30.1% | DiffCompression |
| HTML page | 192 | 58 | −69.8% | HtmlExtract+NlpCompression |
| Source code | 249 | 184 | −26.1% | CodeCompression |
What this means for your costs
Token pricing varies by model. As a rough example with GPT-4o ($2.50 / 1M input tokens):
| Daily input volume | Without Synthelion | With Synthelion (40% avg savings) | Annual saving |
|---|---|---|---|
| 500K tokens/day | $456/year | $274/year | $182/year |
| 2M tokens/day | $1,825/year | $1,095/year | $730/year |
| 10M tokens/day | $9,125/year | $5,475/year | $3,650/year |
Savings scale with volume. For agent loops that send the same context on every call, real savings are often higher than the 40% average.
Energy & sustainability
Synthelion includes a built-in energy estimator. Every saved token avoids approximately 0.005 mWh of compute energy and 0.002 mg CO₂. At scale, that adds up.
result = svc.compress(long_prompt, CompressionLevel.SEMANTIC)
print(f"Energy saved: {result.estimated_energy_saved_mwh:.3f} mWh")
print(f"CO₂ avoided: {result.estimated_co2_saved_mg:.3f} mg")
Install
pip install synthelion
Integrations
MCP — Claude Code, Claude Desktop, OpenCode, Cursor, Windsurf, Continue…
Any agent that supports the Model Context Protocol can use Synthelion as a tool server.
1. Open your agent's MCP settings file:
| Agent | Settings file |
|---|---|
| Claude Code | ~/.claude/settings.json |
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
| OpenCode | ~/.config/opencode/config.json |
| Cursor / Windsurf | MCP settings in the app |
2. Add this block:
{
"mcpServers": {
"synthelion": {
"command": "synthelion-mcp"
}
}
}
3. Restart the agent. Done.
Zero-install with uvx (no pip install needed if you have uv):
{
"mcpServers": {
"synthelion": {
"command": "uvx",
"args": ["synthelion-mcp"]
}
}
}
Once connected, just ask naturally:
"Compress this text to save tokens"
"Summarize this article in 3 sentences"
"Detect the language of this message"
"Compress this JSON / HTML / diff / log"
OpenAI — GPT-4, GPT-4o, Codex, and any OpenAI-compatible API
from openai import OpenAI
from synthelion.plugins.openai_tools import get_tool_definitions, execute_tool
client = OpenAI()
tools = get_tool_definitions()
response = client.chat.completions.create(
model="gpt-4o",
messages=[{"role": "user", "content": "Compress this text: I would like to know if it is possible..."}],
tools=tools,
tool_choice="auto",
)
# Handle tool calls returned by the model
for tool_call in response.choices[0].message.tool_calls or []:
result = execute_tool(tool_call.function.name, tool_call.function.arguments)
print(result)
LangChain — LangGraph, LCEL, ReAct agents
pip install "synthelion[langchain]"
from synthelion.plugins.langchain_tools import get_tools
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
llm = ChatOpenAI(model="gpt-4o")
tools = get_tools()
agent = create_react_agent(llm, tools)
result = agent.invoke({"messages": [{"role": "user", "content": "Compress this prompt: ..."}]})
Works with any LangChain-compatible LLM (OpenAI, Anthropic, Groq, Ollama, …).
Python API — any custom agent or pipeline
from synthelion import CompressionService, CompressionLevel, ContentRouter, CompressionProfile
# Compress text
svc = CompressionService()
result = svc.compress(
"I would like to know if it is possible to receive information about cheap restaurants in Rome.",
CompressionLevel.SEMANTIC,
)
print(result.compressed_text) # "know possible receive information cheap restaurant Rome"
print(f"{result.efficiency_pct:.1f}% saved")
# Auto-route any content type (JSON, HTML, diff, log, code, prose)
router = ContentRouter.from_profile(CompressionProfile.BALANCED)
routed = router.route(my_content)
print(routed.strategy_used, f"{routed.savings_pct:.1f}% saved")
CLI — shell scripts, pipelines, any language
# Compress text
synthelion compress --text "I would like to know if it is possible..." --level semantic
# Detect language
synthelion detect --text "Guten Morgen, wie geht es Ihnen?"
# Auto-route a file
synthelion route --file context.json
# Summarize
synthelion summarize --text "..." --sentences 3
# Start MCP server manually
synthelion serve-mcp
Pipe-friendly — reads from stdin if no --text or --file is given:
cat big_prompt.txt | synthelion compress --level aggressive
Tools
| Tool | What it does |
|---|---|
| compress | Removes stop words, lemmatizes content words. Up to 70% token reduction. |
| detect_language | Identifies language of any text. Returns ISO 639-3 code. |
| route_content | Auto-detects JSON, HTML, diff, log, code or prose and applies the best algorithm. |
| summarize | Extractive summarization — keeps the most important sentences (TF-IDF or TextRank). |
| compress_batch | Compresses a list of texts in one call. |
Compression levels
| Level | What it removes | Typical savings |
|---|---|---|
light |
Stop words (articles, prepositions, conjunctions…) | 25–35% |
semantic |
Stop words + lemmatization to base form | 30–69% |
aggressive |
Everything above + generic verbs and descriptive adjectives | 35–70% |
Default: semantic.
Supported languages (50+)
Afrikaans · Arabic · Armenian · Basque · Belarusian · Bengali · Bulgarian · Catalan · Chinese · Croatian · Czech · Danish · Dutch · English · Estonian · Finnish · French · Galician · German · Greek · Hebrew · Hindi · Hungarian · Icelandic · Indonesian · Irish · Italian · Japanese · Kannada · Kazakh · Korean · Latin · Latvian · Lithuanian · Macedonian · Malay · Marathi · Norwegian · Persian · Polish · Portuguese · Romanian · Russian · Serbian · Slovak · Slovenian · Spanish · Swedish · Tamil · Telugu · Thai · Turkish · Ukrainian · Urdu · Vietnamese
Language is detected automatically from the text. Pass an explicit ISO 639-3 code to override.
Troubleshooting
synthelion-mcp: command not found
Use the module form instead:
{
"mcpServers": {
"synthelion": {
"command": "python",
"args": ["-m", "synthelion.plugins.mcp_server"]
}
}
}
Or use uvx — it always works without PATH issues.
Links
- PyPI: https://pypi.org/project/synthelion/
- Source: https://github.com/francescopaolopassaro/synthelion
- Original C# project (Caveman): https://github.com/francescopaolopassaro/caveman
© 2026 Passaro Francesco Paolo — Digitalsolutions.it
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file synthelion-1.0.3.tar.gz.
File metadata
- Download URL: synthelion-1.0.3.tar.gz
- Upload date:
- Size: 12.8 MB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
c0d621b6be9652f6d985fe56172558b663feb15467fd7e232d46ad8c144f24a2
|
|
| MD5 |
13c7d02cfd8ab91a2a31f6f07c69a8ff
|
|
| BLAKE2b-256 |
8b0ad3484bd5af68f222d700d491842fefeef9cd15a5fb196153352d8223e720
|
File details
Details for the file synthelion-1.0.3-py3-none-any.whl.
File metadata
- Download URL: synthelion-1.0.3-py3-none-any.whl
- Upload date:
- Size: 12.8 MB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/6.2.0 CPython/3.12.10
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ef6761eb6ee4eede0253673d0cb8cd2693ed542f10c6db775c1bf9827e897fd4
|
|
| MD5 |
1ab79f9fe22821cd6457f1475be5439b
|
|
| BLAKE2b-256 |
3cd02b2413dbbb253ea054d890e7d42dc4612ded67621089c7ef911b1fbe5e7b
|
