pyalloq-core 0.1.10__tar.gz

pyalloq_core-0.1.10/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.3
+Name: pyalloq-core
+Version: 0.1.10
+Summary: Pure interfaces, Enums, StrategyPipeline, and MarketData for PyAlloq.
+Author: Siddeshkanth
+Author-email: Siddeshkanth <pyalloq-info@alloq-alpha.com>
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# pyalloq-core
+
+`pyalloq-core` provides the foundational data structures, pure interfaces, and core abstractions for the **PyAlloq** quantitative portfolio optimization SDK.
+
+## Key Modules & Abstractions
+
+- **`MarketData`**: Standardized parameter object holding aligned price time-series (`pd.DataFrame`), optional asset features (`dict[str, pd.DataFrame]`), cross-sectional data, asset lists, risk-free rates, and risk aversion parameters. Includes zero-lookahead time slicing (`slice_time`).
+- **`BaseAllocator`**: Abstract base class for all portfolio allocation engines (Markowitz, Risk Parity, HRP, NCO, Deep Learning allocators, etc.).
+- **`BaseReturnEstimator`**: Abstract base class for expected return estimators (Classical, EWMA, Black-Litterman, Factor models, Deep Learning).
+- **`BaseCovarianceEstimator`**: Abstract base class for covariance matrix estimators (Empirical, EWMA, Ledoit-Wolf, Semi-covariance, RMT).
+- **`StrategyPipeline`**: Pipeline orchestrator linking return estimators, covariance estimators, and portfolio allocators into an end-to-end strategy execution object.
+- **`OptimizationResult`**: Standardized result container storing optimized portfolio weights, solver status, and metadata.
+
+## Installation
+
+```bash
+uv add pyalloq-core
+# Or inside workspace
+uv sync
+```
+
+## Quick Example
+
+```python
+import pandas as pd
+from pyalloq_core.data import MarketData
+from pyalloq_core.enums import ObjectiveFunction
+
+# Create MarketData container
+prices = pd.DataFrame(
+    {"AAPL": [150.0, 152.5, 151.0], "MSFT": [300.0, 305.0, 302.0]},
+    index=pd.date_range("2024-01-01", periods=3)
+)
+
+data = MarketData(prices=prices, risk_free_rate=0.04)
+
+print(data.assets)  # ['AAPL', 'MSFT']
+print(data.prices.head())
+```

pyalloq_core-0.1.10/README.md

@@ -0,0 +1,39 @@
+# pyalloq-core
+
+`pyalloq-core` provides the foundational data structures, pure interfaces, and core abstractions for the **PyAlloq** quantitative portfolio optimization SDK.
+
+## Key Modules & Abstractions
+
+- **`MarketData`**: Standardized parameter object holding aligned price time-series (`pd.DataFrame`), optional asset features (`dict[str, pd.DataFrame]`), cross-sectional data, asset lists, risk-free rates, and risk aversion parameters. Includes zero-lookahead time slicing (`slice_time`).
+- **`BaseAllocator`**: Abstract base class for all portfolio allocation engines (Markowitz, Risk Parity, HRP, NCO, Deep Learning allocators, etc.).
+- **`BaseReturnEstimator`**: Abstract base class for expected return estimators (Classical, EWMA, Black-Litterman, Factor models, Deep Learning).
+- **`BaseCovarianceEstimator`**: Abstract base class for covariance matrix estimators (Empirical, EWMA, Ledoit-Wolf, Semi-covariance, RMT).
+- **`StrategyPipeline`**: Pipeline orchestrator linking return estimators, covariance estimators, and portfolio allocators into an end-to-end strategy execution object.
+- **`OptimizationResult`**: Standardized result container storing optimized portfolio weights, solver status, and metadata.
+
+## Installation
+
+```bash
+uv add pyalloq-core
+# Or inside workspace
+uv sync
+```
+
+## Quick Example
+
+```python
+import pandas as pd
+from pyalloq_core.data import MarketData
+from pyalloq_core.enums import ObjectiveFunction
+
+# Create MarketData container
+prices = pd.DataFrame(
+    {"AAPL": [150.0, 152.5, 151.0], "MSFT": [300.0, 305.0, 302.0]},
+    index=pd.date_range("2024-01-01", periods=3)
+)
+
+data = MarketData(prices=prices, risk_free_rate=0.04)
+
+print(data.assets)  # ['AAPL', 'MSFT']
+print(data.prices.head())
+```

pyalloq_core-0.1.10/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "pyalloq-core"
+version = "0.1.10"
+description = "Pure interfaces, Enums, StrategyPipeline, and MarketData for PyAlloq."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "numpy>=1.24",
+    "pandas>=2.0",
+]
+
+[[project.authors]]
+name = "Siddeshkanth"
+email = "pyalloq-info@alloq-alpha.com"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "ruff>=0.6",
+    "mypy>=1.11",
+]
+
+[tool.setuptools.packages.find]
+where = ["src/"]

pyalloq_core-0.1.10/pyproject.toml.orig

@@ -0,0 +1,22 @@
+[build-system]
+requires = ["uv_build>=0.10.9,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "pyalloq-core"
+version = "0.1.10"
+description = "Pure interfaces, Enums, StrategyPipeline, and MarketData for PyAlloq."
+readme = "README.md"
+requires-python = ">=3.11"
+authors = [{ name = "Siddeshkanth", email = "pyalloq-info@alloq-alpha.com" }]
+
+dependencies = [
+  "numpy>=1.24",
+  "pandas>=2.0",
+]
+
+[dependency-groups]
+dev = ["pytest>=8", "ruff>=0.6", "mypy>=1.11"]
+
+[tool.setuptools.packages.find]
+where = ["src/"]

pyalloq_core-0.1.10/src/pyalloq_core/data.py

@@ -0,0 +1,74 @@
+import pandas as pd
+from dataclasses import dataclass, field
+
+
+@dataclass(kw_only=True)
+class MarketData:
+    """
+    Standardized Parameter Object for all financial data.
+    Serves as a single source of truth across the pyalloq SDK
+    """
+
+    assets: list[str] = field(default_factory=list)
+    prices: pd.DataFrame
+    # Time Series features (e.g: Volume, Factor returns, Macro Indicators, Alternative Data)
+    features: dict[str, pd.DataFrame] = field(default_factory=dict)
+    # Cross Sectional Data (e.g: Market Caps, Sector Mappings)
+    cross_sectional: pd.DataFrame | None = None
+    # Risk free rate (Contant or Time Series)
+    risk_free_rate: pd.Series | float = 0.0
+
+    risk_aversion: pd.Series | float = 1.0
+
+    def __post_init__(self) -> None:
+        if not self.assets and self.prices is not None and not self.prices.empty:
+            self.assets = list(self.prices.columns)
+        self.validate_alignment()
+
+    def validate_alignment(self) -> None:
+        """
+        Ensures Time Series Data aligns perfectly to prevent look-ahead bias.
+        """
+        for feat_name, df_feat in self.features.items():
+            if not self.prices.index.equals(df_feat.index):
+                raise ValueError(
+                    f"Data misalignment: Feature: {feat_name} index does not perfectly match 'prices' index."
+                )
+
+        if isinstance(self.risk_free_rate, pd.Series):
+            if not self.prices.index.equals(self.risk_free_rate.index):
+                raise ValueError(
+                    "Data misalignment: 'risk_free_rate' series index does not perfectly match 'prices' index."
+                )
+
+    def slice_time(
+        self,
+        end_date: pd.Timestamp,
+        lookback: int | None = None,
+    ) -> "MarketData":
+        """
+        Returns a new MarketData instance safely sliced for a backtest window.
+        """
+        sliced_prices = self.prices.loc[:end_date]
+        if lookback is not None:
+            sliced_prices = sliced_prices.iloc[-lookback:]
+
+        sliced_features: dict[str, pd.DataFrame] = {}
+        for name, feat in self.features.items():
+            sliced_feat = feat.loc[:end_date]
+            if lookback is not None:
+                sliced_feat = sliced_feat.iloc[-lookback:]
+            sliced_features[name] = sliced_feat
+
+        sliced_rf = self.risk_free_rate
+        if isinstance(self.risk_free_rate, pd.Series):
+            sliced_rf = self.risk_free_rate.loc[:end_date]
+            if lookback is not None:
+                sliced_rf = sliced_rf.iloc[-lookback:]
+
+        return self.__class__(
+            prices=sliced_prices,
+            features=sliced_features,
+            cross_sectional=self.cross_sectional,
+            risk_free_rate=sliced_rf,
+        )

pyalloq_core-0.1.10/src/pyalloq_core/enums.py

@@ -0,0 +1,21 @@
+from enum import Enum, auto
+
+
+class ObjectiveFunction(Enum):
+    MAX_SHARPE = auto()
+    MIN_VOLATILITY = auto()
+    MAX_RETURN = auto()
+    RISK_PARITY = auto()
+
+
+class ConstraintType(Enum):
+    LONG_ONLY = auto()
+    MARKET_NEUTRAL = auto()
+    CARDINALITY = auto()  # Max number of assets
+
+
+class DataFrequency(Enum):
+    DAILY = 252
+    WEEKLY = 52
+    MONTHLY = 12
+    CRYPTO_DAILY = 365

pyalloq_core-0.1.10/src/pyalloq_core/interfaces.py

@@ -0,0 +1,101 @@
+from abc import ABC, abstractmethod
+import pandas as pd
+from typing import Any
+from .enums import DataFrequency
+from .data import MarketData
+from .results import OptimizationResult
+
+
+class BaseAllocator(ABC):
+    def __init__(self, tickers: list[str]) -> None:
+        self.tickers = tickers
+
+    def _resolve_annualization_factor(
+        self,
+        returns: pd.DataFrame,
+        frequency: DataFrequency | str | int | None = None,
+    ) -> float:
+        """Determines annualization factor from Enum, int or inferred pandas index."""
+        if isinstance(frequency, DataFrequency):
+            return float(frequency.value)
+        if isinstance(frequency, (int, float)):
+            return float(frequency)
+        if isinstance(frequency, str):
+            try:
+                float(DataFrequency[frequency.upper()].value)
+            except KeyError:
+                pass
+
+        if isinstance(returns.index, pd.DatetimeIndex):
+            inferred = pd.infer_freq(returns.index)
+            if inferred:
+                if "W" in inferred:
+                    return DataFrequency.WEEKLY.value
+                if "M" in inferred or "MS" in inferred:
+                    return DataFrequency.MONTHLY.value
+                if "B" in inferred or "D" in inferred:
+                    return DataFrequency.DAILY.value
+
+        return DataFrequency.DAILY.value
+
+    def _prepare_inputs(
+        self,
+        prices: pd.DataFrame,
+        expected_returns: pd.Series | None = None,
+        cov_matrix: pd.DataFrame | None = None,
+        window_len: int | None = None,
+        frequency: DataFrequency | str | int = DataFrequency.DAILY,
+    ) -> tuple[pd.Series, pd.DataFrame]:
+        """
+        Internal helper to resolve inputs. If raw prices are given,
+        it computes basic historical matrices. Otherwise, it uses the provided ones.
+        """
+        final_returns = expected_returns
+        final_cov = cov_matrix
+
+        returns = prices.iloc[-window_len:] if window_len else prices
+        scale_factor = self._resolve_annualization_factor(returns, frequency)
+        df_returns = returns.pct_change().dropna()
+
+        if final_returns is None:
+            final_returns = df_returns.mean() * scale_factor
+
+        if final_cov is None:
+            final_cov = df_returns.cov() * scale_factor
+
+        if final_returns is None or final_cov is None:
+            raise ValueError(
+                "You must provide either raw 'prices' or BOTH 'expected_returns' and 'cov_matrix'"
+            )
+
+        return (final_returns, final_cov)
+
+    @abstractmethod
+    def allocate(
+        self,
+        data: MarketData,
+        cov_matrix: pd.DataFrame,
+        expected_returns: pd.Series | None = None,
+        **kwargs: Any,
+    ) -> OptimizationResult:
+        """
+        Base allocate function all subclasses must implement
+        """
+        ...
+
+
+class BaseReturnEstimator(ABC):
+    @abstractmethod
+    def estimate(self, data: MarketData, **kwargs: Any) -> pd.Series:
+        """
+        Takes raw prices (and optional macro/technical features) and
+        returns an Nx1 pandas Series of expected returns for the assets.
+        """
+        pass
+
+
+class BaseCovarianceEstimator(ABC):
+    @abstractmethod
+    def estimate(self, data: MarketData, **kwargs: Any) -> pd.DataFrame:
+        """Takes a price DataFrame and returns an NxN covariance matrix."""
+        pass

pyalloq_core-0.1.10/src/pyalloq_core/pipeline.py

@@ -0,0 +1,43 @@
+import pandas as pd
+from typing import Any
+from pyalloq_core.interfaces import (
+    BaseAllocator,
+    BaseReturnEstimator,
+    BaseCovarianceEstimator,
+)
+from pyalloq.estimators.returns.classical.ewma import EWMAReturnEstimator
+from pyalloq.estimators.covariance.empirical import EmpiricalCovariance
+from pyalloq_core.data import MarketData
+
+
+class StrategyPipeline:
+    def __init__(
+        self,
+        allocator: BaseAllocator,
+        returns_estimator: BaseReturnEstimator | None = None,
+        cov_estimator: BaseCovarianceEstimator | None = None,
+        allocator_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        self.allocator = allocator
+        self.returns_estimator = (
+            returns_estimator
+            if returns_estimator is not None
+            else EWMAReturnEstimator()
+        )
+        self.cov_estimator = (
+            cov_estimator if cov_estimator is not None else EmpiricalCovariance()
+        )
+        self.allocator_kwargs = allocator_kwargs or {}
+
+    def generate_weights(
+        self,
+        data: MarketData,
+    ) -> pd.Series:
+        expected_returns = self.returns_estimator.estimate(data)
+        cov_matrix = self.cov_estimator.estimate(data)
+
+        result = self.allocator.allocate(
+            data, cov_matrix=cov_matrix, expected_returns=expected_returns
+        )
+
+        return result.weights

pyalloq_core-0.1.10/src/pyalloq_core/py.typed

@@ -0,0 +1 @@
+# Marker file for PEP 561

pyalloq_core-0.1.10/src/pyalloq_core/results.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from typing import Dict, Any, Optional
+import pandas as pd
+import numpy as np
+
+
+@dataclass
+class OptimizationResult:
+    """Standardized output for all portfolio optimizers."""
+
+    name = str
+    weights: pd.Series
+    status: str  # e.g., "OPTIMAL", "INFEASIBLE", "SUBOPTIMAL"
+
+    expected_return: Optional[float] = None
+    volatility: Optional[float] = None
+    sharpe_ratio: Optional[float] = None
+
+    # Store solver-specific data (e.g., cvxpy objective value, RL episode reward, HRP linkages)
+    metadata: Dict[str, Any] = field(default_factory=dict)
+
+    def clean_weights(self, cutoff: float = 1e-4) -> pd.Series:
+        clean = self.weights.copy()
+        clean[np.abs(clean) < cutoff] = 0.0
+
+        return clean / clean.sum()

pyalloq_core-0.1.10/src/pyalloq_core/utils.py

@@ -0,0 +1,8 @@
+import numpy as np
+
+
+def cov_to_corr(cov: np.ndarray) -> np.ndarray:
+    """Helper to convert covariance matrix to correlation matrix."""
+    vols = np.sqrt(np.diag(cov))
+    outer_vols = np.outer(vols, vols)
+    return cov / outer_vols