Skip to content

"Vibe-Trading: Your Personal Trading Agent"

6.2 KB
Raw Blame
"""Shared base class for portfolio optimizers.

Handles preprocessing, rolling covariance windows, and weight normalization;
subclasses implement ``_calc_weights``.
"""

from abc import ABC, abstractmethod
from typing import Dict, Any, List

import numpy as np
import pandas as pd


class BaseOptimizer(ABC):
    """Abstract portfolio optimizer.

    Subclasses implement ``_calc_weights``; the base handles:
    - active asset selection
    - causal rolling window slicing and sanity checks
    - covariance matrix + NaN checks
    - applying weights while preserving signal sign

    Attributes:
        lookback: Lookback days for covariance / mean.
        params: Extra keyword args for subclasses.
    """

    def __init__(self, lookback: int = 60, **kwargs: Any) -> None:
        self.lookback = lookback
        self.params = kwargs

    # ------------------------------------------------------------------
    # Public entry
    # ------------------------------------------------------------------

    def optimize(
        self,
        ret: pd.DataFrame,
        pos: pd.DataFrame,
        dates: pd.DatetimeIndex,
    ) -> pd.DataFrame:
        """Apply optimizer to position weights.

        Args:
            ret: Return matrix (dates x codes). For a decision at ``dt``,
                only rows strictly earlier than ``dt`` are visible to the
                optimizer because execution occurs at the decision bar's open.
            pos: Raw signal positions.
            dates: Date index aligned with ``pos``.

        Returns:
            Adjusted position matrix (not dollar-normalized).
        """
        codes = pos.columns.tolist()
        if len(codes) <= 1:
            return pos

        result = pos.copy()
        for i, dt in enumerate(dates):
            active = [c for c in codes if abs(pos.at[dt, c]) > 1e-9]
            if i < self.lookback:
                continue
            if not active:
                self._on_passthrough_allocation(result.loc[dt])
                continue

            # Signals are executed at the decision bar's open.  ``ret[dt]``
            # is a close-to-close return that is not observable until that
            # bar closes, so including it here would leak future information
            # into the weights applied at the open.
            history = ret.loc[ret.index < dt, active]
            window = history.tail(self.lookback)
            if len(window) < max(self.lookback // 2, 5):
                self._on_passthrough_allocation(result.loc[dt])
                continue

            signs = np.array([np.sign(pos.at[dt, c]) for c in active])
            # Hand subclasses the window in POSITION space: a short's column is
            # negated, so every context built from it describes what is actually
            # being sized. ``mu`` becomes the position's expected return (a
            # short earns the negative of its asset's drift) and ``cov`` becomes
            # D Sigma D, whose cross terms flip sign for a long/short pair --
            # signing only ``mu`` would score the numerator in position space
            # and the variance in asset space, so a hedged pair would still
            # read as correlated. Volatility-only contexts are unaffected
            # (std(-r) == std(r)).
            signed = window.mul(pd.Series(signs, index=window.columns), axis=1)
            ctx = self._build_context(signed, active)
            if ctx is None:
                self._on_passthrough_allocation(result.loc[dt])
                continue

            # Stateful optimizers need the direction as well as the signed
            # return window to measure changes between actual allocations.
            ctx["position_signs"] = signs
            weights = self._calc_weights(ctx)
            if weights is None or len(weights) != len(active):
                self._on_passthrough_allocation(result.loc[dt])
                continue

            for j, c in enumerate(active):
                result.at[dt, c] = signs[j] * weights[j]

        return result

    # ------------------------------------------------------------------
    # Hooks
    # ------------------------------------------------------------------

    def _on_passthrough_allocation(self, allocation: pd.Series) -> None:
        """Observe a post-warmup allocation retained without optimization.

        Args:
            allocation: Signed output allocation for the current decision date.
        """

    def _build_context(
        self, window: pd.DataFrame, active: List[str]
    ) -> "Dict[str, Any] | None":
        """Build context dict for ``_calc_weights``.

        Default: covariance only. Override to add means, vols, etc.
        Return None to skip the date.

        Args:
            window: Return window for active assets, in POSITION space -- a
                short's column is already negated by ``optimize``, so a mean
                taken here is the position's expected return and a covariance
                is the position covariance.
            active: Active asset codes.

        Returns:
            Context dict with at least ``cov``, or None.
        """
        cov = window.cov().values
        if np.isnan(cov).any():
            return None
        return {"cov": cov}

    # ------------------------------------------------------------------
    # Subclass API
    # ------------------------------------------------------------------

    @abstractmethod
    def _calc_weights(self, ctx: Dict[str, Any]) -> np.ndarray:
        """Compute target weights from context.

        Args:
            ctx: Dict from ``_build_context``.

        Returns:
            Weight vector (n,) summing to 1.
        """

    # ------------------------------------------------------------------
    # Utilities
    # ------------------------------------------------------------------

    @staticmethod
    def _normalize(w: np.ndarray) -> np.ndarray:
        """Normalize nonnegative weights to sum 1."""
        w = np.maximum(w, 0.0)
        s = w.sum()
        if s > 1e-12:
            return w / s
        return np.ones(len(w)) / len(w)

    @staticmethod
    def _equal_weight(n: int) -> np.ndarray:
        """Equal weights for n assets."""
        if n == 0:
            return np.array([])
        return np.ones(n) / n