fin-infra 0.1.62__py3-none-any.whl → 0.1.82__py3-none-any.whl

fin_infra/__init__.py

@@ -1,9 +1,45 @@
-"""fin_infra: Financial infrastructure toolkit.
+"""fin_infra: Financial Infrastructure Toolkit.
 
-Public surface is intentionally small at this stage. Import from submodules for
-specific domains (clients, models, markets, credit).
+A comprehensive financial infrastructure library providing:
+- Banking integration (Plaid, Teller, MX)
+- Brokerage integration (Alpaca, Interactive Brokers)
+- Market data (stocks, crypto, forex)
+- Credit scores (Experian, Equifax, TransUnion)
+- Financial calculations (NPV, IRR, PMT, FV, PV)
+- Portfolio analytics (returns, allocation, benchmarking)
+- Transaction categorization (rule-based + ML)
+- Budget management and cash flow analysis
+- Net worth tracking and goal management
+
+Example:
+    from fin_infra.banking import easy_banking
+    from fin_infra.markets import easy_market
+
+    banking = easy_banking()
+    market = easy_market()
+    quote = market.quote("AAPL")
 """
 
+from __future__ import annotations
+
+# Core modules - can be imported as `from fin_infra import banking`
+from . import (
+    analytics,
+    banking,
+    brokerage,
+    budgets,
+    cashflows,
+    categorization,
+    credit,
+    crypto,
+    investments,
+    markets,
+    net_worth,
+    recurring,
+    tax,
+)
+
+# Base exceptions
 from .exceptions import (
     FinInfraError,
     ProviderError,
@@ -14,6 +50,20 @@ from .version import __version__
 
 __all__ = [
     "__version__",
+    # Core modules
+    "analytics",
+    "banking",
+    "brokerage",
+    "budgets",
+    "cashflows",
+    "categorization",
+    "credit",
+    "crypto",
+    "investments",
+    "markets",
+    "net_worth",
+    "recurring",
+    "tax",
     # Base errors
     "FinInfraError",
     "ProviderError",

fin_infra/analytics/__init__.py

@@ -7,6 +7,16 @@ This module provides comprehensive financial analytics capabilities including:
 - Portfolio analytics (returns, allocation, benchmarking)
 - Growth projections (net worth forecasting with scenarios)
 
+Feature Status:
+    ✅ STABLE: Core calculation functions (all analytics work with provided data)
+    ⚠️  INTEGRATION: Auto-fetching from providers requires setup:
+        - Banking provider for transaction data
+        - Brokerage provider for investment data
+        - Categorization for expense categorization
+
+    When providers aren't configured, functions accept data directly or return
+    sensible placeholder values for testing/development.
+
 Serves multiple use cases:
 - Personal finance apps (cash flow, savings tracking)
 - Wealth management platforms (portfolio analytics, projections)
@@ -45,10 +55,11 @@ Dependencies:
 
 from __future__ import annotations
 
-# Import actual implementations
-from .ease import easy_analytics, AnalyticsEngine
 from .add import add_analytics
 
+# Import actual implementations
+from .ease import AnalyticsEngine, easy_analytics
+
 __all__ = [
     "easy_analytics",
     "add_analytics",

fin_infra/analytics/add.py

@@ -7,7 +7,7 @@ MUST use svc-infra dual routers (user_router) - NEVER generic APIRouter.
 from __future__ import annotations
 
 from datetime import datetime
-from typing import TYPE_CHECKING, Optional
+from typing import TYPE_CHECKING
 
 from fastapi import HTTPException, Query
 from pydantic import BaseModel, Field
@@ -15,15 +15,15 @@ from pydantic import BaseModel, Field
 if TYPE_CHECKING:
     from fastapi import FastAPI
 
-from .ease import easy_analytics, AnalyticsEngine
+from .ease import AnalyticsEngine, easy_analytics
 from .models import (
+    BenchmarkComparison,
     CashFlowAnalysis,
-    SavingsRateData,
-    SpendingInsight,
+    GrowthProjection,
     PersonalizedSpendingAdvice,
     PortfolioMetrics,
-    BenchmarkComparison,
-    GrowthProjection,
+    SavingsRateData,
+    SpendingInsight,
 )
 
 
@@ -33,15 +33,15 @@ class NetWorthForecastRequest(BaseModel):
 
     user_id: str = Field(..., description="User identifier")
     years: int = Field(default=30, ge=1, le=50, description="Projection years (1-50)")
-    initial_net_worth: Optional[float] = Field(None, description="Override initial net worth")
-    annual_contribution: Optional[float] = Field(None, description="Annual savings contribution")
-    conservative_return: Optional[float] = Field(
+    initial_net_worth: float | None = Field(None, description="Override initial net worth")
+    annual_contribution: float | None = Field(None, description="Annual savings contribution")
+    conservative_return: float | None = Field(
         None, description="Conservative return rate (e.g., 0.05 = 5%)"
     )
-    moderate_return: Optional[float] = Field(
+    moderate_return: float | None = Field(
         None, description="Moderate return rate (e.g., 0.07 = 7%)"
     )
-    aggressive_return: Optional[float] = Field(
+    aggressive_return: float | None = Field(
         None, description="Aggressive return rate (e.g., 0.10 = 10%)"
     )
 
@@ -49,7 +49,7 @@ class NetWorthForecastRequest(BaseModel):
 def add_analytics(
     app: FastAPI,
     prefix: str = "/analytics",
-    provider: Optional[AnalyticsEngine] = None,
+    provider: AnalyticsEngine | None = None,
     include_in_schema: bool = True,
 ) -> AnalyticsEngine:
     """Add analytics endpoints to FastAPI application.
@@ -124,9 +124,9 @@ def add_analytics(
     )
     async def get_cash_flow(
         user_id: str,
-        start_date: Optional[datetime] = None,
-        end_date: Optional[datetime] = None,
-        period_days: Optional[int] = None,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+        period_days: int | None = None,
     ) -> CashFlowAnalysis:
         """
         Calculate cash flow analysis for a user.
@@ -164,7 +164,7 @@ def add_analytics(
     )
     async def get_spending_insights(
         user_id: str,
-        period_days: Optional[int] = None,
+        period_days: int | None = None,
         include_trends: bool = True,
     ) -> SpendingInsight:
         """
@@ -186,7 +186,7 @@ def add_analytics(
     )
     async def get_spending_advice(
         user_id: str,
-        period_days: Optional[int] = None,
+        period_days: int | None = None,
     ) -> PersonalizedSpendingAdvice:
         """
         Generate personalized spending advice using AI.
@@ -206,14 +206,12 @@ def add_analytics(
     )
     async def get_portfolio_metrics(
         user_id: str,
-        accounts: Optional[list[str]] = None,
+        accounts: list[str] | None = None,
         with_holdings: bool = Query(
-            False,
-            description="Use real holdings data from investment provider for accurate P/L"
+            False, description="Use real holdings data from investment provider for accurate P/L"
         ),
-        access_token: Optional[str] = Query(
-            None,
-            description="Investment provider access token (required if with_holdings=true)"
+        access_token: str | None = Query(
+            None, description="Investment provider access token (required if with_holdings=true)"
         ),
     ) -> PortfolioMetrics:
         """
@@ -249,31 +247,31 @@ def add_analytics(
         if with_holdings:
             # Check if investment provider is available on app state
             investment_provider = getattr(app.state, "investment_provider", None)
-            
+
             if investment_provider and access_token:
                 try:
                     # Fetch real holdings from investment provider
                     from fin_infra.analytics.portfolio import portfolio_metrics_with_holdings
-                    
+
                     holdings = await investment_provider.get_holdings(
                         access_token=access_token,
                         account_ids=accounts,
                     )
-                    
+
                     # Calculate metrics from real holdings
                     return portfolio_metrics_with_holdings(holdings)
-                    
+
                 except Exception as e:
                     # Fall back to balance-only calculation on error
                     # Log error but don't fail the request
                     import logging
+
                     logging.warning(f"Failed to fetch holdings, falling back to balance-only: {e}")
             elif with_holdings and not access_token:
                 raise HTTPException(
-                    status_code=400,
-                    detail="access_token required when with_holdings=true"
+                    status_code=400, detail="access_token required when with_holdings=true"
                 )
-        
+
         # Default: Use balance-only calculation (existing behavior)
         return await provider.portfolio_metrics(
             user_id,
@@ -288,9 +286,9 @@ def add_analytics(
     )
     async def get_benchmark_comparison(
         user_id: str,
-        benchmark: Optional[str] = None,
+        benchmark: str | None = None,
         period: str = "1y",
-        accounts: Optional[list[str]] = None,
+        accounts: list[str] | None = None,
     ) -> BenchmarkComparison:
         """
         Compare portfolio to benchmark (e.g., SPY, VTI).

fin_infra/analytics/cash_flow.py

@@ -6,6 +6,7 @@ Provides income vs expense analysis, breakdowns by source/category, and forecast
 from __future__ import annotations
 
 from datetime import datetime, timedelta
+from decimal import Decimal
 from typing import Any, Optional
 
 from ..models import Transaction
@@ -219,7 +220,7 @@ async def forecast_cash_flow(
 def _categorize_transactions(
     transactions: list[Transaction],
     categorization_provider=None,
-) -> tuple[dict[str, float], dict[str, float]]:
+) -> tuple[dict[str, Decimal], dict[str, Decimal]]:
     """Helper to categorize transactions into income sources and expense categories.
 
     Args:
@@ -229,19 +230,19 @@ def _categorize_transactions(
     Returns:
         Tuple of (income_by_source, expenses_by_category) dicts
     """
-    income_by_source: dict[str, float] = {}
-    expenses_by_category: dict[str, float] = {}
+    income_by_source: dict[str, Decimal] = {}
+    expenses_by_category: dict[str, Decimal] = {}
 
     for txn in transactions:
         if txn.amount > 0:
             # Income transaction
             source = _determine_income_source(txn)
-            income_by_source[source] = income_by_source.get(source, 0) + txn.amount
+            income_by_source[source] = income_by_source.get(source, Decimal(0)) + txn.amount
         else:
             # Expense transaction
             category = _get_expense_category(txn, categorization_provider)
             amount = abs(txn.amount)
-            expenses_by_category[category] = expenses_by_category.get(category, 0) + amount
+            expenses_by_category[category] = expenses_by_category.get(category, Decimal(0)) + amount
 
     return income_by_source, expenses_by_category
 

fin_infra/analytics/ease.py

@@ -16,23 +16,22 @@ Typical usage:
     portfolio = await analytics.portfolio_metrics(user_id="user123")
 """
 
-from typing import Optional
 from datetime import datetime, timedelta
 
 from .cash_flow import calculate_cash_flow
-from .savings import calculate_savings_rate, SavingsDefinition
-from .spending import analyze_spending, generate_spending_insights
-from .portfolio import calculate_portfolio_metrics, compare_to_benchmark
-from .projections import project_net_worth, calculate_compound_interest
 from .models import (
+    BenchmarkComparison,
     CashFlowAnalysis,
-    SavingsRateData,
-    SpendingInsight,
+    GrowthProjection,
     PersonalizedSpendingAdvice,
     PortfolioMetrics,
-    BenchmarkComparison,
-    GrowthProjection,
+    SavingsRateData,
+    SpendingInsight,
 )
+from .portfolio import calculate_portfolio_metrics, compare_to_benchmark
+from .projections import calculate_compound_interest, project_net_worth
+from .savings import SavingsDefinition, calculate_savings_rate
+from .spending import analyze_spending, generate_spending_insights
 
 
 class AnalyticsEngine:
@@ -93,9 +92,9 @@ class AnalyticsEngine:
         self,
         user_id: str,
         *,
-        start_date: Optional[datetime] = None,
-        end_date: Optional[datetime] = None,
-        period_days: Optional[int] = None,
+        start_date: datetime | None = None,
+        end_date: datetime | None = None,
+        period_days: int | None = None,
     ) -> CashFlowAnalysis:
         """Analyze cash flow (income vs expenses).
 
@@ -129,7 +128,7 @@ class AnalyticsEngine:
         self,
         user_id: str,
         *,
-        definition: Optional[str | SavingsDefinition] = None,
+        definition: str | SavingsDefinition | None = None,
         period: str = "monthly",
     ) -> SavingsRateData:
         """Calculate savings rate.
@@ -163,7 +162,7 @@ class AnalyticsEngine:
         self,
         user_id: str,
         *,
-        period_days: Optional[int] = None,
+        period_days: int | None = None,
         include_trends: bool = True,
     ) -> SpendingInsight:
         """Analyze spending patterns and generate insights.
@@ -193,8 +192,8 @@ class AnalyticsEngine:
         self,
         user_id: str,
         *,
-        period_days: Optional[int] = None,
-        user_context: Optional[dict] = None,
+        period_days: int | None = None,
+        user_context: dict | None = None,
     ) -> PersonalizedSpendingAdvice:
         """Generate AI-powered personalized spending advice.
 
@@ -228,7 +227,7 @@ class AnalyticsEngine:
         self,
         user_id: str,
         *,
-        accounts: Optional[list[str]] = None,
+        accounts: list[str] | None = None,
     ) -> PortfolioMetrics:
         """Calculate portfolio performance metrics.
 
@@ -250,9 +249,9 @@ class AnalyticsEngine:
         self,
         user_id: str,
         *,
-        benchmark: Optional[str] = None,
+        benchmark: str | None = None,
         period: str = "1y",
-        accounts: Optional[list[str]] = None,
+        accounts: list[str] | None = None,
     ) -> BenchmarkComparison:
         """Compare portfolio to benchmark index.
 
@@ -282,7 +281,7 @@ class AnalyticsEngine:
         user_id: str,
         *,
         years: int = 30,
-        assumptions: Optional[dict] = None,
+        assumptions: dict | None = None,
     ) -> GrowthProjection:
         """Project net worth growth with scenarios.
 

fin_infra/analytics/portfolio.py

@@ -35,7 +35,6 @@ Examples:
 """
 
 from datetime import datetime
-from typing import Optional
 
 from fin_infra.analytics.models import (
     AssetAllocation,
@@ -47,7 +46,7 @@ from fin_infra.analytics.models import (
 async def calculate_portfolio_metrics(
     user_id: str,
     *,
-    accounts: Optional[list[str]] = None,
+    accounts: list[str] | None = None,
     brokerage_provider=None,
     market_provider=None,
 ) -> PortfolioMetrics:
@@ -131,7 +130,7 @@ async def compare_to_benchmark(
     *,
     benchmark: str = "SPY",
     period: str = "1y",
-    accounts: Optional[list[str]] = None,
+    accounts: list[str] | None = None,
     brokerage_provider=None,
     market_provider=None,
 ) -> BenchmarkComparison:
@@ -221,7 +220,7 @@ async def compare_to_benchmark(
 
 def _generate_mock_holdings(
     user_id: str,
-    accounts: Optional[list[str]] = None,
+    accounts: list[str] | None = None,
 ) -> list[dict]:
     """Generate mock portfolio holdings for testing.
 
@@ -415,7 +414,7 @@ def _parse_benchmark_period(period: str) -> int:
 def _calculate_portfolio_return(
     user_id: str,
     period_days: int,
-    accounts: Optional[list[str]] = None,
+    accounts: list[str] | None = None,
 ) -> tuple[float, float]:
     """Calculate portfolio return for specified period.
 
@@ -483,7 +482,7 @@ def _calculate_beta(
     user_id: str,
     benchmark: str,
     period_days: int,
-) -> Optional[float]:
+) -> float | None:
     """Calculate portfolio beta (volatility relative to benchmark).
 
     Beta = Covariance(portfolio_returns, benchmark_returns) / Variance(benchmark_returns)
@@ -565,25 +564,18 @@ def portfolio_metrics_with_holdings(holdings: list) -> PortfolioMetrics:
         >>> metrics = portfolio_metrics_with_holdings(holdings)
     """
     # Import here to avoid circular dependency
-    from decimal import Decimal
 
     # Calculate total portfolio value and cost basis
-    total_value = float(sum(
-        holding.institution_value
-        for holding in holdings
-    ))
+    total_value = float(sum(holding.institution_value for holding in holdings))
 
-    total_cost_basis = float(sum(
-        holding.cost_basis if holding.cost_basis is not None else 0
-        for holding in holdings
-    ))
+    total_cost_basis = float(
+        sum(holding.cost_basis if holding.cost_basis is not None else 0 for holding in holdings)
+    )
 
     # Calculate total return (P/L)
     total_return_dollars = total_value - total_cost_basis
     total_return_percent = (
-        (total_return_dollars / total_cost_basis * 100.0)
-        if total_cost_basis > 0
-        else 0.0
+        (total_return_dollars / total_cost_basis * 100.0) if total_cost_basis > 0 else 0.0
     )
 
     # Calculate asset allocation from real security types
@@ -685,9 +677,7 @@ def calculate_day_change_with_snapshot(
     # Calculate day change
     day_change_dollars = current_total - previous_total
     day_change_percent = (
-        (day_change_dollars / previous_total * 100.0)
-        if previous_total > 0
-        else 0.0
+        (day_change_dollars / previous_total * 100.0) if previous_total > 0 else 0.0
     )
 
     return {
@@ -722,6 +712,7 @@ def _calculate_allocation_from_holdings(
         - other → Other
     """
     from collections import defaultdict
+
     from .models import AssetAllocation
 
     if total_value == 0:
@@ -739,18 +730,20 @@ def _calculate_allocation_from_holdings(
     }
 
     # Sum values by asset class
-    allocation_values = defaultdict(float)
+    allocation_values: dict[str, float] = defaultdict(float)
     for holding in holdings:
-        security_type = holding.security.type.value if hasattr(holding.security.type, 'value') else holding.security.type
+        security_type = (
+            holding.security.type.value
+            if hasattr(holding.security.type, "value")
+            else holding.security.type
+        )
         asset_class = type_to_class.get(security_type, "Other")
         allocation_values[asset_class] += float(holding.institution_value)
 
     # Convert to list of AssetAllocation objects
     allocation_list = [
         AssetAllocation(
-            asset_class=asset_class,
-            value=value,
-            percentage=round((value / total_value) * 100.0, 2)
+            asset_class=asset_class, value=value, percentage=round((value / total_value) * 100.0, 2)
         )
         for asset_class, value in allocation_values.items()
     ]

fin_infra/analytics/projections.py

@@ -19,12 +19,10 @@ Typical usage:
     )
 """
 
-from typing import Optional
 import math
 
 from fin_infra.analytics.models import GrowthProjection, Scenario
 
-
 # ============================================================================
 # Public API
 # ============================================================================
@@ -34,7 +32,7 @@ async def project_net_worth(
     user_id: str,
     *,
     years: int = 30,
-    assumptions: Optional[dict] = None,
+    assumptions: dict | None = None,
     net_worth_provider=None,
     cash_flow_provider=None,
 ) -> GrowthProjection:

fin_infra/analytics/rebalancing.py

@@ -329,13 +329,11 @@ def _generate_trade_reasoning(
 
     if action == "buy":
         return (
-            f"Buy {symbol} to increase {asset_class} allocation "
-            f"by {diff_pct:.1f}% towards target"
+            f"Buy {symbol} to increase {asset_class} allocation by {diff_pct:.1f}% towards target"
         )
     else:
         return (
-            f"Sell {symbol} to decrease {asset_class} allocation "
-            f"by {diff_pct:.1f}% towards target"
+            f"Sell {symbol} to decrease {asset_class} allocation by {diff_pct:.1f}% towards target"
         )
 
 

fin_infra/analytics/savings.py

@@ -77,7 +77,7 @@ async def calculate_savings_rate(
         period_enum = Period(period)
     except ValueError:
         raise ValueError(
-            f"Invalid period '{period}'. Must be one of: " f"{', '.join([p.value for p in Period])}"
+            f"Invalid period '{period}'. Must be one of: {', '.join([p.value for p in Period])}"
         )
 
     try:

fin_infra/analytics/spending.py

@@ -162,12 +162,13 @@ async def analyze_spending(
     )
 
     return SpendingInsight(
-        top_merchants=top_merchants,
-        category_breakdown=dict(category_totals),
+        # Convert Decimal to float for model compatibility (intentional for Pydantic field types)
+        top_merchants=[(m, float(v)) for m, v in top_merchants],
+        category_breakdown={k: float(v) for k, v in category_totals.items()},
         spending_trends=spending_trends,
         anomalies=anomalies,
         period_days=days,
-        total_spending=total_spending,
+        total_spending=float(total_spending) if total_spending else 0.0,
     )
 
 
@@ -291,10 +292,10 @@ async def _calculate_spending_trends(
         # In reality, would fetch historical data
         previous_amount = current_amount * Decimal("0.9")
 
-        change_percent = (
-            ((current_amount - previous_amount) / previous_amount) * 100
+        change_percent: float = (
+            float((current_amount - previous_amount) / previous_amount) * 100
             if previous_amount > 0
-            else 0
+            else 0.0
         )
 
         # Threshold for "stable" is within 5%
@@ -342,8 +343,10 @@ async def _detect_spending_anomalies(
         # In reality, would calculate from historical data
         average_amount = current_amount * Decimal("0.8")
 
-        deviation_percent = (
-            ((current_amount - average_amount) / average_amount) * 100 if average_amount > 0 else 0
+        deviation_percent: float = (
+            float((current_amount - average_amount) / average_amount) * 100
+            if average_amount > 0
+            else 0.0
         )
 
         # Detect anomalies based on deviation
@@ -359,9 +362,10 @@ async def _detect_spending_anomalies(
         anomalies.append(
             SpendingAnomaly(
                 category=category,
-                current_amount=current_amount,
-                average_amount=average_amount,
-                deviation_percent=deviation_percent,
+                # Convert Decimal to float for model compatibility (intentional for Pydantic field types)
+                current_amount=float(current_amount),
+                average_amount=float(average_amount),
+                deviation_percent=float(deviation_percent),
                 severity=severity,
             )
         )