fin-infra 0.1.69__py3-none-any.whl → 0.4.0__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:
+    [OK] 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,11 +206,11 @@ 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"
         ),
-        access_token: Optional[str] = Query(
+        access_token: str | None = Query(
             None, description="Investment provider access token (required if with_holdings=true)"
         ),
     ) -> PortfolioMetrics:
@@ -239,9 +239,9 @@ def add_analytics(
 
         Note:
             Real holdings provide:
-            - Accurate cost basis → real profit/loss
-            - Security types → precise asset allocation
-            - Current values → live portfolio tracking
+            - Accurate cost basis -> real profit/loss
+            - Security types -> precise asset allocation
+            - Current values -> live portfolio tracking
         """
         # If with_holdings requested and investment provider available
         if with_holdings:
@@ -286,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

@@ -7,7 +7,7 @@ from __future__ import annotations
 
 from datetime import datetime, timedelta
 from decimal import Decimal
-from typing import Any, Optional
+from typing import Any
 
 from ..models import Transaction
 from .models import CashFlowAnalysis
@@ -17,7 +17,7 @@ async def calculate_cash_flow(
     user_id: str,
     start_date: str | datetime,
     end_date: str | datetime,
-    accounts: Optional[list[str]] = None,
+    accounts: list[str] | None = None,
     *,
     banking_provider=None,
     categorization_provider=None,
@@ -117,7 +117,7 @@ async def calculate_cash_flow(
 async def forecast_cash_flow(
     user_id: str,
     months: int = 6,
-    assumptions: Optional[dict[str, Any]] = None,
+    assumptions: dict[str, Any] | None = None,
     *,
     recurring_provider=None,
 ) -> list[CashFlowAnalysis]:

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/models.py

@@ -7,7 +7,7 @@ from __future__ import annotations
 
 from datetime import datetime
 from enum import Enum
-from typing import Any, Optional
+from typing import Any
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -72,7 +72,7 @@ class SavingsRateData(BaseModel):
     expenses: float = Field(..., description="Total expenses for period")
     period: Period = Field(..., description="Period type")
     definition: SavingsDefinition = Field(..., description="Calculation method used")
-    trend: Optional[TrendDirection] = Field(None, description="Trend over time")
+    trend: TrendDirection | None = Field(None, description="Trend over time")
 
 
 class SpendingAnomaly(BaseModel):
@@ -132,7 +132,7 @@ class PersonalizedSpendingAdvice(BaseModel):
     alerts: list[str] = Field(
         default_factory=list, description="Urgent spending issues requiring attention"
     )
-    estimated_monthly_savings: Optional[float] = Field(
+    estimated_monthly_savings: float | None = Field(
         None, description="Potential monthly savings if recommendations followed"
     )
 
@@ -183,7 +183,7 @@ class BenchmarkComparison(BaseModel):
     benchmark_return_percent: float = Field(..., description="Benchmark return percentage")
     benchmark_symbol: str = Field(..., description="Benchmark ticker (e.g., SPY)")
     alpha: float = Field(..., description="Portfolio alpha (excess return)")
-    beta: Optional[float] = Field(None, description="Portfolio beta (volatility vs benchmark)")
+    beta: float | None = Field(None, description="Portfolio beta (volatility vs benchmark)")
     period: str = Field(..., description="Comparison period (1y, 3y, 5y, etc.)")
 
 
@@ -213,6 +213,6 @@ class GrowthProjection(BaseModel):
     assumptions: dict[str, Any] = Field(
         default_factory=dict, description="Assumptions used (inflation, returns, etc.)"
     )
-    confidence_intervals: Optional[dict[str, tuple[float, float]]] = Field(
+    confidence_intervals: dict[str, tuple[float, float]] | None = Field(
         None, description="95% confidence intervals by scenario"
     )

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)
@@ -528,10 +527,10 @@ def portfolio_metrics_with_holdings(holdings: list) -> PortfolioMetrics:
         PortfolioMetrics with real portfolio analysis
 
     Real Data Advantages:
-        - Actual cost basis → accurate P/L calculations
-        - Real security types → precise asset allocation
-        - Current market values → live portfolio value
-        - No mock data → production-ready analytics
+        - Actual cost basis -> accurate P/L calculations
+        - Real security types -> precise asset allocation
+        - Current market values -> live portfolio value
+        - No mock data -> production-ready analytics
 
     Limitations:
         - Day/YTD/MTD returns require historical snapshots (not in holdings)
@@ -653,7 +652,7 @@ def calculate_day_change_with_snapshot(
         Function matches holdings by account_id + security_id for accurate tracking
         of individual position changes (accounts for buys/sells, not just price moves).
     """
-    # Build lookup map for previous snapshot: (account_id, security_id) → value
+    # Build lookup map for previous snapshot: (account_id, security_id) -> value
     previous_map = {}
     for holding in previous_snapshot:
         key = (holding.account_id, holding.security.security_id)
@@ -704,15 +703,16 @@ def _calculate_allocation_from_holdings(
         list[AssetAllocation] with asset_class, value, and percentage
 
     Asset Class Mapping:
-        - equity → Stocks
-        - etf → Stocks (equity ETFs grouped with stocks)
-        - mutual_fund → Bonds (conservative assumption)
-        - bond → Bonds
-        - cash → Cash
-        - derivative → Other
-        - other → Other
+        - equity -> Stocks
+        - etf -> Stocks (equity ETFs grouped with stocks)
+        - mutual_fund -> Bonds (conservative assumption)
+        - bond -> Bonds
+        - cash -> Cash
+        - derivative -> Other
+        - other -> Other
     """
     from collections import defaultdict
+
     from .models import AssetAllocation
 
     if total_value == 0:

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/spending.py

@@ -45,7 +45,6 @@ Examples:
 from collections import defaultdict
 from datetime import timedelta
 from decimal import Decimal
-from typing import Optional
 
 from fin_infra.analytics.models import (
     PersonalizedSpendingAdvice,
@@ -60,7 +59,7 @@ async def analyze_spending(
     user_id: str,
     *,
     period: str = "30d",
-    categories: Optional[list[str]] = None,
+    categories: list[str] | None = None,
     banking_provider=None,
     categorization_provider=None,
 ) -> SpendingInsight:
@@ -426,7 +425,7 @@ def _generate_mock_transactions(days: int) -> list[Transaction]:
 async def generate_spending_insights(
     spending_insight: SpendingInsight,
     *,
-    user_context: Optional[dict] = None,
+    user_context: dict | None = None,
     llm_provider=None,
 ) -> "PersonalizedSpendingAdvice":
     """Generate personalized spending insights using LLM.
@@ -521,7 +520,7 @@ async def generate_spending_insights(
 
 def _build_spending_insights_prompt(
     spending_insight: SpendingInsight,
-    user_context: Optional[dict] = None,
+    user_context: dict | None = None,
 ) -> str:
     """Build LLM prompt with financial context.
 
@@ -621,7 +620,7 @@ Be specific, encouraging, and actionable. Focus on realistic savings, not extrem
 
 def _generate_rule_based_insights(
     spending_insight: SpendingInsight,
-    user_context: Optional[dict] = None,
+    user_context: dict | None = None,
 ) -> "PersonalizedSpendingAdvice":
     """Generate rule-based insights when LLM is unavailable.