tools-only 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 jeremy@intentsolutions.io |
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
- Fetch: Parallel data retrieval from multiple sources
- Score: Analyze news sentiment using keyword matching
- Calculate: Compute weighted composite score
- Classify: Map score to sentiment classification
- Format: Output in requested format
Progressive Disclosure Strategy
Level 1: Quick Sentiment Check (Default)
python sentiment_analyzer.py
Returns overall sentiment score and classification.
Level 2: Coin-Specific Analysis
python sentiment_analyzer.py --coin BTC
Adds coin-specific sentiment breakdown.
Level 3: Detailed Analysis
python sentiment_analyzer.py --detailed --period 24h
Full breakdown with news article scores.
Level 4: Export with Custom Weights
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)
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
{
"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
# 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
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
# 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
- Parallel Fetching: Concurrent API calls with asyncio/threading
- Caching: Cache Fear & Greed (5 min TTL), news (2 min TTL)
- Lazy Loading: Only fetch detailed data if --detailed flag
- 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
# 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