equiframe 0.12.4__py3-none-any.whl

equiframe/docs/performance.md

@@ -0,0 +1,263 @@
+# Performance and safe resource budgets
+
+[Handbook](index.md) · [Semantics](semantics.md) · [Compatibility](compatibility.md)
+
+EquiFrame favors declared semantics and reviewable evidence over an unconditional
+speed claim. Native assertions may be the smaller service when you only need a
+verdict. There is no universal row limit, latency guarantee, process-RSS quota,
+larger-than-RAM promise or demonstrated advantage over every comparison tool.
+
+## Understand the work you request
+
+`diff` first captures native inputs, then compares. `compare` can read local
+captured Arrow IPC/Parquet in batches and uses private SQLite working files for
+exact grouping/alignment. It still validates schema, keys, values, multiplicity
+and all requested evidence. A displayed sample limit does not skip the remaining
+data. Wide strings, many differences and approximate matching can cost more than
+an equal narrow table with the same row count.
+
+Common default budgets, as declared by the installed models:
+
+| Options | Defaults and scope |
+|---|---|
+| `DiffCaptureOptions` | 1,000,000 rows and 256 MiB per eager input |
+| `ComparisonOptions.batch_rows` | 4,096 rows per comparison batch |
+| `max_batch_bytes`, `max_row_bytes` | 64 MiB per batch; 1 MiB per row |
+| `max_rows`, `max_work` | 10,000,000 rows; 100,000,000 accounted work units |
+| `max_disk_bytes`, `max_evidence_bytes` | 4 GiB comparison working budget; 512 MiB difference evidence |
+| `max_matching_rows`, `max_matching_bytes`, `max_pair_checks` | 2,000 matching rows; 32 MiB; 2,000,000 candidate pair checks |
+| `partitions`, `sqlite_cache_kib` | 16 partitions; 4,096 KiB SQLite cache setting |
+| `max_examples` | 20 summary examples; does not limit evaluation |
+| `timeout_seconds` | None by default; explicit timeouts are cooperative |
+| `DuckDBCaptureOptions` | 4,096-row batches; 1,000,000 rows; 64 MiB batch and 256 MiB file budgets |
+
+These are operational checks, not an admission guarantee for every case below
+the numbers. Capture/conversion can allocate before a check. File sizes, Arrow
+buffers, engine-managed memory, working disk and process RSS are distinct.
+`duckdb_memory_mb` constrains engine-managed memory, not all Python/Arrow/native
+allocations. Core callback and Polars collection cancellation are cooperative;
+a callback that does not check can run until it returns. DuckDB query interruption
+does not impose a hard deadline on all Python capture/publication work.
+
+Choose a private output directory on a suitable disk-backed filesystem, leave
+space for inputs, temporary files, snapshots and full differences, and avoid
+concurrent benchmark workloads. For large inputs prefer captured files and an
+explicit contract over eager conversion. Set work/time/evidence budgets based on
+a small representative run. Preserve insufficient-budget results instead of
+silently loosening exactness or dropping duplicates.
+
+## Reproducible engineering measurements
+
+The separate `equiframe-benchmark` package offers experimental `ScaleSpec`,
+`ScaleTrial`, `ScaleRun`, `measure_scale`, `read_scale` and `summarize_scale`.
+Install its identified matching wheel with the required dependency profile before
+running this complete small example outside the checkout:
+
+```python
+from pathlib import Path
+import equiframe as ef
+import equiframe_benchmark as eb
+
+spec = eb.ScaleSpec(
+    case_id="keyed-last-batch-1k",
+    rows=1_000,
+    width=4,
+    alignment="keyed",
+    null_every=11,
+    difference_last=True,
+    repetitions=3,
+    comparison_options=ef.ComparisonOptions(batch_rows=256),
+    concurrent_loads="Record actual known concurrent work; host load is uncontrolled",
+)
+result = eb.measure_scale(spec, work_dir=Path("scale-runs"))
+verified = eb.read_scale(Path("scale-runs") / result.run_id)
+summary = eb.summarize_scale(verified)
+print(summary)
+if not verified.complete:
+    raise SystemExit(3)
+```
+
+For meaningful CPU/RSS monitoring install the benchmark's `resources` extra;
+missing or failed monitoring remains explicit. The optional `engines` extra
+permits applicable native baselines. This script measures a deliberately
+**different** case: completion means the expected verdict occurred, not that the
+two tables should pass an equivalence assertion.
+
+The generator uses deterministic synthetic integer/text/NULL data with exact keys
+or multisets. Width, string length, cardinality, skew, duplicate multiplicity,
+NULLs, difference density and final-row differences are controlled explicitly.
+It does not establish performance for Decimal, timestamps, approximate matching,
+unknown SQL, remote services, data warehouses or larger-than-RAM datasets.
+
+One isolated trusted worker runs 2–10 repetitions sequentially, default 3. The
+first uses a fresh Python worker; subsequent trials reuse it. OS caches are
+uncontrolled. Raw labels distinguish `fresh_process_os_cache_uncontrolled` and
+`warm_process_os_cache_uncontrolled`; summaries retain n/median/min/max, failures
+and missing observations. One fresh observation is not a variability estimate.
+
+The recorded stages are capture, snapshot hashing/counting, local transfer,
+contract planning, public comparison, additional standalone serialization,
+persistence, rendering and verification. Public `compare` includes its own
+capture/snapshot/planning/evidence work; the additional serialization/persistence
+stages do not isolate its internals. End-to-end trial time brackets these stages.
+Supervisor elapsed time additionally includes startup, repetitions, baselines,
+monitoring and reaping. Parent final inventory verification/publication is outside
+that measured interval. Do not subtract unlike scopes to invent a component cost.
+
+## What the resource figures mean
+
+- RSS is an absolute sampled **lower bound on peak**, not an allocation delta or
+  hard maximum. Sample gaps and monitoring failures remain visible
+- Worker CPU/I/O counters are last available observations; physical storage bytes
+  and logical syscall bytes are different. Missing final totals stay unknown
+- Disk apparent/allocated peaks are sampled within the owned worker tree and
+  temporary directory. Hard links count once; deleted-between-sample or
+  open-unlinked files may be missed
+- Engine allocator peak is not supplied by this protocol. Supervisor resources
+  and unrelated host work are not included in worker RSS
+- Observed RSS/disk thresholds reactively terminate work and may overshoot; they
+  are not cgroups, containers or a sandbox
+- A watchdog can terminate the trusted worker's private process group on POSIX
+  or direct child elsewhere. Scheduling delays and unsupported escaping children
+  prevent a universal hard-time/containment claim
+- `complete` describes operation/verdict completion;
+  `resource_measurement_complete` separately states observation quality
+
+Native pandas assertions and DuckDB bidirectional `EXCEPT ALL` baselines are
+restricted to the generator's exact integer/text/NULL policies and original
+Arrow-schema check. They provide less evidence: no complete EquiFrame difference
+files, snapshots, reports and integrity inspection. Ratios are service-cost
+comparisons, not proof one equivalent service is faster. DataComPy is not pinned
+in this candidate and no measurement is invented for it.
+
+## Historical baseline, not a new-artifact speed claim
+
+The STEP8 identified Linux x86_64/CPython 3.12.14 artifacts recorded nine synthetic
+cases with three sequential trials each. The narrow 1M-row/two-column last-batch
+case had an all-trial median end-to-end pipeline time of **207.985 seconds**,
+range **206.989–211.278 seconds** and sampled worker peak RSS about **396.8 MiB**.
+The corresponding restricted DuckDB verdict baseline was about **0.493 seconds**
+median, providing substantially less evidence. There is no raw verdict-speed
+advantage for EquiFrame in that example.
+
+Those results belong to core wheel SHA-256
+`61030f6755d943954920ef989939fae845bb8b77c69886a347b4fc00e05de1be`
+and benchmark wheel SHA-256
+`e7a227e13c0ea2db926d24e5e6625025bdf4a052e7eac8a0406cb48d6a5a3d96`.
+They are **not measurements of a later rebuilt STEP9 wheel**. All nine runs
+retained `resource_measurement_complete=False` due to incomplete final I/O
+monitoring; some RSS sampling was partial. Host load and OS caches were not
+controlled. These numbers are orientation with explicit limits, not a sizing SLA.
+
+The measured narrow 1M recipe used a 1 GiB sampled RSS threshold, 2 GiB sampled
+disk threshold, 1 billion comparison work units, 540 seconds per-comparison
+cooperative timeout and 1,800 seconds supervised allowance for three trials.
+Admission additionally reserves at least disk budget + 256 MiB free space. These
+are fixture-specific budgets, not recommendations for every 1M-row workload.
+The default 100 million work units was insufficient for that fixture.
+
+## Failure, finalization and cleanup
+
+`equiframe-benchmark scale spec.json --output scale-runs` and
+`verify-scale scale-runs/scale-ID` return 3 for incomplete/failed measurement or
+invalid finalization. Exit zero by itself is insufficient. The worker's completion
+receipt, finalized aggregate and `finished.json` inventory binding must all
+validate. A native kill, incorrect verdict, corrupted inventory or incomplete
+comparison is not successful measurement.
+
+After reaping the worker, only known disposable SQLite files in owned comparison
+directories are removed; partial captures, diagnostics and logs remain. A reader
+does not execute workloads or delete evidence. Receipts retain original local
+paths and are not portable bundles; reproduce from the specification and exact
+artifacts. If the parent dies before publication, `read_scale` fails closed.
+
+Tests use bounded subprocesses, genuine SIGKILL and injected ENOSPC rather than
+filling a host disk or causing host OOM. No destructive whole-host stress result
+is claimed. The consumer must treat missing finalization, abnormal exit and
+insufficient evidence as failure or unavailable evaluation, never equivalence.
+
+## Bounded consolidation suite
+
+`tools/measure_bounded.py` adds a repeatable developer suite. It reuses
+`ScaleSpec`, `measure_scale`, `read_scale`, `summarize_scale` and their existing
+isolated-worker supervisor for final-row differences, dense differences,
+duplicate multiplicity, wide strings and ordinary disk/evidence costs. A separate
+small Decimal supplement measures exact cents through Arrow and pandas, including
+an explicitly timed Arrow-to-pandas conversion. It does not change historical
+scale schemas or introduce a core dependency on the benchmark.
+
+Use a benchmark environment containing the **matching installed** core and
+benchmark builds, including pandas, Arrow and the benchmark `resources` extra.
+From the checkout, after the identified artifacts have been installed:
+
+```bash
+packages/equiframe-benchmark/.venv/bin/python -I \
+  tools/measure_bounded.py \
+  --output /new/private/bounded-costs --rows 512 --repetitions 3
+```
+
+The scale supervisor deliberately ignores `PYTHONPATH`; pointing the parent at
+changed source while its isolated worker has an older installed wheel fails the
+producer-identity check. Install the matching artifacts instead of weakening the
+check. `suite.json` retains imported-source fingerprints, tool hash, versions,
+individual stage boundaries, raw supervision records and explicit completion.
+An older version string alone is not a matching artifact. Failed attempts remain
+separate; each run requires a new output directory.
+
+Defaults run sequentially at 512 rows/side (1,024 for the disk/evidence fixture),
+three repetitions, 128-row batches, a 512 MiB sampled RSS threshold, 64 MiB sampled
+disk threshold and 120 seconds per supervised case. Comparison budgets are 32 MiB
+disk, 8 MiB differences and 30 cooperative seconds. The suite admits only
+8–2,048 rows and 2–5 repetitions and requires at least 384 MiB initially free.
+These are conservative test boundaries, not hard quotas or workload sizing advice.
+The disk fixture writes complete snapshots and dense differences without trying
+to fill the host disk. The small tests simulate interruption and ENOSPC; they do
+not exhaust memory or storage.
+
+The Decimal supplement has its own developer-receipt format rather than claiming
+the historical `ScaleSpec` supports Decimal. It retains the independently expected
+one-cent final-record difference, all comparison records and a redacted report.
+`diff` includes its own conversion/capture, inference, complete comparison and
+publication. Additional conversion, capture, hashing, serialization and durable
+write timings describe additional work; they are not disjoint pieces extracted
+from the internal `diff` timing. A completed comparison followed by failed receipt
+publication is an incomplete measurement. Pre-contract cancellation can raise
+`ExecutionCancelled` before a final comparison exists.
+
+### Measured reference at the consolidation base
+
+On 2026-10-06, the installed core and benchmark Python sources were independently
+matched to commit `c4be1c5a29d9f58b2628882bd986de2bb5ca4184`. This **base reference**,
+not a final rebuilt-consolidation measurement, ran all six families with three
+repetitions and complete expected outcomes. Linux x86_64, CPython 3.12.14,
+PyArrow 25.0.1, pandas 3.0.6 and psutil 7.2.2; shared cloud host, uncontrolled OS
+caches and concurrent development work. Each case has one fresh worker trial and
+two warm-worker trials; medians below combine those three explicitly identified
+observations and do not imply cold-cache repeatability.
+
+| Case | Rows/side | Pipeline median (range), seconds | Sampled worker RSS, MiB | Sampled apparent disk, MiB |
+|---|---:|---:|---:|---:|
+| Final-row difference | 512 | 0.221 (0.207–0.485) | 147.8 | 1.74 |
+| Every-row difference | 512 | 0.243 (0.228–0.497) | 148.8 | 2.47 |
+| Eight distinct rows, duplicates | 512 | 0.131 (0.130–0.365) | 148.0 | 1.21 |
+| Eight columns, wider strings | 512 | 0.275 (0.271–0.530) | 158.8 | 15.90 |
+| Dense differences plus disk evidence | 1,024 | 0.755 (0.650–0.967) | 160.0 | 24.98 |
+| Exact Decimal final cent | 512 | 0.184 (0.181–0.186) | 149.2 | 1.31 |
+
+The public comparison stage dominates these small cases. For example, the
+Decimal median stages were 0.00051 s construction, 0.00087 s additional conversion,
+0.00027 s additional IPC capture, 0.00007 s hashing, 0.17618 s full `diff`,
+0.00007 s extra serialization, 0.00005 s extra durable write, 0.00314 s report and
+0.00146 s readback. Very short stages are below useful stable sizing resolution.
+No algorithm was optimized from these observations and no percentage improvement
+or comparison against a lower-guarantee service is claimed.
+
+All six resource receipts remain incomplete because the final I/O sampling
+reported `AccessDenied`. Missing final I/O totals are unknown, not zero. RSS and
+disk columns remain observed lower bounds over the supervised worker and retained
+evidence tree; disk is for the case's three repetitions, not one input file.
+Raw receipts also retain allocated-disk observations and sampling gaps. No new
+macOS/Windows/ARM64, large-volume, storage-saturation or human usability result is
+implied. Preserve the supplied private raw receipts when using this reference;
+source/tool fingerprints and actual environment take precedence over these
+rounded display values.

equiframe/docs/piloto-simulado.md

@@ -0,0 +1,56 @@
+# Tres perfiles ficticios para ensayar el protocolo
+
+[Protocolo de adopción](adoption.md) · [Arquitecto](arquitecto.md) · [Científico](cientifico.md)
+
+**SIMULADO.** Hernán autorizó preparar perfiles ficticios. No representan personas,
+empresas o proyectos reales; no tienen consentimiento otorgado ni observaciones
+humanas. No se introducen en el registro de pilotos como `human_pilot` y no suman
+al índice U12. No se fabrican firmas, independencia, tiempos o satisfacción.
+
+## Perfil ficticio A: arquitectura e integración SQL
+
+- Rol ficticio: arquitecta de datos que integra una comprobación en un orquestador existente
+- Proyecto simulado: comparar una consulta DuckDB de inventario sintético con un
+  esperado literal por SKU, conservando clave compuesta y unidades
+- Ruta: guía del arquitecto, captura propia SQL, reporte y aserción; ampliar con
+  el recorrido G para fijación de snapshot local
+- Decisiones a ensayar: elegir `[duckdb]`, distinguir snapshot fijado de servicio
+  real, localizar B=21 frente a B=20 y detener el siguiente paso
+- Escenario de seguimiento propuesto: una consulta posterior añade un filtro;
+  el control debe permanecer. No se afirma que ese cambio haya ocurrido
+
+## Perfil ficticio B: ciencia de datos y preparación
+
+- Rol ficticio: científico de datos que conserva identidad y tiempo al preparar features
+- Proyecto simulado: dataset sintético de tres muestras con IDs, Decimal y NULL
+- Ruta: guía del científico; primero `good`, luego desplazamiento temporal,
+  pérdida de fila y ausencia reemplazada por cero
+- Decisiones a ensayar: interpretar la diferencia y la consecuencia en ventanas,
+  cobertura y joins; mantener el esperado independiente y las ausencias
+- Escenario de seguimiento propuesto: una revisión vectoriza la preparación sin
+  cambiar semántica. No hay modelo entrenado ni utilidad científica observada
+
+## Perfil ficticio C: mantenimiento de una regresión CI
+
+- Rol ficticio: ingeniera que mantiene pruebas de regresión Python de un proyecto
+- Proyecto simulado: comprobar totales sintéticos después de un refactor,
+  conservar el reporte aunque falle pytest y mantener el retorno no cero
+- Ruta: test local de la guía del arquitecto y recorrido A/H
+- Decisiones a ensayar: distinguir cero del arnés que espera fallos del gate que
+  acepta datos; usar carpeta nueva y separar una salida completa de equivalencia
+- Escenario de seguimiento propuesto: otro commit cambia el cálculo; el test y
+  diagnóstico siguen disponibles. No se ejecuta ni acredita CI remota
+
+## Hoja vacía de ensayo, sin resultados humanos
+
+Antes de ensayar, anotar guía/artefactos, propósito y escenario. Si se ejecutan
+comandos, registrarlos como reproducción técnica sintética con sus resultados
+reales. El tiempo automático solo mide comandos; no mide comprensión humana.
+No llenar el consentimiento ni la independencia con valores ficticios positivos.
+
+Para pasar de estos perfiles a U12 se requieren personas y proyectos reales,
+consentimiento con alcance/lectores/retención, revisión humana de independencia,
+interpretación y ayuda observadas, tres diagnósticos iniciales <=300 s con reloj
+predeclarado e integración retenida tras un cambio real posterior. Todo ello
+permanece pendiente. El permiso de ensayar perfiles no es permiso de contactar
+personas, compartir datos o publicar resultados.

equiframe/docs/quickstart.md

@@ -0,0 +1,156 @@
+# Quick start
+
+[Handbook](index.md) · [Recipes](recipes.md) · [Semantics](semantics.md)
+
+This guide targets **0.12.4** artifacts and uses synthetic local data. Its
+commands require identified artifacts after the [release gates](releasing.md)
+pass. Check the official index for availability and verify the artifact hashes.
+It works outside a source checkout. The supported range is Python 3.10–3.13;
+use the exact interpreter/platform dependency closure reviewed for your artifact.
+The first-use builder produces a separate hash lock for the selected minor.
+Metadata admission is not a claim of support for every platform. See
+[compatibility](compatibility.md).
+
+## 1. Install the artifact you were given
+
+The commands below demonstrate the optional [offline wheelhouse](installed-private.md)
+route, with normal pip resolution and a separate hash-locked trial. For registry
+installation, use the README after the corresponding [release gates](releasing.md)
+have verified ownership and publication. For an offline delivery, obtain:
+
+- `equiframe-0.12.4-py3-none-any.whl`
+- A receipt identifying its commit and expected SHA-256, received through a
+  channel you trust independently of the artifact
+- A wheelhouse containing the reviewed runtime dependency wheels for your
+  Python/platform and chosen extra, with their pins, hashes and inventory
+
+A hash checks bytes against a trusted reference; a manifest packaged with the
+same untrusted archive cannot authenticate its sender. Check the supplied wheel
+against the separate receipt before installing. For example, from its directory:
+
+```bash
+python3.12 -c "from pathlib import Path; import hashlib; p=Path('equiframe-0.12.4-py3-none-any.whl'); print(hashlib.sha256(p.read_bytes()).hexdigest())"
+```
+
+Compare the printed value with the receipt. Stop on a mismatch. Do not copy the
+observed hash back into the expected receipt to make it pass.
+
+Create a fresh directory **outside the repository**, then create an environment.
+The following commands use a POSIX shell. Set both paths to your verified local
+locations; `/absolute/path/...` is a placeholder, not a download URL:
+
+```bash
+mkdir equiframe-consumer
+cd equiframe-consumer
+python3.12 -m venv .venv
+. .venv/bin/activate
+WHEEL=/absolute/path/equiframe-0.12.4-py3-none-any.whl
+WHEELHOUSE=/absolute/path/reviewed-wheelhouse
+python -m pip install --no-index --find-links "$WHEELHOUSE" "${WHEEL}[arrow]"
+python -m pip check
+python -I -c "import equiframe, sys; print(sys.version); print(equiframe.__version__); print(equiframe.__file__)"
+```
+
+The import must point into this environment's installed package, not the checkout.
+This command cannot fetch missing dependencies from an index. A missing compatible
+wheel is a blocker to resolve with the artifact provider, not a reason to remove
+integrity checks or install an unrelated `equiframe` from PyPI. For exact hashed
+dependency installation, follow the kit's `--require-hashes` recipe. Do not use an
+editable install or add the checkout to `PYTHONPATH` as an installation test.
+
+On Windows, `py -3.12 -m venv .venv` creates the environment and
+`.venv\Scripts\python.exe` can be used directly instead of activation. Do not
+change security policy to activate it. These command conventions do not establish
+that this candidate was verified on Windows. Each Python minor needs its matching
+reviewed dependency set; do not reuse a 3.12 kit lock as a claim of compatibility
+with 3.10, 3.11 or 3.13.
+
+## 2. Compare two complete outputs
+
+Save this complete script as `quickstart.py` in the new consumer directory:
+
+```python
+from pathlib import Path
+
+import equiframe as ef
+import pyarrow as pa
+
+expected = pa.table({"id": ["A", "B"], "quantity": [10, 20]})
+candidate = pa.table({"id": ["B", "A"], "quantity": [21, 10]})
+private_root = Path("private-evidence")
+result = ef.diff(candidate, expected, keys=["id"], work_dir=private_root)
+assert result.state == "different" and result.complete
+assert result.counts.final
+
+# Default report hides values, names and paths. It does not delete the originals.
+report = ef.write_comparison_report(result, Path("comparison-report"))
+print(report.to_text())
+print(ef.read_diff_contract(result).reference)
+
+try:
+    ef.assert_equivalent(result)
+except ef.EquivalenceDifferentError:
+    print("The regression was correctly rejected")
+else:
+    raise AssertionError("A different result must not pass")
+
+fixed = ef.diff(expected, expected, keys=["id"], work_dir=private_root)
+ef.assert_equivalent(fixed)
+print(fixed.state, fixed.complete)
+```
+
+Run it once in that clean directory:
+
+```bash
+python -I quickstart.py
+```
+
+The first comparison is `different`; the corrected one prints `equivalent True`.
+The key aligns `B` with `B` even though row order differs. Its quantity is 21
+instead of 20. The script catches the deliberate failure only to demonstrate the
+API; real tests should let `assert_equivalent` fail.
+
+`comparison-report/` contains `report.json`, `report.txt`, `report.html` and a
+publication inventory. Use a new report directory on repetition. `private-evidence/`
+contains original snapshots and differences and can reveal your data. Do not
+upload it automatically. With these known synthetic values only, explicit
+`ReportOptions(include_values=True, include_metadata=True)` makes the diagnosis
+visible. Review disclosure permission before using those options with real data.
+
+## 3. Read states before acting
+
+| Comparison state | Meaning | Equivalence gate |
+|---|---|---|
+| `equivalent` | Complete evaluation, no differences under the declared contract | Accepted only if the required guarantee/evidence also passes |
+| `different` | Complete evaluation found a difference or contract violation | Fails |
+| `not_evaluable` | Required judgment cannot be established | Fails, even if `complete=True` |
+
+Use `ef.assert_equivalent(result)` or inspect
+`ef.equivalence_decision(result).accepted`. `if result`, `bool(result)` and
+`assert result` raise `TypeError` in every state. A returned object, zero displayed
+examples, a successful HTML export or an integrity reader's exit zero is not an
+equivalence decision.
+
+`diff` infers a conservative contract from the right-hand schema, never from a
+search for policies that make the pair agree. Inferred units are `unspecified`,
+numbers are exact, only NULL is a missing-value representation, and nullable is
+a visible default rather than inferred from observed rows. Use reviewed explicit
+`ColumnSpec` definitions for domain units, allowed values and nullability.
+
+## 4. Choose only the dependencies you need
+
+| Extra | Purpose |
+|---|---|
+| None | Contract models/validation, serialization, CLI and local artifact support |
+| `arrow` | Tabular comparison and Arrow capture/readers |
+| `pandas`, `polars`, `duckdb` | The named native engine plus PyArrow |
+| `engines` | All three native engines plus PyArrow |
+| `ml` | Fit Isolation Forest with scikit-learn and NumPy |
+
+Change `[arrow]` in the local wheel command to the extra you need. Use
+`[engines,ml]` when you need both. Extra names do not supply missing binaries in an
+offline wheelhouse. `import equiframe` itself does not import the optional engines,
+Arrow, NumPy or scikit-learn. Missing optional dependencies fail explicitly.
+
+Continue with [the three reproducible recipes](recipes.md),
+[API reference](api.md), and [upgrade/failure guidance](upgrading.md).