lacuna-quant 0.13.0

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

Stress-test your alpha before the market does.

                 

Lacuna is the validation and diagnostics layer between a quantitative research idea and confidence in its backtest. Bring a signal, a return stream, or an experiment history; Lacuna's job is to uncover weak evidence, leakage, instability, and unrealistic assumptions before capital is at risk.

[!IMPORTANT] v0.13.0 is the current release. It completes the planned factor-research sequence: explicit signal transformations and multi-lag stability in v0.10, validated decay inference, diagnostic portfolio projections, and event studies in v0.11, and semantics-first factor-panel ingestion in v0.12. Version 0.13 moves distribution to PyPI without changing the lacuna import API or analytical methods. Lacuna remains alpha software and its pre-1.0 APIs may evolve through documented migrations.

[!NOTE] Install the core project from PyPI as lacuna-quant; Python code continues to use import lacuna. The PyPI project named lacuna is unrelated and must not be installed beside lacuna-quant because both own the same import-package path.

Why Lacuna?

Backtest engines are good at answering what happened under these assumptions? Lacuna is being built to ask the harder follow-up questions:

• Is the signal informative before portfolio construction amplifies it?
• Did overlapping labels or unavailable data leak across the validation boundary?
• Does the result survive nearby parameters, different periods, and different regimes?
• Is the evidence still credible after research trials and transaction costs are counted?
• Can every conclusion be reproduced from structured, machine-readable evidence?

Lacuna is not a broker, market-data vendor, strategy generator, or full event-driven backtester. It is designed to sit on top of Polars, pandas, NumPy, Arrow, and existing research or backtesting systems.

Architecture

Your research stack
pandas · Polars · NumPy · Arrow · any backtester
                         │
                         ▼
              Typed Python API
                         │
              Arrow-compatible boundary
                         │
             ┌───────────┼───────────┐
             ▼           ▼           ▼
        Rust kernels  Polars ops  NumPy/SciPy
             └───────────┼───────────┘
                         ▼
        Structured results and findings
                         │
                    JSON · Markdown · HTML

Python owns public contracts, temporal and statistical policy, provenance, and result construction. Most current computation runs through Polars, NumPy, or optional SciPy. The compiled Rust extension is deliberately narrow: it currently accelerates grouped rank IC, bootstrap-mean reduction, and half-open interval purging, each with a tested Python reference. Arrow-compatible columnar data is the interoperability contract; additional Rust kernels require end-to-end profiling and differential evidence.

What works now

Lacuna intentionally does not generate alpha, source market data, compound a portfolio, resolve overlapping holdings, simulate orders or fills, route trades, or run live strategies. It also does not infer calendars, execution timing, data availability, or backtester semantics from convenient defaults.

Install and quick start

Install Lacuna from PyPI. The distribution is named lacuna-quant; the import package and command remain lacuna:

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

The cp311-abi3 wheels support CPython 3.11 and later on the published Linux x86-64/Linux arm64, macOS arm64, and Windows x86-64 targets. Optional dependencies are grouped as statistics, report, pandas, duckdb, and ml; see pyproject.toml for their exact bounds. The decay-fit and interactive-report calls below require SciPy, Jinja2, and Plotly from the statistics and report groups.

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

If you previously installed a GitHub Release wheel whose distribution metadata was lacuna, remove it before installing from PyPI. Installing both distributions leaves ownership of import lacuna ambiguous, and lacuna doctor reports that state as a failure.

python -m pip uninstall lacuna lacuna-options
python -m pip install --upgrade lacuna-quant lacuna-options

The same seven checksummed, provenance-attested distributions remain attached to the v0.13.0 GitHub Release.

For development, Lacuna uses uv for Python environments and Cargo for the Rust workspace:

git clone https://github.com/eyenoticeall/Lacuna.git
cd Lacuna

uv sync --group dev --group docs --extra pandas --extra statistics --extra report
uv run lacuna doctor
uv run pytest
cargo test --workspace

Inspect the runtime in machine-readable form:

uv run lacuna doctor --json --strict

The versioned diagnostic report checks package/native identity, the supported Python and wheel matrix, dependency metadata, packaged schemas, and runtime configuration. Stable check codes and nonzero strict-mode exits make it suitable for CI without reading research data or activating plugins.

Turn a cross-sectional signal and price panel into structured evidence:

import lacuna as lc

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

labels = study.labels()
split = lc.cv.PurgedKFold(n_splits=5, embargo=1).split(labels.frame)
bucketed = study.bucketize(spec=lc.BucketSpec.quantiles(count=5))
bucket_returns = study.bucket_returns(bucketed)
multi_lag = study.turnover(lags=(1, 5, 20))
decay_fit = study.fit_decay(resamples=2_000, seed=42)
projection = study.portfolio_projection(
    bucketed,
    horizon="5D",
    long_buckets=(5,),
    short_buckets=(1,),
    gross_exposure=1.0,
    net_exposure=0.0,
)

report = study.audit(
    bootstrap_resamples=10_000,
    seed=42,
    split=split,
    additional_evidence={
        "bucket_returns_explicit": bucket_returns,
        "multi_lag_stability": multi_lag,
        "decay_fit": decay_fit,
        "portfolio_projection": projection.evidence,
    },
)
report.show()
report.to_json("lacuna-audit.json")
report.to_html("lacuna-audit.html", renderer="plotly", view="signal")
report.bundle(
    "study.lacuna",
    provenance={"code_fingerprint": "git:abc123"},
)

verification = lc.verify_bundle("study.lacuna")
print(verification.archive_sha256)

Missing price-adjustment, delisting, survivorship, trial-history, or validation evidence stays visible as UNKNOWN; it is never silently promoted to a pass.

Compose evidence from every released phase with a scope-specific standardized profile:

evidence = {
    "purged_split": split.evidence,
    "trials": registry.snapshot(),
    "costs": cost_stress,
    "future_data": future_data_check,
    "vendor": adapted_vendor.evidence,
    "backtest": adapted_returns.evidence,
}

standard = lc.standard_audit(results=evidence, scope="strategy")
print(standard.table("category_coverage"))
standard.bundle("strategy-audit.lacuna", evidence=evidence)

The profile distinguishes required, optional, and not-applicable evidence, carries domain findings forward without changing their meaning, and deliberately emits no universal strategy-quality score.

The same methods are composable through the functional API:

labels = lc.labels.forward_returns(
    prices,
    horizons=("1D", "5D", "20D"),
    price_adjustment="total_return_adjusted",
)
ic = lc.signal.ic(signal, labels, method="spearman")
quantiles = lc.signal.quantiles(signal, labels, quantiles=5)
uncertainty = lc.validation.bootstrap(
    [row["ic"] for row in ic.table("ic_by_period") if row["ic"] is not None],
    method="stationary",
    expected_block_length=5,
    resamples=10_000,
    seed=42,
)

Keep model-fitting CPCV separate from selection analysis, then test a declared strategy family against one common benchmark:

paths = lc.cv.CombinatorialPurgedKFold(
    n_groups=6,
    n_test_groups=2,
    embargo=2,
).split(labels.frame)

pbo = lc.validation.probability_of_backtest_overfitting(
    synchronous_strategy_returns,
    partitions=8,
    partition_sensitivity=(4, 6, 10),
)

spa = lc.validation.superior_predictive_ability(
    performance_differentials,
    expected_block_length=20,
    resamples=10_000,
    seed=42,
)

Record every tried variant before selecting a winner, then adjust the complete family:

registry = lc.ExperimentRegistry("momentum-search", path="experiments.sqlite3")
for lookback, p_value in [(20, 0.03), (40, 0.01), (60, 0.20)]:
    registry.record(
        parameters={"lookback": lookback},
        metric=p_value,
        metric_name="p_value",
        method="strategy.evaluate",
        data_fingerprint="dataset:2026-08-26",
        code_fingerprint="git:abc123",
    )

adjusted = lc.validation.multiple_testing(registry, method="holm")

Stress normalized trades across explicit friction assumptions without hiding missing evidence:

surface = lc.costs.stress(
    trades,
    spread_bps=(0, 2, 5, 10, 20),
    slippage_bps=(0, 2, 5, 10),
    capital=10_000_000,
    annualization=252,
)

curve = lc.costs.capacity_curve(
    trades,
    capital=(1_000_000, 5_000_000, 10_000_000),
    base_capital=1_000_000,
    scenarios=(lc.costs.CapacityScenario("base", impact_coefficient=0.10),),
    classification_mode="point_in_time",
    available_time="market_available_time",
)

Keep future information and current-only universes out of historical decisions:

joined = lc.bias.asof_join(
    decisions,
    fundamentals,
    left_time="decision_time",
    right_time="available_time",
    by="instrument",
    revision="revision_id",
    revision_mode="point_in_time",
)

members = lc.bias.membership_at(
    index_membership,
    as_of=rebalance_time,
    identity=("index", "instrument"),
    source_status="confirmed_safe",
)

Anchor event studies to when information became available—not merely when the underlying event occurred:

windows = lc.events.event_windows(
    events,
    prices,
    anchor="available_time",
    before=5,
    after=10,
    overlap_policy="raise",
    price_adjustment="total_return_adjusted",
)
response = lc.events.event_response(
    windows,
    resamples=2_000,
    seed=42,
)

Cross external boundaries without hiding their semantics:

factor_schema = lc.adapters.FactorPanelSchema(
    schema_id="research.factor.v1",
    columns={
        "observation_time": "date",
        "instrument": "asset_id",
        "signal": "factor",
        "forward_return": "forward_5d",
    },
    semantics=lc.adapters.FactorPanelSemantics(
        signal_observation="market close",
        decision_time_rule="next session open",
        forward_return_entry="next session open",
        forward_return_exit="fifth session close",
        horizon_clock="trading observations",
        timezone="UTC",
        calendar="XNYS",
        adjustment_policy="total return adjusted",
        group_availability="unknown",
        imported_bucket_definition="not imported",
    ),
)
factor_panel = lc.adapters.adapt_factor_panel(raw_factor_data, factor_schema)

duckdb_frame = lc.adapters.from_duckdb(executed_relation)

cv = lc.adapters.as_sklearn_cv(
    lc.cv.PurgedKFold(n_splits=5, embargo=1),
    label_intervals,
)

candidates = lc.plugins.discover_plugins(group="audit_rules")  # metadata only
plugin = lc.plugins.activate_plugin(candidates[0], required_capability="audit.signal")

The options package is independently versioned and imported separately:

import lacuna_options as lo

chain = lo.validate_chain(option_quotes, year_basis=365.25)
bucketed = lo.delta_buckets(chain)
residuals = lo.empirical_residual(chain, expected="fair_iv")

For local Parquet, CSV, Arrow IPC, or Feather files:

uv run lacuna signal \
  --signal factor.parquet \
  --prices prices.parquet \
  --horizon 1D --horizon 5D --horizon 20D \
  --signal-observed-at open \
  --entry current_close \
  --price-adjustment total_return_adjusted \
  --bootstrap-resamples 10000 \
  --seed 42 \
  --out lacuna-audit.html \
  --html-renderer plotly \
  --bundle study.lacuna

uv run lacuna bundle verify study.lacuna

uv run lacuna audit \
  --scope strategy \
  --evidence split=purged-split.json \
  --evidence costs=cost-stress.json \
  --evidence bias=future-data.json \
  --out strategy-audit.html \
  --bundle strategy-audit.lacuna

Repository map

.
├── python/lacuna/          # public Python package
├── rust/
│   ├── lacuna-core/        # language-independent kernels
│   └── lacuna-python/      # PyO3 extension
├── extensions/
│   └── lacuna-options/     # independently versioned optional distribution
├── tests/                  # unit, property, reference, schema, golden, and integration tests
├── benches/                # Python benchmark entry points
├── schemas/                # published result compatibility schemas
├── docs/                   # engineering handbook and subsystem contracts
├── examples/               # executable examples
├── logos/                  # Lacuna brand assets
├── AGENTS.md               # repository contract for coding agents
├── pyproject.toml          # Python package and tooling
└── Cargo.toml              # Rust workspace

Roadmap and maturity

The planned 0.1–0.12 milestones are implemented, compatibility-fixtured, and released. The current 0.12 line includes the full factor-research sequence while retaining Lacuna's explicit no-backtester boundary.

Every repository-controlled item in the v1 readiness ledger has implementation evidence. 1.0.0 remains blocked by one intentionally external requirement: real users must apply Lacuna to independent research stacks. Until then, work should emphasize adoption feedback, compatibility, correctness, and measured performance rather than accumulating speculative features.

See the implementation roadmap for the phase-to-version progression and the v1 readiness ledger for the remaining gate. The full technical specification defines the architecture and statistical scope.

Engineering handbook

The technical specification is backed by implementation-oriented documentation:

• architecture and dependency boundaries;
• semantic time, identity, and table contracts;
• structured evidence and finding contracts;
• developer workflow, testing, native, performance, and release guides;
• subsystem contracts with formulas, invariants, failure modes, and tests;
• factor-research migration from Alphalens Reloaded;
• coding-agent playbooks and review checklist.

The documentation distinguishes released v0.1–v0.12 behavior from later contracts. Contributors and coding agents should begin with AGENTS.md, then read the relevant methodology and subsystem pages before changing a method.

Principles

• Time is part of the type system. Event, availability, effective, revision, and label times are not interchangeable.
• Unknown is not pass. Missing evidence stays visible.
• Results before reports. Every visualization is backed by structured, inspectable data.
• Robustness means neighborhoods, not points. Isolated optima are warnings, not trophies.
• Performance claims require benchmarks. Native code is earned through measurement.
• Interoperate instead of replacing. Lacuna complements existing research stacks.

Development

# Format and lint
uv run ruff format --check .
uv run ruff check .
cargo fmt --all --check
cargo clippy --workspace --all-targets -- -D warnings

# Type-check and test
uv run mypy
uv run pytest
cargo test --workspace

# Build a local wheel
uv run maturin build --release

# Run reproducible benchmarks
uv run lacuna bench --tier smoke
cargo bench --bench kernels

Pull requests pass through formatting, lint, strict typing, Python 3.11–3.14 on Linux, Python 3.13 on macOS and Windows, Rust, optional dataframe/reference integrations, strict documentation, and a minimum-Rust check, plus a clean source-distribution-to-wheel smoke test. See the CI architecture for the job graph and branch-protection contract.

Version-matching tags additionally build target-smoke-tested stable-ABI wheels for Linux x86_64, Linux aarch64, macOS arm64, and Windows x86_64, then publish checksums and GitHub provenance. See the release engineering contract.

Contribution guidance lives in CONTRIBUTING.md. The complete local documentation site can be built with uv run mkdocs serve. Security concerns should follow SECURITY.md.

License

The current repository and future distributions are released under the MIT License. Artifacts published before the MIT-only change retain the grants under which they were released; see the changelog.

Bring a signal or backtest. Lacuna will try to find the gaps in the evidence.