ria-toolkit-oss/#module.sigil

component RiaToolkitOss {
  goal {
    RIA Toolkit OSS is the open-source RIA Toolkit: the foundational Python tools to develop, test, and deploy radio intelligence applications.

    It owns the core radio data types, signal generation and processing, the radio dataset framework, a unified SDR hardware abstraction, annotation tooling, visualization, and the CLI, agent, and server surfaces that expose them.

    It serves both standalone SDR/ML researchers and RIA Hub, whose controller embeds this library in-process.

    It does not own RIA Hub's web platform, storage, or orchestration UI; it provides the radio primitives those build on.
  }

  interface {
    PythonLibrary {
      A Python library (ria_toolkit_oss) importable by downstream code, including RIA Hub's controller which imports it in-process.

      Library surfaces: data (radio-ML data types including Recording and Annotation, plus the radio dataset and dataset-builder framework); io (load/save recordings across SigMF, npy, wav, and Blue); signal (signal generation and processing); transforms (NumPy radio-data transforms used in ML); sdr (unified receive/transmit API across software-defined radios); annotations (annotation management and automatic signal-detection annotation); view and viz (plotting and report generation); utils (array-conversion and helpers).
    }

    Orchestration {
      orchestration: configure and run automated RF capture campaigns (CampaignConfig).
    }

    RemoteControl {
      remote_control: remote SDR transmitter control over SSH and ZMQ.
    }

    Server {
      server: the RT-OSS HTTP server (ria-server) that can run orchestration and inference as a standalone HTTP service.
    }

    CommandLineTools {
      CLI suite (console scripts): ria and ria-tools (main toolkit CLI), ria-server (RT-OSS HTTP server), ria-agent (edge node agent for campaigns/inference), ria-app (pull and run containerized RIA applications).
    }

    FileFormats {
      File formats: SigMF signal recordings and HDF5 radio datasets.
    }
  }
}

expand RiaToolkitOss {
  logic {
    The library provides the radio data types and signal tools; the CLI, agent, server, and app runners are entry points layered over that library.

    It is consumed both as an imported Python library and through its console-script CLIs.

    The server package (RT-OSS) is a standalone HTTP deployment of orchestration and inference; RIA Hub's controller embeds this library in-process rather than calling that server.
  }

  constraints {
    Python 3.10+; license is AGPL-3.0-only.

    Ships as a single distribution (ria-toolkit-oss) containing two packages from src: the ria_toolkit_oss library and the ria_toolkit_oss_cli CLI.

    numpy is pinned to 1.26.4 for Radioconda compatibility; scipy is constrained below 1.16.

    SDR hardware backends are intended as optional extras, but the individual optional-dependency entries are currently commented out; only an all-sdr list (pyrtlsdr, pyadi-iio for Pluto, pyhackrf, pyrf for ThinkRF; excluding USRP/UHD and BladeRF, which need system libraries) is present, and it is not wired as a valid PEP 621 extra.

    Built with poetry-core.

    The view and viz packages overlap: both provide recording-plot primitives (spectrogram, iq_time_series, frequency_spectrum, constellation); viz is the superset RIA Hub imports, view is the CLI-facing set. This duplication is unresolved.
  }

  decisions {
    DependencyPinning {
      Decision: Pin numpy to 1.26.4 and constrain scipy below 1.16.

      Scope: Governs the distribution's core numeric dependencies; does not govern optional SDR backends.

      Design issues addressed: Radioconda compatibility requires a specific numpy ABI, and an unconstrained scipy pulls in versions incompatible with that pin.

      Revisit when: Radioconda moves to a newer numpy, or the scipy constraint blocks a required feature.
    }

    SdrBackendExtras {
      Decision: Offer SDR hardware backends only as optional extras, and exclude USRP/UHD and BladeRF from the bundled all-sdr list.

      Scope: Governs optional-dependency packaging for SDR hardware; the core library installs without any SDR backend.

      Design issues addressed: USRP/UHD and BladeRF require system libraries that cannot be resolved through Python packaging alone.

      Consequences: Only pyrtlsdr, pyadi-iio (Pluto), pyhackrf, and pyrf (ThinkRF) are candidates for pure Python extras; the individual entries are currently commented out and the all-sdr list is not yet wired as a valid PEP 621 extra.
    }
  }

  cases {
    A researcher installs the package and uses the ria CLI to generate or inspect a radio dataset.

    RIA Hub's controller imports ria_toolkit_oss in-process to load recordings, render plots, and drive radios.

    A ria-agent node runs on an edge device to execute capture or inference campaigns.

    ria-server exposes toolkit operations to RIA Hub over HTTP.
  }
}