Metadata-Version: 2.4
Name: wspr-ai-lite
Version: 0.2.5
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 rendering tool employing DuckDB + Streamlit**

## Resources

[![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/)
[![Docs](https://img.shields.io/badge/docs-github_pages-blue)](https://KI7MT.github.io/wspr-ai-lite/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## Workflows and Packaging
[![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)
[![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)
[![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)
[![smoke](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/smoke.yml/badge.svg)](https://github.com/KI7MT/wspr-ai-lite/actions/workflows/smoke.yml)

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 !!
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. Run the UI
```bash
wspr-ai-lite ui --db data/wspr.duckdb --port 8501
```
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:

### Makefile Usage

There is an extensive list of Makefile targets that simplify operations. See `make help` for a full list of available targets.

```bash
make help

# sample output

Available Make Targets
-------------------------------------------------------------------------------
build                Build PyPi Pyjon Package
clean                Clean temporary files, caches, local DBs, and MkDocs site/
dist-clean-all       Deep clean + remove smoke artifacts
distclean            More thorough clean: includes venv, packaging artifacts, temp dirs
docs-deploy          Deplot docs to hh-pages
docs-serve           Docs tasks (MkDocs)
ingest               Ingest a sample month (2014-07)
install-dev          Install dev dependencies (requirements-dev.txt)
install              Install runtime dependencies (requirements.txt)
lint-docs            Docstring checks: coverage (interrogate) + style (pydocstyle)
precommit-install    Install git pre-commit hooks
publish-test         Pulublish Package to PyPi Test Repository
publish              Pulublish Package to PyPi Production Repository
reset                Full reset: distclean + recreate venv + install deps + ingest sample
run                  Run Streamlit UI
setup-dev            Create venv, install dev deps, install pre-commit hooks
smoke-build          Build wheel+sdist for smoke test
smoke-clean          Remove smoke-test artifacts (venv + tmp DB)
smoke-ingest         Ingest a single month into a temporary DuckDB
smoke-install        Create isolated smoke venv and install the built wheel
smoke-test-pypi      Install from PyPI and run verify+ui-check
smoke-test           Full end-to-end smoke test
smoke-ui-check       Check UI presence and streamlit availability
smoke-verify         Verify the DuckDB contains rows
test                  Run pytest
venv                 Create Python virtual environment (.venv)
```

## 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.
