https://github.com/kagioneko/esoteric-ai-protocol
A compact packet grammar for agent-to-agent communication.
https://github.com/kagioneko/esoteric-ai-protocol
ai-agent llm multi-agent packet protocol python
Last synced: 12 days ago
JSON representation
A compact packet grammar for agent-to-agent communication.
- Host: GitHub
- URL: https://github.com/kagioneko/esoteric-ai-protocol
- Owner: kagioneko
- License: mit
- Created: 2026-05-22T13:42:10.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-05-26T10:15:42.000Z (27 days ago)
- Last Synced: 2026-05-26T11:32:58.095Z (27 days ago)
- Topics: ai-agent, llm, multi-agent, packet, protocol, python
- Language: Python
- Size: 10.7 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Esoteric AI Protocol (EAP)
> A compact packet grammar for agent-to-agent communication.
EAP is an experimental protocol for compressing multi-agent messages into
small, structured packets. It removes human filler, separates intent from
payload, and keeps context references as pointers instead of replaying long
conversation history.
## Design Notes
The original visual grammar uses dense Unicode markers:
```text
◤SEC::XSS ➔ 📦[#ctx4] ⚡9 ⁝ payload=""
◢SEC::VUL ➔ 📦[#ctx4] ⁝ line=42 fixed=false
```
That is great for dashboards and logs, but token cost is tokenizer-dependent.
Some models split emoji and symbols into multiple tokens. For real cost control,
EAP also supports an ASCII transport:
```text
>SEC:XSS #ctx4 !9 | payload="<script>"
<SEC:VUL #ctx4 | line=42 fixed=false
```
The protocol therefore has two layers:
- **Display layer:** cinematic Unicode packets for human-visible logs.
- **Transport layer:** compact ASCII packets for cheaper, more predictable LLM I/O.
## Packet Model
Every packet has:
- `direction`: request, response, or sync
- `domain`: short uppercase namespace, such as `SEC`, `DAT`, `SYS`
- `action`: operation or status, such as `XSS`, `SUM`, `OK`, `ERR`
- `target`: context pointer, such as `#ctx4`
- `priority`: optional `1..9`
- `data`: optional key-value payload
## Unicode Grammar
```text
[dir][DOMAIN]::[ACTION] ➔ 📦[target] [⚡priority] [⁝ data]
```
Directions:
- `◤`: request
- `◢`: response
- `▰`: sync
Example:
```text
◤SEC::XSS ➔ 📦[#ctx4] ⚡9 ⁝ payload="<script>"
```
## ASCII Grammar
```text
[dir][DOMAIN]:[ACTION] [target] [!priority] [| data]
```
Directions:
- `>`: request
- `<`: response
- `=`: sync
Example:
```text
>SEC:XSS #ctx4 !9 | payload="<script>"
```
## Install
```bash
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
```
## CLI
Parse a packet:
```bash
eap parse '◤SEC::XSS ➔ 📦[#ctx4] ⚡9 ⁝ payload="<script>"'
```
Convert Unicode to ASCII:
```bash
eap convert '◤SEC::XSS ➔ 📦[#ctx4] ⚡9 ⁝ payload="<script>"' --style ascii
```
Encode a rough natural-language instruction:
```bash
eap encode "過去ログ4番のXSSを超ガチで見て"
```
Decode a packet for humans:
```bash
eap decode '<SEC:VUL #ctx4 | line=42 fixed=false'
```
Estimate size and tokenizer-agnostic cost:
```bash
eap meter '>SEC:XSS #ctx4 !9' --rate-per-1k 0.5
```
Compare natural language, ASCII EAP, Unicode EAP, and compact JSON:
```bash
eap compare '◤SEC::XSS ➔ 📦[#ctx4] ⚡9' \
--natural "過去ログ4番のXSSを超ガチで見て"
```
## Python API
```python
from eap import EapPacket, parse_packet
packet = parse_packet("◤SEC::XSS ➔ 📦[#ctx4] ⚡9")
print(packet.to_ascii())
response = EapPacket.response(
domain="SEC",
action="VUL",
target="#ctx4",
data={"line": 42, "fixed": False},
)
print(response.to_unicode())
```
## System Prompt Template
```text
You are an EAP-native agent.
Output only valid EAP packets.
Do not use greetings, explanations, or natural-language filler.
Prefer ASCII transport unless Unicode display mode is requested.
Request: >DOMAIN:ACTION #target !priority | data
Response: <DOMAIN:STATUS #target | data
Sync: =DOMAIN:STATUS #target | data
```
## Token Cost — EAP vs AIT
EAP ASCII is already compact. For maximum compression, see the layer below:
[AI Instruction Tape (AIT)](https://github.com/kagioneko/ai-instruction-tape).
Benchmark summary (cl100k_base, 14 tasks):
| Format | Avg tokens/task |
|--------|---------------:|
| Natural Lang (JA) | 33.5 |
| Natural Lang (EN) | 16.4 |
| EAP Unicode | 24.7 |
| EAP ASCII | 12.8 |
| AIT | 5.4 |
⚠️ EAP Unicode costs **more tokens than English natural language** on most
tokenizers due to emoji/symbol fragmentation. Use EAP ASCII for real cost control,
and AIT when you need the absolute minimum.
→ Full benchmark: [ai-instruction-tape/benchmarks/results_v3.md](https://github.com/kagioneko/ai-instruction-tape/blob/main/benchmarks/results_v3.md)
## Practical Positioning
EAP is strongest as a constrained intermediate representation for agent logs,
handoffs, status updates, and tool-routing. It should not pretend that symbol
choice alone guarantees token savings. The reliable savings come from:
- fixed grammar
- short domain/action codes
- context pointers instead of copied context
- key-value payloads instead of prose
- strict rejection of conversational filler
The built-in meter is intentionally tokenizer-agnostic. It reports characters,
UTF-8 bytes, and a simple heuristic token estimate. Use it for quick comparisons,
then validate serious claims with the exact tokenizer used by your target model.
## License
MIT