sophhub 0.2.3 → 0.2.4

package/skills/sophnet-stock/src/docs/ARCHITECTURE.md

@@ -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

package/skills/sophnet-stock/src/docs/CONCEPT.md

@@ -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. 📈