portfolio-risk-engine 0.1.0__tar.gz

portfolio_risk_engine-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.DS_Store
+*.egg
+.venv/
+venv/

portfolio_risk_engine-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Chien
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

portfolio_risk_engine-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: portfolio-risk-engine
+Version: 0.1.0
+Summary: Standalone portfolio risk analytics engine
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: cvxpy
+Requires-Dist: numpy
+Requires-Dist: pandas
+Requires-Dist: pyarrow
+Requires-Dist: pyyaml
+Requires-Dist: requests
+Requires-Dist: statsmodels
+Description-Content-Type: text/markdown
+
+# portfolio-risk-engine
+
+Standalone portfolio risk analytics engine extracted from the risk_module monorepo.

portfolio_risk_engine-0.1.0/README.md

@@ -0,0 +1,3 @@
+# portfolio-risk-engine
+
+Standalone portfolio risk analytics engine extracted from the risk_module monorepo.

portfolio_risk_engine-0.1.0/portfolio_risk_engine/__init__.py

@@ -0,0 +1,27 @@
+"""Public API for portfolio_risk_engine."""
+
+from portfolio_risk_engine.portfolio_risk import (
+    build_portfolio_view,
+    normalize_weights,
+    calculate_portfolio_performance_metrics,
+)
+from portfolio_risk_engine.providers import (
+    PriceProvider,
+    FXProvider,
+    set_price_provider,
+    get_price_provider,
+    set_fx_provider,
+    get_fx_provider,
+)
+
+__all__ = [
+    "build_portfolio_view",
+    "normalize_weights",
+    "calculate_portfolio_performance_metrics",
+    "PriceProvider",
+    "FXProvider",
+    "set_price_provider",
+    "get_price_provider",
+    "set_fx_provider",
+    "get_fx_provider",
+]

portfolio_risk_engine-0.1.0/portfolio_risk_engine/_fmp_provider.py

@@ -0,0 +1,91 @@
+"""Default lazy FMP-backed providers for standalone or monorepo usage."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import pandas as pd
+
+from portfolio_risk_engine._ticker import select_fmp_symbol
+
+
+class FMPPriceProvider:
+    """Thin adapter over fmp.compat with lazy imports."""
+
+    def fetch_monthly_close(self, ticker, start_date=None, end_date=None, **kw) -> pd.Series:
+        from fmp.compat import fetch_monthly_close as _fn  # type: ignore
+
+        return _fn(ticker, start_date, end_date, **kw)
+
+    def fetch_monthly_total_return_price(self, ticker, start_date=None, end_date=None, **kw) -> pd.Series:
+        from fmp.compat import fetch_monthly_total_return_price as _fn  # type: ignore
+
+        return _fn(ticker, start_date, end_date, **kw)
+
+    def fetch_monthly_treasury_rates(self, maturity: str, start_date=None, end_date=None) -> pd.Series:
+        from fmp.compat import fetch_monthly_treasury_rates as _fn  # type: ignore
+
+        return _fn(maturity, start_date, end_date)
+
+    def fetch_dividend_history(self, ticker, start_date=None, end_date=None, **kw) -> pd.DataFrame:
+        from fmp.compat import fetch_dividend_history as _fn  # type: ignore
+
+        return _fn(ticker, start_date, end_date, **kw)
+
+    def fetch_current_dividend_yield(self, ticker, **kw) -> float:
+        # Keep this lightweight and consistent with existing implementation:
+        # compute from dividend history + latest month-end close.
+        fmp_symbol = select_fmp_symbol(
+            ticker,
+            fmp_ticker=kw.get("fmp_ticker"),
+            fmp_ticker_map=kw.get("fmp_ticker_map"),
+        )
+
+        lookback_months = int((kw.get("lookback_months") or 12))
+        end_month = (pd.Timestamp.today().to_period("M") - 1).to_timestamp("M")
+        start_month = end_month - pd.DateOffset(months=lookback_months - 1)
+
+        div_df = self.fetch_dividend_history(
+            fmp_symbol,
+            start_month,
+            end_month,
+            fmp_ticker=fmp_symbol,
+        )
+        if isinstance(div_df, pd.Series):
+            div_df = div_df.to_frame(name="adjDividend")
+        if div_df is None or div_df.empty:
+            return 0.0
+
+        annual_dividends = pd.to_numeric(
+            div_df.get("adjDividend", pd.Series(dtype=float)),
+            errors="coerce",
+        ).fillna(0.0).sum()
+
+        prices = self.fetch_monthly_close(
+            fmp_symbol,
+            None,
+            end_month.date().isoformat(),
+            fmp_ticker=fmp_symbol,
+        )
+        if prices is None or prices.dropna().empty:
+            return 0.0
+
+        current_price = float(prices.dropna().iloc[-1])
+        if current_price <= 0 or annual_dividends <= 0:
+            return 0.0
+
+        return round(float((annual_dividends / current_price) * 100.0), 4)
+
+
+class FMPFXProvider:
+    """Optional FX adapter over fmp.fx."""
+
+    def adjust_returns_for_fx(self, returns: pd.Series, currency: str, **kw):
+        from fmp.fx import adjust_returns_for_fx as _fn  # type: ignore
+
+        return _fn(returns, currency, **kw)
+
+    def get_fx_rate(self, currency: str) -> float:
+        from fmp.fx import get_fx_rate as _fn  # type: ignore
+
+        return float(_fn(currency))

portfolio_risk_engine-0.1.0/portfolio_risk_engine/_logging.py

@@ -0,0 +1,57 @@
+"""Logging shim.
+
+Uses monorepo logging when available. Falls back to stdlib logging and no-op
+instrumentation decorators in standalone mode.
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+from typing import Any, Callable
+
+
+try:  # pragma: no cover - preferred in monorepo
+    from utils.logging import (  # type: ignore
+        portfolio_logger,
+        log_operation,
+        log_timing,
+        log_errors,
+        log_portfolio_operation,
+        log_critical_alert,
+        log_service_health,
+    )
+except Exception:  # pragma: no cover - standalone fallback
+    portfolio_logger = logging.getLogger("portfolio_risk_engine")
+
+    def _identity_decorator(_arg: Any = None) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        def deco(fn: Callable[..., Any]) -> Callable[..., Any]:
+            @functools.wraps(fn)
+            def wrapper(*args: Any, **kwargs: Any) -> Any:
+                return fn(*args, **kwargs)
+
+            return wrapper
+
+        return deco
+
+    def log_operation(_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        return _identity_decorator()
+
+    def log_timing(_threshold: float = 0.0) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        return _identity_decorator()
+
+    def log_errors(_severity: str = "medium") -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        return _identity_decorator()
+
+    def log_portfolio_operation(_event: str, _details: dict[str, Any] | None = None, execution_time: float | None = None) -> dict[str, Any]:
+        if _details:
+            portfolio_logger.info("[%s] %s", _event, _details)
+        else:
+            portfolio_logger.info("[%s]", _event)
+        return {"event": _event, "details": _details or {}, "execution_time": execution_time}
+
+    def log_critical_alert(_alert_type: str, _severity: str, message: str, _action: str | None = None, details: dict[str, Any] | None = None) -> None:
+        portfolio_logger.warning("critical_alert: %s %s", message, details or {})
+
+    def log_service_health(service: str, status: str, response_time: float | None = None, details: dict[str, Any] | None = None) -> None:
+        portfolio_logger.info("service_health: %s %s %.3f %s", service, status, response_time or 0.0, details or {})

portfolio_risk_engine-0.1.0/portfolio_risk_engine/_ticker.py

@@ -0,0 +1,59 @@
+"""Minimal ticker/currency resolver helpers for standalone mode."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def normalize_currency(currency: Optional[str]) -> Optional[str]:
+    if not currency:
+        return None
+    ccy = str(currency).upper()
+    aliases = {
+        "GBX": "GBP",
+        "GBP": "GBP",
+    }
+    return aliases.get(ccy, ccy)
+
+
+def select_fmp_symbol(
+    ticker: str,
+    *,
+    fmp_ticker: Optional[str] = None,
+    fmp_ticker_map: Optional[dict[str, str]] = None,
+) -> str:
+    if fmp_ticker:
+        return fmp_ticker
+    if fmp_ticker_map and ticker in fmp_ticker_map:
+        mapped = fmp_ticker_map.get(ticker)
+        if mapped:
+            return mapped
+    return ticker
+
+
+def normalize_fmp_price(price: Optional[float], currency: Optional[str]) -> tuple[Optional[float], str]:
+    if price is None:
+        return None, (currency or "USD")
+    ccy = normalize_currency(currency) or "USD"
+    minor = {
+        "GBX": ("GBP", 100.0),
+    }
+    if ccy in minor:
+        base_ccy, divisor = minor[ccy]
+        return (float(price) / divisor), base_ccy
+    return float(price), ccy
+
+
+def fetch_fmp_quote_with_currency(symbol: str) -> tuple[Optional[float], Optional[str]]:
+    if not symbol:
+        return None, None
+    try:  # pragma: no cover - best effort live fetch
+        from fmp.client import FMPClient  # type: ignore
+
+        data = FMPClient().fetch_raw("profile", symbol=symbol)
+        if isinstance(data, list) and data:
+            row = data[0] or {}
+            return row.get("price"), row.get("currency")
+    except Exception:
+        pass
+    return None, None

portfolio_risk_engine-0.1.0/portfolio_risk_engine/_vendor.py

@@ -0,0 +1,76 @@
+"""Small vendored helpers for standalone-safe serialization/coercion."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+try:
+    import numpy as np
+except Exception:  # pragma: no cover
+    np = None
+
+try:
+    import pandas as pd
+except Exception:  # pragma: no cover
+    pd = None
+
+
+def make_json_safe(obj: Any) -> Any:
+    """Recursively convert values into JSON-serializable forms."""
+    if isinstance(obj, dict):
+        out = {}
+        for key, value in obj.items():
+            if pd is not None and isinstance(key, (pd.Timestamp, datetime)):
+                safe_key = key.strftime("%Y-%m-%d %H:%M:%S")
+            elif isinstance(key, (int, float, str, bool, type(None))):
+                safe_key = key
+            else:
+                safe_key = str(key)
+            out[safe_key] = make_json_safe(value)
+        return out
+
+    if isinstance(obj, list):
+        return [make_json_safe(item) for item in obj]
+
+    if pd is not None and isinstance(obj, pd.DataFrame):
+        return obj.to_dict("records")
+
+    if pd is not None and isinstance(obj, pd.Series):
+        return {str(k): make_json_safe(v) for k, v in obj.to_dict().items()}
+
+    if np is not None and isinstance(obj, np.ndarray):
+        return obj.tolist()
+
+    if np is not None and isinstance(obj, (np.int64, np.int32)):
+        return int(obj)
+
+    if np is not None and isinstance(obj, (np.float64, np.float32)):
+        return float(obj)
+
+    if np is not None and isinstance(obj, np.bool_):
+        return bool(obj)
+
+    if pd is not None and isinstance(obj, (pd.Timestamp, datetime)):
+        return obj.strftime("%Y-%m-%d %H:%M:%S")
+
+    if pd is not None:
+        try:
+            if pd.isna(obj):
+                return None
+        except Exception:
+            pass
+
+    if isinstance(obj, (int, float, str, bool, type(None))):
+        return obj
+
+    return str(obj)
+
+
+def _to_float(value: Any) -> float | None:
+    try:
+        if value is None:
+            return None
+        return float(value)
+    except (TypeError, ValueError):
+        return None

portfolio_risk_engine-0.1.0/portfolio_risk_engine/asset_class_performance.py

@@ -0,0 +1,103 @@
+"""
+Asset Class Performance - Core Business Logic (monthly-only periods)
+
+Pure functions to compute portfolio asset-class performance over a selected
+monthly period window using cached price data. No logging, no services here.
+"""
+from __future__ import annotations
+
+from typing import Dict
+from datetime import datetime, timedelta
+
+from portfolio_risk_engine.data_loader import fetch_monthly_close
+
+
+SUPPORTED_PERIODS = {"1M", "3M", "6M", "1Y", "YTD"}
+
+
+def get_period_start_date(time_period: str) -> str:
+    """Return ISO date string for the start of the given monthly period.
+
+    Supported periods: 1M, 3M, 6M, 1Y, YTD
+    Defaults to 1M if unknown.
+    """
+    now = datetime.now()
+    period = (time_period or "1M").upper()
+    if period == "3M":
+        start = now - timedelta(days=90)
+    elif period == "6M":
+        start = now - timedelta(days=180)
+    elif period == "1Y":
+        start = now - timedelta(days=365)
+    elif period == "YTD":
+        start = datetime(now.year, 1, 1)
+    else:
+        # Default 1M
+        start = now - timedelta(days=30)
+    return start.strftime("%Y-%m-%d")
+
+
+def group_holdings_by_asset_class(
+    portfolio_weights: Dict[str, float],
+    asset_class_mapping: Dict[str, str]
+) -> Dict[str, Dict[str, float]]:
+    """Group weights by asset class using a ticker→asset_class mapping."""
+    grouped: Dict[str, Dict[str, float]] = {}
+    for ticker, weight in (portfolio_weights or {}).items():
+        asset_class = asset_class_mapping.get(ticker, "unknown")
+        bucket = grouped.setdefault(asset_class, {})
+        bucket[ticker] = weight
+    return grouped
+
+
+def calculate_weighted_portfolio_return(
+    holdings: Dict[str, float],
+    time_period: str,
+    fmp_ticker_map: Dict[str, str] | None = None,
+) -> float:
+    """Compute weighted period return for a set of holdings using monthly closes."""
+    total_weight = sum(holdings.values()) or 0.0
+    if total_weight == 0:
+        return 0.0
+
+    start_date = get_period_start_date(time_period)
+    total_return = 0.0
+    for ticker, weight in holdings.items():
+        series = fetch_monthly_close(
+            ticker,
+            start_date=start_date,
+            fmp_ticker_map=fmp_ticker_map,
+        )
+        if len(series) >= 2:
+            period_ret = (series.iloc[-1] / series.iloc[0]) - 1.0
+            total_return += period_ret * (weight / total_weight)
+    return total_return
+
+
+def calculate_asset_class_returns(
+    asset_class_holdings: Dict[str, Dict[str, float]],
+    time_period: str,
+    fmp_ticker_map: Dict[str, str] | None = None,
+) -> Dict[str, float]:
+    """Calculate weighted returns per asset class for the selected period."""
+    results: Dict[str, float] = {}
+    for asset_class, class_holdings in (asset_class_holdings or {}).items():
+        if not class_holdings:
+            continue
+        results[asset_class] = calculate_weighted_portfolio_return(
+            class_holdings,
+            time_period,
+            fmp_ticker_map=fmp_ticker_map,
+        )
+    return results
+
+
+def classify_performance_change(return_pct: float) -> str:
+    """Classify change as positive/negative/neutral using ±0.5% thresholds."""
+    if return_pct is None:
+        return "neutral"
+    if return_pct > 0.005:
+        return "positive"
+    if return_pct < -0.005:
+        return "negative"
+    return "neutral"

portfolio_risk_engine-0.1.0/portfolio_risk_engine/config.py

@@ -0,0 +1,143 @@
+"""Standalone-safe configuration surface for portfolio_risk_engine."""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+
+def _env_int(name: str, default: int) -> int:
+    try:
+        return int(os.getenv(name, str(default)))
+    except Exception:
+        return default
+
+
+def _env_float(name: str, default: float) -> float:
+    try:
+        return float(os.getenv(name, str(default)))
+    except Exception:
+        return default
+
+
+_DEFAULTS: dict[str, Any] = {
+    "PORTFOLIO_DEFAULTS": {
+        "start_date": os.getenv("PORTFOLIO_DEFAULT_START_DATE", "2019-01-31"),
+        "end_date": os.getenv("PORTFOLIO_DEFAULT_END_DATE", "2026-01-29"),
+        "normalize_weights": os.getenv("PORTFOLIO_DEFAULT_NORMALIZE_WEIGHTS", "false").lower() == "true",
+        "worst_case_lookback_years": _env_int("PORTFOLIO_WORST_CASE_LOOKBACK_YEARS", 10),
+        "expected_returns_lookback_years": _env_int("PORTFOLIO_EXPECTED_RETURNS_LOOKBACK_YEARS", 10),
+        "expected_returns_fallback_default": _env_float("PORTFOLIO_EXPECTED_RETURNS_FALLBACK", 0.06),
+        "cash_proxy_fallback_return": _env_float("PORTFOLIO_CASH_PROXY_FALLBACK_RETURN", 0.02),
+    },
+    "DIVIDEND_DEFAULTS": {
+        "lookback_months": _env_int("DIVIDEND_LOOKBACK_MONTHS", 12),
+        "min_dividend_data_coverage": _env_float("DIVIDEND_MIN_DATA_COVERAGE", 0.7),
+        "include_zero_yield_positions": os.getenv("DIVIDEND_INCLUDE_ZERO_YIELD_POSITIONS", "true").lower() == "true",
+    },
+    "RATE_FACTOR_CONFIG": {
+        "default_maturities": ["UST2Y", "UST5Y", "UST10Y", "UST30Y"],
+        "treasury_mapping": {
+            "UST2Y": "year2",
+            "UST5Y": "year5",
+            "UST10Y": "year10",
+            "UST30Y": "year30",
+        },
+        "min_required_maturities": 2,
+        "scale": "pp",
+        "frequency": "M",
+        "eligible_asset_classes": ["bond", "real_estate"],
+    },
+    "DATA_QUALITY_THRESHOLDS": {
+        "min_observations_for_factor_betas": 2,
+        "min_observations_for_interest_rate_beta": 6,
+        "min_observations_for_peer_validation": 3,
+        "min_peer_overlap_observations": 1,
+        "min_observations_for_returns_calculation": 2,
+        "min_observations_for_regression": 3,
+        "min_valid_peers_for_median": 1,
+        "max_peer_drop_rate": 0.8,
+        "min_observations_for_expected_returns": 11,
+        "min_observations_for_capm_regression": 12,
+        "min_r2_for_rate_factors": 0.3,
+        "max_reasonable_interest_rate_beta": 25,
+    },
+    "RISK_ANALYSIS_THRESHOLDS": {
+        "leverage_warning_threshold": 1.1,
+        "risk_score_safe_threshold": 0.8,
+        "risk_score_caution_threshold": 1.0,
+        "risk_score_danger_threshold": 1.5,
+        "risk_score_critical_threshold": 2.0,
+        "beta_warning_ratio": 0.75,
+        "beta_violation_ratio": 1.0,
+        "herfindahl_warning_threshold": 0.15,
+        "concentration_warning_ratio": 0.8,
+        "volatility_warning_ratio": 0.8,
+        "factor_variance_warning_ratio": 0.8,
+        "market_variance_warning_ratio": 0.8,
+        "variance_contribution_threshold": 0.05,
+        "industry_concentration_warning_ratio": 0.5,
+        "leverage_display_threshold": 1.01,
+    },
+    "WORST_CASE_SCENARIOS": {
+        "market_crash": 0.35,
+        "momentum_crash": 0.50,
+        "value_crash": 0.40,
+        "single_stock_crash": 0.80,
+        "sector_crash": 0.50,
+        "etf_crash": 0.35,
+        "fund_crash": 0.40,
+        "mutual_fund_crash": 0.40,
+        "cash_crash": 0.05,
+        "max_reasonable_volatility": 0.40,
+    },
+    "MAX_SINGLE_FACTOR_LOSS": {
+        "default": -0.10,
+        "sector": -0.08,
+        "portfolio": -0.08,
+    },
+    "SECURITY_TYPE_CRASH_MAPPING": {
+        "equity": "single_stock_crash",
+        "etf": "etf_crash",
+        "fund": "fund_crash",
+        "mutual_fund": "mutual_fund_crash",
+        "cash": "cash_crash",
+    },
+    "DIVIDEND_LRU_SIZE": _env_int("DIVIDEND_LRU_SIZE", 100),
+    "DIVIDEND_DATA_QUALITY_THRESHOLD": _env_float("DIVIDEND_DATA_QUALITY_THRESHOLD", 0.25),
+    "PORTFOLIO_RISK_LRU_SIZE": _env_int("PORTFOLIO_RISK_LRU_SIZE", 100),
+    "FMP_API_KEY": os.getenv("FMP_API_KEY", ""),
+}
+
+
+try:  # pragma: no cover - monorepo defaults
+    import settings as _settings  # type: ignore
+
+    for key in list(_DEFAULTS.keys()):
+        if hasattr(_settings, key):
+            _DEFAULTS[key] = getattr(_settings, key)
+except Exception:
+    pass
+
+
+PORTFOLIO_DEFAULTS = _DEFAULTS["PORTFOLIO_DEFAULTS"]
+DIVIDEND_DEFAULTS = _DEFAULTS["DIVIDEND_DEFAULTS"]
+RATE_FACTOR_CONFIG = _DEFAULTS["RATE_FACTOR_CONFIG"]
+DATA_QUALITY_THRESHOLDS = _DEFAULTS["DATA_QUALITY_THRESHOLDS"]
+RISK_ANALYSIS_THRESHOLDS = _DEFAULTS["RISK_ANALYSIS_THRESHOLDS"]
+WORST_CASE_SCENARIOS = _DEFAULTS["WORST_CASE_SCENARIOS"]
+MAX_SINGLE_FACTOR_LOSS = _DEFAULTS["MAX_SINGLE_FACTOR_LOSS"]
+SECURITY_TYPE_CRASH_MAPPING = _DEFAULTS["SECURITY_TYPE_CRASH_MAPPING"]
+DIVIDEND_LRU_SIZE = int(_DEFAULTS["DIVIDEND_LRU_SIZE"])
+DIVIDEND_DATA_QUALITY_THRESHOLD = float(_DEFAULTS["DIVIDEND_DATA_QUALITY_THRESHOLD"])
+PORTFOLIO_RISK_LRU_SIZE = int(_DEFAULTS["PORTFOLIO_RISK_LRU_SIZE"])
+FMP_API_KEY = str(_DEFAULTS["FMP_API_KEY"])
+
+
+def configure(**overrides: Any) -> None:
+    """Programmatically override package configuration values."""
+    globals_dict = globals()
+    for key, value in overrides.items():
+        if key not in globals_dict:
+            raise KeyError(f"Unknown config key: {key}")
+        globals_dict[key] = value