Metadata-Version: 2.4
Name: wspr-ai-lite
Version: 0.2.1
Summary: Lightweight WSPR analytics: DuckDB ingest + Streamlit dashboard.
Project-URL: Homepage, https://github.com/KI7MT/wspr-ai-lite
Project-URL: Documentation, https://ki7mt.github.io/wspr-ai-lite/
Project-URL: Source, https://github.com/KI7MT/wspr-ai-lite
Project-URL: Issues, https://github.com/KI7MT/wspr-ai-lite/issues
Project-URL: Changelog, https://github.com/KI7MT/wspr-ai-lite/blob/main/CHANGELOG.md
Author: Greg Beam (KI7MT)
License: MIT License
        
        Copyright (c) 2025
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: amateur radio,analytics,duckdb,ham radio,streamlit,wspr
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.10
Requires-Dist: duckdb
Requires-Dist: pandas
Requires-Dist: requests
Requires-Dist: streamlit
Description-Content-Type: text/markdown

# 📡 wspr-ai-lite

**Lightweight WSPR analytics with DuckDB + Streamlit**

## Repository Workflow Staus
[![CI](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/ci.yml/badge.svg)](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/ci.yml)
[![Made with Streamlit](https://img.shields.io/badge/Made%20with-Streamlit-FF4B4B)](https://streamlit.io/)
[![DuckDB](https://img.shields.io/badge/Database-DuckDB-blue)](https://duckdb.org/)
[![pre-commit](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/pre-commit.yml/badge.svg)](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/pre-commit.yml)
[![Docs](https://img.shields.io/badge/docs-github_pages-blue)](https://KI7MT.github.io/wspr-ai-lite/)

## Python Package Publishing
[![PyPI version](https://img.shields.io/pypi/v/wspr-ai-lite.svg)](https://pypi.org/project/wspr-ai-lite/)
[![Python versions](https://img.shields.io/pypi/pyversions/wspr-ai-lite.svg)](https://pypi.org/project/wspr-ai-lite/)
[![Publish](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/release.yml/badge.svg)](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/release.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

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.

---

## ✨ 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
- Ready-to-run on modest hardware

---

## 🚀 Quickstart

### 1. Clone & Setup
```bash
git clone git@github.com:KI7MT/wspr-ai-lite.git
cd wspr-ai-lite

# optional venv
python3 -m venv .venv && source .venv/bin/activate

pip install -r requirements.txt
```

### 2. Ingest Data
Fetch WSPRNet monthly archives and load them into DuckDB:

```bash
# adjust to whatever range you wish, but be reasonable !!
python pipelines/ingest.py --from 2014-07 --to 2014-07
```
- Downloads compressed monthly CSVs (caches locally)
- Normalizes into data/wspr.duckdb
- Adds extra fields (band, reporter grid, tx grid)

### 3. Run the UI
```bash
streamlit run app/wspr_app.py
```
Then open http://localhost:8501 in your browser.

---

## 📊 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
```

### Testing
Run unit tests for ingest and utilities:
```bash
pytest -q
```

Or via Makefile:
```bash
make test
```

---

## 🙌 Acknowledgements
- WSPRNet community for providing global weak-signal data
- Joe Taylor, K1JT, and the WSJT-X Development Team
- Contributors to DuckDB and Streamlit
- Amateur radio operators worldwide who share spots and keep the network alive

---

## 📬 Contributing
Pull requests are welcome!
If you have feature ideas (e.g., new metrics, visualizations, or AI integrations), open an issue first to discuss.

---

## 🔮 Roadmap
- 📦 Phase 1: wspr-ai-lite (this project)
- Lightweight, local-only DuckDB + Streamlit dashboard
- 🚀 Phase 2: wspr-ai-analytics
- Full analytics suite with ClickHouse, Grafana, AI Agents, and MCP integration
- Designed for heavier infrastructure and richer analysis

---

## 📜 License
This project is licensed under the MIT License. Open and free for amateur radio and research use.
