fin-infra 0.1.69__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,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:
@@ -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/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)
@@ -713,6 +712,7 @@ def _calculate_allocation_from_holdings(
         - 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/banking/__init__.py

@@ -45,12 +45,12 @@ from __future__ import annotations
 
 import os
 from datetime import date
-from typing import TYPE_CHECKING, Optional, cast
+from typing import TYPE_CHECKING, cast
 
 from pydantic import BaseModel, Field
 
-from ..providers.registry import resolve
 from ..providers.base import BankingProvider
+from ..providers.registry import resolve
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
@@ -99,7 +99,7 @@ class ExchangeTokenResponse(BaseModel):
     """Response model for token exchange."""
 
     access_token: str
-    item_id: Optional[str] = None
+    item_id: str | None = None
 
 
 class BalanceHistoryStats(BaseModel):
@@ -174,7 +174,6 @@ def easy_banking(provider: str = "teller", **config) -> BankingProvider:
     See Also:
         - add_banking(): For FastAPI integration with routes
         - docs/banking.md: Comprehensive banking integration guide
-        - docs/adr/0003-banking-integration.md: Architecture decisions
     """
     # Auto-detect provider config from environment if not explicitly provided
     # Only auto-detect if no config params were passed
@@ -199,11 +198,11 @@ def easy_banking(provider: str = "teller", **config) -> BankingProvider:
             }
 
     # Use provider registry to dynamically load and configure provider
-    return cast(BankingProvider, resolve("banking", provider, **config))
+    return cast("BankingProvider", resolve("banking", provider, **config))
 
 
 def add_banking(
-    app: "FastAPI",
+    app: FastAPI,
     *,
     provider: str | BankingProvider | None = None,
     prefix: str = "/banking",
@@ -350,25 +349,25 @@ def add_banking(
     @router.get("/transactions")
     async def get_transactions(
         access_token: str = Depends(get_access_token),
-        start_date: Optional[date] = Query(None, description="Filter by start date (ISO format)"),
-        end_date: Optional[date] = Query(None, description="Filter by end date (ISO format)"),
-        merchant: Optional[str] = Query(
+        start_date: date | None = Query(None, description="Filter by start date (ISO format)"),
+        end_date: date | None = Query(None, description="Filter by end date (ISO format)"),
+        merchant: str | None = Query(
             None, description="Filter by merchant name (partial match, case-insensitive)"
         ),
-        category: Optional[str] = Query(
+        category: str | None = Query(
             None, description="Filter by category (comma-separated list for multiple)"
         ),
-        min_amount: Optional[float] = Query(
+        min_amount: float | None = Query(
             None, description="Minimum transaction amount (inclusive)"
         ),
-        max_amount: Optional[float] = Query(
+        max_amount: float | None = Query(
             None, description="Maximum transaction amount (inclusive)"
         ),
-        tags: Optional[str] = Query(None, description="Filter by tags (comma-separated list)"),
-        account_id: Optional[str] = Query(None, description="Filter by specific account ID"),
-        is_recurring: Optional[bool] = Query(None, description="Filter by recurring status"),
-        sort_by: Optional[str] = Query("date", description="Sort field: date, amount, or merchant"),
-        order: Optional[str] = Query("desc", description="Sort order: asc or desc"),
+        tags: str | None = Query(None, description="Filter by tags (comma-separated list)"),
+        account_id: str | None = Query(None, description="Filter by specific account ID"),
+        is_recurring: bool | None = Query(None, description="Filter by recurring status"),
+        sort_by: str | None = Query("date", description="Sort field: date, amount, or merchant"),
+        order: str | None = Query("desc", description="Sort order: asc or desc"),
         page: int = Query(1, ge=1, description="Page number (starts at 1)"),
         per_page: int = Query(50, ge=1, le=200, description="Items per page (max 200)"),
     ):
@@ -476,7 +475,7 @@ def add_banking(
     @router.get("/balances")
     async def get_balances(
         access_token: str = Depends(get_access_token),
-        account_id: Optional[str] = Query(None),
+        account_id: str | None = Query(None),
     ):
         """Get current balances."""
         balances = banking.balances(
@@ -593,17 +592,17 @@ def add_banking(
 
 # Import utilities at end to avoid circular imports
 from .utils import (  # noqa: E402
-    validate_plaid_token,
-    validate_teller_token,
-    validate_mx_token,
-    validate_provider_token,
+    BankingConnectionInfo,
+    BankingConnectionStatus,
+    get_primary_access_token,
+    mark_connection_healthy,
+    mark_connection_unhealthy,
     parse_banking_providers,
     sanitize_connection_status,
-    mark_connection_unhealthy,
-    mark_connection_healthy,
-    get_primary_access_token,
-    test_connection_health,
     should_refresh_token,
-    BankingConnectionInfo,
-    BankingConnectionStatus,
+    test_connection_health,
+    validate_mx_token,
+    validate_plaid_token,
+    validate_provider_token,
+    validate_teller_token,
 )

fin_infra/banking/history.py

@@ -42,9 +42,8 @@ from __future__ import annotations
 import logging
 import os
 from datetime import date, datetime, timedelta
-from typing import List, Optional
-from pydantic import BaseModel, Field, ConfigDict
 
+from pydantic import BaseModel, ConfigDict, Field
 
 __all__ = [
     "BalanceSnapshot",
@@ -59,7 +58,7 @@ _logger = logging.getLogger(__name__)
 
 # In-memory storage for testing (will be replaced with SQL database in production)
 # ⚠️ WARNING: All data is LOST on restart when using in-memory storage!
-_balance_snapshots: List[BalanceSnapshot] = []
+_balance_snapshots: list[BalanceSnapshot] = []
 _production_warning_logged = False
 
 
@@ -155,9 +154,9 @@ def record_balance_snapshot(
 def get_balance_history(
     account_id: str,
     days: int = 90,
-    start_date: Optional[date] = None,
-    end_date: Optional[date] = None,
-) -> List[BalanceSnapshot]:
+    start_date: date | None = None,
+    end_date: date | None = None,
+) -> list[BalanceSnapshot]:
     """Get balance history for an account.
 
     Retrieves balance snapshots for the specified account within a date range.
@@ -216,8 +215,8 @@ def get_balance_history(
 
 def get_balance_snapshots(
     account_id: str,
-    dates: List[date],
-) -> List[BalanceSnapshot]:
+    dates: list[date],
+) -> list[BalanceSnapshot]:
     """Get balance snapshots for specific dates.
 
     Args:
@@ -248,7 +247,7 @@ def get_balance_snapshots(
 
 def delete_balance_history(
     account_id: str,
-    before_date: Optional[date] = None,
+    before_date: date | None = None,
 ) -> int:
     """Delete balance history for an account.