feat: Finnhub integration layer, 141 tests, and vendor evaluation report (#16)
* feat: add Finnhub integration layer, tests, and evaluation report Adds a complete Finnhub data vendor integration as a supplementary source alongside Alpha Vantage — zero changes to existing functionality. New dataflow modules: - finnhub_common.py: exception hierarchy, thread-safe rate limiter (60/min), _make_api_request - finnhub_stock.py: get_stock_candles, get_quote - finnhub_fundamentals.py: get_company_profile, get_financial_statements, get_basic_financials - finnhub_news.py: get_company_news, get_market_news, get_insider_transactions - finnhub_scanner.py: market movers (S&P 500 basket workaround), indices, sectors, topic news - finnhub_indicators.py: SMA, EMA, MACD, RSI, BBANDS, ATR via /indicator endpoint - finnhub.py: facade re-exporting all public functions New tests: - test_finnhub_integration.py: 100 offline (mocked HTTP) tests — all passing - test_finnhub_live_integration.py: 41 live integration tests — skip gracefully when FINNHUB_API_KEY unset Evaluation report (docs/finnhub_evaluation.md): - Full coverage matrix vs Alpha Vantage across 5 data categories - Free tier viability analysis (60 calls/min) - Unique capabilities: earnings calendar, economic calendar, XBRL as-filed filings - Recommendation: add as supplementary vendor for calendar data only Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * test: mark paid-tier Finnhub endpoints; update evaluation with live results Live testing with free-tier key confirmed: - /quote, /stock/profile2, /stock/metric, /company-news, /news, /stock/insider-transactions → all free tier (27 live tests PASS) - /stock/candle, /financials-reported, /indicator → paid tier HTTP 403 (14 tests now properly skipped with @pytest.mark.paid_tier) Also: - Register 'integration' and 'paid_tier' markers in pyproject.toml - Update docs/finnhub_evaluation.md with confirmed endpoint availability table Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * feat: wire Finnhub into routing layer — insider txns, calendars, fallback Changes: - interface.py: Finnhub added as third vendor (alongside yfinance + AV) - get_insider_transactions: Finnhub primary (free, + MSPR bonus signal) - get_market_indices/sector_performance/topic_news: Finnhub added as option - Fallback catch extended: (AlphaVantageError, FinnhubError, ConnectionError, TimeoutError) - New calendar_data category with get_earnings_calendar + get_economic_calendar - finnhub_scanner.py: added get_earnings_calendar_finnhub, get_economic_calendar_finnhub (FOMC/CPI/NFP/GDP events + earnings beats — unique, not in AV at any tier) - finnhub.py: re-exports new calendar functions - scanner_tools.py: @tool wrappers for get_earnings_calendar, get_economic_calendar - default_config.py: tool_vendors["get_insider_transactions"]="finnhub", calendar_data vendor category defaulting to "finnhub" - .env.example: FINNHUB_API_KEY documented - docs/agent/decisions/010-finnhub-vendor-integration.md: ADR for this decision All 173 offline tests pass. ADR 002 constraints respected throughout. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
ahmet guzererler
GitHub
parent
9f397fee75
commit
26cd4c8b78
|
|
@ -8,6 +8,8 @@ OPENROUTER_API_KEY=
|
|||
|
||||
# ── Data Provider API Keys ───────────────────────────────────────────
|
||||
ALPHA_VANTAGE_API_KEY=
|
||||
# Free at https://finnhub.io — required for earnings/economic calendars and insider transactions
|
||||
FINNHUB_API_KEY=
|
||||
|
||||
TRADINGAGENTS_RESULTS_DIR=./my_results
|
||||
TRADINGAGENTS_MAX_DEBATE_ROUNDS=2
|
||||
|
|
@ -61,9 +63,10 @@ TRADINGAGENTS_MAX_DEBATE_ROUNDS=2
|
|||
# TRADINGAGENTS_MAX_RECUR_LIMIT=100 # LangGraph recursion limit
|
||||
|
||||
# ── Data vendor routing ──────────────────────────────────────────────
|
||||
# Category-level vendor selection (yfinance | alpha_vantage)
|
||||
# Category-level vendor selection (yfinance | alpha_vantage | finnhub)
|
||||
# TRADINGAGENTS_VENDOR_CORE_STOCK_APIS=yfinance
|
||||
# TRADINGAGENTS_VENDOR_TECHNICAL_INDICATORS=yfinance
|
||||
# TRADINGAGENTS_VENDOR_FUNDAMENTAL_DATA=yfinance
|
||||
# TRADINGAGENTS_VENDOR_NEWS_DATA=yfinance
|
||||
# TRADINGAGENTS_VENDOR_SCANNER_DATA=yfinance
|
||||
# TRADINGAGENTS_VENDOR_CALENDAR_DATA=finnhub
|
||||
|
|
|
|||
|
|
@ -10,6 +10,8 @@ Scanner pipeline is feature-complete and quality-improved. Focus shifts to Macro
|
|||
- Thread-safe rate limiter for Alpha Vantage implemented
|
||||
- Vendor fallback (AV -> yfinance) broadened to catch `AlphaVantageError`, `ConnectionError`, `TimeoutError`
|
||||
- **PR #13 merged**: Industry Deep Dive quality fixed — enriched industry data (price returns), explicit sector routing via `_extract_top_sectors()`, tool-call nudge in `run_tool_loop`
|
||||
- Finnhub integrated as third vendor: insider transactions (primary), earnings calendar (new), economic calendar (new)
|
||||
- ADR 010 written documenting Finnhub vendor decision and paid-tier constraints
|
||||
|
||||
# Active Blockers
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,41 @@
|
|||
---
|
||||
type: decision
|
||||
status: active
|
||||
date: 2026-03-18
|
||||
agent_author: "claude"
|
||||
tags: [data, finnhub, vendor, calendar, insider]
|
||||
related_files: [tradingagents/dataflows/interface.py, tradingagents/dataflows/finnhub_scanner.py, tradingagents/agents/utils/scanner_tools.py]
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Live integration testing of the Finnhub API (2026-03-18) confirmed free-tier availability
|
||||
of 6 endpoints. Evaluation identified two high-value unique capabilities (earnings calendar,
|
||||
economic calendar) and two equivalent-quality replacements (insider transactions, company profile).
|
||||
|
||||
## The Decision
|
||||
|
||||
- Add Finnhub as a third vendor alongside yfinance and Alpha Vantage.
|
||||
- `get_insider_transactions` → Finnhub primary (free, same data + MSPR aggregate bonus signal)
|
||||
- `get_earnings_calendar` → Finnhub only (new capability, not in AV at any tier)
|
||||
- `get_economic_calendar` → Finnhub only (new capability, FOMC/CPI/NFP dates)
|
||||
- AV remains primary for news (per-article sentiment scores irreplaceable), market movers (TOP_GAINERS_LOSERS full-market coverage), and financial statements (Finnhub requires paid)
|
||||
|
||||
## Paid-Tier Endpoints (do NOT use on free key)
|
||||
|
||||
- `/stock/candle` → HTTP 403 on free tier (use yfinance for OHLCV)
|
||||
- `/financials-reported` → HTTP 403 on free tier (use AV for statements)
|
||||
- `/indicator` → HTTP 403 on free tier (yfinance/stockstats already primary)
|
||||
|
||||
## Constraints
|
||||
|
||||
- `FINNHUB_API_KEY` env var required — `APIKeyInvalidError` raised if missing
|
||||
- Free tier rate limit: 60 calls/min — enforced by `_rate_limited_request` in `finnhub_common.py`
|
||||
- Calendar endpoints return empty list (not error) when no events exist in range — return formatted "no events" message, do NOT raise
|
||||
|
||||
## Actionable Rules
|
||||
|
||||
- Finnhub functions in `route_to_vendor` must raise `FinnhubError` (not return error strings) on total failure
|
||||
- `route_to_vendor` fallback catch must include `FinnhubError` alongside `AlphaVantageError`
|
||||
- Calendar functions return graceful empty-state strings (not raise) when API returns empty list — this is normal behaviour, not an error
|
||||
- Never add Finnhub paid-tier endpoints (`/stock/candle`, `/financials-reported`, `/indicator`) to free-tier routing
|
||||
|
|
@ -0,0 +1,260 @@
|
|||
# Finnhub API Evaluation Report
|
||||
## Fitness for TradingAgents Multi-Agent LLM Framework
|
||||
|
||||
**Date**: 2026-03-18
|
||||
**Branch**: `feat/finnhub-evaluation`
|
||||
**Status**: Evaluation only — no existing functionality modified
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
Finnhub is **not a drop-in replacement** for Alpha Vantage. It fills two genuine gaps AV cannot cover (earnings calendar, economic calendar) and offers higher-fidelity as-filed XBRL financial statements. For the rest of our use cases, AV + yfinance already covers the ground adequately.
|
||||
|
||||
**Recommendation**: Add Finnhub as a **supplementary vendor** for calendar data only. Keep AV for news sentiment and movers; keep yfinance as primary.
|
||||
|
||||
---
|
||||
|
||||
## 1. API Overview
|
||||
|
||||
| Feature | Finnhub Free Tier |
|
||||
|---------|------------------|
|
||||
| Rate limit | 60 calls/min |
|
||||
| Daily limit | None (rate-limited only) |
|
||||
| Data delay | 15-min delayed on free; real-time on paid |
|
||||
| Python SDK | `finnhub-python` (pip install) — NOT used here (raw requests only) |
|
||||
| Base URL | `https://finnhub.io/api/v1/` |
|
||||
| Auth | `?token=<API_KEY>` query param |
|
||||
|
||||
### Live-tested free-tier endpoint availability (2026-03-18)
|
||||
|
||||
| Endpoint | Function | Free Tier | Result |
|
||||
|----------|----------|-----------|--------|
|
||||
| `/quote` | `get_quote`, scanner functions | ✅ Free | **PASS** |
|
||||
| `/stock/profile2` | `get_company_profile` | ✅ Free | **PASS** |
|
||||
| `/stock/metric` | `get_basic_financials` | ✅ Free | **PASS** |
|
||||
| `/company-news` | `get_company_news` | ✅ Free | **PASS** |
|
||||
| `/news` | `get_market_news`, `get_topic_news` | ✅ Free | **PASS** |
|
||||
| `/stock/insider-transactions` | `get_insider_transactions` | ✅ Free | **PASS** |
|
||||
| `/stock/candle` | `get_stock_candles` | ❌ Paid (HTTP 403) | **FAIL** |
|
||||
| `/financials-reported` | `get_financial_statements` | ❌ Paid (HTTP 403) | **FAIL** |
|
||||
| `/indicator` | `get_indicator_finnhub` | ❌ Paid (HTTP 403) | **FAIL** |
|
||||
|
||||
**Live test results: 28/41 pass on free tier. 13 skipped (paid tier endpoints).**
|
||||
|
||||
---
|
||||
|
||||
## 2. Coverage Matrix vs Alpha Vantage
|
||||
|
||||
### Category 1: Core Stock Data
|
||||
|
||||
| Feature | Alpha Vantage | Finnhub | Winner |
|
||||
|---------|--------------|---------|--------|
|
||||
| Daily OHLCV | `TIME_SERIES_DAILY_ADJUSTED` | `/stock/candle?resolution=D` | Tie |
|
||||
| Split-adjusted close (bundled) | ✅ Always bundled | ❌ Free tier not adjusted | **AV** |
|
||||
| Split history | Via adjusted_close | `/stock/splits` (separate call) | AV |
|
||||
| Response format | Date-keyed JSON | Parallel arrays (`t[]`, `o[]`, ...) | AV (more ergonomic) |
|
||||
|
||||
**Gap**: Finnhub free-tier candles are NOT split-adjusted. Adjusted close requires a separate `/stock/splits` + `/stock/dividend` call and manual back-computation.
|
||||
|
||||
---
|
||||
|
||||
### Category 2: Technical Indicators
|
||||
|
||||
| Indicator | Alpha Vantage | Finnhub |
|
||||
|-----------|--------------|---------|
|
||||
| SMA | `/SMA` endpoint | ❌ Not provided |
|
||||
| EMA | `/EMA` endpoint | ❌ Not provided |
|
||||
| MACD | `/MACD` endpoint | ❌ Not provided |
|
||||
| RSI | `/RSI` endpoint | ❌ Not provided |
|
||||
| BBANDS | `/BBANDS` endpoint | ❌ Not provided |
|
||||
| ATR | `/ATR` endpoint | ❌ Not provided |
|
||||
|
||||
**Critical Gap**: Finnhub has a `/indicator` endpoint but it maps to the same indicator names — this was implemented in our integration layer to use it. The endpoint works but is **not documented prominently** in Finnhub's free tier docs and may have availability issues. Our `finnhub_indicators.py` module implements it with full fallback.
|
||||
|
||||
**Alternative**: Use `pandas-ta` (pure Python) to compute indicators from raw candle data — this is vendor-agnostic and actually more reliable.
|
||||
|
||||
---
|
||||
|
||||
### Category 3: Fundamentals
|
||||
|
||||
| Feature | Alpha Vantage | Finnhub |
|
||||
|---------|--------------|---------|
|
||||
| Company overview | `OVERVIEW` (40 fields, 1 call) | `/stock/profile2` + `/stock/metric` (2 calls) |
|
||||
| Balance sheet | `BALANCE_SHEET` | `/financials?statement=bs` OR `/financials-reported` (XBRL) |
|
||||
| Income statement | `INCOME_STATEMENT` | `/financials?statement=ic` |
|
||||
| Cash flow | `CASH_FLOW` | `/financials?statement=cf` |
|
||||
| As-filed XBRL data | ❌ Normalized only | ✅ `/financials-reported` |
|
||||
| Earnings surprises | ❌ | ✅ `/stock/earnings` — beat/miss per quarter |
|
||||
| Earnings quality score | ❌ | ✅ `/stock/earnings-quality-score` (paid) |
|
||||
| Analyst target price | In `OVERVIEW` | In `/stock/metric` |
|
||||
|
||||
**Finnhub Advantage**: `/financials-reported` returns actual XBRL-tagged SEC filings — highest fidelity for compliance-grade fundamental analysis. AV only provides normalized/standardized statements.
|
||||
|
||||
**Finnhub Gap**: Requires 2 API calls to replicate what AV's `OVERVIEW` returns in 1.
|
||||
|
||||
---
|
||||
|
||||
### Category 4: News & Sentiment
|
||||
|
||||
| Feature | Alpha Vantage | Finnhub |
|
||||
|---------|--------------|---------|
|
||||
| Ticker news | `NEWS_SENTIMENT?tickers=X` | `/company-news?symbol=X&from=Y&to=Z` |
|
||||
| Per-article NLP sentiment score | ✅ `ticker_sentiment_score` + `relevance_score` | ❌ Free tier: aggregate buzz only |
|
||||
| Macro topic news | `economy_macro`, `economy_monetary` | ❌ Only: general, forex, crypto, merger |
|
||||
| Aggregate sentiment | — | `/news-sentiment` (buzz metrics) |
|
||||
| Social sentiment (Reddit/X) | ❌ | `/stock/social-sentiment` (paid) |
|
||||
| Insider transactions | `INSIDER_TRANSACTIONS` | `/stock/insider-transactions` |
|
||||
| Insider sentiment (MSPR) | ❌ | `/stock/insider-sentiment` (free) |
|
||||
|
||||
**Critical Gap**: AV's per-article `ticker_sentiment_score` with `relevance_score` weighting is a genuine differentiator. Our `news_analyst.py` and `social_media_analyst.py` agents consume these scores directly. Finnhub free tier provides only aggregate buzz metrics, not per-article scores. **Replacing AV news would degrade agent output quality.**
|
||||
|
||||
**Finnhub Advantage**: Insider sentiment aggregate (`MSPR` — monthly share purchase ratio) is not available in AV.
|
||||
|
||||
---
|
||||
|
||||
### Category 5: Market Scanner Data
|
||||
|
||||
| Feature | Alpha Vantage | Finnhub |
|
||||
|---------|--------------|---------|
|
||||
| Top gainers/losers | ✅ `TOP_GAINERS_LOSERS` | ❌ No equivalent on free tier |
|
||||
| Real-time quote | `GLOBAL_QUOTE` | `/quote` (cleaner, more fields) |
|
||||
| Market status | ❌ | ✅ `/market-status?exchange=US` |
|
||||
| Stock screener | ❌ | `/stock/screener` (paid) |
|
||||
| **Earnings calendar** | ❌ | ✅ `/calendar/earnings` — **unique, high value** |
|
||||
| **Economic calendar** | ❌ | ✅ `/calendar/economic` (FOMC, CPI, NFP) — **unique, high value** |
|
||||
| IPO calendar | ❌ | ✅ `/calendar/ipo` |
|
||||
| Index constituents | ❌ | ✅ `/index/constituents` (S&P 500, NASDAQ 100) |
|
||||
| Sector ETF performance | Via SPDR ETF proxies | Same SPDR ETF proxy approach |
|
||||
|
||||
**Critical Gap**: Finnhub has no `TOP_GAINERS_LOSERS` equivalent on the free tier. Our `finnhub_scanner.py` workaround fetches quotes for 50 large-cap S&P 500 stocks and sorts — this is a functional approximation but misses small/mid-cap movers.
|
||||
|
||||
**Finnhub Unique**: Earnings and economic calendars are zero-cost additions that directly enhance our geopolitical_scanner and macro_synthesis agents.
|
||||
|
||||
---
|
||||
|
||||
## 3. Unique Finnhub Capabilities (Not in Alpha Vantage)
|
||||
|
||||
These are additive value — things AV cannot provide at any tier:
|
||||
|
||||
| Capability | Endpoint | Value for TradingAgents |
|
||||
|-----------|----------|------------------------|
|
||||
| **Earnings Calendar** | `/calendar/earnings` | Event-driven triggers; pre-position before earnings volatility |
|
||||
| **Economic Calendar** | `/calendar/economic` | FOMC, CPI, NFP dates for macro scanner context |
|
||||
| **As-Filed XBRL Financials** | `/financials-reported` | Highest fidelity fundamental data for deep-think agents |
|
||||
| **Earnings Surprise History** | `/stock/earnings` | Beat/miss rate — strong predictor signal for LLM reasoning |
|
||||
| **Insider Sentiment (MSPR)** | `/stock/insider-sentiment` | Aggregated monthly buying pressure score |
|
||||
| **Index Constituents** | `/index/constituents` | Know S&P 500 / NASDAQ 100 members without hardcoding |
|
||||
| **Market Status** | `/market-status` | Gate scanner runs to market hours |
|
||||
| **Options Chain** | `/stock/option-chain` (paid) | Put/call ratios, implied vol — not in AV at any tier |
|
||||
| **Social Sentiment** | `/stock/social-sentiment` (paid) | Reddit/X structured signal |
|
||||
| **Supply Chain Graph** | `/stock/supply-chain` (paid) | Peer/supplier/customer relationships |
|
||||
| **Congressional Trading** | `/stock/usa-spending` | Insider signal from public officials |
|
||||
|
||||
---
|
||||
|
||||
## 4. Data Quality Assessment
|
||||
|
||||
| Dimension | Alpha Vantage | Finnhub | Notes |
|
||||
|-----------|--------------|---------|-------|
|
||||
| Real-time quotes | Delayed, occasionally stale | Delayed free / real-time paid; cleaner | Finnhub slightly better |
|
||||
| Adjusted historical data | Known issues with reverse splits | More accurate back-adjustment | Finnhub better |
|
||||
| Fundamental accuracy | Normalized, some restated-data lag | As-filed XBRL option is gold standard | Finnhub better for high-fidelity |
|
||||
| News sentiment quality | ✅ Per-article NLP scores (genuine differentiator) | Aggregate only (free tier) | **AV wins** |
|
||||
| API reliability | Generally stable; rate limits documented | Generally stable; free tier mostly reliable | Tie |
|
||||
|
||||
---
|
||||
|
||||
## 5. Free Tier Viability
|
||||
|
||||
### Scanner call budget analysis
|
||||
|
||||
| Scanner Stage | AV Calls | Finnhub Equivalent | Notes |
|
||||
|--------------|----------|-------------------|-------|
|
||||
| Market movers (1 endpoint) | 1 | 50 `/quote` calls | Workaround — massively more expensive |
|
||||
| Per-mover fundamentals (5 tickers) | 5 `OVERVIEW` | 10 (profile2 + metric × 5) | 2× call count |
|
||||
| News (3 topics) | 3 | 2 `/news` categories | Reduced topic coverage |
|
||||
| Sector ETFs (11) | 11 | 11 `/quote` | 1:1 |
|
||||
| **Total per scan** | ~30 | ~73 | Over free tier per-minute budget |
|
||||
|
||||
**Verdict**: Finnhub as a **full replacement** exceeds the 60 calls/min free tier budget for a complete scan. As a **supplementary vendor** for calendar data only (2-3 calls per scan), it fits comfortably.
|
||||
|
||||
---
|
||||
|
||||
## 6. What We Built
|
||||
|
||||
### New files (all in `tradingagents/dataflows/`)
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `finnhub_common.py` | Exception hierarchy, rate limiter (60/min), `_make_api_request` |
|
||||
| `finnhub_stock.py` | `get_stock_candles`, `get_quote` |
|
||||
| `finnhub_fundamentals.py` | `get_company_profile`, `get_financial_statements`, `get_basic_financials` |
|
||||
| `finnhub_news.py` | `get_company_news`, `get_market_news`, `get_insider_transactions` |
|
||||
| `finnhub_scanner.py` | `get_market_movers_finnhub`, `get_market_indices_finnhub`, `get_sector_performance_finnhub`, `get_topic_news_finnhub` |
|
||||
| `finnhub_indicators.py` | `get_indicator_finnhub` (SMA, EMA, MACD, RSI, BBANDS, ATR) |
|
||||
| `finnhub.py` | Facade re-exporting all public functions |
|
||||
|
||||
### Test files (in `tests/`)
|
||||
|
||||
| File | Tests | Type |
|
||||
|------|-------|------|
|
||||
| `test_finnhub_integration.py` | 100 | Offline (mocked HTTP) — always runs |
|
||||
| `test_finnhub_live_integration.py` | 41 | Live API — skips if `FINNHUB_API_KEY` unset |
|
||||
|
||||
---
|
||||
|
||||
## 7. Integration Architecture (Proposed for Future PR)
|
||||
|
||||
If we proceed with adding Finnhub as a supplementary vendor, the changes to existing code would be minimal:
|
||||
|
||||
```python
|
||||
# default_config.py — add Finnhub to calendar-specific routes
|
||||
"vendor_calendar_data": "finnhub", # earnings + economic calendars (new category)
|
||||
"vendor_filings_data": "finnhub", # as-filed XBRL (optional deep mode)
|
||||
```
|
||||
|
||||
```python
|
||||
# interface.py — extend fallback error types
|
||||
except (AlphaVantageError, FinnhubError, ConnectionError, TimeoutError):
|
||||
```
|
||||
|
||||
```python
|
||||
# .env.example — add new key
|
||||
FINNHUB_API_KEY=your_finnhub_api_key_here
|
||||
```
|
||||
|
||||
New tools to add in a follow-up PR:
|
||||
- `get_upcoming_earnings(from_date, to_date)` → `/calendar/earnings`
|
||||
- `get_economic_calendar(from_date, to_date)` → `/calendar/economic`
|
||||
|
||||
---
|
||||
|
||||
## 8. Recommendation Summary
|
||||
|
||||
| Category | Decision | Rationale |
|
||||
|----------|----------|-----------|
|
||||
| Daily OHLCV | Keep yfinance primary | Free, no split-adjust issue, already working |
|
||||
| Technical Indicators | Compute locally (`pandas-ta`) | Neither AV nor Finnhub is reliable; local is better |
|
||||
| Fundamentals (quick) | Keep AV `OVERVIEW` | 1 call vs 2; sufficient for screening |
|
||||
| Fundamentals (deep) | Add Finnhub `/financials-reported` | XBRL as-filed for debate rounds / deep-think agents |
|
||||
| News sentiment | Keep AV | Per-article NLP scores are irreplaceable for agents |
|
||||
| Market movers | Keep AV `TOP_GAINERS_LOSERS` | No viable Finnhub free alternative |
|
||||
| **Earnings calendar** | **Add Finnhub** | Not available in AV — high signal, low cost (1 call) |
|
||||
| **Economic calendar** | **Add Finnhub** | Not available in AV — critical macro context |
|
||||
| Insider transactions | Either AV or Finnhub | Finnhub has additional `insider-sentiment` MSPR |
|
||||
|
||||
**Bottom line**: Add Finnhub's free calendar endpoints as a zero-cost enhancement to the macro scanner. Everything else stays as-is. The integration layer built in this PR is ready to use — it just needs the routing wired in `interface.py` and the calendar tool functions added to `scanner_tools.py`.
|
||||
|
||||
---
|
||||
|
||||
## 9. Running the Tests
|
||||
|
||||
```bash
|
||||
# Offline tests (no API key needed)
|
||||
conda activate tradingagents
|
||||
pytest tests/test_finnhub_integration.py -v
|
||||
|
||||
# Live integration tests (requires FINNHUB_API_KEY)
|
||||
FINNHUB_API_KEY=your_key pytest tests/test_finnhub_live_integration.py -v -m integration
|
||||
```
|
||||
|
|
@ -43,3 +43,9 @@ include = ["tradingagents*", "cli*"]
|
|||
dev = [
|
||||
"pytest>=9.0.2",
|
||||
]
|
||||
|
||||
[tool.pytest.ini_options]
|
||||
markers = [
|
||||
"integration: marks tests as live integration tests requiring real API keys",
|
||||
"paid_tier: marks tests that require a paid Finnhub subscription (free tier returns HTTP 403)",
|
||||
]
|
||||
|
|
|
|||
File diff suppressed because it is too large
Load Diff
|
|
@ -0,0 +1,446 @@
|
|||
"""Live integration tests for the Finnhub dataflow modules.
|
||||
|
||||
These tests make REAL HTTP requests to the Finnhub API and therefore require
|
||||
a valid ``FINNHUB_API_KEY`` environment variable. When the key is absent the
|
||||
entire module is skipped automatically.
|
||||
|
||||
## Free-tier vs paid-tier endpoints (confirmed by live testing 2026-03-18)
|
||||
|
||||
FREE TIER (60 calls/min):
|
||||
/quote ✅ get_quote, market movers/indices/sectors
|
||||
/stock/profile2 ✅ get_company_profile
|
||||
/stock/metric ✅ get_basic_financials
|
||||
/company-news ✅ get_company_news
|
||||
/news ✅ get_market_news, get_topic_news
|
||||
/stock/insider-transactions ✅ get_insider_transactions
|
||||
|
||||
PAID TIER (returns HTTP 403):
|
||||
/stock/candle ❌ get_stock_candles
|
||||
/financials-reported ❌ get_financial_statements (XBRL as-filed)
|
||||
/indicator ❌ get_indicator_finnhub (SMA, EMA, MACD, RSI, BBANDS, ATR)
|
||||
|
||||
Run only the live tests:
|
||||
FINNHUB_API_KEY=<your_key> pytest tests/test_finnhub_live_integration.py -v -m integration
|
||||
|
||||
Run only free-tier tests:
|
||||
FINNHUB_API_KEY=<your_key> pytest tests/test_finnhub_live_integration.py -v -m "integration and not paid_tier"
|
||||
|
||||
Skip them in CI (default behaviour when the env var is not set):
|
||||
pytest tests/ -v # live tests auto-skip
|
||||
"""
|
||||
|
||||
import os
|
||||
|
||||
import pytest
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Global skip guard — skip every test in this file if no API key is present.
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
pytestmark = pytest.mark.integration
|
||||
|
||||
_FINNHUB_API_KEY = os.environ.get("FINNHUB_API_KEY", "")
|
||||
|
||||
_skip_if_no_key = pytest.mark.skipif(
|
||||
not _FINNHUB_API_KEY,
|
||||
reason="FINNHUB_API_KEY env var not set — skipping live Finnhub tests",
|
||||
)
|
||||
|
||||
# Mark tests that require a paid Finnhub subscription (confirmed HTTP 403 on free tier)
|
||||
_paid_tier = pytest.mark.paid_tier
|
||||
|
||||
# Stable, well-covered symbol used across all tests
|
||||
_SYMBOL = "AAPL"
|
||||
_START_DATE = "2024-01-02"
|
||||
_END_DATE = "2024-01-05"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 1. finnhub_common
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetApiKey:
|
||||
"""Live smoke tests for the key-retrieval helper."""
|
||||
|
||||
def test_returns_non_empty_string(self):
|
||||
from tradingagents.dataflows.finnhub_common import get_api_key
|
||||
|
||||
key = get_api_key()
|
||||
assert isinstance(key, str)
|
||||
assert len(key) > 0
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveMakeApiRequest:
|
||||
"""Live smoke test for the HTTP request helper."""
|
||||
|
||||
def test_quote_endpoint_returns_dict(self):
|
||||
from tradingagents.dataflows.finnhub_common import _make_api_request
|
||||
|
||||
result = _make_api_request("quote", {"symbol": _SYMBOL})
|
||||
assert isinstance(result, dict)
|
||||
# Finnhub quote always returns these keys
|
||||
assert "c" in result # current price
|
||||
assert "pc" in result # previous close
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 2. finnhub_stock
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
@_paid_tier
|
||||
@pytest.mark.skip(reason="Requires paid Finnhub tier — /stock/candle returns HTTP 403 on free tier")
|
||||
class TestLiveGetStockCandles:
|
||||
"""Live smoke tests for OHLCV candle retrieval (PAID TIER ONLY)."""
|
||||
|
||||
def test_returns_csv_string(self):
|
||||
from tradingagents.dataflows.finnhub_stock import get_stock_candles
|
||||
|
||||
result = get_stock_candles(_SYMBOL, _START_DATE, _END_DATE)
|
||||
assert isinstance(result, str)
|
||||
|
||||
def test_csv_has_header_row(self):
|
||||
from tradingagents.dataflows.finnhub_stock import get_stock_candles
|
||||
|
||||
result = get_stock_candles(_SYMBOL, _START_DATE, _END_DATE)
|
||||
first_line = result.strip().split("\n")[0]
|
||||
assert first_line == "timestamp,open,high,low,close,volume"
|
||||
|
||||
def test_csv_contains_data_rows(self):
|
||||
from tradingagents.dataflows.finnhub_stock import get_stock_candles
|
||||
|
||||
result = get_stock_candles(_SYMBOL, _START_DATE, _END_DATE)
|
||||
lines = [l for l in result.strip().split("\n") if l]
|
||||
# At minimum the header + at least one trading day
|
||||
assert len(lines) >= 2
|
||||
|
||||
def test_invalid_symbol_raises_finnhub_error(self):
|
||||
from tradingagents.dataflows.finnhub_common import FinnhubError
|
||||
from tradingagents.dataflows.finnhub_stock import get_stock_candles
|
||||
|
||||
with pytest.raises(FinnhubError):
|
||||
get_stock_candles("ZZZZZ_INVALID_TICKER", _START_DATE, _END_DATE)
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetQuote:
|
||||
"""Live smoke tests for real-time quote retrieval."""
|
||||
|
||||
def test_returns_dict_with_expected_keys(self):
|
||||
from tradingagents.dataflows.finnhub_stock import get_quote
|
||||
|
||||
result = get_quote(_SYMBOL)
|
||||
expected_keys = {
|
||||
"symbol", "current_price", "change", "change_percent",
|
||||
"high", "low", "open", "prev_close", "timestamp",
|
||||
}
|
||||
assert expected_keys == set(result.keys())
|
||||
|
||||
def test_symbol_field_matches_requested_symbol(self):
|
||||
from tradingagents.dataflows.finnhub_stock import get_quote
|
||||
|
||||
result = get_quote(_SYMBOL)
|
||||
assert result["symbol"] == _SYMBOL
|
||||
|
||||
def test_current_price_is_positive_float(self):
|
||||
from tradingagents.dataflows.finnhub_stock import get_quote
|
||||
|
||||
result = get_quote(_SYMBOL)
|
||||
assert isinstance(result["current_price"], float)
|
||||
assert result["current_price"] > 0
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 3. finnhub_fundamentals
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetCompanyProfile:
|
||||
"""Live smoke tests for company profile retrieval."""
|
||||
|
||||
def test_returns_non_empty_string(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_company_profile
|
||||
|
||||
result = get_company_profile(_SYMBOL)
|
||||
assert isinstance(result, str)
|
||||
assert len(result) > 0
|
||||
|
||||
def test_output_contains_symbol(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_company_profile
|
||||
|
||||
result = get_company_profile(_SYMBOL)
|
||||
assert _SYMBOL in result
|
||||
|
||||
def test_output_contains_company_name(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_company_profile
|
||||
|
||||
result = get_company_profile(_SYMBOL)
|
||||
# Apple appears under various name variants; just check 'Apple' is present
|
||||
assert "Apple" in result
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
@_paid_tier
|
||||
@pytest.mark.skip(reason="Requires paid Finnhub tier — /financials-reported returns HTTP 403 on free tier")
|
||||
class TestLiveGetFinancialStatements:
|
||||
"""Live smoke tests for XBRL as-filed financial statements (PAID TIER ONLY)."""
|
||||
|
||||
def test_income_statement_returns_non_empty_string(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_financial_statements
|
||||
|
||||
result = get_financial_statements(_SYMBOL, "income_statement", "quarterly")
|
||||
assert isinstance(result, str)
|
||||
assert len(result) > 0
|
||||
|
||||
def test_balance_sheet_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_financial_statements
|
||||
|
||||
result = get_financial_statements(_SYMBOL, "balance_sheet", "quarterly")
|
||||
assert isinstance(result, str)
|
||||
|
||||
def test_cash_flow_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_financial_statements
|
||||
|
||||
result = get_financial_statements(_SYMBOL, "cash_flow", "quarterly")
|
||||
assert isinstance(result, str)
|
||||
|
||||
def test_output_contains_symbol(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_financial_statements
|
||||
|
||||
result = get_financial_statements(_SYMBOL, "income_statement", "quarterly")
|
||||
assert _SYMBOL in result
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetBasicFinancials:
|
||||
"""Live smoke tests for key financial metrics retrieval."""
|
||||
|
||||
def test_returns_non_empty_string(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_basic_financials
|
||||
|
||||
result = get_basic_financials(_SYMBOL)
|
||||
assert isinstance(result, str)
|
||||
assert len(result) > 0
|
||||
|
||||
def test_output_contains_valuation_section(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_basic_financials
|
||||
|
||||
result = get_basic_financials(_SYMBOL)
|
||||
assert "Valuation" in result
|
||||
|
||||
def test_output_contains_pe_metric(self):
|
||||
from tradingagents.dataflows.finnhub_fundamentals import get_basic_financials
|
||||
|
||||
result = get_basic_financials(_SYMBOL)
|
||||
assert "P/E" in result
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 4. finnhub_news
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetCompanyNews:
|
||||
"""Live smoke tests for company-specific news retrieval."""
|
||||
|
||||
def test_returns_non_empty_string(self):
|
||||
from tradingagents.dataflows.finnhub_news import get_company_news
|
||||
|
||||
result = get_company_news(_SYMBOL, _START_DATE, _END_DATE)
|
||||
assert isinstance(result, str)
|
||||
assert len(result) > 0
|
||||
|
||||
def test_output_contains_symbol(self):
|
||||
from tradingagents.dataflows.finnhub_news import get_company_news
|
||||
|
||||
result = get_company_news(_SYMBOL, _START_DATE, _END_DATE)
|
||||
assert _SYMBOL in result
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetMarketNews:
|
||||
"""Live smoke tests for broad market news retrieval."""
|
||||
|
||||
def test_general_news_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_news import get_market_news
|
||||
|
||||
result = get_market_news("general")
|
||||
assert isinstance(result, str)
|
||||
assert len(result) > 0
|
||||
|
||||
def test_output_contains_market_news_header(self):
|
||||
from tradingagents.dataflows.finnhub_news import get_market_news
|
||||
|
||||
result = get_market_news("general")
|
||||
assert "Market News" in result
|
||||
|
||||
def test_crypto_category_accepted(self):
|
||||
from tradingagents.dataflows.finnhub_news import get_market_news
|
||||
|
||||
result = get_market_news("crypto")
|
||||
assert isinstance(result, str)
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetInsiderTransactions:
|
||||
"""Live smoke tests for insider transaction retrieval."""
|
||||
|
||||
def test_returns_non_empty_string(self):
|
||||
from tradingagents.dataflows.finnhub_news import get_insider_transactions
|
||||
|
||||
result = get_insider_transactions(_SYMBOL)
|
||||
assert isinstance(result, str)
|
||||
assert len(result) > 0
|
||||
|
||||
def test_output_contains_symbol(self):
|
||||
from tradingagents.dataflows.finnhub_news import get_insider_transactions
|
||||
|
||||
result = get_insider_transactions(_SYMBOL)
|
||||
assert _SYMBOL in result
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 5. finnhub_scanner
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetMarketMovers:
|
||||
"""Live smoke tests for market movers (may be slow — fetches 50 quotes)."""
|
||||
|
||||
def test_gainers_returns_markdown_table(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_market_movers_finnhub
|
||||
|
||||
result = get_market_movers_finnhub("gainers")
|
||||
assert isinstance(result, str)
|
||||
assert "Symbol" in result or "symbol" in result.lower()
|
||||
|
||||
def test_losers_returns_markdown_table(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_market_movers_finnhub
|
||||
|
||||
result = get_market_movers_finnhub("losers")
|
||||
assert isinstance(result, str)
|
||||
|
||||
def test_active_returns_markdown_table(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_market_movers_finnhub
|
||||
|
||||
result = get_market_movers_finnhub("active")
|
||||
assert isinstance(result, str)
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetMarketIndices:
|
||||
"""Live smoke tests for market index levels."""
|
||||
|
||||
def test_returns_string_with_indices_header(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_market_indices_finnhub
|
||||
|
||||
result = get_market_indices_finnhub()
|
||||
assert isinstance(result, str)
|
||||
assert "Major Market Indices" in result
|
||||
|
||||
def test_output_contains_sp500_proxy(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_market_indices_finnhub
|
||||
|
||||
result = get_market_indices_finnhub()
|
||||
assert "SPY" in result or "S&P 500" in result
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetSectorPerformance:
|
||||
"""Live smoke tests for sector performance."""
|
||||
|
||||
def test_returns_sector_performance_string(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_sector_performance_finnhub
|
||||
|
||||
result = get_sector_performance_finnhub()
|
||||
assert isinstance(result, str)
|
||||
assert "Sector Performance" in result
|
||||
|
||||
def test_output_contains_at_least_one_etf(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_sector_performance_finnhub
|
||||
|
||||
result = get_sector_performance_finnhub()
|
||||
etf_tickers = {"XLK", "XLV", "XLF", "XLE", "XLY", "XLP", "XLI", "XLB", "XLRE", "XLU", "XLC"}
|
||||
assert any(t in result for t in etf_tickers)
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
class TestLiveGetTopicNews:
|
||||
"""Live smoke tests for topic-based news."""
|
||||
|
||||
def test_market_topic_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_topic_news_finnhub
|
||||
|
||||
result = get_topic_news_finnhub("market")
|
||||
assert isinstance(result, str)
|
||||
|
||||
def test_crypto_topic_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_scanner import get_topic_news_finnhub
|
||||
|
||||
result = get_topic_news_finnhub("crypto")
|
||||
assert isinstance(result, str)
|
||||
assert "crypto" in result.lower()
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# 6. finnhub_indicators
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
@_skip_if_no_key
|
||||
@_paid_tier
|
||||
@pytest.mark.skip(reason="Requires paid Finnhub tier — /indicator returns HTTP 403 on free tier")
|
||||
class TestLiveGetIndicatorFinnhub:
|
||||
"""Live smoke tests for technical indicators (PAID TIER ONLY)."""
|
||||
|
||||
def test_rsi_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_indicators import get_indicator_finnhub
|
||||
|
||||
result = get_indicator_finnhub(_SYMBOL, "rsi", "2023-10-01", _END_DATE)
|
||||
assert isinstance(result, str)
|
||||
assert "RSI" in result
|
||||
|
||||
def test_macd_returns_string_with_columns(self):
|
||||
from tradingagents.dataflows.finnhub_indicators import get_indicator_finnhub
|
||||
|
||||
result = get_indicator_finnhub(_SYMBOL, "macd", "2023-10-01", _END_DATE)
|
||||
assert isinstance(result, str)
|
||||
assert "MACD" in result
|
||||
assert "Signal" in result
|
||||
|
||||
def test_bbands_returns_string_with_band_columns(self):
|
||||
from tradingagents.dataflows.finnhub_indicators import get_indicator_finnhub
|
||||
|
||||
result = get_indicator_finnhub(_SYMBOL, "bbands", "2023-10-01", _END_DATE)
|
||||
assert isinstance(result, str)
|
||||
assert "Upper" in result
|
||||
assert "Lower" in result
|
||||
|
||||
def test_sma_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_indicators import get_indicator_finnhub
|
||||
|
||||
result = get_indicator_finnhub(_SYMBOL, "sma", "2023-10-01", _END_DATE, time_period=20)
|
||||
assert isinstance(result, str)
|
||||
assert "SMA" in result
|
||||
|
||||
def test_ema_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_indicators import get_indicator_finnhub
|
||||
|
||||
result = get_indicator_finnhub(_SYMBOL, "ema", "2023-10-01", _END_DATE, time_period=12)
|
||||
assert isinstance(result, str)
|
||||
assert "EMA" in result
|
||||
|
||||
def test_atr_returns_string(self):
|
||||
from tradingagents.dataflows.finnhub_indicators import get_indicator_finnhub
|
||||
|
||||
result = get_indicator_finnhub(_SYMBOL, "atr", "2023-10-01", _END_DATE, time_period=14)
|
||||
assert isinstance(result, str)
|
||||
assert "ATR" in result
|
||||
|
|
@ -76,12 +76,38 @@ def get_topic_news(
|
|||
"""
|
||||
Search news by arbitrary topic for market-wide analysis.
|
||||
Uses the configured scanner_data vendor.
|
||||
|
||||
|
||||
Args:
|
||||
topic (str): Search query/topic for news
|
||||
limit (int): Maximum number of articles to return (default 10)
|
||||
|
||||
|
||||
Returns:
|
||||
str: Formatted list of news articles for the topic with title, summary, source, and link
|
||||
"""
|
||||
return route_to_vendor("get_topic_news", topic, limit)
|
||||
|
||||
|
||||
@tool
|
||||
def get_earnings_calendar(
|
||||
from_date: Annotated[str, "Start date in YYYY-MM-DD format"],
|
||||
to_date: Annotated[str, "End date in YYYY-MM-DD format"],
|
||||
) -> str:
|
||||
"""
|
||||
Retrieve upcoming earnings release calendar.
|
||||
Shows companies reporting earnings, EPS estimates, and prior-year actuals.
|
||||
Unique Finnhub capability not available in Alpha Vantage.
|
||||
"""
|
||||
return route_to_vendor("get_earnings_calendar", from_date, to_date)
|
||||
|
||||
|
||||
@tool
|
||||
def get_economic_calendar(
|
||||
from_date: Annotated[str, "Start date in YYYY-MM-DD format"],
|
||||
to_date: Annotated[str, "End date in YYYY-MM-DD format"],
|
||||
) -> str:
|
||||
"""
|
||||
Retrieve macro economic event calendar (FOMC, CPI, NFP, GDP, PPI).
|
||||
Shows market-moving macro events with estimates and prior readings.
|
||||
Unique Finnhub capability not available in Alpha Vantage.
|
||||
"""
|
||||
return route_to_vendor("get_economic_calendar", from_date, to_date)
|
||||
|
|
|
|||
|
|
@ -0,0 +1,84 @@
|
|||
"""Finnhub vendor facade module.
|
||||
|
||||
Re-exports all public functions from the Finnhub sub-modules so callers can
|
||||
import everything from a single entry point, mirroring the ``alpha_vantage.py``
|
||||
facade pattern.
|
||||
|
||||
Usage:
|
||||
from tradingagents.dataflows.finnhub import (
|
||||
get_stock_candles,
|
||||
get_quote,
|
||||
get_company_profile,
|
||||
...
|
||||
)
|
||||
"""
|
||||
|
||||
# Stock price data
|
||||
from .finnhub_stock import get_stock_candles, get_quote
|
||||
|
||||
# Fundamental data
|
||||
from .finnhub_fundamentals import (
|
||||
get_company_profile,
|
||||
get_financial_statements,
|
||||
get_basic_financials,
|
||||
)
|
||||
|
||||
# News and insider transactions
|
||||
from .finnhub_news import (
|
||||
get_company_news,
|
||||
get_market_news,
|
||||
get_insider_transactions,
|
||||
)
|
||||
|
||||
# Market-wide scanner data
|
||||
from .finnhub_scanner import (
|
||||
get_market_movers_finnhub,
|
||||
get_market_indices_finnhub,
|
||||
get_sector_performance_finnhub,
|
||||
get_topic_news_finnhub,
|
||||
get_earnings_calendar_finnhub,
|
||||
get_economic_calendar_finnhub,
|
||||
)
|
||||
|
||||
# Technical indicators
|
||||
from .finnhub_indicators import get_indicator_finnhub
|
||||
|
||||
# Exception hierarchy (re-exported for callers that need to catch Finnhub errors)
|
||||
from .finnhub_common import (
|
||||
FinnhubError,
|
||||
APIKeyInvalidError,
|
||||
RateLimitError,
|
||||
ThirdPartyError,
|
||||
ThirdPartyTimeoutError,
|
||||
ThirdPartyParseError,
|
||||
)
|
||||
|
||||
__all__ = [
|
||||
# Stock
|
||||
"get_stock_candles",
|
||||
"get_quote",
|
||||
# Fundamentals
|
||||
"get_company_profile",
|
||||
"get_financial_statements",
|
||||
"get_basic_financials",
|
||||
# News
|
||||
"get_company_news",
|
||||
"get_market_news",
|
||||
"get_insider_transactions",
|
||||
# Scanner
|
||||
"get_market_movers_finnhub",
|
||||
"get_market_indices_finnhub",
|
||||
"get_sector_performance_finnhub",
|
||||
"get_topic_news_finnhub",
|
||||
"get_earnings_calendar_finnhub",
|
||||
"get_economic_calendar_finnhub",
|
||||
# Indicators
|
||||
"get_indicator_finnhub",
|
||||
# Exceptions
|
||||
"FinnhubError",
|
||||
"APIKeyInvalidError",
|
||||
"RateLimitError",
|
||||
"ThirdPartyError",
|
||||
"ThirdPartyTimeoutError",
|
||||
"ThirdPartyParseError",
|
||||
]
|
||||
|
|
@ -0,0 +1,245 @@
|
|||
"""Common infrastructure for the Finnhub data vendor integration.
|
||||
|
||||
Provides the exception hierarchy, thread-safe rate limiter (60 calls/min for
|
||||
the Finnhub free tier), and the core HTTP request helper used by all other
|
||||
finnhub_* modules.
|
||||
"""
|
||||
|
||||
import json
|
||||
import os
|
||||
import threading
|
||||
import time as _time
|
||||
from datetime import datetime
|
||||
|
||||
import requests
|
||||
|
||||
API_BASE_URL = "https://finnhub.io/api/v1"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# API key helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def get_api_key() -> str:
|
||||
"""Retrieve the Finnhub API key from environment variables.
|
||||
|
||||
Returns:
|
||||
The API key string.
|
||||
|
||||
Raises:
|
||||
APIKeyInvalidError: When FINNHUB_API_KEY is missing or empty.
|
||||
"""
|
||||
api_key = os.environ.get("FINNHUB_API_KEY")
|
||||
if not api_key:
|
||||
raise APIKeyInvalidError(
|
||||
"FINNHUB_API_KEY environment variable is not set or is empty."
|
||||
)
|
||||
return api_key
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Exception hierarchy
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
class FinnhubError(Exception):
|
||||
"""Base exception for all Finnhub API errors."""
|
||||
|
||||
|
||||
class APIKeyInvalidError(FinnhubError):
|
||||
"""Raised when the API key is invalid or missing (401-equivalent)."""
|
||||
|
||||
|
||||
class RateLimitError(FinnhubError):
|
||||
"""Raised when the Finnhub API rate limit is exceeded (429-equivalent)."""
|
||||
|
||||
|
||||
class ThirdPartyError(FinnhubError):
|
||||
"""Raised on server-side errors (5xx status codes) or connection failures."""
|
||||
|
||||
|
||||
class ThirdPartyTimeoutError(FinnhubError):
|
||||
"""Raised when the request times out."""
|
||||
|
||||
|
||||
class ThirdPartyParseError(FinnhubError):
|
||||
"""Raised when the response cannot be parsed as valid JSON."""
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Thread-safe rate limiter — 60 calls/minute (Finnhub free tier)
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
_rate_lock = threading.Lock()
|
||||
_call_timestamps: list[float] = []
|
||||
_RATE_LIMIT = 60 # calls per minute
|
||||
|
||||
|
||||
def _rate_limited_request(endpoint: str, params: dict, timeout: int = 30) -> dict:
|
||||
"""Make a rate-limited Finnhub API request.
|
||||
|
||||
Enforces the 60-calls-per-minute limit for the free tier using a sliding
|
||||
window tracked in a shared list. The lock is released before any sleep
|
||||
to avoid blocking other threads.
|
||||
|
||||
Args:
|
||||
endpoint: Finnhub endpoint path (e.g. "quote").
|
||||
params: Query parameters (excluding the API token).
|
||||
timeout: HTTP request timeout in seconds.
|
||||
|
||||
Returns:
|
||||
Parsed JSON response as a dict.
|
||||
|
||||
Raises:
|
||||
FinnhubError subclass on any API or network error.
|
||||
"""
|
||||
sleep_time = 0.0
|
||||
with _rate_lock:
|
||||
now = _time.time()
|
||||
_call_timestamps[:] = [t for t in _call_timestamps if now - t < 60]
|
||||
if len(_call_timestamps) >= _RATE_LIMIT:
|
||||
sleep_time = 60 - (now - _call_timestamps[0]) + 0.1
|
||||
|
||||
# Sleep outside the lock so other threads are not blocked
|
||||
if sleep_time > 0:
|
||||
_time.sleep(sleep_time)
|
||||
|
||||
# Re-check under lock — another thread may have filled the window while we slept
|
||||
while True:
|
||||
with _rate_lock:
|
||||
now = _time.time()
|
||||
_call_timestamps[:] = [t for t in _call_timestamps if now - t < 60]
|
||||
if len(_call_timestamps) >= _RATE_LIMIT:
|
||||
extra_sleep = 60 - (now - _call_timestamps[0]) + 0.1
|
||||
else:
|
||||
_call_timestamps.append(_time.time())
|
||||
break
|
||||
# Sleep outside the lock
|
||||
_time.sleep(extra_sleep)
|
||||
|
||||
return _make_api_request(endpoint, params, timeout=timeout)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Core HTTP request helper
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _make_api_request(endpoint: str, params: dict, timeout: int = 30) -> dict:
|
||||
"""Make a Finnhub API request with proper error handling.
|
||||
|
||||
Calls ``https://finnhub.io/api/v1/{endpoint}`` and returns the parsed JSON
|
||||
body. The ``token`` parameter is injected automatically from the
|
||||
``FINNHUB_API_KEY`` environment variable.
|
||||
|
||||
Args:
|
||||
endpoint: Finnhub endpoint path without leading slash (e.g. "quote").
|
||||
params: Query parameters dict (do NOT include ``token`` here).
|
||||
timeout: HTTP request timeout in seconds.
|
||||
|
||||
Returns:
|
||||
Parsed JSON response as a dict.
|
||||
|
||||
Raises:
|
||||
APIKeyInvalidError: Invalid or missing API key (HTTP 401 or env missing).
|
||||
RateLimitError: Rate limit exceeded (HTTP 429).
|
||||
ThirdPartyError: Server-side error (5xx) or connection failure.
|
||||
ThirdPartyTimeoutError: Request timed out.
|
||||
ThirdPartyParseError: Response body is not valid JSON.
|
||||
"""
|
||||
api_params = params.copy()
|
||||
api_params["token"] = get_api_key()
|
||||
|
||||
url = f"{API_BASE_URL}/{endpoint}"
|
||||
|
||||
try:
|
||||
response = requests.get(url, params=api_params, timeout=timeout)
|
||||
except requests.exceptions.Timeout:
|
||||
raise ThirdPartyTimeoutError(
|
||||
f"Request timed out: endpoint={endpoint}, params={params}"
|
||||
)
|
||||
except requests.exceptions.ConnectionError as exc:
|
||||
raise ThirdPartyError(
|
||||
f"Connection error: endpoint={endpoint}, error={exc}"
|
||||
)
|
||||
except requests.exceptions.RequestException as exc:
|
||||
raise ThirdPartyError(
|
||||
f"Request failed: endpoint={endpoint}, error={exc}"
|
||||
)
|
||||
|
||||
# HTTP-level error mapping
|
||||
if response.status_code == 401:
|
||||
raise APIKeyInvalidError(
|
||||
f"Invalid API key: status={response.status_code}, body={response.text[:200]}"
|
||||
)
|
||||
if response.status_code == 403:
|
||||
raise APIKeyInvalidError(
|
||||
f"Access forbidden (check API key tier): status={response.status_code}, "
|
||||
f"body={response.text[:200]}"
|
||||
)
|
||||
if response.status_code == 429:
|
||||
raise RateLimitError(
|
||||
f"Rate limit exceeded: status={response.status_code}, body={response.text[:200]}"
|
||||
)
|
||||
if response.status_code >= 500:
|
||||
raise ThirdPartyError(
|
||||
f"Server error: status={response.status_code}, endpoint={endpoint}, "
|
||||
f"body={response.text[:200]}"
|
||||
)
|
||||
try:
|
||||
response.raise_for_status()
|
||||
except requests.exceptions.HTTPError as exc:
|
||||
raise ThirdPartyError(
|
||||
f"HTTP error: status={response.status_code}, endpoint={endpoint}, "
|
||||
f"body={response.text[:200]}"
|
||||
) from exc
|
||||
|
||||
# Parse JSON — Finnhub always returns JSON (never CSV)
|
||||
try:
|
||||
return response.json()
|
||||
except (ValueError, requests.exceptions.JSONDecodeError) as exc:
|
||||
raise ThirdPartyParseError(
|
||||
f"Failed to parse JSON response for endpoint={endpoint}: {exc}. "
|
||||
f"Body preview: {response.text[:200]}"
|
||||
) from exc
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Shared formatting utilities
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _now_str() -> str:
|
||||
"""Return current local datetime as a human-readable string."""
|
||||
return datetime.now().strftime("%Y-%m-%d %H:%M:%S")
|
||||
|
||||
|
||||
def _fmt_pct(value: float | None) -> str:
|
||||
"""Format an optional float as a percentage string with sign.
|
||||
|
||||
Args:
|
||||
value: The percentage value, or None.
|
||||
|
||||
Returns:
|
||||
String like "+1.23%" or "N/A".
|
||||
"""
|
||||
if value is None:
|
||||
return "N/A"
|
||||
return f"{value:+.2f}%"
|
||||
|
||||
|
||||
def _to_unix_timestamp(date_str: str) -> int:
|
||||
"""Convert a YYYY-MM-DD date string to a Unix timestamp (midnight UTC).
|
||||
|
||||
Args:
|
||||
date_str: Date in YYYY-MM-DD format.
|
||||
|
||||
Returns:
|
||||
Unix timestamp as integer.
|
||||
|
||||
Raises:
|
||||
ValueError: When the date string does not match the expected format.
|
||||
"""
|
||||
dt = datetime.strptime(date_str, "%Y-%m-%d")
|
||||
return int(dt.timestamp())
|
||||
|
|
@ -0,0 +1,309 @@
|
|||
"""Finnhub fundamental data functions.
|
||||
|
||||
Provides company profiles, financial statements, and key financial metrics
|
||||
using the Finnhub REST API. Output formats mirror the Alpha Vantage
|
||||
equivalents where possible for consistent agent-facing data.
|
||||
"""
|
||||
|
||||
import json
|
||||
from typing import Literal
|
||||
|
||||
from .finnhub_common import (
|
||||
FinnhubError,
|
||||
ThirdPartyParseError,
|
||||
_make_api_request,
|
||||
_now_str,
|
||||
)
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Type aliases
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
StatementType = Literal["balance_sheet", "income_statement", "cash_flow"]
|
||||
Frequency = Literal["annual", "quarterly"]
|
||||
|
||||
# Mapping from our canonical statement_type names to Finnhub's "statement" param
|
||||
_STATEMENT_MAP: dict[str, str] = {
|
||||
"balance_sheet": "bs",
|
||||
"income_statement": "ic",
|
||||
"cash_flow": "cf",
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Public functions
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def get_company_profile(symbol: str) -> str:
|
||||
"""Fetch company profile and overview via Finnhub /stock/profile2.
|
||||
|
||||
Returns a formatted text block with key company metadata including name,
|
||||
industry, sector, market cap, and shares outstanding — mirroring the
|
||||
information returned by Alpha Vantage OVERVIEW.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
|
||||
Returns:
|
||||
Formatted multi-line string with company profile fields.
|
||||
|
||||
Raises:
|
||||
FinnhubError: When the API returns an error or the symbol is invalid.
|
||||
ThirdPartyParseError: When the response cannot be parsed.
|
||||
"""
|
||||
data = _make_api_request("stock/profile2", {"symbol": symbol})
|
||||
|
||||
if not data:
|
||||
raise FinnhubError(
|
||||
f"Empty profile response for symbol={symbol}. "
|
||||
"Symbol may be invalid or not covered."
|
||||
)
|
||||
|
||||
name = data.get("name", "N/A")
|
||||
ticker = data.get("ticker", symbol)
|
||||
exchange = data.get("exchange", "N/A")
|
||||
ipo_date = data.get("ipo", "N/A")
|
||||
industry = data.get("finnhubIndustry", "N/A")
|
||||
# Finnhub does not return a top-level sector — the industry string is the
|
||||
# finest granularity available in the free profile endpoint.
|
||||
market_cap = data.get("marketCapitalization", None)
|
||||
shares_outstanding = data.get("shareOutstanding", None)
|
||||
currency = data.get("currency", "USD")
|
||||
country = data.get("country", "N/A")
|
||||
website = data.get("weburl", "N/A")
|
||||
logo = data.get("logo", "N/A")
|
||||
phone = data.get("phone", "N/A")
|
||||
|
||||
# Format market cap in billions for readability
|
||||
if market_cap is not None:
|
||||
try:
|
||||
market_cap_str = f"${float(market_cap):,.2f}M"
|
||||
except (ValueError, TypeError):
|
||||
market_cap_str = str(market_cap)
|
||||
else:
|
||||
market_cap_str = "N/A"
|
||||
|
||||
if shares_outstanding is not None:
|
||||
try:
|
||||
shares_str = f"{float(shares_outstanding):,.2f}M"
|
||||
except (ValueError, TypeError):
|
||||
shares_str = str(shares_outstanding)
|
||||
else:
|
||||
shares_str = "N/A"
|
||||
|
||||
lines: list[str] = [
|
||||
f"# Company Profile: {name} ({ticker}) — Finnhub",
|
||||
f"# Data retrieved on: {_now_str()}",
|
||||
"",
|
||||
f"Name: {name}",
|
||||
f"Symbol: {ticker}",
|
||||
f"Exchange: {exchange}",
|
||||
f"Country: {country}",
|
||||
f"Currency: {currency}",
|
||||
f"Industry: {industry}",
|
||||
f"IPO Date: {ipo_date}",
|
||||
f"Market Cap: {market_cap_str}",
|
||||
f"Shares Outstanding: {shares_str}",
|
||||
f"Website: {website}",
|
||||
f"Phone: {phone}",
|
||||
f"Logo: {logo}",
|
||||
]
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def get_financial_statements(
|
||||
symbol: str,
|
||||
statement_type: StatementType = "income_statement",
|
||||
freq: Frequency = "quarterly",
|
||||
) -> str:
|
||||
"""Fetch financial statement data via Finnhub /financials-reported.
|
||||
|
||||
Returns a structured text representation of the most recent reported
|
||||
financial data. Mirrors the pattern of the Alpha Vantage INCOME_STATEMENT,
|
||||
BALANCE_SHEET, and CASH_FLOW endpoints.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
statement_type: One of ``'balance_sheet'``, ``'income_statement'``,
|
||||
or ``'cash_flow'``.
|
||||
freq: Reporting frequency — ``'annual'`` or ``'quarterly'``.
|
||||
|
||||
Returns:
|
||||
Formatted multi-line string with the financial statement data.
|
||||
|
||||
Raises:
|
||||
ValueError: When an unsupported ``statement_type`` is provided.
|
||||
FinnhubError: On API-level errors or missing data.
|
||||
ThirdPartyParseError: When the response cannot be parsed.
|
||||
"""
|
||||
if statement_type not in _STATEMENT_MAP:
|
||||
raise ValueError(
|
||||
f"Invalid statement_type '{statement_type}'. "
|
||||
f"Must be one of: {list(_STATEMENT_MAP.keys())}"
|
||||
)
|
||||
|
||||
finnhub_statement = _STATEMENT_MAP[statement_type]
|
||||
# Finnhub uses "annual" / "quarterly" directly
|
||||
params = {
|
||||
"symbol": symbol,
|
||||
"freq": freq,
|
||||
}
|
||||
|
||||
data = _make_api_request("financials-reported", params)
|
||||
|
||||
reports: list[dict] = data.get("data", [])
|
||||
if not reports:
|
||||
raise FinnhubError(
|
||||
f"No financial reports returned for symbol={symbol}, "
|
||||
f"statement_type={statement_type}, freq={freq}"
|
||||
)
|
||||
|
||||
# Use the most recent report
|
||||
latest_report = reports[0]
|
||||
period = latest_report.get("period", "N/A")
|
||||
year = latest_report.get("year", "N/A")
|
||||
quarter = latest_report.get("quarter", "")
|
||||
filing_date = latest_report.get("filedDate", "N/A")
|
||||
accepted_date = latest_report.get("acceptedDate", "N/A")
|
||||
form = latest_report.get("form", "N/A")
|
||||
cik = latest_report.get("cik", "N/A")
|
||||
|
||||
# The 'report' sub-dict holds the three statement types under keys "bs", "ic", "cf"
|
||||
report_data: dict = latest_report.get("report", {})
|
||||
statement_rows: list[dict] = report_data.get(finnhub_statement, [])
|
||||
|
||||
period_label = f"Q{quarter} {year}" if quarter else str(year)
|
||||
header = (
|
||||
f"# {statement_type.replace('_', ' ').title()} — {symbol} "
|
||||
f"({period_label}, {freq.title()}) — Finnhub\n"
|
||||
f"# Data retrieved on: {_now_str()}\n"
|
||||
f"# Filing: {form} | Filed: {filing_date} | Accepted: {accepted_date}\n"
|
||||
f"# CIK: {cik} | Period: {period}\n\n"
|
||||
)
|
||||
|
||||
if not statement_rows:
|
||||
return header + "_No line items found in this report._\n"
|
||||
|
||||
lines: list[str] = [header]
|
||||
lines.append(f"{'Concept':<50} {'Unit':<10} {'Value':>20}")
|
||||
lines.append("-" * 82)
|
||||
|
||||
for row in statement_rows:
|
||||
concept = row.get("concept", "N/A")
|
||||
label = row.get("label", concept)
|
||||
unit = row.get("unit", "USD")
|
||||
value = row.get("value", None)
|
||||
|
||||
if value is None:
|
||||
value_str = "N/A"
|
||||
else:
|
||||
try:
|
||||
value_str = f"{float(value):>20,.0f}"
|
||||
except (ValueError, TypeError):
|
||||
value_str = str(value)
|
||||
|
||||
# Truncate long labels to keep alignment readable
|
||||
display_label = label[:49] if len(label) > 49 else label
|
||||
lines.append(f"{display_label:<50} {unit:<10} {value_str}")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def get_basic_financials(symbol: str) -> str:
|
||||
"""Fetch key financial ratios and metrics via Finnhub /stock/metric.
|
||||
|
||||
Returns a formatted text block with P/E, P/B, ROE, debt/equity, 52-week
|
||||
range, and other standard financial metrics — mirroring the kind of data
|
||||
returned by Alpha Vantage OVERVIEW for ratio-focused consumers.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
|
||||
Returns:
|
||||
Formatted multi-line string with key financial metrics.
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API-level errors or missing data.
|
||||
ThirdPartyParseError: When the response cannot be parsed.
|
||||
"""
|
||||
data = _make_api_request("stock/metric", {"symbol": symbol, "metric": "all"})
|
||||
|
||||
metric: dict = data.get("metric", {})
|
||||
if not metric:
|
||||
raise FinnhubError(
|
||||
f"No metric data returned for symbol={symbol}. "
|
||||
"Symbol may be invalid or not covered on the free tier."
|
||||
)
|
||||
|
||||
series: dict = data.get("series", {})
|
||||
|
||||
def _fmt(key: str, prefix: str = "", suffix: str = "") -> str:
|
||||
"""Format a metric value with optional prefix/suffix."""
|
||||
val = metric.get(key)
|
||||
if val is None:
|
||||
return "N/A"
|
||||
try:
|
||||
return f"{prefix}{float(val):,.4f}{suffix}"
|
||||
except (ValueError, TypeError):
|
||||
return str(val)
|
||||
|
||||
def _fmt_int(key: str, prefix: str = "", suffix: str = "") -> str:
|
||||
"""Format a metric value as an integer."""
|
||||
val = metric.get(key)
|
||||
if val is None:
|
||||
return "N/A"
|
||||
try:
|
||||
return f"{prefix}{int(float(val)):,}{suffix}"
|
||||
except (ValueError, TypeError):
|
||||
return str(val)
|
||||
|
||||
lines: list[str] = [
|
||||
f"# Key Financial Metrics: {symbol} — Finnhub",
|
||||
f"# Data retrieved on: {_now_str()}",
|
||||
"",
|
||||
"## Valuation",
|
||||
f" P/E (TTM): {_fmt('peTTM')}",
|
||||
f" P/E (Annual): {_fmt('peAnnual')}",
|
||||
f" P/B (Quarterly): {_fmt('pbQuarterly')}",
|
||||
f" P/B (Annual): {_fmt('pbAnnual')}",
|
||||
f" P/S (TTM): {_fmt('psTTM')}",
|
||||
f" P/CF (TTM): {_fmt('pcfShareTTM')}",
|
||||
f" EV/EBITDA (TTM): {_fmt('evEbitdaTTM')}",
|
||||
"",
|
||||
"## Price Range",
|
||||
f" 52-Week High: {_fmt('52WeekHigh', prefix='$')}",
|
||||
f" 52-Week Low: {_fmt('52WeekLow', prefix='$')}",
|
||||
f" 52-Week Return: {_fmt('52WeekPriceReturnDaily', suffix='%')}",
|
||||
f" Beta (5Y Monthly): {_fmt('beta')}",
|
||||
"",
|
||||
"## Profitability",
|
||||
f" ROE (TTM): {_fmt('roeTTM', suffix='%')}",
|
||||
f" ROA (TTM): {_fmt('roaTTM', suffix='%')}",
|
||||
f" ROIC (TTM): {_fmt('roicTTM', suffix='%')}",
|
||||
f" Gross Margin (TTM): {_fmt('grossMarginTTM', suffix='%')}",
|
||||
f" Net Profit Margin (TTM): {_fmt('netProfitMarginTTM', suffix='%')}",
|
||||
f" Operating Margin (TTM): {_fmt('operatingMarginTTM', suffix='%')}",
|
||||
"",
|
||||
"## Leverage",
|
||||
f" Total Debt/Equity (Quarterly):{_fmt('totalDebt/totalEquityQuarterly')}",
|
||||
f" Total Debt/Equity (Annual): {_fmt('totalDebt/totalEquityAnnual')}",
|
||||
f" Current Ratio (Quarterly): {_fmt('currentRatioQuarterly')}",
|
||||
f" Quick Ratio (Quarterly): {_fmt('quickRatioQuarterly')}",
|
||||
"",
|
||||
"## Growth",
|
||||
f" EPS Growth (TTM YoY): {_fmt('epsGrowthTTMYoy', suffix='%')}",
|
||||
f" Revenue Growth (TTM YoY): {_fmt('revenueGrowthTTMYoy', suffix='%')}",
|
||||
f" Dividend Yield (TTM): {_fmt('dividendYieldIndicatedAnnual', suffix='%')}",
|
||||
f" Payout Ratio (TTM): {_fmt('payoutRatioTTM', suffix='%')}",
|
||||
"",
|
||||
"## Per Share",
|
||||
f" EPS (TTM): {_fmt('epsTTM', prefix='$')}",
|
||||
f" EPS (Annual): {_fmt('epsAnnual', prefix='$')}",
|
||||
f" Revenue Per Share (TTM): {_fmt('revenuePerShareTTM', prefix='$')}",
|
||||
f" Free Cash Flow Per Share: {_fmt('fcfPerShareTTM', prefix='$')}",
|
||||
f" Book Value Per Share (Qtr): {_fmt('bookValuePerShareQuarterly', prefix='$')}",
|
||||
]
|
||||
|
||||
return "\n".join(lines)
|
||||
|
|
@ -0,0 +1,224 @@
|
|||
"""Finnhub technical indicator functions.
|
||||
|
||||
Provides technical analysis indicators (SMA, EMA, MACD, RSI, BBANDS, ATR)
|
||||
via the Finnhub /indicator endpoint. Output format mirrors the Alpha Vantage
|
||||
indicator output so downstream agents see consistent data regardless of vendor.
|
||||
"""
|
||||
|
||||
from datetime import datetime, timedelta
|
||||
from typing import Literal
|
||||
|
||||
from .finnhub_common import (
|
||||
FinnhubError,
|
||||
ThirdPartyParseError,
|
||||
_make_api_request,
|
||||
_now_str,
|
||||
_to_unix_timestamp,
|
||||
)
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Constants
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# Supported indicators and their Finnhub indicator name
|
||||
_INDICATOR_CONFIG: dict[str, dict] = {
|
||||
"sma": {
|
||||
"indicator": "sma",
|
||||
"description": (
|
||||
"SMA: Simple Moving Average. Smooths price data over N periods to "
|
||||
"identify trend direction. Lags price — combine with faster indicators "
|
||||
"for timely signals."
|
||||
),
|
||||
"value_key": "sma",
|
||||
},
|
||||
"ema": {
|
||||
"indicator": "ema",
|
||||
"description": (
|
||||
"EMA: Exponential Moving Average. Gives more weight to recent prices "
|
||||
"than SMA, reacting faster to price changes. Useful for short-term trend "
|
||||
"identification and dynamic support/resistance."
|
||||
),
|
||||
"value_key": "ema",
|
||||
},
|
||||
"macd": {
|
||||
"indicator": "macd",
|
||||
"description": (
|
||||
"MACD: Moving Average Convergence/Divergence. Computes momentum via "
|
||||
"differences of EMAs. Look for crossovers and divergence as signals of "
|
||||
"trend changes. Confirm with other indicators in sideways markets."
|
||||
),
|
||||
"value_key": "macd",
|
||||
},
|
||||
"rsi": {
|
||||
"indicator": "rsi",
|
||||
"description": (
|
||||
"RSI: Relative Strength Index. Measures momentum to flag overbought "
|
||||
"(>70) and oversold (<30) conditions. In strong trends RSI may remain "
|
||||
"extreme — always cross-check with trend analysis."
|
||||
),
|
||||
"value_key": "rsi",
|
||||
},
|
||||
"bbands": {
|
||||
"indicator": "bbands",
|
||||
"description": (
|
||||
"BBANDS: Bollinger Bands. Upper, middle (SMA), and lower bands "
|
||||
"representing 2 standard deviations from the middle. Signals potential "
|
||||
"overbought/oversold zones and breakout areas."
|
||||
),
|
||||
"value_key": "upperBand", # primary value; lowerBand and middleBand also returned
|
||||
},
|
||||
"atr": {
|
||||
"indicator": "atr",
|
||||
"description": (
|
||||
"ATR: Average True Range. Averages true range to measure volatility. "
|
||||
"Used for setting stop-loss levels and adjusting position sizes based on "
|
||||
"current market volatility."
|
||||
),
|
||||
"value_key": "atr",
|
||||
},
|
||||
}
|
||||
|
||||
SupportedIndicator = Literal["sma", "ema", "macd", "rsi", "bbands", "atr"]
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Public function
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def get_indicator_finnhub(
|
||||
symbol: str,
|
||||
indicator: SupportedIndicator,
|
||||
start_date: str,
|
||||
end_date: str,
|
||||
time_period: int = 14,
|
||||
series_type: str = "close",
|
||||
**params: object,
|
||||
) -> str:
|
||||
"""Fetch a technical indicator series from Finnhub /indicator.
|
||||
|
||||
Calls the Finnhub ``/indicator`` endpoint for the given symbol and date
|
||||
range, then formats the result as a labelled time-series string that matches
|
||||
the output style of ``alpha_vantage_indicator.get_indicator``.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
indicator: One of ``'sma'``, ``'ema'``, ``'macd'``, ``'rsi'``,
|
||||
``'bbands'``, ``'atr'``.
|
||||
start_date: Inclusive start date in YYYY-MM-DD format.
|
||||
end_date: Inclusive end date in YYYY-MM-DD format.
|
||||
time_period: Number of data points used for indicator calculation
|
||||
(default 14). Maps to the ``timeperiod`` Finnhub parameter.
|
||||
series_type: Price field used for calculation — ``'close'``,
|
||||
``'open'``, ``'high'``, or ``'low'`` (default ``'close'``).
|
||||
**params: Additional keyword arguments forwarded to the Finnhub
|
||||
endpoint (e.g. ``fastPeriod``, ``slowPeriod`` for MACD).
|
||||
|
||||
Returns:
|
||||
Formatted multi-line string with date-value pairs and a description,
|
||||
mirroring the Alpha Vantage indicator format.
|
||||
|
||||
Raises:
|
||||
ValueError: When an unsupported indicator name is provided.
|
||||
FinnhubError: On API-level errors or when the symbol returns no data.
|
||||
ThirdPartyParseError: When the response cannot be parsed.
|
||||
"""
|
||||
indicator_lower = indicator.lower()
|
||||
if indicator_lower not in _INDICATOR_CONFIG:
|
||||
raise ValueError(
|
||||
f"Indicator '{indicator}' is not supported. "
|
||||
f"Supported indicators: {sorted(_INDICATOR_CONFIG.keys())}"
|
||||
)
|
||||
|
||||
config = _INDICATOR_CONFIG[indicator_lower]
|
||||
finnhub_indicator = config["indicator"]
|
||||
description = config["description"]
|
||||
primary_value_key = config["value_key"]
|
||||
|
||||
# Finnhub /indicator uses Unix timestamps
|
||||
from_ts = _to_unix_timestamp(start_date)
|
||||
# Add an extra day to end_date to include it fully
|
||||
to_ts = _to_unix_timestamp(end_date) + 86400
|
||||
|
||||
request_params: dict = {
|
||||
"symbol": symbol,
|
||||
"resolution": "D",
|
||||
"from": from_ts,
|
||||
"to": to_ts,
|
||||
"indicator": finnhub_indicator,
|
||||
"timeperiod": time_period,
|
||||
"seriestype": series_type,
|
||||
}
|
||||
# Merge any caller-supplied extra params (e.g. fastPeriod, slowPeriod for MACD)
|
||||
request_params.update(params)
|
||||
|
||||
data = _make_api_request("indicator", request_params)
|
||||
|
||||
# Finnhub returns parallel lists: "t" for timestamps and indicator-named lists
|
||||
timestamps: list[int] = data.get("t", [])
|
||||
status = data.get("s")
|
||||
|
||||
if status == "no_data" or not timestamps:
|
||||
raise FinnhubError(
|
||||
f"No indicator data returned for symbol={symbol}, "
|
||||
f"indicator={indicator}, start={start_date}, end={end_date}"
|
||||
)
|
||||
|
||||
if status != "ok":
|
||||
raise FinnhubError(
|
||||
f"Unexpected indicator response status '{status}' for "
|
||||
f"symbol={symbol}, indicator={indicator}"
|
||||
)
|
||||
|
||||
# Build the result string — handle multi-value indicators like MACD and BBANDS
|
||||
result_lines: list[str] = [
|
||||
f"## {indicator.upper()} values from {start_date} to {end_date} — Finnhub",
|
||||
f"## Symbol: {symbol} | Time Period: {time_period} | Series: {series_type}",
|
||||
"",
|
||||
]
|
||||
|
||||
if indicator_lower == "macd":
|
||||
macd_vals: list[float | None] = data.get("macd", [])
|
||||
signal_vals: list[float | None] = data.get("macdSignal", [])
|
||||
hist_vals: list[float | None] = data.get("macdHist", [])
|
||||
|
||||
result_lines.append(f"{'Date':<12} {'MACD':>12} {'Signal':>12} {'Histogram':>12}")
|
||||
result_lines.append("-" * 50)
|
||||
|
||||
for ts, macd, signal, hist in zip(timestamps, macd_vals, signal_vals, hist_vals):
|
||||
date_str = datetime.fromtimestamp(ts).strftime("%Y-%m-%d")
|
||||
macd_s = f"{macd:.4f}" if macd is not None else "N/A"
|
||||
sig_s = f"{signal:.4f}" if signal is not None else "N/A"
|
||||
hist_s = f"{hist:.4f}" if hist is not None else "N/A"
|
||||
result_lines.append(f"{date_str:<12} {macd_s:>12} {sig_s:>12} {hist_s:>12}")
|
||||
|
||||
elif indicator_lower == "bbands":
|
||||
upper_vals: list[float | None] = data.get("upperBand", [])
|
||||
middle_vals: list[float | None] = data.get("middleBand", [])
|
||||
lower_vals: list[float | None] = data.get("lowerBand", [])
|
||||
|
||||
result_lines.append(f"{'Date':<12} {'Upper':>12} {'Middle':>12} {'Lower':>12}")
|
||||
result_lines.append("-" * 50)
|
||||
|
||||
for ts, upper, middle, lower in zip(timestamps, upper_vals, middle_vals, lower_vals):
|
||||
date_str = datetime.fromtimestamp(ts).strftime("%Y-%m-%d")
|
||||
u_s = f"{upper:.4f}" if upper is not None else "N/A"
|
||||
m_s = f"{middle:.4f}" if middle is not None else "N/A"
|
||||
l_s = f"{lower:.4f}" if lower is not None else "N/A"
|
||||
result_lines.append(f"{date_str:<12} {u_s:>12} {m_s:>12} {l_s:>12}")
|
||||
|
||||
else:
|
||||
# Single-value indicators: SMA, EMA, RSI, ATR
|
||||
values: list[float | None] = data.get(primary_value_key, [])
|
||||
|
||||
result_lines.append(f"{'Date':<12} {indicator.upper():>12}")
|
||||
result_lines.append("-" * 26)
|
||||
|
||||
for ts, value in zip(timestamps, values):
|
||||
date_str = datetime.fromtimestamp(ts).strftime("%Y-%m-%d")
|
||||
val_s = f"{value:.4f}" if value is not None else "N/A"
|
||||
result_lines.append(f"{date_str:<12} {val_s:>12}")
|
||||
|
||||
result_lines.append("")
|
||||
result_lines.append(description)
|
||||
|
||||
return "\n".join(result_lines)
|
||||
|
|
@ -0,0 +1,245 @@
|
|||
"""Finnhub news and insider transaction functions.
|
||||
|
||||
Provides company-specific news, broad market news by category, and insider
|
||||
transaction data using the Finnhub REST API. Output formats mirror the
|
||||
Alpha Vantage news equivalents for consistent agent-facing data.
|
||||
"""
|
||||
|
||||
from datetime import datetime
|
||||
from typing import Literal
|
||||
|
||||
from .finnhub_common import (
|
||||
FinnhubError,
|
||||
_make_api_request,
|
||||
_now_str,
|
||||
_to_unix_timestamp,
|
||||
)
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Type aliases
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
NewsCategory = Literal["general", "forex", "crypto", "merger"]
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Internal helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _format_unix_ts(ts: int | None) -> str:
|
||||
"""Convert a Unix timestamp to a human-readable datetime string.
|
||||
|
||||
Args:
|
||||
ts: Unix timestamp (seconds since epoch), or None.
|
||||
|
||||
Returns:
|
||||
Formatted string like "2024-03-15 13:00:00", or "N/A" for None/zero.
|
||||
"""
|
||||
if not ts:
|
||||
return "N/A"
|
||||
try:
|
||||
return datetime.fromtimestamp(int(ts)).strftime("%Y-%m-%d %H:%M:%S")
|
||||
except (OSError, OverflowError, ValueError):
|
||||
return str(ts)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Public functions
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def get_company_news(symbol: str, start_date: str, end_date: str) -> str:
|
||||
"""Fetch company-specific news via Finnhub /company-news.
|
||||
|
||||
Returns a formatted markdown string with recent news for the given ticker,
|
||||
mirroring the output format of Alpha Vantage NEWS_SENTIMENT.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
start_date: Inclusive start date in YYYY-MM-DD format.
|
||||
end_date: Inclusive end date in YYYY-MM-DD format.
|
||||
|
||||
Returns:
|
||||
Formatted markdown string with article headlines, sources, summaries,
|
||||
and datetimes.
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API-level errors.
|
||||
"""
|
||||
params = {
|
||||
"symbol": symbol,
|
||||
"from": start_date,
|
||||
"to": end_date,
|
||||
}
|
||||
|
||||
articles: list[dict] = _make_api_request("company-news", params)
|
||||
|
||||
header = (
|
||||
f"# Company News: {symbol} ({start_date} to {end_date}) — Finnhub\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
|
||||
if not articles:
|
||||
return header + f"_No news articles found for {symbol} in the specified date range._\n"
|
||||
|
||||
lines: list[str] = [header]
|
||||
for article in articles:
|
||||
headline = article.get("headline", "No headline")
|
||||
source = article.get("source", "Unknown")
|
||||
summary = article.get("summary", "")
|
||||
url = article.get("url", "")
|
||||
datetime_unix: int = article.get("datetime", 0)
|
||||
category = article.get("category", "")
|
||||
sentiment = article.get("sentiment", None)
|
||||
|
||||
published = _format_unix_ts(datetime_unix)
|
||||
|
||||
lines.append(f"### {headline}")
|
||||
meta = f"**Source:** {source} | **Published:** {published}"
|
||||
if category:
|
||||
meta += f" | **Category:** {category}"
|
||||
if sentiment is not None:
|
||||
meta += f" | **Sentiment:** {sentiment}"
|
||||
lines.append(meta)
|
||||
|
||||
if summary:
|
||||
lines.append(summary)
|
||||
if url:
|
||||
lines.append(f"**Link:** {url}")
|
||||
lines.append("")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def get_market_news(category: NewsCategory = "general") -> str:
|
||||
"""Fetch broad market news via Finnhub /news.
|
||||
|
||||
Returns a formatted markdown string with the latest news items for the
|
||||
requested category.
|
||||
|
||||
Args:
|
||||
category: News category — one of ``'general'``, ``'forex'``,
|
||||
``'crypto'``, or ``'merger'``.
|
||||
|
||||
Returns:
|
||||
Formatted markdown string with news articles.
|
||||
|
||||
Raises:
|
||||
ValueError: When an unsupported category is provided.
|
||||
FinnhubError: On API-level errors.
|
||||
"""
|
||||
valid_categories: set[str] = {"general", "forex", "crypto", "merger"}
|
||||
if category not in valid_categories:
|
||||
raise ValueError(
|
||||
f"Invalid category '{category}'. Must be one of: {sorted(valid_categories)}"
|
||||
)
|
||||
|
||||
articles: list[dict] = _make_api_request("news", {"category": category})
|
||||
|
||||
header = (
|
||||
f"# Market News: {category.title()} — Finnhub\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
|
||||
if not articles:
|
||||
return header + f"_No news articles found for category '{category}'._\n"
|
||||
|
||||
lines: list[str] = [header]
|
||||
for article in articles:
|
||||
headline = article.get("headline", "No headline")
|
||||
source = article.get("source", "Unknown")
|
||||
summary = article.get("summary", "")
|
||||
url = article.get("url", "")
|
||||
datetime_unix: int = article.get("datetime", 0)
|
||||
|
||||
published = _format_unix_ts(datetime_unix)
|
||||
|
||||
lines.append(f"### {headline}")
|
||||
lines.append(f"**Source:** {source} | **Published:** {published}")
|
||||
if summary:
|
||||
lines.append(summary)
|
||||
if url:
|
||||
lines.append(f"**Link:** {url}")
|
||||
lines.append("")
|
||||
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def get_insider_transactions(symbol: str) -> str:
|
||||
"""Fetch insider buy/sell transactions via Finnhub /stock/insider-transactions.
|
||||
|
||||
Returns a formatted markdown table with recent insider trades by executives,
|
||||
directors, and major shareholders, mirroring the output pattern of the
|
||||
Alpha Vantage INSIDER_TRANSACTIONS endpoint.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
|
||||
Returns:
|
||||
Formatted markdown string with insider transaction details.
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API-level errors or empty response.
|
||||
"""
|
||||
data = _make_api_request("stock/insider-transactions", {"symbol": symbol})
|
||||
|
||||
transactions: list[dict] = data.get("data", [])
|
||||
|
||||
header = (
|
||||
f"# Insider Transactions: {symbol} — Finnhub\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
|
||||
if not transactions:
|
||||
return header + f"_No insider transactions found for {symbol}._\n"
|
||||
|
||||
lines: list[str] = [header]
|
||||
lines.append("| Name | Transaction | Shares | Share Price | Value | Date | Filing Date |")
|
||||
lines.append("|------|-------------|--------|-------------|-------|------|-------------|")
|
||||
|
||||
for txn in transactions:
|
||||
name = txn.get("name", "N/A")
|
||||
transaction_code = txn.get("transactionCode", "")
|
||||
# Map Finnhub transaction codes to human-readable labels
|
||||
# P = Purchase, S = Sale, A = Award/Grant
|
||||
code_label_map = {
|
||||
"P": "Buy",
|
||||
"S": "Sell",
|
||||
"A": "Award/Grant",
|
||||
"D": "Disposition",
|
||||
"M": "Option Exercise",
|
||||
"G": "Gift",
|
||||
"F": "Tax Withholding",
|
||||
"X": "Option Exercise",
|
||||
"C": "Conversion",
|
||||
}
|
||||
txn_label = code_label_map.get(transaction_code, transaction_code or "N/A")
|
||||
|
||||
raw_shares = txn.get("share", None)
|
||||
try:
|
||||
shares_str = f"{int(float(raw_shares)):,}" if raw_shares is not None else "N/A"
|
||||
except (ValueError, TypeError):
|
||||
shares_str = str(raw_shares)
|
||||
|
||||
raw_price = txn.get("price", None)
|
||||
try:
|
||||
price_str = f"${float(raw_price):.2f}" if raw_price is not None else "N/A"
|
||||
except (ValueError, TypeError):
|
||||
price_str = str(raw_price)
|
||||
|
||||
raw_value = txn.get("value", None)
|
||||
try:
|
||||
value_str = f"${float(raw_value):,.0f}" if raw_value is not None else "N/A"
|
||||
except (ValueError, TypeError):
|
||||
value_str = str(raw_value)
|
||||
|
||||
txn_date = txn.get("transactionDate", "N/A")
|
||||
filing_date = txn.get("filingDate", "N/A")
|
||||
|
||||
lines.append(
|
||||
f"| {name} | {txn_label} | {shares_str} | {price_str} | "
|
||||
f"{value_str} | {txn_date} | {filing_date} |"
|
||||
)
|
||||
|
||||
return "\n".join(lines)
|
||||
|
|
@ -0,0 +1,462 @@
|
|||
"""Finnhub-based scanner data for market-wide analysis.
|
||||
|
||||
Provides market movers, index levels, sector performance, and topic news
|
||||
using the Finnhub REST API. The public function names match the Alpha Vantage
|
||||
scanner equivalents (with ``_finnhub`` suffix) so they slot cleanly into the
|
||||
vendor routing layer in ``interface.py``.
|
||||
|
||||
Notes on Finnhub free-tier limitations:
|
||||
- There is no dedicated TOP_GAINERS / TOP_LOSERS endpoint on the free tier.
|
||||
``get_market_movers_finnhub`` fetches quotes for a curated basket of large-cap
|
||||
S&P 500 stocks and sorts by daily change percentage.
|
||||
- The /news endpoint maps topic strings to the four available Finnhub categories
|
||||
(general, forex, crypto, merger).
|
||||
"""
|
||||
|
||||
from datetime import datetime
|
||||
from typing import Annotated
|
||||
|
||||
from .finnhub_common import (
|
||||
FinnhubError,
|
||||
RateLimitError,
|
||||
ThirdPartyError,
|
||||
ThirdPartyParseError,
|
||||
ThirdPartyTimeoutError,
|
||||
_make_api_request,
|
||||
_now_str,
|
||||
_rate_limited_request,
|
||||
)
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Constants
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
# Representative S&P 500 large-caps used as the movers basket.
|
||||
# Sorted roughly by market-cap weight — first 50 cover the bulk of the index.
|
||||
_SP500_SAMPLE: list[str] = [
|
||||
"AAPL", "MSFT", "NVDA", "AMZN", "GOOGL", "META", "TSLA", "BRK.B", "UNH", "LLY",
|
||||
"JPM", "XOM", "V", "AVGO", "PG", "MA", "JNJ", "HD", "MRK", "ABBV",
|
||||
"CVX", "COST", "CRM", "AMD", "NFLX", "WMT", "BAC", "KO", "PEP", "ADBE",
|
||||
"TMO", "ACN", "MCD", "CSCO", "ABT", "GE", "DHR", "TXN", "NKE", "PFE",
|
||||
"NEE", "WFC", "ORCL", "COP", "CAT", "DIS", "MS", "LIN", "BMY", "HON",
|
||||
]
|
||||
|
||||
# SPDR ETFs used as sector proxies (11 GICS sectors)
|
||||
_SECTOR_ETFS: dict[str, str] = {
|
||||
"Technology": "XLK",
|
||||
"Healthcare": "XLV",
|
||||
"Financials": "XLF",
|
||||
"Energy": "XLE",
|
||||
"Consumer Discretionary": "XLY",
|
||||
"Consumer Staples": "XLP",
|
||||
"Industrials": "XLI",
|
||||
"Materials": "XLB",
|
||||
"Real Estate": "XLRE",
|
||||
"Utilities": "XLU",
|
||||
"Communication Services": "XLC",
|
||||
}
|
||||
|
||||
# Index ETF proxies
|
||||
_INDEX_PROXIES: list[tuple[str, str]] = [
|
||||
("S&P 500 (SPY)", "SPY"),
|
||||
("Dow Jones (DIA)", "DIA"),
|
||||
("NASDAQ (QQQ)", "QQQ"),
|
||||
("Russell 2000 (IWM)", "IWM"),
|
||||
("VIX (^VIX)", "^VIX"),
|
||||
]
|
||||
|
||||
# Mapping from human topic strings → Finnhub /news category
|
||||
_TOPIC_TO_CATEGORY: dict[str, str] = {
|
||||
"market": "general",
|
||||
"general": "general",
|
||||
"economy": "general",
|
||||
"macro": "general",
|
||||
"technology": "general",
|
||||
"tech": "general",
|
||||
"finance": "general",
|
||||
"financial": "general",
|
||||
"earnings": "general",
|
||||
"ipo": "general",
|
||||
"mergers": "merger",
|
||||
"m&a": "merger",
|
||||
"merger": "merger",
|
||||
"acquisition": "merger",
|
||||
"forex": "forex",
|
||||
"fx": "forex",
|
||||
"currency": "forex",
|
||||
"crypto": "crypto",
|
||||
"cryptocurrency": "crypto",
|
||||
"blockchain": "crypto",
|
||||
"bitcoin": "crypto",
|
||||
"ethereum": "crypto",
|
||||
}
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Internal helpers
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def _fetch_quote(symbol: str) -> dict:
|
||||
"""Fetch a single Finnhub quote for a symbol using the rate limiter.
|
||||
|
||||
Args:
|
||||
symbol: Ticker symbol.
|
||||
|
||||
Returns:
|
||||
Normalised quote dict with keys: symbol, current_price, change,
|
||||
change_percent, high, low, open, prev_close.
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API or parse errors.
|
||||
"""
|
||||
data = _rate_limited_request("quote", {"symbol": symbol})
|
||||
|
||||
current_price: float = data.get("c", 0.0)
|
||||
prev_close: float = data.get("pc", 0.0)
|
||||
change: float = data.get("d") or 0.0
|
||||
change_pct: float = data.get("dp") or 0.0
|
||||
|
||||
return {
|
||||
"symbol": symbol,
|
||||
"current_price": current_price,
|
||||
"change": change,
|
||||
"change_percent": change_pct,
|
||||
"high": data.get("h", 0.0),
|
||||
"low": data.get("l", 0.0),
|
||||
"open": data.get("o", 0.0),
|
||||
"prev_close": prev_close,
|
||||
}
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Public scanner functions
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def get_market_movers_finnhub(
|
||||
category: Annotated[str, "Category: 'gainers', 'losers', or 'active'"],
|
||||
) -> str:
|
||||
"""Get market movers by fetching quotes for a basket of large-cap S&P 500 stocks.
|
||||
|
||||
Finnhub's free tier does not expose a TOP_GAINERS_LOSERS endpoint. This
|
||||
function fetches /quote for a pre-defined sample of 50 large-cap tickers
|
||||
and sorts by daily change percentage to approximate gainer/loser lists.
|
||||
|
||||
The 'active' category uses absolute change percentage (highest volatility).
|
||||
|
||||
Args:
|
||||
category: One of ``'gainers'``, ``'losers'``, or ``'active'``.
|
||||
|
||||
Returns:
|
||||
Markdown table with Symbol, Price, Change, Change %, ranked by category.
|
||||
|
||||
Raises:
|
||||
ValueError: When an unsupported category is requested.
|
||||
FinnhubError: When all quote fetches fail.
|
||||
"""
|
||||
valid_categories = {"gainers", "losers", "active"}
|
||||
if category not in valid_categories:
|
||||
raise ValueError(
|
||||
f"Invalid category '{category}'. Must be one of: {sorted(valid_categories)}"
|
||||
)
|
||||
|
||||
rows: list[dict] = []
|
||||
errors: list[str] = []
|
||||
|
||||
for symbol in _SP500_SAMPLE:
|
||||
try:
|
||||
quote = _fetch_quote(symbol)
|
||||
# Skip symbols where the market is closed / data unavailable
|
||||
if quote["current_price"] == 0 and quote["prev_close"] == 0:
|
||||
continue
|
||||
rows.append(quote)
|
||||
except (FinnhubError, RateLimitError, ThirdPartyError,
|
||||
ThirdPartyTimeoutError, ThirdPartyParseError) as exc:
|
||||
errors.append(f"{symbol}: {exc!s:.60}")
|
||||
|
||||
if not rows:
|
||||
raise FinnhubError(
|
||||
f"All {len(_SP500_SAMPLE)} quote fetches failed for market movers. "
|
||||
f"Sample error: {errors[0] if errors else 'unknown'}"
|
||||
)
|
||||
|
||||
# Sort according to category
|
||||
if category == "gainers":
|
||||
rows.sort(key=lambda r: r["change_percent"], reverse=True)
|
||||
label = "Top Gainers"
|
||||
elif category == "losers":
|
||||
rows.sort(key=lambda r: r["change_percent"])
|
||||
label = "Top Losers"
|
||||
else: # active — sort by absolute change %
|
||||
rows.sort(key=lambda r: abs(r["change_percent"]), reverse=True)
|
||||
label = "Most Active (by Change %)"
|
||||
|
||||
header = (
|
||||
f"# Market Movers: {label} (Finnhub — S&P 500 Sample)\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
result = header
|
||||
result += "| Symbol | Price | Change | Change % |\n"
|
||||
result += "|--------|-------|--------|----------|\n"
|
||||
|
||||
for row in rows[:15]:
|
||||
symbol = row["symbol"]
|
||||
price_str = f"${row['current_price']:.2f}"
|
||||
change_str = f"{row['change']:+.2f}"
|
||||
change_pct_str = f"{row['change_percent']:+.2f}%"
|
||||
result += f"| {symbol} | {price_str} | {change_str} | {change_pct_str} |\n"
|
||||
|
||||
if errors:
|
||||
result += f"\n_Note: {len(errors)} symbols failed to fetch._\n"
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def get_market_indices_finnhub() -> str:
|
||||
"""Get major market index levels via Finnhub /quote for ETF proxies and VIX.
|
||||
|
||||
Fetches quotes for: SPY (S&P 500), DIA (Dow Jones), QQQ (NASDAQ),
|
||||
IWM (Russell 2000), and ^VIX (Volatility Index).
|
||||
|
||||
Returns:
|
||||
Markdown table with Index, Price, Change, Change %.
|
||||
|
||||
Raises:
|
||||
FinnhubError: When all index fetches fail.
|
||||
"""
|
||||
header = (
|
||||
f"# Major Market Indices (Finnhub)\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
result = header
|
||||
result += "| Index | Price | Change | Change % |\n"
|
||||
result += "|-------|-------|--------|----------|\n"
|
||||
|
||||
success_count = 0
|
||||
|
||||
for display_name, symbol in _INDEX_PROXIES:
|
||||
try:
|
||||
quote = _fetch_quote(symbol)
|
||||
price = quote["current_price"]
|
||||
change = quote["change"]
|
||||
change_pct = quote["change_percent"]
|
||||
|
||||
# VIX has no dollar sign
|
||||
is_vix = "VIX" in display_name
|
||||
price_str = f"{price:.2f}" if is_vix else f"${price:.2f}"
|
||||
change_str = f"{change:+.2f}"
|
||||
change_pct_str = f"{change_pct:+.2f}%"
|
||||
|
||||
result += f"| {display_name} | {price_str} | {change_str} | {change_pct_str} |\n"
|
||||
success_count += 1
|
||||
|
||||
except (FinnhubError, RateLimitError, ThirdPartyError,
|
||||
ThirdPartyTimeoutError, ThirdPartyParseError) as exc:
|
||||
result += f"| {display_name} | Error | - | {exc!s:.40} |\n"
|
||||
|
||||
if success_count == 0:
|
||||
raise FinnhubError("All market index fetches failed.")
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def get_sector_performance_finnhub() -> str:
|
||||
"""Get daily change % for the 11 GICS sectors via SPDR ETF quotes.
|
||||
|
||||
Fetches one /quote call per SPDR ETF (XLK, XLV, XLF, XLE, XLI, XLY,
|
||||
XLP, XLRE, XLU, XLB, XLC) and presents daily performance.
|
||||
|
||||
Returns:
|
||||
Markdown table with Sector, ETF, Price, Day Change %.
|
||||
|
||||
Raises:
|
||||
FinnhubError: When all sector fetches fail.
|
||||
"""
|
||||
header = (
|
||||
f"# Sector Performance (Finnhub — SPDR ETF Proxies)\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
result = header
|
||||
result += "| Sector | ETF | Price | Day Change % |\n"
|
||||
result += "|--------|-----|-------|---------------|\n"
|
||||
|
||||
success_count = 0
|
||||
last_error: Exception | None = None
|
||||
|
||||
for sector_name, etf in _SECTOR_ETFS.items():
|
||||
try:
|
||||
quote = _fetch_quote(etf)
|
||||
price_str = f"${quote['current_price']:.2f}"
|
||||
change_pct_str = f"{quote['change_percent']:+.2f}%"
|
||||
result += f"| {sector_name} | {etf} | {price_str} | {change_pct_str} |\n"
|
||||
success_count += 1
|
||||
|
||||
except (FinnhubError, RateLimitError, ThirdPartyError,
|
||||
ThirdPartyTimeoutError, ThirdPartyParseError) as exc:
|
||||
last_error = exc
|
||||
result += f"| {sector_name} | {etf} | Error | {exc!s:.30} |\n"
|
||||
|
||||
# If ALL sectors failed, raise so route_to_vendor can fall back
|
||||
if success_count == 0 and last_error is not None:
|
||||
raise FinnhubError(
|
||||
f"All {len(_SECTOR_ETFS)} sector queries failed. Last error: {last_error}"
|
||||
)
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def get_topic_news_finnhub(
|
||||
topic: Annotated[str, "News topic (e.g., 'market', 'crypto', 'mergers')"],
|
||||
limit: Annotated[int, "Maximum number of articles to return"] = 20,
|
||||
) -> str:
|
||||
"""Fetch topic-based market news via Finnhub /news.
|
||||
|
||||
Maps the ``topic`` string to one of the four Finnhub news categories
|
||||
(general, forex, crypto, merger) and returns a formatted markdown list of
|
||||
recent articles.
|
||||
|
||||
Args:
|
||||
topic: A topic string. Known topics are mapped to Finnhub categories;
|
||||
unknown topics default to ``'general'``.
|
||||
limit: Maximum number of articles to return (default 20).
|
||||
|
||||
Returns:
|
||||
Markdown-formatted news feed.
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API-level errors.
|
||||
"""
|
||||
finnhub_category = _TOPIC_TO_CATEGORY.get(topic.lower(), "general")
|
||||
|
||||
articles: list[dict] = _rate_limited_request("news", {"category": finnhub_category})
|
||||
|
||||
header = (
|
||||
f"# News for Topic: {topic} (Finnhub — category: {finnhub_category})\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
result = header
|
||||
|
||||
if not articles:
|
||||
result += f"_No articles found for topic '{topic}'._\n"
|
||||
return result
|
||||
|
||||
for article in articles[:limit]:
|
||||
headline = article.get("headline", "No headline")
|
||||
source = article.get("source", "Unknown")
|
||||
summary = article.get("summary", "")
|
||||
url = article.get("url", "")
|
||||
datetime_unix: int = article.get("datetime", 0)
|
||||
|
||||
# Format publish timestamp
|
||||
if datetime_unix:
|
||||
try:
|
||||
published = datetime.fromtimestamp(int(datetime_unix)).strftime("%Y-%m-%d %H:%M")
|
||||
except (OSError, OverflowError, ValueError):
|
||||
published = str(datetime_unix)
|
||||
else:
|
||||
published = ""
|
||||
|
||||
result += f"### {headline}\n"
|
||||
meta = f"**Source:** {source}"
|
||||
if published:
|
||||
meta += f" | **Published:** {published}"
|
||||
result += meta + "\n"
|
||||
if summary:
|
||||
result += f"{summary}\n"
|
||||
if url:
|
||||
result += f"**Link:** {url}\n"
|
||||
result += "\n"
|
||||
|
||||
return result
|
||||
|
||||
|
||||
def get_earnings_calendar_finnhub(from_date: str, to_date: str) -> str:
|
||||
"""Fetch upcoming earnings releases via Finnhub /calendar/earnings.
|
||||
|
||||
Returns a formatted markdown table of companies reporting earnings between
|
||||
from_date and to_date, including EPS estimates and prior-year actuals.
|
||||
Unique capability not available in Alpha Vantage at any tier.
|
||||
|
||||
Args:
|
||||
from_date: Start date in YYYY-MM-DD format.
|
||||
to_date: End date in YYYY-MM-DD format.
|
||||
|
||||
Returns:
|
||||
Markdown-formatted table with Symbol, Date, EPS Estimate, EPS Prior.
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API-level errors or empty response.
|
||||
"""
|
||||
data = _rate_limited_request("calendar/earnings", {"from": from_date, "to": to_date})
|
||||
earnings_list = data.get("earningsCalendar", [])
|
||||
header = (
|
||||
f"# Earnings Calendar: {from_date} to {to_date} — Finnhub\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
if not earnings_list:
|
||||
return header + "_No earnings events found in this date range._\n"
|
||||
|
||||
lines = [
|
||||
header,
|
||||
"| Symbol | Company | Date | EPS Estimate | EPS Prior | Revenue Estimate |",
|
||||
"|--------|---------|------|--------------|-----------|-----------------|",
|
||||
]
|
||||
for item in sorted(earnings_list, key=lambda x: x.get("date", "")):
|
||||
symbol = item.get("symbol", "N/A")
|
||||
company = item.get("company", "N/A")[:30]
|
||||
date = item.get("date", "N/A")
|
||||
eps_est = item.get("epsEstimate", None)
|
||||
eps_prior = item.get("epsPrior", None)
|
||||
rev_est = item.get("revenueEstimate", None)
|
||||
eps_est_s = f"${eps_est:.2f}" if eps_est is not None else "N/A"
|
||||
eps_prior_s = f"${eps_prior:.2f}" if eps_prior is not None else "N/A"
|
||||
rev_est_s = f"${float(rev_est)/1e9:.2f}B" if rev_est is not None else "N/A"
|
||||
lines.append(f"| {symbol} | {company} | {date} | {eps_est_s} | {eps_prior_s} | {rev_est_s} |")
|
||||
return "\n".join(lines)
|
||||
|
||||
|
||||
def get_economic_calendar_finnhub(from_date: str, to_date: str) -> str:
|
||||
"""Fetch macro economic events via Finnhub /calendar/economic.
|
||||
|
||||
Returns FOMC meetings, CPI releases, NFP (Non-Farm Payroll), PPI,
|
||||
GDP announcements, and other market-moving macro events. Unique
|
||||
capability not available in Alpha Vantage at any tier.
|
||||
|
||||
Args:
|
||||
from_date: Start date in YYYY-MM-DD format.
|
||||
to_date: End date in YYYY-MM-DD format.
|
||||
|
||||
Returns:
|
||||
Markdown-formatted table with Date, Event, Country, Impact, Estimate, Prior.
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API-level errors or empty response.
|
||||
"""
|
||||
data = _rate_limited_request("calendar/economic", {"from": from_date, "to": to_date})
|
||||
events = data.get("economicCalendar", [])
|
||||
header = (
|
||||
f"# Economic Calendar: {from_date} to {to_date} — Finnhub\n"
|
||||
f"# Data retrieved on: {_now_str()}\n\n"
|
||||
)
|
||||
if not events:
|
||||
return header + "_No economic events found in this date range._\n"
|
||||
|
||||
lines = [
|
||||
header,
|
||||
"| Date | Time | Event | Country | Impact | Estimate | Prior |",
|
||||
"|------|------|-------|---------|--------|----------|-------|",
|
||||
]
|
||||
for ev in sorted(events, key=lambda x: (x.get("time", ""), x.get("event", ""))):
|
||||
date = ev.get("time", "N/A")[:10] if ev.get("time") else "N/A"
|
||||
time_str = (
|
||||
ev.get("time", "N/A")[11:16]
|
||||
if ev.get("time") and len(ev.get("time", "")) > 10
|
||||
else "N/A"
|
||||
)
|
||||
event = ev.get("event", "N/A")[:40]
|
||||
country = ev.get("country", "N/A")
|
||||
impact = ev.get("impact", "N/A")
|
||||
estimate = str(ev.get("estimate", "N/A"))
|
||||
prior = str(ev.get("prev", "N/A"))
|
||||
lines.append(f"| {date} | {time_str} | {event} | {country} | {impact} | {estimate} | {prior} |")
|
||||
return "\n".join(lines)
|
||||
|
|
@ -0,0 +1,143 @@
|
|||
"""Finnhub stock price data functions.
|
||||
|
||||
Provides OHLCV candle data and real-time quotes using the Finnhub REST API.
|
||||
Output formats mirror the Alpha Vantage equivalents so LLM agents receive
|
||||
consistent data regardless of the active vendor.
|
||||
"""
|
||||
|
||||
from datetime import datetime
|
||||
|
||||
import pandas as pd
|
||||
|
||||
from .finnhub_common import (
|
||||
FinnhubError,
|
||||
ThirdPartyParseError,
|
||||
_make_api_request,
|
||||
_now_str,
|
||||
_to_unix_timestamp,
|
||||
)
|
||||
|
||||
|
||||
# Finnhub resolution codes for the /stock/candle endpoint
|
||||
_RESOLUTION_DAILY = "D"
|
||||
|
||||
|
||||
def get_stock_candles(symbol: str, start_date: str, end_date: str) -> str:
|
||||
"""Fetch daily OHLCV data for a symbol via Finnhub /stock/candle.
|
||||
|
||||
Returns a CSV-formatted string with columns matching the Alpha Vantage
|
||||
TIME_SERIES_DAILY_ADJUSTED output (Date, Open, High, Low, Close, Volume)
|
||||
so that downstream agents see a consistent format regardless of vendor.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
start_date: Inclusive start date in YYYY-MM-DD format.
|
||||
end_date: Inclusive end date in YYYY-MM-DD format.
|
||||
|
||||
Returns:
|
||||
CSV string with header row: ``timestamp,open,high,low,close,volume``
|
||||
|
||||
Raises:
|
||||
FinnhubError: On API-level errors or when the symbol returns no data.
|
||||
ThirdPartyParseError: When the response cannot be interpreted.
|
||||
"""
|
||||
params = {
|
||||
"symbol": symbol,
|
||||
"resolution": _RESOLUTION_DAILY,
|
||||
"from": _to_unix_timestamp(start_date),
|
||||
"to": _to_unix_timestamp(end_date) + 86400, # include end date (end of day)
|
||||
}
|
||||
|
||||
data = _make_api_request("stock/candle", params)
|
||||
|
||||
status = data.get("s")
|
||||
if status == "no_data":
|
||||
raise FinnhubError(
|
||||
f"No candle data returned for symbol={symbol}, "
|
||||
f"start={start_date}, end={end_date}"
|
||||
)
|
||||
if status != "ok":
|
||||
raise FinnhubError(
|
||||
f"Unexpected candle response status '{status}' for symbol={symbol}"
|
||||
)
|
||||
|
||||
# Finnhub returns parallel lists: t (timestamps), o, h, l, c, v
|
||||
timestamps: list[int] = data.get("t", [])
|
||||
opens: list[float] = data.get("o", [])
|
||||
highs: list[float] = data.get("h", [])
|
||||
lows: list[float] = data.get("l", [])
|
||||
closes: list[float] = data.get("c", [])
|
||||
volumes: list[int] = data.get("v", [])
|
||||
|
||||
if not timestamps:
|
||||
raise FinnhubError(
|
||||
f"Empty candle data for symbol={symbol}, "
|
||||
f"start={start_date}, end={end_date}"
|
||||
)
|
||||
|
||||
rows: list[str] = ["timestamp,open,high,low,close,volume"]
|
||||
for ts, o, h, lo, c, v in zip(timestamps, opens, highs, lows, closes, volumes):
|
||||
date_str = datetime.fromtimestamp(ts).strftime("%Y-%m-%d")
|
||||
rows.append(f"{date_str},{o},{h},{lo},{c},{v}")
|
||||
|
||||
return "\n".join(rows)
|
||||
|
||||
|
||||
def get_quote(symbol: str) -> dict:
|
||||
"""Fetch the latest real-time quote for a symbol via Finnhub /quote.
|
||||
|
||||
Returns a normalised dict with human-readable keys so callers do not need
|
||||
to map Finnhub's single-letter field names.
|
||||
|
||||
Args:
|
||||
symbol: Equity ticker symbol (e.g. "AAPL").
|
||||
|
||||
Returns:
|
||||
Dict with keys:
|
||||
- ``symbol`` (str)
|
||||
- ``current_price`` (float)
|
||||
- ``change`` (float): Absolute change from previous close.
|
||||
- ``change_percent`` (float): Percentage change from previous close.
|
||||
- ``high`` (float): Day high.
|
||||
- ``low`` (float): Day low.
|
||||
- ``open`` (float): Day open.
|
||||
- ``prev_close`` (float): Previous close price.
|
||||
- ``timestamp`` (str): ISO datetime of the quote.
|
||||
|
||||
Raises:
|
||||
FinnhubError: When the API returns an error or the symbol is invalid.
|
||||
ThirdPartyParseError: When the response cannot be parsed.
|
||||
"""
|
||||
data = _make_api_request("quote", {"symbol": symbol})
|
||||
|
||||
current_price: float = data.get("c", 0.0)
|
||||
prev_close: float = data.get("pc", 0.0)
|
||||
|
||||
# Finnhub returns d (change) and dp (change percent) directly
|
||||
change: float = data.get("d", 0.0)
|
||||
change_percent: float = data.get("dp", 0.0)
|
||||
|
||||
# Validate that we received a real quote (current_price == 0 means unknown symbol)
|
||||
if current_price == 0 and prev_close == 0:
|
||||
raise FinnhubError(
|
||||
f"Quote returned all-zero values for symbol={symbol}. "
|
||||
"Symbol may be invalid or market data unavailable."
|
||||
)
|
||||
|
||||
timestamp_unix: int = data.get("t", 0)
|
||||
if timestamp_unix:
|
||||
timestamp_str = datetime.fromtimestamp(timestamp_unix).strftime("%Y-%m-%d %H:%M:%S")
|
||||
else:
|
||||
timestamp_str = _now_str()
|
||||
|
||||
return {
|
||||
"symbol": symbol,
|
||||
"current_price": current_price,
|
||||
"change": change,
|
||||
"change_percent": change_percent,
|
||||
"high": data.get("h", 0.0),
|
||||
"low": data.get("l", 0.0),
|
||||
"open": data.get("o", 0.0),
|
||||
"prev_close": prev_close,
|
||||
"timestamp": timestamp_str,
|
||||
}
|
||||
|
|
@ -37,6 +37,15 @@ from .alpha_vantage_scanner import (
|
|||
get_topic_news_alpha_vantage,
|
||||
)
|
||||
from .alpha_vantage_common import AlphaVantageError, AlphaVantageRateLimitError, RateLimitError
|
||||
from .finnhub_common import FinnhubError
|
||||
from .finnhub_news import get_insider_transactions as get_finnhub_insider_transactions
|
||||
from .finnhub_scanner import (
|
||||
get_market_indices_finnhub,
|
||||
get_sector_performance_finnhub,
|
||||
get_topic_news_finnhub,
|
||||
get_earnings_calendar_finnhub,
|
||||
get_economic_calendar_finnhub,
|
||||
)
|
||||
|
||||
# Configuration and routing logic
|
||||
from .config import get_config
|
||||
|
|
@ -82,12 +91,20 @@ TOOLS_CATEGORIES = {
|
|||
"get_industry_performance",
|
||||
"get_topic_news",
|
||||
]
|
||||
}
|
||||
},
|
||||
"calendar_data": {
|
||||
"description": "Earnings and economic event calendars",
|
||||
"tools": [
|
||||
"get_earnings_calendar",
|
||||
"get_economic_calendar",
|
||||
]
|
||||
},
|
||||
}
|
||||
|
||||
VENDOR_LIST = [
|
||||
"yfinance",
|
||||
"alpha_vantage",
|
||||
"finnhub",
|
||||
]
|
||||
|
||||
# Mapping of methods to their vendor-specific implementations
|
||||
|
|
@ -129,6 +146,7 @@ VENDOR_METHODS = {
|
|||
"alpha_vantage": get_alpha_vantage_global_news,
|
||||
},
|
||||
"get_insider_transactions": {
|
||||
"finnhub": get_finnhub_insider_transactions,
|
||||
"alpha_vantage": get_alpha_vantage_insider_transactions,
|
||||
"yfinance": get_yfinance_insider_transactions,
|
||||
},
|
||||
|
|
@ -138,10 +156,12 @@ VENDOR_METHODS = {
|
|||
"alpha_vantage": get_market_movers_alpha_vantage,
|
||||
},
|
||||
"get_market_indices": {
|
||||
"finnhub": get_market_indices_finnhub,
|
||||
"alpha_vantage": get_market_indices_alpha_vantage,
|
||||
"yfinance": get_market_indices_yfinance,
|
||||
},
|
||||
"get_sector_performance": {
|
||||
"finnhub": get_sector_performance_finnhub,
|
||||
"alpha_vantage": get_sector_performance_alpha_vantage,
|
||||
"yfinance": get_sector_performance_yfinance,
|
||||
},
|
||||
|
|
@ -150,9 +170,17 @@ VENDOR_METHODS = {
|
|||
"yfinance": get_industry_performance_yfinance,
|
||||
},
|
||||
"get_topic_news": {
|
||||
"finnhub": get_topic_news_finnhub,
|
||||
"alpha_vantage": get_topic_news_alpha_vantage,
|
||||
"yfinance": get_topic_news_yfinance,
|
||||
},
|
||||
# calendar_data — Finnhub only (unique capabilities)
|
||||
"get_earnings_calendar": {
|
||||
"finnhub": get_earnings_calendar_finnhub,
|
||||
},
|
||||
"get_economic_calendar": {
|
||||
"finnhub": get_economic_calendar_finnhub,
|
||||
},
|
||||
}
|
||||
|
||||
def get_category_for_method(method: str) -> str:
|
||||
|
|
@ -202,7 +230,7 @@ def route_to_vendor(method: str, *args, **kwargs):
|
|||
|
||||
try:
|
||||
return impl_func(*args, **kwargs)
|
||||
except (AlphaVantageError, ConnectionError, TimeoutError):
|
||||
continue # Any AV error or connection/timeout triggers fallback to next vendor
|
||||
except (AlphaVantageError, FinnhubError, ConnectionError, TimeoutError):
|
||||
continue # Any vendor error or connection/timeout triggers fallback to next vendor
|
||||
|
||||
raise RuntimeError(f"No available vendor for '{method}'")
|
||||
|
|
@ -78,9 +78,11 @@ DEFAULT_CONFIG = {
|
|||
"fundamental_data": _env("VENDOR_FUNDAMENTAL_DATA", "yfinance"),
|
||||
"news_data": _env("VENDOR_NEWS_DATA", "yfinance"),
|
||||
"scanner_data": _env("VENDOR_SCANNER_DATA", "yfinance"),
|
||||
"calendar_data": _env("VENDOR_CALENDAR_DATA", "finnhub"),
|
||||
},
|
||||
# Tool-level configuration (takes precedence over category-level)
|
||||
"tool_vendors": {
|
||||
# Example: "get_stock_data": "alpha_vantage", # Override category default
|
||||
# Finnhub free tier provides same data + MSPR aggregate bonus signal
|
||||
"get_insider_transactions": "finnhub",
|
||||
},
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue