Metadata-Version: 2.4
Name: asrquant
Version: 1.3.0
Summary: Quantitative research infrastructure for market data, validation, fixed income, risk, portfolio construction, backtesting, and auditable research workflows.
Author: Alpha Kabinet TOURE, Srijan Mishra
Author-email: Alpha Stochastic Research <research@asr-lab.online>
License-Expression: MIT
Project-URL: Homepage, https://www.asr-lab.online
Project-URL: Repository, https://github.com/Alpha-Stochastic-Research/asr-quant
Project-URL: Documentation, https://alpha-stochastic-research.github.io/asr-quant/
Project-URL: Issues, https://github.com/Alpha-Stochastic-Research/asr-quant/issues
Project-URL: Changelog, https://github.com/Alpha-Stochastic-Research/asr-quant/blob/main/CHANGELOG.md
Project-URL: Paper, https://github.com/Alpha-Stochastic-Research/asr-quant/blob/main/paper/ASRQuant_paper.pdf
Keywords: quantitative finance,quantitative research,fixed income,interest rates,backtesting,risk,portfolio,factor models,market microstructure,reproducibility
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
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
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: pandas<4,>=2.0
Requires-Dist: scipy<2,>=1.11
Requires-Dist: statsmodels<1,>=0.14
Requires-Dist: pydantic<3,>=2.6
Requires-Dist: PyYAML<7,>=6.0
Provides-Extra: ml
Requires-Dist: scikit-learn<2,>=1.4; extra == "ml"
Requires-Dist: shap>=0.45; extra == "ml"
Requires-Dist: hmmlearn>=0.3; extra == "ml"
Provides-Extra: data
Requires-Dist: yfinance>=0.2.40; extra == "data"
Requires-Dist: openpyxl>=3.1; extra == "data"
Requires-Dist: pyarrow>=16; extra == "data"
Provides-Extra: providers
Requires-Dist: requests<3,>=2.31; extra == "providers"
Provides-Extra: visualization
Requires-Dist: matplotlib<4,>=3.8; extra == "visualization"
Requires-Dist: plotly<7,>=5.20; extra == "visualization"
Requires-Dist: jinja2<4,>=3.1; extra == "visualization"
Provides-Extra: literature
Requires-Dist: pypdf<7,>=5.9; extra == "literature"
Provides-Extra: optimization
Requires-Dist: cvxpy>=1.4; extra == "optimization"
Provides-Extra: volatility
Requires-Dist: arch>=7.0; extra == "volatility"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-cov>=5; extra == "dev"
Requires-Dist: ruff>=0.9; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: pip-audit>=2.7; extra == "dev"
Requires-Dist: bandit[toml]>=1.7; extra == "dev"
Requires-Dist: detect-secrets>=1.5; extra == "dev"
Requires-Dist: cyclonedx-bom>=5.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.5; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "docs"
Provides-Extra: all
Requires-Dist: scikit-learn<2,>=1.4; extra == "all"
Requires-Dist: shap>=0.45; extra == "all"
Requires-Dist: hmmlearn>=0.3; extra == "all"
Requires-Dist: cvxpy>=1.4; extra == "all"
Requires-Dist: arch>=7.0; extra == "all"
Requires-Dist: yfinance>=0.2.40; extra == "all"
Requires-Dist: openpyxl>=3.1; extra == "all"
Requires-Dist: pyarrow>=16; extra == "all"
Requires-Dist: requests<3,>=2.31; extra == "all"
Requires-Dist: matplotlib<4,>=3.8; extra == "all"
Requires-Dist: plotly<7,>=5.20; extra == "all"
Requires-Dist: jinja2<4,>=3.1; extra == "all"
Requires-Dist: pypdf<7,>=5.9; extra == "all"
Dynamic: license-file

<div align="center">

# ASRQuant

### Auditable quantitative finance research in Python

**Research · Modelling · Analysis · Reproducibility**

`pip install asrquant`

</div>

---

ASRQuant is the open-source quantitative-finance toolkit developed by **Alpha Stochastic Research (ASR)**. It connects data, hypothesis discovery, statistical research, fixed income, derivatives, portfolio construction, risk, factor models, market microstructure, backtesting, machine learning, simulation, visualization and reproducibility in one Python package.

The design principle is simple: **make quantitative workflows concise without hiding assumptions that materially change the result.**

[**Documentation**](https://alpha-stochastic-research.github.io/asr-quant/) · [**Repository**](https://github.com/Alpha-Stochastic-Research/asr-quant)

> **Stable release: 1.3.0.** The 1.0 paper contract, 1.1 Research Discovery / Interest Rates stack, and 1.2 canonical research API are preserved. Version 1.3 adds market-convention infrastructure, instrument/curve contracts, quote-space curve risk, credit foundations, advanced research validation, point-in-time data snapshots, experiment lineage, scenario and cost models, calibration/sensitivity frameworks, and stronger API compatibility controls. Guarded live-broker components remain fail-closed and require deployment-specific authorization.

## Documentation

Documentation is rebuilt automatically from the repository. Changes to source code or documentation on `main` trigger a strict MkDocs build, regenerate the source-derived API reference and deploy the resulting site through GitHub Pages. Pull requests run the same build as a validation gate without publishing.

## Install

```bash
pip install asrquant
```

Upgrade:

```bash
pip install --upgrade asrquant
```

Optional research dependencies:

```bash
pip install "asrquant[data]"          # Yahoo Finance, Excel, Parquet, Feather
pip install "asrquant[providers]"     # HTTP market-data / broker connectivity
pip install "asrquant[visualization]" # Matplotlib, Plotly and HTML reporting
pip install "asrquant[ml]"            # scikit-learn, SHAP, HMM extensions
pip install "asrquant[literature]"    # PDF literature ingestion
pip install "asrquant[optimization]"  # CVXPY extensions
pip install "asrquant[volatility]"    # ARCH / GARCH
pip install "asrquant[all]"
```

ASRQuant 1.3.0 declares and validates Python **3.10–3.13** in the release compatibility matrix.

## One import

```python
import asrquant as asr

print(asr.__version__)
# 1.3.0
```

The recommended public namespaces are intentionally predictable:

```text
asr.data           data ingestion, validation and providers
asr.hypotheses     data/literature hypothesis discovery and novelty audit
asr.alpha          cross-sectional signal research
asr.factors        PCA, exposures and factor-risk decomposition
asr.risk           VaR, ES, EVT, drawdown and portfolio risk
asr.microstructure spread, microprice, OFI, Kyle lambda and liquidity analytics
asr.validation     CPCV, PBO, Reality Check, SPA, leakage and multiverse analysis
asr.scenarios      cross-domain deterministic stress scenarios
asr.credit         hazard curves and CDS analytics
asr.backtesting    auditable backtesting
asr.portfolio      optimization, constraints and risk budgeting
asr.covariance     covariance estimators and holdout comparison
asr.costs          reusable transaction-cost and impact models
asr.stats          econometrics, bootstrap and inference
asr.ml             leakage-aware walk-forward ML
asr.options        derivative pricing and Greeks
asr.rates          conventions, curves, instruments, rates risk and IR derivatives
asr.calibration    generic calibrated-model diagnostics
asr.sensitivities finite-difference first/second/cross sensitivities
asr.dependence     Gaussian and Student-t copula research
asr.regimes        volatility, change-point and optional HMM regimes
asr.performance    factor and Brinson attribution
asr.stochastic     stochastic processes
asr.mc             Monte Carlo and variance-reduction tools
asr.vol            volatility modelling
asr.visuals        visualization catalogue
asr.research       experiments, reports and reproducible research workflow
asr.trading        paper trading and guarded execution primitives
```

Legacy 1.x entry points remain available for existing notebooks.

---


# What is new in 1.3

Version 1.3 is a research-infrastructure release rather than a feature-count release. It strengthens the path from market information to a reviewable quantitative decision.

## Independent audit corrections in the final build

The final source incorporates the release-candidate findings that materially affected numerical or interface behaviour: asymmetric key-rate bump partitions on uneven pillars; per-observation Sharpe scaling in PSR/DSR; explicit refusal of non-identifiable implied-volatility boundary inversions; deterministic PCA sign orientation; statsmodels 0.15 compatibility; Wilder RSI as the default convention with an explicit SMA option; fixed Gaussian-process noise contracts; Vasicek mean-reversion uncertainty reporting; and a configurable Omega threshold. Optional plotting, ML, HTTP and PDF stacks are no longer mandatory core dependencies and are imported only when their functionality is requested.

ASRQuant's quantitative-finance calculations remain native to the package: pricing, curve construction, rate risk, calibration and validation are implemented in ASRQuant rather than delegated to an external quantitative-finance engine. Numerical verification relies on analytical identities, round-trip tests, invariants, limiting cases and regression tests under explicit conventions.
Selected native-engine contracts can also be run directly with `PYTHONPATH=src python benchmarks/native_engine_contracts.py`.

## Market conventions, instruments and curve construction

```python
calendar = asr.rates.Calendar("TARGET")
schedule = asr.rates.Schedule(
    start="2026-09-15",
    end="2031-09-15",
    frequency="6M",
    calendar=calendar,
    day_count="ACT/360",
)

builder = asr.rates.CurveBuilder.from_quotes(
    valuation_date="2026-09-15",
    deposits={0.25: 0.0210, 0.50: 0.0220},
    swaps={1.0: 0.0230, 2.0: 0.0240, 5.0: 0.0260},
)
build = builder.build()
print(build.repricing_errors)
print(build.jacobian)
```

The curve build is not treated as successful merely because an optimizer returned: quote repricing and positive discount factors are exposed as diagnostics.

## Curve and quote-space risk

```python
swap = asr.rates.InterestRateSwap(
    maturity=5.0,
    fixed_rate=0.026,
    notional=10_000_000,
)

risk = asr.rates.curve_risk(swap, build.curve, build_result=build)
print(risk.dv01)
print(risk.key_rate_dv01)
print(risk.quote_pv01)
```

## Research validation

```python
splits = asr.validation.combinatorial_purged_cv_splits(
    n_samples=len(returns),
    n_groups=6,
    test_groups=2,
    embargo=5,
)

pbo = asr.validation.probability_of_backtest_overfitting(strategy_returns)
reality = asr.validation.reality_check(strategy_returns)
spa = asr.validation.spa_test(strategy_returns)
validation_report = asr.validation.strategy_report(strategy_returns)
```

`PBO`, Reality Check and SPA are research diagnostics, not guarantees that a strategy is economically valid. They are designed to make selection risk harder to ignore.

## Point-in-time data and snapshots

```python
store = asr.data.DataStore("./research-data")
snapshot = store.put("rates_panel", data, source="internal")
reloaded = store.get("rates_panel")

pit = asr.data.PointInTimeFrame(
    observations,
    observation_column="observation_time",
    available_column="available_time",
    revision_column="revision_time",
)
research_view = pit.as_of("2026-09-15")
```

Snapshots retain fingerprints and schema metadata; point-in-time views separate when an observation describes the world from when it was actually available to a researcher.

## Experiments, lineage and reports

```python
experiment = asr.research.Experiment(
    name="curve_signal",
    config={"lookback": 60, "cost_bps": 5},
    data={"market": data},
    seed=42,
)

registry = asr.research.ExperimentRegistry("experiments.jsonl")
registry.add(experiment)

report = asr.research.ResearchReport("curve_signal")
report.add(experiment, name="experiment")
report.add(pbo, name="validation")
report.export("research_report.html")

graph = asr.research.ResearchGraph()
graph.add("data", snapshot)
graph.add("experiment", experiment, depends_on=["data"])
graph.add("validation", validation_report, depends_on=["experiment"])
print(graph.stale_artifacts("data"))
```

## Credit and scenarios

```python
hazard = asr.credit.bootstrap_hazard_curve(
    build.curve,
    maturities=[1, 3, 5],
    spreads=[0.0080, 0.0110, 0.0140],
    recovery=0.40,
)
cds = asr.credit.CDS(maturity=5.0, spread=0.0140, notional=1_000_000)
print(cds.analytics(build.curve, hazard).summary)

stress = asr.scenarios.steepener(25.0)
scenario_result = asr.scenarios.run(stress, instrument=swap, curve=build.curve)
```

## Extensible adapters

Internal infrastructure can be registered without replacing the ASRQuant research layer:

```python
asr.register.data_provider("internal", internal_data_provider)
asr.register.pricer("rates", internal_rates_pricer)
asr.register.cost_model("desk", desk_cost_model)
```

---

# Stable public API

The high-level verbs are designed to be memorable:

```python
asr.data.load(...)
asr.data.validate(...)
asr.hypotheses.discover(...)
asr.backtesting.run(...)
asr.portfolio.optimize(...)
asr.options.price(...)
asr.rates.analyze(...)
asr.rates.calibrate(...)
asr.stats.regress(...)
asr.ml.fit(...)
```

Structured result objects expose consistent analysis helpers where applicable:

```python
result.summary
result.to_frame()
result.to_dict()
```

---

# Data

ASRQuant uses one data layer for local files, public URLs and provider-backed market data.

## CSV / local file

```python
prices = asr.data.load(
    "prices.csv",
    date_column="Date",
)
```

Supported local formats include CSV, Parquet, Excel, JSON and Feather.

## Public CSV URL

```python
macro = asr.data.load(
    "https://example.org/data.csv",
    date_column="DATE",
)
```

Remote reads use an explicit bounded HTTP request and preserve the same tabular contract.

## Yahoo Finance

Install the data extra first:

```bash
pip install "asrquant[data]"
```

Then:

```python
prices = asr.data.yahoo(
    ["SPY", "TLT", "GLD"],
    start="2020-01-01",
)
```

or through the generic loader:

```python
prices = asr.data.load(
    "yahoo",
    symbols=["SPY", "TLT"],
    start="2020-01-01",
)
```

## ECB yield-curve data

```python
curve_history = asr.data.ecb_yield_curve(
    maturities=["3M", "6M", "1Y", "2Y", "5Y", "10Y", "30Y"],
    start="2020-01-01",
)
```

The ECB connector uses the ECB Data Portal SDMX REST service and returns decimal annual rates. The generic `ECBProvider` remains available for arbitrary ECB series keys.

## Other providers

```python
fred = asr.data.from_provider("fred", "DGS10", field="Value")
btc = asr.data.from_provider("binance", "BTCUSDT", field="Close", interval="1d")
```

Provider adapters currently include ECB, Yahoo Finance, FRED, Binance and Alpha Vantage.

## Validate before research

```python
quality = asr.data.validate(prices)
print(quality.summary)
print(quality.issues)
```

Validation reports duplicates, missing values, infinities, non-numeric values, constant columns, index ordering and sampling gaps without silently changing the input.

---

# Hypothesis discovery

ASRQuant does not treat a statistically interesting pattern as scientific novelty. Version 1.2 separates **data evidence** from **novelty evidence**.

## From data

```python
ideas = asr.hypotheses.from_data(
    data,
    domain="fixed_income",
    targets="target",
    horizons=(1, 5, 20),
)

ideas.to_frame()
```

The discovery layer can screen chronology-safe candidate relationships, lagged effects, regime changes, structural breaks, cointegration and other research observations. Multiple-testing controls and holdout evidence are tracked explicitly.

## From literature

```python
corpus = asr.LiteratureCorpus.from_pdfs("papers/")
ideas = asr.hypotheses.from_literature(
    corpus,
    topic="interest-rate derivatives",
)
```

Source excerpts retain paper/page provenance.

## Combine data + papers + model disagreement + robustness

```python
ideas = asr.hypotheses.discover(
    data=data,
    papers=corpus,
    predictions=model_predictions,
    robustness_results=robustness_grid,
    robustness_metric="sharpe",
    domain="fixed_income",
)
```

## Search and novelty audit

```python
matches = asr.hypotheses.search(
    "Forward-curve instability precedes rate-regime changes",
    hypotheses=ideas,
    papers=corpus,
)

audit = asr.hypotheses.audit(ideas[0], corpus=corpus)
print(audit.novelty_status)
```

A corpus-relative gap is **not** a claim of global novelty. The public statuses are intentionally conservative.

## Start a research project

```python
project = ideas[0].start()
```

That hands the selected hypothesis to the existing reproducible `ResearchProject` workflow.

---

# Cross-sectional alpha research

```python
signal = prices.pct_change(20, fill_method=None).shift(1)
signal = asr.alpha.cross_sectional_zscore(signal)

future = asr.alpha.forward_returns(prices, periods=(1, 5, 20))
report = asr.alpha.analyze_signal(
    signal,
    future[5],
    quantiles=5,
)

print(report.summary)
```

The alpha layer includes:

- cross-sectional winsorization, ranking and z-scores;
- signal neutralization against exposures;
- forward returns;
- Pearson/Spearman Information Coefficient;
- IC decay;
- quantile portfolios and long-short spreads;
- signal-to-weight conversion;
- turnover diagnostics.

---

# Factor research

## PCA factors

```python
pca = asr.factors.pca(returns, n_components=3)
print(pca.explained_variance_ratio)
print(pca.loadings)
```

## Time-series factor exposures

```python
exposure = asr.factors.exposures(
    asset_returns,
    factor_returns,
    covariance="HAC",
)

print(exposure.to_frame())
```

## Factor-risk decomposition

```python
risk = asr.factors.risk_decomposition(
    weights,
    betas,
    factor_covariance,
    specific_variance,
)

print(risk.summary)
```

---

# Portfolio risk

```python
risk = asr.risk.portfolio_risk_report(
    returns,
    weights,
    level=0.99,
)

print(risk.summary)
```

Available analytics include:

- historical, Gaussian and Cornish-Fisher VaR;
- Expected Shortfall;
- rolling VaR;
- covariance / Euler risk contribution;
- Expected Shortfall contribution;
- scenario P&L;
- volatility and exposure diagnostics.

---

# Market microstructure

```python
micro = asr.microstructure.microprice(
    bid,
    ask,
    bid_size,
    ask_size,
)

ofi = asr.microstructure.order_flow_imbalance(
    bid,
    ask,
    bid_size,
    ask_size,
)
```

The microstructure namespace includes quoted, effective and realized spreads, microprice, price impact, order-flow imbalance, Amihud illiquidity, Roll spread and Kyle lambda.

---

# Portfolio construction

```python
result = asr.portfolio.optimize(
    returns,
    method="maximum_sharpe",
    covariance_method="ledoit_wolf",
)

print(result.weights)
print(result.summary)
```

Supported allocation methods include:

- minimum variance;
- maximum Sharpe;
- equal risk contribution / risk parity;
- maximum diversification;
- hierarchical risk parity;
- efficient frontier;
- Black-Litterman utilities.

Covariance estimators include sample, EWMA, Ledoit-Wolf and OAS.

---

# Backtesting

```python
spec = asr.BacktestSpec(
    execution_delay=1,
    costs=asr.CostModel(
        commission_bps=1,
        spread_bps=2,
        slippage_bps=1,
    ),
)

result = asr.backtesting.run(
    prices,
    target_weights,
    spec=spec,
)

print(result.summary)
result.report("report.html")
```

The engine tracks target/effective weights, transaction costs, borrow cost, turnover, equity, trades and experiment fingerprints.

---

# Statistics and econometrics

```python
fit = asr.stats.regress(
    y,
    x,
    method="ols",
    covariance="HAC",
)
```

The statistics layer includes OLS, quantile regression, factor regression, polynomial regression, logistic regression, Ridge/Lasso/Elastic Net, stationarity tests, block bootstrap, permutation tests, Benjamini-Hochberg FDR, cointegration, Granger causality, ARIMA, VAR and autoregression utilities.

---

# Machine learning

```python
result = asr.ml.fit(
    "ridge",
    features,
    target,
    train_size=504,
    test_size=63,
    gap=5,
    task="regression",
)

print(result.summary)
```

Walk-forward splits are chronological and estimators are re-fitted per fold. ASRQuant does not randomly shuffle time-series observations in this workflow.

---

# Fixed income & interest-rate derivatives

ASRQuant contains a dedicated interest-rate research stack for:

- day-count conventions and schedules;
- discount factors, zero rates and forward rates;
- discount and projection curves;
- multi-curve construction;
- Nelson-Siegel and Svensson calibration;
- bonds, FRAs, futures, swaps and basis swaps;
- OIS / overnight compounding;
- DV01, key-rate DV01 and convexity;
- caps, floors, caplets and swaptions;
- Black-76, Bachelier and SABR volatility;
- Vasicek, CIR, Hull-White, Ho-Lee and Black-Karasinski;
- HJM and LMM simulation;
- PCA / level-slope-curvature analysis;
- carry and roll-down;
- curve interpolation risk and no-arbitrage diagnostics;
- key-rate hedging and rate scenarios;
- Bermudan LSM building blocks.

Example:

```python
curve = asr.rates.DiscountCurve.from_zero_rates(
    maturities=[0.5, 1, 2, 5, 10],
    zero_rates=[0.025, 0.027, 0.029, 0.032, 0.034],
)

analysis = asr.rates.analyze(curve)
print(analysis.summary)
```

---

# Derivatives

```python
price = asr.options.price(
    "black_scholes",
    spot=100,
    strike=100,
    maturity=1.0,
    rate=0.03,
    volatility=0.20,
)

print(price.summary)
```

Pricing tools include Black-Scholes-Merton, Black-76, Bachelier, CRR trees, Monte Carlo and implied-volatility inversion.

---

# Simulation and Monte Carlo

```python
paths = asr.stochastic.simulate(
    "heston",
    steps=252,
    paths=10_000,
    random_state=7,
)
```

Supported process families include ABM, GBM, OU, CIR, Vasicek, Heston, Merton jump diffusion and regime-switching processes.

The universal Monte Carlo layer supports custom generators, estimators, empirical quantiles, confidence intervals, expected shortfall, path-dependent losses, parameter surfaces and animations.

---

# Research workflow

ASRQuant can connect the full chain:

```text
Evidence / Data
      ↓
Observation
      ↓
Research Question
      ↓
Hypothesis
      ↓
Data Plan
      ↓
Features / Model / Signal
      ↓
Backtest / Experiment
      ↓
Robustness & Falsification
      ↓
Decision
      ↓
Research Note / Publication Pack
```

The existing `ResearchProject`, `ResearchBoard` and `WeeklyResearchCycle` APIs remain available.

---

# Guarded trading and production readiness

ASRQuant includes paper-broker objects, risk policies, audit storage, reconciliation and guarded live-broker primitives. These are deliberately separated from research validity.

Installing the package **does not authorize live capital deployment**. Live components require explicit deployment evidence, a matching certificate and risk-policy gates.

---

# End-to-end example

```python
import asrquant as asr

# 1. Data
prices = asr.data.yahoo(["SPY", "TLT", "GLD"], start="2018-01-01")
quality = asr.data.validate(prices)

# 2. Returns
returns = prices.pct_change(fill_method=None).dropna()

# 3. Factors
pca = asr.factors.pca(returns, n_components=2)

# 4. Portfolio
portfolio = asr.portfolio.optimize(
    returns,
    method="maximum_sharpe",
    covariance_method="ledoit_wolf",
)

# 5. Risk
risk = asr.risk.portfolio_risk_report(
    returns,
    portfolio.weights,
    level=0.99,
)

print(portfolio.summary)
print(risk.summary)
```

For research projects, replace step 2 with `asr.hypotheses.discover(...)` and hand the selected candidate to `candidate.start()`.

---

# Reproducibility rules

ASRQuant is opinionated about research hygiene:

- preserve source/provenance metadata;
- make missing-data policy explicit;
- separate signal time from execution time;
- model costs explicitly;
- use chronological validation for time series;
- correct for multiple testing when exploring many hypotheses;
- separate in-sample evidence from holdout evidence;
- separate data support from scientific novelty;
- save configuration and experiment fingerprints;
- never infer live-deployment authorization from package installation.

---

# Development

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

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -e ".[dev,all]"
```

Run the full domain suite:

```bash
python scripts/test_all.py --group all
```

Run the 1.2 integration suite:

```bash
pytest -q \
  tests/test_api_consistency_v120.py \
  tests/test_data_sources_v120.py \
  tests/test_hypotheses_v120.py \
  tests/test_alpha_v120.py \
  tests/test_factors_v120.py \
  tests/test_risk_v120.py \
  tests/test_microstructure_v120.py \
  tests/test_end_to_end_v120.py
```

Build distributions:

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

---

# Repository structure

```text
src/asrquant/
├── api.py                  QuantLab high-level API
├── data.py                 data loading / validation
├── providers.py            ECB, Yahoo, FRED, Binance, Alpha Vantage
├── hypotheses.py           hypothesis discovery / search / audit
├── discovery.py            research-candidate discovery board
├── workflow.py             research project workflow
├── alpha.py                cross-sectional alpha research
├── factors.py              PCA / factor exposures / factor risk
├── risk.py                 portfolio risk and scenarios
├── microstructure.py       execution / liquidity analytics
├── backtest.py             auditable backtesting
├── optimization.py         portfolio construction
├── statistics.py           econometrics / inference
├── machine_learning.py     walk-forward ML
├── derivatives.py          option pricing
├── interest_rates.py       fixed income / interest-rate derivatives
├── simulation.py           stochastic processes
├── monte_carlo.py          generic Monte Carlo engine
├── volatility.py           volatility models
├── trading.py              paper trading
├── production.py           readiness gates
├── live.py                 guarded broker execution
├── audit_store.py          durable audit log
└── viz/                    visualization catalogue
```

The package keeps domain modules explicit rather than hiding quantitative logic behind a monolithic object hierarchy.

---

# Project links

- Website: https://www.asr-lab.online
- Repository: https://github.com/Alpha-Stochastic-Research/asr-quant
- Issues: https://github.com/Alpha-Stochastic-Research/asr-quant/issues

# Contributors and citation

ASRQuant 1.3.0 recognizes **Alpha Kabinet TOURE** and **Srijan Mishra** as software contributors, with **Alpha Stochastic Research** as the institutional maintainer. See `CONTRIBUTORS.md` for contribution roles.

For software citation metadata, use `CITATION.cff`. Manuscript authorship is tracked separately in `paper/`; software contribution does not automatically imply authorship of a separate paper.

# License

MIT License. See `LICENSE`.

# Disclaimer

ASRQuant is research software. It is not investment advice, a brokerage service, or a guarantee that a model, strategy, backtest or hypothesis is economically valid. Users remain responsible for data licenses, model validation, operational controls and applicable regulation.
