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

fin_infra/obs/classifier.py

@@ -63,8 +63,8 @@ def financial_route_classifier(route_path: str, method: str) -> str:
     svc-infra's add_observability route_classifier parameter.
 
     Classification Logic:
-    - Financial routes (e.g., /banking/*, /market/*) → "financial"
-    - All other routes → "public"
+    - Financial routes (e.g., /banking/*, /market/*) -> "financial"
+    - All other routes -> "public"
 
     This allows Grafana dashboards to split metrics by route class:
     - Filter by route_class="financial" for financial provider SLOs

fin_infra/providers/brokerage/alpaca.py

@@ -1,6 +1,6 @@
 """Alpaca brokerage provider for paper and live trading.
 
-⚠️ IMPORTANT: This module provides real trading capabilities. Always use paper trading
+[!] IMPORTANT: This module provides real trading capabilities. Always use paper trading
 mode for development and testing. Live trading requires explicit opt-in.
 """
 

fin_infra/recurring/add.py

@@ -109,7 +109,7 @@ def add_recurring_detection(
         Detect recurring patterns in transaction history.
 
         Analyzes transaction history for recurring subscriptions and bills using
-        3-layer hybrid detection (fixed → variable → irregular).
+        3-layer hybrid detection (fixed -> variable -> irregular).
 
         **Example Request:**
         ```json

fin_infra/recurring/detectors_llm.py

@@ -100,30 +100,30 @@ 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"
    Amounts: [$50, $50, $50, $78, $50, $50]
    Dates: Monthly (20th ±3 days)
-   → is_recurring: true, cadence: "monthly", range: (50, 80),
+   -> is_recurring: true, cadence: "monthly", range: (50, 80),
      reasoning: "Occasional overage charge spike", confidence: 0.80
 
 3. Merchant: "Random Store"
    Amounts: [$10, $45, $23, $67, $12]
    Dates: Irregular
-   → is_recurring: false, reasoning: "Too much variance, no pattern", confidence: 0.95
+   -> is_recurring: false, reasoning: "Too much variance, no pattern", confidence: 0.95
 
 4. Merchant: "Gas Company"
    Amounts: [$45, $48, $50, $52, $120, $115]
    Dates: Monthly
-   → is_recurring: true, cadence: "monthly", range: (40, 120),
+   -> is_recurring: true, cadence: "monthly", range: (40, 120),
      reasoning: "Winter heating season doubles bill", confidence: 0.80
 
 5. Merchant: "Gym Membership"
    Amounts: [$40, $40, $0, $40, $40]
    Dates: Monthly
-   → is_recurring: true, cadence: "monthly", range: (0, 40),
+   -> is_recurring: true, cadence: "monthly", range: (0, 40),
      reasoning: "Annual fee waived one month", confidence: 0.75
 
 Output format (JSON):

fin_infra/recurring/ease.py

@@ -43,7 +43,7 @@ def easy_recurring_detection(
     V2 Parameters (LLM Enhancement):
         enable_llm: Enable LLM for merchant normalization and variable detection (default: False)
                    When False, uses V1 pattern-based only (fast, $0 cost)
-                   When True, uses 4-layer hybrid (RapidFuzz → LLM normalization → Statistical → LLM variable detection)
+                   When True, uses 4-layer hybrid (RapidFuzz -> LLM normalization -> Statistical -> LLM variable detection)
         llm_provider: LLM provider to use (default: "google")
                      Options: "google" (Gemini 2.0 Flash, cheapest), "openai" (GPT-4o-mini), "anthropic" (Claude 3.5 Haiku)
         llm_model: Override default model for provider (default: None)
@@ -54,9 +54,9 @@ def easy_recurring_detection(
                                  Higher values (0.9) call LLM more often (more accurate, higher cost)
                                  Lower values (0.7) call LLM less often (less accurate, lower cost)
         llm_cache_merchant_ttl: Merchant normalization cache TTL in seconds (default: 604800 = 7 days)
-                               95% cache hit rate expected → most requests <1ms
+                               95% cache hit rate expected -> most requests <1ms
         llm_cache_insights_ttl: Insights generation cache TTL in seconds (default: 86400 = 24 hours)
-                               80% cache hit rate expected → most requests <1ms
+                               80% cache hit rate expected -> most requests <1ms
         llm_max_cost_per_day: Daily budget cap in USD (default: $0.10)
                              Supports ~33k normalizations or ~1k variable detections per day
                              Sufficient for 100k+ users
@@ -80,7 +80,7 @@ def easy_recurring_detection(
         >>> # V2: LLM-enhanced detection (better accuracy, minimal cost)
         >>> detector = easy_recurring_detection(enable_llm=True)
         >>> patterns = detector.detect_patterns(transactions)
-        >>> # Merchant normalization: "NFLX*SUB" → "Netflix" (90-95% accuracy)
+        >>> # Merchant normalization: "NFLX*SUB" -> "Netflix" (90-95% accuracy)
         >>> # Variable detection: Utility bills with seasonal variance (85-88% accuracy)
         >>> # Cost: ~$0.003/user/year with caching
 

fin_infra/recurring/insights.py

@@ -7,7 +7,7 @@ Provides on-demand insights for users:
 - Cost-saving recommendations (bundle deals, unused subscriptions)
 
 Uses ai-infra LLM with few-shot prompting.
-Caches results for 24 hours (80% hit rate expected) → <1ms latency.
+Caches results for 24 hours (80% hit rate expected) -> <1ms latency.
 Triggered via GET /recurring/insights API endpoint (not automatic).
 """
 
@@ -105,23 +105,23 @@ 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
+   -> "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
+   -> 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
+   -> 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
+   -> total_monthly_cost: 50.00
+   -> potential_savings: 40.00
 
 Output format (JSON):
 {
@@ -152,8 +152,8 @@ class SubscriptionInsightsGenerator:
     LLM-based subscription insights generator with caching.
 
     Layer 5 of 4-layer hybrid architecture (on-demand, optional):
-    1. Check cache first (80% hit rate, 24h TTL) → <1ms
-    2. Call LLM if cache miss → 300-500ms
+    1. Check cache first (80% hit rate, 24h TTL) -> <1ms
+    2. Call LLM if cache miss -> 300-500ms
     3. Cache result for 24 hours
     4. Return SubscriptionInsights
 
@@ -236,9 +236,9 @@ class SubscriptionInsightsGenerator:
         Generate subscription insights with natural language recommendations.
 
         Flow:
-        1. Check cache (80% hit rate, key: insights:{user_id}) → <1ms
+        1. Check cache (80% hit rate, key: insights:{user_id}) -> <1ms
         2. Check budget (daily/monthly caps)
-        3. Call LLM if cache miss → 300-500ms
+        3. Call LLM if cache miss -> 300-500ms
         4. Cache result (24h TTL)
         5. Return SubscriptionInsights
 
@@ -352,6 +352,7 @@ class SubscriptionInsightsGenerator:
         import json
 
         subscriptions_json = json.dumps(subscriptions, sort_keys=True)
+        # Security: B324 skip justified - MD5 used for cache key generation only.
         hash_hex = hashlib.md5(subscriptions_json.encode()).hexdigest()
         return f"insights:{hash_hex}"
 

fin_infra/recurring/normalizer.py

@@ -26,12 +26,12 @@ def normalize_merchant(raw_name: str) -> str:
     Normalize merchant name for grouping.
 
     Pipeline:
-    1. Lowercase: "NETFLIX.COM" → "netflix.com"
-    2. Remove domain suffixes: "netflix.com" → "netflix"
-    3. Remove special chars: "netflix*subscription" → "netflix subscription"
-    4. Remove store/transaction numbers: "starbucks #12345" → "starbucks"
-    5. Remove legal entities: "netflix inc" → "netflix"
-    6. Strip whitespace: "  netflix  " → "netflix"
+    1. Lowercase: "NETFLIX.COM" -> "netflix.com"
+    2. Remove domain suffixes: "netflix.com" -> "netflix"
+    3. Remove special chars: "netflix*subscription" -> "netflix subscription"
+    4. Remove store/transaction numbers: "starbucks #12345" -> "starbucks"
+    5. Remove legal entities: "netflix inc" -> "netflix"
+    6. Strip whitespace: "  netflix  " -> "netflix"
 
     Args:
         raw_name: Original merchant name

fin_infra/recurring/normalizers.py

@@ -8,7 +8,7 @@ Handles cryptic merchant names that fail pattern-based normalization:
 - Legal entities: Inc, LLC, Corp, Ltd
 
 Uses ai-infra LLM with few-shot prompting for 90-95% accuracy.
-Caches results for 7 days (95% hit rate expected) → <1ms latency.
+Caches results for 7 days (95% hit rate expected) -> <1ms latency.
 Falls back to RapidFuzz if LLM fails or disabled.
 """
 
@@ -93,26 +93,26 @@ Common patterns:
 - POS systems: TST* (Toast), CLOVER*, SQUARE*
 
 Examples:
-1. "NFLX*SUB #12345" → Netflix (streaming)
-2. "Netflix Inc" → Netflix (streaming)
-3. "NETFLIX.COM" → Netflix (streaming)
-4. "SQ *COZY CAFE" → Cozy Cafe (coffee_shop, Square processor)
-5. "TST* STARBUCKS" → Starbucks (coffee_shop, Toast POS)
-6. "AMZN MKTP US" → Amazon (online_shopping)
-7. "SPFY*PREMIUM" → Spotify (streaming)
-8. "UBER *TRIP 12345" → Uber (rideshare)
-9. "LYFT   *RIDE ABC" → Lyft (rideshare)
-10. "CLOVER* PIZZA PLACE" → Pizza Place (restaurant, Clover POS)
-11. "AAPL* ICLOUD STORAGE" → Apple iCloud (cloud_storage)
-12. "MSFT*MICROSOFT 365" → Microsoft 365 (software_subscription)
-13. "DISNEY PLUS #123" → Disney Plus (streaming)
-14. "PRIME VIDEO" → Amazon Prime Video (streaming)
-15. "CITY ELECTRIC #456" → City Electric (utility_electric)
-16. "T-MOBILE USA" → T-Mobile (phone_service)
-17. "VERIZON WIRELESS" → Verizon (phone_service)
-18. "WHOLE FOODS MKT #789" → Whole Foods (grocery)
-19. "STARBUCKS #1234" → Starbucks (coffee_shop)
-20. "LA FITNESS #567" → LA Fitness (gym)
+1. "NFLX*SUB #12345" -> Netflix (streaming)
+2. "Netflix Inc" -> Netflix (streaming)
+3. "NETFLIX.COM" -> Netflix (streaming)
+4. "SQ *COZY CAFE" -> Cozy Cafe (coffee_shop, Square processor)
+5. "TST* STARBUCKS" -> Starbucks (coffee_shop, Toast POS)
+6. "AMZN MKTP US" -> Amazon (online_shopping)
+7. "SPFY*PREMIUM" -> Spotify (streaming)
+8. "UBER *TRIP 12345" -> Uber (rideshare)
+9. "LYFT   *RIDE ABC" -> Lyft (rideshare)
+10. "CLOVER* PIZZA PLACE" -> Pizza Place (restaurant, Clover POS)
+11. "AAPL* ICLOUD STORAGE" -> Apple iCloud (cloud_storage)
+12. "MSFT*MICROSOFT 365" -> Microsoft 365 (software_subscription)
+13. "DISNEY PLUS #123" -> Disney Plus (streaming)
+14. "PRIME VIDEO" -> Amazon Prime Video (streaming)
+15. "CITY ELECTRIC #456" -> City Electric (utility_electric)
+16. "T-MOBILE USA" -> T-Mobile (phone_service)
+17. "VERIZON WIRELESS" -> Verizon (phone_service)
+18. "WHOLE FOODS MKT #789" -> Whole Foods (grocery)
+19. "STARBUCKS #1234" -> Starbucks (coffee_shop)
+20. "LA FITNESS #567" -> LA Fitness (gym)
 
 Output format (JSON):
 {
@@ -131,8 +131,8 @@ class MerchantNormalizer:
     LLM-based merchant name normalizer with caching and fallback.
 
     Layer 2 of 4-layer hybrid architecture:
-    1. Check cache first (95% hit rate, 7-day TTL) → <1ms
-    2. Call LLM if cache miss → 200-400ms
+    1. Check cache first (95% hit rate, 7-day TTL) -> <1ms
+    2. Call LLM if cache miss -> 200-400ms
     3. Cache result for 7 days
     4. Return MerchantNormalized
 
@@ -221,9 +221,9 @@ class MerchantNormalizer:
         Normalize merchant name using LLM with caching.
 
         Flow:
-        1. Check cache (95% hit rate) → <1ms
+        1. Check cache (95% hit rate) -> <1ms
         2. Check budget (daily/monthly caps)
-        3. Call LLM if cache miss → 200-400ms
+        3. Call LLM if cache miss -> 200-400ms
         4. Validate confidence threshold
         5. Cache result (7-day TTL)
         6. Return MerchantNormalized
@@ -330,6 +330,7 @@ class MerchantNormalizer:
         Format: merchant_norm:{md5_hex}
         """
         normalized = merchant_name.lower().strip()
+        # Security: B324 skip justified - MD5 used for cache key generation only.
         hash_hex = hashlib.md5(normalized.encode()).hexdigest()
         return f"merchant_norm:{hash_hex}"
 
@@ -386,7 +387,7 @@ class MerchantNormalizer:
         # Remove special characters
         normalized = normalized.replace("*", " ").replace("#", " ").replace(".", " ")
 
-        # Remove store numbers (e.g., "starbucks 1234" → "starbucks")
+        # Remove store numbers (e.g., "starbucks 1234" -> "starbucks")
         import re
 
         normalized = re.sub(r"\b\d{3,}\b", "", normalized)

fin_infra/scaffold/goals.py

@@ -178,10 +178,10 @@ def scaffold_goals_core(
     Scaffold goals domain files: models, schemas, repository (optional), and __init__.py.
 
     Generates production-ready code from templates in fin_infra.goals.scaffold_templates:
-    - models.py.tmpl → Goal model with progress tracking, status, priority, milestones
-    - schemas.py.tmpl → GoalBase, GoalCreate, GoalUpdate, GoalRead with status validation
-    - repository.py.tmpl → GoalRepository with CRUD + domain methods (get_active, update_progress)
-    - README.md → Complete usage guide with examples
+    - models.py.tmpl -> Goal model with progress tracking, status, priority, milestones
+    - schemas.py.tmpl -> GoalBase, GoalCreate, GoalUpdate, GoalRead with status validation
+    - repository.py.tmpl -> GoalRepository with CRUD + domain methods (get_active, update_progress)
+    - README.md -> Complete usage guide with examples
 
     Args:
         dest_dir: Destination directory (will be created if missing)

fin_infra/security/add.py

@@ -5,7 +5,6 @@ Easy integration of financial PII masking and token encryption.
 """
 
 import logging
-from typing import Optional
 
 from fastapi import FastAPI
 
@@ -15,7 +14,7 @@ from .pii_filter import FinancialPIIFilter
 
 def add_financial_security(
     app: FastAPI,
-    encryption_key: Optional[bytes] = None,
+    encryption_key: bytes | None = None,
     enable_pii_filter: bool = True,
     enable_audit_log: bool = True,
     mask_emails: bool = False,

fin_infra/security/audit.py

@@ -6,7 +6,6 @@ Track access to sensitive financial data for compliance.
 
 import logging
 from datetime import datetime
-from typing import Optional
 
 from .models import PIIAccessLog
 
@@ -23,10 +22,10 @@ async def log_pii_access(
     pii_type: str,
     action: str,
     resource: str,
-    ip_address: Optional[str] = None,
-    user_agent: Optional[str] = None,
+    ip_address: str | None = None,
+    user_agent: str | None = None,
     success: bool = True,
-    error_message: Optional[str] = None,
+    error_message: str | None = None,
 ) -> PIIAccessLog:
     """
     Log PII access for audit trail.
@@ -86,9 +85,9 @@ async def log_pii_access(
 
 
 def get_audit_logs(
-    user_id: Optional[str] = None,
-    pii_type: Optional[str] = None,
-    action: Optional[str] = None,
+    user_id: str | None = None,
+    pii_type: str | None = None,
+    action: str | None = None,
     limit: int = 100,
 ) -> list[PIIAccessLog]:
     """

fin_infra/security/pii_filter.py

@@ -116,8 +116,8 @@ class FinancialPIIFilter(logging.Filter):
         Mask Social Security Numbers.
 
         Examples:
-            123-45-6789 → ***-**-6789
-            123456789 → *****6789 (with context)
+            123-45-6789 -> ***-**-6789
+            123456789 -> *****6789 (with context)
         """
         # With dashes (high confidence)
         text = SSN_PATTERN.sub(lambda m: f"***-**-{m.group()[-4:]}", text)
@@ -145,7 +145,7 @@ class FinancialPIIFilter(logging.Filter):
         Mask Employer Identification Numbers.
 
         Example:
-            12-3456789 → **-****789
+            12-3456789 -> **-****789
         """
         return EIN_PATTERN.sub(lambda m: f"**-****{m.group()[-3:]}", text)
 
@@ -154,8 +154,8 @@ class FinancialPIIFilter(logging.Filter):
         Mask credit card numbers using Luhn validation.
 
         Examples:
-            4111 1111 1111 1111 → **** **** **** 1111
-            4111111111111111 → ************1111
+            4111 1111 1111 1111 -> **** **** **** 1111
+            4111111111111111 -> ************1111
         """
 
         def mask_card_match(match):
@@ -182,7 +182,7 @@ class FinancialPIIFilter(logging.Filter):
         Mask ABA routing numbers with checksum validation.
 
         Example:
-            021000021 → ******021
+            021000021 -> ******021
         """
 
         def mask_routing_match(match):
@@ -207,7 +207,7 @@ class FinancialPIIFilter(logging.Filter):
         Mask bank account numbers.
 
         Example:
-            1234567890 → ******7890
+            1234567890 -> ******7890
         """
 
         def mask_account_match(match):
@@ -231,7 +231,7 @@ class FinancialPIIFilter(logging.Filter):
         Mask CVV codes (context-dependent).
 
         Example:
-            CVV: 123 → CVV: ***
+            CVV: 123 -> CVV: ***
         """
 
         def mask_cvv_match(match):
@@ -255,7 +255,7 @@ class FinancialPIIFilter(logging.Filter):
         Mask email addresses.
 
         Example:
-            user@example.com → u***@example.com
+            user@example.com -> u***@example.com
         """
 
         def mask_email_match(match):
@@ -272,7 +272,7 @@ class FinancialPIIFilter(logging.Filter):
         Mask phone numbers.
 
         Example:
-            (555) 123-4567 → (***) ***-4567
+            (555) 123-4567 -> (***) ***-4567
         """
 
         def mask_phone_match(match):

fin_infra/security/token_store.py

@@ -5,7 +5,6 @@ Database operations for encrypted provider tokens.
 """
 
 from datetime import datetime
-from typing import Optional
 
 from sqlalchemy import Column, DateTime, String, Text, select, update
 from sqlalchemy.dialects.postgresql import UUID
@@ -48,8 +47,8 @@ async def store_provider_token(
     provider: str,
     token: str,
     encryption: ProviderTokenEncryption,
-    expires_at: Optional[datetime] = None,
-    key_id: Optional[str] = None,
+    expires_at: datetime | None = None,
+    key_id: str | None = None,
 ) -> ProviderTokenMetadata:
     """
     Store encrypted provider token in database.

fin_infra/tax/add.py

@@ -279,7 +279,7 @@ def add_tax_data(
         that can be sold to offset capital gains. Suggests replacement securities
         to maintain market exposure without triggering wash sale rules.
 
-        ⚠️ **DISCLAIMER**: Not a substitute for professional tax or financial advice.
+        [!] **DISCLAIMER**: Not a substitute for professional tax or financial advice.
         Consult a certified tax professional before executing TLH trades.
 
         Args:
@@ -344,7 +344,7 @@ def add_tax_data(
         Projects the outcome of executing provided TLH opportunities, including
         total tax savings, portfolio impact, and risk assessment.
 
-        ⚠️ **DISCLAIMER**: Not a substitute for professional tax or financial advice.
+        [!] **DISCLAIMER**: Not a substitute for professional tax or financial advice.
         Consult a certified tax professional before executing TLH trades.
 
         Args:

fin_infra/tax/tlh.py

@@ -456,7 +456,7 @@ def _suggest_replacement(symbol: str, asset_class: str) -> str:
     # Simple rule-based suggestions (v1)
     # TODO: Replace with ai-infra LLM for intelligent suggestions
     replacements = {
-        # Tech stocks → sector ETFs
+        # Tech stocks -> sector ETFs
         "AAPL": "VGT",  # Tech ETF
         "MSFT": "VGT",
         "GOOGL": "VGT",
@@ -464,19 +464,19 @@ def _suggest_replacement(symbol: str, asset_class: str) -> str:
         "META": "VGT",
         "NVDA": "SOXX",  # Semiconductor ETF
         "AMD": "SOXX",
-        # Auto/EV → sector alternatives
+        # Auto/EV -> sector alternatives
         "TSLA": "ARKK",  # Innovation ETF
         "F": "XLI",  # Industrials ETF
         "GM": "XLI",
-        # Finance → sector ETF
+        # Finance -> sector ETF
         "JPM": "XLF",  # Financials ETF
         "BAC": "XLF",
         "GS": "XLF",
-        # Healthcare → sector ETF
+        # Healthcare -> sector ETF
         "JNJ": "XLV",  # Healthcare ETF
         "PFE": "XLV",
         "MRNA": "XBI",  # Biotech ETF
-        # Crypto → broad exposure
+        # Crypto -> broad exposure
         "BTC": "ETH",  # Ethereum (different asset)
         "ETH": "BTC",  # Bitcoin (different asset)
     }

fin_infra/utils/__init__.py

@@ -10,8 +10,22 @@ and should be imported from there:
 
 For async retry with exponential backoff:
     from fin_infra.utils.retry import retry_async, RetryError
+
+For deprecation utilities:
+    from fin_infra.utils.deprecation import deprecated, deprecated_parameter
 """
 
+from fin_infra.utils.deprecation import (
+    DeprecatedWarning,
+    deprecated,
+    deprecated_parameter,
+)
 from fin_infra.utils.retry import RetryError, retry_async
 
-__all__ = ["RetryError", "retry_async"]
+__all__ = [
+    "RetryError",
+    "retry_async",
+    "deprecated",
+    "deprecated_parameter",
+    "DeprecatedWarning",
+]