Initial commit with translated description
This commit is contained in:
408
docs/ARCHITECTURE.md
Normal file
408
docs/ARCHITECTURE.md
Normal file
@@ -0,0 +1,408 @@
|
||||
# Technical Architecture
|
||||
|
||||
How Stock Analysis v6.0 works under the hood.
|
||||
|
||||
## System Overview
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────────┐
|
||||
│ Stock Analysis v6.0 │
|
||||
├─────────────────────────────────────────────────────────────────────┤
|
||||
│ │
|
||||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||||
│ │ CLI Interface │ │
|
||||
│ │ analyze_stock.py | dividends.py | watchlist.py | portfolio.py│ │
|
||||
│ └────────────────────────────┬─────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────────────▼─────────────────────────────────┐ │
|
||||
│ │ Analysis Engine │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │Earnings │ │Fundmtls │ │Analysts │ │Historical│ │ │
|
||||
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │ │
|
||||
│ │ │ Market │ │ Sector │ │Momentum │ │Sentiment│ │ │
|
||||
│ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ └───────────┴───────────┴───────────┘ │ │
|
||||
│ │ │ │ │
|
||||
│ │ [Synthesizer] │ │
|
||||
│ │ │ │ │
|
||||
│ │ [Signal Output] │ │
|
||||
│ └──────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ┌────────────────────────────▼─────────────────────────────────┐ │
|
||||
│ │ Data Sources │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
|
||||
│ │ │ Yahoo │ │ CNN │ │ SEC │ │ Google │ │ │
|
||||
│ │ │ Finance │ │Fear/Grd │ │ EDGAR │ │ News │ │ │
|
||||
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
|
||||
│ └──────────────────────────────────────────────────────────────┘ │
|
||||
│ │
|
||||
└─────────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Data Fetching (`fetch_stock_data`)
|
||||
|
||||
```python
|
||||
def fetch_stock_data(ticker: str, verbose: bool = False) -> StockData | None:
|
||||
"""Fetch stock data from Yahoo Finance with retry logic."""
|
||||
```
|
||||
|
||||
**Features:**
|
||||
- 3 retries with exponential backoff
|
||||
- Graceful handling of missing data
|
||||
- Asset type detection (stock vs crypto)
|
||||
|
||||
**Returns:** `StockData` dataclass with:
|
||||
- `info`: Company fundamentals
|
||||
- `earnings_history`: Past earnings
|
||||
- `analyst_info`: Ratings and targets
|
||||
- `price_history`: 1-year OHLCV
|
||||
|
||||
### 2. Analysis Modules
|
||||
|
||||
Each dimension has its own analyzer:
|
||||
|
||||
| Module | Function | Returns |
|
||||
|--------|----------|---------|
|
||||
| Earnings | `analyze_earnings_surprise()` | `EarningsSurprise` |
|
||||
| Fundamentals | `analyze_fundamentals()` | `Fundamentals` |
|
||||
| Analysts | `analyze_analyst_sentiment()` | `AnalystSentiment` |
|
||||
| Historical | `analyze_historical_patterns()` | `HistoricalPatterns` |
|
||||
| Market | `analyze_market_context()` | `MarketContext` |
|
||||
| Sector | `analyze_sector_performance()` | `SectorComparison` |
|
||||
| Momentum | `analyze_momentum()` | `MomentumAnalysis` |
|
||||
| Sentiment | `analyze_sentiment()` | `SentimentAnalysis` |
|
||||
|
||||
### 3. Sentiment Sub-Analyzers
|
||||
|
||||
Sentiment runs 5 parallel async tasks:
|
||||
|
||||
```python
|
||||
results = await asyncio.gather(
|
||||
get_fear_greed_index(), # CNN Fear & Greed
|
||||
get_short_interest(data), # Yahoo Finance
|
||||
get_vix_term_structure(), # VIX Futures
|
||||
get_insider_activity(), # SEC EDGAR
|
||||
get_put_call_ratio(data), # Options Chain
|
||||
return_exceptions=True
|
||||
)
|
||||
```
|
||||
|
||||
**Timeout:** 10 seconds per indicator
|
||||
**Minimum:** 2 of 5 indicators required
|
||||
|
||||
### 4. Signal Synthesis
|
||||
|
||||
```python
|
||||
def synthesize_signal(
|
||||
ticker, company_name,
|
||||
earnings, fundamentals, analysts, historical,
|
||||
market_context, sector, earnings_timing,
|
||||
momentum, sentiment,
|
||||
breaking_news, geopolitical_risk_warning, geopolitical_risk_penalty
|
||||
) -> Signal:
|
||||
```
|
||||
|
||||
**Scoring:**
|
||||
1. Collect available component scores
|
||||
2. Apply normalized weights
|
||||
3. Calculate weighted average → `final_score`
|
||||
4. Apply adjustments (timing, overbought, risk-off)
|
||||
5. Determine recommendation threshold
|
||||
|
||||
**Thresholds:**
|
||||
```python
|
||||
if final_score > 0.33:
|
||||
recommendation = "BUY"
|
||||
elif final_score < -0.33:
|
||||
recommendation = "SELL"
|
||||
else:
|
||||
recommendation = "HOLD"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Caching Strategy
|
||||
|
||||
### What's Cached
|
||||
|
||||
| Data | TTL | Key |
|
||||
|------|-----|-----|
|
||||
| Market Context | 1 hour | `market_context` |
|
||||
| Fear & Greed | 1 hour | `fear_greed` |
|
||||
| VIX Structure | 1 hour | `vix_structure` |
|
||||
| Breaking News | 1 hour | `breaking_news` |
|
||||
|
||||
### Cache Implementation
|
||||
|
||||
```python
|
||||
_SENTIMENT_CACHE = {}
|
||||
_CACHE_TTL_SECONDS = 3600 # 1 hour
|
||||
|
||||
def _get_cached(key: str):
|
||||
if key in _SENTIMENT_CACHE:
|
||||
value, timestamp = _SENTIMENT_CACHE[key]
|
||||
if time.time() - timestamp < _CACHE_TTL_SECONDS:
|
||||
return value
|
||||
return None
|
||||
|
||||
def _set_cache(key: str, value):
|
||||
_SENTIMENT_CACHE[key] = (value, time.time())
|
||||
```
|
||||
|
||||
### Why This Matters
|
||||
|
||||
- First stock: ~8 seconds (full fetch)
|
||||
- Second stock: ~4 seconds (reuses market data)
|
||||
- Same stock again: ~4 seconds (no stock-level cache)
|
||||
|
||||
---
|
||||
|
||||
## Data Flow
|
||||
|
||||
### Single Stock Analysis
|
||||
|
||||
```
|
||||
User Input: "AAPL"
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. FETCH DATA (yfinance) │
|
||||
│ - Stock info, earnings, price history │
|
||||
│ - ~2 seconds │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 2. PARALLEL ANALYSIS │
|
||||
│ │
|
||||
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
|
||||
│ │ Earnings │ │Fundmtls │ │ Analysts │ ... (sync) │
|
||||
│ └──────────┘ └──────────┘ └──────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ Market Context (cached or fetch) │ ~1 second │
|
||||
│ └────────────────────────────────────┘ │
|
||||
│ │
|
||||
│ ┌────────────────────────────────────┐ │
|
||||
│ │ Sentiment (5 async tasks) │ ~3-5 seconds │
|
||||
│ │ - Fear/Greed (cached) │ │
|
||||
│ │ - Short Interest │ │
|
||||
│ │ - VIX Structure (cached) │ │
|
||||
│ │ - Insider Trading (slow!) │ │
|
||||
│ │ - Put/Call Ratio │ │
|
||||
│ └────────────────────────────────────┘ │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 3. SYNTHESIZE SIGNAL │
|
||||
│ - Combine scores with weights │
|
||||
│ - Apply adjustments │
|
||||
│ - Generate caveats │
|
||||
│ - ~10 ms │
|
||||
└────────────────────────┬────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 4. OUTPUT │
|
||||
│ - Text or JSON format │
|
||||
│ - Include disclaimer │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Risk Detection
|
||||
|
||||
### Geopolitical Risk
|
||||
|
||||
```python
|
||||
GEOPOLITICAL_RISK_MAP = {
|
||||
"taiwan": {
|
||||
"keywords": ["taiwan", "tsmc", "strait"],
|
||||
"sectors": ["Technology", "Communication Services"],
|
||||
"affected_tickers": ["NVDA", "AMD", "TSM", ...],
|
||||
"impact": "Semiconductor supply chain disruption",
|
||||
},
|
||||
# ... china, russia_ukraine, middle_east, banking_crisis
|
||||
}
|
||||
```
|
||||
|
||||
**Process:**
|
||||
1. Check breaking news for keywords
|
||||
2. If keyword found, check if ticker in affected list
|
||||
3. Apply confidence penalty (30% direct, 15% sector)
|
||||
|
||||
### Breaking News
|
||||
|
||||
```python
|
||||
def check_breaking_news(verbose: bool = False) -> list[str] | None:
|
||||
"""Scan Google News RSS for crisis keywords (last 24h)."""
|
||||
```
|
||||
|
||||
**Crisis Keywords:**
|
||||
```python
|
||||
CRISIS_KEYWORDS = {
|
||||
"war": ["war", "invasion", "military strike", ...],
|
||||
"economic": ["recession", "crisis", "collapse", ...],
|
||||
"regulatory": ["sanctions", "embargo", "ban", ...],
|
||||
"disaster": ["earthquake", "hurricane", "pandemic", ...],
|
||||
"financial": ["emergency rate", "bailout", ...],
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
stock-analysis/
|
||||
├── scripts/
|
||||
│ ├── analyze_stock.py # Main analysis engine (2500+ lines)
|
||||
│ ├── portfolio.py # Portfolio management
|
||||
│ ├── dividends.py # Dividend analysis
|
||||
│ ├── watchlist.py # Watchlist + alerts
|
||||
│ └── test_stock_analysis.py # Unit tests
|
||||
├── docs/
|
||||
│ ├── CONCEPT.md # Philosophy & ideas
|
||||
│ ├── USAGE.md # Practical guide
|
||||
│ └── ARCHITECTURE.md # This file
|
||||
├── SKILL.md # OpenClaw skill definition
|
||||
├── README.md # Project overview
|
||||
└── .clawdhub/ # ClawHub metadata
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Data Storage
|
||||
|
||||
### Portfolio (`portfolios.json`)
|
||||
|
||||
```json
|
||||
{
|
||||
"portfolios": [
|
||||
{
|
||||
"name": "Retirement",
|
||||
"created_at": "2024-01-01T00:00:00Z",
|
||||
"assets": [
|
||||
{
|
||||
"ticker": "AAPL",
|
||||
"quantity": 100,
|
||||
"cost_basis": 150.00,
|
||||
"type": "stock",
|
||||
"added_at": "2024-01-01T00:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Watchlist (`watchlist.json`)
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"ticker": "NVDA",
|
||||
"added_at": "2024-01-15T10:30:00Z",
|
||||
"price_at_add": 700.00,
|
||||
"target_price": 800.00,
|
||||
"stop_price": 600.00,
|
||||
"alert_on_signal": true,
|
||||
"last_signal": "BUY",
|
||||
"last_check": "2024-01-20T08:00:00Z"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
```python
|
||||
# /// script
|
||||
# requires-python = ">=3.10"
|
||||
# dependencies = [
|
||||
# "yfinance>=0.2.40", # Stock data
|
||||
# "pandas>=2.0.0", # Data manipulation
|
||||
# "fear-and-greed>=0.4", # CNN Fear & Greed
|
||||
# "edgartools>=2.0.0", # SEC EDGAR filings
|
||||
# "feedparser>=6.0.0", # RSS parsing
|
||||
# ]
|
||||
# ///
|
||||
```
|
||||
|
||||
**Why These:**
|
||||
- `yfinance`: Most reliable free stock API
|
||||
- `pandas`: Industry standard for financial data
|
||||
- `fear-and-greed`: Simple CNN F&G wrapper
|
||||
- `edgartools`: Clean SEC EDGAR access
|
||||
- `feedparser`: Robust RSS parsing
|
||||
|
||||
---
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### Current
|
||||
|
||||
| Operation | Time |
|
||||
|-----------|------|
|
||||
| yfinance fetch | ~2s |
|
||||
| Market context | ~1s (cached after) |
|
||||
| Insider trading | ~3-5s (slowest!) |
|
||||
| Sentiment (parallel) | ~3-5s |
|
||||
| Synthesis | ~10ms |
|
||||
| **Total** | **5-10s** |
|
||||
|
||||
### Fast Mode (`--fast`)
|
||||
|
||||
Skips:
|
||||
- Insider trading (SEC EDGAR)
|
||||
- Breaking news scan
|
||||
|
||||
**Result:** 2-3 seconds
|
||||
|
||||
### Future Optimizations
|
||||
|
||||
1. **Stock-level caching** — Cache fundamentals for 24h
|
||||
2. **Batch API calls** — yfinance supports multiple tickers
|
||||
3. **Background refresh** — Pre-fetch watchlist data
|
||||
4. **Local SEC data** — Avoid EDGAR API calls
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Retry Strategy
|
||||
|
||||
```python
|
||||
max_retries = 3
|
||||
for attempt in range(max_retries):
|
||||
try:
|
||||
# fetch data
|
||||
except Exception as e:
|
||||
wait_time = 2 ** attempt # Exponential backoff: 1, 2, 4 seconds
|
||||
time.sleep(wait_time)
|
||||
```
|
||||
|
||||
### Graceful Degradation
|
||||
|
||||
- Missing earnings → Skip dimension, reweight
|
||||
- Missing analysts → Skip dimension, reweight
|
||||
- Missing sentiment → Skip dimension, reweight
|
||||
- API failure → Return None, continue with partial data
|
||||
|
||||
### Minimum Requirements
|
||||
|
||||
- At least 2 of 8 dimensions required
|
||||
- At least 2 of 5 sentiment indicators required
|
||||
- Otherwise → HOLD with low confidence
|
||||
233
docs/CONCEPT.md
Normal file
233
docs/CONCEPT.md
Normal file
@@ -0,0 +1,233 @@
|
||||
# Concept & Philosophy
|
||||
|
||||
## The Problem
|
||||
|
||||
Making investment decisions is hard. There's too much data, too many opinions, and too much noise. Most retail investors either:
|
||||
|
||||
1. **Over-simplify** — Buy based on headlines or tips
|
||||
2. **Over-complicate** — Get lost in endless research
|
||||
3. **Freeze** — Analysis paralysis, never act
|
||||
|
||||
## The Solution
|
||||
|
||||
Stock Analysis provides a **structured, multi-dimensional framework** that:
|
||||
|
||||
- Aggregates data from multiple sources
|
||||
- Weighs different factors objectively
|
||||
- Produces a clear **BUY / HOLD / SELL** signal
|
||||
- Explains the reasoning with bullet points
|
||||
- Flags risks and caveats
|
||||
|
||||
Think of it as a **second opinion** — not a replacement for your judgment, but a systematic check.
|
||||
|
||||
---
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
### 1. Multiple Perspectives Beat Single Metrics
|
||||
|
||||
No single metric tells the whole story:
|
||||
- A low P/E might mean "cheap" or "dying business"
|
||||
- High analyst ratings might mean "priced in" or "genuine upside"
|
||||
- Strong momentum might mean "trend" or "overbought"
|
||||
|
||||
By combining **8 dimensions**, we get a more complete picture.
|
||||
|
||||
### 2. Contrarian Signals Matter
|
||||
|
||||
Some of our best signals are **contrarian**:
|
||||
|
||||
| Indicator | Crowd Says | We Interpret |
|
||||
|-----------|------------|--------------|
|
||||
| Extreme Fear (Fear & Greed < 25) | "Sell everything!" | Potential buy opportunity |
|
||||
| Extreme Greed (> 75) | "Easy money!" | Caution, reduce exposure |
|
||||
| High Short Interest + Days to Cover | "Stock is doomed" | Squeeze potential |
|
||||
| Insider Buying | (often ignored) | Smart money signal |
|
||||
|
||||
### 3. Timing Matters
|
||||
|
||||
A good stock at the wrong time is a bad trade:
|
||||
|
||||
- **Pre-earnings** — Even strong stocks can gap down 10%+
|
||||
- **Post-spike** — Buying after a 20% run often means buying the top
|
||||
- **Overbought** — RSI > 70 + near 52-week high = high-risk entry
|
||||
|
||||
We detect these timing issues and adjust recommendations accordingly.
|
||||
|
||||
### 4. Context Changes Everything
|
||||
|
||||
The same stock behaves differently in different market regimes:
|
||||
|
||||
| Regime | Characteristics | Impact |
|
||||
|--------|-----------------|--------|
|
||||
| **Bull** | VIX < 20, SPY up | BUY signals more reliable |
|
||||
| **Bear** | VIX > 30, SPY down | Even good stocks fall |
|
||||
| **Risk-Off** | GLD/TLT/UUP rising | Flight to safety, reduce equity |
|
||||
| **Geopolitical** | Crisis keywords | Sector-specific penalties |
|
||||
|
||||
### 5. Dividends Are Different
|
||||
|
||||
Income investors have different priorities than growth investors:
|
||||
|
||||
| Growth Investor | Income Investor |
|
||||
|-----------------|-----------------|
|
||||
| Price appreciation | Dividend yield |
|
||||
| Revenue growth | Payout sustainability |
|
||||
| Market share | Dividend growth rate |
|
||||
| P/E ratio | Safety of payment |
|
||||
|
||||
That's why we have a **separate dividend analysis** module.
|
||||
|
||||
---
|
||||
|
||||
## The 8 Dimensions
|
||||
|
||||
### Why These 8?
|
||||
|
||||
Each dimension captures a different aspect of investment quality:
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ FUNDAMENTAL VALUE │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Earnings │ │ Fundamentals │ │
|
||||
│ │ Surprise │ │ (P/E, etc.) │ │
|
||||
│ │ (30%) │ │ (20%) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ EXTERNAL VALIDATION │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Analyst │ │ Historical │ │
|
||||
│ │ Sentiment │ │ Patterns │ │
|
||||
│ │ (20%) │ │ (10%) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ MARKET ENVIRONMENT │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Market │ │ Sector │ │
|
||||
│ │ Context │ │ Performance │ │
|
||||
│ │ (10%) │ │ (15%) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ TECHNICAL & SENTIMENT │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Momentum │ │ Sentiment │ │
|
||||
│ │ (RSI, range) │ │ (Fear, shorts) │ │
|
||||
│ │ (15%) │ │ (10%) │ │
|
||||
│ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### Weight Rationale
|
||||
|
||||
| Weight | Dimension | Rationale |
|
||||
|--------|-----------|-----------|
|
||||
| 30% | Earnings | Most direct measure of company performance |
|
||||
| 20% | Fundamentals | Long-term value indicators |
|
||||
| 20% | Analysts | Professional consensus (with skepticism) |
|
||||
| 15% | Sector | Relative performance matters |
|
||||
| 15% | Momentum | Trend is your friend (until it isn't) |
|
||||
| 10% | Market | Rising tide lifts all boats |
|
||||
| 10% | Sentiment | Contrarian edge |
|
||||
| 10% | Historical | Past behavior predicts future reactions |
|
||||
|
||||
**Note:** Weights auto-normalize when data is missing.
|
||||
|
||||
---
|
||||
|
||||
## Risk Detection Philosophy
|
||||
|
||||
### "Don't Lose Money"
|
||||
|
||||
Warren Buffett's Rule #1. Our risk detection is designed to **prevent bad entries**:
|
||||
|
||||
1. **Pre-Earnings Hold** — Don't buy right before a binary event
|
||||
2. **Post-Spike Caution** — Don't chase a run-up
|
||||
3. **Overbought Warning** — Technical exhaustion
|
||||
4. **Risk-Off Mode** — When even good stocks fall
|
||||
5. **Geopolitical Flags** — Sector-specific event risk
|
||||
|
||||
### False Positive vs False Negative
|
||||
|
||||
We err on the side of **caution**:
|
||||
|
||||
- Missing a 10% gain is annoying
|
||||
- Catching a 30% loss is devastating
|
||||
|
||||
That's why our caveats are prominent, and we downgrade BUY → HOLD liberally.
|
||||
|
||||
---
|
||||
|
||||
## Crypto Adaptation
|
||||
|
||||
Crypto is fundamentally different from stocks:
|
||||
|
||||
| Stocks | Crypto |
|
||||
|--------|--------|
|
||||
| Earnings | No earnings |
|
||||
| P/E Ratio | Market cap tiers |
|
||||
| Sector ETFs | BTC correlation |
|
||||
| Dividends | Staking yields (not tracked) |
|
||||
| SEC Filings | No filings |
|
||||
|
||||
We adapted the framework:
|
||||
- **3 dimensions** instead of 8
|
||||
- **BTC correlation** as a key metric
|
||||
- **Category classification** (L1, DeFi, etc.)
|
||||
- **No sentiment** (no insider data for crypto)
|
||||
|
||||
---
|
||||
|
||||
## Why Not Just Use [X]?
|
||||
|
||||
### vs. Stock Screeners (Finviz, etc.)
|
||||
- Screeners show data, we provide **recommendations**
|
||||
- We combine fundamental + technical + sentiment
|
||||
- We flag timing and risk issues
|
||||
|
||||
### vs. Analyst Reports
|
||||
- Analysts have conflicts of interest
|
||||
- Reports are often stale
|
||||
- We aggregate multiple signals
|
||||
|
||||
### vs. Trading Bots
|
||||
- Bots execute, we advise
|
||||
- We explain reasoning
|
||||
- Human stays in control
|
||||
|
||||
### vs. ChatGPT/AI Chat
|
||||
- We have **structured scoring**, not just conversation
|
||||
- Real-time data fetching
|
||||
- Consistent methodology
|
||||
|
||||
---
|
||||
|
||||
## Limitations We Acknowledge
|
||||
|
||||
1. **Data Lag** — Yahoo Finance is 15-20 min delayed
|
||||
2. **US Focus** — International stocks have incomplete data
|
||||
3. **No Execution** — We advise, you decide and execute
|
||||
4. **Past ≠ Future** — All models have limits
|
||||
5. **Black Swans** — Can't predict unpredictable events
|
||||
|
||||
**This is a tool, not a crystal ball.**
|
||||
|
||||
---
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
Stock Analysis v6.0 is designed to be your **systematic second opinion**:
|
||||
|
||||
- ✅ Multi-dimensional analysis
|
||||
- ✅ Clear recommendations
|
||||
- ✅ Risk detection
|
||||
- ✅ Explained reasoning
|
||||
- ✅ Fast and automated
|
||||
|
||||
**NOT:**
|
||||
- ❌ Financial advice
|
||||
- ❌ Guaranteed returns
|
||||
- ❌ Replacement for research
|
||||
- ❌ Trading signals
|
||||
|
||||
Use it wisely. 📈
|
||||
288
docs/HOT_SCANNER.md
Normal file
288
docs/HOT_SCANNER.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 🔥 Hot Scanner
|
||||
|
||||
Find viral stocks & crypto trends in real-time by aggregating multiple data sources.
|
||||
|
||||
## Overview
|
||||
|
||||
The Hot Scanner answers one question: **"What's hot right now?"**
|
||||
|
||||
It aggregates data from:
|
||||
- CoinGecko (trending coins, biggest movers)
|
||||
- Google News (finance & crypto headlines)
|
||||
- Yahoo Finance (gainers, losers, most active)
|
||||
- Twitter/X (social sentiment, optional)
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Full scan with all sources
|
||||
python3 scripts/hot_scanner.py
|
||||
|
||||
# Skip social media (faster)
|
||||
python3 scripts/hot_scanner.py --no-social
|
||||
|
||||
# JSON output for automation
|
||||
python3 scripts/hot_scanner.py --json
|
||||
```
|
||||
|
||||
## Output Format
|
||||
|
||||
### Console Output
|
||||
|
||||
```
|
||||
============================================================
|
||||
🔥 HOT SCANNER v2 - What's Trending Right Now?
|
||||
📅 2026-02-02 10:45:30 UTC
|
||||
============================================================
|
||||
|
||||
📊 TOP TRENDING (by buzz):
|
||||
1. BTC (6 pts) [CoinGecko, Google News] 📉 bearish (-2.5%)
|
||||
2. ETH (5 pts) [CoinGecko, Twitter] 📉 bearish (-7.2%)
|
||||
3. NVDA (3 pts) [Google News, Yahoo] 📰 Earnings beat...
|
||||
|
||||
🪙 CRYPTO HIGHLIGHTS:
|
||||
🚀 RIVER River +14.0%
|
||||
📉 BTC Bitcoin -2.5%
|
||||
📉 ETH Ethereum -7.2%
|
||||
|
||||
📈 STOCK MOVERS:
|
||||
🟢 NVDA (gainers)
|
||||
🔴 TSLA (losers)
|
||||
📊 AAPL (most active)
|
||||
|
||||
🐦 SOCIAL BUZZ:
|
||||
[twitter] Bitcoin to $100k prediction...
|
||||
[reddit_wsb] GME yolo update...
|
||||
|
||||
📰 BREAKING NEWS:
|
||||
[BTC, ETH] Crypto crash: $2.5B liquidated...
|
||||
[NVDA] Nvidia beats earnings expectations...
|
||||
```
|
||||
|
||||
### JSON Output
|
||||
|
||||
```json
|
||||
{
|
||||
"scan_time": "2026-02-02T10:45:30+00:00",
|
||||
"top_trending": [
|
||||
{
|
||||
"symbol": "BTC",
|
||||
"mentions": 6,
|
||||
"sources": ["CoinGecko Trending", "Google News"],
|
||||
"signals": ["📉 bearish (-2.5%)"]
|
||||
}
|
||||
],
|
||||
"crypto_highlights": [...],
|
||||
"stock_highlights": [...],
|
||||
"social_buzz": [...],
|
||||
"breaking_news": [...]
|
||||
}
|
||||
```
|
||||
|
||||
## Data Sources
|
||||
|
||||
### CoinGecko (No Auth Required)
|
||||
|
||||
| Endpoint | Data |
|
||||
|----------|------|
|
||||
| `/search/trending` | Top 15 trending coins |
|
||||
| `/coins/markets` | Top 100 by market cap with 24h changes |
|
||||
|
||||
**Scoring:** Trending coins get 2 points, movers with >3% change get 1 point.
|
||||
|
||||
### Google News RSS (No Auth Required)
|
||||
|
||||
| Feed | Content |
|
||||
|------|---------|
|
||||
| Business News | General finance headlines |
|
||||
| Crypto Search | Bitcoin, Ethereum, crypto keywords |
|
||||
|
||||
**Ticker Extraction:** Uses regex patterns and company name mappings.
|
||||
|
||||
### Yahoo Finance (No Auth Required)
|
||||
|
||||
| Page | Data |
|
||||
|------|------|
|
||||
| `/gainers` | Top gaining stocks |
|
||||
| `/losers` | Top losing stocks |
|
||||
| `/most-active` | Highest volume stocks |
|
||||
|
||||
**Note:** Requires gzip decompression.
|
||||
|
||||
### Twitter/X (Auth Required)
|
||||
|
||||
Uses [bird CLI](https://github.com/steipete/bird) for Twitter search.
|
||||
|
||||
**Searches:**
|
||||
- `stock OR $SPY OR $QQQ OR earnings`
|
||||
- `bitcoin OR ethereum OR crypto OR $BTC`
|
||||
|
||||
## Twitter/X Setup
|
||||
|
||||
### 1. Install bird CLI
|
||||
|
||||
```bash
|
||||
# macOS
|
||||
brew install steipete/tap/bird
|
||||
|
||||
# npm
|
||||
npm install -g @steipete/bird
|
||||
```
|
||||
|
||||
### 2. Get Auth Tokens
|
||||
|
||||
**Option A: Browser cookies (macOS)**
|
||||
1. Login to x.com in Safari/Chrome
|
||||
2. Grant Terminal "Full Disk Access" in System Settings
|
||||
3. Run `bird whoami` to verify
|
||||
|
||||
**Option B: Manual extraction**
|
||||
1. Open x.com in Chrome
|
||||
2. DevTools (F12) → Application → Cookies → x.com
|
||||
3. Copy `auth_token` and `ct0` values
|
||||
|
||||
### 3. Configure
|
||||
|
||||
Create `.env` file in the skill directory:
|
||||
|
||||
```bash
|
||||
# /path/to/stock-analysis/.env
|
||||
AUTH_TOKEN=your_auth_token_here
|
||||
CT0=your_ct0_token_here
|
||||
```
|
||||
|
||||
Or export as environment variables:
|
||||
|
||||
```bash
|
||||
export AUTH_TOKEN="..."
|
||||
export CT0="..."
|
||||
```
|
||||
|
||||
### 4. Verify
|
||||
|
||||
```bash
|
||||
bird whoami
|
||||
# Should show: 🙋 @YourUsername
|
||||
```
|
||||
|
||||
## Scoring System
|
||||
|
||||
Each mention from a source adds points:
|
||||
|
||||
| Source | Points |
|
||||
|--------|--------|
|
||||
| CoinGecko Trending | 2 |
|
||||
| CoinGecko Movers | 1 |
|
||||
| Google News | 1 |
|
||||
| Yahoo Finance | 1 |
|
||||
| Twitter/X | 1 |
|
||||
| Reddit (high score) | 2 |
|
||||
| Reddit (normal) | 1 |
|
||||
|
||||
Symbols are ranked by total points across all sources.
|
||||
|
||||
## Ticker Extraction
|
||||
|
||||
### Patterns
|
||||
|
||||
```python
|
||||
# Cashtag: $AAPL
|
||||
r'\$([A-Z]{1,5})\b'
|
||||
|
||||
# Parentheses: (AAPL)
|
||||
r'\(([A-Z]{2,5})\)'
|
||||
|
||||
# Stock mentions: AAPL stock, AAPL shares
|
||||
r'\b([A-Z]{2,5})(?:\'s|:|\s+stock|\s+shares)'
|
||||
```
|
||||
|
||||
### Company Mappings
|
||||
|
||||
```python
|
||||
{
|
||||
"Apple": "AAPL",
|
||||
"Microsoft": "MSFT",
|
||||
"Tesla": "TSLA",
|
||||
"Nvidia": "NVDA",
|
||||
"Bitcoin": "BTC",
|
||||
"Ethereum": "ETH",
|
||||
# ... etc
|
||||
}
|
||||
```
|
||||
|
||||
### Crypto Keywords
|
||||
|
||||
```python
|
||||
{
|
||||
"bitcoin": "BTC",
|
||||
"ethereum": "ETH",
|
||||
"solana": "SOL",
|
||||
"dogecoin": "DOGE",
|
||||
# ... etc
|
||||
}
|
||||
```
|
||||
|
||||
## Automation
|
||||
|
||||
### Cron Job
|
||||
|
||||
```bash
|
||||
# Daily at 8 AM
|
||||
0 8 * * * cd /path/to/stock-analysis && python3 scripts/hot_scanner.py --json > cache/daily_scan.json
|
||||
```
|
||||
|
||||
### OpenClaw Integration
|
||||
|
||||
```yaml
|
||||
# Cron job config
|
||||
name: "🔥 Daily Hot Scanner"
|
||||
schedule:
|
||||
kind: cron
|
||||
expr: "0 8 * * *"
|
||||
tz: "Europe/Berlin"
|
||||
payload:
|
||||
kind: agentTurn
|
||||
message: "Run hot scanner and summarize results"
|
||||
deliver: true
|
||||
sessionTarget: isolated
|
||||
```
|
||||
|
||||
## Caching
|
||||
|
||||
Results are saved to:
|
||||
- `cache/hot_scan_latest.json` — Most recent scan
|
||||
|
||||
## Limitations
|
||||
|
||||
- **Reddit:** Blocked without OAuth (403). Requires API application.
|
||||
- **Twitter:** Requires auth tokens, may expire.
|
||||
- **Yahoo:** Sometimes rate-limited.
|
||||
- **Google News:** RSS URLs may change.
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
- [ ] Reddit API integration (PRAW)
|
||||
- [ ] StockTwits integration
|
||||
- [ ] Google Trends
|
||||
- [ ] Historical trend tracking
|
||||
- [ ] Alert thresholds (notify when score > X)
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Twitter not working
|
||||
|
||||
```bash
|
||||
# Check auth
|
||||
bird whoami
|
||||
|
||||
# Should see your username
|
||||
# If not, re-export tokens
|
||||
```
|
||||
|
||||
### Yahoo 403 or gzip errors
|
||||
|
||||
The scanner handles gzip automatically. If issues persist, Yahoo may be rate-limiting.
|
||||
|
||||
### No tickers found
|
||||
|
||||
Check that news headlines contain recognizable patterns. The scanner uses conservative extraction to avoid false positives.
|
||||
95
docs/README.md
Normal file
95
docs/README.md
Normal file
@@ -0,0 +1,95 @@
|
||||
# Documentation
|
||||
|
||||
## Stock Analysis v6.1
|
||||
|
||||
This folder contains detailed documentation for the Stock Analysis skill.
|
||||
|
||||
## Contents
|
||||
|
||||
| Document | Description |
|
||||
|----------|-------------|
|
||||
| [CONCEPT.md](./CONCEPT.md) | Philosophy, ideas, and design rationale |
|
||||
| [USAGE.md](./USAGE.md) | Practical usage guide with examples |
|
||||
| [ARCHITECTURE.md](./ARCHITECTURE.md) | Technical implementation details |
|
||||
| [HOT_SCANNER.md](./HOT_SCANNER.md) | 🔥 Viral trend detection (NEW) |
|
||||
|
||||
## Quick Links
|
||||
|
||||
### For Users
|
||||
|
||||
Start with **[USAGE.md](./USAGE.md)** — it has practical examples for:
|
||||
- Basic stock analysis
|
||||
- Comparing stocks
|
||||
- Crypto analysis
|
||||
- Dividend investing
|
||||
- Portfolio management
|
||||
- Watchlist & alerts
|
||||
|
||||
### For Understanding
|
||||
|
||||
Read **[CONCEPT.md](./CONCEPT.md)** to understand:
|
||||
- Why 8 dimensions?
|
||||
- How scoring works
|
||||
- Contrarian signals
|
||||
- Risk detection philosophy
|
||||
- Limitations we acknowledge
|
||||
|
||||
### For Developers
|
||||
|
||||
Check **[ARCHITECTURE.md](./ARCHITECTURE.md)** for:
|
||||
- System overview diagram
|
||||
- Data flow
|
||||
- Caching strategy
|
||||
- File structure
|
||||
- Performance optimization
|
||||
|
||||
## Quick Start
|
||||
|
||||
```bash
|
||||
# Analyze a stock
|
||||
uv run scripts/analyze_stock.py AAPL
|
||||
|
||||
# Fast mode (2-3 seconds)
|
||||
uv run scripts/analyze_stock.py AAPL --fast
|
||||
|
||||
# Dividend analysis
|
||||
uv run scripts/dividends.py JNJ
|
||||
|
||||
# Watchlist
|
||||
uv run scripts/watchlist.py add AAPL --target 200
|
||||
uv run scripts/watchlist.py check
|
||||
```
|
||||
|
||||
## Key Concepts
|
||||
|
||||
### The 8 Dimensions
|
||||
|
||||
1. **Earnings Surprise** (30%) — Did they beat expectations?
|
||||
2. **Fundamentals** (20%) — P/E, margins, growth, debt
|
||||
3. **Analyst Sentiment** (20%) — Professional consensus
|
||||
4. **Historical Patterns** (10%) — Past earnings reactions
|
||||
5. **Market Context** (10%) — VIX, SPY/QQQ trends
|
||||
6. **Sector Performance** (15%) — Relative strength
|
||||
7. **Momentum** (15%) — RSI, 52-week range
|
||||
8. **Sentiment** (10%) — Fear/Greed, shorts, insiders
|
||||
|
||||
### Signal Thresholds
|
||||
|
||||
| Score | Recommendation |
|
||||
|-------|----------------|
|
||||
| > +0.33 | **BUY** |
|
||||
| -0.33 to +0.33 | **HOLD** |
|
||||
| < -0.33 | **SELL** |
|
||||
|
||||
### Risk Flags
|
||||
|
||||
- ⚠️ Pre-earnings (< 14 days)
|
||||
- ⚠️ Post-spike (> 15% in 5 days)
|
||||
- ⚠️ Overbought (RSI > 70 + near 52w high)
|
||||
- ⚠️ Risk-off mode (GLD/TLT/UUP rising)
|
||||
- ⚠️ Geopolitical keywords
|
||||
- ⚠️ Breaking news alerts
|
||||
|
||||
## Disclaimer
|
||||
|
||||
⚠️ **NOT FINANCIAL ADVICE.** For informational purposes only. Always do your own research and consult a licensed financial advisor.
|
||||
465
docs/USAGE.md
Normal file
465
docs/USAGE.md
Normal file
@@ -0,0 +1,465 @@
|
||||
# Usage Guide
|
||||
|
||||
Practical examples for using Stock Analysis v6.0 in real scenarios.
|
||||
|
||||
## Table of Contents
|
||||
|
||||
1. [Basic Stock Analysis](#basic-stock-analysis)
|
||||
2. [Comparing Stocks](#comparing-stocks)
|
||||
3. [Crypto Analysis](#crypto-analysis)
|
||||
4. [Dividend Investing](#dividend-investing)
|
||||
5. [Portfolio Management](#portfolio-management)
|
||||
6. [Watchlist & Alerts](#watchlist--alerts)
|
||||
7. [Performance Tips](#performance-tips)
|
||||
8. [Interpreting Results](#interpreting-results)
|
||||
|
||||
---
|
||||
|
||||
## Basic Stock Analysis
|
||||
|
||||
### Single Stock
|
||||
|
||||
```bash
|
||||
uv run scripts/analyze_stock.py AAPL
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
===========================================================================
|
||||
STOCK ANALYSIS: AAPL (Apple Inc.)
|
||||
Generated: 2024-02-01T10:30:00
|
||||
===========================================================================
|
||||
|
||||
RECOMMENDATION: BUY (Confidence: 72%)
|
||||
|
||||
SUPPORTING POINTS:
|
||||
• Beat by 8.2% - EPS $2.18 vs $2.01 expected
|
||||
• Strong margin: 24.1%
|
||||
• Analyst consensus: Buy with 12.3% upside (42 analysts)
|
||||
• Momentum: RSI 58 (neutral)
|
||||
• Sector: Technology uptrend (+5.2% 1m)
|
||||
|
||||
CAVEATS:
|
||||
• Earnings in 12 days - high volatility expected
|
||||
• High market volatility (VIX 24)
|
||||
|
||||
===========================================================================
|
||||
DISCLAIMER: NOT FINANCIAL ADVICE.
|
||||
===========================================================================
|
||||
```
|
||||
|
||||
### JSON Output
|
||||
|
||||
For programmatic use:
|
||||
|
||||
```bash
|
||||
uv run scripts/analyze_stock.py AAPL --output json | jq '.recommendation, .confidence'
|
||||
```
|
||||
|
||||
### Verbose Mode
|
||||
|
||||
See what's happening under the hood:
|
||||
|
||||
```bash
|
||||
uv run scripts/analyze_stock.py AAPL --verbose
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparing Stocks
|
||||
|
||||
### Side-by-Side Analysis
|
||||
|
||||
```bash
|
||||
uv run scripts/analyze_stock.py AAPL MSFT GOOGL
|
||||
```
|
||||
|
||||
Each stock gets a full analysis. Compare recommendations and confidence levels.
|
||||
|
||||
### Sector Comparison
|
||||
|
||||
Compare stocks in the same sector:
|
||||
|
||||
```bash
|
||||
# Banks
|
||||
uv run scripts/analyze_stock.py JPM BAC WFC GS
|
||||
|
||||
# Tech
|
||||
uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Crypto Analysis
|
||||
|
||||
### Basic Crypto
|
||||
|
||||
```bash
|
||||
uv run scripts/analyze_stock.py BTC-USD
|
||||
```
|
||||
|
||||
**Crypto-Specific Output:**
|
||||
- Market cap classification (large/mid/small)
|
||||
- Category (Smart Contract L1, DeFi, etc.)
|
||||
- BTC correlation (30-day)
|
||||
- Momentum (RSI, price range)
|
||||
|
||||
### Compare Cryptos
|
||||
|
||||
```bash
|
||||
uv run scripts/analyze_stock.py BTC-USD ETH-USD SOL-USD
|
||||
```
|
||||
|
||||
### Supported Cryptos
|
||||
|
||||
```
|
||||
BTC, ETH, BNB, SOL, XRP, ADA, DOGE, AVAX, DOT, MATIC,
|
||||
LINK, ATOM, UNI, LTC, BCH, XLM, ALGO, VET, FIL, NEAR
|
||||
```
|
||||
|
||||
Use `-USD` suffix: `BTC-USD`, `ETH-USD`, etc.
|
||||
|
||||
---
|
||||
|
||||
## Dividend Investing
|
||||
|
||||
### Analyze Dividend Stock
|
||||
|
||||
```bash
|
||||
uv run scripts/dividends.py JNJ
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
============================================================
|
||||
DIVIDEND ANALYSIS: JNJ (Johnson & Johnson)
|
||||
============================================================
|
||||
|
||||
Current Price: $160.50
|
||||
Annual Dividend: $4.76
|
||||
Dividend Yield: 2.97%
|
||||
Payment Freq: quarterly
|
||||
Ex-Dividend: 2024-02-15
|
||||
|
||||
Payout Ratio: 65.0% (moderate)
|
||||
5Y Div Growth: +5.8%
|
||||
Consecutive Yrs: 62
|
||||
|
||||
SAFETY SCORE: 78/100
|
||||
INCOME RATING: GOOD
|
||||
|
||||
Safety Factors:
|
||||
• Moderate payout ratio (65%)
|
||||
• Good dividend growth (+5.8% CAGR)
|
||||
• Dividend Aristocrat (62+ years)
|
||||
|
||||
Dividend History:
|
||||
2023: $4.52
|
||||
2022: $4.36
|
||||
2021: $4.24
|
||||
2020: $4.04
|
||||
2019: $3.80
|
||||
============================================================
|
||||
```
|
||||
|
||||
### Compare Dividend Stocks
|
||||
|
||||
```bash
|
||||
uv run scripts/dividends.py JNJ PG KO MCD VZ T
|
||||
```
|
||||
|
||||
### Dividend Aristocrats Screen
|
||||
|
||||
Look for stocks with:
|
||||
- Yield > 2%
|
||||
- Payout < 60%
|
||||
- Growth > 5%
|
||||
- Consecutive years > 25
|
||||
|
||||
---
|
||||
|
||||
## Portfolio Management
|
||||
|
||||
### Create Portfolio
|
||||
|
||||
```bash
|
||||
uv run scripts/portfolio.py create "Retirement"
|
||||
```
|
||||
|
||||
### Add Holdings
|
||||
|
||||
```bash
|
||||
# Stocks
|
||||
uv run scripts/portfolio.py add AAPL --quantity 100 --cost 150.00
|
||||
|
||||
# Crypto
|
||||
uv run scripts/portfolio.py add BTC-USD --quantity 0.5 --cost 40000
|
||||
```
|
||||
|
||||
### View Portfolio
|
||||
|
||||
```bash
|
||||
uv run scripts/portfolio.py show
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```
|
||||
Portfolio: Retirement
|
||||
====================
|
||||
|
||||
Assets:
|
||||
AAPL 100 shares @ $150.00 = $15,000.00
|
||||
Current: $185.00 = $18,500.00 (+23.3%)
|
||||
|
||||
BTC-USD 0.5 @ $40,000 = $20,000.00
|
||||
Current: $45,000 = $22,500.00 (+12.5%)
|
||||
|
||||
Total Cost: $35,000.00
|
||||
Current Value: $41,000.00
|
||||
Total P&L: +$6,000.00 (+17.1%)
|
||||
```
|
||||
|
||||
### Analyze Portfolio
|
||||
|
||||
```bash
|
||||
# Full analysis of all holdings
|
||||
uv run scripts/analyze_stock.py --portfolio "Retirement"
|
||||
|
||||
# With period returns
|
||||
uv run scripts/analyze_stock.py --portfolio "Retirement" --period monthly
|
||||
```
|
||||
|
||||
### Rebalance Check
|
||||
|
||||
The analysis flags concentration warnings:
|
||||
```
|
||||
⚠️ CONCENTRATION WARNINGS:
|
||||
• AAPL: 45.1% (>30% of portfolio)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Watchlist & Alerts
|
||||
|
||||
### Add to Watchlist
|
||||
|
||||
```bash
|
||||
# Basic watch
|
||||
uv run scripts/watchlist.py add NVDA
|
||||
|
||||
# With price target
|
||||
uv run scripts/watchlist.py add NVDA --target 800
|
||||
|
||||
# With stop loss
|
||||
uv run scripts/watchlist.py add NVDA --stop 600
|
||||
|
||||
# Alert on signal change
|
||||
uv run scripts/watchlist.py add NVDA --alert-on signal
|
||||
|
||||
# All options
|
||||
uv run scripts/watchlist.py add NVDA --target 800 --stop 600 --alert-on signal
|
||||
```
|
||||
|
||||
### View Watchlist
|
||||
|
||||
```bash
|
||||
uv run scripts/watchlist.py list
|
||||
```
|
||||
|
||||
**Output:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"items": [
|
||||
{
|
||||
"ticker": "NVDA",
|
||||
"current_price": 725.50,
|
||||
"price_at_add": 700.00,
|
||||
"change_pct": 3.64,
|
||||
"target_price": 800.00,
|
||||
"to_target_pct": 10.27,
|
||||
"stop_price": 600.00,
|
||||
"to_stop_pct": -17.30,
|
||||
"alert_on_signal": true,
|
||||
"last_signal": "BUY",
|
||||
"added_at": "2024-01-15"
|
||||
}
|
||||
],
|
||||
"count": 1
|
||||
}
|
||||
```
|
||||
|
||||
### Check Alerts
|
||||
|
||||
```bash
|
||||
# Check for triggered alerts
|
||||
uv run scripts/watchlist.py check
|
||||
|
||||
# Format for notification (Telegram)
|
||||
uv run scripts/watchlist.py check --notify
|
||||
```
|
||||
|
||||
**Alert Example:**
|
||||
```
|
||||
📢 Stock Alerts
|
||||
|
||||
🎯 NVDA hit target! $802.50 >= $800.00
|
||||
🛑 TSLA hit stop! $195.00 <= $200.00
|
||||
📊 AAPL signal changed: HOLD → BUY
|
||||
```
|
||||
|
||||
### Remove from Watchlist
|
||||
|
||||
```bash
|
||||
uv run scripts/watchlist.py remove NVDA
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Fast Mode
|
||||
|
||||
Skip slow analyses for quick checks:
|
||||
|
||||
```bash
|
||||
# Skip insider trading + breaking news
|
||||
uv run scripts/analyze_stock.py AAPL --fast
|
||||
```
|
||||
|
||||
**Speed comparison:**
|
||||
| Mode | Time | What's Skipped |
|
||||
|------|------|----------------|
|
||||
| Default | 5-10s | Nothing |
|
||||
| `--no-insider` | 3-5s | SEC EDGAR |
|
||||
| `--fast` | 2-3s | Insider + News |
|
||||
|
||||
### Batch Analysis
|
||||
|
||||
Analyze multiple stocks in one command:
|
||||
|
||||
```bash
|
||||
uv run scripts/analyze_stock.py AAPL MSFT GOOGL AMZN META
|
||||
```
|
||||
|
||||
### Caching
|
||||
|
||||
Market context is cached for 1 hour:
|
||||
- VIX, SPY, QQQ trends
|
||||
- Fear & Greed Index
|
||||
- VIX term structure
|
||||
- Breaking news
|
||||
|
||||
Second analysis of different stock reuses cached data.
|
||||
|
||||
---
|
||||
|
||||
## Interpreting Results
|
||||
|
||||
### Recommendation Thresholds
|
||||
|
||||
| Score | Recommendation |
|
||||
|-------|----------------|
|
||||
| > +0.33 | BUY |
|
||||
| -0.33 to +0.33 | HOLD |
|
||||
| < -0.33 | SELL |
|
||||
|
||||
### Confidence Levels
|
||||
|
||||
| Confidence | Meaning |
|
||||
|------------|---------|
|
||||
| > 80% | Strong conviction |
|
||||
| 60-80% | Moderate conviction |
|
||||
| 40-60% | Mixed signals |
|
||||
| < 40% | Low conviction |
|
||||
|
||||
### Reading Caveats
|
||||
|
||||
**Always read the caveats!** They often contain critical information:
|
||||
|
||||
```
|
||||
CAVEATS:
|
||||
• Earnings in 5 days - high volatility expected ← Timing risk
|
||||
• RSI 78 (overbought) + near 52w high ← Technical risk
|
||||
• ⚠️ BREAKING NEWS: Fed emergency rate discussion ← External risk
|
||||
• ⚠️ SECTOR RISK: China tensions affect tech ← Geopolitical
|
||||
```
|
||||
|
||||
### When to Ignore the Signal
|
||||
|
||||
- **Pre-earnings:** Even BUY → wait until after
|
||||
- **Overbought:** Consider smaller position
|
||||
- **Risk-off:** Reduce overall exposure
|
||||
- **Low confidence:** Do more research
|
||||
|
||||
### When to Trust the Signal
|
||||
|
||||
- **High confidence + no major caveats**
|
||||
- **Multiple supporting points align**
|
||||
- **Sector is strong**
|
||||
- **Market regime is favorable**
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Morning Check
|
||||
|
||||
```bash
|
||||
# Check watchlist alerts
|
||||
uv run scripts/watchlist.py check --notify
|
||||
|
||||
# Quick portfolio update
|
||||
uv run scripts/analyze_stock.py --portfolio "Main" --fast
|
||||
```
|
||||
|
||||
### Research New Stock
|
||||
|
||||
```bash
|
||||
# Full analysis
|
||||
uv run scripts/analyze_stock.py XYZ
|
||||
|
||||
# If dividend stock
|
||||
uv run scripts/dividends.py XYZ
|
||||
|
||||
# Add to watchlist for monitoring
|
||||
uv run scripts/watchlist.py add XYZ --alert-on signal
|
||||
```
|
||||
|
||||
### Weekly Review
|
||||
|
||||
```bash
|
||||
# Full portfolio analysis
|
||||
uv run scripts/analyze_stock.py --portfolio "Main" --period weekly
|
||||
|
||||
# Check dividend holdings
|
||||
uv run scripts/dividends.py JNJ PG KO
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Invalid ticker"
|
||||
|
||||
- Check spelling
|
||||
- For crypto, use `-USD` suffix
|
||||
- Non-US stocks may not work
|
||||
|
||||
### "Insufficient data"
|
||||
|
||||
- Stock might be too new
|
||||
- ETFs have limited data
|
||||
- OTC stocks often fail
|
||||
|
||||
### Slow Performance
|
||||
|
||||
- Use `--fast` for quick checks
|
||||
- Insider trading is slowest
|
||||
- Breaking news adds ~2s
|
||||
|
||||
### Missing Data
|
||||
|
||||
- Not all stocks have analyst coverage
|
||||
- Some metrics require options chains
|
||||
- Crypto has no sentiment data
|
||||
Reference in New Issue
Block a user