A daily digest tool that surfaces high-value engagement opportunities across online communities, starting with Reddit. Signal Scout uses a local LLM (Ollama) to intelligently score and prioritize posts where you can add genuine value.

Core philosophy: Surface signal, not noise. Spend time helping people, not searching for them.

• Smart LLM Scoring - Local Ollama integration scores posts 0-10 for engagement opportunity
• Gap Analysis - Detects unanswered questions and weak/incomplete answers
• Keyword Matching - Configurable emotional, technical, and lexicon keyword detection
• Author Memory - Tracks users you've helped for relationship building
• Warm Lead Tracking - Identifies and prioritizes positive reply sentiment
• Analytics Dashboards - Visualize trends, top subreddits, and engagement patterns
• Dual Reddit Source - Works with both authenticated API and public JSON endpoint

# 1. Clone and install
git clone https://github.com/yourusername/signal-scout.git
cd signal-scout
uv sync

# 2. Copy and configure settings
cp config/settings.example.yaml config/settings.yaml
# Edit config/settings.yaml with your subreddits and keywords

# 3. Start Ollama (required for scoring)
ollama pull llama3.1:8b
ollama serve

# 4. Fetch and score posts
uv run signal-scout fetch

# 5. Browse opportunities in web UI
uv run signal-scout serve
# Open http://localhost:8000

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Reddit    │────▶│   Match     │────▶│   Score     │────▶│   Store     │
│   Fetch     │     │   Keywords  │     │   with LLM  │     │   SQLite    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                   │
                                                                   ▼
                                                            ┌─────────────┐
                                                            │   Web UI    │
                                                            │   (HTMX)    │
                                                            └─────────────┘

1. Fetch - Pull posts from configured subreddits (JSON or PRAW API)
2. Match - Detect keywords with weighted scoring (emotional, technical, lexicon)
3. Score - LLM evaluates opportunity value, effort required, and suggested angle
4. Store - Persist to SQLite with full metadata and scoring
5. Display - Browse, filter, and act on opportunities via web UI

• Python 3.12+
• Ollama with a model (default: llama3.1:8b)
• Reddit API credentials (optional - JSON endpoint works without auth)

Full documentation is available at the MkDocs site:

• Getting Started - Installation and setup
• Configuration - YAML config reference
• CLI Commands - Detailed command documentation
• Web UI Guide - Dashboard and workflow guides
• Scoring Algorithms - How scoring works
• Architecture - System design overview

Build and serve docs locally:

uv run mkdocs serve

# Install with dev dependencies
uv sync

# Run tests
uv run pytest

# Lint and format
uv run ruff check --fix src tests
uv run ruff format src tests

# Type check
uv run pyright

See CONTRIBUTING.md for full development guidelines.

MIT License - see LICENSE for details.