Initial commit: Vault Dashboard for options hedging

- FastAPI + NiceGUI web application
- QuantLib-based Black-Scholes pricing with Greeks
- Protective put, laddered, and LEAPS strategies
- Real-time WebSocket updates
- TradingView-style charts via Lightweight-Charts
- Docker containerization
- GitLab CI/CD pipeline for VPS deployment
- VPN-only access configuration

app/models/portfolio.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class LombardPortfolio:
+    """Lombard loan portfolio backed by physical gold.
+
+    Attributes:
+        gold_ounces: Quantity of pledged gold in troy ounces.
+        gold_price_per_ounce: Current gold spot price per ounce.
+        loan_amount: Outstanding Lombard loan balance.
+        initial_ltv: Origination or current reference loan-to-value ratio.
+        margin_call_ltv: LTV threshold at which a margin call is triggered.
+    """
+
+    gold_ounces: float
+    gold_price_per_ounce: float
+    loan_amount: float
+    initial_ltv: float
+    margin_call_ltv: float
+
+    def __post_init__(self) -> None:
+        if self.gold_ounces <= 0:
+            raise ValueError("gold_ounces must be positive")
+        if self.gold_price_per_ounce <= 0:
+            raise ValueError("gold_price_per_ounce must be positive")
+        if self.loan_amount < 0:
+            raise ValueError("loan_amount must be non-negative")
+        if not 0 < self.initial_ltv < 1:
+            raise ValueError("initial_ltv must be between 0 and 1")
+        if not 0 < self.margin_call_ltv < 1:
+            raise ValueError("margin_call_ltv must be between 0 and 1")
+        if self.initial_ltv > self.margin_call_ltv:
+            raise ValueError("initial_ltv cannot exceed margin_call_ltv")
+        if self.loan_amount > self.gold_value:
+            raise ValueError("loan_amount cannot exceed current gold value")
+
+    @property
+    def gold_value(self) -> float:
+        """Current market value of pledged gold."""
+        return self.gold_ounces * self.gold_price_per_ounce
+
+    @property
+    def current_ltv(self) -> float:
+        """Current loan-to-value ratio."""
+        return self.loan_amount / self.gold_value
+
+    @property
+    def net_equity(self) -> float:
+        """Equity remaining after subtracting the loan from gold value."""
+        return self.gold_value - self.loan_amount
+
+    def gold_value_at_price(self, gold_price_per_ounce: float) -> float:
+        """Gold value under an alternative spot-price scenario."""
+        if gold_price_per_ounce <= 0:
+            raise ValueError("gold_price_per_ounce must be positive")
+        return self.gold_ounces * gold_price_per_ounce
+
+    def ltv_at_price(self, gold_price_per_ounce: float) -> float:
+        """Portfolio LTV under an alternative gold-price scenario."""
+        return self.loan_amount / self.gold_value_at_price(gold_price_per_ounce)
+
+    def net_equity_at_price(self, gold_price_per_ounce: float) -> float:
+        """Net equity under an alternative gold-price scenario."""
+        return self.gold_value_at_price(gold_price_per_ounce) - self.loan_amount
+
+    def margin_call_price(self) -> float:
+        """Gold price per ounce at which the portfolio breaches the margin LTV."""
+        return self.loan_amount / (self.margin_call_ltv * self.gold_ounces)