Metadata-Version: 2.4
Name: portfolio-risk-lab
Version: 0.1.0
Summary: Portfolio rebalancing and uncertainty-aware risk budgeting for decision support
Author: Garros Gong
License: MIT License
        
        Copyright (c) 2026 Garros Gong
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
        Scope note: This grant applies to original work in portfolio_risk_lab/, docs/,
        assets/readme/, tests_package/, tests_site/, and new project documentation and
        packaging files. It does not relicense historical third-party content in src/,
        legacy tests/, or data/. See THIRD_PARTY_NOTICES.md.
        
Project-URL: Homepage, https://garroshub.github.io/portfolio-risk-lab/
Project-URL: Source, https://github.com/garroshub/portfolio-risk-lab
Project-URL: Documentation, https://github.com/garroshub/portfolio-risk-lab#python-api
Project-URL: Issues, https://github.com/garroshub/portfolio-risk-lab/issues
Keywords: portfolio optimization,risk budgeting,scenario robustness,decision support
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Provides-Extra: market
Requires-Dist: yfinance>=0.2.40; extra == "market"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Dynamic: license-file

# Portfolio Risk & Rebalancing Lab

**General-purpose portfolio optimization and uncertainty-aware risk budgeting for portfolio-manager decision support.**

[Interactive PM decision workspace](https://garroshub.github.io/portfolio-risk-lab/) · [GitHub source](https://github.com/garroshub/portfolio-risk-lab) · [Issues](https://github.com/garroshub/portfolio-risk-lab/issues) · [MIT license and notices](https://github.com/garroshub/portfolio-risk-lab/blob/main/THIRD_PARTY_NOTICES.md)

Portfolio Risk Lab provides a general-purpose NumPy, pandas and SciPy API and CLI to compare conventional long-only portfolios with scenario-robust risk budgeting.

## Quick start

```bash
pip install portfolio-risk-lab
portfolio-risk-lab demo --output sample.json
```

```python
import pandas as pd
from portfolio_risk_lab import PortfolioAnalyzer, RiskConfig

daily_returns = pd.read_csv(
    "daily_returns.csv", parse_dates=["date"]
).set_index("date")

model = PortfolioAnalyzer(
    daily_returns,
    config=RiskConfig(
        risk_budget=0.12,
        max_weight=0.40,
        cash_asset="Cash_Proxy",
        transaction_cost_bps=10,
    ),
)
result = model.compare(
    methods=["standard", "scenario_robust"],
    uncertainty="historical_calibration",
)
print(result.allocation_comparison)
print(result.risk_budget_analysis)
```

Input values are daily simple decimal returns; `0.01` denotes +1%, not a price level. At least 504 daily rows are required by default.

## Features

- Standard and scenario-robust mean–variance optimization with hard long-only, fully invested position and risk constraints.
- Annualized long-window, short-window and EWMA covariance forecasts.
- Historical risk-error margin using exclusively matured, completed calendar months.
- Asset-weight comparisons, model disagreement, risk contributions, one-time trade-cost estimates, and JSON output.
- Data-source agnostic API/CLI, without broker accounts, order execution or Streamlit.

## Research boundaries

The library is intended for research and decision support, not trading signals or investment advice. Historical reference-portfolio error quantiles do not guarantee future risk-limit coverage. Exploratory backtests did not establish a persistent increase in economic utility over simply tighter conventional risk limits.

The [GitHub Pages decision workspace](https://garroshub.github.io/portfolio-risk-lab/) is a separate browser-only JavaScript approximation using simulated portfolio data. It is not the SciPy solver and does not retrieve live market prices.

The MIT license grants rights to newly authored Portfolio Risk Lab code. Historic third-party files in the GitHub repository are not bundled into the Python distribution and are explicitly excluded from the new-code license grant.
