feat: add portfolio snapshot read layer
This commit is contained in:
@@ -0,0 +1,361 @@
|
||||
"""Portfolio snapshot read + selection (REQ-027/028/029/030/031, dcy-005).
|
||||
|
||||
Application-layer port for reading portfolio-hub universe + in-process
|
||||
snapshot store + asset-selection service. Domain stays free of HTTP and
|
||||
RabbitMQ deps (NFR-1).
|
||||
|
||||
The snapshot is split between:
|
||||
- in-memory `SnapshotStore` universe + cash/position + warnings (process-local;
|
||||
warning is automatic/temporary, reset on restart)
|
||||
- durable `PauseStore` portfolio_id -> paused (Postgres; manual/persistent,
|
||||
survives restart and daily refresh — REQ-032)
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import threading
|
||||
from dataclasses import dataclass, field, replace
|
||||
from datetime import datetime, timezone
|
||||
from enum import Enum
|
||||
from typing import Optional, Protocol
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- portfolio-hub
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class PortfolioItem:
|
||||
"""One asset in the daemon's portfolio universe (REQ-027 AC-1).
|
||||
|
||||
Mirrors portfolio-hub's `list_portfolios_v1` PortfolioItem with **no price
|
||||
field** — pricing is the strategy module's concern, not core's.
|
||||
"""
|
||||
portfolio_id: str # == asset_id, dcy-004 OQ-1
|
||||
symbol: str
|
||||
cash_balance: float
|
||||
asset_quantity: float # integer shares semantically; float for tolerance
|
||||
active_strategy_id: Optional[str] = None
|
||||
strategy_params: dict = field(default_factory=dict) # opaque, pass-through
|
||||
|
||||
|
||||
class PortfolioHubReadError(Exception):
|
||||
"""Base class for portfolio-hub read failures."""
|
||||
|
||||
|
||||
class PortfolioHubUnavailableError(PortfolioHubReadError):
|
||||
"""portfolio-hub unreachable / 5xx / timeout — degraded signal upstream."""
|
||||
|
||||
|
||||
class PortfolioHubReadPort(Protocol):
|
||||
"""Read-side contract for portfolio-hub universe (REQ-027)."""
|
||||
|
||||
def get_portfolios(self, daemon_id: str) -> list[PortfolioItem]:
|
||||
"""Return all portfolios where `managed_by_daemon_id == daemon_id`."""
|
||||
...
|
||||
|
||||
def whoami(self) -> str:
|
||||
"""Resolve daemon_id from the credentials/token (REQ-027 AC-4).
|
||||
|
||||
Called once at startup so `daemon_id` lookup never depends on
|
||||
`TREX_DAEMON_ID` env (single source of truth = auth token).
|
||||
"""
|
||||
...
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- selection enums
|
||||
|
||||
class View(str, Enum):
|
||||
"""Snapshot view modes (REQ-029, dcy-005 OQ-11/OQ-12)."""
|
||||
ALL = "all" # universe ∪ holding slots
|
||||
BUYABLE = "buyable" # universe − occupied slots
|
||||
HELD = "held" # holding slots only
|
||||
|
||||
|
||||
class DegradedReason(str, Enum):
|
||||
"""Machine-readable degraded reason codes (REQ-028 AC-2, dcy-005 OQ-5)."""
|
||||
PORTFOLIO_HUB_UNAVAILABLE = "portfolio_hub_unavailable"
|
||||
SNAPSHOT_FETCH_FAILED = "snapshot_fetch_failed"
|
||||
CASH_POSITION_STALE = "cash_position_stale"
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- snapshot store
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class SnapshotAsset:
|
||||
"""A portfolio item augmented with overlays (warning, sequence)."""
|
||||
item: PortfolioItem
|
||||
warning: bool = False
|
||||
updated_at: Optional[datetime] = None
|
||||
|
||||
|
||||
class SnapshotStore:
|
||||
"""In-memory snapshot — universe baseline + warning overlay.
|
||||
|
||||
Two-phase: callers `swap(new_universe)` to atomically replace the universe
|
||||
after a fetch, and `set_warning(portfolio_id, on)` to toggle the automatic
|
||||
warning overlay (REQ-031). pause overlay lives in PauseStore (REQ-032).
|
||||
|
||||
Thread-safe; the snapshot RPC handler can read concurrently with the
|
||||
scheduler refresh.
|
||||
"""
|
||||
|
||||
def __init__(self) -> None:
|
||||
self._lock = threading.Lock()
|
||||
self._assets: dict[str, SnapshotAsset] = {}
|
||||
self._degraded: Optional[DegradedReason] = None
|
||||
self._degraded_message: Optional[str] = None
|
||||
self._last_refresh_at: Optional[datetime] = None
|
||||
|
||||
# --- universe ---
|
||||
def swap(self, items: list[PortfolioItem]) -> None:
|
||||
"""Replace the entire universe atomically (immutable swap, Decision 6)."""
|
||||
now = datetime.now(tz=timezone.utc)
|
||||
with self._lock:
|
||||
prior_warnings = {pid for pid, a in self._assets.items() if a.warning}
|
||||
new_assets: dict[str, SnapshotAsset] = {}
|
||||
for item in items:
|
||||
# Carry forward warning if the same portfolio was warned before;
|
||||
# reconciliation will clear it on the next successful check.
|
||||
warn = item.portfolio_id in prior_warnings
|
||||
new_assets[item.portfolio_id] = SnapshotAsset(
|
||||
item=item, warning=warn, updated_at=now,
|
||||
)
|
||||
self._assets = new_assets
|
||||
self._degraded = None
|
||||
self._degraded_message = None
|
||||
self._last_refresh_at = now
|
||||
|
||||
def list_assets(self) -> list[SnapshotAsset]:
|
||||
with self._lock:
|
||||
return list(self._assets.values())
|
||||
|
||||
def get(self, portfolio_id: str) -> Optional[SnapshotAsset]:
|
||||
with self._lock:
|
||||
return self._assets.get(portfolio_id)
|
||||
|
||||
# --- warning overlay (automatic, in-memory only) ---
|
||||
def set_warning(self, portfolio_id: str, on: bool) -> None:
|
||||
with self._lock:
|
||||
a = self._assets.get(portfolio_id)
|
||||
if a is None or a.warning is on:
|
||||
return
|
||||
self._assets[portfolio_id] = replace(a, warning=on)
|
||||
|
||||
def warnings(self) -> set[str]:
|
||||
with self._lock:
|
||||
return {pid for pid, a in self._assets.items() if a.warning}
|
||||
|
||||
# --- option D cash/position (REQ-030 AC-2/AC-3 — wired but no-op until
|
||||
# portfolio-hub#8 ships) ---
|
||||
def update_cash_position(
|
||||
self,
|
||||
portfolio_id: str,
|
||||
cash_balance: float,
|
||||
asset_quantity: float,
|
||||
) -> None:
|
||||
with self._lock:
|
||||
a = self._assets.get(portfolio_id)
|
||||
if a is None:
|
||||
return
|
||||
self._assets[portfolio_id] = replace(
|
||||
a, item=replace(a.item, cash_balance=cash_balance,
|
||||
asset_quantity=asset_quantity),
|
||||
updated_at=datetime.now(tz=timezone.utc),
|
||||
)
|
||||
|
||||
# --- degraded signal (REQ-028 AC-2) ---
|
||||
def set_degraded(self, reason: DegradedReason, message: str) -> None:
|
||||
with self._lock:
|
||||
self._degraded = reason
|
||||
self._degraded_message = _sanitize(message)
|
||||
|
||||
def clear_degraded(self) -> None:
|
||||
with self._lock:
|
||||
self._degraded = None
|
||||
self._degraded_message = None
|
||||
|
||||
def degraded_state(self) -> tuple[Optional[DegradedReason], Optional[str]]:
|
||||
with self._lock:
|
||||
return self._degraded, self._degraded_message
|
||||
|
||||
def last_refresh_at(self) -> Optional[datetime]:
|
||||
with self._lock:
|
||||
return self._last_refresh_at
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- pause store
|
||||
|
||||
class PauseStore(Protocol):
|
||||
"""Durable pause overlay — `portfolio_id` PK (REQ-032)."""
|
||||
|
||||
def list_paused(self) -> set[str]:
|
||||
...
|
||||
|
||||
def pause(self, portfolio_id: str, *, actor: str = "operator") -> None:
|
||||
...
|
||||
|
||||
def resume(self, portfolio_id: str) -> None:
|
||||
...
|
||||
|
||||
|
||||
class InMemoryPauseStore:
|
||||
"""Process-local pause store for tests + CI."""
|
||||
|
||||
def __init__(self, initial: Optional[set[str]] = None) -> None:
|
||||
self._lock = threading.Lock()
|
||||
self._paused: set[str] = set(initial or set())
|
||||
|
||||
def list_paused(self) -> set[str]:
|
||||
with self._lock:
|
||||
return set(self._paused)
|
||||
|
||||
def pause(self, portfolio_id: str, *, actor: str = "operator") -> None:
|
||||
with self._lock:
|
||||
self._paused.add(portfolio_id)
|
||||
|
||||
def resume(self, portfolio_id: str) -> None:
|
||||
with self._lock:
|
||||
self._paused.discard(portfolio_id)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------- selection
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class SnapshotEnvelope:
|
||||
"""REQ-028 response envelope (transport-agnostic)."""
|
||||
assets: list[dict]
|
||||
view: str
|
||||
available_slots: int
|
||||
degraded: bool
|
||||
reason: Optional[str]
|
||||
message: Optional[str] = None
|
||||
|
||||
def to_dict(self) -> dict:
|
||||
return {
|
||||
"assets": list(self.assets),
|
||||
"view": self.view,
|
||||
"available_slots": self.available_slots,
|
||||
"degraded": self.degraded,
|
||||
"reason": self.reason,
|
||||
"message": self.message,
|
||||
}
|
||||
|
||||
|
||||
def _asset_to_dict(item: PortfolioItem) -> dict:
|
||||
"""REQ-027 AC-1 / REQ-028 AC-3 — strict no-price field shape."""
|
||||
return {
|
||||
"symbol": item.symbol,
|
||||
"asset_id": item.portfolio_id,
|
||||
"cash_balance": item.cash_balance,
|
||||
"asset_quantity": item.asset_quantity,
|
||||
"active_strategy_id": item.active_strategy_id,
|
||||
"strategy_params": dict(item.strategy_params or {}),
|
||||
}
|
||||
|
||||
|
||||
def _sanitize(message: str) -> str:
|
||||
"""Strip credentials/URLs/tokens — REQ-028 AC-2 sanitization."""
|
||||
if not message:
|
||||
return ""
|
||||
out = message
|
||||
for needle in ("authorization:", "Bearer ", "token=", "appsecret="):
|
||||
idx = out.lower().find(needle.lower())
|
||||
if idx >= 0:
|
||||
out = out[:idx] + "<redacted>"
|
||||
break
|
||||
# Truncate to keep response payload bounded.
|
||||
return out[:200]
|
||||
|
||||
|
||||
def build_snapshot_envelope(
|
||||
*,
|
||||
store: SnapshotStore,
|
||||
pause_store: PauseStore,
|
||||
slot_repo,
|
||||
available_slots: int,
|
||||
view: View = View.ALL,
|
||||
strategy_key: Optional[str] = None,
|
||||
trading_date=None,
|
||||
) -> SnapshotEnvelope:
|
||||
"""Compose base(view) − mask(pending·warning·pause) − strategy_key (REQ-029).
|
||||
|
||||
`slot_repo` is the SlotRepository used to read holding/pending state.
|
||||
`trading_date` defaults to UTC today (matches the daemon's preallocate).
|
||||
"""
|
||||
# Read core authoritative slot state once.
|
||||
day = trading_date or datetime.now(tz=timezone.utc).date()
|
||||
slots = slot_repo.list_slots(day)
|
||||
holding_pids: set[str] = set()
|
||||
pending_pids: set[str] = set()
|
||||
holding_qty: dict[str, float] = {}
|
||||
for s in slots:
|
||||
if s.portfolio_id is None:
|
||||
continue
|
||||
if s.status.value == "holding":
|
||||
holding_pids.add(s.portfolio_id)
|
||||
holding_qty[s.portfolio_id] = float(s.qty or 0.0)
|
||||
elif s.status.value in ("pending_buy", "pending_sell"):
|
||||
pending_pids.add(s.portfolio_id)
|
||||
|
||||
assets = store.list_assets()
|
||||
paused = pause_store.list_paused()
|
||||
warned = {a.item.portfolio_id for a in assets if a.warning}
|
||||
|
||||
# Build the base set (view).
|
||||
by_pid = {a.item.portfolio_id: a for a in assets}
|
||||
base_pids: list[str]
|
||||
if view is View.HELD:
|
||||
base_pids = sorted(holding_pids)
|
||||
elif view is View.BUYABLE:
|
||||
if available_slots <= 0:
|
||||
base_pids = []
|
||||
else:
|
||||
# universe − occupied slots (pending OR holding occupy)
|
||||
occupied = holding_pids | pending_pids
|
||||
base_pids = [a.item.portfolio_id for a in assets
|
||||
if a.item.portfolio_id not in occupied]
|
||||
else: # ALL
|
||||
base_pids = list({a.item.portfolio_id for a in assets} | holding_pids)
|
||||
base_pids.sort()
|
||||
|
||||
# Apply masks: pending OR warning OR pause.
|
||||
masked = pending_pids | warned | paused
|
||||
|
||||
# Filter and shape.
|
||||
out: list[dict] = []
|
||||
for pid in base_pids:
|
||||
if pid in masked:
|
||||
continue
|
||||
if pid in by_pid:
|
||||
item = by_pid[pid].item
|
||||
elif pid in holding_pids:
|
||||
# holding slot for an asset NOT in the current universe (e.g. fetch
|
||||
# gap) — synthesize a minimal item using slot data so the response
|
||||
# still carries authoritative position info (REQ-029 slot overlay
|
||||
# priority over portfolio-hub presence).
|
||||
slot = next((s for s in slots if s.portfolio_id == pid), None)
|
||||
item = PortfolioItem(
|
||||
portfolio_id=pid,
|
||||
symbol=(slot.symbol if slot else "") or "",
|
||||
cash_balance=0.0,
|
||||
asset_quantity=float((slot.qty if slot else 0.0) or 0.0),
|
||||
active_strategy_id=(slot.strategy_id if slot else None),
|
||||
strategy_params={},
|
||||
)
|
||||
else:
|
||||
continue
|
||||
if strategy_key is not None and item.active_strategy_id != strategy_key:
|
||||
continue
|
||||
d = _asset_to_dict(item)
|
||||
# holding slot quantity wins for held assets (slot-overlay priority).
|
||||
if pid in holding_qty:
|
||||
d["asset_quantity"] = holding_qty[pid]
|
||||
out.append(d)
|
||||
|
||||
reason_code, message = store.degraded_state()
|
||||
return SnapshotEnvelope(
|
||||
assets=out,
|
||||
view=view.value,
|
||||
available_slots=max(0, int(available_slots)),
|
||||
degraded=reason_code is not None,
|
||||
reason=reason_code.value if reason_code is not None else None,
|
||||
message=message,
|
||||
)
|
||||
Reference in New Issue
Block a user