# ARD: Analyzing Market Sentiment > This skill implements a multi-source data aggregation pattern with weighted composite scoring. - Skill: `tools-only/ard-analyzing-market-sentiment` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/ard-analyzing-market-sentiment` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/ard-analyzing-market-sentiment/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/ard-analyzing-market-sentiment --- # ARD: Analyzing Market Sentiment ## Document Control | Field | Value | |-------|-------| | **Skill Name** | analyzing-market-sentiment | | **Architecture Pattern** | Multi-Source Aggregation + Scoring | | **Version** | 2.0.0 | | **Author** | Jeremy Longshore | --- ## Architectural Overview ### Pattern: Composite Scoring Pipeline This skill implements a multi-source data aggregation pattern with weighted composite scoring. ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ MARKET SENTIMENT ANALYZER ARCHITECTURE │ └─────────────────────────────────────────────────────────────────────────────┘ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ Fear & Greed │ │ News Articles │ │ Market Data │ │ Index │ │ (RSS/Aggregator)│ │ (CoinGecko) │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ ▼ ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ F&G FETCHER │ │ NEWS FETCHER │ │ MARKET FETCHER │ │ - API call │ │ - RSS parsing │ │ - Price data │ │ - Caching │ │ - Deduplication │ │ - Volume data │ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ │ │ │ ▼ │ │ ┌──────────────────┐ │ │ │ NEWS SCORER │ │ │ │ - Keyword match │ │ │ │ - Sentiment │ │ │ │ - Aggregation │ │ │ └────────┬─────────┘ │ │ │ │ └────────────────────────┼────────────────────────┘ │ ▼ ┌─────────────────────────┐ │ COMPOSITE CALCULATOR │ │ - Weight application │ │ - Score normalization │ │ - Classification │ └────────────┬────────────┘ │ ▼ ┌─────────────────────────┐ │ FORMATTER │ │ - Dashboard view │ │ - JSON export │ │ - CSV export │ └─────────────────────────┘ ``` ### Workflow 1. **Fetch**: Parallel data retrieval from multiple sources 2. **Score**: Analyze news sentiment using keyword matching 3. **Calculate**: Compute weighted composite score 4. **Classify**: Map score to sentiment classification 5. **Format**: Output in requested format --- ## Progressive Disclosure Strategy ### Level 1: Quick Sentiment Check (Default) ```bash python sentiment_analyzer.py ``` Returns overall sentiment score and classification. ### Level 2: Coin-Specific Analysis ```bash python sentiment_analyzer.py --coin BTC ``` Adds coin-specific sentiment breakdown. ### Level 3: Detailed Analysis ```bash python sentiment_analyzer.py --detailed --period 24h ``` Full breakdown with news article scores. ### Level 4: Export with Custom Weights ```bash python sentiment_analyzer.py --format json --weights "news:0.5,fng:0.3,momentum:0.2" ``` Custom weighting and JSON export. --- ## Tool Permission Strategy ### Allowed Tools (Scoped) ```yaml allowed-tools: Read, Bash(crypto:sentiment-*) ``` | Tool | Scope | Purpose | |------|-------|---------| | Read | Unrestricted | Read config, cached data | | Bash | `crypto:sentiment-*` | Execute sentiment analysis scripts | ### Why These Tools - **Read**: Load configuration and cached sentiment data - **Bash(crypto:sentiment-*)**: Execute Python scripts for analysis - **No Write**: Analysis is read-only; exports use script file output --- ## Directory Structure ``` plugins/crypto/market-sentiment-analyzer/ └── skills/ └── analyzing-market-sentiment/ ├── PRD.md # Product requirements ├── ARD.md # This file ├── SKILL.md # Core instructions ├── scripts/ │ ├── sentiment_analyzer.py # Main CLI entry point │ ├── fear_greed.py # Fear & Greed Index fetcher │ ├── news_sentiment.py # News sentiment scoring │ ├── market_momentum.py # Market momentum calculation │ └── formatters.py # Output formatting ├── references/ │ ├── errors.md # Error handling guide │ └── examples.md # Usage examples └── config/ └── settings.yaml # Configuration options ``` --- ## Data Flow Architecture ### Input - User request with optional filters (--coin, --period, --detailed) - External API data (Fear & Greed, news, market) ### Processing Pipeline ``` Input Request │ ├──► Fetch Fear & Greed Index │ │ │ ▼ │ Score: 0-100, Classification │ ├──► Fetch News (RSS or aggregator) │ │ │ ▼ │ Score each article (-1 to +1) │ │ │ ▼ │ Aggregate: weighted average │ │ │ ▼ │ Normalize to 0-100 │ ├──► Fetch Market Data │ │ │ ▼ │ Calculate momentum (price change, volume) │ │ │ ▼ │ Normalize to 0-100 │ └──► Calculate Composite Score │ ▼ Weighted Sum: - News: 40% - Fear & Greed: 40% - Momentum: 20% │ ▼ Classify: - 0-20: Extreme Fear - 21-40: Fear - 41-60: Neutral - 61-80: Greed - 81-100: Extreme Greed ``` ### Output Schema ```json { "composite_score": 65.5, "classification": "Greed", "components": { "fear_greed": { "score": 72, "classification": "Greed", "weight": 0.40, "contribution": 28.8 }, "news_sentiment": { "score": 58.5, "articles_analyzed": 25, "positive": 12, "negative": 5, "neutral": 8, "weight": 0.40, "contribution": 23.4 }, "market_momentum": { "score": 66.5, "btc_change_24h": 3.5, "volume_ratio": 1.2, "weight": 0.20, "contribution": 13.3 } }, "meta": { "timestamp": "2026-01-14T15:30:00Z", "period": "24h", "coin_filter": null, "data_freshness": { "fear_greed": "5 min", "news": "2 min", "market": "1 min" } } } ``` --- ## Sentiment Scoring Algorithm ### News Sentiment Scoring ```python # Per-article scoring def score_article(title: str, summary: str) -> float: """Score article from -1 (bearish) to +1 (bullish).""" text = f"{title} {summary}".lower() score = 0.0 # Positive keywords positive = ["bullish", "surge", "rally", "breakout", "adoption", "partnership", "approval", "milestone", "record"] for kw in positive: if kw in text: score += 0.2 # Negative keywords negative = ["bearish", "crash", "dump", "hack", "exploit", "ban", "lawsuit", "fraud", "bankruptcy"] for kw in negative: if kw in text: score -= 0.2 return max(-1, min(1, score)) # Aggregate scoring def aggregate_news_sentiment(articles: List[dict]) -> float: """Aggregate article scores to 0-100 scale.""" if not articles: return 50 # Neutral # Weight by recency weighted_sum = 0 weight_total = 0 for article in articles: age_hours = article.get("age_hours", 24) weight = 1 / (1 + age_hours / 12) # Decay over 12 hours weighted_sum += article["score"] * weight weight_total += weight avg_score = weighted_sum / weight_total # -1 to +1 return (avg_score + 1) * 50 # Convert to 0-100 ``` ### Composite Score Calculation ```python def calculate_composite( fear_greed: float, # 0-100 news_sentiment: float, # 0-100 momentum: float, # 0-100 weights: dict = None ) -> float: """Calculate weighted composite sentiment score.""" weights = weights or { "fear_greed": 0.40, "news": 0.40, "momentum": 0.20 } return ( fear_greed * weights["fear_greed"] + news_sentiment * weights["news"] + momentum * weights["momentum"] ) ``` --- ## Error Handling Strategy ### Error Categories | Category | Examples | Strategy | |----------|----------|----------| | API Error | Fear & Greed API down | Use cached value with stale warning | | Network | Timeout, DNS failure | Skip component, partial analysis | | Parse | Invalid JSON response | Log warning, use default | | Data | No news found | Reduce weight, increase other components | ### Graceful Degradation ``` Full Analysis (all components) │ ▼ Partial Analysis (some components failed) │ → Recalculate weights for available data │ → Warn user about missing components │ ▼ Cached Fallback (API failures) │ → Use recent cached values │ → Show "stale data" warning │ ▼ Minimal Analysis (only Fear & Greed) │ → Single source analysis │ → Clear limitations disclosure ``` --- ## Composability & Stacking ### Optional Dependencies - **crypto-news-aggregator**: Enhanced news analysis - If available: Uses aggregator's scored news - If unavailable: Falls back to direct RSS fetch ### As Data Provider Skills that can consume sentiment data: - **crypto-signal-generator**: Sentiment as signal input - **trading-strategy-backtester**: Historical sentiment data ### Integration Pattern ```python # Check for news aggregator NEWS_AGGREGATOR = None try: from pathlib import Path aggregator_path = Path(__file__).parent.parent.parent.parent / \ "crypto-news-aggregator/skills/aggregating-crypto-news/scripts" if (aggregator_path / "news_aggregator.py").exists(): NEWS_AGGREGATOR = aggregator_path except Exception: pass def get_news_for_sentiment(coin: str = None, period: str = "24h"): """Fetch news using aggregator if available, else direct RSS.""" if NEWS_AGGREGATOR: # Use aggregator return fetch_via_aggregator(coin, period) else: # Direct RSS fallback return fetch_direct_rss(coin, period) ``` --- ## Performance & Scalability ### Performance Targets | Metric | Target | Approach | |--------|--------|----------| | Full analysis | < 15s | Parallel API calls | | Quick check | < 5s | Cached Fear & Greed only | | News scoring | < 2s per 100 articles | Efficient keyword matching | ### Optimization Strategies 1. **Parallel Fetching**: Concurrent API calls with asyncio/threading 2. **Caching**: Cache Fear & Greed (5 min TTL), news (2 min TTL) 3. **Lazy Loading**: Only fetch detailed data if --detailed flag 4. **Early Exit**: Return cached data for repeated calls --- ## Testing Strategy ### Unit Tests | Component | Test Cases | |-----------|------------| | FearGreedFetcher | API response parsing, caching, classification | | NewsSentiment | Keyword matching, aggregation, normalization | | CompositeCalculator | Weight application, edge cases | | Formatters | All output formats, empty data handling | ### Integration Tests - End-to-end with mock APIs - Real API tests (daily CI) - Export format validation ### Manual Testing ```bash # Quick check python sentiment_analyzer.py # Coin-specific python sentiment_analyzer.py --coin BTC # Detailed with export python sentiment_analyzer.py --detailed --format json --output sentiment.json ``` --- ## Security & Compliance ### Security Considerations - **No Authentication**: All APIs used are public - **No User Data**: No personal information collected - **Output Only**: Read-only analysis, no state modification ### Rate Limiting - Alternative.me: Respect 10 req/min limit - CoinGecko: Respect free tier limits - Caching reduces API calls significantly