aeo-sdk-python

Python SDK for the AEO Protocol v0.1 — parse, build, validate, and fetch AEO declaration documents.

Install

pip install aeo-protocol

Quickstart

from aeo import Document, fetch_well_known

# Fetch and parse from a live well-known URL
doc = fetch_well_known("https://mizcausevic-dev.github.io")
print(doc.entity.name)              # "Miz Causevic"
print(doc.claim_ids())               # ['current-role', 'location', ...]
print(doc.find_claim("years-experience").value)  # 30

# Parse from disk
doc = Document.from_file("aeo.json")

# Build programmatically
from aeo import Entity, Authority, Claim, Document
doc = Document(
    entity=Entity(
        id="https://example.com/#org",
        type="Organization",
        name="Example Org",
        canonical_url="https://example.com/",
    ),
    authority=Authority(primary_sources=["https://example.com/"]),
    claims=[Claim(id="tagline", predicate="description", value="A reference example.")],
)
print(doc.to_json())

Async variant:

import asyncio
from aeo.client import fetch_well_known_async

doc = asyncio.run(fetch_well_known_async("https://mizcausevic-dev.github.io"))

What it does

• Parse — Document.from_json / from_file / from_dict
• Build — pydantic v2 model classes for every type in the spec (Entity, Authority, Claim, Verification, CitationPreferences, AnswerConstraints, Audit)
• Serialize — Document.to_json() returns canonical JSON
• Fetch — fetch_well_known(origin) performs HTTP discovery against /.well-known/aeo.json with Accept: application/aeo+json, application/json
• Query — doc.claim_ids() and doc.find_claim(id) for convenience

Conformance

This SDK supports the AEO Protocol at conformance Level 1 (Declare). Signature verification (Level 2) and audit-endpoint posting (Level 3) are not yet implemented; signed documents parse fine but the signature is not verified.

Dependencies

• pydantic >= 2.0 — model validation and serialization
• httpx >= 0.27 — sync and async HTTP

Development

pip install -e .[dev]
pytest -v

Specification

Full spec at github.com/mizcausevic-dev/aeo-protocol-spec.

License

MIT-licensed. Free for commercial and non-commercial use with attribution. The AEO Protocol specification this SDK implements is also MIT (see aeo-protocol-spec).

Kinetic Gain Protocol Suite

Spec	Implementation
AEO Protocol	aeo-sdk-python (this) · aeo-sdk-typescript · aeo-sdk-rust · aeo-sdk-go · aeo-cli · aeo-crawler
Prompt Provenance	—
Agent Cards	—
AI Evidence Format	—
MCP Tool Cards	—

---

Connect: LinkedIn · Kinetic Gain · Medium · Skills