Metadata-Version: 2.4
Name: synthelion
Version: 1.0.0
Summary: MCP plugin + Python library for LLM token compression. 50+ languages, zero ML models. Port of Caveman (C#).
Author-email: Passaro Francesco Paolo <passaroweb@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/francescopaolopassaro/synthelion
Project-URL: Repository, https://github.com/francescopaolopassaro/synthelion
Project-URL: Bug Tracker, https://github.com/francescopaolopassaro/synthelion/issues
Project-URL: Original C# project, https://github.com/francescopaolopassaro/caveman
Keywords: llm,token,compression,prompt,nlp,mcp,claude,claude-code
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: brotli>=1.1
Requires-Dist: regex>=2024.1
Requires-Dist: mcp>=1.0
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == "openai"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Dynamic: license-file

# Synthelion — Claude Code Plugin + Python Library

**Synthelion** is a [Claude Code](https://claude.ai/code) MCP plugin and Python library that reduces LLM token usage by stripping grammatical noise and lemmatizing words — across 50+ languages, with zero ML model dependencies.

> "Why use many tokens when few tokens do trick?" — A caveman (and your wallet).

Python port of [Caveman](https://github.com/francescopaolopassaro/caveman) by Passaro Francesco Paolo (Digitalsolutions.it).

---

## Use as Claude Code plugin (30 seconds)

**1. Install:**
```bash
pip install synthelion
```

**2. Add to Claude Code** (`~/.claude/settings.json` on macOS/Linux, `%APPDATA%\Claude\claude_desktop_config.json` on Windows):
```json
{
  "mcpServers": {
    "synthelion": {
      "command": "synthelion-mcp"
    }
  }
}
```

**3. Restart Claude Code.** Done — the tools `compress`, `detect_language`, `route_content`, `summarize`, `compress_batch` are now available.

**Zero-install with uvx:**
```json
{
  "mcpServers": {
    "synthelion": {
      "command": "uvx",
      "args": ["synthelion-mcp"]
    }
  }
}
```

→ Full plugin guide: [`docs/claude-code-plugin.md`](docs/claude-code-plugin.md)

---

Powered by Synthelion — © Passaro Francesco Paolo, Digitalsolutions.it (https://digitalsolutions.it)

---

## Installation

```bash
pip install synthelion
# With MCP server support (for Claude Code, OpenCode, …):
pip install "synthelion[mcp]"
# With OpenAI function tools:
pip install "synthelion[openai]"
```

---

## Quick start

```python
from synthelion import CompressionService, CompressionLevel

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")
```

---

## Compression levels

| Level | What it does | Typical savings |
|---|---|---|
| `LIGHT` | Remove stop words | ~25–35% |
| `SEMANTIC` | Stop words + lemmatization | ~30–69% |
| `AGGRESSIVE` | Lemmatization + generic-term pruning | ~35–70% |

---

## Language detection

```python
from synthelion import LanguageDetector

det = LanguageDetector()
print(det.detect("Vorrei un tavolo per due persone, per favore."))  # ita
scores = det.detect_with_scores("Where is the nearest train station?")
# {"eng": 0.42, ...}
```

---

## Content-aware routing

```python
from synthelion import ContentRouter, CompressionProfile

router = ContentRouter.from_profile(CompressionProfile.BALANCED)
result = router.route(content)   # auto-detects JSON/HTML/diff/log/code/prose
print(result.strategy_used, result.savings_pct)
```

---

## MCP server (Claude Code / OpenCode)

```bash
# Run the MCP server on stdio:
synthelion-mcp

# Or add to your Claude Code MCP config:
# {
#   "mcpServers": {
#     "synthelion": { "command": "synthelion-mcp" }
#   }
# }
```

Tools exposed: `compress`, `detect_language`, `route_content`, `summarize`, `compress_batch`.

---

## OpenAI function tools

```python
from synthelion.plugins.openai_tools import get_tool_definitions, execute_tool

tools = get_tool_definitions()
# Pass to: client.chat.completions.create(tools=tools, ...)

# Execute a tool call returned by the model:
result = execute_tool("compress", {"text": "...", "level": "semantic"})
```

---

## CLI

```bash
synthelion compress --text "Hello world, I would like to know..." --level semantic
synthelion detect --text "Guten Morgen, wie geht es Ihnen?"
synthelion route --file myfile.json
synthelion serve-mcp   # same as synthelion-mcp
```

---

## Summarization

```python
from synthelion.nlp import TfIdfSummarizer, TextRankSummarizer

summarizer = TfIdfSummarizer()
summary = summarizer.summarize(long_text, sentence_count=3)

tr = TextRankSummarizer()
summary = tr.summarize(long_text, ratio=0.3)
```

---

## Agent toolkit

```python
from synthelion.agent import ContextWindow, MemoryStore

window = ContextWindow(max_tokens=4000)
window.append("user", "Tell me about Rome.")
window.append("assistant", "Rome is the capital of Italy...")
# Auto-compacts when over budget:
print(window.to_messages_json())

memory = MemoryStore()
memory.remember({"summary": "User prefers Italian cuisine", "keywords": ["pizza", "pasta"]})
relevant = memory.recall("What food does the user like?", top_k=3)
```

---

## Attribution

Synthelion is a Python port of **Caveman** — © 2026 Passaro Francesco Paolo, Digitalsolutions.it.
Original C# source: https://github.com/francescopaolopassaro/caveman

Language data derived from [Universal Dependencies](https://universaldependencies.org/) treebanks (CC BY-SA / CC BY).
