aep: no Python emitter example / exported JSON Schema; downstream ports drift silently

[telleroutlook]

No Python emitter example in packages/aep

Repo: packages/aep

Problem

@wasmagent/aep is a TypeScript emitter. Real production agents live in many languages — LangChain / LlamaIndex / FastAPI / Django services often run in Python. Any Python service that wants to emit AEP records has to reverse-engineer the schema from the Zod definitions.

Evidence

I searched wasmagent-js/README.md, packages/aep/README.md, and all of docs/. The Python-related references are:

• docs/data-pipeline.md:57,105,115,124,145 — python -m datafactory (training-data consumption, not emit)
• docs/kernels/comparison.md:26,27,47 — Pyodide kernel comparison (running Python inside the agent, not emitting from Python)
• docs/compare.md:18,48 — Pyodide feature table

Zero Python examples for the AEP emit path. packages/aep/README.md shows only TypeScript. packages/aep/src/emitter.ts is not exposed as a schema/OpenAPI/protobuf equivalent that a Python service can generate a client from.

What downstream integrators end up doing

In our project (Python FastAPI + @openagentaudit) we hand-ported the emitter to Python:

• audit/emitter.py — 200-line Python AEPEmitter that mirrors the TS version's public surface (addAction, addCapabilityDecision, setBudgetLedger, build)
• The port re-encodes the schema shape from reading wasmagent-js/packages/aep/src/types.ts line by line
• Every wasmagent-js release, we have to diff the types file to stay in sync

That works for us but is fragile: a v0.3 field addition on your side won't cause a compile error on our side; we'll just silently drop it.

Impact

1. Python is likely the largest agent ecosystem. Every Python integrator writes their own emitter port.
2. Ports drift silently. A minor schema evolution can break downstream analysis (open-agent-audit's adapter is strict about schema_version).
3. No official test fixture — Python ports can't verify their output against a canonical example.

Proposed fix

In order of cost:

Option A (cheapest, non-code): publish the AEP JSON schema. packages/aep/src/types.ts uses Zod — you can zodToJsonSchema the top-level AEPRecordSchema and commit it as packages/aep/schema/aep-v0_2.schema.json. Python / Go / any language can then codegen a validator without hand-porting. Also useful for validating against test fixtures.

Option B (small code): a canonical example file packages/aep/examples/canonical-v0_2.json — one full record with every optional field populated (signature, actions with capability_decisions, budget_ledger, run_context). Serves as a fixture non-JS ports can round-trip against.

Option C (bigger): a tiny Python package wasmagent-aep-py (or in another repo under WasmAgent org) with a AEPEmitter class mirroring the TS surface. Reference implementation you maintain, so downstream doesn't drift.

Option A + B together would be a big win and low cost. Happy to send a PR that adds them.

Optional bonus: mention in README that non-JS emitters should target schema_version: "aep/v0.2" and pin against the JSON Schema file.

---

Filed by: CATL Ariba Joule integration team. We maintain a private Python port; would prefer to base it on a supported schema definition.