alphadataforge 0.1.0__py3-none-any.whl

alphadataforge/providers/fmp_fetcher.py

@@ -0,0 +1,183 @@
+import pandas as pd
+import requests
+from typing import Optional, List, Dict, Any
+
+from ..core.base_fetcher import BaseDataFetcher
+from ..core.exceptions import ProviderConfigurationError
+from ..config.settings import config
+from ..config.endpoints import Endpoints
+from ..utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+class FMPFetcher(BaseDataFetcher):
+    """
+    Data fetcher for Financial Modeling Prep (FMP).
+    Handles EOD prices, splits, and dividends.
+    """
+    
+    def __init__(self, api_key: Optional[str] = None):
+        super().__init__()
+        self.api_key = api_key or config.FMP_API_KEY
+        self.base_url = Endpoints.FMP.BASE_URL
+
+    def _require_api_key(self) -> None:
+        if not self.api_key:
+            raise ProviderConfigurationError(
+                "FMP_API_KEY is not set. Please set it in your .env file or environment variables."
+            )
+
+    def _make_request(self, endpoint: str, **params) -> dict:
+        """
+        Executes HTTP GET request to FMP API.
+        """
+        self._require_api_key()
+        params['apikey'] = self.api_key
+        url = f"{self.base_url}/{endpoint}"
+        return self._make_http_request(url, params=params)
+
+    def fetch_single(
+        self, 
+        symbol: str, 
+        start_date: Optional[str] = None, 
+        end_date: Optional[str] = None, 
+        outputsize: str = "full", 
+        adjusted: bool = False,
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch EOD price data for a single symbol from FMP.
+        FMP provides 'adjClose' by default, but if `adjusted=True`, this will fully calculate 
+        Adj Open, Adj High, Adj Low, and Adj Volume via the finance_math utility.
+        """
+        logger.info("Fetching price for %s (adjusted=%s) via FMP...", symbol, adjusted)
+        self._validate_inputs(symbol, start_date, end_date)
+        
+        # --- Step 1: Fetch raw price data ---
+        # Note: We request 'from' and 'to' in the API to save bandwidth
+        params = {'symbol': symbol}
+        if start_date:
+            params['from'] = start_date
+        if end_date:
+            params['to'] = end_date
+
+        # Use the appropriate endpoint based on 'adjusted' flag
+        # 'dividend-adjusted' = Fully adjusted (splits + dividends)
+        # 'price_adjusted' = Fully adjusted (splits + dividends)
+        # 'price_raw' = Standard price (split-adjusted only)
+        if adjusted:
+            endpoint = Endpoints.FMP.PATHS["price_adjusted"]
+        else:
+            endpoint = Endpoints.FMP.PATHS["price_raw"]
+        
+        raw_json = self._make_request(endpoint, **params)
+            
+        historical = raw_json if isinstance(raw_json, list) else raw_json.get("historical", [])
+        if not historical:
+            logger.warning("No historical data found for %s in FMP.", symbol)
+            return pd.DataFrame()
+            
+        df = pd.DataFrame(historical)
+        if 'date' in df.columns:
+            df.index = pd.to_datetime(df['date'])
+            df = df.drop(columns=['date'])
+
+        # Since FMP's dividend-adjusted endpoint already provides adjusted OHLC, 
+        # we don't need to manually fetch splits/dividends and calculate it.
+        # We just normalize the columns and return.
+        
+        return self._normalize_ohlcv(df)
+
+    def fetch_multiple(
+        self,
+        symbols: List[str],
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        outputsize: str = "full",
+        adjusted: bool = False,
+        **kwargs
+    ) -> Dict[str, pd.DataFrame]:
+        """
+        Fetch price data for multiple symbols.
+        Passes outputsize and adjusted down to fetch_single.
+        """
+        return super().fetch_multiple(
+            symbols,
+            adjusted=adjusted,
+            **kwargs
+        )
+
+    def fetch_info(self, symbol: str) -> dict:
+        """
+        Fetch company profile (fundamentals like sector, industry, mktCap).
+        """
+        logger.info("Fetching info for %s via FMP...", symbol)
+        self._validate_inputs(symbol)
+        
+        # FMP profile API
+        # using the v3 endpoint, but our base url is stable, wait, we need to adjust the base_url or override it
+        # self.base_url is "https://financialmodelingprep.com/stable" but profile is usually "https://financialmodelingprep.com/api/v3/profile/AAPL"
+        # Let's override the url completely here.
+        url = f"{self.base_url}/{Endpoints.FMP.PATHS['profile']}"
+        params = {'apikey': self.api_key, 'symbol': symbol}
+        
+        try:
+            
+            data = self._make_http_request(url, params=params)
+            if isinstance(data, list) and len(data) > 0:
+                return data[0]
+            return {}
+        except requests.exceptions.HTTPError as e:
+            if e.response is not None and e.response.status_code == 403:
+                raise RuntimeError("FMP Fundamentals data (like company profile) requires a premium API key.") from e
+            raise
+
+    def fetch_financials(self, symbol: str, statement: str = "income", period: str = "annual") -> pd.DataFrame:
+        """
+        Fetch financial statements from FMP.
+        """
+        logger.info("Fetching %s statement for %s (%s) via FMP...", statement, symbol, period)
+        self._validate_inputs(symbol)
+        
+        # FMP expects period as 'annual' (default/omit) or 'quarter'
+        fmp_period = "quarter" if period.lower() == "quarterly" else "annual"
+        
+        endpoint_map = Endpoints.FMP.PATHS
+        valid_statements = {"income", "balance", "cashflow", "shares_float"}
+        
+        if statement not in valid_statements:
+            raise ValueError(f"Unknown statement type: '{statement}'. Choose 'income', 'balance', 'cashflow', or 'shares_float'.")
+            
+        if statement == "shares_float":
+            url = f"{self.base_url}/{Endpoints.FMP.PATHS['shares_float']}"
+            params = {'apikey': self.api_key, 'symbol': symbol}
+        else:
+            url = f"{self.base_url}/{endpoint_map[statement]}"
+            params = {'apikey': self.api_key, 'symbol': symbol, 'limit': 5} # limit 5 for free tier
+            if fmp_period == "quarter":
+                params['period'] = "quarter"
+
+            
+        try:
+            data = self._make_http_request(url, params=params)
+        except requests.exceptions.HTTPError as e:
+            if e.response is not None and e.response.status_code == 403:
+                raise RuntimeError(f"FMP Financial Statements data requires a premium API key.") from e
+            raise
+            
+        if not data or not isinstance(data, list):
+            logger.warning("No financial data found for %s in FMP.", symbol)
+            return pd.DataFrame()
+            
+        df = pd.DataFrame(data)
+        
+        # FMP returns dates in the 'date' column.
+        if 'date' in df.columns:
+            df.index = pd.to_datetime(df['date'])
+            df = df.drop(columns=['date'])
+            
+        # Normalize and return
+        if statement == "shares_float":
+            # Just return the DataFrame directly for shares_float
+            return df
+        return self._normalize_financials(df)

alphadataforge/providers/hybrid_fetcher.py

@@ -0,0 +1,87 @@
+import pandas as pd
+from typing import Optional, List, Dict
+
+from ..core.base_fetcher import BaseDataFetcher
+from .alphavantage_fetcher import AlphaVantageFetcher
+from .tiingo_fetcher import TiingoFetcher
+from ..utils.finance_math import calculate_adjusted_prices
+from ..utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+class HybridFetcher(BaseDataFetcher):
+    """
+    Hybrid Data Fetcher that combines multiple providers for optimal rate limit usage.
+    Primary use case:
+    - Fetches long-history raw prices from Alpha Vantage.
+    - Fetches dividend and split events from Tiingo.
+    - Computes full adjusted prices locally.
+    Saves 2 API calls per symbol on Alpha Vantage compared to using AV's native adjusted fetch.
+    """
+
+    def __init__(self):
+        super().__init__()
+        self.av_fetcher = AlphaVantageFetcher()
+        self.tiingo_fetcher = TiingoFetcher()
+
+    def fetch_single(
+        self,
+        symbol: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch hybrid data for a single symbol.
+        """
+        logger.info("Fetching hybrid price data for %s (AlphaVantage + Tiingo)...", symbol)
+        
+        # Pop adjusted if present to avoid multiple values conflict
+        kwargs.pop("adjusted", None)
+        
+        # 1. Fetch raw prices from Alpha Vantage
+        # Force adjusted=False to save API calls, we just need raw OHLCV
+        df_raw = self.av_fetcher.fetch_single(
+            symbol=symbol,
+            start_date=start_date,
+            end_date=end_date,
+            adjusted=False,
+            **kwargs
+        )
+        
+        if df_raw.empty:
+            return df_raw
+            
+        # 2. Fetch splits and dividends from Tiingo
+        try:
+            df_tiingo = self.tiingo_fetcher.fetch_single(
+                symbol=symbol,
+                start_date=start_date,
+                end_date=end_date,
+                frequency="daily"
+            )
+        except Exception as e:
+            logger.warning("Failed to fetch Tiingo data for %s: %s. Returning raw AV data.", symbol, e)
+            return df_raw
+            
+        if df_tiingo.empty:
+            # No Tiingo data, return raw AV data
+            return df_raw
+            
+        # Extract dividends and splits
+        dividends_df = df_tiingo[['divCash']].rename(columns={'divCash': 'Dividend'})
+        dividends_df = dividends_df[dividends_df['Dividend'] > 0]
+        
+        splits_df = df_tiingo[['splitFactor']].rename(columns={'splitFactor': 'SplitFactor'})
+        splits_df = splits_df[splits_df['SplitFactor'] != 1.0]
+        
+        # 3. Calculate adjusted prices using our math utility
+        df_adj = calculate_adjusted_prices(df_raw, dividends_df, splits_df)
+        
+        return df_adj
+
+    def fetch_info(self, symbol: str, **kwargs) -> dict:
+        raise NotImplementedError("HybridFetcher only supports price fetching.")
+
+    def fetch_financials(self, symbol: str, statement: str = "income", **kwargs) -> pd.DataFrame:
+        raise NotImplementedError("HybridFetcher only supports price fetching.")

alphadataforge/providers/stockfit_fetcher.py

@@ -0,0 +1,265 @@
+import pandas as pd
+from typing import Optional, List, Dict, Any, Union
+import logging
+
+from ..core.base_fetcher import BaseDataFetcher
+from ..core.exceptions import ProviderConfigurationError
+from ..config.settings import config
+from ..config.endpoints import Endpoints
+from ..utils.logger import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class StockFitFetcher(BaseDataFetcher):
+    """
+    Data fetcher for StockFit API (https://stockfit.io).
+    Extracts structured, point-in-time intelligence directly from official SEC EDGAR XBRL filings.
+    
+    Provides:
+      - 15-20+ years of normalized financial statements (income, balance, cashflow)
+      - SEC filing traceability (10-K, 10-Q accession numbers)
+      - Financial health scores (Piotroski F-score, etc.)
+      - Company profiles and price history
+    """
+
+    def __init__(self, api_key: Optional[str] = None):
+        super().__init__()
+        self.api_key = api_key or config.STOCKFIT_API_KEY
+        self.base_url = Endpoints.StockFit.BASE_URL
+
+    def _require_api_key(self) -> None:
+        if not self.api_key:
+            raise ProviderConfigurationError(
+                "STOCKFIT_API_KEY is not set. Please set it in your .env file or pass it to StockFitFetcher(api_key=...)."
+            )
+
+    def _make_request(self, endpoint_path: str, **params) -> Any:
+        """
+        Executes HTTP GET request to StockFit API with Bearer token authentication.
+        """
+        self._require_api_key()
+        url = f"{self.base_url}/{endpoint_path}"
+        headers = {
+            "Authorization": f"Bearer {self.api_key}",
+            "Accept": "application/json"
+        }
+        # Filter out None params
+        filtered_params = {k: v for k, v in params.items() if v is not None}
+        return self._make_http_request(url, params=filtered_params, headers=headers)
+
+    # ------------------------------------------------------------------
+    # Price
+    # ------------------------------------------------------------------
+    def fetch_single(
+        self,
+        symbol: str,
+        start_date: Optional[str] = None,
+        end_date: Optional[str] = None,
+        adjusted: bool = True,
+        resolution: str = "1d",
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch historical close prices from StockFit.
+        
+        Args:
+            symbol: Ticker symbol (e.g. 'AAPL').
+            start_date: 'YYYY-MM-DD' lower bound.
+            end_date: 'YYYY-MM-DD' upper bound.
+            adjusted: Split/dividend adjusted close (default True).
+            resolution: Bar resolution ('1d', '1wk', '1mo').
+        """
+        logger.info("Fetching price history for %s via StockFit...", symbol)
+        self._validate_inputs(symbol, start_date, end_date)
+
+        params = {
+            "symbol": symbol,
+            "resolution": resolution,
+            "adjusted": adjusted
+        }
+        if start_date:
+            params["from"] = start_date
+        if end_date:
+            params["to"] = end_date
+
+        try:
+            data = self._make_request(Endpoints.StockFit.PATHS["price_history"], **params)
+        except Exception as e:
+            logger.error("Failed to fetch price history for %s via StockFit: %s", symbol, e)
+            return pd.DataFrame()
+
+        bars = data.get("data", [])
+        if not bars:
+            return pd.DataFrame()
+
+        records = []
+        for item in bars:
+            if isinstance(item, (list, tuple)) and len(item) >= 2:
+                ts_ms, val = item[0], item[1]
+                records.append({
+                    "Date": pd.to_datetime(ts_ms, unit="ms"),
+                    "Close": val,
+                    "Adj Close": val if adjusted else None
+                })
+
+        if not records:
+            return pd.DataFrame()
+
+        df = pd.DataFrame(records).set_index("Date")
+        df.index = df.index.tz_localize(None) if df.index.tz is not None else df.index
+        df.index.name = "Date"
+
+        # Backfill standard columns if needed
+        return self._normalize_ohlcv(df)
+
+    # ------------------------------------------------------------------
+    # Company Profile / Info
+    # ------------------------------------------------------------------
+    def fetch_info(self, symbol: str) -> Dict[str, Any]:
+        """
+        Fetch company profile and basic information from StockFit.
+        """
+        logger.info("Fetching company details for %s via StockFit...", symbol)
+        self._validate_inputs(symbol)
+
+        try:
+            data = self._make_request(Endpoints.StockFit.PATHS["details"], symbol=symbol)
+            if isinstance(data, dict):
+                return data
+            return {}
+        except Exception as e:
+            logger.error("Failed to fetch company details for %s via StockFit: %s", symbol, e)
+            return {}
+
+    # ------------------------------------------------------------------
+    # Financial Statements
+    # ------------------------------------------------------------------
+    def fetch_financials(
+        self,
+        symbol: str,
+        statement: str = "income",
+        period: str = "annual",
+        limit: int = 100,
+        **kwargs
+    ) -> pd.DataFrame:
+        """
+        Fetch historical SEC-reported financial statements from StockFit.
+        
+        Args:
+            symbol: Ticker symbol (e.g., 'AAPL').
+            statement: "income", "balance", "cashflow", "growth", "scores", or "key_metrics".
+            period: "annual" (default) or "quarterly".
+            limit: Number of historical periods to retrieve (default 100, up to 20 years).
+        
+        Returns:
+            DataFrame with normalized financial metrics and DatetimeIndex.
+        """
+        logger.info("Fetching %s statement for %s (%s) via StockFit...", statement, symbol, period)
+        self._validate_inputs(symbol)
+
+        statement_clean = statement.lower().replace("-", "").replace("_", "")
+        period_clean = "quarterly" if period.lower() in ("quarterly", "quarter", "q") else "annual"
+
+        valid_statements = {
+            "income": Endpoints.StockFit.PATHS["income"],
+            "balance": Endpoints.StockFit.PATHS["balance"],
+            "cashflow": Endpoints.StockFit.PATHS["cashflow"],
+            "growth": Endpoints.StockFit.PATHS["growth"],
+            "scores": Endpoints.StockFit.PATHS["scores"],
+            "keymetrics": Endpoints.StockFit.PATHS["key_metrics"],
+            "asreported": Endpoints.StockFit.PATHS["as_reported"],
+        }
+
+        if statement_clean not in valid_statements:
+            raise ValueError(
+                f"Unknown statement type: '{statement}'. Choose from {list(valid_statements.keys())}."
+            )
+
+        endpoint_path = valid_statements[statement_clean]
+        params = {"symbol": symbol}
+
+        # Statement and growth take period and limit
+        if statement_clean in ("income", "balance", "cashflow", "growth", "asreported"):
+            params["period"] = period_clean
+            params["limit"] = limit
+            if "splitAdjust" in kwargs:
+                params["splitAdjust"] = kwargs["splitAdjust"]
+
+        try:
+            data = self._make_request(endpoint_path, **params)
+        except Exception as e:
+            logger.error("Failed to fetch %s for %s via StockFit: %s", statement, symbol, e)
+            return pd.DataFrame()
+
+        if not data:
+            logger.warning("No %s financial data returned for %s in StockFit.", statement, symbol)
+            return pd.DataFrame()
+
+        # Handle score endpoints which return a single dict
+        if statement_clean == "scores" and isinstance(data, dict):
+            row = {k: v for k, v in data.items() if not isinstance(v, dict)}
+            if "piotroskiDetails" in data and isinstance(data["piotroskiDetails"], dict):
+                for k, v in data["piotroskiDetails"].items():
+                    row[f"piotroski_{k}"] = v
+            df = pd.DataFrame([row])
+            if "period" in df.columns:
+                df.index = pd.to_datetime(df["period"])
+                df = df.drop(columns=["period"])
+            df.index.name = "Date"
+            return df
+
+        # Handle growth or keymetrics
+        if statement_clean == "growth" and isinstance(data, list):
+            df = pd.DataFrame(data)
+            if not df.empty and "period" in df.columns:
+                df.index = pd.to_datetime(df["period"])
+                df = df.drop(columns=["period"])
+            df.index.name = "Date"
+            return df
+
+        # Standard financial statements: unpack 'facts' object
+        if not isinstance(data, list):
+            return pd.DataFrame()
+
+        rows = []
+        for item in data:
+            if not isinstance(item, dict):
+                continue
+            facts = item.get("facts", {})
+            row = facts.copy() if isinstance(facts, dict) else {}
+            row["period"] = item.get("period")
+            if "fiscalYear" in item:
+                row["fiscalYear"] = item.get("fiscalYear")
+            if "fiscalPeriod" in item:
+                row["fiscalPeriod"] = item.get("fiscalPeriod")
+            if "dateFiled" in item:
+                row["dateFiled"] = item.get("dateFiled")
+            rows.append(row)
+
+        if not rows:
+            return pd.DataFrame()
+
+        df = pd.DataFrame(rows)
+        if "period" in df.columns:
+            df.index = pd.to_datetime(df["period"])
+            df = df.drop(columns=["period"])
+        df.index.name = "Date"
+
+        # Apply standardized column normalization
+        return self._normalize_financials(df)
+
+    # ------------------------------------------------------------------
+    # Additional Specialized Intelligence
+    # ------------------------------------------------------------------
+    def fetch_scores(self, symbol: str) -> Dict[str, Any]:
+        """
+        Fetch Piotroski F-score and financial health metrics.
+        """
+        return self._make_request(Endpoints.StockFit.PATHS["scores"], symbol=symbol)
+
+    def fetch_growth(self, symbol: str, period: str = "annual") -> pd.DataFrame:
+        """
+        Fetch historical growth rates (revenue, gross profit, net income, EPS).
+        """
+        return self.fetch_financials(symbol, statement="growth", period=period)