fin-infra 0.1.57__py3-none-any.whl → 0.1.59__py3-none-any.whl

fin_infra/__init__.py

@@ -4,8 +4,19 @@ Public surface is intentionally small at this stage. Import from submodules for
 specific domains (clients, models, markets, credit).
 """
 
+from .exceptions import (
+    FinInfraError,
+    ProviderError,
+    ProviderNotFoundError,
+    ValidationError,
+)
 from .version import __version__
 
 __all__ = [
     "__version__",
+    # Base errors
+    "FinInfraError",
+    "ProviderError",
+    "ProviderNotFoundError",
+    "ValidationError",
 ]

fin_infra/analytics/spending.py

@@ -44,6 +44,7 @@ Examples:
 
 from collections import defaultdict
 from datetime import timedelta
+from decimal import Decimal
 from typing import Optional
 
 from fin_infra.analytics.models import (
@@ -132,7 +133,7 @@ async def analyze_spending(
         ]
 
     # Calculate top merchants
-    merchant_totals: dict[str, float] = defaultdict(float)
+    merchant_totals: dict[str, Decimal] = defaultdict(Decimal)
     for t in expense_transactions:
         merchant = _extract_merchant_name(t.description or "Unknown")
         merchant_totals[merchant] += abs(t.amount)
@@ -142,7 +143,7 @@ async def analyze_spending(
     ]  # Top 10 merchants
 
     # Calculate category breakdown
-    category_totals: dict[str, float] = defaultdict(float)
+    category_totals: dict[str, Decimal] = defaultdict(Decimal)
     for t in expense_transactions:
         category = _get_transaction_category(t)
         category_totals[category] += abs(t.amount)
@@ -261,7 +262,7 @@ def _get_transaction_category(transaction: Transaction) -> str:
 
 async def _calculate_spending_trends(
     user_id: str,
-    current_category_totals: dict[str, float],
+    current_category_totals: dict[str, Decimal],
     current_period_days: int,
     banking_provider=None,
     categorization_provider=None,
@@ -288,7 +289,7 @@ async def _calculate_spending_trends(
     for category, current_amount in current_category_totals.items():
         # Mock: assume previous period was 10% lower on average
         # In reality, would fetch historical data
-        previous_amount = current_amount * 0.9
+        previous_amount = current_amount * Decimal("0.9")
 
         change_percent = (
             ((current_amount - previous_amount) / previous_amount) * 100
@@ -311,7 +312,7 @@ async def _calculate_spending_trends(
 
 async def _detect_spending_anomalies(
     user_id: str,
-    current_category_totals: dict[str, float],
+    current_category_totals: dict[str, Decimal],
     current_period_days: int,
     banking_provider=None,
     categorization_provider=None,
@@ -339,7 +340,7 @@ async def _detect_spending_anomalies(
     for category, current_amount in current_category_totals.items():
         # Mock: assume historical average is current amount * 0.8
         # In reality, would calculate from historical data
-        average_amount = current_amount * 0.8
+        average_amount = current_amount * Decimal("0.8")
 
         deviation_percent = (
             ((current_amount - average_amount) / average_amount) * 100 if average_amount > 0 else 0
@@ -409,7 +410,7 @@ def _generate_mock_transactions(days: int) -> list[Transaction]:
                 Transaction(
                     id=f"mock_{i}",
                     account_id="mock_account",
-                    amount=float(amount),
+                    amount=Decimal(str(amount)),
                     date=base_date - timedelta(days=days_ago),
                     description=description,
                 )

fin_infra/categorization/llm_layer.py

@@ -20,7 +20,7 @@ from pydantic import BaseModel, Field
 
 # ai-infra imports
 try:
-    from ai_infra.llm import LLM
+    from ai_infra.llm import CoreLLM as LLM
     from ai_infra.llm.providers import Providers
 except ImportError:
     raise ImportError("ai-infra not installed. Install with: pip install ai-infra")

fin_infra/credit/experian/auth.py

@@ -27,7 +27,6 @@ import base64
 
 import httpx
 from svc_infra.cache import cache_read
-from svc_infra.cache.tags import invalidate_tags
 
 # Cache key for OAuth tokens: "oauth_token:experian:{base_url_hash}"
 # TTL: 3600 seconds (1 hour) - matches typical OAuth token expiry
@@ -91,7 +90,7 @@ class ExperianAuthManager:
     @cache_read(
         key="oauth_token:experian:{client_id}",  # Use client_id for uniqueness
         ttl=3600,  # 1 hour - matches OAuth token expiry
-        tags=lambda **kw: ["oauth:experian"],
+        tags=lambda **kw: [f"oauth:experian:{kw['client_id']}"],  # Client-specific tag
     )
     async def _get_token_cached(self, *, client_id: str) -> str:
         """Cached token getter (internal method).
@@ -144,10 +143,10 @@ class ExperianAuthManager:
         return data["access_token"]
 
     async def invalidate(self) -> None:
-        """Invalidate cached token (force refresh on next get_token call).
+        """Invalidate cached token for THIS client (force refresh on next get_token call).
 
-        Uses svc-infra cache tag invalidation to clear all tokens with tag
-        "oauth:experian". Useful when token is rejected by API.
+        Invalidates only the token for this specific client_id, not all Experian tokens.
+        Useful when token is rejected by API.
 
         Example:
             >>> try:
@@ -157,4 +156,8 @@ class ExperianAuthManager:
             ...         await auth.invalidate()
             ...         # Next get_token() will fetch new token
         """
-        await invalidate_tags("oauth:experian")
+        # Import here to avoid circular import
+        from svc_infra.cache.tags import invalidate_tags
+
+        # Invalidate using client-specific tag, not all Experian tokens
+        await invalidate_tags(f"oauth:experian:{self.client_id}")

fin_infra/credit/experian/client.py

@@ -25,33 +25,21 @@ from tenacity import (
 )
 
 from fin_infra.credit.experian.auth import ExperianAuthManager
+from fin_infra.exceptions import (
+    ExperianAPIError,
+    ExperianAuthError,
+    ExperianNotFoundError,
+    ExperianRateLimitError,
+)
 
-
-class ExperianAPIError(Exception):
-    """Base exception for Experian API errors."""
-
-    def __init__(self, message: str, status_code: int | None = None, response: dict | None = None):
-        super().__init__(message)
-        self.status_code = status_code
-        self.response = response
-
-
-class ExperianRateLimitError(ExperianAPIError):
-    """Raised when rate limit is exceeded (429)."""
-
-    pass
-
-
-class ExperianAuthError(ExperianAPIError):
-    """Raised when authentication fails (401)."""
-
-    pass
-
-
-class ExperianNotFoundError(ExperianAPIError):
-    """Raised when user not found in bureau (404)."""
-
-    pass
+# Re-export for backward compatibility
+__all__ = [
+    "ExperianAPIError",
+    "ExperianAuthError",
+    "ExperianNotFoundError",
+    "ExperianRateLimitError",
+    "ExperianClient",
+]
 
 
 class ExperianClient:

fin_infra/credit/experian/provider.py

@@ -7,6 +7,7 @@ Features:
 - HTTP client with retry logic
 - Response parsing to Pydantic models
 - FCRA compliance headers
+- FCRA audit logging (required for regulatory compliance)
 - Error handling
 
 Example:
@@ -28,6 +29,8 @@ Example:
     >>> print(len(report.accounts))  # Real credit accounts
 """
 
+import logging
+from datetime import datetime, timezone
 from typing import Literal
 
 from fin_infra.credit.experian.auth import ExperianAuthManager
@@ -37,6 +40,10 @@ from fin_infra.models.credit import CreditReport, CreditScore
 from fin_infra.providers.base import CreditProvider
 from fin_infra.settings import Settings
 
+# FCRA audit logger - use dedicated logger for compliance auditing
+# This should be configured to write to a tamper-evident, append-only log
+fcra_audit_logger = logging.getLogger("fin_infra.fcra_audit")
+
 
 class ExperianProvider(CreditProvider):
     """Experian credit bureau provider with real API integration.
@@ -143,11 +150,14 @@ class ExperianProvider(CreditProvider):
         """Retrieve current credit score for a user from Experian API.
 
         Makes real API call to Experian. Uses FCRA-compliant permissible purpose.
+        All credit pulls are logged for FCRA compliance (15 USC § 1681b).
 
         Args:
             user_id: User identifier (SSN hash or internal ID)
             **kwargs: Additional parameters
                 - permissible_purpose: FCRA purpose (default: "account_review")
+                - requester_ip: IP address of requester (for audit log)
+                - requester_user_id: ID of user/service making the request
 
         Returns:
             CreditScore with real FICO score from Experian
@@ -162,25 +172,79 @@ class ExperianProvider(CreditProvider):
             >>> print(score.score)  # Real FICO score (300-850)
         """
         permissible_purpose = kwargs.get("permissible_purpose", "account_review")
-
-        # Fetch from Experian API
-        data = await self._client.get_credit_score(
-            user_id,
-            permissible_purpose=permissible_purpose,
+        requester_ip = kwargs.get("requester_ip", "unknown")
+        requester_user_id = kwargs.get("requester_user_id", "unknown")
+        
+        # FCRA Audit Log - REQUIRED for regulatory compliance (15 USC § 1681b)
+        # This log must be retained for at least 2 years per FCRA requirements
+        timestamp = datetime.now(timezone.utc).isoformat()
+        fcra_audit_logger.info(
+            "FCRA_CREDIT_PULL",
+            extra={
+                "action": "credit_score_pull",
+                "subject_user_id": user_id,
+                "requester_user_id": requester_user_id,
+                "requester_ip": requester_ip,
+                "permissible_purpose": permissible_purpose,
+                "provider": "experian",
+                "environment": self.environment,
+                "timestamp": timestamp,
+                "result": "pending",
+            }
         )
 
-        # Parse response to CreditScore model
-        return parse_credit_score(data, user_id=user_id)
+        try:
+            # Fetch from Experian API
+            data = await self._client.get_credit_score(
+                user_id,
+                permissible_purpose=permissible_purpose,
+            )
+
+            # Parse response to CreditScore model
+            result = parse_credit_score(data, user_id=user_id)
+            
+            # Log successful pull
+            fcra_audit_logger.info(
+                "FCRA_CREDIT_PULL_SUCCESS",
+                extra={
+                    "action": "credit_score_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "success",
+                    "score_returned": result.score is not None,
+                }
+            )
+            
+            return result
+            
+        except Exception as e:
+            # Log failed pull - still required for FCRA audit trail
+            fcra_audit_logger.warning(
+                "FCRA_CREDIT_PULL_FAILED",
+                extra={
+                    "action": "credit_score_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "error",
+                    "error_type": type(e).__name__,
+                }
+            )
+            raise
 
     async def get_credit_report(self, user_id: str, **kwargs) -> CreditReport:
         """Retrieve full credit report for a user from Experian API.
 
         Makes real API call to Experian. Includes FCRA-required permissible purpose header.
+        All credit pulls are logged for FCRA compliance (15 USC § 1681b).
 
         Args:
             user_id: User identifier (SSN hash or internal ID)
             **kwargs: Additional parameters
                 - permissible_purpose: FCRA purpose (default: "account_review")
+                - requester_ip: IP address of requester (for audit log)
+                - requester_user_id: ID of user/service making the request
 
         Returns:
             CreditReport with real credit data from Experian
@@ -196,15 +260,69 @@ class ExperianProvider(CreditProvider):
             >>> print(report.score.score)  # Real FICO score
         """
         permissible_purpose = kwargs.get("permissible_purpose", "account_review")
-
-        # Fetch from Experian API
-        data = await self._client.get_credit_report(
-            user_id,
-            permissible_purpose=permissible_purpose,
+        requester_ip = kwargs.get("requester_ip", "unknown")
+        requester_user_id = kwargs.get("requester_user_id", "unknown")
+        
+        # FCRA Audit Log - REQUIRED for regulatory compliance (15 USC § 1681b)
+        # Full credit report pulls have stricter requirements than score-only pulls
+        # This log must be retained for at least 2 years per FCRA requirements
+        timestamp = datetime.now(timezone.utc).isoformat()
+        fcra_audit_logger.info(
+            "FCRA_CREDIT_PULL",
+            extra={
+                "action": "credit_report_pull",
+                "subject_user_id": user_id,
+                "requester_user_id": requester_user_id,
+                "requester_ip": requester_ip,
+                "permissible_purpose": permissible_purpose,
+                "provider": "experian",
+                "environment": self.environment,
+                "timestamp": timestamp,
+                "result": "pending",
+                "report_type": "full",
+            }
         )
 
-        # Parse response to CreditReport model
-        return parse_credit_report(data, user_id=user_id)
+        try:
+            # Fetch from Experian API
+            data = await self._client.get_credit_report(
+                user_id,
+                permissible_purpose=permissible_purpose,
+            )
+
+            # Parse response to CreditReport model
+            result = parse_credit_report(data, user_id=user_id)
+            
+            # Log successful pull
+            fcra_audit_logger.info(
+                "FCRA_CREDIT_PULL_SUCCESS",
+                extra={
+                    "action": "credit_report_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "success",
+                    "accounts_returned": len(result.accounts) if result.accounts else 0,
+                    "inquiries_returned": len(result.inquiries) if result.inquiries else 0,
+                }
+            )
+            
+            return result
+            
+        except Exception as e:
+            # Log failed pull - still required for FCRA audit trail
+            fcra_audit_logger.warning(
+                "FCRA_CREDIT_PULL_FAILED",
+                extra={
+                    "action": "credit_report_pull",
+                    "subject_user_id": user_id,
+                    "requester_user_id": requester_user_id,
+                    "timestamp": timestamp,
+                    "result": "error",
+                    "error_type": type(e).__name__,
+                }
+            )
+            raise
 
     async def subscribe_to_changes(self, user_id: str, webhook_url: str, **kwargs) -> str:
         """Subscribe to credit score change notifications from Experian.