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

fin_infra/investments/scaffold_templates/README.md

@@ -18,15 +18,15 @@ These templates generate production-ready persistence code for investment holdin
 ## Why Historical Snapshots?
 
 **Investment data providers (Plaid, SnapTrade, etc.) only provide current/live data:**
-- ❌ No historical portfolio values from past dates
-- ❌ No historical performance metrics
-- ❌ Cannot answer "What was my portfolio worth 3 months ago?"
+- [X] No historical portfolio values from past dates
+- [X] No historical performance metrics
+- [X] Cannot answer "What was my portfolio worth 3 months ago?"
 
 **Solution: Store periodic snapshots in your database**
-- ✅ Track portfolio value changes over time
-- ✅ Calculate performance metrics (returns, growth)
-- ✅ Show trend charts and historical analysis
-- ✅ Works even if user disconnects provider
+- [OK] Track portfolio value changes over time
+- [OK] Calculate performance metrics (returns, growth)
+- [OK] Show trend charts and historical analysis
+- [OK] Works even if user disconnects provider
 
 ## Template Variables
 
@@ -148,12 +148,12 @@ async def capture_holdings_snapshot(
     holdings_data: list[dict],  # From Plaid/SnapTrade API
 ) -> None:
     """Capture current holdings as a snapshot for historical tracking."""
-    
+
     # Calculate aggregated metrics
     total_value = sum(Decimal(str(h.get("institution_value", 0))) for h in holdings_data)
     total_cost_basis = sum(Decimal(str(h.get("cost_basis", 0))) for h in holdings_data if h.get("cost_basis"))
     total_unrealized_gain_loss = sum(Decimal(str(h.get("unrealized_gain_loss", 0))) for h in holdings_data if h.get("unrealized_gain_loss"))
-    
+
     # Create snapshot
     service = create_holding_snapshot_service(session)
     snapshot = await service.create(HoldingSnapshotCreate(
@@ -167,7 +167,7 @@ async def capture_holdings_snapshot(
         provider="plaid",  # or "snaptrade"
         notes="Automatic daily snapshot"
     ))
-    
+
     await session.commit()
 ```
 
@@ -181,18 +181,18 @@ async def daily_holdings_snapshot():
     """Capture holdings snapshots for all users with investment accounts."""
     from sqlalchemy import select
     from my_app.models.user import User
-    
+
     async with AsyncSession(engine) as session:
         # Get all users with Plaid/SnapTrade connections
         stmt = select(User).where(User.banking_providers.isnot(None))
         result = await session.execute(stmt)
         users = result.scalars().all()
-        
+
         for user in users:
             try:
                 # Fetch current holdings from provider
                 holdings = await fetch_holdings_from_provider(user)
-                
+
                 # Create snapshot
                 await capture_holdings_snapshot(session, user.id, holdings)
             except Exception as e:
@@ -299,10 +299,10 @@ async def get_portfolio_performance_data(user_id: str):
     """Get data for portfolio performance dashboard."""
     async with AsyncSession(engine) as session:
         repo = create_holding_snapshot_service(session)
-        
+
         # Get last 12 months trend
         snapshots = await repo.get_trend(user_id=user_id, months=12)
-        
+
         # Calculate YTD performance
         today = date.today()
         year_start = date(today.year, 1, 1)
@@ -311,10 +311,10 @@ async def get_portfolio_performance_data(user_id: str):
             start_date=year_start,
             end_date=today
         )
-        
+
         # Get latest snapshot
         latest = await repo.get_latest(user_id=user_id)
-        
+
         return {
             "current_value": latest.total_value if latest else 0,
             "ytd_return": ytd_performance["percent_return"],

fin_infra/markets/__init__.py

@@ -20,7 +20,10 @@ if TYPE_CHECKING:
     from fastapi import FastAPI
 
 from ..providers.base import MarketDataProvider
-from ..clients.base import MarketDataClient
+
+# Deprecated: MarketDataClient alias for backward compatibility
+# Use MarketDataProvider instead
+MarketDataClient = MarketDataProvider  # type: ignore[misc]
 
 
 def easy_market(
@@ -30,8 +33,8 @@ def easy_market(
     """Create a market data provider with zero or minimal configuration.
 
     Auto-detects provider based on environment variables:
-    1. If ALPHA_VANTAGE_API_KEY or ALPHAVANTAGE_API_KEY is set → Alpha Vantage
-    2. Otherwise → Yahoo Finance (no key needed)
+    1. If ALPHA_VANTAGE_API_KEY or ALPHAVANTAGE_API_KEY is set -> Alpha Vantage
+    2. Otherwise -> Yahoo Finance (no key needed)
 
     Args:
         provider: Provider name ("alphavantage" or "yahoo").
@@ -98,7 +101,7 @@ def easy_market(
 
 
 def add_market_data(
-    app: "FastAPI",
+    app: FastAPI,
     *,
     provider: str | MarketDataProvider | None = None,
     prefix: str = "/market",
@@ -178,7 +181,6 @@ def add_market_data(
     See Also:
         - easy_market(): For standalone provider usage without FastAPI
         - docs/market-data.md: API documentation and examples
-        - docs/adr/0004-market-data-integration.md: Architecture decisions
     """
     from fastapi import HTTPException, Query
 

fin_infra/models/__init__.py

@@ -1,21 +1,21 @@
 from .accounts import Account, AccountType
-from .transactions import Transaction
-from .quotes import Quote
-from .money import Money
-from .candle import Candle
-from .brokerage import Order, Position, PortfolioHistory
 from .brokerage import Account as BrokerageAccount  # Avoid name conflict
+from .brokerage import Order, PortfolioHistory, Position
+from .candle import Candle
+from .money import Money
+from .quotes import Quote
 from .tax import (
+    CryptoTaxReport,
+    CryptoTransaction,
     TaxDocument,
-    TaxFormW2,
-    TaxForm1099INT,
-    TaxForm1099DIV,
     TaxForm1099B,
+    TaxForm1099DIV,
+    TaxForm1099INT,
     TaxForm1099MISC,
-    CryptoTransaction,
-    CryptoTaxReport,
+    TaxFormW2,
     TaxLiability,
 )
+from .transactions import Transaction
 
 __all__ = [
     "Account",

fin_infra/models/accounts.py

@@ -2,7 +2,6 @@ from __future__ import annotations
 
 from decimal import Decimal
 from enum import Enum
-from typing import Optional
 
 from pydantic import BaseModel, field_validator
 
@@ -26,11 +25,11 @@ class Account(BaseModel):
     id: str
     name: str
     type: AccountType
-    mask: Optional[str] = None
+    mask: str | None = None
     currency: str = "USD"
-    institution: Optional[str] = None
-    balance_available: Optional[Decimal] = None
-    balance_current: Optional[Decimal] = None
+    institution: str | None = None
+    balance_available: Decimal | None = None
+    balance_current: Decimal | None = None
 
     @field_validator("balance_available", "balance_current", mode="before")
     @classmethod

fin_infra/models/brokerage.py

@@ -2,9 +2,10 @@
 
 from __future__ import annotations
 
-from decimal import Decimal
 from datetime import datetime
+from decimal import Decimal
 from typing import Literal
+
 from pydantic import BaseModel, Field
 
 

fin_infra/models/candle.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from decimal import Decimal
+
 from pydantic import BaseModel, field_validator
 
 

fin_infra/models/money.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from decimal import Decimal
+
 from pydantic import BaseModel, field_validator
 
 

fin_infra/models/quotes.py

@@ -1,7 +1,8 @@
 from __future__ import annotations
 
-from datetime import datetime, timezone
+from datetime import UTC, datetime
 from decimal import Decimal
+
 from pydantic import BaseModel, field_validator
 
 
@@ -16,5 +17,5 @@ class Quote(BaseModel):
     def _ensure_tzaware(cls, v: datetime) -> datetime:
         # Normalize to timezone-aware (UTC) for consistency
         if v.tzinfo is None:
-            return v.replace(tzinfo=timezone.utc)
-        return v.astimezone(timezone.utc)
+            return v.replace(tzinfo=UTC)
+        return v.astimezone(UTC)

fin_infra/models/tax.py

@@ -37,7 +37,8 @@ Example:
 
 from datetime import date, datetime
 from decimal import Decimal
-from pydantic import BaseModel, Field, ConfigDict
+
+from pydantic import BaseModel, ConfigDict, Field
 
 
 class TaxDocument(BaseModel):

fin_infra/models/transactions.py

@@ -1,8 +1,7 @@
 from __future__ import annotations
 
-from datetime import date  # noqa: F401 - used in type annotation
+import datetime
 from decimal import Decimal
-from typing import Optional
 
 from pydantic import BaseModel, field_validator
 
@@ -16,11 +15,11 @@ class Transaction(BaseModel):
 
     id: str
     account_id: str
-    date: date
+    date: datetime.date
     amount: Decimal
     currency: str = "USD"
-    description: Optional[str] = None
-    category: Optional[str] = None
+    description: str | None = None
+    category: str | None = None
 
     @field_validator("amount", mode="before")
     @classmethod

fin_infra/net_worth/__init__.py

@@ -4,9 +4,16 @@ Net Worth Tracking Module
 Calculates net worth by aggregating balances from multiple financial providers
 (banking, brokerage, crypto) with historical snapshots and change detection.
 
+**Feature Status**:
+    [OK] STABLE: Core calculation (works with provided data)
+    [OK] STABLE: Banking integration (Plaid, Teller)
+    [!]  INTEGRATION: Brokerage integration (requires provider setup)
+    [!]  INTEGRATION: Crypto integration (requires provider setup)
+    [!]  INTEGRATION: Currency conversion (pass exchange_rate manually)
+
 **Key Features**:
 - Multi-provider aggregation (banking + brokerage + crypto)
-- Currency normalization (all currencies → USD)
+- Currency normalization (all currencies -> USD)
 - Historical snapshots (daily at midnight UTC)
 - Change detection (>5% or >$10k triggers webhook)
 - Asset allocation breakdown (pie charts)

fin_infra/net_worth/aggregator.py

@@ -30,6 +30,7 @@ print(f"Net Worth: ${snapshot.total_net_worth:,.2f}")
 """
 
 import asyncio
+import logging
 import uuid
 from datetime import datetime
 from typing import Any
@@ -47,6 +48,8 @@ from fin_infra.net_worth.models import (
     NetWorthSnapshot,
 )
 
+logger = logging.getLogger(__name__)
+
 
 class NetWorthAggregator:
     """
@@ -56,7 +59,7 @@ class NetWorthAggregator:
     - Multi-provider support (banking, brokerage, crypto)
     - Parallel account fetching (faster performance)
     - Graceful error handling (continue if one provider fails)
-    - Currency normalization (all → base currency)
+    - Currency normalization (all -> base currency)
     - Market value calculation (stocks/crypto)
 
     **Example**:
@@ -219,8 +222,7 @@ class NetWorthAggregator:
 
         for i, result in enumerate(results):
             if isinstance(result, BaseException):
-                # Log error but continue (graceful degradation)
-                print(f"Provider {providers_used[i]} failed: {result}")
+                logger.warning("Provider %s failed: %s", providers_used[i], result)
                 continue
 
             # result is now tuple[list[AssetDetail], list[LiabilityDetail]]

fin_infra/net_worth/calculator.py

@@ -3,7 +3,7 @@ Net Worth Calculator Module
 
 Provides core calculation functions for net worth tracking:
 - Net worth calculation (assets - liabilities)
-- Currency normalization (all currencies → base currency)
+- Currency normalization (all currencies -> base currency)
 - Asset allocation breakdown
 - Change detection (amount + percentage)
 

fin_infra/net_worth/insights.py

@@ -31,7 +31,6 @@ from typing import Any
 
 from pydantic import BaseModel, Field
 
-
 # ============================================================================
 # Pydantic Schemas (Structured Output)
 # ============================================================================
@@ -168,7 +167,7 @@ Be specific with numbers. Cite percentage changes and dollar amounts.
 Focus on actionable insights, not generic advice.
 
 Example 1:
-User: Net worth: $500k → $575k over 6 months. Assets: +$65k (investments +$60k, savings +$5k). Liabilities: -$10k (new mortgage).
+User: Net worth: $500k -> $575k over 6 months. Assets: +$65k (investments +$60k, savings +$5k). Liabilities: -$10k (new mortgage).
 Response: {
   "summary": "Net worth increased 15% ($75k) over 6 months, driven primarily by strong investment performance.",
   "period": "6 months",
@@ -192,7 +191,7 @@ Response: {
 }
 
 Example 2:
-User: Net worth: $100k → $95k over 3 months. Assets: -$2k (market down). Liabilities: +$3k (credit card debt).
+User: Net worth: $100k -> $95k over 3 months. Assets: -$2k (market down). Liabilities: +$3k (credit card debt).
 Response: {
   "summary": "Net worth decreased 5% ($5k) over 3 months due to market decline and rising credit card debt.",
   "period": "3 months",
@@ -216,7 +215,7 @@ Response: {
   "confidence": 0.89
 }
 
-⚠️ This is AI-generated advice. Not a substitute for a certified financial advisor.
+[!] This is AI-generated advice. Not a substitute for a certified financial advisor.
 Verify calculations independently. For personalized advice, consult a professional."""
 
 DEBT_REDUCTION_SYSTEM_PROMPT = """You are a debt counselor using the avalanche method (highest APR first).
@@ -270,7 +269,7 @@ Response: {
   "confidence": 0.98
 }
 
-⚠️ This is AI-generated advice. Not a substitute for a certified financial advisor.
+[!] This is AI-generated advice. Not a substitute for a certified financial advisor.
 Verify calculations independently. For personalized advice, consult a professional."""
 
 GOAL_RECOMMENDATION_SYSTEM_PROMPT = """You are a financial planner validating goals and suggesting paths.
@@ -323,7 +322,7 @@ Response: {
   "confidence": 0.89
 }
 
-⚠️ This is AI-generated advice. Not a substitute for a certified financial advisor.
+[!] This is AI-generated advice. Not a substitute for a certified financial advisor.
 Verify calculations independently. For personalized advice, consult a professional."""
 
 ASSET_ALLOCATION_SYSTEM_PROMPT = """You are a portfolio advisor recommending asset allocation.
@@ -334,7 +333,7 @@ Given current allocation, age, and risk tolerance:
 3. Provide specific rebalancing steps
 
 Rule of thumb:
-- Stock allocation = 100 - age (e.g., age 35 → 65% stocks)
+- Stock allocation = 100 - age (e.g., age 35 -> 65% stocks)
 - Bonds for stability (increases with age)
 - Cash for emergency fund (3-6 months expenses)
 
@@ -366,7 +365,7 @@ Response: {
   "confidence": 0.91
 }
 
-⚠️ This is AI-generated advice. Not a substitute for a certified financial advisor.
+[!] This is AI-generated advice. Not a substitute for a certified financial advisor.
 Verify calculations independently. For personalized advice, consult a professional."""
 
 

fin_infra/normalization/__init__.py

@@ -54,7 +54,7 @@ def easy_normalization(
     Example:
         >>> from fin_infra.normalization import easy_normalization
         >>> resolver, converter = easy_normalization()
-        >>> ticker = await resolver.to_ticker("037833100")  # CUSIP → AAPL
+        >>> ticker = await resolver.to_ticker("037833100")  # CUSIP -> AAPL
         >>> eur = await converter.convert(100, "USD", "EUR")  # 92.0
     """
     global _resolver_instance, _converter_instance
@@ -107,7 +107,7 @@ def add_normalization(
         >>> resolver, converter = add_normalization(app)
         >>>
         >>> # Routes available:
-        >>> # GET /normalize/symbol/037833100 → {"ticker": "AAPL", ...}
+        >>> # GET /normalize/symbol/037833100 -> {"ticker": "AAPL", ...}
         >>> # GET /normalize/convert?amount=100&from_currency=USD&to_currency=EUR
 
     Integration with svc-infra:
@@ -116,11 +116,11 @@ def add_normalization(
         - Scoped docs at {prefix}/docs for standalone documentation
     """
     # Import FastAPI dependencies
-    from fastapi import Query, HTTPException
+    from fastapi import HTTPException, Query
+    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
 
     # Import svc-infra public router (no auth - utility endpoints)
     from svc_infra.api.fastapi.dual.public import public_router
-    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
 
     # Get normalization services
     resolver, converter = easy_normalization(api_key=api_key)

fin_infra/normalization/currency_converter.py

@@ -2,7 +2,6 @@
 
 import logging
 from datetime import date as DateType
-from typing import Optional
 
 from fin_infra.exceptions import CurrencyNotSupportedError, ExchangeRateAPIError
 from fin_infra.normalization.models import CurrencyConversionResult
@@ -25,7 +24,7 @@ class CurrencyConverter:
     Supports 160+ currencies including crypto (BTC, ETH).
     """
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: str | None = None):
         """
         Initialize currency converter.
 
@@ -39,7 +38,7 @@ class CurrencyConverter:
         amount: float,
         from_currency: str,
         to_currency: str,
-        date: Optional[DateType] = None,
+        date: DateType | None = None,
     ) -> float:
         """
         Convert amount from one currency to another.
@@ -72,14 +71,14 @@ class CurrencyConverter:
         except ExchangeRateAPIError as e:
             logger.error(f"Failed to convert {from_currency} to {to_currency}: {e}")
             raise CurrencyNotSupportedError(
-                f"Conversion failed: {from_currency} → {to_currency}"
+                f"Conversion failed: {from_currency} -> {to_currency}"
             ) from e
 
     async def get_rate(
         self,
         from_currency: str,
         to_currency: str,
-        date: Optional[DateType] = None,
+        date: DateType | None = None,
     ) -> float:
         """
         Get exchange rate between two currencies.
@@ -109,9 +108,9 @@ class CurrencyConverter:
             return rate_data.rate
 
         except ExchangeRateAPIError as e:
-            logger.error(f"Failed to get rate {from_currency} → {to_currency}: {e}")
+            logger.error(f"Failed to get rate {from_currency} -> {to_currency}: {e}")
             raise CurrencyNotSupportedError(
-                f"Rate not available: {from_currency} → {to_currency}"
+                f"Rate not available: {from_currency} -> {to_currency}"
             ) from e
 
     async def get_rates(self, base_currency: str = "USD") -> dict[str, float]:
@@ -142,7 +141,7 @@ class CurrencyConverter:
         amount: float,
         from_currency: str,
         to_currency: str,
-        date: Optional[DateType] = None,
+        date: DateType | None = None,
     ) -> CurrencyConversionResult:
         """
         Convert amount with detailed result information.

fin_infra/normalization/models.py

@@ -1,7 +1,6 @@
 """Data models for normalization module."""
 
 from datetime import date as DateType
-from typing import Optional
 
 from pydantic import BaseModel, Field
 
@@ -11,12 +10,12 @@ class SymbolMetadata(BaseModel):
 
     ticker: str = Field(..., description="Standard ticker symbol")
     name: str = Field(..., description="Company or asset name")
-    exchange: Optional[str] = Field(None, description="Primary exchange (e.g., NASDAQ, NYSE)")
-    cusip: Optional[str] = Field(None, description="CUSIP identifier")
-    isin: Optional[str] = Field(None, description="ISIN identifier")
-    sector: Optional[str] = Field(None, description="Business sector")
-    industry: Optional[str] = Field(None, description="Industry classification")
-    market_cap: Optional[float] = Field(None, description="Market capitalization in USD")
+    exchange: str | None = Field(None, description="Primary exchange (e.g., NASDAQ, NYSE)")
+    cusip: str | None = Field(None, description="CUSIP identifier")
+    isin: str | None = Field(None, description="ISIN identifier")
+    sector: str | None = Field(None, description="Business sector")
+    industry: str | None = Field(None, description="Industry classification")
+    market_cap: float | None = Field(None, description="Market capitalization in USD")
     asset_type: str = Field(default="stock", description="Asset type: stock, etf, crypto, forex")
 
 
@@ -26,8 +25,8 @@ class ExchangeRate(BaseModel):
     from_currency: str = Field(..., description="Source currency code (e.g., USD)")
     to_currency: str = Field(..., description="Target currency code (e.g., EUR)")
     rate: float = Field(..., description="Exchange rate (1 from_currency = rate to_currency)")
-    date: Optional[DateType] = Field(None, description="Rate date (None = current)")
-    timestamp: Optional[int] = Field(None, description="Unix timestamp of rate")
+    date: DateType | None = Field(None, description="Rate date (None = current)")
+    timestamp: int | None = Field(None, description="Unix timestamp of rate")
 
 
 class CurrencyConversionResult(BaseModel):
@@ -38,4 +37,4 @@ class CurrencyConversionResult(BaseModel):
     to_currency: str = Field(..., description="Target currency")
     converted: float = Field(..., description="Converted amount")
     rate: float = Field(..., description="Exchange rate used")
-    date: Optional[DateType] = Field(None, description="Rate date")
+    date: DateType | None = Field(None, description="Rate date")

fin_infra/normalization/providers/exchangerate.py

@@ -2,7 +2,7 @@
 
 import os
 from datetime import date as DateType
-from typing import Optional, cast
+from typing import cast
 
 import httpx
 
@@ -19,7 +19,7 @@ __all__ = [
 class ExchangeRateClient:
     """Client for exchangerate-api.io API."""
 
-    def __init__(self, api_key: Optional[str] = None):
+    def __init__(self, api_key: str | None = None):
         """
         Initialize exchange rate client.
 
@@ -66,10 +66,10 @@ class ExchangeRateClient:
                         raise ExchangeRateAPIError(
                             f"API returned error: {data.get('error-type', 'unknown')}"
                         )
-                    return cast(dict[str, float], data["conversion_rates"])
+                    return cast("dict[str, float]", data["conversion_rates"])
                 else:
                     # Free tier response format
-                    return cast(dict[str, float], data["rates"])
+                    return cast("dict[str, float]", data["rates"])
 
         except httpx.HTTPError as e:
             raise ExchangeRateAPIError(f"HTTP error fetching rates: {e}")
@@ -77,7 +77,7 @@ class ExchangeRateClient:
             raise ExchangeRateAPIError(f"Invalid API response: {e}")
 
     async def get_rate(
-        self, from_currency: str, to_currency: str, date: Optional[DateType] = None
+        self, from_currency: str, to_currency: str, date: DateType | None = None
     ) -> ExchangeRate:
         """
         Get exchange rate between two currencies.

fin_infra/normalization/providers/static_mappings.py

@@ -109,7 +109,7 @@ TICKER_TO_ISIN = {
 }
 
 # Provider-specific symbol normalization
-# Maps provider-specific format → standard ticker
+# Maps provider-specific format -> standard ticker
 PROVIDER_SYMBOL_MAP = {
     "yahoo": {
         # Yahoo Finance uses dashes for crypto

fin_infra/normalization/symbol_resolver.py

@@ -1,7 +1,6 @@
 """Symbol resolver for converting between ticker formats."""
 
 import logging
-from typing import Optional
 
 from fin_infra.exceptions import SymbolNotFoundError
 from fin_infra.normalization.models import SymbolMetadata
@@ -231,9 +230,9 @@ class SymbolResolver:
     def add_mapping(
         self,
         ticker: str,
-        cusip: Optional[str] = None,
-        isin: Optional[str] = None,
-        metadata: Optional[dict] = None,
+        cusip: str | None = None,
+        isin: str | None = None,
+        metadata: dict | None = None,
     ):
         """
         Add or override a symbol mapping (useful for custom symbols).

fin_infra/obs/classifier.py

@@ -37,7 +37,7 @@ Usage:
 
 from __future__ import annotations
 
-from typing import Callable
+from collections.abc import Callable
 
 # Financial capability prefix patterns (extensible)
 FINANCIAL_ROUTE_PREFIXES = (
@@ -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