malatium 0.1.2__tar.gz

malatium-0.1.2/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: malatium
+Version: 0.1.2
+Summary: Quant research backtesting tools.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+Requires-Dist: bear-lake>=0.1.5
+Requires-Dist: cvxpy>=1.8.1
+Requires-Dist: numpy>=2.4.2
+Requires-Dist: polars>=1.38.1
+Requires-Dist: tqdm>=4.67.3
+Requires-Dist: matplotlib>=3.10.8
+Requires-Dist: seaborn>=0.13.2
+
+# Malatium
+
+Quant primitives for building a hedge fund. Malatium provides a modular backtesting framework with convex portfolio optimization, pluggable risk models, transaction cost modeling, and flexible data providers.
+
+## Installation
+
+```bash
+pip install malatium
+```
+
+## Quick Start
+
+```python
+from malatium.backtester import Backtester
+from malatium.strategy import OptimizationStrategy
+from malatium.objectives import MaxUtilityWithTargetActiveRisk
+from malatium.optimizer_constraints import LongOnly, FullyInvested
+from malatium.trading_constraints import MinPositionSize
+from malatium.risk_model import FactorRiskModel
+from malatium.costs import LinearCost
+import datetime as dt
+
+# 1. Create your data providers (see "Data Providers" below)
+start = dt.date(2026, 1, 1)
+end = dt.date(2026, 12, 31)
+
+calendar = MyCalendarProvider(start, end)
+returns = MyReturnsProvider(start, end)
+alphas = MyAlphaProvider(start, end)
+factor_loadings = MyFactorLoadingsProvider(start, end)
+factor_covariances = MyFactorCovariancesProvider(start, end)
+idio_vol = MyIdioVolProvider(start, end)
+benchmark = MyBenchmarkProvider(start, end)
+
+# 2. Define a strategy
+strategy = OptimizationStrategy(
+    alphas=alphas,
+    risk_model=FactorRiskModel(factor_loadings, factor_covariances, idio_vol),
+    objective=MaxUtilityWithTargetActiveRisk(target_active_risk=0.05),
+    optimizer_constraints=[LongOnly(), FullyInvested()],
+    trading_constraints=[MinPositionSize(dollars=1)],
+    benchmark=benchmark,
+)
+
+# 3. Run the backtest
+bt = Backtester()
+result = bt.run(
+    calendar=calendar,
+    returns=returns,
+    strategy=strategy,
+    cost_model=LinearCost(bps=5),
+    start=start,
+    end=end,
+    initial_capital=100_000,
+)
+
+# 4. Analyze results
+print(result.summary())
+result.plot_equity_curve("equity_curve.png")
+```
+
+## Data Providers
+
+Allomancy uses Protocol-based data providers — one per dataset. Each provider has a single `get()` method. Any class with a matching `get()` signature satisfies the protocol automatically (no subclassing required).
+
+| Provider | `get()` signature | Returns |
+|----------|-------------------|---------|
+| `CalendarProvider` | `get(start, end) -> list[dt.date]` | Trading dates in range |
+| `ReturnsProvider` | `get(date) -> DataFrame` | `[date, ticker, return]` |
+| `AlphaProvider` | `get(date) -> DataFrame` | `[date, ticker, alpha]` |
+| `FactorLoadingsProvider` | `get(date) -> DataFrame` | `[date, ticker, factor, loading]` |
+| `FactorCovariancesProvider` | `get(date) -> DataFrame` | `[date, factor_1, factor_2, covariance]` |
+| `IdioVolProvider` | `get(date) -> DataFrame` | `[date, ticker, idio_vol]` |
+| `BenchmarkProvider` | `get(date) -> DataFrame` | `[date, ticker, weight]` |
+
+### Writing a Data Provider
+
+Each provider is a simple class with a `get()` method. Pre-loading data into memory during `__init__` is recommended for backtest speed.
+
+```python
+import datetime as dt
+import polars as pl
+
+
+class MyReturnsProvider:
+    def __init__(self, start: dt.date, end: dt.date) -> None:
+        self._returns = load_returns_from_db(start, end)
+
+    def get(self, date_: dt.date) -> pl.DataFrame:
+        return self._returns.filter(pl.col("date").eq(date_))
+
+
+class MyAlphaProvider:
+    def __init__(self, start: dt.date, end: dt.date) -> None:
+        self._alphas = load_alphas_from_db(start, end)
+
+    def get(self, date_: dt.date) -> pl.DataFrame:
+        return self._alphas.filter(pl.col("date").eq(date_))
+```
+
+## Components
+
+### Objectives
+
+Control how the optimizer selects portfolio weights.
+
+- **`MaxUtility(lambda_)`** — Mean-variance optimization: maximize `w @ alpha - lambda/2 * w' Sigma w`.
+- **`MaxUtilityWithTargetActiveRisk(target_active_risk)`** — Iteratively finds the risk-aversion parameter that produces a portfolio matching the target active risk (annualized tracking error vs. benchmark).
+
+### Optimizer Constraints
+
+Hard constraints passed to the CVXPY solver.
+
+- **`LongOnly()`** — No short positions (`w >= 0`).
+- **`FullyInvested()`** — Weights sum to one (`sum(w) == 1`).
+
+Implement `OptimizerConstraint` to add your own.
+
+### Trading Constraints
+
+Post-optimization filters applied to the resulting weights.
+
+- **`MinPositionSize(dollars)`** — Zeroes out any position smaller than the given dollar amount.
+
+Implement `TradingConstraint` to add your own.
+
+### Risk Models
+
+Build the covariance matrix used by the optimizer.
+
+- **`FactorRiskModel(factor_loadings, factor_covariances, idio_vol)`** — Computes `Sigma = X F X' + D^2` from factor loadings (`X`), factor covariances (`F`), and idiosyncratic volatilities (`D`).
+
+Implement `RiskModel` to add your own.
+
+### Cost Models
+
+Estimate transaction costs deducted from capital at each rebalance.
+
+- **`NoCost()`** — Zero cost.
+- **`LinearCost(bps)`** — Cost proportional to turnover: `turnover * capital * bps / 10,000`.
+
+Implement `CostModel` to add your own.
+
+### Backtest Results
+
+`BacktestResult` provides:
+
+| Method | Returns |
+|--------|---------|
+| `summary()` | DataFrame with annualized return, volatility, Sharpe ratio, and max drawdown |
+| `portfolio_returns()` | Daily portfolio returns and values |
+| `sharpe_ratio()` | Annualized Sharpe ratio |
+| `annualized_return()` | Annualized return (%) |
+| `annualized_volatility()` | Annualized volatility (%) |
+| `max_drawdown()` | Maximum peak-to-trough drawdown |
+| `plot_equity_curve(path)` | Save an equity curve chart to disk |

malatium-0.1.2/README.md

@@ -0,0 +1,156 @@
+# Malatium
+
+Quant primitives for building a hedge fund. Malatium provides a modular backtesting framework with convex portfolio optimization, pluggable risk models, transaction cost modeling, and flexible data providers.
+
+## Installation
+
+```bash
+pip install malatium
+```
+
+## Quick Start
+
+```python
+from malatium.backtester import Backtester
+from malatium.strategy import OptimizationStrategy
+from malatium.objectives import MaxUtilityWithTargetActiveRisk
+from malatium.optimizer_constraints import LongOnly, FullyInvested
+from malatium.trading_constraints import MinPositionSize
+from malatium.risk_model import FactorRiskModel
+from malatium.costs import LinearCost
+import datetime as dt
+
+# 1. Create your data providers (see "Data Providers" below)
+start = dt.date(2026, 1, 1)
+end = dt.date(2026, 12, 31)
+
+calendar = MyCalendarProvider(start, end)
+returns = MyReturnsProvider(start, end)
+alphas = MyAlphaProvider(start, end)
+factor_loadings = MyFactorLoadingsProvider(start, end)
+factor_covariances = MyFactorCovariancesProvider(start, end)
+idio_vol = MyIdioVolProvider(start, end)
+benchmark = MyBenchmarkProvider(start, end)
+
+# 2. Define a strategy
+strategy = OptimizationStrategy(
+    alphas=alphas,
+    risk_model=FactorRiskModel(factor_loadings, factor_covariances, idio_vol),
+    objective=MaxUtilityWithTargetActiveRisk(target_active_risk=0.05),
+    optimizer_constraints=[LongOnly(), FullyInvested()],
+    trading_constraints=[MinPositionSize(dollars=1)],
+    benchmark=benchmark,
+)
+
+# 3. Run the backtest
+bt = Backtester()
+result = bt.run(
+    calendar=calendar,
+    returns=returns,
+    strategy=strategy,
+    cost_model=LinearCost(bps=5),
+    start=start,
+    end=end,
+    initial_capital=100_000,
+)
+
+# 4. Analyze results
+print(result.summary())
+result.plot_equity_curve("equity_curve.png")
+```
+
+## Data Providers
+
+Allomancy uses Protocol-based data providers — one per dataset. Each provider has a single `get()` method. Any class with a matching `get()` signature satisfies the protocol automatically (no subclassing required).
+
+| Provider | `get()` signature | Returns |
+|----------|-------------------|---------|
+| `CalendarProvider` | `get(start, end) -> list[dt.date]` | Trading dates in range |
+| `ReturnsProvider` | `get(date) -> DataFrame` | `[date, ticker, return]` |
+| `AlphaProvider` | `get(date) -> DataFrame` | `[date, ticker, alpha]` |
+| `FactorLoadingsProvider` | `get(date) -> DataFrame` | `[date, ticker, factor, loading]` |
+| `FactorCovariancesProvider` | `get(date) -> DataFrame` | `[date, factor_1, factor_2, covariance]` |
+| `IdioVolProvider` | `get(date) -> DataFrame` | `[date, ticker, idio_vol]` |
+| `BenchmarkProvider` | `get(date) -> DataFrame` | `[date, ticker, weight]` |
+
+### Writing a Data Provider
+
+Each provider is a simple class with a `get()` method. Pre-loading data into memory during `__init__` is recommended for backtest speed.
+
+```python
+import datetime as dt
+import polars as pl
+
+
+class MyReturnsProvider:
+    def __init__(self, start: dt.date, end: dt.date) -> None:
+        self._returns = load_returns_from_db(start, end)
+
+    def get(self, date_: dt.date) -> pl.DataFrame:
+        return self._returns.filter(pl.col("date").eq(date_))
+
+
+class MyAlphaProvider:
+    def __init__(self, start: dt.date, end: dt.date) -> None:
+        self._alphas = load_alphas_from_db(start, end)
+
+    def get(self, date_: dt.date) -> pl.DataFrame:
+        return self._alphas.filter(pl.col("date").eq(date_))
+```
+
+## Components
+
+### Objectives
+
+Control how the optimizer selects portfolio weights.
+
+- **`MaxUtility(lambda_)`** — Mean-variance optimization: maximize `w @ alpha - lambda/2 * w' Sigma w`.
+- **`MaxUtilityWithTargetActiveRisk(target_active_risk)`** — Iteratively finds the risk-aversion parameter that produces a portfolio matching the target active risk (annualized tracking error vs. benchmark).
+
+### Optimizer Constraints
+
+Hard constraints passed to the CVXPY solver.
+
+- **`LongOnly()`** — No short positions (`w >= 0`).
+- **`FullyInvested()`** — Weights sum to one (`sum(w) == 1`).
+
+Implement `OptimizerConstraint` to add your own.
+
+### Trading Constraints
+
+Post-optimization filters applied to the resulting weights.
+
+- **`MinPositionSize(dollars)`** — Zeroes out any position smaller than the given dollar amount.
+
+Implement `TradingConstraint` to add your own.
+
+### Risk Models
+
+Build the covariance matrix used by the optimizer.
+
+- **`FactorRiskModel(factor_loadings, factor_covariances, idio_vol)`** — Computes `Sigma = X F X' + D^2` from factor loadings (`X`), factor covariances (`F`), and idiosyncratic volatilities (`D`).
+
+Implement `RiskModel` to add your own.
+
+### Cost Models
+
+Estimate transaction costs deducted from capital at each rebalance.
+
+- **`NoCost()`** — Zero cost.
+- **`LinearCost(bps)`** — Cost proportional to turnover: `turnover * capital * bps / 10,000`.
+
+Implement `CostModel` to add your own.
+
+### Backtest Results
+
+`BacktestResult` provides:
+
+| Method | Returns |
+|--------|---------|
+| `summary()` | DataFrame with annualized return, volatility, Sharpe ratio, and max drawdown |
+| `portfolio_returns()` | Daily portfolio returns and values |
+| `sharpe_ratio()` | Annualized Sharpe ratio |
+| `annualized_return()` | Annualized return (%) |
+| `annualized_volatility()` | Annualized volatility (%) |
+| `max_drawdown()` | Maximum peak-to-trough drawdown |
+| `plot_equity_curve(path)` | Save an equity curve chart to disk |

malatium-0.1.2/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "malatium"
+version = "0.1.2"
+description = "Quant research backtesting tools."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    "bear-lake>=0.1.5",
+    "cvxpy>=1.8.1",
+    "numpy>=2.4.2",
+    "polars>=1.38.1",
+    "tqdm>=4.67.3",
+    "matplotlib>=3.10.8",
+    "seaborn>=0.13.2",
+]

malatium-0.1.2/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

malatium-0.1.2/src/malatium/__init__.py

@@ -0,0 +1 @@
+

malatium-0.1.2/src/malatium/backtester.py

@@ -0,0 +1,138 @@
+from typing import Literal
+from malatium.data import CalendarProvider, ReturnsProvider, BenchmarkProvider
+from malatium.strategy import Strategy
+from malatium.costs import CostModel, NoCost
+from malatium.result import BacktestResult
+import polars as pl
+import datetime as dt
+from tqdm import tqdm
+
+RebalanceFrequency = Literal['daily', 'weekly', 'monthly']
+
+
+class Backtester:
+    """Engine that runs a strategy over historical data and tracks portfolio performance.
+
+    On each trading date the backtester generates new weights, deducts
+    transaction costs, computes PnL from forward returns, and rolls
+    capital forward.
+    """
+
+    def _is_rebalance_date(
+        self,
+        date_: dt.date,
+        prev_date: dt.date | None,
+        frequency: RebalanceFrequency,
+    ) -> bool:
+        """Return True if the portfolio should be rebalanced on this date."""
+        if prev_date is None:
+            return True
+        if frequency == 'daily':
+            return True
+        if frequency == 'weekly':
+            y1, w1, _ = prev_date.isocalendar()
+            y2, w2, _ = date_.isocalendar()
+            return (y1, w1) != (y2, w2)
+        if frequency == 'monthly':
+            return (prev_date.year, prev_date.month) != (date_.year, date_.month)
+        return True
+
+    def run(
+        self,
+        calendar: CalendarProvider,
+        returns: ReturnsProvider,
+        strategy: Strategy,
+        start: dt.date,
+        end: dt.date,
+        initial_capital: float,
+        cost_model: CostModel | None = None,
+        rebalance_frequency: RebalanceFrequency = 'daily',
+        benchmark: BenchmarkProvider | None = None,
+    ) -> BacktestResult:
+        """Execute the backtest and return a BacktestResult.
+
+        Args:
+            calendar: Provider for trading dates.
+            returns: Provider for next-period forward returns.
+            strategy: Strategy that generates portfolio weights each period.
+            start: First date of the backtest (inclusive).
+            end: Last date of the backtest (inclusive).
+            initial_capital: Starting portfolio value in dollars.
+            cost_model: Transaction cost model (defaults to NoCost).
+            rebalance_frequency: How often to rebalance — 'daily', 'weekly'
+                (first trading day of each ISO week), or 'monthly' (first
+                trading day of each calendar month).
+            benchmark: Optional benchmark provider for benchmark returns.
+                When supplied, BacktestResult will include benchmark-relative
+                analytics.
+        """
+        if cost_model is None:
+            cost_model = NoCost()
+
+        capital = initial_capital
+        holdings: pl.DataFrame | None = None
+        prev_date: dt.date | None = None
+        results_list: list[pl.DataFrame] = []
+        benchmark_returns_list: list[dict] = []
+
+        for date_ in tqdm(calendar.get(start, end), "RUNNING BACKTEST"):
+            rebalance = self._is_rebalance_date(date_, prev_date, rebalance_frequency)
+
+            if rebalance:
+                new_weights = strategy.generate_weights(date_, capital)
+                costs = cost_model.compute_costs(holdings, new_weights, capital)
+                capital -= costs
+            else:
+                new_weights = holdings.with_columns(pl.lit(date_).alias('date'))
+
+            forward_returns = returns.get(date_)
+
+            results = (
+                new_weights
+                .join(forward_returns, on=['date', 'ticker'], how='left')
+                .with_columns(pl.col('return').fill_null(0))
+                .with_columns(
+                    pl.col('weight').mul(pl.lit(capital)).alias('value'),
+                )
+                .with_columns(
+                    pl.col('value').mul('return').alias('pnl'),
+                )
+            )
+
+            invested = results['value'].sum()
+            cash = capital - invested
+            capital = invested + results['pnl'].sum() + cash
+
+            # Compute drifted weights for next day's holdings
+            holdings = (
+                results
+                .with_columns(
+                    ((pl.col('value') + pl.col('pnl')) / capital).alias('weight'),
+                )
+                .select('date', 'ticker', 'weight')
+            )
+
+            if benchmark is not None:
+                bm_weights = benchmark.get(date_)
+                bm_return = (
+                    bm_weights
+                    .join(forward_returns, on=['date', 'ticker'], how='left')
+                    .with_columns(pl.col('return').fill_null(0))
+                    .select(pl.col('weight').mul(pl.col('return')).sum())
+                    .item()
+                )
+                benchmark_returns_list.append({
+                    'date': date_,
+                    'benchmark_return': float(bm_return),
+                })
+
+            prev_date = date_
+            results_list.append(results)
+
+        benchmark_returns = (
+            pl.DataFrame(benchmark_returns_list)
+            if benchmark_returns_list
+            else None
+        )
+
+        return BacktestResult(pl.concat(results_list), benchmark_returns)

malatium-0.1.2/src/malatium/costs.py

@@ -0,0 +1,72 @@
+from abc import ABC, abstractmethod
+import polars as pl
+
+
+class CostModel(ABC):
+    """Base class for transaction cost estimation."""
+
+    @abstractmethod
+    def compute_costs(
+        self,
+        old_weights: pl.DataFrame | None,
+        new_weights: pl.DataFrame,
+        capital: float,
+    ) -> float:
+        """Estimate the dollar cost of rebalancing from old_weights to new_weights.
+
+        Args:
+            old_weights: Previous portfolio weights, or None for the first rebalance.
+            new_weights: Target portfolio weights with columns [ticker, weight].
+            capital: Current portfolio capital in dollars.
+        """
+        pass
+
+
+class NoCost(CostModel):
+    """Cost model that charges zero transaction costs."""
+
+    def compute_costs(
+        self,
+        old_weights: pl.DataFrame | None,
+        new_weights: pl.DataFrame,
+        capital: float,
+    ) -> float:
+        """Return 0.0 (no costs)."""
+        return 0.0
+
+
+class LinearCost(CostModel):
+    """Transaction cost proportional to portfolio turnover.
+
+    Cost is computed as: turnover * capital * bps / 10,000.
+
+    Args:
+        bps: Cost in basis points per unit of turnover.
+    """
+
+    def __init__(self, bps: float):
+        self.bps = bps
+
+    def compute_costs(
+        self,
+        old_weights: pl.DataFrame | None,
+        new_weights: pl.DataFrame,
+        capital: float,
+    ) -> float:
+        """Compute linear transaction costs based on weight turnover."""
+        if old_weights is None:
+            turnover = new_weights['weight'].abs().sum()
+        else:
+            combined = (
+                new_weights.select('ticker', pl.col('weight').alias('new_weight'))
+                .join(
+                    old_weights.select('ticker', pl.col('weight').alias('old_weight')),
+                    on='ticker',
+                    how='full',
+                    coalesce=True,
+                )
+                .fill_null(0)
+            )
+            turnover = (combined['new_weight'] - combined['old_weight']).abs().sum()
+
+        return turnover * capital * self.bps / 10_000

malatium-0.1.2/src/malatium/data.py

@@ -0,0 +1,45 @@
+from typing import Protocol
+import datetime as dt
+import polars as pl
+
+
+class CalendarProvider(Protocol):
+    """Provides the list of trading dates for a given range."""
+
+    def get(self, start: dt.date, end: dt.date) -> list[dt.date]: ...
+
+
+class ReturnsProvider(Protocol):
+    """Provides next-period forward returns with columns [date, ticker, return]."""
+
+    def get(self, date_: dt.date) -> pl.DataFrame: ...
+
+
+class AlphaProvider(Protocol):
+    """Provides expected returns with columns [date, ticker, alpha]."""
+
+    def get(self, date_: dt.date) -> pl.DataFrame: ...
+
+
+class FactorLoadingsProvider(Protocol):
+    """Provides factor exposures with columns [date, ticker, factor, loading]."""
+
+    def get(self, date_: dt.date) -> pl.DataFrame: ...
+
+
+class FactorCovariancesProvider(Protocol):
+    """Provides factor covariance matrix with columns [date, factor_1, factor_2, covariance]."""
+
+    def get(self, date_: dt.date) -> pl.DataFrame: ...
+
+
+class IdioVolProvider(Protocol):
+    """Provides idiosyncratic volatility with columns [date, ticker, idio_vol]."""
+
+    def get(self, date_: dt.date) -> pl.DataFrame: ...
+
+
+class BenchmarkProvider(Protocol):
+    """Provides benchmark portfolio weights with columns [date, ticker, weight]."""
+
+    def get(self, date_: dt.date) -> pl.DataFrame: ...