Metadata-Version: 2.4
Name: sanskrit-mesh
Version: 1.0.0
Summary: AI-native bytecode compiler that reduces LLM token costs 55-75% using Paninian-inspired Intermediate Representation.
Home-page: https://github.com/krishanumanna48-ctrl/sanskrit-mesh
Author: Krishanu Manna
Author-email: krishanumanna48@gmail.com
Project-URL: Bug Reports, https://github.com/krishanumanna48-ctrl/sanskrit-mesh/issues
Project-URL: Source, https://github.com/krishanumanna48-ctrl/sanskrit-mesh
Keywords: ai llm agents tokens compression autogen crewai langchain openai cost token-reduction context-window
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Provides-Extra: langchain
Requires-Dist: langchain>=0.1.0; extra == "langchain"
Provides-Extra: autogen
Requires-Dist: pyautogen>=0.2.0; extra == "autogen"
Provides-Extra: all
Requires-Dist: langchain>=0.1.0; extra == "all"
Requires-Dist: pyautogen>=0.2.0; extra == "all"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-python
Dynamic: summary

# Sanskrit-Mesh

> **Why are your AI agents wasting millions of tokens being polite to each other?**

`Sanskrit-Mesh` is an AI-native bytecode compiler for **multi-agent LLM pipelines**. It intercepts the structured payloads that frameworks like AutoGen, LangChain, and CrewAI generate automatically — agent messages, memory objects, tool calls, system prompts — and compresses them into an ultra-dense Intermediate Representation (IR) inspired by Panini's Sanskrit grammar. On the other side, it decompiles back to perfect English with zero data loss.

**Result: 55–77% token reduction on agent-generated payloads. Zero logic changes to your pipeline.**

> **What V1 does and doesn't do**
>
> ✅ Compresses structured agent payloads (JSON keys, framework boilerplate, error messages, system prompts, status fields, tool call structures)
>
> ✅ Works with AutoGen, LangChain, or any OpenAI-format API call
>
> ❌ Does **not** compress freeform human text — a user typing "deploy my app" saves nothing. The dictionary covers agent vocabulary, not natural conversation.
>
> ❌ Does **not** speed up inference or reduce model size

---

## The Problem

Multi-agent systems (AutoGen, CrewAI, LangChain) auto-generate and transmit repetitive structured payloads on every step:

```json
{
  "sender": "Agent A",
  "receiver": "Agent B",
  "intent": "Request Clarification",
  "context": {
    "status": "failed",
    "message": "I encountered the following error: NullPointerException: object reference not set. Please advise on how to proceed."
  }
}
```
*232 characters. Sent hundreds of times per pipeline run. You never wrote this — your framework did.*

## The Solution

Sanskrit-Mesh compresses it to:

```json
{"s":"|AgA|","r":"|AgB|","i":"|Prashna|","c":{"st":"|F|","m":"|E:| |ShunyaDosha|. |?|"}}
```
*88 characters. Same meaning. **62% smaller.***

Three compression layers running simultaneously:
1. **Key minification** — JSON keys shrunk to 1–3 chars (`"sender"` → `"s"`, `"intermediate_steps"` → `"is_"`)
2. **Semantic IR dictionary** — 200+ agent phrases mapped to dense Sanskrit tokens
3. **Whitespace stripping** — removes bloat agents auto-generate

---

## Why Paninian Grammar?

Panini formalized Sanskrit grammar 2,500 years ago into the most concise, unambiguous linguistic rule system ever written. It encodes complex meaning in single dense constructs — exactly what machine-to-machine communication needs. `MemoryError: out of memory` becomes `SmritiBhara`. `ConnectionError: failed to establish connection` becomes `BandhanDosha`. Dense, unambiguous, lossless.

---

## Installation

```bash
# Clone and use directly
git clone https://github.com/krishanumanna48-ctrl/sanskrit-mesh.git
cd sanskrit-mesh
```

No dependencies required for the base compiler and middleware. LangChain and AutoGen integrations require those packages installed separately.

> PyPI release (`pip install sanskrit-mesh`) coming soon.

---

## Quickstart

### Universal — Works With Any OpenAI-Format API

```python
from middleware import SanskritMeshMiddleware

middleware = SanskritMeshMiddleware()

# These messages contain agent-generated content — compresses well
messages = [
    {"role": "system",    "content": "You are a helpful, harmless, and honest assistant. Think step by step before answering. Always respond in JSON format."},
    {"role": "assistant", "content": "I will execute the tool to deploy. The deployment failed. Running again..."},
    {"role": "tool",      "content": "I encountered the following error: ConnectionError: failed to establish connection. Please advise on how to proceed."},
]

# NOTE: human freeform text (user messages) compresses minimally.
# The savings come from system prompts, assistant messages, and tool responses.
compressed = middleware.compress_messages(messages)

response = openai_client.chat.completions.create(
    model="gpt-4o",
    messages=compressed
)

print(middleware.get_savings_report())
```

### System Prompt Compression

System prompts are one of the best targets — they're repetitive, written by developers, and run on **every single API call**.

```python
from middleware import SanskritMeshMiddleware

middleware = SanskritMeshMiddleware()

system_prompt = (
    "You are a helpful, harmless, and honest assistant. "
    "You are operating in a multi-agent environment. "
    "Think step by step before answering. "
    "Always respond in valid JSON. "
    "Your goal is to complete the assigned task efficiently."
)

compressed = middleware.compress_system_prompt(system_prompt)
# Result: |sys:hhh| |sys:multi| |sys:CoT| |sys:json+| |sys:goal|
# 315 chars → 74 chars. 76.5% smaller. Runs on every call.
```

### LangChain Integration

```python
from middleware import SanskritMeshLangChainCallback
from langchain_openai import ChatOpenAI

# One line — attaches to any LangChain LLM
callback = SanskritMeshLangChainCallback(verbose=True)
llm = ChatOpenAI(model="gpt-4o", callbacks=[callback])

# System prompts, memory, agent scratchpad all get compressed automatically
response = llm.invoke("Deploy the application.")

print(callback.get_session_report())
```

Compress LangChain memory directly:
```python
compressed_memory = callback.compress_memory(memory.chat_memory.dict())
```

### AutoGen Integration

```python
from middleware import SanskritMeshAutoGenHook
import autogen

hook = SanskritMeshAutoGenHook(verbose=True)

planner  = autogen.ConversableAgent("PlannerAgent", ...)
executor = autogen.ConversableAgent("ExecutorAgent", ...)

# Register — all agent-to-agent messages compressed before transmission
planner.register_hook(
    hookable_method="process_message_before_send",
    hook=hook.compress_hook
)

# Compress full conversation history before passing to a new agent
compressed_history = hook.compress_conversation_history(
    planner.chat_messages[executor]
)
```

### Raw Compiler

```python
from compiler import SanskritMeshCompiler

compiler = SanskritMeshCompiler()

payload = {
    "intent": "Request Clarification",
    "message": "I encountered the following error: IndexError: list index out of range. Please advise on how to proceed."
}

compressed = compiler.compile_payload(payload)
# {'i': '|Prashna|', 'm': '|E:| |KramaBhanga|. |?|'}

restored = compiler.decompile_payload(compressed)
assert restored == payload  # 100% lossless — guaranteed
```

---

## Live Benchmark

Run the benchmark suite on your machine:

```bash
python benchmark.py
```

Test your own payload:
```bash
python benchmark.py --payload '{"role": "system", "content": "You are a helpful assistant. Think step by step."}'
```

Test a JSON file:
```bash
python benchmark.py --file my_agent_payload.json
```

### Real Benchmark Results (V1)

Actual numbers from `python benchmark.py` — verifiable on your machine.

| Benchmark | Original | Compressed | Saving |
|---|---|---|---|
| Simple agent message | 232 chars | 88 chars | **62.1%** |
| System prompt | 373 chars | 87 chars | **76.7%** |
| LangChain memory / chat history | 864 chars | 379 chars | **56.1%** |
| Complex nested multi-agent payload | 833 chars | 374 chars | **55.1%** |
| ReAct agent scratchpad | 656 chars | 335 chars | **48.9%** |
| Worst case (zero dictionary matches) | 245 chars | 236 chars | 3.7% |

**Real-world average on agent-generated traffic: ~59–62%**

The worst case benchmark is deliberately adversarial — pure narrative text with zero agent vocabulary. That's not what Sanskrit-Mesh is built for. Real agent pipelines land between 55–77%.

---

## What V1 Can Actually Save

| Payload Type | Max Observed | Typical Range | Notes |
|---|---|---|---|
| System prompts | **76.7%** | 60–77% | Best target — repetitive, developer-written |
| Simple agent messages | **62.1%** | 55–65% | Framework-generated boilerplate |
| Multi-agent nested payloads | **55–62%** | 50–65% | AutoGen / CrewAI message chains |
| ReAct scratchpads | **48.9%** | 40–55% | Mixed agent + reasoning text |
| Human freeform text | ~0–4% | 0–8% | Not the target — key minification only |

**V1 ceiling: ~77%. Real-world average on agent pipelines: ~59%.**

---

## Cost Savings at Scale

Based on real benchmark averages (~59% compression, GPT-4o input pricing at $5/1M tokens):

| Monthly API Calls | Avg Token Reduction | Monthly Savings |
|---|---|---|
| 10,000 | 59% | ~$7 |
| 100,000 | 59% | ~$74 |
| 1,000,000 | 59% | ~$740 |
| 10,000,000 | 59% | ~$7,400 |

*Assumes average 500 tokens/call on agent pipelines. Human chat apps will see lower savings.*

---

## For Local LLM Users (Low-End PCs)

If you run **agent pipelines** locally via Ollama or llama.cpp with models like Llama 3.2, Phi-3, or Mistral, Sanskrit-Mesh extends your effective context window on the structured parts of your conversation. A 4K context model running an AutoGen pipeline gets meaningfully more turns before hitting the limit.

This does **not** help if you're just doing casual chat — the savings only apply to agent-structured messages.

```python
import ollama
from middleware import SanskritMeshMiddleware

middleware = SanskritMeshMiddleware()

# Works well when messages contain agent/tool structured content
messages = [...]
compressed = middleware.compress_messages(messages)

response = ollama.chat(model="llama3.2", messages=compressed)
```

---

## Roadmap

- [x] Core compiler with 200+ IR dictionary entries
- [x] System prompt compression
- [x] LangChain callback integration
- [x] AutoGen hook integration
- [x] Universal OpenAI-format middleware
- [x] Live benchmark tool with cost reporting
- [ ] PyPI package release (`pip install sanskrit-mesh`)
- [ ] CrewAI integration
- [ ] Adaptive dictionary that learns from your own agent traffic
- [ ] Fine-tuned `Sanskrit-Mesh-3B` — a model that natively reads/writes IR (no decompilation needed)
- [ ] Human prompt compression via LLMLingua integration
- [ ] Ollama / llama.cpp plugin

---

## License

MIT — free forever. Stop paying OpenAI to read your agents' polite greetings.
