|
1 | 1 | # RadioShaq |
2 | 2 |
|
3 | | -RadioShaq for RadioShaq: ham radio AI orchestration and remote SDR reception. |
| 3 | +Monorepo for **RadioShaq**: ham radio AI orchestration and remote SDR reception. One main app (single PyPI package); Python is managed with [uv](https://github.com/astral-sh/uv). |
4 | 4 |
|
5 | | -**PyPI long description:** [.github/PYPI_README.md](PYPI_README.md) is a user-facing README for the package (interactive setup, CLI, quick start). To use it as the PyPI project description, set `readme = "../.github/PYPI_README.md"` in `radioshaq/pyproject.toml` when building from the repo root, or copy its contents into `radioshaq/README.md` before publishing. |
| 5 | +**What this repo does** |
6 | 6 |
|
7 | | -**Published code in this repo:** |
| 7 | +- **RadioShaq** — AI-powered orchestrator for ham radio, emergency comms, and field–HQ coordination. FastAPI backend, React (Vite) web UI, Postgres + Alembic, optional real radios and SDR. The **remote receiver** (SDR listen-only station) is bundled; run with `radioshaq run-receiver`. |
8 | 8 |
|
9 | | -- **[radioshaq/](radioshaq/)** — RadioShaq (formerly SHAKODS): AI-powered orchestrator for ham radio, emergency comms, and field–HQ coordination. Includes the **remote receiver** (SDR listen-only station) as `radioshaq.remote_receiver`; run with `radioshaq run-receiver`. |
| 9 | +--- |
| 10 | + |
| 11 | +## Prerequisites |
10 | 12 |
|
11 | | -The directories `codex/`, `mistral-vibe-main/`, and `nanobot-main/` are **reference-only** and are not part of the published codebase; they are listed in `.gitignore`. |
| 13 | +- **Python 3.11+** and **[uv](https://github.com/astral-sh/uv)** |
| 14 | +- **PostgreSQL** — Easiest is Docker on port 5434 (avoids conflict with local 5432). Or use an existing server and set `RADIOSHAQ_DATABASE__POSTGRES_URL`. |
| 15 | +- **Optional:** Node.js + PM2 for running the API under PM2; Docker for Postgres. |
12 | 16 |
|
13 | 17 | --- |
14 | 18 |
|
15 | | -## Quick start (main app) |
| 19 | +## Launch (choose one path) |
| 20 | + |
| 21 | +All steps below assume you are in **radioshaq/** unless noted. |
16 | 22 |
|
17 | | -From the `radioshaq/` directory: |
| 23 | +### Option A: Interactive setup (recommended first time) |
| 24 | + |
| 25 | +Guided prompts for mode, database (Docker or URL), JWT, LLM, and optional radio/memory. Writes `.env` and `config.yaml`, can start Docker and run migrations. |
18 | 26 |
|
19 | 27 | ```bash |
20 | | -# 1. Install |
21 | | -uv sync --extra dev --extra test |
| 28 | +cd radioshaq |
| 29 | +uv sync --all-extras |
| 30 | +radioshaq setup |
| 31 | +# Minimal: radioshaq setup --quick |
| 32 | +# CI: radioshaq setup --no-input --mode field |
| 33 | +``` |
| 34 | + |
| 35 | +Then start the API (see Option D or manual steps below). |
| 36 | + |
| 37 | +### Option B: Full automated setup (Windows / Linux) |
22 | 38 |
|
23 | | -# 2. Start Postgres (Docker, port 5434) |
| 39 | +One script: install deps, create config, start Docker Postgres (port 5434), run migrations, install PM2 if Node is present. |
| 40 | + |
| 41 | +```powershell |
| 42 | +# Windows (from radioshaq/) |
| 43 | +.\infrastructure\local\setup.ps1 |
| 44 | +``` |
| 45 | + |
| 46 | +```bash |
| 47 | +# Linux/macOS (from radioshaq/) |
| 48 | +./infrastructure/local/setup.sh |
| 49 | +``` |
| 50 | + |
| 51 | +Then start the API with `radioshaq launch pm2` or `radioshaq run-api`. |
| 52 | + |
| 53 | +### Option C: Manual step-by-step |
| 54 | + |
| 55 | +```bash |
| 56 | +cd radioshaq |
| 57 | +uv sync --all-extras |
| 58 | + |
| 59 | +# Start Postgres (port 5434) |
24 | 60 | cd infrastructure/local && docker compose up -d postgres && cd ../.. |
25 | 61 |
|
26 | | -# 3. Migrations |
| 62 | +# Migrations (from radioshaq/) |
27 | 63 | uv run alembic -c infrastructure/local/alembic.ini upgrade head |
28 | 64 |
|
29 | | -# 4. Start API |
| 65 | +# Start API |
30 | 66 | uv run python -m radioshaq.api.server |
31 | | -# API: http://localhost:8000/docs |
32 | 67 | ``` |
33 | 68 |
|
34 | | -Full install and usage: see the main app [README.md](radioshaq/README.md) in that directory. |
| 69 | +From **repo root**, Postgres and migrations can be run as: |
| 70 | + |
| 71 | +```bash |
| 72 | +cd radioshaq/infrastructure/local && docker compose up -d postgres && cd ../../.. |
| 73 | +python radioshaq/infrastructure/local/run_alembic.py upgrade head |
| 74 | +``` |
| 75 | + |
| 76 | +### Option D: Launch CLI (after install) |
| 77 | + |
| 78 | +Start dependencies and API in one go: |
| 79 | + |
| 80 | +```bash |
| 81 | +# Postgres only (port 5434) |
| 82 | +radioshaq launch docker |
| 83 | +# With Hindsight (semantic memory): radioshaq launch docker --hindsight |
| 84 | + |
| 85 | +# Postgres + API under PM2 |
| 86 | +radioshaq launch pm2 |
| 87 | +# With Hindsight: radioshaq launch pm2 --hindsight |
| 88 | +``` |
| 89 | + |
| 90 | +Then run migrations if needed: `uv run alembic -c infrastructure/local/alembic.ini upgrade head` from `radioshaq/`. |
| 91 | + |
| 92 | +**Endpoints:** API docs **http://localhost:8000/docs**, web UI **http://localhost:8000/**, health **http://localhost:8000/health**. |
35 | 93 |
|
36 | 94 | --- |
37 | 95 |
|
38 | | -## Project structure |
| 96 | +## Usage |
39 | 97 |
|
| 98 | +### Get a JWT |
| 99 | + |
| 100 | +Most endpoints require a Bearer JWT. Request a token (no prior auth in dev), then send it on protected routes. |
| 101 | + |
| 102 | +**PowerShell:** |
| 103 | + |
| 104 | +```powershell |
| 105 | +$r = Invoke-RestMethod -Method Post -Uri "http://localhost:8000/auth/token?subject=op1&role=field&station_id=STATION-01" |
| 106 | +$env:TOKEN = $r.access_token |
| 107 | +Invoke-RestMethod -Uri "http://localhost:8000/auth/me" -Headers @{ Authorization = "Bearer $env:TOKEN" } |
40 | 108 | ``` |
41 | | -radioshaq/ # Main RadioShaq application (single PyPI package) |
42 | | -├── radioshaq/ # Python package (API, radio, audio, orchestrator) |
43 | | -│ └── remote_receiver/ # Bundled SDR receiver (run-receiver) |
44 | | -├── web-interface/ # React frontend (Vite + TypeScript) |
45 | | -├── tests/ # pytest suite (unit + integration + remote_receiver) |
46 | | -├── infrastructure/ # Docker, PM2, AWS Lambda, Alembic |
47 | | -└── scripts/ # Demo and utility scripts |
48 | 109 |
|
49 | | -docs/ # Implementation plans and hardware notes |
50 | | -codex/ # Reference-only (gitignored) |
51 | | -mistral-vibe-main/ # Reference-only (gitignored) |
52 | | -nanobot-main/ # Reference-only (gitignored) |
| 110 | +**Bash:** |
| 111 | + |
| 112 | +```bash |
| 113 | +TOKEN=$(curl -s -X POST "http://localhost:8000/auth/token?subject=op1&role=field&station_id=STATION-01" | jq -r .access_token) |
| 114 | +curl -H "Authorization: Bearer $TOKEN" http://localhost:8000/auth/me |
53 | 115 | ``` |
54 | 116 |
|
| 117 | +Roles: `field`, `hq`, `receiver`. Set `RADIOSHAQ_TOKEN` to use the CLI below. |
| 118 | + |
| 119 | +### CLI (with API running) |
| 120 | + |
| 121 | +| Command | Description | |
| 122 | +|--------|-------------| |
| 123 | +| `radioshaq token --subject op1 --role field --station-id STATION-01` | Get JWT (then set `RADIOSHAQ_TOKEN`) | |
| 124 | +| `radioshaq health` | Liveness; `radioshaq health --ready` for readiness | |
| 125 | +| `radioshaq message process "your request"` | Send message through REACT orchestrator | |
| 126 | +| `radioshaq message inject "text"` | Inject into RX path (demo). Options: `--band`, `--source-callsign` | |
| 127 | +| `radioshaq message relay "msg" --source-band 40m --target-band 2m` | Relay between bands | |
| 128 | +| `radioshaq transcripts list` | List transcripts. Options: `--callsign`, `--band`, `--destination-only` | |
| 129 | +| `radioshaq callsigns list` | List registered callsigns | |
| 130 | +| `radioshaq callsigns add <callsign>` | Register a callsign | |
| 131 | + |
| 132 | +API base URL: `RADIOSHAQ_API` (default `http://localhost:8000`). Use `radioshaq --help` and `radioshaq <command> --help` for options. |
| 133 | + |
| 134 | +### Demo script |
| 135 | + |
| 136 | +With the API running, in a second terminal from **radioshaq/**: |
| 137 | + |
| 138 | +```bash |
| 139 | +uv run python scripts/demo/run_demo.py |
| 140 | +``` |
| 141 | + |
| 142 | +Gets a token, injects on 40m, relays to 2m, and polls `/transcripts`. See [radioshaq/scripts/demo/README.md](radioshaq/scripts/demo/README.md). |
| 143 | + |
| 144 | +### API calls |
| 145 | + |
| 146 | +- **Process a message:** `POST /messages/process` with JSON `{"message": "your request"}` and header `Authorization: Bearer <token>`. |
| 147 | +- **Transcripts:** `GET /transcripts?callsign=<callsign>&destination_only=true&band=<band>` for messages for you on a band. |
| 148 | +- See **http://localhost:8000/docs** for the full OpenAPI spec. |
| 149 | + |
55 | 150 | --- |
56 | 151 |
|
57 | | -## Development |
| 152 | +## Run the remote receiver |
| 153 | + |
| 154 | +From **radioshaq/** (SDR listen-only station streaming to HQ): |
58 | 155 |
|
59 | 156 | ```bash |
60 | | -# Run tests |
61 | | -cd radioshaq |
62 | | -uv run pytest tests/unit tests/integration -v |
| 157 | +uv sync --extra dev --extra test |
| 158 | +# With hardware: uv sync --extra sdr # or --extra hackrf |
63 | 159 |
|
64 | | -# Type check |
65 | | -uv run mypy radioshaq |
| 160 | +# Set env then run |
| 161 | +# JWT_SECRET=... STATION_ID=RECEIVER-01 HQ_URL=http://your-hq:8000 |
| 162 | +uv run radioshaq run-receiver |
| 163 | +``` |
| 164 | + |
| 165 | +Default port **8765**. HQ accepts uploads at `POST /receiver/upload`. See [docs/](docs/) and [radioshaq/README.md](radioshaq/README.md). |
| 166 | + |
| 167 | +--- |
| 168 | + |
| 169 | +## Development (uv) |
| 170 | + |
| 171 | +All from **radioshaq/**: |
66 | 172 |
|
67 | | -# Lint / format |
| 173 | +```bash |
| 174 | +uv run pytest tests/unit tests/integration -v |
| 175 | +uv run mypy radioshaq |
68 | 176 | uv run ruff check . && uv run ruff format . |
| 177 | +uv run alembic -c infrastructure/local/alembic.ini upgrade head |
| 178 | +``` |
| 179 | + |
| 180 | +Frontend: `cd web-interface && npm install && npm run dev`. |
| 181 | + |
| 182 | +--- |
| 183 | + |
| 184 | +## Documentation |
| 185 | + |
| 186 | +| Doc | Description | |
| 187 | +|-----|-------------| |
| 188 | +| [docs/quick-start.md](docs/quick-start.md) | Step-by-step first run | |
| 189 | +| [docs/configuration.md](docs/configuration.md) | Config file, env vars, interactive setup | |
| 190 | +| [docs/radio-usage.md](docs/radio-usage.md) | Rig models, CAT, hardware | |
| 191 | +| [docs/api-reference.md](docs/api-reference.md) | API overview | |
| 192 | +| [radioshaq/README.md](radioshaq/README.md) | App install, auth, demo, monitoring | |
| 193 | + |
| 194 | +--- |
| 195 | + |
| 196 | +## Project structure |
| 197 | + |
| 198 | +``` |
| 199 | +radioshaq/ # Main application (single PyPI package) |
| 200 | +├── radioshaq/ # Python package (API, radio, audio, orchestrator) |
| 201 | +│ └── remote_receiver/ # Bundled SDR receiver (radioshaq run-receiver) |
| 202 | +├── web-interface/ # React frontend (Vite + TypeScript) |
| 203 | +├── tests/ # pytest (unit + integration) |
| 204 | +├── infrastructure/ # Docker, PM2, AWS Lambda, Alembic |
| 205 | +└── scripts/ # Demo and utilities |
| 206 | +
|
| 207 | +docs/ # Quick-start, configuration, snippets |
| 208 | +.github/ # Workflows, PYPI_README.md |
69 | 209 | ``` |
70 | 210 |
|
71 | 211 | --- |
|
0 commit comments