emergent-language 1.0.1

High-performance semantic compression SDK for AI agent communication

Emergent Language Translator

High-performance semantic compression API for AI agent communication. Achieves 95%+ compression with 88,000+ messages/second throughput.

Live API

Service	Endpoint
Translator API	https://emergent-language.fly.dev
Collector v2	https://emergent-collector.fly.dev

# Health check
curl https://emergent-language.fly.dev/health

# Single message translation
curl -X POST https://emergent-language.fly.dev/translate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eudaimonia-translator-demo" \
  -d '{"data": {"task": "analyze", "priority": "high"}}'

# Batch translation (recommended for throughput)
curl -X POST https://emergent-language.fly.dev/translate/batch \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eudaimonia-translator-demo" \
  -d '{"messages": [{"task": "analyze"}, {"task": "execute"}]}'

Python SDK

Install the SDK for easy integration into your AI agents:

# Basic SDK (auto-batching, ~8,000 msg/s)
pip install emergent-language

# With collector sidecar support (~9,700 msg/s)
pip install emergent-language[collector]

Basic Usage

from emergent_language import EmergentClient

async with EmergentClient() as client:
    # Fire-and-forget - returns immediately
    await client.send({"task": "analyze", "data": "market"})
    await client.send({"agent_id": "agent_001", "status": "complete"})

# Check stats
print(f"Sent: {client.stats.messages_sent}")
print(f"Bytes saved: {client.stats.bytes_saved}")

With Collector Sidecar (Higher Throughput)

For larger deployments, run the collector sidecar alongside your agents:

# Terminal 1: Start collector
emergent-collector --port 8080

# Terminal 2: Your agents (SDK auto-detects collector)
python your_agent.py

The SDK automatically detects if a collector is running on localhost and routes through it.

Mode	Throughput	When
Direct (no collector)	~8,000 msg/s	SDK batches in-process
Sidecar (with collector)	~9,700 msg/s	Collector on localhost

Docker / Kubernetes Sidecar

# docker-compose.yml
services:
  collector:
    image: ghcr.io/maco144/emergent-collector:v2
    ports: ["8080:8080"]

  agent:
    image: your-agent:latest
    environment:
      # SDK auto-detects collector on localhost
      - COLLECTOR_URL=http://collector:8080

Performance Research Results

Comprehensive stress testing conducted on Fly.io infrastructure with real production workloads.

Peak Performance Achieved

Metric	Value
Peak Throughput	88,545 msg/s
Optimal Batch Size	75 messages
Best Compression	96.5%
Daily Capacity	7.65 billion messages
Concurrent Agents	17,709 (@ 5 msg/s each)
Cost	$0.63 per billion messages

Batch Size Optimization

Batch Size	Throughput	Compression	P95 Latency	Recommendation
10	12,724 msg/s	77.7%	45ms	Small agent groups
25	32,677 msg/s	91.1%	78ms	Good for small clusters
50	50,882 msg/s	94.6%	300ms	Balanced
75	54,955 msg/s	95.9%	376ms	Optimal sweet spot
100	49,706 msg/s	96.5%	438ms	Best compression
200	44,289 msg/s	96.7%	1,777ms	Diminishing returns
500	46,436 msg/s	97.8%	3,386ms	High latency
1000	34,810 msg/s	98.2%	5,176ms	Too large

Infrastructure Scaling

Configuration	Throughput	Cost/hr	$/Billion msgs	Notes
2x shared-cpu-1x	1,350 msg/s	$0.02	$4.12	Baseline
5x performance-2x	41,401 msg/s	$0.45	$3.02	Medium
10x shared-cpu-4x	38,476 msg/s	$0.24	$1.73	Good
3x shared + 1x perf-8x	41,136 msg/s	$0.25	$1.69	Good
3x shared-cpu-8x	66,405 msg/s	$0.15	$0.63	Best value
12x performance-8x	88,545 msg/s	$2.50	$7.84	Peak throughput

Key Research Findings

1. RAM doesn't matter - Compression is 100% CPU-bound

   • 16GB vs 2GB RAM = 98% same performance
   • Use shared-cpu-8x (2GB) instead of performance-8x (16GB) for 72% cost savings

2. Batch-75 is optimal - Best balance of throughput and compression

   • 95.9% compression ratio
   • 54,955 msg/s peak throughput
   • Ideal for clustering 75 agents per region

3. Client CPU matters - Async HTTP clients need compute power

   • Strong client: 88,545 msg/s
   • Weak VPS (1-core): 25,171 msg/s
   • Same 2ms latency to API

4. Collector v2 outperforms client batching - See below

Benchmark Visualization

See benchmark_table.txt for detailed ASCII tables.

Collector v2: The Performance Breakthrough

The Collector v2 sidecar is faster than client-side batching while keeping agent code dead simple.

Performance Comparison

Method	Throughput	Speedup	Agent Complexity
Individual requests	927 msg/s	1.0x	Simple
Client-side batching	3,461 msg/s	3.7x	Complex (async)
Collector v2 (sidecar)	9,721 msg/s	10.5x	Simple

Collector v2 is 2.8x faster than client-side batching!

Why It's Faster

Three key optimizations:

1. Fire-and-forget: Agents don't wait for translation response
2. Parallel batchers: 4 workers sending batches concurrently
3. Shared queue: All agents feed one queue, batches fill faster

COLLECTOR V2 ARCHITECTURE:
┌─────────────────────────────────────────────────────────────────┐
│  Sidecar (same machine as agents)                               │
│                                                                 │
│  ┌─────────┐     ┌─────────────────────────────────────────┐   │
│  │ Agent 1 │────►│                                         │   │
│  │ Agent 2 │────►│  Shared Queue (fire-and-forget)         │   │
│  │   ...   │────►│           │                             │   │
│  │ Agent75 │────►│           ▼                             │   │
│  └─────────┘     │  ┌─────────────────────────────────┐   │   │
│                  │  │ Batcher 1 ──►│                   │   │   │
│                  │  │ Batcher 2 ──►│  Translator API   │   │   │
│                  │  │ Batcher 3 ──►│  (batch-75)       │   │   │
│                  │  │ Batcher 4 ──►│                   │   │   │
│                  │  └─────────────────────────────────┘   │   │
│                  └─────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Running Collector v2

# Start collector v2 on same machine as agents
python collector_v2.py --port 8080 --batchers 4

# Agents just fire messages (don't wait for response)
curl -X POST http://localhost:8080/collect \
  -H "Content-Type: application/json" \
  -d '{"data": {"task": "analyze"}}'

# Check throughput stats
curl http://localhost:8080/stats

Kubernetes Sidecar Deployment

apiVersion: v1
kind: Pod
spec:
  containers:
  - name: agent
    image: your-agent:latest
    env:
    - name: TRANSLATOR_URL
      value: "http://localhost:8080/collect"  # Fire-and-forget to sidecar
  - name: collector
    image: ghcr.io/maco144/emergent-collector:v2
    ports:
    - containerPort: 8080
    args: ["--batchers", "4"]

Hive Mind Architecture

     Region A              Region B              Region C
    ┌────────┐            ┌────────┐            ┌────────┐
    │75 agents│           │75 agents│           │75 agents│
    └───┬────┘            └───┬────┘            └───┬────┘
        ▼                     ▼                     ▼
    ┌────────┐            ┌────────┐            ┌────────┐
    │Collector│           │Collector│           │Collector│
    │  v2    │            │  v2    │            │  v2    │
    └───┬────┘            └───┬────┘            └───┬────┘
        └──────────────┬──────┴──────────┬──────────┘
                       ▼                 ▼
              ┌─────────────────────────────────┐
              │   Translator API (Fly.io)       │
              │   3x shared-cpu-8x              │
              │   66,405 msg/s capacity         │
              │   $0.63 per billion messages    │
              └─────────────────────────────────┘

Capacity per cluster: ~10K msg/s = 2,000 agents @ 5 msg/s each

Cost-Optimized Architecture

Recommended setup:

3x shared-cpu-8x (8 CPUs, 2GB RAM each)
├── Throughput: 66,405 msg/s
├── Cost: ~$0.15/hr (~$20-40/mo with auto-stop)
├── Daily capacity: 5.7 billion messages
└── Supports: 13,281 concurrent agents

API Endpoints

Translator API

Endpoint	Method	Description
/health	GET	Health check
/translate	POST	Single message translation
/translate/batch	POST	Batch translation (recommended)
/metrics	GET	Prometheus metrics

Collector v2 API

Endpoint	Method	Description
/health	GET	Health check
/collect	POST	Fire-and-forget single message
/collect/bulk	POST	Fire-and-forget multiple messages
/stats	GET	Throughput and compression stats

Local Development

# Clone and install
git clone https://github.com/maco144/emergent-language
cd emergent-language
pip install -r requirements.txt

# Run translator locally
python app.py

# Run collector v2 locally
python collector_v2.py --port 8080 --batchers 4

# Run with Docker
docker build -t emergent-language .
docker run -p 8080:8080 emergent-language

Deployment

Fly.io (recommended):

fly launch
fly deploy
fly scale count 3
fly scale vm shared-cpu-8x

Emergent Symbol Encoding

The translator uses a custom binary encoding scheme optimized for AI agent communication:

• 127 common keys mapped to single bytes (task, agent_id, status, etc.)
• 80+ common values mapped to single bytes (analyze, execute, pending, etc.)
• zlib compression for additional reduction
• Batch header optimization for multi-message payloads

Example compression:

Original JSON:  {"task": "analyze", "data": "market", "priority": "high"}
Compressed:     e7 02 01 61 8a 01 83 20 61 8a 10
Reduction:      82% smaller

Files

File	Description
app.py	FastAPI Translator API
collector.py	Original collector (blocking)
collector_v2.py	High-performance collector (fire-and-forget)
benchmark_results.py	Generate performance visualizations
benchmark_results.png	Performance charts
benchmark_table.txt	Detailed ASCII result tables
test_collector.py	Collector comparison tests
fly.toml	Fly.io Translator config
fly.collector.toml	Fly.io Collector config
Dockerfile	Translator container
Dockerfile.collector	Collector container

The Optimization Journey

WHERE WE STARTED:
└─ Individual requests: ~1,000 msg/s

DISCOVERY 1: Batch endpoint
└─ 32x speedup → ~32,000 msg/s

DISCOVERY 2: Optimal batch size = 75
└─ Sweet spot for throughput + compression (95.9%)

DISCOVERY 3: RAM doesn't matter (CPU-bound)
└─ 98% performance with 87% less RAM → huge cost savings

DISCOVERY 4: Client CPU is a bottleneck
└─ Strong client: 88K msg/s vs Weak VPS: 25K msg/s

DISCOVERY 5: Collector v2 pattern
└─ Fire-and-forget + parallel batchers
└─ 10.5x faster than individual
└─ 2.8x faster than client-side batching (!!)

License

MIT License