new-scanner
Use this skill ONLY when creating a new data scanner (e.g., Twitter scanner, Bloomberg scanner). Do not use for agents or strategies.
SKILL.md.claude/skills/new-scanner
GitHubScope Constraint
- Scanner files go in
src/alpacalyzer/scanners/{name}_scanner.py - Tests go in
tests/test_{name}_scanner.py - Scanners discover trading opportunities from external data sources
Placeholders
<scanner>— lowercase with underscores (e.g.,twitter)<Scanner>— PascalCase (e.g.,Twitter)
Steps
1. Study the reference implementations
Read these files:
src/alpacalyzer/scanners/reddit_scanner.py— Reddit API integration (PRAW)src/alpacalyzer/scanners/finviz_scanner.py— web scraping + fundamental filterssrc/alpacalyzer/scanners/adapters.py— scanner adapter pattern for pipeline integration
Key patterns: scanners implement the Scanner protocol (or extend BaseScanner ABC) from src/alpacalyzer/pipeline/scanner_protocol.py. They return ScanResult objects containing lists of TopTicker, handle API failures gracefully (return empty results), deduplicate results, and filter invalid symbols.
2. Create scanner file
Create src/alpacalyzer/scanners/<scanner>_scanner.py. Extend BaseScanner from src/alpacalyzer/pipeline/scanner_protocol.py:
from alpacalyzer.pipeline.scanner_protocol import BaseScanner
from alpacalyzer.data.models import TopTicker
class <Scanner>Scanner(BaseScanner):
def __init__(self):
super().__init__(name="<scanner>", enabled=True, cache_ttl_seconds=300)
def _execute_scan(self) -> list[TopTicker]:
# Fetch data, extract tickers, deduplicate, filter
# Return [] on failure, never crash
...
- API client initialization (use env vars for keys, never hardcode)
_execute_scan()method — fetch data, extract tickers, deduplicate, filter- Error handling —
BaseScanner.scan()wraps_execute_scan()with timing and error handling automatically
3. Register scanner in pipeline
Create an adapter in src/alpacalyzer/pipeline/scanner_adapters.py following the existing RedditScannerAdapter or SocialScannerAdapter pattern.
Then register the adapter in src/alpacalyzer/pipeline/registry.py via ScannerRegistry. The CLI registers scanners at startup in src/alpacalyzer/cli.py.
4. Add env vars
If the scanner needs API keys, add to .env.example with a descriptive comment.
5. Write tests
Follow the pattern in existing scanner tests:
- Test successful scan returns ticker list
- Test API failure returns empty list (not exception)
- Test deduplication removes duplicates
- Test invalid ticker filtering (single letters, common words like "CEO", "WSB")
- Test result count is capped (max 20)
6. Run and verify
uv run pytest tests/test_<scanner>_scanner.py -v
Reference files
| Purpose | File |
|---|---|
| Scanner protocol | src/alpacalyzer/pipeline/scanner_protocol.py |
| Reference scanner | src/alpacalyzer/scanners/reddit_scanner.py |
| Web scraping example | src/alpacalyzer/scanners/finviz_scanner.py |
| Pipeline adapters | src/alpacalyzer/pipeline/scanner_adapters.py |
| Scanner adapters | src/alpacalyzer/scanners/adapters.py |
| Scanner registry | src/alpacalyzer/pipeline/registry.py |
| CLI registration | src/alpacalyzer/cli.py |