Metadata-Version: 2.4
Name: asr-open-sc
Version: 0.3.3
Summary: Meta-package and ecosystem registry for Alpha Stochastic Research quantitative-finance libraries.
Author-email: Alpha Kabinet TOURE <alpha_kabinet.toure@asr-lab.online>
Maintainer-email: Alpha Stochastic Research <research@asr-lab.online>
License-Expression: MIT
Project-URL: Homepage, https://asr-lab.online
Project-URL: Repository, https://github.com/Alpha-Stochastic-Research/asr-open-sc
Project-URL: Issues, https://github.com/Alpha-Stochastic-Research/asr-open-sc/issues
Project-URL: Documentation, https://github.com/Alpha-Stochastic-Research/asr-open-sc#readme
Project-URL: Changelog, https://github.com/Alpha-Stochastic-Research/asr-open-sc/blob/main/CHANGELOG.md
Project-URL: PyPI, https://pypi.org/project/asr-open-sc/
Project-URL: Organization, https://github.com/Alpha-Stochastic-Research
Keywords: alpha-stochastic-research,asr,quantitative-finance,financial-mathematics,stochastic-processes,risk-management,deep-hedging,option-pricing,monte-carlo-simulation,financial-machine-learning,scientific-computing,open-science,reproducible-research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS.md
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: twine>=5.0; extra == "dev"
Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "dev"
Provides-Extra: bachelier
Requires-Dist: asr-theory-of-speculation<2.0.0,>=1.1.0; extra == "bachelier"
Provides-Extra: risk
Requires-Dist: asr-var-cvar-tail-risk<2.0.0,>=1.0.0; extra == "risk"
Provides-Extra: hedging
Requires-Dist: asr-deep-hedging<0.3.0,>=0.2.0; python_version >= "3.11" and extra == "hedging"
Provides-Extra: all
Requires-Dist: asr-theory-of-speculation<2.0.0,>=1.1.0; extra == "all"
Requires-Dist: asr-var-cvar-tail-risk<2.0.0,>=1.0.0; extra == "all"
Requires-Dist: asr-deep-hedging<0.3.0,>=0.2.0; python_version >= "3.11" and extra == "all"
Dynamic: license-file

<div align="center">

# Alpha Stochastic Research Open Science

### Meta-package and ecosystem registry for ASR quantitative-finance libraries

**Alpha Stochastic Research**  
*Independent Quantitative Finance Research Laboratory*

<br>

[![PyPI version](https://img.shields.io/pypi/v/asr-open-sc?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/asr-open-sc/)
[![Python versions](https://img.shields.io/pypi/pyversions/asr-open-sc?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/asr-open-sc/)
[![Python CI](https://img.shields.io/github/actions/workflow/status/Alpha-Stochastic-Research/asr-open-sc/python-ci.yml?branch=main&style=for-the-badge&logo=githubactions&label=Python%20CI)](https://github.com/Alpha-Stochastic-Research/asr-open-sc/actions/workflows/python-ci.yml)
[![License](https://img.shields.io/badge/License-MIT-16A34A?style=for-the-badge)](LICENSE)

<br>

[![Deep Hedging](https://img.shields.io/badge/asr--deep--hedging-v0.2.0-0F766E?style=for-the-badge&logo=github)](https://github.com/Alpha-Stochastic-Research/asr-deep-hedging/releases)
[![Deep Hedging Paper](https://img.shields.io/badge/Deep%20Hedging%20Paper-10.5281%2Fzenodo.21519919-1682D4?style=for-the-badge)](https://doi.org/10.5281/zenodo.21519919)

<br>

[![Website](https://img.shields.io/badge/Website-asr--lab.online-0A2540?style=for-the-badge)](https://asr-lab.online)
[![GitHub](https://img.shields.io/badge/GitHub-Alpha%20Stochastic%20Research-181717?style=for-the-badge&logo=github)](https://github.com/Alpha-Stochastic-Research)
[![Contact](https://img.shields.io/badge/Contact-research%40asr--lab.online-0A2540?style=for-the-badge)](mailto:research@asr-lab.online)
</div>

---

## Overview

`asr-open-sc` is the lightweight meta-package, package catalogue, and installation coordinator for the **Alpha Stochastic Research (ASR)** Python ecosystem.

The project does not duplicate the scientific implementation of every ASR library. Instead, it provides:

- a stable registry of ASR distributions;
- package names, import paths, versions, maturity statuses, repositories, PyPI pages, and research identifiers;
- optional dependency groups for installing compatible ASR libraries;
- a shared architectural policy for namespace-based and standalone ASR packages;
- automated validation of registry metadata and ecosystem integrations.

The current release is:

```text
asr-open-sc 0.3.3
```

Install the lightweight registry:

```bash
python -m pip install --upgrade asr-open-sc
```

Import it with:

```python
import asr.open_sc as asr_sc

print(asr_sc.__version__)
asr_sc.print_ecosystem()
```

Expected version:

```text
0.3.3
```

> [!IMPORTANT]
> `asr-open-sc` is an ecosystem coordinator, not a monolithic quantitative-finance library. Scientific implementations remain independently versioned, tested, documented, and released from their dedicated repositories.

---

## What is new in version 0.3.3

Version `0.3.3` formally integrates **ASR Deep Hedging v0.2.0** into the ecosystem.

The release:

- registers `asr-deep-hedging` as a published ASR package;
- records its real Python import path, `deep_hedging`;
- adds the `hedging` optional dependency group;
- includes Deep Hedging in the `all` ecosystem installation;
- adds package-version, PyPI, DOI, Python-requirement, and category metadata to the registry;
- adds lookup and filtering utilities;
- updates Bachelier from `research-release` to `published`;
- synchronizes the package version across `pyproject.toml`, `__init__.py`, tests, citation metadata, and documentation;
- fixes the invalid Dependabot configuration;
- strengthens CI, packaging validation, clean-wheel testing, and PyPI publication checks;
- corrects broken installation commands present in the previous README.

---

## Distribution names and import paths

A PyPI distribution name and a Python import path are related, but they are not necessarily identical.

### Registry package

```text
Distribution: asr-open-sc
Import path:  asr.open_sc
```

### Bachelier package

```text
Distribution: asr-theory-of-speculation
Import path:  asr.models.bachelier
```

### Tail-risk package

```text
Distribution: asr-var-cvar-tail-risk
Import path:  asr.risk.tail
```

### Deep Hedging package

```text
Distribution: asr-deep-hedging
Import path:  deep_hedging
```

Deep Hedging intentionally uses a standalone top-level import package. `asr-open-sc` records the package exactly as it is distributed and does not create a fictitious `asr.ml.deep_hedging` compatibility layer.

---

## Installation

### Registry only

This is the smallest installation:

```bash
python -m pip install --upgrade asr-open-sc
```

It installs the registry without forcing installation of every scientific package.

### Bachelier research package

```bash
python -m pip install "asr-open-sc[bachelier]"
```

Equivalent direct installation:

```bash
python -m pip install "asr-theory-of-speculation>=1.1.0,<2.0.0"
```

Import:

```python
from asr.models import bachelier
```

### Tail-risk package

```bash
python -m pip install "asr-open-sc[risk]"
```

Equivalent direct installation:

```bash
python -m pip install "asr-var-cvar-tail-risk>=1.0.0,<2.0.0"
```

Import:

```python
from asr.risk.tail import TailRiskConfig
```

### Deep Hedging package

Deep Hedging requires Python `3.11` or newer.

```bash
python -m pip install "asr-open-sc[hedging]"
```

Equivalent direct installation:

```bash
python -m pip install "asr-deep-hedging>=0.2.0,<0.3.0"
```

Import:

```python
from deep_hedging import (
    Adam,
    TanhMLP,
    black_scholes_delta,
    evaluate_positions,
    simulate_gbm,
    train_step,
)
```

### All activated ASR packages

On Python `3.11` or newer:

```bash
python -m pip install "asr-open-sc[all]"
```

The `all` extra currently includes:

```text
asr-theory-of-speculation >=1.1.0,<2.0.0
asr-var-cvar-tail-risk    >=1.0.0,<2.0.0
asr-deep-hedging          >=0.2.0,<0.3.0
```

On Python `3.10`, the base registry, Bachelier package, and tail-risk package remain supported. The Deep Hedging dependency is guarded by a Python-version marker because Deep Hedging requires Python `3.11+`.

### Development installation

```bash
git clone https://github.com/Alpha-Stochastic-Research/asr-open-sc.git
cd asr-open-sc

python -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

Windows PowerShell:

```powershell
python -m venv .venv
.venv\Scripts\Activate.ps1

python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

---

## Quick start

### Print the ecosystem

```python
import asr.open_sc as asr_sc

print(asr_sc.__version__)
asr_sc.print_ecosystem()
```

### List every registered package

```python
from asr.open_sc import available_packages

for package in available_packages():
    print(package.name)
    print(package.import_path)
    print(package.version)
    print(package.status)
    print(package.repository)
    print(package.pypi_url)
    print(package.doi)
    print()
```

### Find one package

```python
from asr.open_sc import get_package

deep_hedging = get_package("asr-deep-hedging")

print(deep_hedging.version)
print(deep_hedging.import_path)
print(deep_hedging.status)
```

Expected values:

```text
0.2.0
deep_hedging
published
```

### Filter by status

```python
from asr.open_sc import available_packages

published = available_packages(status="published")

for package in published:
    print(package.name, package.version)
```

### Retrieve the status mapping

```python
from asr.open_sc import package_status

print(package_status())
```

### Retrieve only published packages

```python
from asr.open_sc import published_packages

for package in published_packages():
    print(package.name)
```

---

## Current ecosystem registry

| Distribution | Import path | Version | Status | Python | Category |
|---|---|---:|---|---|---|
| `asr-open-sc` | `asr.open_sc` | `0.3.3` | `active` | `>=3.10` | Infrastructure |
| `asr-theory-of-speculation` | `asr.models.bachelier` | `1.1.0` | `published` | `>=3.10` | Financial mathematics |
| `asr-var-cvar-tail-risk` | `asr.risk.tail` | `1.0.0` | `published` | `>=3.10` | Quantitative risk |
| `asr-deep-hedging` | `deep_hedging` | `0.2.0` | `published` | `>=3.11` | Financial machine learning |
| `asr-portfolio-optimization` | `asr.portfolio.optimization` | — | `planned` | — | Portfolio management |
| `asr-hierarchical-risk-parity` | `asr.portfolio.hrp` | — | `planned` | — | Portfolio management |
| `asr-agentic-trading-systems` | `asr.agents.trading` | — | `planned` | — | Financial AI |

### Registry status values

| Status | Meaning |
|---|---|
| `planned` | The project is part of the research roadmap but has not been released. |
| `development` | Implementation is active, but the public release contract is not complete. |
| `research-release` | A research repository or pre-release artifact exists, but stable package integration is incomplete. |
| `published` | A public Python distribution has been released and is registered for installation. |
| `active` | Core ecosystem infrastructure is actively maintained. |
| `deprecated` | The package should not be selected for new work. |

---

## ASR Deep Hedging integration

### Research output

**Deep Hedging under Transaction Costs: An Auditable NumPy Implementation and Exploratory Study**

- Paper DOI: <https://doi.org/10.5281/zenodo.21519919>
- Repository: <https://github.com/Alpha-Stochastic-Research/asr-deep-hedging>
- PyPI: <https://pypi.org/project/asr-deep-hedging/>
- Registered version: `0.2.0`
- Import package: `deep_hedging`

### Scientific scope

The package provides an auditable NumPy implementation for:

- discrete-time option hedging;
- proportional and quadratic transaction costs;
- exact finite-sample empirical CVaR;
- pathwise hedging-loss gradients;
- Geometric Brownian Motion simulation;
- full-truncation Heston simulation;
- state-only and inventory-aware neural policies;
- manually implemented neural-network gradients;
- Adam optimization;
- classical benchmark strategies;
- evaluation and paired-bootstrap utilities.

### Minimal simulation

```python
from deep_hedging import simulate_gbm

prices = simulate_gbm(
    n_paths=10_000,
    n_steps=30,
    s0=100.0,
    maturity=30 / 252,
    mu=0.0,
    sigma=0.20,
    seed=42,
)

print(prices.shape)
```

### Public API example

```python
from deep_hedging import (
    Adam,
    TanhMLP,
    simulate_gbm,
    train_step,
)

maturity = 30 / 252

network = TanhMLP(
    input_dim=2,
    hidden=16,
    delta_max=1.5,
    seed=1,
)

optimizer = Adam(
    network.params,
    lr=3e-3,
)

prices = simulate_gbm(
    n_paths=4_096,
    n_steps=30,
    s0=100.0,
    maturity=maturity,
    sigma=0.20,
    seed=100,
)

cvar, losses, deltas, details, grad_norm = train_step(
    network,
    optimizer,
    prices=prices,
    strike=100.0,
    maturity=maturity,
    alpha=0.95,
    kappa=0.01,
    cost_kind="linear",
)

print(cvar)
print(grad_norm)
print(deltas.shape)
```

> [!NOTE]
> `asr-open-sc` installs and registers Deep Hedging but does not re-export its scientific functions. Import them from `deep_hedging`.

---

## Published Bachelier package

Install:

```bash
python -m pip install "asr-open-sc[bachelier]"
```

Use:

```python
from asr.models import bachelier

time_grid, paths = bachelier.simulate_paths(
    initial_price=100.0,
    volatility=2.0,
    maturity=1.0,
    n_steps=250,
    n_paths=5_000,
    seed=42,
)

price = bachelier.call_price(
    initial_price=100.0,
    strike=100.0,
    volatility=2.0,
    maturity=1.0,
)

print(paths.shape)
print(price)
```

Research paper:

<https://doi.org/10.5281/zenodo.21385499>

---

## Published tail-risk package

Install:

```bash
python -m pip install "asr-open-sc[risk]"
```

Use:

```python
from asr.risk.tail import (
    TailRiskConfig,
    empirical_cvar,
    empirical_var,
    simulate_student_t_losses,
)

config = TailRiskConfig()

losses = simulate_student_t_losses(
    n_paths=config.n_paths,
    notional=config.notional,
    volatility=config.volatility,
    degrees_of_freedom=config.degrees_of_freedom,
    seed=config.seed,
)

var_99 = empirical_var(losses, 0.99)
cvar_99 = empirical_cvar(losses, 0.99)

print(f"99% VaR:  USD {var_99:,.2f}")
print(f"99% CVaR: USD {cvar_99:,.2f}")
```

---

## Namespace architecture

ASR supports two package-integration patterns.

### Shared namespace packages

These packages contribute modules beneath the implicit `asr` namespace:

```text
asr
├── open_sc
├── models
│   └── bachelier
├── risk
│   └── tail
└── portfolio
    ├── optimization
    └── hrp
```

Packages participating in the shared namespace should normally avoid creating:

```text
src/asr/__init__.py
```

The parent `asr` directory should remain an implicit namespace package so independently distributed projects can coexist.

Recommended configuration:

```toml
[tool.setuptools.packages.find]
where = ["src"]
include = ["asr*"]
namespaces = true
```

### Standalone packages

An ASR project may preserve a standalone import identity when that identity is already part of its public package contract.

Deep Hedging uses:

```python
import deep_hedging
```

The registry records this real import path rather than forcing every project into the shared namespace.

---

## Registry API

### `ASRPackage`

Each registry entry exposes:

```text
name
import_path
description
status
repository
version
pypi_url
doi
python_requires
category
```

### `available_packages`

```python
from asr.open_sc import available_packages

all_packages = available_packages()
published = available_packages(status="published")
```

### `get_package`

```python
from asr.open_sc import get_package

package = get_package("asr-deep-hedging")
```

An unknown distribution name raises `KeyError`.

### `package_status`

```python
from asr.open_sc import package_status

statuses = package_status()
```

### `published_packages`

```python
from asr.open_sc import published_packages

packages = published_packages()
```

### `print_ecosystem`

```python
from asr.open_sc import print_ecosystem

print_ecosystem()
```

---

## Repository structure

```text
asr-open-sc/
├── .github/
│   ├── CODEOWNERS
│   ├── dependabot.yml
│   └── workflows/
│       ├── publish-pypi.yml
│       └── python-ci.yml
├── src/
│   └── asr/
│       └── open_sc/
│           ├── __init__.py
│           └── registry.py
├── tests/
│   └── test_registry.py
├── AUTHORS.md
├── CHANGELOG.md
├── CITATION.cff
├── CONTRIBUTING_PROJECTS.md
├── LICENSE
├── README.md
├── RELEASE_NOTES_v0.3.3.md
├── pyproject.toml
└── requirements.txt
```

---

## Development and validation

Install development dependencies:

```bash
python -m pip install -e ".[dev]"
```

Run linting:

```bash
ruff check src tests
```

Run tests:

```bash
pytest
```

Build distributions:

```bash
rm -rf build dist *.egg-info src/*.egg-info
python -m build
```

Validate metadata:

```bash
python -m twine check dist/*
```

Test the wheel in a clean environment:

```bash
python -m venv .wheel-test
source .wheel-test/bin/activate

python -m pip install --upgrade pip
python -m pip install dist/asr_open_sc-0.3.3-py3-none-any.whl

python -c "import asr.open_sc as asr_sc; print(asr_sc.__version__)"
python -c "from asr.open_sc import get_package; print(get_package('asr-deep-hedging'))"

deactivate
rm -rf .wheel-test
```

Test all activated extras on Python `3.11+`:

```bash
python -m pip install ".[all]"
python -m pip check

python -c "from asr.models import bachelier; print('Bachelier OK')"
python -c "from asr.risk.tail import TailRiskConfig; print('Tail risk OK')"
python -c "from deep_hedging import simulate_gbm; print('Deep Hedging OK')"
```

---

## Release checklist

Before publishing `0.3.3`:

1. Publish and verify `asr-deep-hedging==0.2.0` on PyPI.
2. Confirm `pyproject.toml` contains `version = "0.3.3"`.
3. Confirm `asr.open_sc.__version__ == "0.3.3"`.
4. Run `ruff check src tests`.
5. Run `pytest`.
6. Install and test `.[all]` on Python `3.11+`.
7. Run `python -m build`.
8. Run `python -m twine check dist/*`.
9. Test the generated wheel in a clean environment.
10. Create the GitHub tag `v0.3.3`.
11. Publish the GitHub release.
12. Verify `asr-open-sc==0.3.3` on PyPI.

The release tag must be:

```text
v0.3.3
```

not:

```text
v.0.3.3
```

---

## Scientific and engineering principles

ASR packages are expected to be:

- independently installable;
- independently versioned;
- independently testable;
- reproducible;
- explicit about assumptions and limitations;
- compatible with documented Python versions;
- supported by citation metadata;
- transparent about research maturity;
- integrated into the ecosystem only after release validation.

---

## Contributing

Guidance for creating, publishing, and registering an ASR project is provided in:

[`CONTRIBUTING_PROJECTS.md`](CONTRIBUTING_PROJECTS.md)

Contributions should use pull requests, pass CI, preserve backward compatibility, and update tests and documentation whenever registry metadata or dependency groups change.

---

## Citation

Citation metadata are provided in [`CITATION.cff`](CITATION.cff).

Suggested citation:

```text
Alpha Kabinet TOURE.
asr-open-sc: Meta-package and Ecosystem Registry for Alpha Stochastic Research.
Version 0.3.3. Alpha Stochastic Research, 2026.
https://github.com/Alpha-Stochastic-Research/asr-open-sc
```

---

## License

The source code is released under the MIT License. See [`LICENSE`](LICENSE).

---

## Disclaimer

This software is provided for research, education, reproducibility, and open-source development.

It does not constitute investment, trading, financial, legal, or regulatory advice. It is not a production trading or risk-management system. Users are responsible for independently validating all packages, models, data, assumptions, and numerical results before practical use.

---

<div align="center">

**Alpha Stochastic Research**  
Independent Quantitative Finance Research Laboratory

*Research → Modelling → Analysis → Impact*

<https://asr-lab.online>

© 2026 Alpha Stochastic Research

</div>
