ben
1a8bfb2c51
All checks were successful
Build Sphinx Docs Set / Build Docs (pull_request) Successful in 22s
Build Project / Build Project (3.10) (pull_request) Successful in 1m10s
Build Project / Build Project (3.11) (pull_request) Successful in 1m5s
Build Project / Build Project (3.12) (pull_request) Successful in 1m2s
Test with tox / Test with tox (3.11) (pull_request) Successful in 9m17s
Test with tox / Test with tox (3.10) (pull_request) Successful in 14m19s
Test with tox / Test with tox (3.12) (pull_request) Successful in 8m56s
60 lines
3.0 KiB
Plaintext
60 lines
3.0 KiB
Plaintext
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.
|
|
}
|
|
}
|
|
}
|