""" Data catalog endpoint """ from datetime import datetime from typing import Dict, List from fastapi import APIRouter, Depends from sqlalchemy.ext.asyncio import AsyncSession from app.core.database import get_db from app.schemas.financial import DataCatalogResponse, DataCatalogItem router = APIRouter() def get_data_catalog() -> Dict[str, List[DataCatalogItem]]: """Get comprehensive data catalog""" catalog = { "Company Information": [ DataCatalogItem( field_name="ticker", description="Stock ticker symbol", data_type="string", unit=None, calculation=None, source="SEC EDGAR" ), DataCatalogItem( field_name="name", description="Company legal name", data_type="string", unit=None, calculation=None, source="SEC EDGAR" ), DataCatalogItem( field_name="cik", description="Central Index Key - SEC's unique identifier", data_type="string", unit=None, calculation=None, source="SEC EDGAR" ), DataCatalogItem( field_name="sector", description="Business sector classification", data_type="string", unit=None, calculation=None, source="SEC EDGAR / External" ), DataCatalogItem( field_name="industry", description="Industry classification", data_type="string", unit=None, calculation=None, source="SEC EDGAR / External" ) ], "Income Statement": [ DataCatalogItem( field_name="revenue", description="Total revenue/sales for the period", data_type="float", unit="USD", calculation=None, source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="gross_profit", description="Revenue minus cost of goods sold", data_type="float", unit="USD", calculation="Revenue - COGS", source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="operating_income", description="Gross profit minus operating expenses", data_type="float", unit="USD", calculation="Gross Profit - Operating Expenses", source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="net_income", description="Bottom line profit after all expenses and taxes", data_type="float", unit="USD", calculation="Operating Income - Interest - Taxes", source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="eps", description="Earnings per share - basic", data_type="float", unit="USD per share", calculation="Net Income / Shares Outstanding", source="SEC EDGAR 10-K/10-Q" ) ], "Balance Sheet": [ DataCatalogItem( field_name="total_assets", description="Total value of everything the company owns", data_type="float", unit="USD", calculation="Current Assets + Non-Current Assets", source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="total_equity", description="Shareholders' equity (Assets - Liabilities)", data_type="float", unit="USD", calculation="Total Assets - Total Liabilities", source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="total_debt", description="Long-term debt obligations", data_type="float", unit="USD", calculation=None, source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="cash", description="Cash and cash equivalents", data_type="float", unit="USD", calculation=None, source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="shares_outstanding", description="Number of shares currently held by shareholders", data_type="float", unit="shares", calculation=None, source="SEC EDGAR 10-K/10-Q" ) ], "Cash Flow Statement": [ DataCatalogItem( field_name="operating_cash_flow", description="Cash generated from core business operations", data_type="float", unit="USD", calculation="Net Income + Non-cash adjustments + Working Capital changes", source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="free_cash_flow", description="Cash available after capital expenditures", data_type="float", unit="USD", calculation="Operating Cash Flow - Capital Expenditures", source="SEC EDGAR 10-K/10-Q" ), DataCatalogItem( field_name="capex", description="Capital expenditures for property, plant, and equipment", data_type="float", unit="USD", calculation=None, source="SEC EDGAR 10-K/10-Q" ) ], "Valuation Ratios": [ DataCatalogItem( field_name="pe_ratio", description="Price-to-Earnings ratio (trailing)", data_type="float", unit="ratio", calculation="Stock Price / EPS", source="Calculated" ), DataCatalogItem( field_name="pb_ratio", description="Price-to-Book ratio", data_type="float", unit="ratio", calculation="Market Cap / Total Equity", source="Calculated" ), DataCatalogItem( field_name="ps_ratio", description="Price-to-Sales ratio", data_type="float", unit="ratio", calculation="Market Cap / Revenue", source="Calculated" ), DataCatalogItem( field_name="ev_ebitda", description="Enterprise Value to EBITDA ratio", data_type="float", unit="ratio", calculation="Enterprise Value / EBITDA", source="Calculated" ) ], "Profitability Metrics": [ DataCatalogItem( field_name="roe", description="Return on Equity", data_type="float", unit="percentage", calculation="(Net Income / Total Equity) × 100", source="Calculated" ), DataCatalogItem( field_name="roa", description="Return on Assets", data_type="float", unit="percentage", calculation="(Net Income / Total Assets) × 100", source="Calculated" ), DataCatalogItem( field_name="gross_margin", description="Gross profit margin", data_type="float", unit="percentage", calculation="(Gross Profit / Revenue) × 100", source="Calculated" ), DataCatalogItem( field_name="operating_margin", description="Operating profit margin", data_type="float", unit="percentage", calculation="(Operating Income / Revenue) × 100", source="Calculated" ), DataCatalogItem( field_name="net_margin", description="Net profit margin", data_type="float", unit="percentage", calculation="(Net Income / Revenue) × 100", source="Calculated" ) ], "Growth Metrics": [ DataCatalogItem( field_name="revenue_growth_yoy", description="Year-over-year revenue growth rate", data_type="float", unit="percentage", calculation="((Current Year Revenue - Previous Year Revenue) / Previous Year Revenue) × 100", source="Calculated" ), DataCatalogItem( field_name="revenue_growth_qoq", description="Quarter-over-quarter revenue growth rate", data_type="float", unit="percentage", calculation="((Current Quarter Revenue - Previous Quarter Revenue) / Previous Quarter Revenue) × 100", source="Calculated" ), DataCatalogItem( field_name="eps_growth_yoy", description="Year-over-year EPS growth rate", data_type="float", unit="percentage", calculation="((Current Year EPS - Previous Year EPS) / Previous Year EPS) × 100", source="Calculated" ) ], "Liquidity & Solvency": [ DataCatalogItem( field_name="debt_to_equity", description="Debt-to-Equity ratio", data_type="float", unit="ratio", calculation="Total Debt / Total Equity", source="Calculated" ), DataCatalogItem( field_name="debt_to_assets", description="Debt-to-Assets ratio", data_type="float", unit="ratio", calculation="Total Debt / Total Assets", source="Calculated" ), DataCatalogItem( field_name="current_ratio", description="Current assets to current liabilities ratio", data_type="float", unit="ratio", calculation="Current Assets / Current Liabilities", source="Calculated" ) ], "Efficiency Metrics": [ DataCatalogItem( field_name="asset_turnover", description="How efficiently company uses assets to generate revenue", data_type="float", unit="ratio", calculation="Revenue / Average Total Assets", source="Calculated" ), DataCatalogItem( field_name="ocf_margin", description="Operating cash flow margin", data_type="float", unit="percentage", calculation="(Operating Cash Flow / Revenue) × 100", source="Calculated" ), DataCatalogItem( field_name="fcf_margin", description="Free cash flow margin", data_type="float", unit="percentage", calculation="(Free Cash Flow / Revenue) × 100", source="Calculated" ) ], "Market Data (Future)": [ DataCatalogItem( field_name="market_cap", description="Market capitalization", data_type="float", unit="USD", calculation="Stock Price × Shares Outstanding", source="Calculated (requires price data)" ), DataCatalogItem( field_name="forward_pe", description="Forward P/E ratio based on estimated earnings", data_type="float", unit="ratio", calculation="Stock Price / Forward EPS Estimate", source="External data required" ), DataCatalogItem( field_name="peg_ratio", description="Price/Earnings to Growth ratio", data_type="float", unit="ratio", calculation="P/E Ratio / Earnings Growth Rate", source="External data required" ), DataCatalogItem( field_name="beta", description="Stock's volatility relative to market", data_type="float", unit="coefficient", calculation="Covariance(Stock Returns, Market Returns) / Variance(Market Returns)", source="External price data required" ) ] } return catalog @router.get( "/catalog", response_model=DataCatalogResponse, summary="Get data catalog", description=""" Get a comprehensive catalog of all available data fields. This endpoint returns: - All available financial metrics and their descriptions - Data types and units for each field - Calculation methods where applicable - Data sources for each field The catalog is organized by categories: - Company Information - Income Statement - Balance Sheet - Cash Flow Statement - Valuation Ratios - Profitability Metrics - Growth Metrics - Liquidity & Solvency - Efficiency Metrics - Market Data (Future) """ ) async def get_catalog(db: AsyncSession = Depends(get_db)): """Get comprehensive data catalog""" catalog = get_data_catalog() return DataCatalogResponse( categories=catalog, last_updated=datetime.utcnow() )