Python Library (axl-core)

Full API reference for the axl-core Python package. Zero dependencies. Python 3.10+.

Installation

pip install axl-core

Modules

axl.parser

Parses raw AXL strings into structured Packet objects.

from axl.parser import parse

packet = parse("S:OPS.3|cpu_high|node-7|threshold=90|!ALERT|!ROUTE")

parse(raw: str) -> Packet

Parameter	Type	Description
raw	str	Raw AXL packet string to parse.

Returns: A fully populated Packet instance.

Raises: AXLParseError if the packet is malformed.

from axl.parser import parse

pkt = parse("@ipfs://Qm.../rosetta.axl|T:1711234567|S:SIG.2|breach|zone-3|!ALERT")
print(pkt.preamble.rosetta)   # "ipfs://Qm.../rosetta.axl"
print(pkt.preamble.timestamp) # 1711234567
print(pkt.header.domain)      # "SIG"
print(pkt.header.tier)        # 2
print(pkt.fields)             # ["breach", "zone-3"]
print(pkt.flags)              # ["ALERT"]

---

axl.emitter

Constructs AXL packet strings from structured parameters.

from axl.emitter import emit

emit(domain: str, tier: int, fields: list[str], flags: list[str] = None, timestamp: bool = False, nonce: bool = False, rosetta: str = None, payment: PaymentProof = None) -> str

Parameter	Type	Default	Description
domain	str	-	Domain code (e.g., "OPS", "SIG")
tier	int	-	Priority tier (1-5)
fields	list[str]	-	Data fields
flags	list[str]	None	Signal flags (e.g., "ALERT")
timestamp	bool	False	Attach Unix timestamp
nonce	bool	False	Attach monotonic nonce
rosetta	str	None	Rosetta file URI
payment	PaymentProof	None	On-chain payment proof

Returns: A valid AXL packet string.

from axl.emitter import emit

pkt = emit(
    domain="PAY",
    tier=2,
    fields=["invoice_settled", "amount=250", "currency=USDC"],
    flags=["ACK", "LOG"],
    timestamp=True,
)
print(pkt)
# T:1711234567|S:PAY.2|invoice_settled|amount=250|currency=USDC|!ACK|!LOG

---

axl.validator

Validates AXL packet strings for syntactic and semantic correctness.

from axl.validator import validate

validate(raw: str, strict: bool = False) -> ValidationResult

Parameter	Type	Default	Description
raw	str	-	Raw AXL packet string to validate.
strict	bool	False	Enable strict mode (rejects unknown flags)

Returns: A ValidationResult instance.

from axl.validator import validate

result = validate("S:OPS.3|cpu_high|node-7|!ALERT")
print(result.valid)      # True
print(result.errors)     # []
print(result.warnings)   # []
print(result.tier)       # 3
print(result.domain)     # "OPS"

result = validate("S:INVALID.99|bad")
print(result.valid)      # False
print(result.errors)     # ["Unknown domain: INVALID", "Tier out of range: 99"]

---

axl.translator

Converts between AXL, English, and JSON representations.

from axl.translator import to_english, to_json, from_json

to_english(raw: str) -> str

Translates an AXL packet to a human-readable English sentence.

from axl.translator import to_english

print(to_english("S:SIG.1|breach_detected|zone-4|severity=critical|!ALERT|!ESCALATE"))
# "Security signal (priority 1): Breach detected in zone-4, severity critical. Flags: ALERT, ESCALATE."

to_json(raw: str) -> dict

Translates an AXL packet to a structured JSON dictionary.

from axl.translator import to_json

data = to_json("S:OPS.3|cpu_high|node-7|threshold=90|!ALERT")
# {
#     "domain": "OPS",
#     "tier": 3,
#     "fields": ["cpu_high", "node-7", "threshold=90"],
#     "flags": ["ALERT"],
#     "timestamp": null,
#     "rosetta": null,
#     "payment": null
# }

from_json(data: dict) -> str

Constructs an AXL packet from a JSON dictionary.

from axl.translator import from_json

pkt = from_json({
    "domain": "ERR",
    "tier": 2,
    "fields": ["db_timeout", "latency=3200ms"],
    "flags": ["ALERT", "RETRY"],
})
print(pkt)
# S:ERR.2|db_timeout|latency=3200ms|!ALERT|!RETRY

---

Data Models

Packet

Top-level container for a parsed AXL packet.

@dataclass
class Packet:
    preamble: Preamble
    header: Header
    fields: list[str]
    flags: list[str]
    raw: str

Preamble

Optional metadata preceding the header.

@dataclass
class Preamble:
    rosetta: str | None       # Rosetta file URI
    payment: PaymentProof | None  # On-chain payment proof
    timestamp: int | None     # Unix timestamp
    nonce: int | None         # Monotonic nonce

Header

The S:DOMAIN.TIER segment.

@dataclass
class Header:
    domain: str   # e.g., "OPS", "SIG", "PAY"
    tier: int     # 1 (critical) through 5 (debug)

Body

Container for fields and flags (used internally).

@dataclass
class Body:
    fields: list[str]   # Data fields
    flags: list[str]    # Signal flags (without "!" prefix)

PaymentProof

On-chain payment attestation.

@dataclass
class PaymentProof:
    tx_id: str     # Transaction hash
    sig: str       # Cryptographic signature
    gas: int       # Gas cost in wei

ValidationResult

Output of the validate() function.

@dataclass
class ValidationResult:
    valid: bool            # Overall validity
    errors: list[str]      # Blocking errors
    warnings: list[str]    # Non-blocking warnings
    domain: str | None     # Parsed domain (if parseable)
    tier: int | None       # Parsed tier (if parseable)

Import Summary

# Individual imports
from axl.parser import parse
from axl.emitter import emit
from axl.validator import validate
from axl.translator import to_english, to_json, from_json

# Data models
from axl.models import Packet, Preamble, Header, Body, PaymentProof, ValidationResult