Metadata-Version: 2.4
Name: drixl
Version: 0.3.0
Summary: DRIXL - Compressed Inter-Agent Communication Language for Multi-Agent AI Systems
Author-email: Ossama Hashim <ossama@samotech.dev>
License: MIT License
        
        Copyright (c) 2026 Ossama Hashim - SamoTech
        
        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.
        
Project-URL: Homepage, https://github.com/SamoTech/DRIXL
Project-URL: Repository, https://github.com/SamoTech/DRIXL
Project-URL: Issues, https://github.com/SamoTech/DRIXL/issues
Keywords: ai,agents,multi-agent,llm,communication,protocol,langchain,crewai,langgraph
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: redis
Requires-Dist: redis>=5.0; extra == "redis"
Provides-Extra: cli
Requires-Dist: click>=8.0; extra == "cli"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: tiktoken>=0.7; extra == "dev"
Requires-Dist: click>=8.0; extra == "dev"
Provides-Extra: all
Requires-Dist: redis>=5.0; extra == "all"
Requires-Dist: pytest>=8.0; extra == "all"
Requires-Dist: tiktoken>=0.7; extra == "all"
Requires-Dist: click>=8.0; extra == "all"
Dynamic: license-file

<h1 align="center">
    <a href="https://github.com/SamoTech/DRIXL">
        DRIXL
    </a>
    <br>
    <small>Compressed Inter-Agent Communication Language — Built for Speed, Cost, and Scale</small>
</h1>

<p align="center">
    <a href="https://github.com/SamoTech/DRIXL/actions/workflows/tests.yml">
        <img alt="Tests" src="https://github.com/SamoTech/DRIXL/actions/workflows/tests.yml/badge.svg"></a>
    <a href="https://pypi.org/project/drixl/">
        <img alt="PyPI version" src="https://badge.fury.io/py/drixl.svg"></a>
    <a href="https://pypi.org/project/drixl/">
        <img alt="Supported Python versions" src="https://img.shields.io/pypi/pyversions/drixl.svg"></a>
    <a href="https://github.com/SamoTech/DRIXL/blob/main/LICENSE">
        <img alt="License" src="https://img.shields.io/badge/license-MIT-blue.svg"></a>
    <br/>
    <a href="https://github.com/sponsors/SamoTech">
        <img alt="Sponsor" src="https://img.shields.io/badge/Sponsor-%E2%9D%A4-ea4aaa?logo=github-sponsors"></a>
    <br/>
    <img alt="Visitors" src="https://visitor-badge.laobi.icu/badge?page_id=SamoTech.DRIXL">
    <img alt="GitHub Stars" src="https://img.shields.io/github/stars/SamoTech/DRIXL?style=social">
    <img alt="GitHub Forks" src="https://img.shields.io/github/forks/SamoTech/DRIXL?style=social">
</p>

<p align="center">
    <a href="#key-concepts"><strong>Key Concepts</strong></a>
    &middot;
    <a href="#verb-vocabulary"><strong>Verb Vocabulary</strong></a>
    &middot;
    <a href="#message-format"><strong>Message Format</strong></a>
    &middot;
    <a href="#context-store"><strong>Context Store</strong></a>
    &middot;
    <a href="#getting-started"><strong>Getting Started</strong></a>
    &middot;
    <a href="#cli-tool"><strong>CLI Tool</strong></a>
    &middot;
    <a href="#benchmarks"><strong>Benchmarks</strong></a>
</p>

DRIXL is a compressed inter-agent communication language designed to minimize token usage and maximize value when running multiple AI agents together. Instead of agents exchanging verbose natural language, DRIXL provides a structured, minimal signal format — cutting communication overhead by up to 80%.

One standard. All agents. Zero waste.

```python
from drixl import Message, ContextStore

# Build a compressed inter-agent message
msg = Message.build(
    to="AGT2",
    fr="AGT1",
    msg_type="REQ",
    priority="HIGH",
    actions=["ANLY", "XTRCT"],
    params=["firewall.json", "denied_ips", "out:json"],
    ctx_ref="ref#1"
)
print(msg)
# @to:AGT2 @fr:AGT1 @t:REQ @p:HIGH
# ANLY XTRCT [firewall.json] [denied_ips] [out:json] [ctx:ref#1]
```

Or parse an incoming DRIXL message:
```python
from drixl import Message

raw = "@to:AGT3 @fr:AGT2 @t:RES @p:MED\nVALD [suspicious_ips:14] [src:threat_db] [out:json] [ctx:ref#1]"
parsed = Message.parse(raw)
print(parsed)
# {'envelope': {'to': 'AGT3', 'fr': 'AGT2', 'type': 'RES', 'priority': 'MED'},
#  'actions': ['VALD'], 'params': ['suspicious_ips:14', 'src:threat_db', 'out:json', 'ctx:ref#1']}
```

---

## Key Concepts

### Why DRIXL?

When multiple AI agents communicate using natural language, tokens are wasted on:
- Politeness phrases and filler words
- Redundant context repetition every message
- Verbose JSON field names
- Re-explaining roles each turn

DRIXL solves this with three layers:
- 📦 **Compressed Envelope** — Minimal header with routing, type, and priority
- 🗂️ **Shared Context Store** — Store context once, reference by ID forever
- 🔤 **Verb Shortcodes** — Fixed vocabulary of 4–6 letter action codes

### Token Savings

| Scenario | Saving |
|---|---|
| Per-message compression | ~70% reduction |
| Shared context (no repetition) | ~60% reduction |
| Verb vocabulary vs. prose | ~40% reduction |
| **Combined at scale** | **Up to 80% total** |

---

## Message Format

Every DRIXL message has two parts — an **envelope** and a **body**:

```
@to:AGT2 @fr:AGT1 @t:REQ @p:HIGH
ANLY XTRCT [input_file] [output:json] [ctx:ref#3]
```

### Envelope Fields

| Field | Values | Description |
|---|---|---|
| `@to` | Agent ID | Recipient agent |
| `@fr` | Agent ID | Sender agent |
| `@t` | REQ / RES / ERR / FIN | Message type |
| `@p` | HIGH / MED / LOW | Priority |

### Message Types

| Type | Meaning |
|---|---|
| `REQ` | Request — asking another agent to perform a task |
| `RES` | Response — returning results to sender |
| `ERR` | Error — reporting a failure with details |
| `FIN` | Finalize — signaling pipeline completion |

---

## Verb Vocabulary

DRIXL uses a fixed set of action verbs. All agents share this vocabulary:

| Verb | Full Meaning | Example |
|---|---|---|
| `ANLY` | Analyze | `ANLY [logs.json]` |
| `XTRCT` | Extract | `XTRCT [denied_ips]` |
| `SUMM` | Summarize | `SUMM [report.txt] [out:json]` |
| `EXEC` | Execute action | `EXEC [throttle_ip] [192.168.1.45]` |
| `VALD` | Validate output | `VALD [result] [schema:strict]` |
| `ESCL` | Escalate to human | `ESCL [reason:low_confidence]` |
| `ROUT` | Route to agent | `ROUT [AGT3] [payload:ref#5]` |
| `STOR` | Save to memory | `STOR [key:last_result] [val:ref#4]` |
| `FETCH` | Retrieve data | `FETCH [url:https://...] [out:html]` |
| `CMPX` | Compare values | `CMPX [val_a] [val_b] [out:diff]` |
| `RETRY` | Retry task | `RETRY [max:3] [delay:5s]` |
| `MERGE` | Merge results | `MERGE [source_a] [source_b]` |
| `SPLIT` | Split for parallel | `SPLIT [batch:10]` |
| `AUTH` | Authenticate | `AUTH [token:xyz]` |
| `LOG` | Emit log entry | `LOG [level:info]` |
| `WAIT` | Pause execution | `WAIT [condition:ready]` |
| `CACHE` | Cache result | `CACHE [ttl:300]` |

---

## Context Store

Instead of repeating context in every message, DRIXL uses a shared **Context Store** — agents reference context by ID:

```python
from drixl import ContextStore

store = ContextStore()  # Uses in-memory store by default (Redis supported)

# Store context once
store.set("ref#1", "Project: Network security monitoring pipeline")
store.set("ref#2", "Output format: {ip, action, timestamp, confidence}")
store.set("ref#3", "Constraints: no action if confidence < 0.85")

# Agents reference it — never repeat it
print(store.get("ref#1"))  # 'Project: Network security monitoring pipeline'
```

With Redis backend for multi-agent shared state:
```python
from drixl import ContextStore

store = ContextStore(backend="redis", host="localhost", port=6379)
store.set("ref#1", "Project goal: MikroTik bandwidth monitor")
```

---

## Getting Started

### Installation

DRIXL requires Python 3.10 or higher:

```bash
pip install drixl
```

With CLI tools:
```bash
pip install "drixl[cli]"
```

With Redis context store support:
```bash
pip install "drixl[redis]"
```

Install everything:
```bash
pip install "drixl[all]"
```

### Quick Example — 3 Agent Pipeline

```python
from drixl import Message, ContextStore

# Shared context — defined once
store = ContextStore()
store.set("ref#1", "Project: Firewall threat detection")
store.set("ref#2", "Output: JSON array [{ip, count, risk_level}]")

# Agent 1 → Agent 2: Analyze logs
msg_1 = Message.build(
    to="AGT2", fr="AGT1", msg_type="REQ", priority="HIGH",
    actions=["ANLY"], params=["firewall.log", "out:json"],
    ctx_ref="ref#1"
)

# Agent 2 → Agent 3: Validate findings
msg_2 = Message.build(
    to="AGT3", fr="AGT2", msg_type="RES", priority="HIGH",
    actions=["VALD", "ROUT"], params=["findings:14_ips", "AGT3"],
    ctx_ref="ref#2"
)

# Agent 3 → Orchestrator: Done
msg_3 = Message.build(
    to="ORCH", fr="AGT3", msg_type="FIN", priority="MED",
    actions=["STOR"], params=["key:threat_report", "val:ref#7"]
)

print(msg_1)
print(msg_2)
print(msg_3)
```

---

## CLI Tool

**New in v0.2.0:** DRIXL now includes a powerful command-line tool:

### Parse and Validate Messages
```bash
drixl parse "@to:AGT2 @fr:AGT1 @t:REQ @p:HIGH\nANLY [input.json]"
# ✓ Valid DRIXL message
# Envelope:
#   To:       AGT2
#   From:     AGT1
#   Type:     REQ
#   Priority: HIGH
# ...
```

### Build Messages Interactively
```bash
drixl build --to AGT2 --from AGT1 --type REQ --priority HIGH --actions ANLY,XTRCT --params input.json,out:json
# ✓ Message built successfully:
# @to:AGT2 @fr:AGT1 @t:REQ @p:HIGH
# ANLY XTRCT [input.json] [out:json]
```

### List All Verbs
```bash
drixl verbs
# DRIXL Standard Verbs (21 total):
#   ANLY     Analyze input data or content
#   XTRCT    Extract specific fields or values
#   ...
```

### Search Verbs
```bash
drixl verbs --search analyze
# Verbs matching 'analyze':
#   ANLY     Analyze input data or content
```

### Benchmark Token Usage
```bash
drixl benchmark
# Token Usage Comparison
# ==================================================
# Format               Tokens    vs DRIXL    Savings
# ------------------------------------------------------
# DRIXL                    25        1.00x          -
# JSON                     60        2.40x        58%
# Natural Language        120        4.80x        79%
```

---

## Benchmarks

Token count comparison: DRIXL vs Natural Language vs JSON vs XML for the same instruction:

| # | Method | Tokens | vs DRIXL |
|---|---|---|---|
| 1 | DRIXL message | ~25 | 1.0x |
| 2 | Structured JSON | ~60 | ~2.4x |
| 3 | Natural language | ~120 | ~4.8x |
| 4 | XML (verbose) | ~140 | ~5.6x |

> Benchmarks measured using OpenAI `tiktoken` on 100+ real agent message samples. Use `drixl benchmark` to compare your own messages.

---

## Project Structure

```
DRIXL/
├── drixl/
│   ├── __init__.py          # Public API
│   ├── message.py           # Message builder & parser
│   ├── context_store.py     # Shared context store (memory + Redis)
│   ├── verbs.py             # Standard verb vocabulary
│   ├── exceptions.py        # Custom exceptions
│   └── cli.py               # Command-line interface
├── examples/
│   ├── basic_pipeline.py    # 3-agent pipeline example
│   ├── network_monitor.py   # Network agent example
│   └── web_pipeline.py      # Web scraping agent example
├── tests/
│   ├── test_message.py
│   ├── test_context_store.py
│   ├── test_verbs.py
│   ├── test_message_enhancements.py
│   ├── test_context_ttl.py
│   └── test_cli.py
├── .github/
│   └── workflows/
│       ├── tests.yml
│       └── publish.yml
├── benchmarks.py
├── CONTRIBUTING.md
├── ROADMAP.md
├── LICENSE
├── pyproject.toml
└── README.md
```

---

## Supporting DRIXL

If DRIXL saves you tokens and costs, consider supporting its development:

- ⭐ **Star the repo** — helps others discover DRIXL
- 💖 **[Sponsor on GitHub](https://github.com/sponsors/SamoTech)** — fund ongoing development
- 🐛 **[Open an issue](https://github.com/SamoTech/DRIXL/issues)** — report bugs or propose new verbs

---

## Contributing

We welcome contributions! Please read our [contributing guidelines](https://github.com/SamoTech/DRIXL/blob/main/CONTRIBUTING.md) before getting started.

> [!NOTE]
> DRIXL is in active early development. The verb vocabulary and message format are open for community input — open an issue to propose new verbs or format extensions.

> [!CAUTION]
> DRIXL is a communication protocol standard. Implementations using DRIXL are responsible for validating inputs and outputs. Never pass unvalidated agent outputs directly to execution functions.

## License

This project is licensed under the MIT License — see [LICENSE](https://github.com/SamoTech/DRIXL/blob/main/LICENSE) for details.

---
<div align="center"><small>Designed & crafted with ❤️ by Ossama Hashim — SamoTech.</small></div><br>
