adds multiband and relay support

[Josephrp]

Title

Add multi-band listening and relay support

Summary

Adds simultaneous multi-band listening, orchestrator-centric message flow, reply-on-correct-band, and targeted relay (immediate and scheduled). Introduces a voice listener as the default capture path when audio is enabled, extends config/API for bands and relay, and adds a Settings page in the web UI.

What’s included

Multi-band listening

• Concurrent mode (default): one asyncio task per band; each calls monitor_frequency for that band’s center frequency. With multiple SDRs/receivers, listening is simultaneous.
• Single-receiver mode: one loop round-robins over bands with configurable listener_cycle_seconds.
• Bands from listen_bands or [default_band]; band listener runs when listener_enabled and at least one band is set.
• Received messages are stored with metadata.band, optionally injected, and by default published to the MessageBus for the orchestrator.

Orchestrator-centric flow

• All radio messages (band listener, receiver upload, inject) are published to the MessageBus as InboundMessage(channel="radio_rx", chat_id=band, ...).
• REACT runs per message; orchestrator gets inbound_metadata (band, frequency_hz, destination_callsign, mode) for relay and reply decisions.
• Skip flags: listener_skip_bus, receiver_upload_skip_bus, inject_skip_bus.

Reply on the correct band

• Outbound replies for channel="radio_rx" keep chat_id as the band. Outbound radio handler resolves frequency/mode from BAND_PLANS and calls radio_tx on that band.
• radio_reply_tx_enabled: false for listen-only.

Relay (targeted and scheduled)

• Immediate relay: POST /messages/relay stores source + relayed transcript; optional relay_inject_target_band / relay_tx_target_band for inject and/or TX on target band.
• Scheduled delivery: deliver_at (ISO datetime) in request body; relay delivery worker (when relay_scheduled_delivery_enabled) processes undelivered rows and injects/TXs then marks delivered.
• Orchestrator tool: relay_message_between_bands calls the same relay service; delivery is poll-based via GET /transcripts?callsign=X&destination_only=true&band=Y.

Voice listener (default capture)

• When audio_input_enabled and voice_listener_enabled, voice is the primary ingestion path: rig audio → ASR → segments published to MessageBus.
• Optional voice_store_transcript to also store voice segments as transcripts.

Callsigns and bands

• Registered callsigns support preferred_bands and last_band; bridge updates last_band from radio_rx; orchestrator context includes whitelisted_callsign_bands for relay targeting.

Config and API

• New schema/options for listener, relay, voice, bands (see config.schema, config.example.yaml, .env.example).
• API: GET /transcripts (callsign, band, destination_only), POST /messages/relay (optional deliver_at), GET/PATCH /callsigns/registered/... for bands, and config routes under /api/v1/config/*.

Other

• Setup/CLI: radioshaq setup extended (e.g. station callsign, trigger phrases, bands); radioshaq launch docker|pm2; radioshaq config show; infrastructure/local/setup.sh and setup.ps1 for full local setup.
• Web UI: Settings page for config/overrides; transcripts and API client updates for bands and relay.
• DB: Transcript storage with band; migrations for new columns; optional retention script.
• Docs: Configuration, quick-start, radio usage, API reference, reference .env.example and config.example.yaml; removed/archived interactive-setup-plan and PR-DESCRIPTION; MkDocs workflow and build updates.

Testing

• Unit: band_listener, relay_service, relay_tools, radio_rx / radio_rx_audio, outbound_radio, radio_ingestion, transcripts retention, callsign repo and new routes.
• Integration: orchestrator relay tool, transcripts relay.

Migration / compatibility

• New config keys have defaults; existing single-band setups keep working. Run migrations for transcript/band and any new columns.

---

Greptile Summary

This PR adds comprehensive multi-band listening and relay support to RadioShaq, introducing concurrent band monitoring, orchestrator-centric message flow, and targeted relay capabilities. The implementation is well-structured with proper separation of concerns, comprehensive testing, and database migrations.

Major changes:

• Multi-band listener runs concurrent tasks per band (or round-robin for single receiver), stores messages with metadata.band, and publishes to MessageBus
• Relay service stores source + relayed transcripts with proper metadata linking, supports immediate and scheduled delivery via deliver_at, and optionally injects/transmits on target band
• Orchestrator integration passes inbound_metadata (band, frequency, destination) to REACT loop and maintains whitelisted_callsign_bands context for relay decisions
• Reply routing preserves chat_id as band for radio_rx messages so outbound handler transmits on correct band using BAND_PLANS
• Voice listener runs as default capture path when audio enabled, publishes segments to MessageBus, and optionally stores transcripts with band metadata
• Database changes add band index on extra_data->>'band', preferred_bands/last_band columns, and relay delivery queries
• Config extensions add listener, relay, and voice options with proper validation; per-role LLM/memory overrides
• API additions include /messages/relay, /config/* routes, and band filtering on /transcripts
• Background workers for band listener, voice listener, relay delivery, and outbound radio handler with proper cleanup
• Comprehensive tests cover band listener, relay service, radio ingestion, outbound radio, and integration scenarios

Observations:

• The PR is quite large (89 files, ~5000 additions) which makes thorough review challenging - consider breaking similar features into smaller PRs
• SQL queries use safe parameterization with text().bindparams() to prevent injection
• Async task management properly handles cancellation and cleanup
• Error handling is generally robust with try/except blocks and logging
• Mode consistency: relay_delivery.py retrieves mode from transcript rather than using target band's mode from BAND_PLANS (minor style issue)

The implementation follows good architectural patterns with message bus integration, proper async patterns, and clean separation between storage, injection, and transmission paths.

Confidence Score: 4/5

• Safe to merge with minor style refinement suggested for mode consistency
• Score reflects comprehensive testing, clean architecture, and proper error handling, with minor deduction for PR size making exhaustive review difficult and one style consistency issue in relay_delivery.py
• radioshaq/radioshaq/listener/relay_delivery.py should align mode retrieval with relay_service.py for consistency

Important Files Changed

Filename	Overview
radioshaq/radioshaq/listener/band_listener.py	Implements concurrent multi-band listening with proper async task management and message processing
radioshaq/radioshaq/relay/service.py	Clean relay service implementation with proper band validation and optional inject/TX
radioshaq/radioshaq/listener/relay_delivery.py	Scheduled relay delivery worker with mode retrieval from transcript (should use target band mode)
radioshaq/radioshaq/orchestrator/outbound_radio.py	Outbound radio handler resolves band/frequency correctly and handles TX enablement flag
radioshaq/radioshaq/database/postgres_gis.py	Adds band filtering, relay delivery queries, and callsign band tracking with safe SQL parameterization
radioshaq/radioshaq/api/routes/relay.py	Relay endpoint with proper validation, callsign whitelist checks, and deliver_at support
radioshaq/radioshaq/specialized/relay_tools.py	LLM-callable relay tool with validation, error handling, and callsign authorization checks
radioshaq/radioshaq/orchestrator/react_loop.py	Extends orchestrator with inbound_metadata and whitelisted_callsign_bands context for relay decisions
radioshaq/radioshaq/orchestrator/bridge.py	Updates last_band for radio_rx senders and passes reply_band metadata for correct TX routing
radioshaq/radioshaq/config/schema.py	Adds comprehensive multi-band, relay, and voice listener config options with proper validation
radioshaq/radioshaq/api/server.py	Starts band listener, voice listener, relay delivery, and outbound radio handler with proper cleanup
radioshaq/radioshaq/specialized/radio_rx_audio.py	Extends voice RX to publish to MessageBus and optionally store transcripts with band metadata

Sequence Diagram

sequenceDiagram
    participant BandListener as Band Listener
    participant RadioRX as Radio RX Agent
    participant Storage as Transcript Storage
    participant MessageBus as Message Bus
    participant Orchestrator as REACT Orchestrator
    participant RelayTool as Relay Tool
    participant OutboundRadio as Outbound Radio Handler
    participant RadioTX as Radio TX Agent

    Note over BandListener,RadioRX: Multi-band Listening
    BandListener->>RadioRX: monitor_frequency(band, freq, mode)
    RadioRX-->>BandListener: messages
    BandListener->>Storage: store(band=40m, metadata)
    BandListener->>MessageBus: publish_inbound(channel=radio_rx, chat_id=band)
    
    Note over MessageBus,Orchestrator: Orchestrator Processing
    MessageBus->>Orchestrator: consume_inbound()
    Orchestrator->>Orchestrator: process_request(inbound_metadata={band, freq})
    Orchestrator->>RelayTool: relay_message_between_bands(source_band=40m, target_band=2m)
    
    Note over RelayTool,Storage: Relay Service
    RelayTool->>Storage: store(source: band=40m, relay_role=source)
    RelayTool->>Storage: store(relayed: band=2m, relay_role=relayed, deliver_at)
    RelayTool-->>Orchestrator: relay result
    
    Orchestrator->>MessageBus: publish_outbound(channel=radio_rx, chat_id=band, reply_band)
    
    Note over OutboundRadio,RadioTX: Outbound Reply
    MessageBus->>OutboundRadio: consume_outbound()
    OutboundRadio->>OutboundRadio: resolve freq/mode from band BAND_PLANS
    OutboundRadio->>RadioTX: execute(freq, message, mode)
    RadioTX-->>OutboundRadio: transmitted

Loading

_{Last reviewed commit: 7e185b2}