diff --git a/#module.sigil b/#module.sigil new file mode 100644 index 0000000..8c0ac9c --- /dev/null +++ b/#module.sigil @@ -0,0 +1,95 @@ +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. + } +} diff --git a/.sigil/config.json b/.sigil/config.json new file mode 100644 index 0000000..0616a94 --- /dev/null +++ b/.sigil/config.json @@ -0,0 +1,20 @@ +{ + "sigilVersion": "0.5.0", + "workspace": { + "name": "ria-toolkit-oss", + "members": [] + }, + "files": { + "include": [ + "**/*.sigil" + ], + "exclude": [ + ".git/**", + ".deno/**", + "node_modules/**", + "build/**", + "coverage/**" + ] + }, + "tools": {} +} diff --git a/src/ria_toolkit_oss/agent/agent.sigil b/src/ria_toolkit_oss/agent/agent.sigil new file mode 100644 index 0000000..f0ee780 --- /dev/null +++ b/src/ria_toolkit_oss/agent/agent.sigil @@ -0,0 +1,59 @@ +component RiaAgent { + goal { + Run a toolkit agent on an edge device that connects outbound to RIA Hub to capture, stream, or run inference on live radio. + + Own the agent CLI, its two execution modes, and its persisted registration. + } + + interface { + AgentCommands { + CLI ria-agent with subcommands: register (--hub, --api-key, --name, and TX interlock flags), stream, run (legacy), and detect (list SDR drivers). + } + + Registration { + register POSTs to {hub}/screens/agents/register with the X-API-Key registration key and saves agent_id and token to ~/.ria/agent.json (mode 0600). + } + + ExecutionModes { + Two execution modes: a WebSocket streamer that opens an SDR and streams raw IQ to the hub (the hub does inference), and a legacy long-poll NodeAgent that runs ONNX inference locally on the device. + } + } +} + +expand RiaAgent { + logic { + The streamer connects to wss://{hub}/screens/agent/ws with a bearer token, heartbeats, auto-reconnects, and runs concurrent RX (ship interleaved float32 IQ) and TX (play inbound IQ) sessions, sharing one driver for full-duplex when RX and TX name the same device. + + The legacy NodeAgent connects outbound only: it registers at /composer/nodes/register, heartbeats, long-polls /commands, and dispatches run_campaign, load_model, start/stop/configure_inference, and TX commands, reporting to /events and /campaign-status. + } + + constraints { + TX is opt-in (--allow-tx) and bounded by tx_max_gain_db, tx_max_duration_s, and allowed frequency ranges, with a TX watchdog; a TX-start request exceeding the interlocks is rejected (per-frame handling rejects malformed frames and enforces max duration). + + Registration keys are personal (ria_reg_ prefix); the legacy shared key is deprecated. Failures are reason-coded (invalid_key, expired, revoked, already_consumed, rate-limited). + + Config is AgentConfig at ~/.ria/agent.json (override RIA_AGENT_CONFIG). + } + + decisions { + ExecutionModeSplit { + Decision: The agent offers a WebSocket streamer that ships raw IQ for hub-side inference and retains a legacy long-poll NodeAgent that runs ONNX inference locally on the device. + + Scope: Governs where inference executes for a connected agent. + + Trade-offs: Streaming keeps the edge thin and centralizes model logic at the hub at the cost of a continuous IQ uplink; local inference avoids that uplink but pins model execution to the device. + + Consequences: The legacy local-inference path is retained alongside the streamer rather than being the primary mode. + } + + TxOptIn { + Decision: Transmit is disabled unless --allow-tx is set and is bounded by max gain, max duration, allowed frequency ranges, and a TX watchdog. + + Scope: Governs whether and how a registered agent may transmit. + + Design issues addressed: RF transmission is regulated and physically risky, so an agent must not transmit by default or outside operator-declared bounds. + + Consequences: A TX-start request exceeding the interlocks is rejected. + } + } +} diff --git a/src/ria_toolkit_oss/annotations/annotations.sigil b/src/ria_toolkit_oss/annotations/annotations.sigil new file mode 100644 index 0000000..e946bae --- /dev/null +++ b/src/ria_toolkit_oss/annotations/annotations.sigil @@ -0,0 +1,65 @@ +component Annotations { + goal { + Create, manage, and automatically detect annotations on a recording. + + Own the detection algorithms, annotation transforms, signal isolation, and slice qualification. + } + + interface { + SignalDetection { + Automatic detection, each returning a new Recording with detected annotations appended: detect_signals_energy (energy/envelope), annotate_with_cusum (change-point segmentation), threshold_qualifier (hysteresis burst detection), annotate_with_obw (occupied-bandwidth), and find_spectral_components with split_recording_annotations (parallel signal separation). + } + + BandwidthHelpers { + Bandwidth helpers: calculate_occupied_bandwidth, calculate_nominal_bandwidth, calculate_full_detected_bandwidth. + } + + AnnotationTransforms { + Annotation transforms: remove_contained_boxes and is_annotation_contained (merge_annotations is declared but not implemented). + } + + SignalIsolation { + isolate_signal (slice, normalize, shift to baseband, low-pass to the annotation bandwidth) and qualify_slice_from_annotations (fixed-length slices overlapping annotations). + } + + StandaloneSurface { + This layer is a standalone library surface; the RIA Hub controller does not import it directly. + } + } +} + +expand Annotations { + logic { + Energy detection builds a moving-average envelope, estimates a segment-median noise floor, thresholds with hysteresis, merges nearby boundaries, and assigns frequency bounds by the chosen method (nominal, occupied, or full-detected bandwidth). + + Detectors write a JSON comment recording the detection type, generator, and parameters, plus a detail dict. + } + + constraints { + Detectors require a sample_rate in the recording metadata and operate on channel 0 (only threshold_qualifier accepts a channel override). + + Annotation frequencies are stored absolute (center frequency plus the relative offset); the parallel separator works in baseband and converts. + + A detector warns and returns the recording unchanged when the dynamic range is too low to threshold. + } + + decisions { + DetectionProvenance { + Decision: Have each detector write a JSON comment capturing the detection type, generator, and parameters, plus a detail dict, onto the annotations it appends. + + Scope: Governs annotations produced by the automatic detectors. + + Design issues addressed: A detected annotation's origin and settings must be recoverable after the fact for auditing and reproducibility. + } + + AbsoluteFrequencyStorage { + Decision: Store annotation frequencies as absolute values (center frequency plus the relative offset). + + Scope: Governs frequency bounds on all annotations, including those produced by the parallel separator. + + Design issues addressed: Relative-only frequencies are ambiguous once a recording is shifted to baseband or compared across recordings. + + Consequences: The parallel separator works in baseband and converts its results to absolute frequencies before storing them. + } + } +} diff --git a/src/ria_toolkit_oss/app/app.sigil b/src/ria_toolkit_oss/app/app.sigil new file mode 100644 index 0000000..7e9407d --- /dev/null +++ b/src/ria_toolkit_oss/app/app.sigil @@ -0,0 +1,45 @@ +component AppRunner { + goal { + Pull and run containerized RIA applications, auto-configuring hardware access from image labels. + + Own the ria-app CLI over a container engine. + } + + interface { + AppCommands { + CLI ria-app with subcommands: pull, run, list, stop, logs, and configure; a global --sudo flag. + } + + RunBehavior { + run auto-pulls the image if absent and derives container flags from the image's ria.* labels. + } + } +} + +expand AppRunner { + logic { + The engine is the first of docker or podman on PATH, optionally sudo-prefixed. + + Image references resolve against a configured registry and namespace; fully-qualified references pass through. + + Hardware flags are derived from ria.profile and ria.hardware labels: GPU access when an NVIDIA profile and runtime are present, USB device passthrough for USB SDRs, and host networking for USRP, ThinkRF, and Pluto; flags can be overridden or dry-run. + } + + constraints { + There is no Python SDK; it is a subprocess wrapper and exits with an error if no container engine is found. + + Config is AppConfig (registry, namespace, sudo) at ~/.ria/toolkit.json with environment-variable fallbacks. + } + + decisions { + SubprocessWrapper { + Decision: ria-app shells out to a container engine (the first of docker or podman on PATH) rather than exposing a Python SDK or using an engine client library. + + Scope: Governs how the runner controls containers. + + Consequences: A container engine must be present on PATH and the tool exits with an error when none is found; there is no in-process programmatic API for callers. + + Trade-offs: Reuses the installed engine and its existing auth and configuration directly at the cost of no library-level integration point. + } + } +} diff --git a/src/ria_toolkit_oss/data/data.sigil b/src/ria_toolkit_oss/data/data.sigil new file mode 100644 index 0000000..e24275c --- /dev/null +++ b/src/ria_toolkit_oss/data/data.sigil @@ -0,0 +1,83 @@ +component RadioData { + goal { + Provide the core radio-ML data types: a Recording (an immutable IQ tape with metadata and annotations) and the radio dataset and dataset-builder framework. + + Own the in-memory contract the rest of the toolkit and RIA Hub build on for signals and datasets. + } + + interface { + Recording { + Recording(data, metadata=None, dtype=None, timestamp=None, annotations=None) - complex IQ data shaped channels-by-samples (1-D is reshaped to one channel); metadata must be a JSON-serializable dict; rec_id and timestamp are auto-populated. + + Recording properties: data, metadata, annotations, shape, n_chan, rec_id, dtype, timestamp, sample_rate (settable). + + Recording methods: astype, add_to_metadata/update_metadata/remove_from_metadata (rec_id and timestamp protected), trim, normalize, view/simple_view, and to_sigmf/to_npy/to_wav/to_blue (delegating to io). + } + + Annotation { + Annotation(sample_start, sample_count, freq_lower_edge=None, freq_upper_edge=None, label="", comment="", detail=None) with is_valid, overlap, area, and to_sigmf_format. + } + + DatasetFramework { + Dataset framework (data.datasets): abstract RadioDataset (HDF5-backed and iterable; item assignment raises, though it exposes explicit inplace mutators) with IQDataset and SpectDataset subclasses, DatasetBuilder, and leakage-safe split/random_split. + } + } +} + +expand RadioData { + state { + A Recording's sample data is immutable: item assignment raises, and property accessors return copies or read-only views; metadata is mutable only through the metadata methods. + + Metadata keys must be lowercase letters and underscores only (no digits); rec_id and timestamp are protected and cannot be modified or removed. + } + + logic { + A Recording requires complex data of one or two dimensions (channels by samples); rec_id is the SHA-256 of the data bytes plus timestamp. + + trim slices samples and re-aligns annotations; normalize scales peak magnitude to 1 and rejects all-zero data. + + RadioDataset reads data and metadata lazily from an HDF5 source; non-inplace mutations write numbered sibling files; concrete backends live outside the OSS package. + + split and random_split partition by rec_id so no recording leaks across subsets; lengths may be counts or fractions. + } + + constraints { + Recording data must be complex or construction raises; metadata must be a JSON-serializable dict. + + RadioDataset sources must be HDF5 (validated at construction); the data and metadata datasets are required for use but not checked at init; the class is abstract and instantiated only via a concrete backend. + + The datatypes package is stale (only bytecode remains); the live location is data. + } + + decisions { + RecordingImmutability { + Decision: Make Recording sample data immutable and derive rec_id as the SHA-256 of the data bytes plus timestamp. + + Scope: Governs Recording identity and the sample-data contract; metadata remains mutable through the dedicated metadata methods. + + Design issues addressed: A content-addressed identity is stable only if the underlying samples cannot change after construction, so item assignment raises and accessors return copies or read-only views. + + Consequences: Datasets and splits can key on rec_id as a durable identity, but any modification must produce a new Recording rather than mutate in place. + } + + LeakageSafeSplit { + Decision: Partition split and random_split by rec_id so no recording appears in more than one subset. + + Scope: Governs dataset splitting for train/validation/test construction. + + Design issues addressed: Sharing a recording across subsets leaks information between ML training and evaluation sets. + + Assumptions: rec_id uniquely identifies a recording's samples. + } + + HdfBackedAbstractDataset { + Decision: Keep RadioDataset abstract and HDF5-backed, with concrete storage backends living outside the OSS package. + + Scope: Governs the dataset framework's storage contract; IQDataset and SpectDataset define the data shape, backends define storage. + + Design issues addressed: Large radio datasets need lazy on-disk reads, and the OSS package should define the dataset contract without shipping a specific concrete backend. + + Consequences: HDF5 sources are validated at construction, and the class cannot be instantiated directly without a concrete backend. + } + } +} diff --git a/src/ria_toolkit_oss/io/io.sigil b/src/ria_toolkit_oss/io/io.sigil new file mode 100644 index 0000000..75552db --- /dev/null +++ b/src/ria_toolkit_oss/io/io.sigil @@ -0,0 +1,55 @@ +component RecordingIO { + goal { + Load and save Recording objects to and from file across the RF formats the toolkit supports. + + Own format detection and the per-format readers and writers. + } + + interface { + FormatDispatch { + load_recording(file) - dispatch on file extension to the matching reader (sigmf, npy, wav, blue); an unknown extension raises. + } + + FormatCodecs { + Per-format readers and writers: to_sigmf/from_sigmf, to_npy/from_npy (plus from_npy_legacy), to_wav/from_wav, to_blue/from_blue. + } + + WriterBehavior { + Most writers return the output path (to_sigmf returns None) and honor an overwrite flag; auto-generated filenames land under recordings/. + } + } +} + +expand RecordingIO { + logic { + The npy v2 format stores a version marker then data, JSON metadata, and JSON annotations, avoiding pickle; legacy npy paths fall back to pickle with a warning and normalize namespaced metadata keys. + + SigMF writes paired .sigmf-data and .sigmf-meta, mapping RIA metadata to core keys and namespacing the rest under ria:. + + WAV stores I and Q as stereo channels with metadata in an info chunk; Blue uses the MIDAS 512-byte header format. + } + + constraints { + Format detection is by file extension only. + + The SigMF, WAV, and Blue writers reject multichannel input and the readers produce single-channel output; only npy round-trips multichannel data. + + Integer-encoded outputs (16-bit WAV, integer Blue) require samples normalized to the range -1 to 1. + + io.common (exists, validate, move, copy) is declared but unimplemented. + + save_recording is exported in the package __all__ but not defined (latent bug). + } + + decisions { + NpyPickleAvoidance { + Decision: Store the npy v2 format as a version marker followed by data, JSON metadata, and JSON annotations rather than a pickle. + + Scope: Governs the native npy reader and writer; legacy npy files still load through a pickle fallback. + + Design issues addressed: Pickle payloads are unsafe to load from untrusted sources and are not portable across Python versions. + + Consequences: Legacy npy paths fall back to pickle with a warning and normalize namespaced metadata keys for backward compatibility. + } + } +} diff --git a/src/ria_toolkit_oss/orchestration/orchestration.sigil b/src/ria_toolkit_oss/orchestration/orchestration.sigil new file mode 100644 index 0000000..67217f8 --- /dev/null +++ b/src/ria_toolkit_oss/orchestration/orchestration.sigil @@ -0,0 +1,49 @@ +component Orchestration { + goal { + Define and execute automated RF capture campaigns: sweep transmitters and channels, record, QA, and label the results. + + Own the campaign configuration schema, the executor, and the QA checks. + } + + interface { + CampaignSchema { + CampaignConfig(name, recorder, transmitters, qa, output, mode, loops) with loaders from_dict, from_yaml, and from_device_profile; it requires a recorder and at least one transmitter. + + Supporting dataclasses: RecorderConfig, TransmitterConfig (type and control_method external_script/sdr/sdr_remote/sdr_agent), CaptureStep, QAConfig, and OutputConfig. + } + + Execution { + CampaignExecutor(config, progress_cb=None).run() returns a CampaignResult of StepResults; check_recording(recording, config) returns a QAResult; label_recording writes ria: SigMF metadata. + } + } +} + +expand Orchestration { + logic { + The executor opens the SDR and remote TX controllers once, then for each loop, transmitter, and step it starts the transmitter, records IQ, stops the transmitter, then labels, QA-checks, and saves it as SigMF. + + QA estimates SNR from the PSD and checks duration and SNR; in flag-for-review mode a recording always passes but may be flagged. + + Cancellation is cooperative at step boundaries via the progress callback. + } + + constraints { + Frequencies, gains, durations, and bandwidths are parsed from human units (for example 2.45GHz, auto, 1.5m). + + Device names are aliased onto SDR drivers, including mock and sim for hardware-free runs. + + The controller's Conductor and the RT-OSS server are parallel HTTP wrappers that both reuse this package's CampaignConfig and CampaignExecutor in-process. + } + + decisions { + SingleExecutionCore { + Decision: Campaign configuration and execution live in this package as a wrapper-agnostic in-process core, reused directly by both the controller's Conductor and the RT-OSS server rather than reimplemented behind each HTTP front end. + + Scope: Governs where campaign orchestration logic lives relative to its HTTP wrappers. + + Consequences: The HTTP wrappers stay thin and share identical campaign semantics; a change to campaign behavior here propagates to every wrapper. + + Trade-offs: Both wrappers are coupled to this package's in-process API and dataclasses rather than to a stable network contract. + } + } +} diff --git a/src/ria_toolkit_oss/remote_control/remote-control.sigil b/src/ria_toolkit_oss/remote_control/remote-control.sigil new file mode 100644 index 0000000..432aaba --- /dev/null +++ b/src/ria_toolkit_oss/remote_control/remote-control.sigil @@ -0,0 +1,47 @@ +component RemoteControl { + goal { + Drive a software-defined radio transmitter on a remote machine over SSH and ZMQ. + + Own the client controller and the remote server that bridge transmit commands to a remote SDR. + } + + interface { + TransmitterController { + RemoteTransmitterController(host, ssh_user, ssh_key_path, zmq_port=5556): set_radio, init_tx, transmit_async, wait_transmit, stop, close. + } + + TransmitterServer { + RemoteTransmitter (the server on the transmit machine): set_radio, init_tx, transmit, stop, and a run_function JSON-RPC dispatcher; launched as a module over a ZMQ REP socket. + } + } +} + +expand RemoteControl { + logic { + The controller SSHes into the transmit host (paramiko, key-file auth), launches the remote_transmitter server there, waits for it to bind, then drives it with JSON-RPC over a ZMQ REQ/REP socket. + + Supported remote devices are the transmit-capable drivers: Pluto, USRP, HackRF, and BladeRF. + + set_radio must precede init_tx and transmit (both guard on a radio being set); the init_tx-before-transmit order is a usage convention, not an enforced guard; transmit runs in a daemon thread joined by wait_transmit. + } + + constraints { + SSH host-key policy is AutoAddPolicy, which accepts unknown hosts (security note). + + RIA Hub does not use this subpackage; remote and agent transmit is handled through the agent path instead. + + Known gap: transmit calls an SDR method tx_cw that no driver defines, so remote CW transmit currently no-ops for real drivers (the AttributeError is swallowed). + } + + decisions { + HostKeyAutoAdd { + Decision: SSH connections use paramiko AutoAddPolicy, accepting an unknown host key on first connect instead of requiring pre-provisioned known hosts. + + Scope: Governs how the controller establishes the SSH channel to the transmit host. + + Trade-offs: Removes manual known-hosts setup for ad-hoc transmit hosts at the cost of exposure to man-in-the-middle on the initial connection. + + Consequences: Host authenticity is not verified, so the SSH channel's integrity depends on the surrounding network being trusted. + } + } +} diff --git a/src/ria_toolkit_oss/sdr/sdr.sigil b/src/ria_toolkit_oss/sdr/sdr.sigil new file mode 100644 index 0000000..ec65374 --- /dev/null +++ b/src/ria_toolkit_oss/sdr/sdr.sigil @@ -0,0 +1,47 @@ +component SdrInterface { + goal { + Provide a unified receive and transmit API across a variety of software-defined radios. + + Own the SDR base contract, the per-device drivers, and device discovery and selection. + } + + interface { + DeviceDiscovery { + get_sdr_device(device_type, ident=None, tx=False) returns an SDR; mock and sim return a MockSDR, real devices delegate to the CLI package's factory. + + detect_available() returns the drivers whose optional dependency imports cleanly; it does not probe hardware. + } + + SdrContract { + SDR base class: record(num_samples, rx_time) and rx(num_samples) to receive, tx_recording(recording) to transmit, stream_to_zmq and pickle_buffer_to_zmq to stream, getters and setters for sample rate, center frequency, and gain, and capability probes for bias-tee and dynamic-update support. + } + + Drivers { + Drivers: Pluto, USRP, HackRF, and Blade (receive and transmit); RTLSDR and ThinkRF (receive only); MockSDR (AWGN generator, no hardware, receive and transmit). Real drivers are constructed with a device identifier; MockSDR takes a buffer size and seed. + } + + SdrErrors { + Errors: SDRError with SDRParameterError and SdrDisconnectedError (SDROverflowError is defined but not in the public __all__). + } + } +} + +expand SdrInterface { + logic { + init_rx or init_tx must be called before record or tx_recording (rx auto-initializes on first use); they push sample rate, center frequency, and gain to the hardware via per-driver setters. + + Receive accumulates validated buffers into a Recording; transmit loops or truncates the source IQ to the requested length. + + A driver is available only if its optional hardware dependency imports; USB or network drops are translated to SdrDisconnectedError. + } + + constraints { + gain_mode absolute applies the requested gain (clamped or snapped to the device's valid range); relative requires a negative (attenuation) value; ThinkRF uses named gain profiles instead. + + RTLSDR and ThinkRF are receive-only; their transmit methods raise or are stubs. + + Identifiers are device-specific free-form values (Pluto URI or IP, USRP serial or args, HackRF/BladeRF serial). + + RIA Hub consumes this layer through the SDR base contract and get_sdr_device but currently wires only Pluto and USRP live; the controller imports driver modules directly rather than only via the factory. + } +} diff --git a/src/ria_toolkit_oss/server/server.sigil b/src/ria_toolkit_oss/server/server.sigil new file mode 100644 index 0000000..4329b08 --- /dev/null +++ b/src/ria_toolkit_oss/server/server.sigil @@ -0,0 +1,63 @@ +component RtOssServer { + goal { + Expose the toolkit's campaign orchestration and live RF inference over HTTP as a standalone service (RT-OSS). + + Own the FastAPI app, its auth, and the deploy and inference endpoints. + } + + interface { + AppFactory { + create_app(api_key="") returns a FastAPI app mounting /conductor and /inference (both API-key gated) plus an unauthenticated GET /health; an empty api_key disables auth (dev only). + + serve() launches uvicorn from RT_OSS_API_KEY, RT_OSS_HOST (default 0.0.0.0), and RT_OSS_PORT (default 8080), and is the ria-server entry point; the ria serve CLI command is separate and calls create_app() directly. + } + + ConductorEndpoints { + Conductor endpoints: POST /conductor/deploy ({config}) returns {campaign_id} and runs the campaign in a background thread; GET /conductor/status/{campaign_id}; POST /conductor/cancel/{campaign_id}. + } + + InferenceEndpoints { + Inference endpoints: POST /inference/load (ONNX model plus label_map), POST /inference/start, POST /inference/stop, POST /inference/configure, GET /inference/status. + } + } +} + +expand RtOssServer { + logic { + A deploy parses the body via CampaignConfig.from_dict and rejects any transmitter carrying a script field (external scripts blocked). + + The inference loop captures 4096 IQ samples, estimates SNR, preprocesses to the model input shape, softmaxes, and maps the index to a label; idle-class labels are reported as idle. + + State is in-memory only (a campaign dict plus a single thread-locked inference state); nothing is persisted. + } + + constraints { + Auth is X-API-Key compared in constant time; a missing configured key allows all requests (dev only). + + Server dependencies (fastapi, uvicorn, onnxruntime) are an optional extra; a missing onnxruntime or SDR yields 503. + + RIA Hub's controller does not call this server; it embeds the toolkit library in-process. This server is the alternative standalone deployment. + + A deploy rejects any transmitter carrying a script field; external scripts are blocked. + + model_path is path-traversal validated and must resolve to a .onnx file. + } + + decisions { + StandaloneDeployment { + Decision: RT-OSS is packaged as a standalone HTTP service; RIA Hub's controller does not call it but embeds the toolkit library in-process instead. + + Scope: Governs how this server relates to the primary RIA Hub deployment. + + Consequences: The server carries its own auth, in-memory state, and process lifecycle rather than sharing the controller's, and exists as the alternative deployment for environments that want the toolkit behind HTTP. + } + + ScriptTransmitterRejection { + Decision: Deploy rejects any transmitter config carrying a script field, blocking external scripts. + + Scope: Governs the campaign config accepted by POST /conductor/deploy. + + Design issues addressed: Honoring a script field on a network-exposed, API-key-gated deploy endpoint would allow a caller to run arbitrary external commands on the server host. + } + } +} diff --git a/src/ria_toolkit_oss/signal/signal.sigil b/src/ria_toolkit_oss/signal/signal.sigil new file mode 100644 index 0000000..a68e44b --- /dev/null +++ b/src/ria_toolkit_oss/signal/signal.sigil @@ -0,0 +1,63 @@ +component SignalProcessing { + goal { + Provide the toolkit's signal generation and processing suite: functional waveform generators and a modular block-based modulation-chain framework. + + Own the DSP building blocks that produce Recording objects for datasets and transmission. + } + + interface { + FunctionalGenerators { + Functional generators returning a Recording: sine, square, sawtooth, noise, chirp, lfm_chirp_complex, complex_sine. + } + + BlockFramework { + Block framework: Block, SourceBlock, ProcessBlock, and RecordableBlock forming a DataType-typed chain, with sources (BinarySource, AWGNSource, SineSource, RecordingSource, ...), Mapper (PSK/QAM/PAM constellations; standalone APSK and cross-QAM mapper classes exist but are not reachable through Mapper) and SymbolDemapper, symbol modulators (GMSK, OOK, OQPSK), continuous-phase modulators (FSK, CPFSK), pulse-shaping filters (RaisedCosine, RootRaisedCosine, Gaussian, Sinc, Rect), Upsampling, channels (AWGNChannel, FlatRayleigh), and basic ops (Add, MultiplyConstant, PhaseShift, FrequencyShift, frequency up/down conversion). + } + + HighLevelGenerators { + High-level generators: PSKGenerator, QAMGenerator, and PAMGenerator, each with record(batch_size, num_bits). + } + + StandaloneSurface { + This layer is a standalone library surface; the RIA Hub controller does not import it directly. + } + } +} + +expand SignalProcessing { + logic { + A SignalGenerator validates that each block's output type matches the next block's input type; sample production is driven by the blocks themselves (Block and RecordableBlock via get_samples, and the PSK/QAM/PAM generators by chaining block __call__). + + Blocks auto-serialize their JSON-safe attributes into the produced Recording's metadata. + } + + constraints { + Supported modulations reachable via Mapper and the generators: PSK, QAM, PAM (constellation); GMSK, OOK, OQPSK (symbol); FSK and CPFSK (continuous). QAM and PAM require an even bits-per-symbol (QAM additionally more than 2). APSK and cross-QAM mapper classes exist but are unwired. + + The basic generators (sine, square, sawtooth, noise, complex_sine) raise on a sample rate below 1 (chirp instead requires at least two samples); FSK and CPFSK require frequency spacing times symbol duration of at least 0.5. + + Data flows as typed stages (bits, symbols, upsampled symbols, baseband, passband) via the DataType enum. + } + + decisions { + TypedBlockChain { + Decision: Model the modulation chain as DataType-typed blocks and validate that each block's output type matches the next block's input type. + + Scope: Governs the block framework and the SignalGenerator that assembles blocks; the functional generators bypass the chain. + + Design issues addressed: Connecting incompatible DSP stages (for example feeding symbols where baseband is expected) would otherwise fail silently or produce meaningless output. + + Consequences: Data flows as explicit typed stages (bits, symbols, upsampled symbols, baseband, passband) via the DataType enum. + } + + BlockMetadataProvenance { + Decision: Have blocks auto-serialize their JSON-safe attributes into the produced Recording's metadata. + + Scope: Governs metadata written by block-based generation. + + Design issues addressed: A generated Recording should carry the parameters that produced it so datasets are reproducible and self-describing. + + Assumptions: The block attributes relevant to reproduction are JSON-serializable. + } + } +} diff --git a/src/ria_toolkit_oss/transforms/transforms.sigil b/src/ria_toolkit_oss/transforms/transforms.sigil new file mode 100644 index 0000000..5b3d16b --- /dev/null +++ b/src/ria_toolkit_oss/transforms/transforms.sigil @@ -0,0 +1,47 @@ +component Transforms { + goal { + Provide NumPy radio-data transforms used by the ML backends: data augmentations and channel/hardware impairment models over IQ. + + Own the functions that manipulate a signal while preserving its container type. + } + + interface { + Augmentations { + Augmentations (iq_augmentations): generate_awgn, time_reversal, spectral_inversion, channel_swap, amplitude_reversal, drop_samples, quantize_tape, quantize_parts, magnitude_rescale, cut_out, patch_shuffle. + } + + Impairments { + Impairments (iq_impairments): add_awgn_to_signal, time_shift, frequency_shift, phase_shift, iq_imbalance, resample. + } + + TypePreservingContract { + Every function accepts an array or a Recording and returns the same type, preserving metadata for a Recording. + } + + StandaloneSurface { + This layer is a standalone library surface; the RIA Hub controller does not import it directly. + } + } +} + +expand Transforms { + constraints { + Input must be a 2-D complex channels-by-samples array or a ValueError is raised; most transforms implement only the single-channel path and raise NotImplementedError for more channels. + + frequency_shift is relative to the sample rate and must be within -0.5 to 0.5; phase_shift must be within -pi to pi. + + AWGN is generated to match a target SNR in dB. + } + + decisions { + TypePreservingTransforms { + Decision: Accept either a raw array or a Recording and return the same type, preserving metadata when the input is a Recording. + + Scope: Governs the call contract of every augmentation and impairment function. + + Design issues addressed: ML pipelines mix bare IQ arrays and Recording objects, and a transform must not strip a Recording's metadata as it passes through. + + Consequences: Callers can compose transforms without branching on input type or re-attaching metadata. + } + } +} diff --git a/src/ria_toolkit_oss_cli/cli.sigil b/src/ria_toolkit_oss_cli/cli.sigil new file mode 100644 index 0000000..582d386 --- /dev/null +++ b/src/ria_toolkit_oss_cli/cli.sigil @@ -0,0 +1,17 @@ +component ToolkitCli { + goal { + Provide the ria and ria-tools command-line interface over the toolkit's library features. + + Own the Click command group and its subcommands. + } + + interface { + CommandGroup { + A Click group that auto-registers the commands defined in ria_toolkit_oss_cli.ria_toolkit_oss.commands and warns when git-lfs is missing. + } + + CommandMap { + Commands map to library features: capture and transmit (sdr), campaign (orchestration), generate and synth (signal), transform/combine/split/convert (transforms, data, io), annotate (annotations), view (view and viz), discover (sdr), serve (the RT-OSS server), and upload/setup_repo/init (RIA Hub repo integration). + } + } +}