Financial Analysis

Financial Analysis Skill

A multi-source financial analysis engine that aggregates data from 14+ free APIs and 20+ RSS feeds to produce professional-grade stock analysis with actionable buy/sell ratings and price targets.

First-Time Setup

Before using this skill, read the API setup guide and configure API keys:

Copy code
Read references/api_setup_guide.md

Then initialize the config:

bashCopy code
python scripts/api_config.py init
python scripts/api_config.py status

Install Python dependencies:

bashCopy code
pip install yfinance feedparser pandas pandas-ta requests --break-system-packages

Architecture Overview

Copy code
financial-analysis/
├── SKILL.md                          # This file — main instructions
├── scripts/
│   ├── api_config.py                 # API registry, keys, fallback chains
│   ├── usage_tracker.py              # Rate limit enforcement, logging, reports
│   ├── api_caller.py                 # Resilient caller with auto-fallback
│   └── rss_feeds.py                  # RSS feed catalog and parser
└── references/
    └── api_setup_guide.md            # Step-by-step key setup + rate limits

How the API System Works

Every API call flows through scripts/api_caller.py which:

1. Checks rate limits before calling (per-minute, per-day, per-month)
2. Enforces delays between calls to avoid IP blocks
3. Logs every call to ~/.financial-analysis/logs/api_usage.jsonl
4. On failure: logs to error_log.jsonl and tries the next API in the fallback chain
5. On all failures: returns an error with details of every attempt

The tracker at scripts/usage_tracker.py aggregates usage and generates:

• Daily usage reports with % of free limit consumed per API
• Error reports showing which APIs failed and which fallbacks worked
• Paid tier recommendations when any API exceeds 70% of its free limit

Fallback Chains

Every data category has a prioritized chain of APIs. If the primary fails or is rate-limited, the next one is tried automatically. The chains are defined in scripts/api_config.py → FALLBACK_CHAINS. Key chains:

Three Use Cases

This skill supports three distinct workflows. The user will ask for one of them (or you can suggest the appropriate one based on context).

Use Case 1: Weekly Portfolio Review

Trigger: User provides a PDF, CSV, or list of current holdings and asks for a review, analysis, or buy/hold/sell recommendations.

Input: Portfolio holdings (tickers + optional quantities/cost basis) Output: Per-ticker rating (Buy / Hold / Trim / Sell) with confidence score, 3 entry levels, 3 sell targets, and key reasons. Frequency: Once per week (Sunday/Monday)

Workflow

Execute these phases in order. Use call_with_fallback() from scripts/api_caller.py for every API call to get automatic fallback + logging.

Phase A — Data Collection (for each ticker in portfolio):

1. Fetch current price + 1yr daily OHLCV history (yfinance)
2. Pull quarterly financial statements: income, balance sheet, cash flow (yfinance + SEC EDGAR)
3. Get analyst ratings consensus: buy/hold/sell counts (Finnhub)
4. Scan insider activity last 90 days: Form 4 filings (SEC EDGAR)
5. Check insider sentiment score: MSPR (Finnhub)
6. Pull front-month options chain (yfinance)
7. Get news sentiment (Finnhub + Alpha Vantage)
8. Single call: Reddit trending tickers + mention velocity (ApeWisdom)
9. Single call: recent Congress trades (Mboum)
10. Single call: upcoming earnings calendar (Finnhub)

Phase B — Technical Analysis (computed locally with pandas-ta, no API calls):

• SMA/EMA suite (10/20/50/100/200)
• RSI (14), MACD (12,26,9), Bollinger Bands (20,2)
• Stochastic Oscillator, ADX
• Volume analysis + OBV
• Pivot points (Classic + Fibonacci)
• Fibonacci retracement + extensions from recent swing
• ATR for position sizing

Phase C — Scoring (all local compute):

• Fundamental score (0-100): revenue growth, margins, FCF, ratios, peer comparison
• Technical score (0-100): trend, momentum, volatility, S/R positioning
• Sentiment score (0-100): analyst + insider + Congress + news + social
• Composite score: 40% fundamental + 30% technical + 30% sentiment
• Rating: 75-100 = Buy · 40-74 = Hold · 0-39 = Trim/Sell

Phase D — Output Generation (per ticker):

After all tickers are analyzed, run the usage report:

pythonCopy code
from scripts.usage_tracker import get_tracker
get_tracker().print_daily_report()
get_tracker().save_daily_summary()

Use Case 2: Daily Opportunity Scanner

Trigger: User asks to find new stock ideas, scan for opportunities, or identify swing trades.

Input: User's portfolio focus (e.g., "growth", "value", "income") and optional current holdings to avoid duplicates. Output: Top 5 Portfolio Adds + Top 5 Swing Trades, each with score, 3 entries, 3 exits. Frequency: Daily (before market open)

Workflow

Phase A — Source Aggregation (cast a wide net):

1. Scan all Tier 1+2 RSS feeds using scripts/rss_feeds.py → scan_all_feeds(). Extract tickers mentioned across all feeds.
2. Pull Seeking Alpha per-ticker RSS for top 5 tickers from step 1.
3. Get Reddit trending tickers (ApeWisdom) — cross-reference with RSS mentions.
4. StockTwits sentiment scan for top 10 overlapping tickers.
5. Check new Congress trades (Mboum).
6. Pull upcoming earnings in next 5 days (Finnhub).

Phase B — Screening (narrow down to top 20 candidates): 7. News sentiment on top 20 candidates (Finnhub). 8. SA quant ratings + factor grades for top 5 (SA RapidAPI). 9. AI sentiment score for top 5 (Alpha Vantage — 5 of 25/day). 10. Price + volume screening (yfinance) — 52wk range positioning, volume vs avg. 11. Financial health check for top 10 (yfinance) — revenue growth, margins, PE. 12. Analyst consensus for top 10 (Finnhub). 13. Insider activity for top 10 (SEC EDGAR).

Phase C — Analysis (for top 10 survivors): 14. Compute S/R levels + entry/exit targets (pandas-ta locally). 15. Check unusual options activity for top 5 (Mboum). 16. Multi-factor scoring + final ranking (local compute).

Phase D — Output:

Present two lists:

Portfolio Adds (growth-aligned, longer horizon):

• Ticker, Score, Rating, 3 Entries, 3 Exits, Stop Loss, R:R, Catalysts

Swing Trades (momentum-based, shorter horizon):

• Ticker, Score, Rating, 3 Entries, 3 Exits, Stop Loss, R:R, Catalysts, Time Horizon

Use Case 3: On-Demand Stock Deep Dive

Trigger: User asks to analyze a specific stock, do a deep dive on a ticker, or asks "should I buy X?"

Input: 1-10 tickers Output: Full analyst-grade report per ticker with Buy / Watch·Hold / Sell rating, 3 entries, 3 exits, and comprehensive analysis.

Workflow

This is the most thorough analysis — every available data source is queried. Four phases, ~30 API calls per ticker.

Phase A — Fundamentals (11 steps per ticker): Company profile, 5yr income statement, quarterly income trends, balance sheet, cash flow, XBRL cross-validation from SEC EDGAR, key ratio computation (PE/PB/PS/PEG/EV-EBITDA/ROE/ROA/D-E/FCF yield), peer comparison (5 peers), earnings history + surprises, upcoming earnings date, dividend history.

Phase B — Technicals (17 steps, mostly local via pandas-ta): 2yr daily + 6mo intraday price history, SMA/EMA suite, RSI, MACD, Bollinger Bands, Stochastic, ADX, Volume + OBV, VWAP, Pivot Points, Fibonacci Retracement, Fibonacci Extensions, Volume Profile, ATR, Ichimoku Cloud. Cross-validate 2 indicators via Alpha Vantage API.

Phase C — Sentiment & Alternative Data (16 steps): Analyst ratings consensus (Finnhub), price targets (yfinance), insider Form 4 filings (SEC EDGAR), insider MSPR (Finnhub), Congress trades (Mboum), institutional holders (yfinance), short interest, news sentiment (Finnhub + AV AI), Reddit mentions (ApeWisdom), StockTwits sentiment, SA quant ratings + factor grades (SA RapidAPI), SA per-ticker articles (RSS), options flow (yfinance), unusual options (Mboum), recent SEC filings scan.

Phase D — Scoring & Output (12 steps, all local): Fundamental score (0-100), Technical score (0-100), Sentiment score (0-100), Composite score (weighted 40/30/30), Rating assignment (Buy ≥75 / Watch·Hold 40-74 / Sell <40), 3 Entry levels, 3 Exit targets, Stop Loss, Risk:Reward ratio, Confidence level, Key Catalysts, Key Risks.

Output a comprehensive per-ticker report with all findings. Only recommend trades where R:R ≥ 2:1.

Error Handling

When any API call fails, the system:

1. Logs the error to ~/.financial-analysis/logs/error_log.jsonl with timestamp, API, category, and error message
2. Tries the fallback — next API in the chain for that data category
3. Logs fallback result — records which fallback was used and whether it succeeded
4. If all fallbacks fail, continues with available data and notes the gap in the output

Viewing Errors

bashCopy code
python scripts/usage_tracker.py errors      # Last 7 days
python scripts/usage_tracker.py errors 30   # Last 30 days

Common Errors and Fixes

Usage Reports & Paid Tier Recommendations

After each workflow run, the usage tracker saves a daily summary. When any API exceeds 70% of its free limit, it generates a paid tier recommendation:

bashCopy code
python scripts/usage_tracker.py daily    # See today's report
python scripts/usage_tracker.py summary  # Save JSON summary

The summary includes per-API: calls today/this month, % of free limit, error count, and a severity rating (SAFE / WARNING / CRITICAL).

The APIs most likely to need upgrading (in order):

1. Alpha Vantage (25/day) — first to hit limits. Upgrade: $29.99/mo
2. Mboum (600/mo) — tight if running all 3 use cases daily. Upgrade: $9.95/mo
3. SA RapidAPI (1K/mo) — tight with heavy deep dive usage. Check RapidAPI pricing.

Important Notes

• This skill provides data-driven analysis, not financial advice. Always do your own due diligence.
• yfinance is an unofficial library — data may be delayed or temporarily unavailable.
• SEC EDGAR data is authoritative but requires parsing.
• All timestamps are in the timezone of the market being analyzed (US Eastern for US stocks).
• The scoring system weights can be adjusted based on user preference.