API reference

Warning

Pre-implementation. This section describes proposed contracts. Behavior is subject to change before code lands.

Who should read this. Implementers porting the spec to code, and reviewers checking an anchor.

Before you start. Read the schema reference first; the API classes implement those schemas.

What this section is not. It is not runnable yet; every signature here is a proposed contract.

The Python surface of EMMA (Electromagnetic Multi-task Model Assessment), organized by module. Each page documents the concrete classes shipped in that module, the data types they consume and produce, and the abstract base class every concrete class subclasses. Every signature is proposed-contract until src/emma/ lands.

Design principles

The API follows the same four rules that shape every rfgen module page:

1. Three roles, kept separate. Data types (frozen dataclasses), ABCs and Protocols (the extension contract), and concrete classes (what users instantiate). Conflating them is a documentation smell.

2. ABCs are the normative spec. If a concrete class behaves differently from its ABC, the ABC page is the source of truth and the concrete class is the bug.

3. No concrete-to-concrete inheritance. Composition, not deep inheritance. To add behavior, write a new concrete class against the ABC.

4. The reference will be autogenerated. Once code lands, pages here are built from docstrings via sphinx.ext.autodoc. Hand-written prose stays in Concepts; this section stays close to the code.

Module map

Module	Section	What it contains
emma.enums	Primitives	StrEnum types for closed choices: TaskID, Pillar, ReleaseVersion, Maturity, Split, Environment, OODAxis, SubmissionMode, MetricDirection, Domain
emma.errors	Primitives	Exception hierarchy rooted at EmmaError
emma.schemas	Schemas	Pydantic v2 models: TaskSpec, DatasetRecipe, SceneManifest, DataReleaseManifest, PredictionBundle, Submission, LeaderboardRow, RunManifest, PreRegistration, ReScoringLog
emma.datasets	Datasets	RfgenRecipe, EMMADataset, LabelExtractor, DataRelease, ArraySpec, the RealCaptureAdapter ABC plus the Colosseum, POWDER, and COSMOS concretes
emma.metrics	Metrics	The Metric ABC, 15 concrete per-task metric classes, the Aggregator ABC, OODAvg, SimToRealGap
emma.tasks	Tasks	The FrozenBackbone Protocol, the ReadoutHead ABC and five concrete heads, the Task ABC and TaskRegistry, the OODProtocol ABC and three concrete protocols
emma.harness	Harness	Evaluator, EvalRun, ProtocolRunner, PredictionWriter
emma.leaderboard	Leaderboard	The LeaderboardStore ABC, ResultsOnlyBoard, SandboxedCodeBoard, HoldoutScorer, ScoringServer, AntiOverfit, SubmissionValidator
emma.cli	CLI	The Typer application: list-tasks, download, eval, submit, score, release
emma.governance	Governance	PreRegistrationStore, ReScoringLogWriter, COICharter

How each module page is structured

Module pages follow the same shape, matching what sphinx.ext.autodoc produces:

1. Module summary: one paragraph on what the module covers.

2. Class index: one row per public class with role and one-line note.

3. Per-class entries: signature block, field or parameter tables, method signatures where relevant, invariants, and notes.

Boundary ABCs and Protocols

The current set of framework-owned extension points, one per concept:

• FrozenBackbone (Protocol)

• ReadoutHead (ABC)

• Task (ABC)

• Metric (ABC)

• Aggregator (ABC; OODAvg is the sole concrete subclass, and SimToRealGap is intentionally not a subclass for Liskov reasons documented on the Metrics page)

• OODProtocol (ABC)

• RealCaptureAdapter (ABC)

• LeaderboardStore (ABC)

See PRINCIPLES.md for the one-ABC-per-concept and no-concrete-to-concrete-inheritance rules.