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

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
@@ -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/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, 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.
 
@@ -93,7 +94,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 +134,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 +181,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 +209,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 +231,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
@@ -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.
@@ -321,7 +322,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 +378,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 +406,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

@@ -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.
@@ -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
@@ -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,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, 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__)
 
@@ -38,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. "
@@ -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,
             }
@@ -97,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"
@@ -161,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,
     ):
@@ -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

@@ -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
@@ -200,7 +198,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(
@@ -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}"

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, 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__)
 
@@ -58,7 +61,7 @@ class SubscriptionInsights(BaseModel):
         ge=0.0,
         description="Total monthly subscription cost",
     )
-    potential_savings: Optional[float] = Field(
+    potential_savings: float | None = Field(
         None,
         ge=0.0,
         description="Potential monthly savings from recommendations (if applicable)",
@@ -102,20 +105,20 @@ Guidelines:
 
 Examples:
 1. Subscriptions: Netflix $15.99, Hulu $12.99, Disney+ $10.99, Spotify $9.99, Amazon Prime $14.99
-   → "You have 5 subscriptions totaling $64.95/month. Consider the Disney+ bundle 
-      (Disney+, Hulu, ESPN+ for $19.99) to save $29.98/month. Also, Amazon Prime 
+   → "You have 5 subscriptions totaling $64.95/month. Consider the Disney+ bundle
+      (Disney+, Hulu, ESPN+ for $19.99) to save $29.98/month. Also, Amazon Prime
       includes Prime Video - you may be able to cancel Netflix or Hulu."
    → total_monthly_cost: 64.95
    → potential_savings: 30.00
 
 2. Subscriptions: Spotify $9.99, Apple Music $10.99
-   → "You're paying for both Spotify and Apple Music ($20.98/month). Cancel one 
+   → "You're paying for both Spotify and Apple Music ($20.98/month). Cancel one
       to save $10.99/month."
    → total_monthly_cost: 20.98
    → potential_savings: 10.99
 
 3. Subscriptions: LA Fitness $40, Planet Fitness $10
-   → "You have 2 gym memberships totaling $50/month. Consider consolidating to 
+   → "You have 2 gym memberships totaling $50/month. Consider consolidating to
       just Planet Fitness to save $40/month."
    → total_monthly_cost: 50.00
    → potential_savings: 40.00
@@ -160,7 +163,7 @@ class SubscriptionInsightsGenerator:
     def __init__(
         self,
         provider: str = "google",
-        model_name: Optional[str] = None,
+        model_name: str | None = None,
         cache_ttl: int = 86400,  # 24 hours
         enable_cache: bool = True,
         max_cost_per_day: float = 0.10,
@@ -227,7 +230,7 @@ class SubscriptionInsightsGenerator:
     async def generate(
         self,
         subscriptions: list[dict[str, Any]],
-        user_id: Optional[str] = None,
+        user_id: str | None = None,
     ) -> SubscriptionInsights:
         """
         Generate subscription insights with natural language recommendations.
@@ -288,8 +291,8 @@ class SubscriptionInsightsGenerator:
     async def _get_cached(
         self,
         subscriptions: list[dict[str, Any]],
-        user_id: Optional[str] = None,
-    ) -> Optional[SubscriptionInsights]:
+        user_id: str | None = None,
+    ) -> SubscriptionInsights | None:
         """
         Get cached insights.
 
@@ -314,7 +317,7 @@ class SubscriptionInsightsGenerator:
         self,
         subscriptions: list[dict[str, Any]],
         result: SubscriptionInsights,
-        user_id: Optional[str] = None,
+        user_id: str | None = None,
     ) -> None:
         """
         Cache insights result.
@@ -335,7 +338,7 @@ class SubscriptionInsightsGenerator:
     def _make_cache_key(
         self,
         subscriptions: list[dict[str, Any]],
-        user_id: Optional[str] = None,
+        user_id: str | None = None,
     ) -> str:
         """
         Generate cache key for insights.
@@ -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, 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__)
 
@@ -142,7 +145,7 @@ class MerchantNormalizer:
     def __init__(
         self,
         provider: str = "google",
-        model_name: Optional[str] = None,
+        model_name: str | None = None,
         cache_ttl: int = 604800,  # 7 days
         enable_cache: bool = True,
         confidence_threshold: float = 0.8,
@@ -281,7 +284,7 @@ class MerchantNormalizer:
             logger.error(f"LLM normalization failed for '{merchant_name}': {e}")
             return self._fallback_normalize(merchant_name, fallback_confidence)
 
-    async def _get_cached(self, merchant_name: str) -> Optional[MerchantNormalized]:
+    async def _get_cached(self, merchant_name: str) -> MerchantNormalized | None:
         """
         Get cached normalization result.
 
@@ -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}'")