proteusllp-optimisation-package 0.1.3
Proteus Optimisation Package (POP): Domain-agnostic stochastic optimization engine for PAL variables
License: MIT License
Requires Python: >=3.13
Keywords: optimization, stochastic, portfolio, risk-analysis, PAL, actuarial

<div style="display: flex; align-items: center; gap: 15px;">
  <img src="https://raw.githubusercontent.com/ProteusLLP/proteusllp-optimisation-package/main/POP.svg" alt="POP Logo" width="80"/>
  <div>
    <h1 style="margin: 0;">Proteus Optimisation Package (POP)</h1>
    <p style="margin: 5px 0 0 0;">
      <a href="https://proteusllp-optimisation-package.readthedocs.io/en/latest/?badge=latest">
        <img src="https://readthedocs.org/projects/proteusllp-optimisation-package/badge/?version=latest" alt="Documentation Status"/>
      </a>
    </p>
  </div>
</div>

<br/>

Domain-agnostic stochastic optimization engine for [PAL (Proteus Actuarial Library)](https://proteusllp-actuarial-library.readthedocs.io/) variables.

## Features

- **🎯 Metric-Centric Design**: Unified framework for objectives and constraints
- **📊 Multiple Metric Types**: Mean, Std, SpreadVaR, plus composite metrics (Ratio, Product, Sum, Difference)
- **🔗 Composite Metrics**: Build complex metrics like Sharpe ratios, risk-adjusted returns
- **🎲 Dual Data Support**: StochasticScalar (aggregated) and FreqSevSims (frequency-severity)
- **⚖️ Flexible Constraints**: Portfolio-level and occurrence-level constraints
- **📈 Efficient Frontiers**: Parallel constraint variation for risk-return tradeoff analysis
- **✅ Type-Safe API**: Pydantic models with comprehensive validation

## Installation

### From PyPI

```bash
pip install proteusllp-optimisation-package
```

### From Local Source (Development)

```bash
pip install -e /proteus-optimisation-package
```

## Quick Start

```python
from pop import (
    ObjectiveSpec, OptimizationInput, SimpleConstraint,
    MeanMetric, StdMetric, optimize
)
from pal.variables import ProteusVariable
from pal import StochasticScalar

# Create PAL variable with return simulations
returns = ProteusVariable("item", {
    "stock_a": StochasticScalar([0.10, 0.12, 0.08]),
    "stock_b": StochasticScalar([0.15, 0.18, 0.12])
})

# Define objective: maximize expected return
objective = ObjectiveSpec(
    objective_value=returns,
    metric=MeanMetric(),
    direction="maximize"
)

# Add risk constraint: limit portfolio std dev
risk_constraint = SimpleConstraint(
    constraint_value=returns,
    metric=StdMetric(),
    threshold=0.15,
    direction="cap",
    name="max_risk"
)

# Create optimization problem
opt_input = OptimizationInput(
    item_ids=["stock_a", "stock_b"],
    current_shares={"stock_a": 100.0, "stock_b": 100.0},
    objective=objective,
    simple_constraints=[risk_constraint]
)

# Run optimization
result = optimize(opt_input.preprocess())
print(f"Optimal shares: {result.optimal_shares}")
print(f"Expected return: {result.objective_value:.4f}")
```

## Documentation

Full documentation is available at [proteusllp-optimisation-package.readthedocs.io](https://proteusllp-optimisation-package.readthedocs.io).

## Requirements

- Python 3.13+
- PAL (Proteus Analytics Library) >=0.2.8
- NumPy >=2.2
- SciPy >=1.15
- Pydantic >=2.0
- cvxopt

## Development

### Setup

```bash
# Clone the repository
git clone https://github.com/ProteusLLP/proteusllp-optimisation-package.git
cd proteusllp-optimisation-package

# Open in VS Code - will prompt to reopen in devcontainer
code .  # Runs 'pdm install' automatically

# Or install locally with PDM
pdm install
```

### Running Checks

```bash
# Run tests
pytest tests/ -v

# Run static analysis (lint, format, security, deadcode)
make static-analysis

# Run typecheck separately (has known issues with PAL's dynamic types)
make typecheck
```

**Note on Type Checking**: Pyright type checking is temporarily excluded from CI due to PAL's dynamic typing patterns. PAL adds attributes like `.occurrence`, `.sim_index`, and `.n_sims` at runtime, which pyright cannot fully infer. All tests pass, confirming functional correctness.

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.