synthelion 1.0.0__tar.gz

synthelion-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Francesco Paolo Passaro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

synthelion-1.0.0/PKG-INFO

@@ -0,0 +1,225 @@
+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).

synthelion-1.0.0/README.md

@@ -0,0 +1,194 @@
+# 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).

synthelion-1.0.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "synthelion"
+version = "1.0.0"
+description = "MCP plugin + Python library for LLM token compression. 50+ languages, zero ML models. Port of Caveman (C#)."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Passaro Francesco Paolo", email = "passaroweb@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["llm", "token", "compression", "prompt", "nlp", "mcp", "claude", "claude-code"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+# mcp is a core dependency — this package is primarily a Claude Code / MCP plugin
+dependencies = [
+    "brotli>=1.1",
+    "regex>=2024.1",
+    "mcp>=1.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/francescopaolopassaro/synthelion"
+Repository = "https://github.com/francescopaolopassaro/synthelion"
+"Bug Tracker" = "https://github.com/francescopaolopassaro/synthelion/issues"
+"Original C# project" = "https://github.com/francescopaolopassaro/caveman"
+
+[project.optional-dependencies]
+openai = ["openai>=1.0"]
+dev = ["pytest>=8.0", "pytest-asyncio>=0.23"]
+
+[project.scripts]
+synthelion = "synthelion.cli:main"
+synthelion-mcp = "synthelion.plugins.mcp_server:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["synthelion*"]
+
+[tool.setuptools.package-data]
+synthelion = ["worddata/*.br"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"

synthelion-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

synthelion-1.0.0/synthelion/__init__.py

@@ -0,0 +1,38 @@
+# Synthelion — Python port of Caveman (https://github.com/francescopaolopassaro/caveman)
+# © 2026 Passaro Francesco Paolo — Digitalsolutions.it
+"""Synthelion: token compressor for LLMs. 50+ languages, zero ML models.
+
+Python port of Caveman (C#) by Passaro Francesco Paolo (Digitalsolutions.it).
+Original: https://github.com/francescopaolopassaro/caveman
+"""
+from synthelion.models import (
+    CompressionLevel,
+    CompressionProfile,
+    CompressionResult,
+    ContentType,
+    RoutedCompressionResult,
+    VerbosityLevel,
+)
+from synthelion.word_provider import FunctionWordProvider
+from synthelion.detector import LanguageDetector
+from synthelion.core import CompressionFilter, CompressionService
+from synthelion.content_detector import ContentDetector
+from synthelion.content_router import ContentRouter
+
+__version__ = "1.0.0"
+__author__ = "Passaro Francesco Paolo"
+
+__all__ = [
+    "CompressionLevel",
+    "CompressionProfile",
+    "CompressionResult",
+    "CompressionFilter",
+    "ContentType",
+    "RoutedCompressionResult",
+    "VerbosityLevel",
+    "FunctionWordProvider",
+    "LanguageDetector",
+    "CompressionService",
+    "ContentDetector",
+    "ContentRouter",
+]

synthelion-1.0.0/synthelion/agent/__init__.py

@@ -0,0 +1,5 @@
+from synthelion.agent.context_window import ContextWindow
+from synthelion.agent.memory_extractor import MemoryExtractor
+from synthelion.agent.memory_store import MemoryStore
+
+__all__ = ["ContextWindow", "MemoryExtractor", "MemoryStore"]

synthelion-1.0.0/synthelion/agent/context_window.py

@@ -0,0 +1,87 @@
+# Synthelion — Python port of Caveman (https://github.com/francescopaolopassaro/caveman)
+# © 2026 Passaro Francesco Paolo — Digitalsolutions.it
+from __future__ import annotations
+
+import hashlib
+import json
+
+from synthelion.nlp.text_rank import TextRankSummarizer
+from synthelion.word_provider import FunctionWordProvider
+
+
+def _count_tokens(text: str) -> int:
+    return len(text) // 4
+
+
+class ContextWindow:
+    """Rolling token-budget conversation buffer for AI agents.
+
+    Ported from C# CavemanContextWindow. Auto-compacts older turns with
+    TextRank when the total token count exceeds max_tokens.
+    """
+
+    def __init__(
+        self,
+        max_tokens: int = 4000,
+        keep_last_turns: int = 4,
+        deduplicate: bool = False,
+        summarizer: TextRankSummarizer | None = None,
+    ) -> None:
+        if max_tokens <= 0:
+            raise ValueError("max_tokens must be positive")
+        self.max_tokens = max_tokens
+        self.keep_last_turns = keep_last_turns
+        self.deduplicate = deduplicate
+        self._messages: list[dict] = []
+        self._seen_hashes: set[str] = set()
+        self._summarizer = summarizer or TextRankSummarizer()
+
+    @property
+    def message_count(self) -> int:
+        return len(self._messages)
+
+    @property
+    def token_count(self) -> int:
+        return _count_tokens(self.render())
+
+    def append(self, role: str, content: str) -> None:
+        if not content or not content.strip():
+            return
+        h = hashlib.md5(content.encode()).hexdigest()
+        if self.deduplicate and h in self._seen_hashes:
+            return
+        self._seen_hashes.add(h)
+        self._messages.append({"role": role, "content": content})
+        if self.token_count > self.max_tokens:
+            self._compact()
+
+    def render(self) -> str:
+        return "\n".join(f"{m['role']}: {m['content']}" for m in self._messages)
+
+    def to_messages_json(self, indent: int | None = None) -> str:
+        return json.dumps(self._messages, ensure_ascii=False, indent=indent)
+
+    def to_messages(self) -> list[dict]:
+        return list(self._messages)
+
+    def clear(self) -> None:
+        self._messages.clear()
+        self._seen_hashes.clear()
+
+    def _compact(self) -> None:
+        """Summarize older turns to fit within the token budget."""
+        if len(self._messages) <= self.keep_last_turns:
+            return
+
+        system_msgs = [m for m in self._messages if m["role"] == "system"]
+        recent = self._messages[-self.keep_last_turns :]
+        old = self._messages[len(system_msgs) : len(self._messages) - self.keep_last_turns]
+
+        if not old:
+            return
+
+        old_text = "\n".join(f"{m['role']}: {m['content']}" for m in old)
+        summary = self._summarizer.summarize(old_text, ratio=0.3)
+
+        compacted = {"role": "assistant", "content": f"[Summary of earlier context: {summary}]"}
+        self._messages = system_msgs + [compacted] + recent

synthelion-1.0.0/synthelion/agent/memory_extractor.py

@@ -0,0 +1,44 @@
+# Synthelion — Python port of Caveman (https://github.com/francescopaolopassaro/caveman)
+# © 2026 Passaro Francesco Paolo — Digitalsolutions.it
+from __future__ import annotations
+
+import re
+
+from synthelion.nlp.text_rank import TextRankSummarizer
+from synthelion.word_provider import FunctionWordProvider
+
+
+class MemoryExtractor:
+    """Distils salient sentences and key terms from a conversation.
+
+    Ported from C# CavemanMemoryExtractor. Returns {summary, keywords}.
+    No embeddings — pure lexical extraction.
+    """
+
+    def __init__(self, word_provider: FunctionWordProvider | None = None) -> None:
+        self._provider = word_provider or FunctionWordProvider()
+        self._summarizer = TextRankSummarizer(self._provider)
+
+    def extract(self, text: str, max_sentences: int = 5) -> dict:
+        if not text or not text.strip():
+            return {"summary": "", "keywords": []}
+
+        summary = self._summarizer.summarize(text, sentence_count=max_sentences)
+        keywords = self._extract_keywords(text)
+        return {"summary": summary, "keywords": keywords[:20]}
+
+    def _extract_keywords(self, text: str) -> list[str]:
+        # Extract capitalized words (likely proper nouns / entities) and frequent nouns
+        from collections import Counter
+        words = re.findall(r"\b[A-Z][a-z]{2,}\b", text)
+        # Add most frequent content words
+        all_words = re.findall(r"\b[a-zA-Z]{4,}\b", text.lower())
+        common = [w for w, _ in Counter(all_words).most_common(30)]
+        seen: set[str] = set()
+        result: list[str] = []
+        for w in words + common:
+            low = w.lower()
+            if low not in seen:
+                seen.add(low)
+                result.append(w)
+        return result