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

fin_infra/net_worth/aggregator.py

@@ -30,6 +30,7 @@ print(f"Net Worth: ${snapshot.total_net_worth:,.2f}")
 """
 
 import asyncio
+import logging
 import uuid
 from datetime import datetime
 from typing import Any
@@ -47,6 +48,8 @@ from fin_infra.net_worth.models import (
     NetWorthSnapshot,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class NetWorthAggregator:
     """
@@ -219,8 +222,7 @@ class NetWorthAggregator:
 
         for i, result in enumerate(results):
             if isinstance(result, BaseException):
-                # Log error but continue (graceful degradation)
-                print(f"Provider {providers_used[i]} failed: {result}")
+                logger.warning("Provider %s failed: %s", providers_used[i], result)
                 continue
 
             # result is now tuple[list[AssetDetail], list[LiabilityDetail]]

fin_infra/net_worth/insights.py

@@ -31,7 +31,6 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
-
 # ============================================================================
 # Pydantic Schemas (Structured Output)
 # ============================================================================

fin_infra/normalization/__init__.py

@@ -116,11 +116,11 @@ def add_normalization(
         - Scoped docs at {prefix}/docs for standalone documentation
     """
     # Import FastAPI dependencies
-    from fastapi import Query, HTTPException
+    from fastapi import HTTPException, Query
+    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
 
     # Import svc-infra public router (no auth - utility endpoints)
     from svc_infra.api.fastapi.dual.public import public_router
-    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
 
     # Get normalization services
     resolver, converter = easy_normalization(api_key=api_key)

fin_infra/normalization/providers/exchangerate.py

@@ -2,7 +2,7 @@
 
 import os
 from datetime import date as DateType
-from typing import Optional, cast
+from typing import cast
 
 import httpx
 
@@ -19,7 +19,7 @@ __all__ = [
 class ExchangeRateClient:
     """Client for exchangerate-api.io API."""
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: str | None = None):
         """
         Initialize exchange rate client.
 
@@ -66,10 +66,10 @@ class ExchangeRateClient:
                         raise ExchangeRateAPIError(
                             f"API returned error: {data.get('error-type', 'unknown')}"
                         )
-                    return cast(dict[str, float], data["conversion_rates"])
+                    return cast("dict[str, float]", data["conversion_rates"])
                 else:
                     # Free tier response format
-                    return cast(dict[str, float], data["rates"])
+                    return cast("dict[str, float]", data["rates"])
 
         except httpx.HTTPError as e:
             raise ExchangeRateAPIError(f"HTTP error fetching rates: {e}")
@@ -77,7 +77,7 @@ class ExchangeRateClient:
             raise ExchangeRateAPIError(f"Invalid API response: {e}")
 
     async def get_rate(
-        self, from_currency: str, to_currency: str, date: Optional[DateType] = None
+        self, from_currency: str, to_currency: str, date: DateType | None = None
     ) -> ExchangeRate:
         """
         Get exchange rate between two currencies.

fin_infra/obs/classifier.py

@@ -37,7 +37,7 @@ Usage:
 
 from __future__ import annotations
 
-from typing import Callable
+from collections.abc import Callable
 
 # Financial capability prefix patterns (extensible)
 FINANCIAL_ROUTE_PREFIXES = (

fin_infra/providers/banking/plaid_client.py

@@ -7,15 +7,15 @@ from typing import Any, cast
 try:
     import plaid
     from plaid.api import plaid_api
+    from plaid.model.accounts_balance_get_request import AccountsBalanceGetRequest
+    from plaid.model.accounts_get_request import AccountsGetRequest
     from plaid.model.country_code import CountryCode
+    from plaid.model.identity_get_request import IdentityGetRequest
     from plaid.model.item_public_token_exchange_request import ItemPublicTokenExchangeRequest
     from plaid.model.link_token_create_request import LinkTokenCreateRequest
     from plaid.model.link_token_create_request_user import LinkTokenCreateRequestUser
     from plaid.model.products import Products
     from plaid.model.transactions_get_request import TransactionsGetRequest
-    from plaid.model.accounts_get_request import AccountsGetRequest
-    from plaid.model.accounts_balance_get_request import AccountsBalanceGetRequest
-    from plaid.model.identity_get_request import IdentityGetRequest
 
     PLAID_AVAILABLE = True
 except Exception:  # pragma: no cover - dynamic import guard
@@ -97,7 +97,7 @@ class PlaidClient(BankingProvider):
             language="en",
         )
         response = self.client.link_token_create(request)
-        return cast(str, response["link_token"])
+        return cast("str", response["link_token"])
 
     def exchange_public_token(self, public_token: str) -> dict:
         request = ItemPublicTokenExchangeRequest(public_token=public_token)
@@ -151,4 +151,4 @@ class PlaidClient(BankingProvider):
         """Fetch identity/account holder information."""
         request = IdentityGetRequest(access_token=access_token)
         response = self.client.identity_get(request)
-        return cast(dict[Any, Any], response.to_dict())
+        return cast("dict[Any, Any]", response.to_dict())

fin_infra/providers/banking/teller_client.py

@@ -23,9 +23,10 @@ Example:
 from __future__ import annotations
 
 import ssl
-import httpx
 from typing import Any, cast
 
+import httpx
+
 from ..base import BankingProvider
 
 
@@ -145,7 +146,7 @@ class TellerClient(BankingProvider):
                 "products": ["accounts", "transactions", "balances", "identity"],
             },
         )
-        return cast(str, response.get("enrollment_id", ""))
+        return cast("str", response.get("enrollment_id", ""))
 
     def exchange_public_token(self, public_token: str) -> dict:
         """Exchange public token for access token.
@@ -192,7 +193,7 @@ class TellerClient(BankingProvider):
             auth=(access_token, ""),
         )
         response.raise_for_status()
-        return cast(list[dict[Any, Any]], response.json())
+        return cast("list[dict[Any, Any]]", response.json())
 
     def transactions(
         self,
@@ -235,7 +236,7 @@ class TellerClient(BankingProvider):
             params=params,
         )
         response.raise_for_status()
-        return cast(list[dict[Any, Any]], response.json())
+        return cast("list[dict[Any, Any]]", response.json())
 
     def balances(self, access_token: str, account_id: str | None = None) -> dict:
         """Fetch current balances.
@@ -267,7 +268,7 @@ class TellerClient(BankingProvider):
             )
 
         response.raise_for_status()
-        return cast(dict[Any, Any], response.json())
+        return cast("dict[Any, Any]", response.json())
 
     def identity(self, access_token: str) -> dict:
         """Fetch identity/account holder information.
@@ -291,7 +292,7 @@ class TellerClient(BankingProvider):
             auth=(access_token, ""),
         )
         response.raise_for_status()
-        return cast(dict[Any, Any], response.json())
+        return cast("dict[Any, Any]", response.json())
 
     def __del__(self) -> None:
         """Close HTTP client on cleanup."""

fin_infra/providers/base.py

@@ -1,9 +1,34 @@
+"""Base provider ABCs for fin-infra.
+
+This module defines abstract base classes for all financial data providers.
+These are the canonical ABCs - use these instead of fin_infra.clients.
+
+Sync vs Async Pattern:
+    Most providers use SYNCHRONOUS methods for simplicity. The exceptions are:
+    - InvestmentProvider: Uses async methods (get_holdings, get_investment_accounts)
+
+    If you need async, wrap sync providers with asyncio.to_thread():
+        import asyncio
+        result = await asyncio.to_thread(provider.quote, "AAPL")
+
+Provider Categories:
+    - MarketDataProvider: Stock/equity quotes and historical data
+    - CryptoDataProvider: Cryptocurrency market data
+    - BankingProvider: Bank account aggregation (Plaid, Teller, MX)
+    - BrokerageProvider: Trading operations (Alpaca, Interactive Brokers)
+    - CreditProvider: Credit scores and reports
+    - TaxProvider: Tax documents and calculations
+    - IdentityProvider: Identity verification
+    - InvestmentProvider: Investment holdings (async)
+"""
+
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Any, Iterable, Sequence
+from collections.abc import Iterable, Sequence
+from typing import Any
 
-from ..models import Quote, Candle
+from ..models import Candle, Quote
 
 
 class MarketDataProvider(ABC):

fin_infra/providers/brokerage/alpaca.py

@@ -314,8 +314,8 @@ class AlpacaBrokerage(BrokerageProvider):
         Alpaca entities have a _raw attribute with the API response data.
         """
         if hasattr(obj, "_raw"):
-            return cast(dict[Any, Any], obj._raw)
+            return cast("dict[Any, Any]", obj._raw)
         elif hasattr(obj, "__dict__"):
-            return cast(dict[Any, Any], obj.__dict__)
+            return cast("dict[Any, Any]", obj.__dict__)
         else:
-            return cast(dict[Any, Any], obj)
+            return cast("dict[Any, Any]", obj)

fin_infra/providers/market/alphavantage.py

@@ -8,16 +8,15 @@ from __future__ import annotations
 
 import os
 import time
-from typing import Sequence
+from collections.abc import Sequence
+from datetime import UTC, datetime
 from decimal import Decimal
-from datetime import datetime, timezone
 
 import httpx
 
-from .base import MarketDataProvider
-from ...models import Quote, Candle
+from ...models import Candle, Quote
 from ...settings import Settings
-
+from .base import MarketDataProvider
 
 _BASE = "https://www.alphavantage.co/query"
 
@@ -128,11 +127,7 @@ class AlphaVantageMarketData(MarketDataProvider):
 
         price = Decimal(str(q.get("05. price", "0")))
         ts = q.get("07. latest trading day")
-        as_of = (
-            datetime.strptime(ts, "%Y-%m-%d").replace(tzinfo=timezone.utc)
-            if ts
-            else datetime.now(timezone.utc)
-        )
+        as_of = datetime.strptime(ts, "%Y-%m-%d").replace(tzinfo=UTC) if ts else datetime.now(UTC)
 
         return Quote(symbol=symbol.upper(), price=price, as_of=as_of)
 
@@ -202,7 +197,7 @@ class AlphaVantageMarketData(MarketDataProvider):
         out: list[Candle] = []
         for d, vals in list(time_series.items())[:limit]:
             try:
-                dt = datetime.strptime(d, "%Y-%m-%d").replace(tzinfo=timezone.utc)
+                dt = datetime.strptime(d, "%Y-%m-%d").replace(tzinfo=UTC)
                 ts_ms = int(dt.timestamp() * 1000)
                 out.append(
                     Candle(

fin_infra/providers/market/ccxt_crypto.py

@@ -2,15 +2,31 @@ from __future__ import annotations
 
 from typing import Any, cast
 
-import ccxt
+try:
+    import ccxt
+
+    HAS_CCXT = True
+except ImportError:  # pragma: no cover
+    HAS_CCXT = False
+    ccxt = None
 
 from ..base import CryptoDataProvider
 
 
+def _require_ccxt() -> None:
+    """Raise ImportError if ccxt is not installed."""
+    if not HAS_CCXT:
+        raise ImportError(
+            "Crypto exchange support requires the 'ccxt' package. "
+            "Install with: pip install fin-infra[crypto] or pip install fin-infra[markets]"
+        )
+
+
 class CCXTCryptoData(CryptoDataProvider):
     """Exchange-agnostic crypto market data using CCXT."""
 
     def __init__(self, exchange: str = "binance") -> None:
+        _require_ccxt()
         if not hasattr(ccxt, exchange):
             raise ValueError(f"Unknown exchange '{exchange}' in ccxt")
         self.exchange = getattr(ccxt, exchange)()
@@ -21,13 +37,13 @@ class CCXTCryptoData(CryptoDataProvider):
         if not self._markets_loaded:
             self.exchange.load_markets()
             self._markets_loaded = True
-        return cast(dict[Any, Any], self.exchange.fetch_ticker(symbol_pair))
+        return cast("dict[Any, Any]", self.exchange.fetch_ticker(symbol_pair))
 
     def ohlcv(self, symbol_pair: str, timeframe: str = "1d", limit: int = 100) -> list[list[float]]:
         if not self._markets_loaded:
             self.exchange.load_markets()
             self._markets_loaded = True
         return cast(
-            list[list[float]],
+            "list[list[float]]",
             self.exchange.fetch_ohlcv(symbol_pair, timeframe=timeframe, limit=limit),
         )

fin_infra/providers/market/coingecko.py

@@ -1,12 +1,13 @@
 from __future__ import annotations
 
 import logging
-import httpx
+from datetime import UTC, datetime
 from decimal import Decimal
-from datetime import datetime, timezone
 
+import httpx
+
+from ...models import Candle, Quote
 from ..base import CryptoDataProvider
-from ...models import Quote, Candle
 
 logger = logging.getLogger(__name__)
 
@@ -30,9 +31,7 @@ class CoinGeckoCryptoData(CryptoDataProvider):
         except Exception as e:
             logger.warning("CoinGecko ticker fetch failed for %s: %s", symbol_pair, e)
             price = 0
-        return Quote(
-            symbol=f"{base}/{quote}", price=Decimal(str(price)), as_of=datetime.now(timezone.utc)
-        )
+        return Quote(symbol=f"{base}/{quote}", price=Decimal(str(price)), as_of=datetime.now(UTC))
 
     def ohlcv(self, symbol_pair: str, timeframe: str = "1d", limit: int = 100) -> list[Candle]:
         # CoinGecko provides market_chart with daily data; map timeframe crudely

fin_infra/providers/market/yahoo.py

@@ -10,14 +10,29 @@ For production, consider Alpha Vantage or other official providers.
 
 from __future__ import annotations
 
-from typing import Sequence
+from collections.abc import Sequence
+from datetime import UTC, datetime
 from decimal import Decimal
-from datetime import datetime, timezone
 
-from yahooquery import Ticker
+try:
+    from yahooquery import Ticker
 
+    HAS_YAHOOQUERY = True
+except ImportError:  # pragma: no cover
+    HAS_YAHOOQUERY = False
+    Ticker = None
+
+from ...models import Candle, Quote
 from .base import MarketDataProvider
-from ...models import Quote, Candle
+
+
+def _require_yahooquery() -> None:
+    """Raise ImportError if yahooquery is not installed."""
+    if not HAS_YAHOOQUERY:
+        raise ImportError(
+            "Yahoo Finance support requires the 'yahooquery' package. "
+            "Install with: pip install fin-infra[yahoo] or pip install fin-infra[markets]"
+        )
 
 
 class YahooFinanceMarketData(MarketDataProvider):
@@ -42,7 +57,7 @@ class YahooFinanceMarketData(MarketDataProvider):
 
     def __init__(self) -> None:
         """Initialize Yahoo Finance provider (no configuration needed)."""
-        pass
+        _require_yahooquery()
 
     def quote(self, symbol: str) -> Quote:
         """Get real-time quote for a symbol.
@@ -78,9 +93,9 @@ class YahooFinanceMarketData(MarketDataProvider):
         ts_raw = data.get("regularMarketTime")
         if ts_raw:
             # Convert Unix timestamp to datetime
-            as_of = datetime.fromtimestamp(ts_raw, tz=timezone.utc)
+            as_of = datetime.fromtimestamp(ts_raw, tz=UTC)
         else:
-            as_of = datetime.now(timezone.utc)
+            as_of = datetime.now(UTC)
 
         return Quote(
             symbol=symbol.upper(),
@@ -135,7 +150,7 @@ class YahooFinanceMarketData(MarketDataProvider):
 
                 # Ensure timezone aware
                 if dt.tzinfo is None:
-                    dt = dt.replace(tzinfo=timezone.utc)
+                    dt = dt.replace(tzinfo=UTC)
 
                 ts_ms = int(dt.timestamp() * 1000)
 

fin_infra/providers/tax/__init__.py

@@ -1,7 +1,7 @@
 """Tax providers package."""
 
-from .mock import MockTaxProvider
 from .irs import IRSProvider
+from .mock import MockTaxProvider
 from .taxbit import TaxBitProvider
 
 __all__ = [

fin_infra/providers/tax/irs.py

@@ -22,8 +22,8 @@ Example:
 from decimal import Decimal
 
 from fin_infra.models.tax import (
-    TaxDocument,
     CryptoTaxReport,
+    TaxDocument,
     TaxLiability,
 )
 from fin_infra.providers.base import TaxProvider

fin_infra/providers/tax/mock.py

@@ -14,14 +14,14 @@ from datetime import date, datetime
 from decimal import Decimal
 
 from fin_infra.models.tax import (
+    CryptoTaxReport,
+    CryptoTransaction,
     TaxDocument,
-    TaxFormW2,
-    TaxForm1099INT,
-    TaxForm1099DIV,
     TaxForm1099B,
+    TaxForm1099DIV,
+    TaxForm1099INT,
     TaxForm1099MISC,
-    CryptoTransaction,
-    CryptoTaxReport,
+    TaxFormW2,
     TaxLiability,
 )
 from fin_infra.providers.base import TaxProvider

fin_infra/providers/tax/taxbit.py

@@ -21,8 +21,8 @@ Example:
 from decimal import Decimal
 
 from fin_infra.models.tax import (
-    TaxDocument,
     CryptoTaxReport,
+    TaxDocument,
     TaxLiability,
 )
 from fin_infra.providers.base import TaxProvider

fin_infra/recurring/__init__.py

@@ -46,18 +46,18 @@ from .models import (
     SubscriptionDetection,
     SubscriptionStats,
 )
-from .summary import (
-    CancellationOpportunity,
-    RecurringItem,
-    RecurringSummary,
-    get_recurring_summary,
-)
 from .normalizer import (
     FuzzyMatcher,
     get_canonical_merchant,
     is_generic_merchant,
     normalize_merchant,
 )
+from .summary import (
+    CancellationOpportunity,
+    RecurringItem,
+    RecurringSummary,
+    get_recurring_summary,
+)
 
 __all__ = [
     # Easy builders

fin_infra/recurring/add.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 import time
 from datetime import datetime, timedelta
-from typing import TYPE_CHECKING, Any, Optional
+from typing import TYPE_CHECKING, Any
 
 from .ease import easy_recurring_detection
 from .models import (
@@ -24,6 +24,7 @@ from .models import (
 
 if TYPE_CHECKING:
     from fastapi import FastAPI
+
     from .detector import RecurringDetector
 
 
@@ -35,9 +36,9 @@ def add_recurring_detection(
     date_tolerance_days: int = 7,
     enable_llm: bool = False,
     llm_provider: str = "google",
-    llm_model: Optional[str] = None,
+    llm_model: str | None = None,
     include_in_schema: bool = True,
-) -> "RecurringDetector":
+) -> RecurringDetector:
     """
     Add recurring transaction detection endpoints to FastAPI app.
 
@@ -242,7 +243,7 @@ def add_recurring_detection(
     @router.get("/summary")
     async def get_recurring_summary(
         user_id: str,
-        category_map: Optional[dict[str, str]] = None,
+        category_map: dict[str, str] | None = None,
     ):
         """
         Get comprehensive recurring transaction summary.

fin_infra/recurring/detector.py

@@ -17,15 +17,15 @@ from __future__ import annotations
 import statistics
 from collections import defaultdict
 from datetime import datetime, timedelta
-from typing import Any, Optional, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from .models import CadenceType, PatternType, RecurringPattern
 from .normalizer import get_canonical_merchant, is_generic_merchant
 
 if TYPE_CHECKING:
-    from .normalizers import MerchantNormalizer
     from .detectors_llm import VariableDetectorLLM
     from .insights import SubscriptionInsightsGenerator
+    from .normalizers import MerchantNormalizer
 
 
 class Transaction:
@@ -59,8 +59,8 @@ class PatternDetector:
         min_occurrences: int = 3,
         amount_tolerance: float = 0.02,
         date_tolerance_days: int = 7,
-        merchant_normalizer: Optional[MerchantNormalizer] = None,
-        variable_detector_llm: Optional[VariableDetectorLLM] = None,
+        merchant_normalizer: MerchantNormalizer | None = None,
+        variable_detector_llm: VariableDetectorLLM | None = None,
     ):
         """
         Initialize pattern detector.
@@ -512,9 +512,9 @@ class RecurringDetector:
         min_occurrences: int = 3,
         amount_tolerance: float = 0.02,
         date_tolerance_days: int = 7,
-        merchant_normalizer: Optional[MerchantNormalizer] = None,
-        variable_detector_llm: Optional[VariableDetectorLLM] = None,
-        insights_generator: Optional[SubscriptionInsightsGenerator] = None,
+        merchant_normalizer: MerchantNormalizer | None = None,
+        variable_detector_llm: VariableDetectorLLM | None = None,
+        insights_generator: SubscriptionInsightsGenerator | None = None,
     ):
         """
         Initialize recurring detector.

fin_infra/recurring/detectors_llm.py

@@ -14,7 +14,7 @@ Only called for ambiguous patterns (20-40% variance, ~10% of patterns).
 from __future__ import annotations
 
 import logging
-from typing import Any, Optional, cast
+from typing import Any, cast
 
 from pydantic import BaseModel, ConfigDict, Field
 
@@ -41,14 +41,14 @@ class VariableRecurringPattern(BaseModel):
         ...,
         description="True if pattern is recurring despite variance",
     )
-    cadence: Optional[str] = Field(
+    cadence: str | None = Field(
         None,
         description=(
             "Frequency if recurring: monthly, bi-weekly, quarterly, annual, etc. "
             "None if not recurring."
         ),
     )
-    expected_range: Optional[tuple[float, float]] = Field(
+    expected_range: tuple[float, float] | None = Field(
         None,
         description=(
             "Expected amount range (min, max) if recurring. "
@@ -100,7 +100,7 @@ Examples:
 1. Merchant: "City Electric"
    Amounts: [$45, $52, $48, $55, $50, $49]
    Dates: Monthly (15th ±7 days)
-   → is_recurring: true, cadence: "monthly", range: (40, 60), 
+   → is_recurring: true, cadence: "monthly", range: (40, 60),
      reasoning: "Seasonal winter heating variation", confidence: 0.85
 
 2. Merchant: "T-Mobile"
@@ -164,7 +164,7 @@ class VariableDetectorLLM:
     def __init__(
         self,
         provider: str = "google",
-        model_name: Optional[str] = None,
+        model_name: str | None = None,
         max_cost_per_day: float = 0.10,
         max_cost_per_month: float = 2.00,
     ):
@@ -293,7 +293,7 @@ class VariableDetectorLLM:
 
         # Extract structured output
         if hasattr(response, "structured") and response.structured:
-            return cast(VariableRecurringPattern, response.structured)
+            return cast("VariableRecurringPattern", response.structured)
         else:
             raise ValueError(f"LLM returned no structured output for '{merchant_name}'")
 

fin_infra/recurring/ease.py

@@ -9,8 +9,6 @@ variable amount detection, and natural language insights.
 
 from __future__ import annotations
 
-from typing import Optional
-
 from .detector import RecurringDetector
 
 
@@ -20,7 +18,7 @@ def easy_recurring_detection(
     date_tolerance_days: int = 7,
     enable_llm: bool = False,
     llm_provider: str = "google",
-    llm_model: Optional[str] = None,
+    llm_model: str | None = None,
     llm_confidence_threshold: float = 0.8,
     llm_cache_merchant_ttl: int = 604800,  # 7 days
     llm_cache_insights_ttl: int = 86400,  # 24 hours
@@ -216,9 +214,9 @@ def easy_recurring_detection(
     if enable_llm:
         # Import V2 components only if needed (avoid circular imports)
         try:
-            from .normalizers import MerchantNormalizer
             from .detectors_llm import VariableDetectorLLM
             from .insights import SubscriptionInsightsGenerator
+            from .normalizers import MerchantNormalizer
         except ImportError as e:
             raise ImportError(
                 f"LLM components not available. Install ai-infra: pip install ai-infra. Error: {e}"