# wspr-ai-lite
Lightweight WSPR analytics and AI‑ready backend using **DuckDB** + **Streamlit**, with safe query access via **MCP Agents**.
[](https://streamlit.io/)
[](https://duckdb.org/)
[](https://modelcontextprotocol.io/)
[](https://ki7mt.github.io/wspr-ai-lite/)
[](LICENSE)
## Workflows and Packaging Status
**Versions**
[](https://github.com/KI7MT/wspr-ai-lite/releases)
[](https://github.com/KI7MT/wspr-ai-lite/tags)
[](https://pypi.org/project/wspr-ai-lite/)
[](https://pypi.org/project/wspr-ai-lite/)
**CI/CD**
[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/ci.yml)
[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/smoke.yml)
[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/release.yml)
[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/pre-commit.yml)
[](https://conventionalcommits.org)
---
## Overview
- **Analytics Dashboard**: Streamlit UI lets you explore WSPR spots with SNR trends, DX distance analysis, station activity, and “QSO‑like” reciprocity views.
- **Canonical Schema**: Data is normalized into a portable DuckDB file—consistent, lightweight, and ready for future backend upgrades.
- **CLI Tools**: Click-based tools (`wspr-ai-lite`, `wspr-ai-lite-fetch`, `wspr-ai-lite-tools`) for downloading, ingesting, verifying, and managing the database.
- **MCP Integration**: Experimental MCP server (`wspr-ai-lite-mcp`) exposing safe APIs for AI agents. A manifest defines permitted queries and access control.
- **Roadmap (v0.4+ vision)**: MCP server will migrate to a **FastAPI + Uvicorn** backend with service control (start/stop/restart), enabling production-grade deployment.
---
## What Can You Do With It
Explore **Weak Signal Propagation Reporter (WSPR)** data with an easy, local dashboard:
- SNR distributions & monthly spot trends
- Top reporters, most-heard TX stations
- Geographic spread & distance/DX analysis
- QSO-like reciprocal reports
- Hourly activity heatmaps & yearly unique counts
- Works on **Windows, Linux, macOS** — no heavy server required.
## Key Features
- Local DuckDB storage with efficient ingest + caching
- Streamlit UI for interactive exploration
- Distance/DX analysis with Maidenhead grid conversion
- QSO-like reciprocal finder with configurable time window
## Fast Performance
- Columnar Storage: DuckDB is a columnar database, which allows for better data compression and faster query execution.
- Vectorization: processes data in batches, optimized CPU usage, significantly faster than traditional OLTP databases.
## Ease of Use
- Simple Installation: DuckDB can be installed with just a few lines of code, and on any platform.
- In-Process Operation: It runs within as a host application, eliminating network latency and simplifying data access.
## Quickstart (Recommended: PyPI)
### 1. Install from PyPI
> optional but recommended: [create a Python virtual environment](https://docs.python.org/3/library/venv.html) first
```bash
python3 -m venv .venv && source .venv/bin/activate
pip install wspr-ai-lite
```
### 2. Ingest Data
Fetch WSPRNet monthly archives and load them into DuckDB:
```bash
wspr-ai-lite ingest --from 2014-07 --to 2014-07 --db data/wspr.duckdb
```
- Downloads compressed monthly CSVs (caches locally in .cache/)
- Normalizes into data/wspr.duckdb
- Adds extra fields (band, reporter grid, tx grid)
### 3. Launch the Dashboard
```bash
wspr-ai-lite ui --db data/wspr.duckdb --port 8501
```
Open http://localhost:8501 in your browser 🎉
👉 For developers who want to hack on the code directly, see [Developer Setup](https://ki7mt.github.io/wspr-ai-lite/DEV_SETUP/).
## Example Visualizations
- SNR Distribution by Count
- Monthly Spot Counts
- Top Reporting Stations
- Most Heard TX Stations
- Geographic Spread (Unique Grids)
- Distance Distribution + Longest DX
- Best DX per Band
- Activity by Hour × Month
- TX/RX Balance and QSO Success Rate
## Development
For contributors and developers:
- docs/dev-setup.md --> Development setup guide
- docs/testing.md --> Testing instructions (pytest + Makefile)
- docs/troubleshooting.md --> Common issues & fixes
```bash
make setup-dev # create venv and install deps
make ingest # run ingest pipeline
make run # launch Streamlit UI
make test # run pytest suite
```
### Makefile Usage
There is an extensive list of Makefile targets that simplify operations. See `make help` for a full list of available targets.
## Get Help
- **Report a bug** → [New Bug Report](https://github.com/KI7MT/wspr-ai-lite/issues/new?template=bug_report.yml)
- **Request a feature** → [New Feature Request](https://github.com/KI7MT/wspr-ai-lite/issues/new?template=feature_request.yml)
- **Ask a question / share ideas** → [GitHub Discussions](https://github.com/KI7MT/wspr-ai-lite/discussions)
- **Read the docs** → https://ki7mt.github.io/wspr-ai-lite/
## Acknowledgements
- Joe Taylor, K1JT, and the WSJT-X Development Team
- WSPRNet community for providing global weak-signal data
- Contributors to DuckDB and Streamlit
- Amateur radio operators worldwide who share spots and keep the network alive
## Contributing
Pull requests are welcome!
## Roadmap
- **Phase 1**: wspr-ai-lite (this project)
- Lightweight, local-only DuckDB + Streamlit dashboard
- **Phase 2**: wspr-ai-analytics (modernize [wspr-analytics](https://github.com/KI7MT/wspr-analytics))
- Full analytics suite with ClickHouse, Grafana, AI Agents, and MCP integration
- Designed for heavier infrastructure and richer analysis
## 📜 License
MIT — free to use for amateur radio and research.
Raw data
{
"_id": null,
"home_page": null,
"name": "wspr-ai-lite",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "wspr, ham radio, duckdb, streamlit, amateur radio, analytics",
"author": "Greg Beam (KI7MT)",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/00/9c/fcefbc26aea85bd2519a98086b251068f08a3c10c53eddd187706f21099d/wspr_ai_lite-0.4.0.tar.gz",
"platform": null,
"description": "# wspr-ai-lite\nLightweight WSPR analytics and AI\u2011ready backend using **DuckDB** + **Streamlit**, with safe query access via **MCP Agents**.\n\n[](https://streamlit.io/)\n[](https://duckdb.org/)\n[](https://modelcontextprotocol.io/)\n[](https://ki7mt.github.io/wspr-ai-lite/)\n[](LICENSE)\n\n## Workflows and Packaging Status\n\n**Versions**\n[](https://github.com/KI7MT/wspr-ai-lite/releases)\n[](https://github.com/KI7MT/wspr-ai-lite/tags)\n[](https://pypi.org/project/wspr-ai-lite/)\n[](https://pypi.org/project/wspr-ai-lite/)\n\n**CI/CD**\n[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/ci.yml)\n[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/smoke.yml)\n[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/release.yml)\n[](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/pre-commit.yml)\n[](https://conventionalcommits.org)\n\n---\n\n## Overview\n\n- **Analytics Dashboard**: Streamlit UI lets you explore WSPR spots with SNR trends, DX distance analysis, station activity, and \u201cQSO\u2011like\u201d reciprocity views.\n- **Canonical Schema**: Data is normalized into a portable DuckDB file\u2014consistent, lightweight, and ready for future backend upgrades.\n- **CLI Tools**: Click-based tools (`wspr-ai-lite`, `wspr-ai-lite-fetch`, `wspr-ai-lite-tools`) for downloading, ingesting, verifying, and managing the database.\n- **MCP Integration**: Experimental MCP server (`wspr-ai-lite-mcp`) exposing safe APIs for AI agents. A manifest defines permitted queries and access control.\n- **Roadmap (v0.4+ vision)**: MCP server will migrate to a **FastAPI + Uvicorn** backend with service control (start/stop/restart), enabling production-grade deployment.\n\n---\n\n## What Can You Do With It\n\nExplore **Weak Signal Propagation Reporter (WSPR)** data with an easy, local dashboard:\n\n- SNR distributions & monthly spot trends\n- Top reporters, most-heard TX stations\n- Geographic spread & distance/DX analysis\n- QSO-like reciprocal reports\n- Hourly activity heatmaps & yearly unique counts\n- Works on **Windows, Linux, macOS** \u2014 no heavy server required.\n\n## Key Features\n- Local DuckDB storage with efficient ingest + caching\n- Streamlit UI for interactive exploration\n- Distance/DX analysis with Maidenhead grid conversion\n- QSO-like reciprocal finder with configurable time window\n\n## Fast Performance\n- Columnar Storage: DuckDB is a columnar database, which allows for better data compression and faster query execution.\n- Vectorization: processes data in batches, optimized CPU usage, significantly faster than traditional OLTP databases.\n\n## Ease of Use\n- Simple Installation: DuckDB can be installed with just a few lines of code, and on any platform.\n- In-Process Operation: It runs within as a host application, eliminating network latency and simplifying data access.\n\n## Quickstart (Recommended: PyPI)\n\n### 1. Install from PyPI\n\n> optional but recommended: [create a Python virtual environment](https://docs.python.org/3/library/venv.html) first\n\n```bash\npython3 -m venv .venv && source .venv/bin/activate\npip install wspr-ai-lite\n```\n\n### 2. Ingest Data\nFetch WSPRNet monthly archives and load them into DuckDB:\n\n```bash\nwspr-ai-lite ingest --from 2014-07 --to 2014-07 --db data/wspr.duckdb\n```\n- Downloads compressed monthly CSVs (caches locally in .cache/)\n- Normalizes into data/wspr.duckdb\n- Adds extra fields (band, reporter grid, tx grid)\n\n### 3. Launch the Dashboard\n```bash\nwspr-ai-lite ui --db data/wspr.duckdb --port 8501\n```\nOpen http://localhost:8501 in your browser \ud83c\udf89\n\n\ud83d\udc49 For developers who want to hack on the code directly, see [Developer Setup](https://ki7mt.github.io/wspr-ai-lite/DEV_SETUP/).\n\n## Example Visualizations\n- SNR Distribution by Count\n- Monthly Spot Counts\n- Top Reporting Stations\n- Most Heard TX Stations\n- Geographic Spread (Unique Grids)\n- Distance Distribution + Longest DX\n- Best DX per Band\n- Activity by Hour \u00d7 Month\n- TX/RX Balance and QSO Success Rate\n\n## Development\n\nFor contributors and developers:\n- docs/dev-setup.md --> Development setup guide\n- docs/testing.md --> Testing instructions (pytest + Makefile)\n- docs/troubleshooting.md --> Common issues & fixes\n\n```bash\nmake setup-dev # create venv and install deps\nmake ingest # run ingest pipeline\nmake run # launch Streamlit UI\nmake test # run pytest suite\n```\n\n### Makefile Usage\n\nThere is an extensive list of Makefile targets that simplify operations. See `make help` for a full list of available targets.\n\n## Get Help\n- **Report a bug** \u2192 [New Bug Report](https://github.com/KI7MT/wspr-ai-lite/issues/new?template=bug_report.yml)\n- **Request a feature** \u2192 [New Feature Request](https://github.com/KI7MT/wspr-ai-lite/issues/new?template=feature_request.yml)\n- **Ask a question / share ideas** \u2192 [GitHub Discussions](https://github.com/KI7MT/wspr-ai-lite/discussions)\n- **Read the docs** \u2192 https://ki7mt.github.io/wspr-ai-lite/\n\n## Acknowledgements\n- Joe Taylor, K1JT, and the WSJT-X Development Team\n- WSPRNet community for providing global weak-signal data\n- Contributors to DuckDB and Streamlit\n- Amateur radio operators worldwide who share spots and keep the network alive\n\n## Contributing\nPull requests are welcome!\n\n## Roadmap\n- **Phase 1**: wspr-ai-lite (this project)\n - Lightweight, local-only DuckDB + Streamlit dashboard\n- **Phase 2**: wspr-ai-analytics (modernize [wspr-analytics](https://github.com/KI7MT/wspr-analytics))\n - Full analytics suite with ClickHouse, Grafana, AI Agents, and MCP integration\n - Designed for heavier infrastructure and richer analysis\n\n## \ud83d\udcdc License\nMIT \u2014 free to use for amateur radio and research.\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight WSPR analytics: DuckDB ingest + Streamlit dashboard.",
"version": "0.4.0",
"project_urls": {
"Changelog": "https://github.com/KI7MT/wspr-ai-lite/blob/main/CHANGELOG.md",
"Documentation": "https://ki7mt.github.io/wspr-ai-lite/",
"Homepage": "https://github.com/KI7MT/wspr-ai-lite",
"Issues": "https://github.com/KI7MT/wspr-ai-lite/issues",
"Source": "https://github.com/KI7MT/wspr-ai-lite"
},
"split_keywords": [
"wspr",
" ham radio",
" duckdb",
" streamlit",
" amateur radio",
" analytics"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e1a03627a0f02a58fc1dddf13d79edfa637e51d9bfa3023ceae2188329485ea2",
"md5": "7678a82ea24de743b64ac11b1ff7f438",
"sha256": "6a67f19c5741261c8b3888a8a2a111b374e2983bcf62fa224c029c81ce9149fe"
},
"downloads": -1,
"filename": "wspr_ai_lite-0.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7678a82ea24de743b64ac11b1ff7f438",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 33141,
"upload_time": "2025-08-26T08:26:56",
"upload_time_iso_8601": "2025-08-26T08:26:56.138219Z",
"url": "https://files.pythonhosted.org/packages/e1/a0/3627a0f02a58fc1dddf13d79edfa637e51d9bfa3023ceae2188329485ea2/wspr_ai_lite-0.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "009cfcefbc26aea85bd2519a98086b251068f08a3c10c53eddd187706f21099d",
"md5": "b3a3bc7ef3aa1d9879056952c5d7ab73",
"sha256": "fce90dc5278e58d503de3133f2481bb0be71d35d93fbcb9201728768fcc0b1e3"
},
"downloads": -1,
"filename": "wspr_ai_lite-0.4.0.tar.gz",
"has_sig": false,
"md5_digest": "b3a3bc7ef3aa1d9879056952c5d7ab73",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 34285,
"upload_time": "2025-08-26T08:26:58",
"upload_time_iso_8601": "2025-08-26T08:26:58.008647Z",
"url": "https://files.pythonhosted.org/packages/00/9c/fcefbc26aea85bd2519a98086b251068f08a3c10c53eddd187706f21099d/wspr_ai_lite-0.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-26 08:26:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "KI7MT",
"github_project": "wspr-ai-lite",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "streamlit",
"specs": []
},
{
"name": "duckdb",
"specs": []
},
{
"name": "pandas",
"specs": []
},
{
"name": "numpy",
"specs": []
},
{
"name": "requests",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pyyaml-env-tag",
"specs": []
},
{
"name": "click",
"specs": [
[
">=",
"8.1"
]
]
},
{
"name": "commitizen",
"specs": [
[
">=",
"3.30"
]
]
}
],
"lcname": "wspr-ai-lite"
}
JSON
