Open Questions

The unresolved tradeoffs across the framework. Each will be settled during the v0.5 → v1 cycle.

Resolved decisions worth recording

These were considered “open” early in design and have since been resolved. Recorded here so reviewers see the deliberation.

  1. Cloud portability. Resolved: the framework’s core has no cloud dependencies. All cloud-specific code lives behind ABCs (BaseDistributedExecutor, BaseBatchAnnotationOrchestrator, BaseCredentialsProvider, BaseLogSink) with concrete subclasses in optional extras (rfgen[gcp], rfgen[aws], rfgen[azure], rfgen[databricks], etc.). Adding a new cloud is strictly additive: a new package or module that subclasses the relevant base. See Reference / Cloud Backends.

  2. Plugin discovery and future hub. Resolved: plugins ship a standardized PluginMetadata declaration (Reference / Plugin Metadata). Discovery uses a BaseRegistry abstraction; the default reads Python entry points, and a future hub-style remote registry is a JsonManifestRegistry subclass added later without core changes.

Cross-cutting

  1. Real captures in the loop or pure sim? Default is “sim with HIL validation,” but specific high-value classes (drone OcuSync, real WiSig devices) may need capture-augmented templates.

  2. Spectrogram-domain output? Some downstream models consume spectrograms directly. Generate IQ canonically and emit spectrograms on-demand, or store both?

  3. Public dataset release tiers. Source dataset licenses constrain what derivatives we can ship publicly. Likely two tiers: internal full dataset + public CLIP-for-RF benchmark on permissively-licensed sources.

  4. LLM choice for bulk annotation. Gemini Flash, GPT-4o-mini, Claude Haiku: pick one for cost / quality / latency. Verifier model separate.

  5. TorchSig version pinning. v2.1.x is current; v2.x to v3 will likely break. Pin and lock.

Layout (see Reference / Project Layout)

  1. validation/ inside rfgen vs. sibling package rfgen-validate?

  2. presets/ as YAML files inside the package vs. shipped under configs/presets/?

  3. emitters/cellular/ vs. emitters/lte/ + emitters/nr/?

  4. Where do hardware-fingerprint parameters live: per-emitter or in channels/?

Plugin interfaces (see Reference / Plugin Interfaces)

  1. Should BaseEmitter.generate return Spectrogram too?

  2. BaseChannel.apply shape contract: explicit tail length via meta, or always pad?

  3. BaseAnnotator granularity, one annotator per type or one per suite?

  4. Multi-RX Record.iq shape: (num_rx, 2, N) vs. (2, num_rx, N) vs. complex (num_rx, N).

Config schema (see Reference / Config Schema)

  1. If a shared SNR-range knob returns, should it live on ChannelConfig or SceneConfig? (The shipped ChannelConfig.snr_db_range field is a legacy compatibility placeholder and is not consumed at runtime.)

  2. Per-emitter SNR override. Add EmitterFamilyConfig.snr_db_range_override?

  3. Hydra structured configs (Pydantic-as-source-of-truth) vs. dict-based.

Label schema (see Reference / Label Schema)

  1. Multi-label segmentation as default? Lean: keep single-label default; per-dataset config knob.

  2. Spectrogram precomputed or on-the-fly? Lean: on-the-fly; opt-in flag.

  3. Per-bin SNR map? Lean: per-emitter scalar for v1.

  4. Confidence-tagged unknown nodes for HIL captures? Lean: introduce in v1.1.

Storage (see Reference / Storage Layout)

  1. _shards/shard_index.parquet required or optional?

  2. WebDataset compression: per-record gzip or per-tar zstd?

  3. HDF5 SWMR mode for ongoing writes?

Cloud backends (see Reference / Cloud Backends)

  1. Should the framework ship a rfgen[cloud-agnostic] meta-extra that bundles Databricks, Anthropic Batch, OpenAI Batch, and Ray? Lean: yes, but not before v1.

  2. Should the project host an official remote plugin index (analog to PyPI’s index for rfgen-* packages) or rely on PyPI keyword search? Lean: rely on PyPI initially; build a hub if the community grows past about 30 plugins.