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

fin_infra/providers/base.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from abc import ABC, abstractmethod
-from typing import Iterable, Sequence
+from typing import Any, Iterable, Sequence
 
 from ..models import Quote, Candle
 
@@ -20,11 +20,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 +67,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 +83,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 +161,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 +174,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/ccxt_crypto.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from typing import Any, cast
+
 import ccxt
 
 from ..base import CryptoDataProvider
@@ -15,14 +17,17 @@ class CCXTCryptoData(CryptoDataProvider):
         # 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/tax/mock.py

@@ -313,9 +313,9 @@ class MockTaxProvider(TaxProvider):
         return CryptoTaxReport(
             user_id=user_id,
             tax_year=tax_year,
-            total_gain_loss=short_term + long_term,
-            short_term_gain_loss=short_term,
-            long_term_gain_loss=long_term,
+            total_gain_loss=Decimal(short_term + long_term),
+            short_term_gain_loss=Decimal(short_term),
+            long_term_gain_loss=Decimal(long_term),
             transaction_count=len(crypto_transactions),
             cost_basis_method=cost_basis_method,
             transactions=crypto_transactions,

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, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
 from .ease import easy_recurring_detection
 from .models import (
@@ -93,7 +93,7 @@ def add_recurring_detection(
         llm_model=llm_model,
     )
 
-        # Store on app.state
+    # Store on app.state
     app.state.recurring_detector = detector
 
     # Use svc-infra user_router for authentication (recurring detection is user-specific)
@@ -133,7 +133,7 @@ def add_recurring_detection(
         # For now, return empty result with structure.
         # In production: transactions = get_user_transactions(user.id, days=request.days)
 
-        transactions = []  # Placeholder
+        transactions: list[dict[str, Any]] = []  # Placeholder
 
         # Detect patterns
         patterns = detector.detect_patterns(transactions)
@@ -180,7 +180,7 @@ def add_recurring_detection(
         #     return cached
 
         # Detect patterns (same as /detect endpoint)
-        transactions = []  # Placeholder
+        transactions: list[dict[str, Any]] = []  # Placeholder
         patterns = detector.detect_patterns(transactions)
         patterns = [p for p in patterns if p.confidence >= min_confidence]
 
@@ -208,7 +208,7 @@ def add_recurring_detection(
         List of predicted charges with expected dates and amounts
         """
         # Get detected patterns
-        transactions = []  # Placeholder
+        transactions: list[dict[str, Any]] = []  # Placeholder
         patterns = detector.detect_patterns(transactions)
         patterns = [p for p in patterns if p.confidence >= min_confidence]
 
@@ -230,7 +230,7 @@ def add_recurring_detection(
         - Top merchants by amount
         """
         # Get all detected patterns
-        transactions = []  # Placeholder
+        transactions: list[dict[str, Any]] = []  # Placeholder
         patterns = detector.detect_patterns(transactions)
 
         # Calculate stats
@@ -321,7 +321,9 @@ def add_recurring_detection(
         from .summary import get_recurring_summary
 
         # Get detected patterns for user
-        transactions = []  # Placeholder - in production: get_user_transactions(user_id)
+        transactions: list[
+            dict[str, Any]
+        ] = []  # Placeholder - in production: get_user_transactions(user_id)
         patterns = detector.detect_patterns(transactions)
 
         # Generate summary
@@ -375,7 +377,7 @@ def add_recurring_detection(
             **Cost:** ~$0.0002/generation with Google Gemini, <$0.00004 effective with caching
             """
             # Get detected patterns
-            transactions = []  # Placeholder
+            transactions: list[dict[str, Any]] = []  # Placeholder
             patterns = detector.detect_patterns(transactions)
 
             # Convert patterns to subscription dicts for LLM
@@ -403,7 +405,16 @@ def add_recurring_detection(
 
             # Generate insights with LLM
             # TODO: Pass user_id for better caching (currently uses subscriptions hash)
-            insights = await detector.insights_generator.generate(subscriptions)
+            insights_generator = detector.insights_generator
+            if insights_generator is None:
+                from fastapi import HTTPException
+
+                raise HTTPException(
+                    status_code=500,
+                    detail="Subscription insights generator not configured (enable_llm=True required).",
+                )
+
+            insights = await insights_generator.generate(subscriptions)
 
             return insights
     else:

fin_infra/recurring/detector.py

@@ -450,7 +450,7 @@ class PatternDetector:
             min_amt, max_amt = pattern.amount_range or (0, 0)
             return (
                 f"Variable amount ${min_amt:.2f}-${max_amt:.2f} charged {pattern.cadence.value} "
-                f"({pattern.amount_variance_pct*100:.1f}% variance, "
+                f"({pattern.amount_variance_pct * 100:.1f}% variance, "
                 f"{pattern.occurrence_count} occurrences)"
             )
         else:  # IRREGULAR

fin_infra/recurring/detectors_llm.py

@@ -14,15 +14,18 @@ Only called for ambiguous patterns (20-40% variance, ~10% of patterns).
 from __future__ import annotations
 
 import logging
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from pydantic import BaseModel, ConfigDict, Field
 
 # Lazy import for optional dependency (ai-infra)
 try:
     from ai_infra.llm import LLM
+
+    LLM_AVAILABLE = True
 except ImportError:
-    LLM = None
+    LLM = None  # type: ignore[misc,assignment]
+    LLM_AVAILABLE = False
 
 logger = logging.getLogger(__name__)
 
@@ -73,7 +76,7 @@ class VariableRecurringPattern(BaseModel):
             "example": {
                 "is_recurring": True,
                 "cadence": "monthly",
-                "expected_range": (45.0, 60.0),
+                "expected_range": [45.0, 60.0],
                 "reasoning": "Seasonal winter heating causes variance",
                 "confidence": 0.85,
             }
@@ -278,12 +281,10 @@ class VariableDetectorLLM:
         )
 
         response = await self.llm.achat(
+            user_msg=user_prompt,
             provider=self.provider,
-            model=self.model_name,
-            messages=[
-                {"role": "system", "content": VARIABLE_DETECTION_SYSTEM_PROMPT},
-                {"role": "user", "content": user_prompt},
-            ],
+            model_name=self.model_name,
+            system=VARIABLE_DETECTION_SYSTEM_PROMPT,
             output_schema=VariableRecurringPattern,
             output_method="prompt",  # Cross-provider compatibility
             temperature=0.0,  # Deterministic
@@ -292,7 +293,7 @@ class VariableDetectorLLM:
 
         # Extract structured output
         if hasattr(response, "structured") and response.structured:
-            return response.structured
+            return cast(VariableRecurringPattern, response.structured)
         else:
             raise ValueError(f"LLM returned no structured output for '{merchant_name}'")
 

fin_infra/recurring/ease.py

@@ -200,7 +200,7 @@ def easy_recurring_detection(
         )
 
     # Validate config keys (reserved for future use)
-    valid_config_keys = set()  # Will expand in future versions
+    valid_config_keys: set[str] = set()  # Will expand in future versions
     invalid_keys = set(config.keys()) - valid_config_keys
     if invalid_keys:
         raise ValueError(

fin_infra/recurring/insights.py

@@ -15,15 +15,18 @@ from __future__ import annotations
 
 import hashlib
 import logging
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from pydantic import BaseModel, ConfigDict, Field
 
 # Lazy import for optional dependency (ai-infra)
 try:
     from ai_infra.llm import LLM
+
+    LLM_AVAILABLE = True
 except ImportError:
-    LLM = None
+    LLM = None  # type: ignore[misc,assignment]
+    LLM_AVAILABLE = False
 
 logger = logging.getLogger(__name__)
 
@@ -369,12 +372,10 @@ class SubscriptionInsightsGenerator:
         user_prompt = INSIGHTS_GENERATION_USER_PROMPT.format(subscriptions_json=subscriptions_json)
 
         response = await self.llm.achat(
+            user_msg=user_prompt,
             provider=self.provider,
-            model=self.model_name,
-            messages=[
-                {"role": "system", "content": INSIGHTS_GENERATION_SYSTEM_PROMPT},
-                {"role": "user", "content": user_prompt},
-            ],
+            model_name=self.model_name,
+            system=INSIGHTS_GENERATION_SYSTEM_PROMPT,
             output_schema=SubscriptionInsights,
             output_method="prompt",  # Cross-provider compatibility
             temperature=0.3,  # Slight creativity for recommendations
@@ -383,7 +384,7 @@ class SubscriptionInsightsGenerator:
 
         # Extract structured output
         if hasattr(response, "structured") and response.structured:
-            return response.structured
+            return cast(SubscriptionInsights, response.structured)
         else:
             raise ValueError("LLM returned no structured output for insights")
 

fin_infra/recurring/models.py

@@ -228,9 +228,9 @@ class SubscriptionStats(BaseModel):
                 "by_pattern_type": {"fixed": 12, "variable": 2, "irregular": 1},
                 "by_cadence": {"monthly": 13, "quarterly": 1, "annual": 1},
                 "top_merchants": [
-                    ("Netflix", 15.99),
-                    ("Spotify", 9.99),
-                    ("Amazon Prime", 14.99),
+                    ["Netflix", 15.99],
+                    ["Spotify", 9.99],
+                    ["Amazon Prime", 14.99],
                 ],
                 "confidence_distribution": {
                     "high (0.85-1.0)": 12,

fin_infra/recurring/normalizer.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 
 import re
 from functools import lru_cache
+from typing import cast
 
 try:
     from rapidfuzz import fuzz, process
@@ -95,7 +96,7 @@ class FuzzyMatcher:
         """
         if not RAPIDFUZZ_AVAILABLE:
             raise ImportError(
-                "rapidfuzz is required for fuzzy matching. " "Install with: pip install rapidfuzz"
+                "rapidfuzz is required for fuzzy matching. Install with: pip install rapidfuzz"
             )
         self.similarity_threshold = similarity_threshold
 
@@ -165,7 +166,7 @@ class FuzzyMatcher:
         norm2 = normalize_merchant(name2)
 
         similarity = fuzz.token_sort_ratio(norm1, norm2)
-        return similarity >= self.similarity_threshold
+        return cast(bool, similarity >= self.similarity_threshold)
 
     def group_merchants(self, merchants: list[str]) -> dict[str, list[str]]:
         """

fin_infra/recurring/normalizers.py

@@ -16,15 +16,18 @@ from __future__ import annotations
 
 import hashlib
 import logging
-from typing import Any, Optional
+from typing import Any, Optional, cast
 
 from pydantic import BaseModel, ConfigDict, Field
 
 # Lazy import for optional dependency (ai-infra)
 try:
     from ai_infra.llm import LLM
+
+    LLM_AVAILABLE = True
 except ImportError:
-    LLM = None
+    LLM = None  # type: ignore[misc,assignment]
+    LLM_AVAILABLE = False
 
 logger = logging.getLogger(__name__)
 
@@ -340,12 +343,10 @@ class MerchantNormalizer:
         user_prompt = MERCHANT_NORMALIZATION_USER_PROMPT.format(merchant_name=merchant_name)
 
         response = await self.llm.achat(
+            user_msg=user_prompt,
             provider=self.provider,
-            model=self.model_name,
-            messages=[
-                {"role": "system", "content": MERCHANT_NORMALIZATION_SYSTEM_PROMPT},
-                {"role": "user", "content": user_prompt},
-            ],
+            model_name=self.model_name,
+            system=MERCHANT_NORMALIZATION_SYSTEM_PROMPT,
             output_schema=MerchantNormalized,
             output_method="prompt",  # Cross-provider compatibility
             temperature=0.0,  # Deterministic
@@ -354,7 +355,7 @@ class MerchantNormalizer:
 
         # Extract structured output
         if hasattr(response, "structured") and response.structured:
-            return response.structured
+            return cast(MerchantNormalized, response.structured)
         else:
             raise ValueError(f"LLM returned no structured output for '{merchant_name}'")
 

fin_infra/scaffold/__init__.py

@@ -12,7 +12,7 @@ Typical usage:
         include_tenant=True,
         include_soft_delete=True,
     )
-    
+
     result = scaffold_goals_core(
         dest_dir=Path("app/models/goals"),
         include_tenant=False,

fin_infra/security/encryption.py

@@ -7,7 +7,7 @@ Encrypt/decrypt financial provider API tokens at rest.
 import base64
 import json
 import os
-from typing import Any, Dict, Optional
+from typing import Any, Dict, Optional, cast
 
 from cryptography.fernet import Fernet, InvalidToken
 
@@ -144,7 +144,7 @@ class ProviderTokenEncryption:
                         "Token may have been tampered with or used for wrong user/provider."
                     )
 
-            return data["token"]
+            return cast(str, data["token"])
 
         except InvalidToken as e:
             raise ValueError(

fin_infra/security/pii_patterns.py

@@ -67,7 +67,7 @@ def luhn_checksum(card_number: str) -> bool:
         True if valid, False otherwise
     """
 
-    def digits_of(n):
+    def digits_of(n: int | str) -> list[int]:
         return [int(d) for d in str(n)]
 
     digits = digits_of(card_number)

fin_infra/security/token_store.py

@@ -162,7 +162,9 @@ async def get_provider_token(
 
     # Decrypt token
     context = {"user_id": user_id, "provider": provider}
-    token = encryption.decrypt(token_obj.encrypted_token, context=context)
+    # Cast to str since SQLAlchemy Column[str] needs explicit conversion for type checker
+    encrypted_token_str: str = str(token_obj.encrypted_token)
+    token = encryption.decrypt(encrypted_token_str, context=context)
 
     # Update last_used_at
     update_stmt = (

fin_infra/tax/__init__.py

@@ -144,7 +144,7 @@ def easy_tax(provider: str | TaxProvider = "mock", **config) -> TaxProvider:
 
     else:
         raise ValueError(
-            f"Unknown tax provider: {provider}. " f"Supported providers: 'mock', 'irs', 'taxbit'"
+            f"Unknown tax provider: {provider}. Supported providers: 'mock', 'irs', 'taxbit'"
         )
 
 

fin_infra/utils/http.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import httpx
+from typing import Any, cast
 from tenacity import retry, stop_after_attempt, wait_exponential, retry_if_exception_type
 
 _DEFAULT_TIMEOUT = httpx.Timeout(20.0)
@@ -12,8 +13,8 @@ _DEFAULT_TIMEOUT = httpx.Timeout(20.0)
     retry=retry_if_exception_type(httpx.HTTPError),
     reraise=True,
 )
-async def aget_json(url: str, **kwargs) -> dict:
+async def aget_json(url: str, **kwargs) -> dict[Any, Any]:
     async with httpx.AsyncClient(timeout=_DEFAULT_TIMEOUT) as client:
         r = await client.get(url, **kwargs)
         r.raise_for_status()
-        return r.json()
+        return cast(dict[Any, Any], r.json())