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

fin_infra/providers/banking/plaid_client.py

@@ -1,20 +1,21 @@
 from __future__ import annotations
 
 from datetime import date, datetime, timedelta
+from typing import Any, cast
 
 # Plaid SDK v25+ uses new API structure
 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
@@ -33,7 +34,7 @@ class PlaidClient(BankingProvider):
         environment: str | None = None,
     ) -> None:
         """Initialize Plaid client with either Settings object or individual parameters.
-        
+
         Args:
             settings: Settings object (legacy pattern)
             client_id: Plaid client ID (preferred - from env or passed directly)
@@ -44,14 +45,14 @@ class PlaidClient(BankingProvider):
             raise RuntimeError(
                 "plaid-python SDK not available or import failed; check installed version (requires v25+)"
             )
-        
+
         # Support both patterns: Settings object or individual params
         if settings is not None:
             # Legacy pattern with Settings object
             client_id = client_id or settings.plaid_client_id
             secret = secret or settings.plaid_secret
             environment = environment or settings.plaid_env
-        
+
         # Map environment string to Plaid Environment enum
         # Note: Plaid only has Sandbox and Production (no Development in SDK)
         env_str = environment or "sandbox"
@@ -60,22 +61,22 @@ class PlaidClient(BankingProvider):
             "development": plaid.Environment.Sandbox,  # Map development to sandbox (Plaid SDK limitation)
             "production": plaid.Environment.Production,
         }
-        
+
         if env_str not in env_map:
             raise ValueError(
                 f"Invalid Plaid environment: '{env_str}'. "
                 f"Must be one of: sandbox, development, production"
             )
-        
+
         host = env_map[env_str]
-        
+
         # Configure Plaid client (v8.0.0+ API)
         configuration = plaid.Configuration(
             host=host,
             api_key={
                 "clientId": client_id,
                 "secret": secret,
-            }
+            },
         )
         api_client = plaid.ApiClient(configuration)
         self.client = plaid_api.PlaidApi(api_client)
@@ -85,18 +86,18 @@ class PlaidClient(BankingProvider):
             user=LinkTokenCreateRequestUser(client_user_id=user_id),
             client_name="fin-infra",
             products=[
-                Products("auth"),           # Account/routing numbers for ACH
-                Products("transactions"),   # Transaction history
-                Products("liabilities"),    # Credit cards, loans, student loans
-                Products("investments"),    # Brokerage, retirement accounts
-                Products("assets"),         # Asset reports for lending/verification
-                Products("identity"),       # Account holder info (name, email, phone)
+                Products("auth"),  # Account/routing numbers for ACH
+                Products("transactions"),  # Transaction history
+                Products("liabilities"),  # Credit cards, loans, student loans
+                Products("investments"),  # Brokerage, retirement accounts
+                Products("assets"),  # Asset reports for lending/verification
+                Products("identity"),  # Account holder info (name, email, phone)
             ],
             country_codes=[CountryCode("US")],
             language="en",
         )
         response = self.client.link_token_create(request)
-        return response["link_token"]
+        return cast("str", response["link_token"])
 
     def exchange_public_token(self, public_token: str) -> dict:
         request = ItemPublicTokenExchangeRequest(public_token=public_token)
@@ -121,7 +122,7 @@ class PlaidClient(BankingProvider):
             start = end - timedelta(days=30)
             start_date = start_date or start.isoformat()
             end_date = end_date or end.isoformat()
-        
+
         request = TransactionsGetRequest(
             access_token=access_token,
             start_date=date.fromisoformat(start_date),
@@ -135,19 +136,19 @@ class PlaidClient(BankingProvider):
         request = AccountsBalanceGetRequest(access_token=access_token)
         response = self.client.accounts_balance_get(request)
         accounts = [acc.to_dict() for acc in response["accounts"]]
-        
+
         if account_id:
             # Filter to specific account
             for account in accounts:
                 if account.get("account_id") == account_id:
                     return {"balances": [account.get("balances", {})]}
             return {"balances": []}
-        
+
         # Return all balances
         return {"balances": [acc.get("balances", {}) for acc in accounts]}
 
-    def identity(self, access_token: str) -> dict:
+    def identity(self, access_token: str) -> dict[Any, Any]:
         """Fetch identity/account holder information."""
         request = IdentityGetRequest(access_token=access_token)
         response = self.client.identity_get(request)
-        return response.to_dict()
+        return cast("dict[Any, Any]", response.to_dict())

fin_infra/providers/banking/teller_client.py

@@ -23,8 +23,9 @@ Example:
 from __future__ import annotations
 
 import ssl
+from typing import Any, cast
+
 import httpx
-from typing import Any
 
 from ..base import BankingProvider
 
@@ -93,7 +94,13 @@ class TellerClient(BankingProvider):
             ssl_context.load_cert_chain(certfile=cert_path, keyfile=key_path)
             client_kwargs["verify"] = ssl_context
 
-        self.client = httpx.Client(**client_kwargs)
+        # Create client with explicit parameters to satisfy type checker
+        self.client = httpx.Client(
+            base_url=str(client_kwargs["base_url"]),
+            timeout=float(client_kwargs["timeout"]),  # type: ignore[arg-type]
+            headers=client_kwargs["headers"],  # type: ignore[arg-type]
+            verify=client_kwargs.get("verify", True),  # type: ignore[arg-type]
+        )
 
     def _request(self, method: str, path: str, **kwargs: Any) -> Any:
         """Make HTTP request to Teller API with error handling.
@@ -139,7 +146,7 @@ class TellerClient(BankingProvider):
                 "products": ["accounts", "transactions", "balances", "identity"],
             },
         )
-        return 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.
@@ -186,7 +193,7 @@ class TellerClient(BankingProvider):
             auth=(access_token, ""),
         )
         response.raise_for_status()
-        return response.json()
+        return cast("list[dict[Any, Any]]", response.json())
 
     def transactions(
         self,
@@ -229,7 +236,7 @@ class TellerClient(BankingProvider):
             params=params,
         )
         response.raise_for_status()
-        return 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.
@@ -261,7 +268,7 @@ class TellerClient(BankingProvider):
             )
 
         response.raise_for_status()
-        return response.json()
+        return cast("dict[Any, Any]", response.json())
 
     def identity(self, access_token: str) -> dict:
         """Fetch identity/account holder information.
@@ -285,7 +292,7 @@ class TellerClient(BankingProvider):
             auth=(access_token, ""),
         )
         response.raise_for_status()
-        return 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 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):
@@ -20,11 +45,11 @@ class MarketDataProvider(ABC):
 
 class CryptoDataProvider(ABC):
     @abstractmethod
-    def ticker(self, symbol_pair: str) -> Quote:
+    def ticker(self, symbol_pair: str) -> Any:
         pass
 
     @abstractmethod
-    def ohlcv(self, symbol_pair: str, timeframe: str = "1d", limit: int = 100) -> Sequence[Candle]:
+    def ohlcv(self, symbol_pair: str, timeframe: str = "1d", limit: int = 100) -> Any:
         pass
 
 
@@ -67,7 +92,15 @@ class BankingProvider(ABC):
 class BrokerageProvider(ABC):
     @abstractmethod
     def submit_order(
-        self, symbol: str, qty: float, side: str, type_: str, time_in_force: str
+        self,
+        symbol: str,
+        qty: float,
+        side: str,
+        type_: str,
+        time_in_force: str,
+        limit_price: float | None = None,
+        stop_price: float | None = None,
+        client_order_id: str | None = None,
     ) -> dict:
         pass
 
@@ -75,6 +108,71 @@ class BrokerageProvider(ABC):
     def positions(self) -> Iterable[dict]:
         pass
 
+    @abstractmethod
+    def get_account(self) -> dict:
+        """Get trading account information."""
+        pass
+
+    @abstractmethod
+    def get_position(self, symbol: str) -> dict:
+        """Get position for a specific symbol."""
+        pass
+
+    @abstractmethod
+    def close_position(self, symbol: str) -> dict:
+        """Close a position (market sell/cover)."""
+        pass
+
+    @abstractmethod
+    def list_orders(self, status: str = "open", limit: int = 50) -> list[dict]:
+        """List orders."""
+        pass
+
+    @abstractmethod
+    def get_order(self, order_id: str) -> dict:
+        """Get order by ID."""
+        pass
+
+    @abstractmethod
+    def cancel_order(self, order_id: str) -> None:
+        """Cancel an order."""
+        pass
+
+    @abstractmethod
+    def get_portfolio_history(self, period: str = "1M", timeframe: str = "1D") -> dict:
+        """Get portfolio value history."""
+        pass
+
+    @abstractmethod
+    def create_watchlist(self, name: str, symbols: list[str] | None = None) -> dict:
+        """Create a new watchlist."""
+        pass
+
+    @abstractmethod
+    def list_watchlists(self) -> list[dict]:
+        """List all watchlists."""
+        pass
+
+    @abstractmethod
+    def get_watchlist(self, watchlist_id: str) -> dict:
+        """Get a watchlist by ID."""
+        pass
+
+    @abstractmethod
+    def delete_watchlist(self, watchlist_id: str) -> None:
+        """Delete a watchlist."""
+        pass
+
+    @abstractmethod
+    def add_to_watchlist(self, watchlist_id: str, symbol: str) -> dict:
+        """Add a symbol to a watchlist."""
+        pass
+
+    @abstractmethod
+    def remove_from_watchlist(self, watchlist_id: str, symbol: str) -> dict:
+        """Remove a symbol from a watchlist."""
+        pass
+
 
 class IdentityProvider(ABC):
     @abstractmethod
@@ -88,7 +186,12 @@ class IdentityProvider(ABC):
 
 class CreditProvider(ABC):
     @abstractmethod
-    def get_credit_score(self, user_id: str, **kwargs) -> dict | None:
+    def get_credit_score(self, user_id: str, **kwargs: Any) -> Any:
+        pass
+
+    @abstractmethod
+    def get_credit_report(self, user_id: str, **kwargs: Any) -> Any:
+        """Retrieve full credit report for a user."""
         pass
 
 
@@ -96,44 +199,58 @@ class TaxProvider(ABC):
     """Provider for tax data and document retrieval."""
 
     @abstractmethod
-    def get_tax_forms(self, user_id: str, tax_year: int, **kwargs) -> list[dict]:
+    def get_tax_forms(self, user_id: str, tax_year: int, **kwargs: Any) -> Any:
         """Retrieve tax forms for a user and tax year."""
         pass
 
     @abstractmethod
-    def get_tax_document(self, document_id: str, **kwargs) -> dict:
+    def get_tax_documents(self, user_id: str, tax_year: int, **kwargs: Any) -> Any:
+        """Retrieve tax documents for a user and tax year."""
+        pass
+
+    @abstractmethod
+    def get_tax_document(self, document_id: str, **kwargs: Any) -> Any:
         """Retrieve a specific tax document by ID."""
         pass
 
     @abstractmethod
-    def calculate_crypto_gains(self, transactions: list[dict], **kwargs) -> dict:
+    def calculate_crypto_gains(self, *args: Any, **kwargs: Any) -> Any:
         """Calculate capital gains from crypto transactions."""
         pass
 
+    @abstractmethod
+    def calculate_tax_liability(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """Calculate estimated tax liability."""
+        pass
+
 
 class InvestmentProvider(ABC):
     """Provider for investment holdings and portfolio data (Plaid, SnapTrade).
-    
+
     This is a minimal ABC for type checking. The full implementation with
     all abstract methods is in fin_infra.investments.providers.base.InvestmentProvider.
-    
+
     Abstract Methods (defined in full implementation):
         - get_holdings(access_token, account_ids) -> List[Holding]
         - get_transactions(access_token, start_date, end_date, account_ids) -> List[InvestmentTransaction]
         - get_securities(access_token, security_ids) -> List[Security]
         - get_investment_accounts(access_token) -> List[InvestmentAccount]
-    
+
     Example:
         >>> from fin_infra.investments import easy_investments
         >>> provider = easy_investments(provider="plaid")
         >>> holdings = await provider.get_holdings(access_token)
     """
-    
+
     @abstractmethod
     async def get_holdings(self, access_token: str, account_ids: list[str] | None = None) -> list:
         """Fetch holdings for investment accounts."""
         pass
-    
+
     @abstractmethod
     async def get_investment_accounts(self, access_token: str) -> list:
         """Fetch investment accounts with aggregated holdings."""

fin_infra/providers/brokerage/alpaca.py

@@ -7,7 +7,7 @@ mode for development and testing. Live trading requires explicit opt-in.
 from __future__ import annotations
 
 import os
-from typing import Literal
+from typing import Any, Literal, cast
 
 try:
     from alpaca_trade_api import REST
@@ -55,8 +55,7 @@ class AlpacaBrokerage(BrokerageProvider):
     ) -> None:
         if not ALPACA_AVAILABLE:
             raise ImportError(
-                "alpaca-trade-api is not installed. "
-                "Install it with: pip install alpaca-trade-api"
+                "alpaca-trade-api is not installed. Install it with: pip install alpaca-trade-api"
             )
 
         # Get credentials from args or environment
@@ -128,6 +127,7 @@ class AlpacaBrokerage(BrokerageProvider):
         # Without this, network retries can cause duplicate order execution = MONEY LOSS.
         if client_order_id is None:
             import uuid
+
             client_order_id = str(uuid.uuid4())
 
         order = self.client.submit_order(
@@ -308,14 +308,14 @@ class AlpacaBrokerage(BrokerageProvider):
         return self._extract_raw(watchlist)
 
     @staticmethod
-    def _extract_raw(obj) -> dict:
+    def _extract_raw(obj: Any) -> dict[Any, Any]:
         """Extract raw dict from Alpaca entity object.
 
         Alpaca entities have a _raw attribute with the API response data.
         """
         if hasattr(obj, "_raw"):
-            return obj._raw
+            return cast("dict[Any, Any]", obj._raw)
         elif hasattr(obj, "__dict__"):
-            return obj.__dict__
+            return cast("dict[Any, Any]", obj.__dict__)
         else:
-            return obj
+            return cast("dict[Any, Any]", obj)

fin_infra/providers/credit/experian.py

@@ -11,3 +11,8 @@ class ExperianCredit(CreditProvider):
         self, user_id: str, **kwargs
     ) -> dict | None:  # pragma: no cover - placeholder
         return None
+
+    def get_credit_report(
+        self, user_id: str, **kwargs
+    ) -> dict | None:  # pragma: no cover - placeholder
+        return None

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

@@ -1,28 +1,49 @@
 from __future__ import annotations
 
-import ccxt
+from typing import Any, cast
+
+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)()
         # Defer load_markets to first call to avoid network on construction
         self._markets_loaded = False
 
-    def ticker(self, symbol_pair: str) -> dict:
+    def ticker(self, symbol_pair: str) -> dict[Any, Any]:
         if not self._markets_loaded:
             self.exchange.load_markets()
             self._markets_loaded = True
-        return 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 self.exchange.fetch_ohlcv(symbol_pair, timeframe=timeframe, limit=limit)
+        return cast(
+            "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__ = [