Skip to content

Commit 732b14f

Browse files
JosephrpJosephrp
authored
Enforce main <- dev governance, migrate to GPL-2.0-only, add CLI/UI license gates, and split stable/nightly PyPI release lanes (#16)
* adds docs site and ci docs build * Stop tracking ancient-docs (reference-only, in .gitignore) * Ignore site/ (MkDocs build output), stop tracking * resolves url , site/ ignore and uv install security * adds dashboard * removes stray md * adds memory system * adds memory system (#6) * adds memory system * fix failing tests in ci * fix failing tests in ci * adds trusted publisher * adds multiband and relay support * adds multiband and relay support (#7) * adds multiband and relay support * Update radioshaq/radioshaq/listener/relay_delivery.py * update tests * adds dbstate __getattr__ * docs ci update pinned mkdocs version * adds radio frequency * adds radio outbound reply default * adds ci test on pr * solves frequency and send tx race conditions * fixes pending entries & mode clobbering (fm) * fixes configuration hardcoded path and fixed reject path misleading error , cleans up pending list api semantics * resolves code review issues * Add frequency-aware radio replies (#8) * adds radio frequency * adds radio outbound reply default * adds ci test on pr * solves frequency and send tx race conditions * fixes pending entries & mode clobbering (fm) * fixes configuration hardcoded path and fixed reject path misleading error , cleans up pending list api semantics * resolves code review issues * adds ci fixes * Update radioshaq/radioshaq/api/routes/messages.py * solves code review suggestions * fixes failing tests * Fixes PyPI UI bundling flow (#12) * adds radio frequency * adds radio outbound reply default * adds ci test on pr * solves frequency and send tx race conditions * fixes pending entries & mode clobbering (fm) * fixes configuration hardcoded path and fixed reject path misleading error , cleans up pending list api semantics * resolves code review issues * adds ci fixes * Update radioshaq/radioshaq/api/routes/messages.py * solves code review suggestions * fixes failing tests * fixes build patch * fixes minor issues * fixes build env bug (#13) * adds radio frequency * adds radio outbound reply default * adds ci test on pr * solves frequency and send tx race conditions * fixes pending entries & mode clobbering (fm) * fixes configuration hardcoded path and fixed reject path misleading error , cleans up pending list api semantics * resolves code review issues * adds ci fixes * Update radioshaq/radioshaq/api/routes/messages.py * solves code review suggestions * fixes failing tests * fixes build patch * fixes minor issues * fixes ci issue * Update radioshaq/tests/integration/test_live_e2e_workflows.py * fixes ci issue (#14) * adds radio frequency * adds radio outbound reply default * adds ci test on pr * solves frequency and send tx race conditions * fixes pending entries & mode clobbering (fm) * fixes configuration hardcoded path and fixed reject path misleading error , cleans up pending list api semantics * resolves code review issues * adds ci fixes * Update radioshaq/radioshaq/api/routes/messages.py * solves code review suggestions * fixes failing tests * fixes build patch * fixes minor issues * fixes ci issue * Update radioshaq/tests/integration/test_live_e2e_workflows.py * Fix settings TS build and include web UI in wheel * adds release , versioning and workflows * adds ci , build , enfore branch protection and more * adds contributing * chore: bump version to 0.1.1 * fix(ci): allow non-interactive GPL acceptance in CLI setup tests * fix(ci): harden publish/governance workflows and refresh action versions * Fix CI branch guards, release push race handling, and license/version checks * adds contributing * adds validation fixes
1 parent f92ebaa commit 732b14f

178 files changed

Lines changed: 18062 additions & 1254 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.githooks/pre-push‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
#!/usr/bin/env bash
2+
set -euo pipefail
3+
4+
repo_root="$(git rev-parse --show-toplevel)"
5+
cd "$repo_root"
6+
7+
echo "[pre-push] Validating version synchronization..."
8+
python radioshaq/scripts/check_version_sync.py
9+
10+
echo "[pre-push] Installing/syncing test dependencies..."
11+
cd radioshaq
12+
uv sync --extra dev --extra test --extra sdr
13+
14+
echo "[pre-push] Running unit + integration tests..."
15+
uv run pytest tests/unit tests/integration -v
16+
17+
echo "[pre-push] All checks passed."

‎.github/PYPI_README.md‎

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
# RadioShaq
2+
3+
**S**trategic **H**am **R**adio **A**utonomous **Q**uery and **K**ontrol System
4+
5+
An AI-powered orchestrator for ham radio operations, emergency communications, and field-to-HQ coordination. One install gives you the API, web UI, and optional remote SDR receiver.
6+
7+
---
8+
9+
## Install
10+
11+
```bash
12+
pip install radioshaq
13+
```
14+
15+
**Optional (for SDR hardware):** `pip install radioshaq[sdr]` (RTL-SDR) or `radioshaq[hackrf]` (HackRF).
16+
17+
**Requirements:** Python 3.11+
18+
19+
**License notice:** RadioShaq is distributed under GPL-2.0-only. Official CLI and web UI require explicit license acceptance before normal use.
20+
21+
---
22+
23+
## Easiest way to get started: interactive setup
24+
25+
From a project directory (or the repo root), run:
26+
27+
```bash
28+
radioshaq setup
29+
```
30+
31+
This walks you through:
32+
33+
- **Mode** — field, hq, or receiver
34+
- **Database** — use Docker Postgres or an existing URL
35+
- **Secrets** — JWT secret, LLM API key (optional)
36+
- **Config** — writes `.env` and `config.yaml`, can start Docker and run migrations
37+
38+
**Minimal prompts:** `radioshaq setup --quick` (mode + “use Docker?” then defaults).
39+
40+
**Non-interactive (CI/scripts):** `radioshaq setup --no-input --mode field` (optionally `--db-url postgresql://...`).
41+
42+
**Reconfigure:** `radioshaq setup --reconfigure` to update existing config without starting over.
43+
44+
---
45+
46+
## Run the API and web UI
47+
48+
```bash
49+
radioshaq run-api
50+
```
51+
52+
- **API docs:** http://localhost:8000/docs
53+
- **Web UI:** http://localhost:8000/
54+
- **Health:** http://localhost:8000/health
55+
56+
Default host: `0.0.0.0`, port: `8000`. Override with `--host` and `--port`.
57+
58+
---
59+
60+
## Get a token (auth)
61+
62+
Most API calls need a Bearer JWT:
63+
64+
```bash
65+
radioshaq token --subject op1 --role field --station-id STATION-01
66+
```
67+
68+
Then set `RADIOSHAQ_TOKEN` to the printed value, or pass it in requests. Roles: `field`, `hq`, `receiver`.
69+
70+
**Check API from the CLI:**
71+
72+
```bash
73+
radioshaq health
74+
radioshaq health --ready
75+
```
76+
77+
---
78+
79+
## CLI at a glance
80+
81+
| Command | What it does |
82+
|--------|------------------|
83+
| **setup** | |
84+
| `radioshaq setup` | Interactive setup: .env, config.yaml, optional Docker and migrations |
85+
| `radioshaq setup --quick` | Minimal prompts (mode, use Docker?), then defaults |
86+
| `radioshaq setup --no-input --mode field` | Non-interactive for CI; optional `--db-url`, `--config-dir` |
87+
| `radioshaq setup --reconfigure` | Update existing config (merge sections) |
88+
| **Server & auth** | |
89+
| `radioshaq run-api` | Start FastAPI server (and web UI at /). Options: `--host`, `--port`, `--reload` |
90+
| `radioshaq run-receiver` | Start remote SDR receiver (port 8765). Set `JWT_SECRET`, `STATION_ID`, `HQ_URL` |
91+
| `radioshaq token` | Get JWT. Options: `--subject`, `--role`, `--station-id`, `--base-url` |
92+
| `radioshaq health` | Liveness check; `radioshaq health --ready` for readiness |
93+
| **Callsigns** (require `RADIOSHAQ_TOKEN`) | |
94+
| `radioshaq callsigns list` | List registered callsigns |
95+
| `radioshaq callsigns add <callsign>` | Register a callsign |
96+
| `radioshaq callsigns remove <callsign>` | Remove from whitelist |
97+
| `radioshaq callsigns register-from-audio <file>` | Register from audio (ASR) |
98+
| **Messages** | |
99+
| `radioshaq message process <text>` | Send message through REACT orchestrator |
100+
| `radioshaq message inject <text>` | Inject into RX path (demo). Options: `--band`, `--mode`, `--source-callsign` |
101+
| `radioshaq message whitelist-request <text>` | Whitelist request (orchestrator + optional TTS) |
102+
| `radioshaq message relay <msg> --source-band X --target-band Y` | Relay message between bands |
103+
| **Transcripts** | |
104+
| `radioshaq transcripts list` | List transcripts. Options: `--callsign`, `--band`, `--since`, `--limit` |
105+
| `radioshaq transcripts get <id>` | Get one transcript |
106+
| `radioshaq transcripts play <id>` | Play transcript as TTS over radio |
107+
| **Radio** | |
108+
| `radioshaq radio bands` | List bands |
109+
| `radioshaq radio send-tts <message>` | Send TTS over radio. Options: `--frequency-hz`, `--mode` |
110+
111+
Use `radioshaq --help` and `radioshaq <command> --help` for options. API base URL: `RADIOSHAQ_API` (default `http://localhost:8000`).
112+
113+
---
114+
115+
## Remote receiver (SDR listen-only)
116+
117+
For a listen-only station (e.g. Raspberry Pi + RTL-SDR) that streams to HQ:
118+
119+
```bash
120+
pip install radioshaq[sdr] # or radioshaq[hackrf] for HackRF
121+
export JWT_SECRET=your-secret
122+
export STATION_ID=RECEIVER-01
123+
export HQ_URL=http://your-hq:8000
124+
radioshaq run-receiver
125+
```
126+
127+
HQ accepts uploads at `POST /receiver/upload` (Bearer JWT). Default receiver port: `8765` (`--port` to change).
128+
129+
---
130+
131+
## After install (no interactive setup)
132+
133+
If you prefer to configure by hand:
134+
135+
1. **Database:** Set `DATABASE_URL` or `POSTGRES_*` (and run migrations with your Alembic config).
136+
2. **Config:** Copy `config.example.yaml` to `config.yaml` and set `mode`, `database`, `auth`, etc. See [Configuration](https://Josephrp.github.io/RadioShaq/configuration/).
137+
3. **Start:** `radioshaq run-api`.
138+
139+
---
140+
141+
## Documentation
142+
143+
- [Quick Start](https://Josephrp.github.io/RadioShaq/quick-start/)
144+
- [Configuration](https://Josephrp.github.io/RadioShaq/configuration/)
145+
- [API Reference](https://Josephrp.github.io/RadioShaq/api-reference/)
146+
- [Radio / hardware](https://Josephrp.github.io/RadioShaq/radio-usage/)
147+
148+
---
149+
150+
## License
151+
152+
GPL-2.0-only

README.md renamed to .github/README.md

Lines changed: 11 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,12 @@
11
# RadioShaq
22

3-
Monorepo for RadioShaq: ham radio AI orchestration and remote SDR reception.
3+
RadioShaq for RadioShaq: ham radio AI orchestration and remote SDR reception.
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.
46

57
**Published code in this repo:**
68

7-
- **[radioshaq/](radioshaq/)** — RadioShaq (formerly SHAKODS): AI-powered orchestrator for ham radio, emergency comms, and field–HQ coordination.
8-
- **[remote_receiver/](remote_receiver/)** — Remote SDR receiver station (RTL-SDR / HackRF) with JWT auth and HQ upload.
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`.
910

1011
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`.
1112

@@ -37,18 +38,15 @@ Full install and usage: see the main app [README.md](radioshaq/README.md) in tha
3738
## Project structure
3839

3940
```
40-
radioshaq/ # Main RadioShaq application
41+
radioshaq/ # Main RadioShaq application (single PyPI package)
4142
├── radioshaq/ # Python package (API, radio, audio, orchestrator)
42-
├── web-interface/ # React frontend (Vite + TypeScript)
43-
├── tests/ # pytest suite (unit + integration)
44-
├── infrastructure/ # Docker, PM2, AWS Lambda, Alembic
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
4547
└── scripts/ # Demo and utility scripts
4648
47-
remote_receiver/ # Remote SDR receiver station
48-
├── receiver/ # FastAPI server for SDR data
49-
└── pyproject.toml # Separate uv project
50-
51-
docs/ # Implementation plans and hardware notes
49+
docs/ # Implementation plans and hardware notes
5250
codex/ # Reference-only (gitignored)
5351
mistral-vibe-main/ # Reference-only (gitignored)
5452
nanobot-main/ # Reference-only (gitignored)
@@ -74,4 +72,4 @@ uv run ruff check . && uv run ruff format .
7472

7573
## License
7674

77-
MIT
75+
GPL-2.0-only

‎.github/mkdocs.yml‎

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
# RadioShaq documentation — MkDocs Material
2+
# Config lives in .github/; paths are relative to this file.
3+
# Build: mkdocs build -f .github/mkdocs.yml (from repo root). Deploy: GitHub Actions.
4+
site_name: RadioShaq
5+
site_description: Ham Radio AI Orchestration and Field-to-HQ Coordination
6+
site_url: https://josephrp.github.io/radioshaq/
7+
8+
docs_dir: ../docs
9+
site_dir: ../site
10+
11+
theme:
12+
name: material
13+
language: en
14+
palette:
15+
# Light mode (default) — Lakers: blue + gold/yellow
16+
- scheme: default
17+
primary: blue
18+
accent: amber
19+
toggle:
20+
icon: material/brightness-7
21+
name: Switch to dark mode
22+
# Dark mode
23+
- scheme: slate
24+
primary: blue
25+
accent: amber
26+
toggle:
27+
icon: material/brightness-4
28+
name: Switch to light mode
29+
features:
30+
- navigation.instant
31+
- navigation.instant.prefetch
32+
- navigation.instant.progress
33+
- navigation.tabs
34+
- navigation.tabs.sticky
35+
- navigation.path
36+
- content.tabs.link
37+
- content.code.copy
38+
- content.code.select
39+
- content.code.annotate
40+
- toc.follow
41+
42+
markdown_extensions:
43+
- pymdownx.highlight:
44+
anchor_linenums: true
45+
line_spans: __span
46+
pygments_lang_class: true
47+
- pymdownx.inlinehilite
48+
- pymdownx.snippets:
49+
# Resolved from cwd (run mkdocs from repo root). docs/ and radioshaq/ for snippet includes.
50+
base_path: [docs, ., radioshaq]
51+
check_paths: true
52+
- pymdownx.superfences
53+
- pymdownx.tabbed:
54+
alternate_style: true
55+
slugify: !!python/object/apply:pymdownx.slugs.slugify
56+
kwds:
57+
case: lower
58+
59+
plugins:
60+
- search
61+
- git-revision-date-localized:
62+
type: date
63+
timezone: UTC
64+
locale: en
65+
fallback_to_build_date: true
66+
- neoteroi.mkdocsoad:
67+
use_pymdownx: true
68+
69+
# optional: add docs/stylesheets/mkdocsoad.css from neoteroi/mkdocs-plugins releases for OAD styling
70+
# extra_css:
71+
# - stylesheets/mkdocsoad.css
72+
73+
nav:
74+
- About: index.md
75+
- Quick Start: quick-start.md
76+
- Radio Usage: radio-usage.md
77+
- Configuration: configuration.md
78+
- Monitoring: monitoring.md
79+
- API Reference: api-reference.md

‎.github/workflows/build-docs.yml‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Build and deploy documentation (manual only). Tests run first; then MkDocs build; then deploy to GitHub Pages.
2+
name: Build and deploy documentation
3+
4+
on:
5+
workflow_dispatch:
6+
7+
permissions:
8+
contents: read
9+
10+
jobs:
11+
test:
12+
name: Test
13+
runs-on: ubuntu-latest
14+
steps:
15+
- uses: actions/checkout@v6
16+
- uses: actions/setup-python@v6
17+
with:
18+
python-version: "3.11"
19+
- uses: astral-sh/setup-uv@v7
20+
- name: Run tests
21+
run: |
22+
cd radioshaq && \
23+
uv sync --extra dev --extra test && \
24+
uv run pytest tests/unit tests/integration -v
25+
26+
build-docs:
27+
name: Build docs
28+
needs: test
29+
runs-on: ubuntu-latest
30+
steps:
31+
- uses: actions/checkout@v6
32+
with:
33+
fetch-depth: 0 # full history for git-revision-date-localized-plugin
34+
- uses: actions/setup-python@v6
35+
with:
36+
python-version: "3.11"
37+
- uses: astral-sh/setup-uv@v7
38+
- name: Install doc dependencies
39+
run: pip install --no-cache-dir -r docs/requirements.txt
40+
- name: MkDocs version
41+
run: mkdocs --version
42+
- name: Install radioshaq (for OpenAPI export)
43+
run: uv sync --directory radioshaq
44+
- name: Export OpenAPI
45+
run: uv run --directory radioshaq python scripts/export_openapi.py
46+
- name: Sync config examples into docs
47+
run: |
48+
mkdir -p docs/reference
49+
cp radioshaq/.env.example docs/reference/.env.example
50+
cp radioshaq/config.example.yaml docs/reference/config.example.yaml
51+
- name: Build MkDocs
52+
run: mkdocs build -f .github/mkdocs.yml
53+
- name: Upload GitHub Pages artifact
54+
uses: actions/upload-pages-artifact@v4
55+
with:
56+
path: site
57+
58+
deploy:
59+
name: Deploy to GitHub Pages
60+
needs: build-docs
61+
runs-on: ubuntu-latest
62+
environment:
63+
name: github-pages
64+
url: ${{ steps.deployment.outputs.page_url }}
65+
permissions:
66+
pages: write
67+
id-token: write
68+
steps:
69+
- name: Deploy to GitHub Pages
70+
id: deployment
71+
uses: actions/deploy-pages@v4
72+

‎.github/workflows/enforce-main-source.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: Enforce Main PR Source
2+
3+
on:
4+
pull_request:
5+
branches:
6+
- main
7+
8+
permissions:
9+
contents: read
10+
11+
jobs:
12+
enforce-main-source:
13+
name: Enforce main <- dev only
14+
runs-on: ubuntu-latest
15+
env:
16+
BASE_REF: ${{ github.base_ref }}
17+
HEAD_REF: ${{ github.head_ref }}
18+
steps:
19+
- name: Validate pull request source branch
20+
run: |
21+
echo "Base branch: $BASE_REF"
22+
echo "Head branch: $HEAD_REF"
23+
if [ "$BASE_REF" = "main" ] && [ "$HEAD_REF" != "dev" ]; then
24+
echo "Only pull requests from 'dev' into 'main' are allowed."
25+
echo "Required flow: feature/* -> dev -> main."
26+
exit 1
27+
fi

0 commit comments

Comments
 (0)
⚡