pairl (Python)

Reference implementation of PAIRL — a compact, human-readable, machine-parseable message format for agent-to-agent communication. This package parses PAIRL, validates it (rules V1–V12), canonicalizes and SHA-256–hashes it, and renders it back to human-readable text. Pure standard library, no runtime dependencies.

PAIRL v1.6

This release tracks spec v1.6 in lockstep. v1.6 adds no new grammar — the extractive-quote and marked-condensate carriage forms for #req/#rpt live inside ordinary quoted strings and kvpairs, so this parser handles v1.6 bodies unchanged (two v1.6 cases are part of the conformance corpus). The new rules V13–V15 are delivery-/encoder-side and out of message-parser scope by design (SPEC §12a, §3.1/V15).

Why PAIRL?

Agents exchanging context in natural language burn tokens and let facts drift; raw JSON is rigid and verbose. PAIRL separates a lossy intent channel (tone, length, speech act) from a lossless fact channel (names, numbers, evidence) and references large content instead of copying it.

Protocol architecture

A PAIRL message is a header block (@v, @id, @ts, threading, budget, …) followed by a blank line and body records:

• Intents — req{t=topic,s=f,l=2} — the lossy channel: speech act + style.
• Lossless records — #fact, #ref, #evid, #rule — exact data, treated as ground truth (never paraphrased).
• Economic records — #cost, #quota — native budget/usage tracking.
• Tool records — #call, #ret, #think, #edit — compact tool-use chains.
• Turn markers (v1.3) — #u1/#a2 — attribute records to a speaker when a whole conversation is compressed into one body.
• Columnar blocks (v1.5) — #evid[claim,src,conf] + positional rows — declare a repeated key schema once instead of per record (~40% fewer tokens, lossless).

Canonicalization & hashing (§9). Columnar blocks expand to #type key=value records before hashing, so a message produces the same SHA-256 whether sent in columnar or key=value form — enabling content-addressing, dedup, and caching.

Install

pip install pairl

Library

import pairl

msg = pairl.parse(open("message.pairl").read())

res = pairl.validate(msg)            # rules V1–V12
print(res.valid, res.errors, res.warnings)

print(pairl.compute_hash(msg))       # canonical SHA-256 (columnar-invariant)
print(pairl.render(msg))             # faithful human-readable rendering

CLI

python -m pairl validate [--strict] message.pairl   # exit 0 ok / 1 invalid
python -m pairl render   message.pairl
python -m pairl hash     message.pairl
python -m pairl canon    message.pairl

Test

cd impl/python && python -m unittest discover -s tests

Links

• Specification: https://github.com/dwehrmann/PAIRL/blob/main/SPEC.md
• Repository & other implementations (TypeScript, Rust) + shared conformance corpus: https://github.com/dwehrmann/PAIRL/tree/main/impl
• Website: https://pairl.dev

Licensed under Apache-2.0.