API Reference¶

The Python surface of the framework, 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.

Warning

Pre-implementation. Class signatures, parameter lists, and method names are proposals. Once code lands, these pages will be regenerated from docstrings via sphinx.ext.autodoc + autosummary. Hand-written prose lives in Concepts; the API reference stays close to the code.

Design principles¶

The API is shaped by four rules that recur in every module page:

1. Four roles, kept separate. The Python surface has four kinds of public symbol. Conflating an extension contract with a sealed service is a documentation smell:

Role	What it is	Examples
Data types	The currency every layer speaks. Frozen dataclasses, schema-versioned, no behavior.	Signal, SignalMetadata, SceneMetadata, Record, BBox
Plugin interfaces (ABCs)	The extension contract. One per layer, normative, auto-registering. Subclass to add a backend.	BaseEmitter, BaseChannel, BaseSceneComposer, BaseLabeler, BaseAnnotator, BaseStore
Concrete classes	Implementations of a plugin ABC that users instantiate or select through config.	LoRaEmitter, SionnaRT, DefaultSceneComposer, JointLabeler, ZarrStore
Sealed services and facades	A deliberately non-extensible operation or a stable, small user entry point. Their exact method or function contract is normative; callers compose them but do not subclass or register replacements.	ExecutionEvidenceValidatorV1, rfgen.open_store, DoctorReportV1

A typical user instantiates concrete classes (or names them in YAML); a plugin author subclasses an ABC. Data types flow through both unchanged. A caller of a sealed service supplies typed input at its documented boundary instead of implementing a plugin interface. For example, the caller owns the declared SelectorInventoryV1 passed to the evidence validator; the validator owns the fixed cross-record and Git-policy checks, so it has no extension ABC.

2. ABCs are normative only at plugin boundaries. If a concrete plugin class behaves differently from its ABC, the ABC page is the source of truth and the concrete class is the bug. Concrete plugins are selected and swapped by config; there is no recommended default that lives in code. A sealed service or facade instead owns a fixed policy or import boundary. It is not made extensible merely to fit the plugin pattern.

3. You don’t subclass concrete classes. Composition, not deep inheritance. At a plugin boundary, write a new concrete class against the ABC, not a subclass of an existing one. At a sealed-service boundary, pass the documented typed input or compose the result. This keeps extension points explicit and prevents release-policy ownership from leaking into user implementations.

4. The reference is autogenerated. Once code lands, every class page in this section is built from docstrings via sphinx.ext.autodoc. Hand-written prose is restricted to the conceptual pages under Concepts; this section stays close to the code so docs cannot drift from behavior. Pre-implementation, the pages here are written by hand in the same shape autodoc emits, so the eventual swap is mechanical.

Module map¶

Module	Section	What it contains
`rfgen.enums`	Enums	`StrEnum` types used by config fields and metadata fields with closed value sets
`rfgen.core.types`	Core Types	Signal, SignalMetadata, SceneMetadata, Record, BBox, type aliases
`rfgen.config`	Config	Pydantic models for the full config schema
`rfgen.emitters`	Emitters	Concrete emitter classes (one per family) and the BaseEmitter ABC
`rfgen.channels`	Channels	Layer 2 BaseChannel ABC, the `Transformation` and `Group` enums, the per-call `ChannelContext`, and the 13 per-transformation ABCs
`rfgen.device_fingerprint`	Device Fingerprint	`FingerprintParams` and `DeviceRegistry` per-device parameter store
`rfgen.propagation`	Propagation	`BaseChannelPropagation` plus the `AWGNChannel` and Sionna-backed propagation concretes
`rfgen.rx_frontend`	RX Frontend	Eight RX-side per-transformation concretes (mixer, IF filter, resampler, LNA noise, ADC, RX phase noise, RX IQ-imbalance, AGC) plus the `TorchSigImpairments` adapter
`rfgen.rf_chain`	Calibrated RF Chain	Sealed calibration-profile, compiled-stage, deterministic processing, snapshot, and report contracts
`rfgen.rt_assets`	RT Material Assets	Sealed versioned material and antenna-pattern validation, public Sionna RT binding, and deterministic assignment receipts
`rfgen.scene`	Scene	DefaultSceneComposer and the BaseSceneComposer ABC
`rfgen.labels`	Labels	BBoxLabeler, SegmentationLabeler, JointLabeler
`rfgen.annotators`	Annotators	Per-template annotators, BaseInferenceClient implementations
`rfgen.storage`	Storage	ZarrStore, WebDatasetStore, the BaseStore ABC
`rfgen.executors`	Executors	Local, Ray, and Spark executors behind the BaseDistributedExecutor ABC
`rfgen.credentials`	Credentials	Credential providers for cloud backends and LLM APIs
`rfgen.registry`	Registry	Plugin discovery, registration, and entry-point loading
`rfgen.logging`	Log Sinks	Structured log sinks and observability hooks
`rfgen.execution_evidence`	Execution Evidence	Immutable workstream, gate, scientific-validation, and chapter evidence records plus the semantic validator
`rfgen.manifest`	Manifest	Versioned canonical run-manifest payloads, forward-compatible envelopes, verification reports, and packaged JSON Schema loaders
`rfgen.manifest_repository`	Manifest	Dataset-bound local manifest staging, immutable revisions, and compare-and-swap `LATEST` publication
`rfgen.manifest_verification`	Manifest Verification	Read-only metadata, object-checksum, and bounded reproduction verification of a published manifest
`rfgen.attestation`	Attestation	Closed Sigstore DSSE signing and verification boundary, identity policy, canonical in-toto statements, and typed fail-closed errors
`rfgen.supply_chain_evidence`	Supply-chain Evidence	Offline verification of self-hashed release reports against caller-parsed SBOM, scan, signature-bundle, and provenance evidence
`rfgen.admission_estimation`	Admission Estimation	Strict, immutable price, quota, provenance, resource-demand, and offline signed-admission-estimate contracts
`rfgen.release_support_inventory`	Release Support Inventory	Canonical advertised capability, support-row, evidence, and release-publication contracts
`rfgen.benchmark_qualification`	Benchmark Qualification	Signed five-sample baselines, fixed qualification gates, and PASS-only Wave 5 sealing
`rfgen`, `rfgen.public`	Installed-wheel Public Surface	Root `open_store` and version exports plus doctor capability diagnostics
`rfgen.dataset`	Dataset	BaseSampler, BaseCollator, and concrete sampler/collator classes for consumer-side training pipelines
`rfgen.dataset`	Adapters	RfgenTorchDataset bridge for `torch.utils.data.DataLoader`; behind `rfgen[torch]`
`rfgen.errors`	Errors	Exception hierarchy raised across the framework

Each extensible module page contains its own ABC section alongside the concrete classes that implement it; there is no separate plugin-interfaces page. Pages for sealed services and facades instead document their fixed function, model, and validation boundaries.

How each module page is structured¶

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

Module summary - one paragraph on what the module covers.
Class index - one row per public class with family / backend tier / one-line note.
Per-class entries, in autodoc order:
- Class signature with constructor parameters.
- Class attributes (family, supported_classes, …).
- Methods with signatures, parameter tables, return types, raises, example.
- Schema - the Pydantic model the class accepts as params.
- Notes for non-obvious behavior; See Also for cross-links.
ABC reference, when extensible - the ABC section on the same module page documents a plugin contract. A sealed-service or facade page documents its fixed function, model, and validation boundary instead.