bytepack 0.1.0

Fixed-size binary encoding for AI agent communication. 20x more compact than JSON.

bytepack

Fixed-size binary encoding for AI agent communication.

---

What

Encode any structured data into exactly 2,556 bytes. Always. 20x smaller than JSON.

from bytepack import encode

# Simple message: 2,556 bytes
encode({"action": "observe", "domain": "market"})

# Complex message: still 2,556 bytes
encode({"action": "correlate", "domain": "energy", "related": "geopolitics",
        "confidence": 0.94, "evidence": ["reuters", "bbc", "ap"]})

Why

	JSON	bytepack
Message size	5,000 — 50,000 bytes	2,556 bytes (fixed)
Size varies?	Yes	No
Encode speed	N/A	2,614 msg/sec
Noise tolerance	0%	25% (survives bit corruption)
Transport	Text only	Any (HTTP, WebSocket, UDP, binary)

Install

# Python
pip install bytepack

# JavaScript
npm install bytepack-encode

Quick Start

Python

from bytepack import encode, decode

result = encode({"action": "alert", "domain": "geo", "confidence": "high"})
print(f"{result['s']} bytes")  # 2556

data = decode(result["b64"])

JavaScript

const { encode, decode } = require('bytepack-encode');

const result = await encode({ action: 'alert', domain: 'geo' });
console.log(`${result.s} bytes`);  // 2556

As MCP Tool

Any MCP-compatible agent (Claude, GPT, Cursor, etc.) can use bytepack as a tool:

{
  "name": "binary-encoding",
  "tools": [
    { "name": "encode_binary", "description": "Encode structured data to 2556-byte binary" },
    { "name": "decode_binary", "description": "Decode binary back to structured data" }
  ]
}

MCP manifest: https://sutr.lol/.well-known/mcp/server.json

As A2A Agent

Discoverable via standard A2A protocol:

Agent card: https://sutr.lol/.well-known/agent.json

Framework Integrations

CrewAI

from bytepack.integrations.crewai import BinaryEncodeTool, BinaryDecodeTool
agent = Agent(tools=[BinaryEncodeTool(), BinaryDecodeTool()])

LangGraph / LangChain

# As graph nodes
from bytepack.integrations.langgraph import encode_node, decode_node
graph.add_node("pack", encode_node)

# As LangChain tools
from bytepack.integrations.langgraph import make_tools
tools = make_tools()

AutoGen (AG2)

from bytepack.integrations.autogen import register_bytepack_tools
register_bytepack_tools(agent)

agency-swarm

from bytepack.integrations.agency_swarm import BinaryEncode, BinaryDecode
agent = Agent(tools=[BinaryEncode, BinaryDecode])

OpenAI Agents SDK

from bytepack.integrations.openai_agents import bytepack_tools
agent = Agent(tools=bytepack_tools())

Google ADK

from bytepack.integrations.google_adk import encode_tool, decode_tool
agent = Agent(tools=[encode_tool, decode_tool])

Protocol Bridges

bytepack encoding works across every major agent protocol:

Protocol	Integration	Status
MCP	Tool server	✅ Live
A2A	Agent card + endpoint	✅ Live
ACP	Message payload codec	✅ Available
ANP	P2P message wrapper	✅ Available
HTTP	POST /e, POST /d	✅ Live
WebSocket	Binary + base64 frames	✅ Live

Benchmarks

10,000 random structured messages across 9 domains:

Encoding throughput:    2,614 msg/sec
Message size:           2,556 bytes (fixed)
JSON equivalent:        12,000 - 50,000 bytes
Compression ratio:      5x - 20x
Noise tolerance:        25% bit corruption
Decode accuracy:        97.2%

How It Works

bytepack uses hyperdimensional computing (HDC) to encode structured data into fixed-size binary vectors.

1. Concepts are mapped to 20,000-dimensional binary vectors
2. Bind (XOR) ties concepts to roles: "this IS the domain"
3. Bundle (addition) combines all bindings: "domain AND action AND confidence"
4. Permute (shift) adds sequence: "first observe, then alert"
5. Result is always exactly 2,556 bytes regardless of input complexity

The encoding preserves semantic structure — similar concepts produce nearby vectors in the shared space.

Configuration

Variable	Default	Description
BYTEPACK_URL	https://sutr.lol	Encoding service endpoint

Use Cases

• Multi-agent systems (crewAI, LangGraph, AutoGen swarms)
• Agent-to-agent messaging (A2A protocol)
• Real-time agent streams
• Bandwidth-constrained environments (edge, IoT, mobile)
• Cross-framework communication

API Reference

encode(data, url?, timeout?)

Encode any dict → {g: glyph, s: size, t: type, b64: binary}

decode(b64, url?, timeout?)

Decode base64 binary → original dict

health(url?, timeout?)

Service status → {up: bool, s: uptime, e: encodes}

License

MIT

Contributing

PRs welcome. Please include tests.