timber-common 0.3.2__tar.gz → 0.3.4__tar.gz

{timber_common-0.3.2 → timber_common-0.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: timber-common
-Version: 0.3.2
+Version: 0.3.4
 Summary: Configuration-driven persistence library with ml tools (finance related) config driven db model registration, llm model choice, automatic encryption, caching, vector search, and GDPR compliance for Python applications
 License: MIT
 License-File: LICENSE

timber_common-0.3.4/common/services/analytics/__init__.py

@@ -0,0 +1,186 @@
+# timber/common/services/analytics/__init__.py
+"""
+Financial Analytics Package
+
+Provides fundamental analysis capabilities that are ADDITIVE to data_processor.
+
+data_processor handles: Technical indicators, returns, risk metrics, portfolio metrics
+analytics handles: Fundamental ratios, growth metrics, valuation (from financial statements)
+
+Main entry points for task configs:
+- calculate_financial_ratios(income_stmt, balance_sheet, cash_flow)
+- calculate_growth_metrics(income_stmt, balance_sheet)  
+- calculate_valuation_metrics(income_stmt, balance_sheet, cash_flow, market_cap, ...)
+"""
+
+from .fundamental import (
+    # Individual ratio functions
+    calculate_profitability_ratios,
+    calculate_leverage_ratios,
+    calculate_liquidity_ratios,
+    calculate_efficiency_ratios,
+    calculate_cashflow_ratios,
+    # Main umbrella function
+    calculate_financial_ratios,
+)
+
+from .growth import (
+    calculate_revenue_growth,
+    calculate_earnings_growth,
+    calculate_margin_trends,
+    calculate_asset_growth,
+    # Main umbrella function
+    calculate_growth_metrics,
+)
+
+from .valuation import (
+    calculate_price_multiples,
+    calculate_ev_multiples,
+    calculate_cf_valuation,
+    calculate_peg_ratio,
+    # Main umbrella function
+    calculate_valuation_metrics,
+)
+
+
+# =============================================================================
+# Unified Analytics Service Class
+# =============================================================================
+
+class FundamentalAnalytics:
+    """
+    Unified fundamental analytics service.
+    
+    Provides methods that can be called via Timber adapter:
+        service: fundamental_analytics
+        method: calculate_financial_ratios
+    """
+    
+    # Fundamental Ratios
+    @staticmethod
+    def calculate_financial_ratios(income_stmt, balance_sheet, cash_flow=None, period_idx=0):
+        """Calculate all fundamental ratios from financial statements."""
+        return calculate_financial_ratios(income_stmt, balance_sheet, cash_flow, period_idx)
+    
+    @staticmethod
+    def calculate_profitability_ratios(income_stmt, balance_sheet, period_idx=0):
+        """Calculate profitability ratios."""
+        return calculate_profitability_ratios(income_stmt, balance_sheet, period_idx)
+    
+    @staticmethod
+    def calculate_leverage_ratios(balance_sheet, income_stmt=None, period_idx=0):
+        """Calculate leverage/solvency ratios."""
+        return calculate_leverage_ratios(balance_sheet, income_stmt, period_idx)
+    
+    @staticmethod
+    def calculate_liquidity_ratios(balance_sheet, period_idx=0):
+        """Calculate liquidity ratios."""
+        return calculate_liquidity_ratios(balance_sheet, period_idx)
+    
+    @staticmethod
+    def calculate_efficiency_ratios(income_stmt, balance_sheet, period_idx=0):
+        """Calculate efficiency ratios."""
+        return calculate_efficiency_ratios(income_stmt, balance_sheet, period_idx)
+    
+    @staticmethod
+    def calculate_cashflow_ratios(cash_flow, income_stmt=None, balance_sheet=None, period_idx=0):
+        """Calculate cash flow quality ratios."""
+        return calculate_cashflow_ratios(cash_flow, income_stmt, balance_sheet, period_idx)
+    
+    # Growth Metrics
+    @staticmethod
+    def calculate_growth_metrics(income_stmt, balance_sheet=None):
+        """Calculate all growth metrics."""
+        return calculate_growth_metrics(income_stmt, balance_sheet)
+    
+    @staticmethod
+    def calculate_revenue_growth(income_stmt):
+        """Calculate revenue growth metrics."""
+        return calculate_revenue_growth(income_stmt)
+    
+    @staticmethod
+    def calculate_earnings_growth(income_stmt):
+        """Calculate earnings growth metrics."""
+        return calculate_earnings_growth(income_stmt)
+    
+    @staticmethod
+    def calculate_margin_trends(income_stmt):
+        """Calculate margin trends."""
+        return calculate_margin_trends(income_stmt)
+    
+    @staticmethod
+    def calculate_asset_growth(balance_sheet):
+        """Calculate asset/equity growth."""
+        return calculate_asset_growth(balance_sheet)
+    
+    # Valuation Metrics
+    @staticmethod
+    def calculate_valuation_metrics(
+        income_stmt, balance_sheet, cash_flow=None,
+        market_cap=None, current_price=None, shares_outstanding=None,
+        period_idx=0
+    ):
+        """Calculate all valuation metrics."""
+        return calculate_valuation_metrics(
+            income_stmt, balance_sheet, cash_flow,
+            market_cap, current_price, shares_outstanding,
+            period_idx
+        )
+    
+    @staticmethod
+    def calculate_price_multiples(
+        income_stmt, balance_sheet, market_cap,
+        shares_outstanding=None, current_price=None, period_idx=0
+    ):
+        """Calculate P/E, P/B, P/S ratios."""
+        return calculate_price_multiples(
+            income_stmt, balance_sheet, market_cap,
+            shares_outstanding, current_price, period_idx
+        )
+    
+    @staticmethod
+    def calculate_ev_multiples(income_stmt, balance_sheet, market_cap, period_idx=0):
+        """Calculate EV/EBITDA, EV/Revenue."""
+        return calculate_ev_multiples(income_stmt, balance_sheet, market_cap, period_idx)
+    
+    @staticmethod
+    def calculate_peg_ratio(income_stmt, market_cap, period_idx=0):
+        """Calculate PEG ratio."""
+        return calculate_peg_ratio(income_stmt, market_cap, period_idx)
+
+
+# Create singleton instance
+fundamental_analytics = FundamentalAnalytics()
+
+
+# =============================================================================
+# Exports
+# =============================================================================
+
+__all__ = [
+    # Main service object
+    'fundamental_analytics',
+    'FundamentalAnalytics',
+    
+    # Fundamental Ratios
+    'calculate_financial_ratios',
+    'calculate_profitability_ratios',
+    'calculate_leverage_ratios',
+    'calculate_liquidity_ratios',
+    'calculate_efficiency_ratios',
+    'calculate_cashflow_ratios',
+    
+    # Growth Metrics
+    'calculate_growth_metrics',
+    'calculate_revenue_growth',
+    'calculate_earnings_growth',
+    'calculate_margin_trends',
+    'calculate_asset_growth',
+    
+    # Valuation Metrics
+    'calculate_valuation_metrics',
+    'calculate_price_multiples',
+    'calculate_ev_multiples',
+    'calculate_cf_valuation',
+    'calculate_peg_ratio',
+]

timber_common-0.3.4/common/services/analytics/fundamental.py

@@ -0,0 +1,458 @@
+# timber/common/services/analytics/fundamental.py
+"""
+Fundamental Analysis - Financial Statement Ratios
+
+Calculates ratios from income statement, balance sheet, and cash flow DataFrames.
+Works with yfinance format: rows=line items, cols=dates
+
+These are ADDITIVE to data_processor which handles price-based technical analysis.
+
+Categories:
+- Profitability: ROE, ROA, ROIC, margins
+- Leverage: Debt ratios, interest coverage
+- Liquidity: Current ratio, quick ratio
+- Efficiency: Asset turnover, inventory turnover
+"""
+
+import logging
+from typing import Dict, Any, Optional, Tuple, List
+from datetime import datetime, timezone
+import pandas as pd
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+# =============================================================================
+# FIELD NAME MAPPINGS (handles yfinance naming variations)
+# =============================================================================
+
+INCOME_FIELDS = {
+    'revenue': ['Total Revenue', 'Revenue', 'Revenues', 'Sales'],
+    'gross_profit': ['Gross Profit'],
+    'operating_income': ['Operating Income', 'EBIT'],
+    'net_income': ['Net Income', 'Net Income Common Stockholders', 'Net Income From Continuing Operations'],
+    'ebitda': ['EBITDA', 'Normalized EBITDA'],
+    'interest_expense': ['Interest Expense', 'Interest Expense Non Operating'],
+    'cost_of_revenue': ['Cost Of Revenue', 'Cost of Goods Sold'],
+    'depreciation': ['Depreciation And Amortization', 'Reconciled Depreciation'],
+}
+
+BALANCE_FIELDS = {
+    'total_assets': ['Total Assets'],
+    'total_liabilities': ['Total Liabilities Net Minority Interest', 'Total Liabilities'],
+    'total_equity': ['Stockholders Equity', 'Total Equity Gross Minority Interest', 'Common Stock Equity'],
+    'current_assets': ['Current Assets', 'Total Current Assets'],
+    'current_liabilities': ['Current Liabilities', 'Total Current Liabilities'],
+    'total_debt': ['Total Debt'],
+    'long_term_debt': ['Long Term Debt', 'Long Term Debt And Capital Lease Obligation'],
+    'short_term_debt': ['Current Debt', 'Current Debt And Capital Lease Obligation'],
+    'cash': ['Cash And Cash Equivalents', 'Cash Cash Equivalents And Short Term Investments'],
+    'inventory': ['Inventory'],
+    'receivables': ['Accounts Receivable', 'Net Receivables', 'Receivables'],
+    'payables': ['Accounts Payable', 'Payables And Accrued Expenses'],
+}
+
+CASHFLOW_FIELDS = {
+    'operating_cash_flow': ['Operating Cash Flow', 'Cash Flow From Continuing Operating Activities'],
+    'capital_expenditure': ['Capital Expenditure', 'Purchase Of Property Plant And Equipment'],
+    'free_cash_flow': ['Free Cash Flow'],
+    'dividends_paid': ['Cash Dividends Paid', 'Common Stock Dividend Paid', 'Payment Of Dividends'],
+}
+
+
+# =============================================================================
+# VALUE EXTRACTION (yfinance format: rows=items, cols=dates)
+# =============================================================================
+
+def _get_value(df: pd.DataFrame, field_names: List[str], period_idx: int = 0) -> Optional[float]:
+    """
+    Extract value from yfinance-format DataFrame.
+    
+    Args:
+        df: Financial statement (rows=line items, cols=dates)
+        field_names: Possible row names for the field
+        period_idx: Column index (0=most recent)
+    
+    Returns:
+        Float value or None
+    """
+    if df is None or df.empty:
+        return None
+    
+    for name in field_names:
+        if name in df.index:
+            try:
+                val = df.loc[name].iloc[period_idx]
+                if pd.notna(val):
+                    return float(val)
+            except (IndexError, KeyError):
+                continue
+    return None
+
+
+def _safe_divide(num: Optional[float], denom: Optional[float]) -> Optional[float]:
+    """Safely divide, returning None if invalid."""
+    if num is None or denom is None or denom == 0:
+        return None
+    return num / denom
+
+
+# =============================================================================
+# PROFITABILITY RATIOS
+# =============================================================================
+
+def calculate_profitability_ratios(
+    income_stmt: pd.DataFrame,
+    balance_sheet: pd.DataFrame,
+    period_idx: int = 0,
+) -> Tuple[Dict[str, Optional[float]], Optional[str]]:
+    """
+    Calculate profitability ratios from financial statements.
+    
+    Args:
+        income_stmt: Income statement DataFrame
+        balance_sheet: Balance sheet DataFrame
+        period_idx: Which period (0=most recent)
+    
+    Returns:
+        Tuple of (ratios_dict, error_message)
+    """
+    try:
+        revenue = _get_value(income_stmt, INCOME_FIELDS['revenue'], period_idx)
+        gross_profit = _get_value(income_stmt, INCOME_FIELDS['gross_profit'], period_idx)
+        operating_income = _get_value(income_stmt, INCOME_FIELDS['operating_income'], period_idx)
+        net_income = _get_value(income_stmt, INCOME_FIELDS['net_income'], period_idx)
+        
+        total_equity = _get_value(balance_sheet, BALANCE_FIELDS['total_equity'], period_idx)
+        total_assets = _get_value(balance_sheet, BALANCE_FIELDS['total_assets'], period_idx)
+        total_debt = _get_value(balance_sheet, BALANCE_FIELDS['total_debt'], period_idx)
+        
+        ratios = {
+            'gross_margin': _safe_divide(gross_profit, revenue),
+            'operating_margin': _safe_divide(operating_income, revenue),
+            'net_margin': _safe_divide(net_income, revenue),
+            'roe': _safe_divide(net_income, total_equity),
+            'roa': _safe_divide(net_income, total_assets),
+        }
+        
+        # ROIC = NOPAT / Invested Capital (using 25% tax estimate)
+        if operating_income is not None:
+            nopat = operating_income * 0.75
+            invested_capital = (total_equity or 0) + (total_debt or 0)
+            ratios['roic'] = _safe_divide(nopat, invested_capital) if invested_capital > 0 else None
+        else:
+            ratios['roic'] = None
+        
+        return ratios, None
+        
+    except Exception as e:
+        logger.error(f"Error calculating profitability ratios: {e}")
+        return {}, str(e)
+
+
+# =============================================================================
+# LEVERAGE RATIOS
+# =============================================================================
+
+def calculate_leverage_ratios(
+    balance_sheet: pd.DataFrame,
+    income_stmt: pd.DataFrame = None,
+    period_idx: int = 0,
+) -> Tuple[Dict[str, Optional[float]], Optional[str]]:
+    """
+    Calculate leverage/solvency ratios.
+    
+    Args:
+        balance_sheet: Balance sheet DataFrame
+        income_stmt: Income statement DataFrame (optional, for interest coverage)
+        period_idx: Which period (0=most recent)
+    
+    Returns:
+        Tuple of (ratios_dict, error_message)
+    """
+    try:
+        total_debt = _get_value(balance_sheet, BALANCE_FIELDS['total_debt'], period_idx)
+        long_term_debt = _get_value(balance_sheet, BALANCE_FIELDS['long_term_debt'], period_idx)
+        short_term_debt = _get_value(balance_sheet, BALANCE_FIELDS['short_term_debt'], period_idx)
+        
+        # Sum components if total not available
+        if total_debt is None and (long_term_debt or short_term_debt):
+            total_debt = (long_term_debt or 0) + (short_term_debt or 0)
+        
+        total_equity = _get_value(balance_sheet, BALANCE_FIELDS['total_equity'], period_idx)
+        total_assets = _get_value(balance_sheet, BALANCE_FIELDS['total_assets'], period_idx)
+        
+        ratios = {
+            'debt_to_equity': _safe_divide(total_debt, total_equity),
+            'debt_to_assets': _safe_divide(total_debt, total_assets),
+            'equity_multiplier': _safe_divide(total_assets, total_equity),
+        }
+        
+        # Interest coverage requires income statement
+        if income_stmt is not None and not income_stmt.empty:
+            operating_income = _get_value(income_stmt, INCOME_FIELDS['operating_income'], period_idx)
+            interest_expense = _get_value(income_stmt, INCOME_FIELDS['interest_expense'], period_idx)
+            depreciation = _get_value(income_stmt, INCOME_FIELDS['depreciation'], period_idx)
+            
+            if interest_expense and interest_expense > 0:
+                ratios['interest_coverage'] = _safe_divide(operating_income, interest_expense)
+            else:
+                ratios['interest_coverage'] = None
+            
+            # Debt to EBITDA
+            if operating_income is not None:
+                ebitda = operating_income + (depreciation or 0)
+                ratios['debt_to_ebitda'] = _safe_divide(total_debt, ebitda)
+            else:
+                ratios['debt_to_ebitda'] = None
+        
+        return ratios, None
+        
+    except Exception as e:
+        logger.error(f"Error calculating leverage ratios: {e}")
+        return {}, str(e)
+
+
+# =============================================================================
+# LIQUIDITY RATIOS
+# =============================================================================
+
+def calculate_liquidity_ratios(
+    balance_sheet: pd.DataFrame,
+    period_idx: int = 0,
+) -> Tuple[Dict[str, Optional[float]], Optional[str]]:
+    """
+    Calculate liquidity ratios.
+    
+    Args:
+        balance_sheet: Balance sheet DataFrame
+        period_idx: Which period (0=most recent)
+    
+    Returns:
+        Tuple of (ratios_dict, error_message)
+    """
+    try:
+        current_assets = _get_value(balance_sheet, BALANCE_FIELDS['current_assets'], period_idx)
+        current_liabilities = _get_value(balance_sheet, BALANCE_FIELDS['current_liabilities'], period_idx)
+        inventory = _get_value(balance_sheet, BALANCE_FIELDS['inventory'], period_idx)
+        cash = _get_value(balance_sheet, BALANCE_FIELDS['cash'], period_idx)
+        
+        ratios = {
+            'current_ratio': _safe_divide(current_assets, current_liabilities),
+            'cash_ratio': _safe_divide(cash, current_liabilities),
+        }
+        
+        # Quick ratio = (Current Assets - Inventory) / Current Liabilities
+        if current_assets is not None:
+            quick_assets = current_assets - (inventory or 0)
+            ratios['quick_ratio'] = _safe_divide(quick_assets, current_liabilities)
+        else:
+            ratios['quick_ratio'] = None
+        
+        # Working capital
+        if current_assets is not None and current_liabilities is not None:
+            ratios['working_capital'] = current_assets - current_liabilities
+        else:
+            ratios['working_capital'] = None
+        
+        return ratios, None
+        
+    except Exception as e:
+        logger.error(f"Error calculating liquidity ratios: {e}")
+        return {}, str(e)
+
+
+# =============================================================================
+# EFFICIENCY RATIOS
+# =============================================================================
+
+def calculate_efficiency_ratios(
+    income_stmt: pd.DataFrame,
+    balance_sheet: pd.DataFrame,
+    period_idx: int = 0,
+) -> Tuple[Dict[str, Optional[float]], Optional[str]]:
+    """
+    Calculate efficiency/activity ratios.
+    
+    Args:
+        income_stmt: Income statement DataFrame
+        balance_sheet: Balance sheet DataFrame
+        period_idx: Which period (0=most recent)
+    
+    Returns:
+        Tuple of (ratios_dict, error_message)
+    """
+    try:
+        revenue = _get_value(income_stmt, INCOME_FIELDS['revenue'], period_idx)
+        cogs = _get_value(income_stmt, INCOME_FIELDS['cost_of_revenue'], period_idx)
+        
+        total_assets = _get_value(balance_sheet, BALANCE_FIELDS['total_assets'], period_idx)
+        inventory = _get_value(balance_sheet, BALANCE_FIELDS['inventory'], period_idx)
+        receivables = _get_value(balance_sheet, BALANCE_FIELDS['receivables'], period_idx)
+        payables = _get_value(balance_sheet, BALANCE_FIELDS['payables'], period_idx)
+        
+        ratios = {
+            'asset_turnover': _safe_divide(revenue, total_assets),
+            'inventory_turnover': _safe_divide(cogs, inventory),
+            'receivables_turnover': _safe_divide(revenue, receivables),
+            'payables_turnover': _safe_divide(cogs, payables),
+        }
+        
+        # Days calculations (annual figures)
+        ratios['days_inventory'] = _safe_divide(365, ratios['inventory_turnover'])
+        ratios['days_receivables'] = _safe_divide(365, ratios['receivables_turnover'])
+        ratios['days_payables'] = _safe_divide(365, ratios['payables_turnover'])
+        
+        # Cash Conversion Cycle = DIO + DSO - DPO
+        dio = ratios.get('days_inventory')
+        dso = ratios.get('days_receivables')
+        dpo = ratios.get('days_payables')
+        
+        if all(v is not None for v in [dio, dso, dpo]):
+            ratios['cash_conversion_cycle'] = dio + dso - dpo
+        else:
+            ratios['cash_conversion_cycle'] = None
+        
+        return ratios, None
+        
+    except Exception as e:
+        logger.error(f"Error calculating efficiency ratios: {e}")
+        return {}, str(e)
+
+
+# =============================================================================
+# CASH FLOW RATIOS
+# =============================================================================
+
+def calculate_cashflow_ratios(
+    cash_flow: pd.DataFrame,
+    income_stmt: pd.DataFrame = None,
+    balance_sheet: pd.DataFrame = None,
+    period_idx: int = 0,
+) -> Tuple[Dict[str, Optional[float]], Optional[str]]:
+    """
+    Calculate cash flow quality ratios.
+    
+    Args:
+        cash_flow: Cash flow statement DataFrame
+        income_stmt: Income statement DataFrame (optional)
+        balance_sheet: Balance sheet DataFrame (optional)
+        period_idx: Which period (0=most recent)
+    
+    Returns:
+        Tuple of (ratios_dict, error_message)
+    """
+    try:
+        ocf = _get_value(cash_flow, CASHFLOW_FIELDS['operating_cash_flow'], period_idx)
+        capex = _get_value(cash_flow, CASHFLOW_FIELDS['capital_expenditure'], period_idx)
+        fcf = _get_value(cash_flow, CASHFLOW_FIELDS['free_cash_flow'], period_idx)
+        
+        # Calculate FCF if not directly available
+        if fcf is None and ocf is not None and capex is not None:
+            fcf = ocf + capex  # capex is typically negative
+        
+        ratios = {
+            'operating_cash_flow': ocf,
+            'free_cash_flow': fcf,
+            'capex': capex,
+        }
+        
+        # Cash flow to net income ratio (earnings quality)
+        if income_stmt is not None and not income_stmt.empty:
+            net_income = _get_value(income_stmt, INCOME_FIELDS['net_income'], period_idx)
+            ratios['ocf_to_net_income'] = _safe_divide(ocf, net_income)
+        
+        # FCF to revenue
+        if income_stmt is not None and not income_stmt.empty:
+            revenue = _get_value(income_stmt, INCOME_FIELDS['revenue'], period_idx)
+            ratios['fcf_margin'] = _safe_divide(fcf, revenue)
+        
+        # FCF to debt (debt coverage)
+        if balance_sheet is not None and not balance_sheet.empty:
+            total_debt = _get_value(balance_sheet, BALANCE_FIELDS['total_debt'], period_idx)
+            ratios['fcf_to_debt'] = _safe_divide(fcf, total_debt)
+        
+        return ratios, None
+        
+    except Exception as e:
+        logger.error(f"Error calculating cash flow ratios: {e}")
+        return {}, str(e)
+
+
+# =============================================================================
+# UMBRELLA FUNCTION - Main Entry Point
+# =============================================================================
+
+def calculate_financial_ratios(
+    income_stmt: pd.DataFrame,
+    balance_sheet: pd.DataFrame,
+    cash_flow: pd.DataFrame = None,
+    period_idx: int = 0,
+) -> Tuple[Dict[str, Any], Optional[str]]:
+    """
+    Calculate all fundamental ratios from financial statements.
+    
+    This is the main entry point called by task configs via:
+        service: analytics_service
+        method: calculate_financial_ratios
+    
+    Args:
+        income_stmt: Income statement DataFrame (yfinance format)
+        balance_sheet: Balance sheet DataFrame (yfinance format)
+        cash_flow: Cash flow statement DataFrame (optional)
+        period_idx: Which period to analyze (0=most recent)
+    
+    Returns:
+        Tuple of (result_dict, error_string or None)
+    """
+    try:
+        result = {
+            'success': True,
+            'period_idx': period_idx,
+            'calculated_at': datetime.now(timezone.utc).isoformat(),
+            'errors': {},
+        }
+        
+        # Get period date if available
+        if not income_stmt.empty and len(income_stmt.columns) > period_idx:
+            result['period_date'] = str(income_stmt.columns[period_idx])
+        
+        # Calculate each category
+        profitability, err = calculate_profitability_ratios(income_stmt, balance_sheet, period_idx)
+        if err:
+            result['errors']['profitability'] = err
+        result['profitability'] = profitability
+        
+        leverage, err = calculate_leverage_ratios(balance_sheet, income_stmt, period_idx)
+        if err:
+            result['errors']['leverage'] = err
+        result['leverage'] = leverage
+        
+        liquidity, err = calculate_liquidity_ratios(balance_sheet, period_idx)
+        if err:
+            result['errors']['liquidity'] = err
+        result['liquidity'] = liquidity
+        
+        efficiency, err = calculate_efficiency_ratios(income_stmt, balance_sheet, period_idx)
+        if err:
+            result['errors']['efficiency'] = err
+        result['efficiency'] = efficiency
+        
+        if cash_flow is not None and not cash_flow.empty:
+            cashflow_ratios, err = calculate_cashflow_ratios(
+                cash_flow, income_stmt, balance_sheet, period_idx
+            )
+            if err:
+                result['errors']['cash_flow'] = err
+            result['cash_flow'] = cashflow_ratios
+        
+        # Mark as failed if all categories errored
+        if len(result['errors']) >= 4:
+            result['success'] = False
+        
+        return result, None
+        
+    except Exception as e:
+        logger.error(f"Error in calculate_financial_ratios: {e}")
+        return {'success': False, 'error': str(e)}, str(e)