README.md

Stress-test your alpha before the market does.

Open-source quantitative research validation for finding where alpha breaks.

                 

Quick start · Capabilities · Documentation · v0.14.0

Lacuna is the evidence layer between quantitative research and confidence in a backtest. Give it signals, returns, trades, events, or experiment history; it looks for leakage, instability, overfitting, unrealistic costs, and missing point-in-time evidence.

It complements your research stack instead of replacing it. Results are returned as structured, versioned evidence that can be inspected, audited, rendered, and archived.

Quick start

Install the core distribution and verify the runtime:

python -m pip install --upgrade lacuna-quant
lacuna doctor --strict

Given explicit signal and price frames, a complete study is deliberately small:

import lacuna as lc

study = lc.SignalStudy(
    signal=signal,
    prices=prices,
    horizons=("1D", "5D", "20D"),
    signal_observed_at="open",
    entry="current_close",
    price_adjustment="total_return_adjusted",
)

report = study.audit(bootstrap_resamples=2_000, seed=42)

print(report.summary())
report.to_html("lacuna-audit.html")
report.bundle("study.lacuna")

Lacuna preserves weak or missing evidence as UNKNOWN; it never silently turns uncertainty into a pass. See the copy-pasteable guided signal audit for runnable data, output inspection, CLI usage, and bundle verification.

Optional method families stay explicit:

python -m pip install "lacuna-quant[statistics,report,pandas]"
python -m pip install lacuna-options

Stable-ABI wheels support CPython 3.11+ on Linux x86-64/arm64, macOS arm64, and Windows x86-64.

What Lacuna validates

Additional support includes availability-anchored event studies, generic factor-panel ingestion, DuckDB and scikit-learn adapters, Arrow-compatible and optional pandas boundaries, and an independently versioned options-research extension.

Evidence first

signals · returns · trades · events · trials
                      │
                      ▼
            explicit Python policy
                      │
          Polars · NumPy/SciPy · Rust
                      │
                      ▼
               AnalysisResult
                      │
          audit · report · JSON · bundle

Python owns methodology, temporal semantics, validation, provenance, findings, and public result construction. Renderers only present stored evidence; they do not recalculate statistics.

Findings keep state separate from severity:

• PASS: the supplied evidence satisfies the declared rule;
• WARN / FAIL: weakness or a violated contract is visible;
• UNKNOWN: the source cannot establish the claim;
• NOT_APPLICABLE: the methodology does not apply.

Performance without a Rust quota

Most work belongs in optimized Polars or NumPy. Rust ships only when full-call benchmarks beat an already optimized reference without changing public semantics.

In v0.14, grouped rank IC and built-in PBO/CSCV cleared that admission gate. Other candidates either improved without Rust or closed with a documented negative decision. Native execution remains single-threaded, reference implementations remain directly testable, and cp311-abi3 portability is a release requirement.

See the native decision ledger for workloads, measurements, correctness evidence, and rejected migrations.

Documentation

The technical specification defines the full product boundary. The roadmap and v1 readiness ledger separate completed work from the remaining independent-user evidence requirement.

git clone https://github.com/eyenoticeall/Lacuna.git
cd Lacuna
uv sync --group dev --group docs --extra all

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest

cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
uv run mkdocs build --strict

License

Lacuna is released under the MIT License. Artifacts published before the MIT-only change retain their original grants.

Bring the research. Lacuna will look for the gaps in the evidence.