feat: OpenBB Investment Analysis API

REST API wrapping OpenBB SDK for stock data, sentiment analysis,
technical indicators, macro data, and rule-based portfolio analysis.

- Stock data via yfinance (quote, profile, metrics, financials, historical, news)
- News sentiment via Alpha Vantage (per-article, per-ticker scores)
- Analyst data via Finnhub (recommendations, insider trades, upgrades)
- Macro data via FRED (Fed rate, CPI, GDP, unemployment, treasury yields)
- Technical indicators via openbb-technical (RSI, MACD, SMA, EMA, Bollinger)
- Rule-based portfolio analysis engine (BUY_MORE/HOLD/SELL)
- Stock discovery (gainers, losers, active, undervalued, growth)
- 102 tests, all passing

routes_sentiment.py

@@ -0,0 +1,138 @@
+"""Routes for sentiment, insider trades, and analyst data (Finnhub + Alpha Vantage)."""
+
+import asyncio
+import functools
+import logging
+from collections.abc import Awaitable, Callable
+from typing import ParamSpec, TypeVar
+
+from fastapi import APIRouter, HTTPException, Path, Query
+
+from models import SYMBOL_PATTERN, ApiResponse
+import alphavantage_service
+import finnhub_service
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v1")
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def _validate_symbol(symbol: str) -> str:
+    if not SYMBOL_PATTERN.match(symbol):
+        raise HTTPException(status_code=400, detail="Invalid symbol format")
+    return symbol.upper()
+
+
+def _safe(fn: Callable[P, Awaitable[R]]) -> Callable[P, Awaitable[R]]:
+    @functools.wraps(fn)
+    async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        try:
+            return await fn(*args, **kwargs)
+        except HTTPException:
+            raise
+        except Exception:
+            logger.exception("Upstream data error")
+            raise HTTPException(
+                status_code=502,
+                detail="Data provider error. Check server logs.",
+            )
+    return wrapper  # type: ignore[return-value]
+
+
+# --- Sentiment & News ---
+
+
+@router.get("/stock/{symbol}/sentiment", response_model=ApiResponse)
+@_safe
+async def stock_sentiment(symbol: str = Path(..., min_length=1, max_length=20)):
+    """Get aggregated sentiment: Alpha Vantage news sentiment + Finnhub analyst data."""
+    symbol = _validate_symbol(symbol)
+    finnhub_data, av_data = await asyncio.gather(
+        finnhub_service.get_sentiment_summary(symbol),
+        alphavantage_service.get_news_sentiment(symbol, limit=20),
+        return_exceptions=True,
+    )
+    if isinstance(finnhub_data, BaseException):
+        logger.exception("Finnhub error", exc_info=finnhub_data)
+        finnhub_data = {}
+    if isinstance(av_data, BaseException):
+        logger.exception("Alpha Vantage error", exc_info=av_data)
+        av_data = {}
+
+    data = {**finnhub_data, "alpha_vantage_sentiment": av_data}
+    return ApiResponse(data=data)
+
+
+@router.get("/stock/{symbol}/news-sentiment", response_model=ApiResponse)
+@_safe
+async def stock_news_sentiment(
+    symbol: str = Path(..., min_length=1, max_length=20),
+    limit: int = Query(default=30, ge=1, le=200),
+):
+    """Get news articles with per-ticker sentiment scores (Alpha Vantage)."""
+    symbol = _validate_symbol(symbol)
+    data = await alphavantage_service.get_news_sentiment(symbol, limit=limit)
+    return ApiResponse(data=data)
+
+
+@router.get("/stock/{symbol}/insider-trades", response_model=ApiResponse)
+@_safe
+async def stock_insider_trades(symbol: str = Path(..., min_length=1, max_length=20)):
+    """Get insider transactions (CEO/CFO buys and sells)."""
+    symbol = _validate_symbol(symbol)
+    raw = await finnhub_service.get_insider_transactions(symbol)
+    trades = [
+        {
+            "name": t.get("name"),
+            "shares": t.get("share"),
+            "change": t.get("change"),
+            "transaction_date": t.get("transactionDate"),
+            "transaction_code": t.get("transactionCode"),
+            "transaction_price": t.get("transactionPrice"),
+            "filing_date": t.get("filingDate"),
+        }
+        for t in raw[:20]
+    ]
+    return ApiResponse(data=trades)
+
+
+@router.get("/stock/{symbol}/recommendations", response_model=ApiResponse)
+@_safe
+async def stock_recommendations(symbol: str = Path(..., min_length=1, max_length=20)):
+    """Get analyst recommendation trends (monthly buy/hold/sell counts)."""
+    symbol = _validate_symbol(symbol)
+    raw = await finnhub_service.get_recommendation_trends(symbol)
+    recs = [
+        {
+            "period": r.get("period"),
+            "strong_buy": r.get("strongBuy"),
+            "buy": r.get("buy"),
+            "hold": r.get("hold"),
+            "sell": r.get("sell"),
+            "strong_sell": r.get("strongSell"),
+        }
+        for r in raw[:12]
+    ]
+    return ApiResponse(data=recs)
+
+
+@router.get("/stock/{symbol}/upgrades", response_model=ApiResponse)
+@_safe
+async def stock_upgrades(symbol: str = Path(..., min_length=1, max_length=20)):
+    """Get recent analyst upgrades and downgrades."""
+    symbol = _validate_symbol(symbol)
+    raw = await finnhub_service.get_upgrade_downgrade(symbol)
+    upgrades = [
+        {
+            "company": u.get("company"),
+            "action": u.get("action"),
+            "from_grade": u.get("fromGrade"),
+            "to_grade": u.get("toGrade"),
+            "date": u.get("gradeTime"),
+        }
+        for u in raw[:20]
+    ]
+    return ApiResponse(data=upgrades)