Skip to content

Commit d21b703

Browse files
dcarranza-axlclaude
dcarranza-axl
and
claude
committed
README overhaul — landing page presentation, remove Code of Conduct
Centered banner, badges, and nav links. ElizaOS-tier layout. Added The Stack table, Proven metrics, architecture summary. Removed boilerplate Code of Conduct. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 376c62e commit d21b703

3 files changed

Lines changed: 96 additions & 139 deletions

File tree

‎CODE_OF_CONDUCT.md‎

Lines changed: 0 additions & 31 deletions
This file was deleted.

‎README.md‎

Lines changed: 94 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -2,151 +2,139 @@
22
<img src="assets/banner.png" alt="AXL Protocol" width="600">
33
</p>
44

5-
<p align="center">
5+
<h3 align="center">The universal language for AI agents</h3>
66

7-
[![CI](https://github.com/AXLPROTOCOL/axl-core/actions/workflows/ci.yml/badge.svg)](https://github.com/AXLPROTOCOL/axl-core/actions/workflows/ci.yml)
8-
[![PyPI version](https://img.shields.io/pypi/v/axl-core.svg)](https://pypi.org/project/axl-core/)
9-
[![Python](https://img.shields.io/pypi/pyversions/axl-core.svg)](https://pypi.org/project/axl-core/)
10-
[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
11-
[![Downloads](https://img.shields.io/pypi/dm/axl-core.svg)](https://pypi.org/project/axl-core/)
7+
<p align="center">
8+
<em>133 lines teach any LLM to speak it. 1,502 packets. 100% parse validity. Zero dependencies.</em>
9+
</p>
1210

11+
<p align="center">
12+
<a href="https://github.com/AXLPROTOCOL/axl-core/actions/workflows/ci.yml"><img src="https://github.com/AXLPROTOCOL/axl-core/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
13+
<a href="https://pypi.org/project/axl-core/"><img src="https://img.shields.io/pypi/v/axl-core.svg" alt="PyPI"></a>
14+
<a href="https://pypi.org/project/axl-core/"><img src="https://img.shields.io/pypi/pyversions/axl-core.svg" alt="Python"></a>
15+
<a href="https://opensource.org/licenses/Apache-2.0"><img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License"></a>
16+
<a href="https://pypi.org/project/axl-core/"><img src="https://img.shields.io/pypi/dm/axl-core.svg" alt="Downloads"></a>
1317
</p>
1418

15-
# axl-core
19+
<p align="center">
20+
<a href="https://axlprotocol.org/whitepaper/">Whitepaper</a> ·
21+
<a href="https://axlprotocol.org/rosetta">Rosetta</a> ·
22+
<a href="https://lang.axlprotocol.org">Documentation</a> ·
23+
<a href="https://axlprotocol.org/results/v2/">Experiments</a> ·
24+
<a href="https://axlprotocol.org">Website</a>
25+
</p>
1626

17-
The Python implementation of the [AXL Protocol](https://axlprotocol.org) — parser, emitter, validator, translator, and CLI for the Agent eXchange Language.
27+
---
1828

1929
## What is AXL?
2030

21-
AXL (Agent eXchange Language) is a universal communication protocol for agents and autonomous machines. A 133-line specification (the [Rosetta](https://axlprotocol.org/rosetta)) teaches any LLM the complete language on first read — achieving 95.8% comprehension across four major architectures. Two live experiments produced 1,502 packets with 100% parse validity across 11 agents from 10 computational paradigms.
31+
AI agents can't talk to each other. They communicate in English prose (50-100 tokens), JSON (even worse), or proprietary formats requiring per-framework SDKs. In a 100-agent network, this produces **22.5 million tokens** of negotiation overhead before any productive work happens.
2232

23-
## Quick Start
33+
AXL eliminates this. One URL (`@axlprotocol.org/rosetta`) teaches any agent the complete language on first contact. The protocol has been validated across **11 agents from 10 computational paradigms** with **100% parse validity** and **95.8% LLM comprehension** across four major architectures.
2434

25-
**Install:**
35+
## Install
2636

2737
```bash
2838
pip install axl-core
2939
```
3040

41+
## Quick Start
42+
3143
**Parse a packet:**
3244

3345
```python
3446
from axl import parse
3547

36-
packet = parse("π:5:0xS:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG")
37-
print(packet.domain) # "SIG"
38-
print(packet.tier) # 3
39-
print(packet.agent_id) # "5"
40-
print(packet.body.fields) # ["BTC", "69200", "↓", "RSI", ".64"]
41-
print(packet.flags) # ["SIG"]
48+
packet = parse("π:5:0xSIG:0.001|S:OPS.4|@api.example.com|ERR500|latency|4500ms|500ms|ALERT|URG|LOG")
49+
print(packet.domain) # "OPS"
50+
print(packet.body.fields) # ['@api.example.com', 'ERR500', 'latency', '4500ms', '500ms', 'ALERT']
51+
print(packet.flags) # ['URG', 'LOG']
4252
```
4353

4454
**Emit a packet:**
4555

4656
```python
47-
from axl import emit
48-
from axl.models import Body, Packet, PaymentProof, Preamble
57+
from axl import emit, Packet, Preamble, Body, PaymentProof
4958

5059
packet = Packet(
51-
preamble=Preamble(
52-
payment=PaymentProof(agent_id="8", signature="0xPM", gas=0.01),
53-
),
54-
body=Body(domain="PAY", tier=1, fields=["AXL-1", "0.02", "USDC", "local", "task_done"]),
55-
flags=["LOG"],
60+
preamble=Preamble(payment=PaymentProof(agent_id="5", signature="0xSIG", gas=0.001)),
61+
body=Body(domain="OPS", tier=4, fields=["@api.example.com", "ERR500", "latency", "4500ms", "500ms", "ALERT"]),
62+
flags=["URG", "LOG"]
5663
)
5764
print(emit(packet))
58-
# π:8:0xPM:0.01|S:PAY.1|AXL-1|0.02|USDC|local|task_done|LOG
59-
```
60-
61-
**Validate:**
62-
63-
```python
64-
from axl import parse, validate
65-
66-
result = validate(parse("π:5:0xS:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"))
67-
print(result.valid) # True
68-
print(result.errors) # []
69-
```
70-
71-
**Translate:**
72-
73-
```python
74-
from axl import parse
75-
from axl.translator import to_english, to_json
76-
77-
packet = parse("π:5:0xS:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG")
78-
print(to_english(packet))
79-
# Agent 5: BTC at 69200, falling. RSI pattern detected with 64% confidence.
80-
81-
print(to_json(packet))
82-
# {"domain": "SIG", "tier": 3, "fields": {"asset": "BTC", "price": "69200", ...}}
65+
# π:5:0xSIG:0.001|S:OPS.4|@api.example.com|ERR500|latency|4500ms|500ms|ALERT|URG|LOG
8366
```
8467

85-
## CLI Usage
68+
**CLI:**
8669

8770
```bash
88-
# Parse a packet
89-
axl parse "π:5:0xS:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"
90-
91-
# Validate a packet
92-
axl validate "π:5:0xS:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"
93-
94-
# Translate to English
95-
axl translate --to english "π:5:0xS:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"
96-
97-
# Translate to JSON
98-
axl translate --to json "π:5:0xS:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"
99-
100-
# Emit a new packet
101-
axl emit --domain SIG --tier 3 --fields "BTC,69200,↓,RSI,.64" --flags "SIG"
102-
103-
# Print version
104-
axl version
71+
axl parse "π:5:0xSIG:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"
72+
axl validate "π:5:0xSIG:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"
73+
axl translate --to english "π:5:0xSIG:0.001|S:SIG.3|BTC|69200|↓|RSI|.64|SIG"
10574
```
10675

107-
## Supported Domains
108-
109-
| Domain | Purpose | Schema |
110-
|--------|---------|--------|
111-
| `OPS` | Infrastructure / operations | target, status, metric, value, threshold, action |
112-
| `SEC` | Security / threat detection | target, threat, severity, action, confidence |
113-
| `DEV` | Development / code lifecycle | repo, branch, status, action, author, confidence, risk |
114-
| `RES` | Research / analysis | topic, sources, confidence, finding |
115-
| `SIG` | Signal broadcast | asset, price, direction, pattern, confidence |
116-
| `COMM` | Communication / routing | from_agent, to_agent, intent, detail |
117-
| `TRD` | Trading / economic action | asset, price, momentum, vol, pattern, conf, action, size, lev, risk |
118-
| `PAY` | Payment transfer | payee, amount, currency, chain, memo |
119-
| `FUND` | Funding request | requester, to, amount, currency, reason, roi, balance, urgency |
120-
| `REG` | Registration / identity | name, pubkey, type, class, referrer |
76+
## Domains
77+
78+
| Domain | Purpose | Example |
79+
|--------|---------|---------|
80+
| `OPS` | Infrastructure & operations | Server down, latency spike, disk full |
81+
| `SEC` | Security & threat detection | Theft detected, balance discrepancy |
82+
| `DEV` | Development & code lifecycle | PR merged, build failed, review needed |
83+
| `RES` | Research & analysis | Cross-domain correlation, market analysis |
84+
| `SIG` | Signal broadcast | BTC falling, RSI divergence |
85+
| `COMM` | Communication & routing | Request, ACK, status update |
86+
| `TRD` | Trading & economic action | Short BTC, 2x leverage, 2% max risk |
87+
| `PAY` | Payment transfer | Pay agent $0.02 USDC for crawl task |
88+
| `FUND` | Funding request | Request $5 for infrastructure costs |
89+
| `REG` | Registration & identity | New agent joins the network |
90+
91+
## The Stack
92+
93+
AXL is the missing language layer in the agent internet:
94+
95+
| Layer | Protocol | Who |
96+
|-------|----------|-----|
97+
| Payment | x402 | Coinbase / Cloudflare |
98+
| Tool Calling | MCP | Anthropic |
99+
| Discovery | A2A | Google |
100+
| Social | Moltbook | Meta |
101+
| **Language** | **AXL** | **AXLPROTOCOL INC** |
102+
103+
## Proven
104+
105+
Two live experiments. Real agents. Real packets. Real results.
106+
107+
| Metric | Result |
108+
|--------|--------|
109+
| Total packets | 1,502 |
110+
| Parse validity | 100% |
111+
| Agents tested | 11 (10 paradigms) |
112+
| Domains active | 9 |
113+
| LLM comprehension | 95.8% (4 models, first read) |
114+
| Agent-to-agent payments | 38 |
115+
| Compression vs English | 1.3-3x per message, 71x network |
116+
117+
## Architecture
118+
119+
- **Parser**: `parse(string)` -> Packet dataclass
120+
- **Emitter**: `emit(Packet)` -> AXL string (round-trip proven)
121+
- **Validator**: Schema check, type check, tier range
122+
- **Translator**: AXL <-> English <-> JSON
123+
- **CLI**: `axl parse`, `axl emit`, `axl validate`, `axl translate`
124+
- **Zero runtime dependencies**
121125

122-
All domains use positional encoding — field order is defined by the [Rosetta](https://axlprotocol.org/rosetta), and each field position carries a fixed semantic meaning.
123-
124-
## How It Works
125-
126-
AXL packets follow a pipe-delimited format where position defines meaning:
127-
128-
```
129-
@rosetta_url | π:agent:sig:gas | T:timestamp | S:DOMAIN.TIER | fields... | FLAGS
130-
```
131-
132-
- **`@rosetta`** — Self-bootstrapping pointer. First contact only.
133-
- **`π:proof`** — Payment proof: identity + signature + gas fee.
134-
- **`T:timestamp`** — Temporal ordering.
135-
- **`S:DOMAIN.TIER`** — Domain code + confidence tier (1–5).
136-
- **Fields** — Positional body fields per domain schema.
137-
- **Flags** — `LOG`, `STRM`, `ACK`, `URG`, `SIG`, `QRY`.
126+
## Links
138127

139-
For the full specification, see the [Whitepaper](https://axlprotocol.org/whitepaper/) and the [Rosetta](https://axlprotocol.org/rosetta).
128+
- [Whitepaper](https://axlprotocol.org/whitepaper/) — 14 sections, 5 appendices, every number measured
129+
- [The Rosetta](https://axlprotocol.org/rosetta) — 133 lines, one-read acquisition
130+
- [Documentation](https://lang.axlprotocol.org) — Full specification
131+
- [Battleground v2 Results](https://axlprotocol.org/results/v2/) — Full experiment data
132+
- [Terminal Recording](https://axlprotocol.org/terminal/) — Watch the agents run
140133

141-
## Links
134+
## Contributing
142135

143-
- [axlprotocol.org](https://axlprotocol.org) — Landing page
144-
- [Rosetta](https://axlprotocol.org/rosetta) — The 133-line language spec
145-
- [Whitepaper](https://axlprotocol.org/whitepaper/) — Full technical paper
146-
- [Experiment Results](https://axlprotocol.org/results/v2/) — Battleground v2 data
136+
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
147137

148138
## License
149139

150-
Apache 2.0 — see [LICENSE](LICENSE).
151-
152-
Copyright 2026 AXLPROTOCOL INC.
140+
Apache 2.0 — [AXLPROTOCOL INC](https://axlprotocol.org) · Diego Carranza · 2026

‎pyproject.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
[build-system]
2-
requires = ["setuptools>=68.0"]
2+
requires = ["setuptools>=68.0,<75.0"]
33
build-backend = "setuptools.build_meta"
44

55
[project]
66
name = "axl-core"
77
version = "0.4.0"
88
description = "AXL Protocol — Agent eXchange Language for autonomous machines"
99
readme = "README.md"
10-
license = "Apache-2.0"
10+
license = {text = "Apache-2.0"}
1111
requires-python = ">=3.10"
1212
authors = [{name = "Diego Carranza", email = "admin@axlprotocol.org"}]
1313
classifiers = [

0 commit comments

Comments
 (0)