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

fin_infra/brokerage/__init__.py

@@ -22,10 +22,12 @@ from typing import TYPE_CHECKING, Literal
 if TYPE_CHECKING:
     from fastapi import FastAPI
 
-from ..providers.base import BrokerageProvider
-from pydantic import BaseModel, Field
 from decimal import Decimal
 
+from pydantic import BaseModel, Field
+
+from ..providers.base import BrokerageProvider
+
 
 # Request model for order submission (used by add_brokerage FastAPI routes)
 class OrderRequest(BaseModel):
@@ -123,11 +125,11 @@ def easy_brokerage(
         )
 
     else:
-        raise ValueError(f"Unknown brokerage provider: {provider_name}. " f"Supported: alpaca")
+        raise ValueError(f"Unknown brokerage provider: {provider_name}. Supported: alpaca")
 
 
 def add_brokerage(
-    app: "FastAPI",
+    app: FastAPI,
     *,
     provider: str | BrokerageProvider | None = None,
     mode: Literal["paper", "live"] = "paper",
@@ -206,13 +208,15 @@ def add_brokerage(
             >>> broker = add_brokerage(app, mode="live")
             >>> # Only use in production with proper safeguards and risk management
     """
-    from svc_infra.api.fastapi.dual.public import public_router
-    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
     from fastapi import HTTPException, Query
+    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
+    from svc_infra.api.fastapi.dual.public import public_router
 
     # Initialize provider if string or None
     if isinstance(provider, str):
-        brokerage_provider = easy_brokerage(provider=provider, mode=mode, **config)
+        # Cast provider string to Literal type for type checker
+        provider_literal: Literal["alpaca"] | None = provider if provider == "alpaca" else None  # type: ignore[assignment]
+        brokerage_provider = easy_brokerage(provider=provider_literal, mode=mode, **config)
     elif provider is None:
         brokerage_provider = easy_brokerage(mode=mode, **config)
     else:
@@ -232,7 +236,7 @@ def add_brokerage(
             account = brokerage_provider.get_account()
             return account
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Error fetching account: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Error fetching account: {e!s}")
 
     @router.get("/positions")
     async def list_positions():
@@ -241,10 +245,10 @@ def add_brokerage(
         Returns list of positions with symbol, quantity, P/L, etc.
         """
         try:
-            positions = brokerage_provider.positions()
+            positions = list(brokerage_provider.positions())  # Convert Iterable to list for len()
             return {"positions": positions, "count": len(positions)}
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Error fetching positions: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Error fetching positions: {e!s}")
 
     @router.get("/positions/{symbol}")
     async def get_position(symbol: str):
@@ -257,9 +261,7 @@ def add_brokerage(
             position = brokerage_provider.get_position(symbol)
             return position
         except Exception as e:
-            raise HTTPException(
-                status_code=404, detail=f"Position not found for {symbol}: {str(e)}"
-            )
+            raise HTTPException(status_code=404, detail=f"Position not found for {symbol}: {e!s}")
 
     @router.delete("/positions/{symbol}")
     async def close_position(symbol: str):
@@ -272,7 +274,7 @@ def add_brokerage(
             order = brokerage_provider.close_position(symbol)
             return {"message": f"Closing position for {symbol}", "order": order}
         except Exception as e:
-            raise HTTPException(status_code=400, detail=f"Error closing position: {str(e)}")
+            raise HTTPException(status_code=400, detail=f"Error closing position: {e!s}")
 
     @router.post("/orders")
     async def submit_order(order_request: OrderRequest):
@@ -293,7 +295,7 @@ def add_brokerage(
             )
             return order
         except Exception as e:
-            raise HTTPException(status_code=400, detail=f"Error submitting order: {str(e)}")
+            raise HTTPException(status_code=400, detail=f"Error submitting order: {e!s}")
 
     @router.get("/orders")
     async def list_orders(
@@ -310,7 +312,7 @@ def add_brokerage(
             orders = brokerage_provider.list_orders(status=status, limit=limit)
             return {"orders": orders, "count": len(orders)}
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Error fetching orders: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Error fetching orders: {e!s}")
 
     @router.get("/orders/{order_id}")
     async def get_order(order_id: str):
@@ -323,7 +325,7 @@ def add_brokerage(
             order = brokerage_provider.get_order(order_id)
             return order
         except Exception as e:
-            raise HTTPException(status_code=404, detail=f"Order not found: {str(e)}")
+            raise HTTPException(status_code=404, detail=f"Order not found: {e!s}")
 
     @router.delete("/orders/{order_id}")
     async def cancel_order(order_id: str):
@@ -336,7 +338,7 @@ def add_brokerage(
             brokerage_provider.cancel_order(order_id)
             return {"message": f"Order {order_id} canceled successfully"}
         except Exception as e:
-            raise HTTPException(status_code=400, detail=f"Error canceling order: {str(e)}")
+            raise HTTPException(status_code=400, detail=f"Error canceling order: {e!s}")
 
     @router.get("/portfolio/history")
     async def get_portfolio_history(
@@ -353,9 +355,7 @@ def add_brokerage(
             history = brokerage_provider.get_portfolio_history(period=period, timeframe=timeframe)
             return history
         except Exception as e:
-            raise HTTPException(
-                status_code=500, detail=f"Error fetching portfolio history: {str(e)}"
-            )
+            raise HTTPException(status_code=500, detail=f"Error fetching portfolio history: {e!s}")
 
     # Watchlist routes
     @router.post("/watchlists")
@@ -373,7 +373,7 @@ def add_brokerage(
             watchlist = brokerage_provider.create_watchlist(name=name, symbols=symbols)
             return watchlist
         except Exception as e:
-            raise HTTPException(status_code=400, detail=f"Error creating watchlist: {str(e)}")
+            raise HTTPException(status_code=400, detail=f"Error creating watchlist: {e!s}")
 
     @router.get("/watchlists")
     async def list_watchlists():
@@ -382,7 +382,7 @@ def add_brokerage(
             watchlists = brokerage_provider.list_watchlists()
             return {"watchlists": watchlists, "count": len(watchlists)}
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Error fetching watchlists: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Error fetching watchlists: {e!s}")
 
     @router.get("/watchlists/{watchlist_id}")
     async def get_watchlist(watchlist_id: str):
@@ -395,7 +395,7 @@ def add_brokerage(
             watchlist = brokerage_provider.get_watchlist(watchlist_id)
             return watchlist
         except Exception as e:
-            raise HTTPException(status_code=404, detail=f"Watchlist not found: {str(e)}")
+            raise HTTPException(status_code=404, detail=f"Watchlist not found: {e!s}")
 
     @router.delete("/watchlists/{watchlist_id}")
     async def delete_watchlist(watchlist_id: str):
@@ -408,7 +408,7 @@ def add_brokerage(
             brokerage_provider.delete_watchlist(watchlist_id)
             return {"message": f"Watchlist {watchlist_id} deleted successfully"}
         except Exception as e:
-            raise HTTPException(status_code=400, detail=f"Error deleting watchlist: {str(e)}")
+            raise HTTPException(status_code=400, detail=f"Error deleting watchlist: {e!s}")
 
     @router.post("/watchlists/{watchlist_id}/symbols")
     async def add_to_watchlist(
@@ -424,7 +424,7 @@ def add_brokerage(
             watchlist = brokerage_provider.add_to_watchlist(watchlist_id, symbol)
             return watchlist
         except Exception as e:
-            raise HTTPException(status_code=400, detail=f"Error adding symbol: {str(e)}")
+            raise HTTPException(status_code=400, detail=f"Error adding symbol: {e!s}")
 
     @router.delete("/watchlists/{watchlist_id}/symbols/{symbol}")
     async def remove_from_watchlist(watchlist_id: str, symbol: str):
@@ -438,7 +438,7 @@ def add_brokerage(
             watchlist = brokerage_provider.remove_from_watchlist(watchlist_id, symbol)
             return watchlist
         except Exception as e:
-            raise HTTPException(status_code=400, detail=f"Error removing symbol: {str(e)}")
+            raise HTTPException(status_code=400, detail=f"Error removing symbol: {e!s}")
 
     # Mount router
     app.include_router(router, include_in_schema=True)

fin_infra/budgets/__init__.py

@@ -105,12 +105,12 @@ def __getattr__(name: str):
     ):
         from fin_infra.budgets.models import (  # noqa: F401
             Budget,
-            BudgetType,
-            BudgetPeriod,
+            BudgetAlert,
             BudgetCategory,
+            BudgetPeriod,
             BudgetProgress,
-            BudgetAlert,
             BudgetTemplate,
+            BudgetType,
         )
 
         return locals()[name]

fin_infra/budgets/add.py

@@ -22,7 +22,6 @@ Generic Design:
 from __future__ import annotations
 
 from datetime import datetime
-from typing import Optional
 
 from fastapi import FastAPI, HTTPException, Query
 from pydantic import BaseModel, Field
@@ -42,16 +41,16 @@ class CreateBudgetRequest(BaseModel):
     type: BudgetType = Field(..., description="Budget type")
     period: BudgetPeriod = Field(..., description="Budget period")
     categories: dict[str, float] = Field(..., description="Category allocations")
-    start_date: Optional[datetime] = Field(None, description="Start date (defaults to now)")
+    start_date: datetime | None = Field(None, description="Start date (defaults to now)")
     rollover_enabled: bool = Field(False, description="Enable rollover")
 
 
 class UpdateBudgetRequest(BaseModel):
     """Request model for updating a budget."""
 
-    name: Optional[str] = Field(None, description="Updated budget name")
-    categories: Optional[dict[str, float]] = Field(None, description="Updated categories")
-    rollover_enabled: Optional[bool] = Field(None, description="Updated rollover setting")
+    name: str | None = Field(None, description="Updated budget name")
+    categories: dict[str, float] | None = Field(None, description="Updated categories")
+    rollover_enabled: bool | None = Field(None, description="Updated rollover setting")
 
 
 class ApplyTemplateRequest(BaseModel):
@@ -60,14 +59,14 @@ class ApplyTemplateRequest(BaseModel):
     user_id: str = Field(..., description="User identifier")
     template_name: str = Field(..., description="Template name (e.g., '50_30_20')")
     total_income: float = Field(..., description="Total income/budget amount", gt=0)
-    budget_name: Optional[str] = Field(None, description="Optional budget name")
-    start_date: Optional[datetime] = Field(None, description="Optional start date")
+    budget_name: str | None = Field(None, description="Optional budget name")
+    start_date: datetime | None = Field(None, description="Optional start date")
 
 
 def add_budgets(
     app: FastAPI,
-    tracker: Optional[BudgetTracker] = None,
-    db_url: Optional[str] = None,
+    tracker: BudgetTracker | None = None,
+    db_url: str | None = None,
     prefix: str = "/budgets",
 ) -> BudgetTracker:
     """Add budget management endpoints to FastAPI app.
@@ -162,13 +161,13 @@ def add_budgets(
         except ValueError as e:
             raise HTTPException(status_code=400, detail=str(e))
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Failed to create budget: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to create budget: {e!s}")
 
     # Endpoint 2: List budgets
     @router.get("", response_model=list[Budget], summary="List Budgets")
     async def list_budgets(
         user_id: str = Query(..., description="User identifier"),
-        type: Optional[BudgetType] = Query(None, description="Filter by budget type"),
+        type: BudgetType | None = Query(None, description="Filter by budget type"),
     ) -> list[Budget]:
         """
         List budgets for a user.
@@ -189,7 +188,7 @@ def add_budgets(
             budgets = await tracker.get_budgets(user_id=user_id, type=type)
             return budgets
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Failed to list budgets: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to list budgets: {e!s}")
 
     # Endpoint 3: Get single budget
     @router.get("/{budget_id}", response_model=Budget, summary="Get Budget")
@@ -217,7 +216,7 @@ def add_budgets(
         except ValueError as e:
             raise HTTPException(status_code=404, detail=str(e))
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Failed to get budget: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to get budget: {e!s}")
 
     # Endpoint 4: Update budget
     @router.patch("/{budget_id}", response_model=Budget, summary="Update Budget")
@@ -269,7 +268,7 @@ def add_budgets(
             else:
                 raise HTTPException(status_code=400, detail=error_msg)
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Failed to update budget: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to update budget: {e!s}")
 
     # Endpoint 5: Delete budget
     @router.delete("/{budget_id}", status_code=204, summary="Delete Budget", response_model=None)
@@ -296,7 +295,7 @@ def add_budgets(
         except ValueError as e:
             raise HTTPException(status_code=404, detail=str(e))
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Failed to delete budget: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to delete budget: {e!s}")
 
     # Endpoint 6: Get budget progress
     @router.get(
@@ -328,7 +327,7 @@ def add_budgets(
         except ValueError as e:
             raise HTTPException(status_code=404, detail=str(e))
         except Exception as e:
-            raise HTTPException(status_code=500, detail=f"Failed to get budget progress: {str(e)}")
+            raise HTTPException(status_code=500, detail=f"Failed to get budget progress: {e!s}")
 
     # Endpoint 7: List templates
     @router.get("/templates/list", response_model=dict, summary="List Budget Templates")
@@ -402,7 +401,7 @@ def add_budgets(
             raise HTTPException(status_code=400, detail=str(e))
         except Exception as e:
             raise HTTPException(
-                status_code=500, detail=f"Failed to create budget from template: {str(e)}"
+                status_code=500, detail=f"Failed to create budget from template: {e!s}"
             )
 
     # Mount router

fin_infra/budgets/alerts.py

@@ -35,7 +35,7 @@ Example:
 from __future__ import annotations
 
 from datetime import datetime
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, Optional
 
 from fin_infra.budgets.models import (
     AlertSeverity,
@@ -52,7 +52,7 @@ async def check_budget_alerts(
     budget_id: str,
     tracker: BudgetTracker,
     thresholds: Optional[dict[str, float]] = None,
-) -> List[BudgetAlert]:
+) -> list[BudgetAlert]:
     """
     Check budget for alerts (overspending, approaching limits, unusual patterns).
 
@@ -111,7 +111,7 @@ async def check_budget_alerts(
     # Get budget progress
     progress = await tracker.get_budget_progress(budget_id)
 
-    alerts: List[BudgetAlert] = []
+    alerts: list[BudgetAlert] = []
 
     # Check each category for alerts
     for category in progress.categories:

fin_infra/budgets/tracker.py

@@ -36,7 +36,7 @@ from __future__ import annotations
 
 import uuid
 from datetime import datetime, timedelta
-from typing import TYPE_CHECKING, List, Optional
+from typing import TYPE_CHECKING, Optional
 
 from sqlalchemy.ext.asyncio import async_sessionmaker
 
@@ -155,7 +155,7 @@ class BudgetTracker:
             BudgetType(type)
         except ValueError:
             raise ValueError(
-                f"Invalid budget type: {type}. " f"Valid types: {[t.value for t in BudgetType]}"
+                f"Invalid budget type: {type}. Valid types: {[t.value for t in BudgetType]}"
             )
 
         # Validate budget period
@@ -163,8 +163,7 @@ class BudgetTracker:
             BudgetPeriod(period)
         except ValueError:
             raise ValueError(
-                f"Invalid budget period: {period}. "
-                f"Valid periods: {[p.value for p in BudgetPeriod]}"
+                f"Invalid budget period: {period}. Valid periods: {[p.value for p in BudgetPeriod]}"
             )
 
         # Validate categories
@@ -207,7 +206,7 @@ class BudgetTracker:
         self,
         user_id: str,
         type: Optional[str] = None,
-    ) -> List[Budget]:
+    ) -> list[Budget]:
         """
         Get all budgets for a user.
 

fin_infra/cashflows/__init__.py

@@ -22,11 +22,14 @@ Example usage:
     rate = irr(cashflows)
 """
 
-from typing import Iterable
+from typing import TYPE_CHECKING
 
 import numpy_financial as npf
 
-from .core import npv, irr
+if TYPE_CHECKING:
+    from fastapi import FastAPI
+
+from .core import irr, npv
 
 __all__ = ["npv", "irr", "pmt", "fv", "pv", "add_cashflows"]
 
@@ -110,7 +113,7 @@ def pv(rate: float, nper: int, pmt: float, fv: float = 0, when: str = "end") ->
 
 
 def add_cashflows(
-    app: "FastAPI",  # type: ignore
+    app: "FastAPI",
     *,
     prefix: str = "/cashflows",
 ) -> None:
@@ -169,16 +172,11 @@ def add_cashflows(
         - Integrated with svc-infra observability
         - Scoped docs at {prefix}/docs
     """
-    from typing import TYPE_CHECKING
-
-    if TYPE_CHECKING:
-        from fastapi import FastAPI
-
     from pydantic import BaseModel, Field
+    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
 
     # Import svc-infra public router (no auth - utility calculations)
     from svc_infra.api.fastapi.dual.public import public_router
-    from svc_infra.api.fastapi.docs.scoped import add_prefixed_docs
 
     # Request/Response models
     class NPVRequest(BaseModel):
@@ -254,4 +252,4 @@ def add_cashflows(
     # Mount router
     app.include_router(router, include_in_schema=True)
 
-    print(f"✅ Cashflow calculations enabled (NPV, IRR, PMT, FV, PV)")
+    print("Cashflow calculations enabled (NPV, IRR, PMT, FV, PV)")

fin_infra/cashflows/core.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import Iterable
+from collections.abc import Iterable
 
 import numpy as np
 import numpy_financial as npf

fin_infra/categorization/__init__.py

@@ -44,7 +44,7 @@ from .taxonomy import Category, CategoryGroup, get_all_categories, get_category_
 try:
     from .llm_layer import LLMCategorizer
 except ImportError:
-    LLMCategorizer = None
+    LLMCategorizer = None  # type: ignore[assignment,misc]
 
 __all__ = [
     # Easy setup

fin_infra/categorization/add.py

@@ -6,10 +6,10 @@ Uses svc-infra dual routers for consistent behavior.
 """
 
 import time
-from typing import Optional
 
 from fastapi import FastAPI, HTTPException
 
+from . import rules
 from .ease import easy_categorization
 from .engine import CategorizationEngine
 from .models import (
@@ -18,7 +18,6 @@ from .models import (
     CategoryStats,
 )
 from .taxonomy import CategoryGroup, count_categories, get_all_categories
-from . import rules
 
 
 def add_categorization(
@@ -96,7 +95,8 @@ def add_categorization(
         start_time = time.perf_counter()
 
         try:
-            prediction = engine.categorize(
+            # Await the async categorize method
+            prediction = await engine.categorize(
                 merchant_name=request.merchant_name,
                 user_id=request.user_id,
                 include_alternatives=request.include_alternatives,
@@ -121,7 +121,7 @@ def add_categorization(
             raise HTTPException(status_code=400, detail=str(e))
 
     @router.get("/categories")
-    async def list_categories(group: Optional[CategoryGroup] = None):
+    async def list_categories(group: CategoryGroup | None = None):
         """
         List all available categories.
 
@@ -135,21 +135,19 @@ def add_categorization(
             categories = get_all_categories()
 
         # Return category metadata
-        return [
-            {
-                "name": cat.value,
-                "group": get_category_metadata(cat).group.value
-                if get_category_metadata(cat)
-                else None,
-                "display_name": get_category_metadata(cat).display_name
-                if get_category_metadata(cat)
-                else cat.value,
-                "description": get_category_metadata(cat).description
-                if get_category_metadata(cat)
-                else None,
-            }
-            for cat in categories
-        ]
+        result = []
+        for cat in categories:
+            meta = get_category_metadata(cat)
+            result.append(
+                {
+                    "name": cat.value,
+                    "group": meta.group.value if meta else None,
+                    "display_name": meta.display_name if meta else cat.value,
+                    "description": meta.description if meta else None,
+                }
+            )
+
+        return result
 
     @router.get("/stats", response_model=CategoryStats)
     async def get_stats():

fin_infra/categorization/ease.py

@@ -13,7 +13,7 @@ from .engine import CategorizationEngine
 try:
     from .llm_layer import LLMCategorizer
 except ImportError:
-    LLMCategorizer = None
+    LLMCategorizer = None  # type: ignore[assignment,misc]
 
 
 def easy_categorization(
@@ -113,7 +113,7 @@ def easy_categorization(
     if enable_llm:
         if LLMCategorizer is None:
             raise ImportError(
-                "LLM support requires ai-infra package. " "Install with: pip install ai-infra"
+                "LLM support requires ai-infra package. Install with: pip install ai-infra"
             )
 
         # Map provider names to ai-infra provider format
@@ -125,8 +125,7 @@ def easy_categorization(
         ai_infra_provider = provider_map.get(llm_provider)
         if not ai_infra_provider:
             raise ValueError(
-                f"Unsupported LLM provider: {llm_provider}. "
-                f"Use 'google', 'openai', or 'anthropic'."
+                f"Unsupported LLM provider: {llm_provider}. Use 'google', 'openai', or 'anthropic'."
             )
 
         # Default models per provider

fin_infra/categorization/engine.py

@@ -10,8 +10,8 @@ Hybrid categorization engine (exact → regex → ML → LLM).
 Expected overall accuracy: 95-97% (V2 with LLM)
 """
 
-import time
 import logging
+import time
 from pathlib import Path
 from typing import Optional
 
@@ -23,7 +23,7 @@ from .taxonomy import Category
 try:
     from .llm_layer import LLMCategorizer
 except ImportError:
-    LLMCategorizer = None
+    LLMCategorizer = None  # type: ignore[assignment,misc]
 
 logger = logging.getLogger(__name__)
 
@@ -51,7 +51,7 @@ class CategorizationEngine:
         enable_ml: bool = False,
         enable_llm: bool = False,
         confidence_threshold: float = 0.6,
-        model_path: Optional[Path] = None,
+        model_path: Path | None = None,
         llm_categorizer: Optional["LLMCategorizer"] = None,
     ):
         self.enable_ml = enable_ml
@@ -81,7 +81,7 @@ class CategorizationEngine:
     async def categorize(
         self,
         merchant_name: str,
-        user_id: Optional[str] = None,
+        user_id: str | None = None,
         include_alternatives: bool = False,
     ) -> CategoryPrediction:
         """
@@ -95,7 +95,7 @@ class CategorizationEngine:
         Returns:
             CategoryPrediction with category, confidence, and method
         """
-        start_time = time.perf_counter()
+        time.perf_counter()
 
         # Normalize merchant name
         normalized = self._normalize(merchant_name)
@@ -195,7 +195,7 @@ class CategorizationEngine:
 
     def _predict_ml(
         self, merchant_name: str, include_alternatives: bool = False
-    ) -> Optional[CategoryPrediction]:
+    ) -> CategoryPrediction | None:
         """
         Predict category using ML model.
 
@@ -251,8 +251,7 @@ class CategorizationEngine:
             )
 
         except Exception as e:
-            # Log error and return None (will fallback to uncategorized)
-            print(f"ML prediction error: {e}")
+            logger.error("ML prediction error: %s", e)
             return None
 
     def _load_ml_model(self) -> None:
@@ -273,8 +272,10 @@ class CategorizationEngine:
         vectorizer_file = self.model_path / "vectorizer.joblib"
 
         if not model_file.exists() or not vectorizer_file.exists():
-            print(f"ML model not found at {self.model_path}")
-            print("Run training script to generate model files")
+            logger.warning(
+                "ML model not found at %s. Run training script to generate model files.",
+                self.model_path,
+            )
             return
 
         try:
@@ -282,12 +283,14 @@ class CategorizationEngine:
 
             self._ml_model = joblib.load(model_file)
             self._ml_vectorizer = joblib.load(vectorizer_file)
-            print(f"Loaded ML model from {self.model_path}")
+            logger.info("Loaded ML model from %s", self.model_path)
         except ImportError:
-            print("scikit-learn not installed. ML predictions disabled.")
-            print("Install with: pip install scikit-learn")
+            logger.warning(
+                "scikit-learn not installed. ML predictions disabled. "
+                "Install with: pip install scikit-learn"
+            )
         except Exception as e:
-            print(f"Error loading ML model: {e}")
+            logger.error("Error loading ML model: %s", e)
 
     def add_rule(
         self,
@@ -322,7 +325,7 @@ class CategorizationEngine:
 
 
 # Singleton instance (for easy access)
-_default_engine: Optional[CategorizationEngine] = None
+_default_engine: CategorizationEngine | None = None
 
 
 def get_engine() -> CategorizationEngine:
@@ -333,9 +336,9 @@ def get_engine() -> CategorizationEngine:
     return _default_engine
 
 
-def categorize(
+async def categorize(
     merchant_name: str,
-    user_id: Optional[str] = None,
+    user_id: str | None = None,
     include_alternatives: bool = False,
 ) -> CategoryPrediction:
     """
@@ -350,4 +353,4 @@ def categorize(
         CategoryPrediction with category, confidence, and method
     """
     engine = get_engine()
-    return engine.categorize(merchant_name, user_id, include_alternatives)
+    return await engine.categorize(merchant_name, user_id, include_alternatives)