# sb-ai-lab/hypex architecture

> Architecture diagram of the GitHub repository sb-ai-lab/hypex, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sb-ai-lab/hypex
- Repository: https://github.com/sb-ai-lab/hypex

## Overview

1. **What this repo is**
   HypEx is a Python analytics library, not an application service. Its architecture is centered on experiment analysis pipelines for:
   - A/B and A/A testing
   - causal inference / matching
   - homogeneity checks
   - variance reduction methods like CUPED/CUPAC

2. **Public entry points**
   The top-level user API is intentionally small and lives in `hypex/`:
   - `hypex.ab`, `hypex.aa`, `hypex.matching`, `hypex.homogeneity`
   - these expose the main experiment objects used in the README examples: `ABTest`, `AATest`, `Matching`
   These are the facade layer that hides the internal pipeline.

3. **Core domain model: roles + dataset**
   The `hypex.dataset` package is the data boundary. It wraps tabular input and assigns semantic roles to columns:
   - ID / info
   - treatment
   - target
   - stratification
   - default feature roles
   It also has a backend abstraction with a concrete Pandas implementation, so the rest of the library can treat input as a typed dataset rather than raw DataFrames.

4. **Preprocessing and feature shaping**
   `hypex.transformers` and `hypex.preprocessing` are the data preparation layer. They handle tasks such as:
   - type casting
   - NA filling
   - filtering / outlier handling
   - shuffling
   - category aggregation
   - CUPED transformation
   These run before analysis so downstream comparators and estimators receive cleaned, role-aware columns.

5. **Experiment orchestration layer**
   `hypex.experiments` and `hypex.executor` appear to coordinate the workflow:
   - select the analysis path
   - apply calculators
   - produce structured outputs
   `executor/calculators.py` suggests a computation stage separate from orchestration, which is useful for running different statistical routines through a shared execution pipeline.

6. **Analysis engines**
   The `hypex.analyzers` package holds the main analytical logic for different experiment types:
   - `aa.py` for A/A validation
   - `ab.py` for A/B testing
   - `matching.py` for matching-based causal inference
   These analyzers likely consume prepared datasets and produce test statistics, effect estimates, and validation metrics.

7. **Matching subsystem**
   Matching is a distinct subsystem rather than just one test mode. It spans:
   - `hypex.matching`
   - `hypex.splitters`
   - `hypex.encoders`
   - `hypex.comparators`
   - `hypex.ml` and `hypex.extensions.faiss`
   This suggests a pipeline that encodes features, computes distances/similarities, and pairs treated/control units efficiently, with Faiss as the accelerated nearest-neighbor backend.

8. **Statistical comparison layer**
   `hypex.comparators` contains reusable statistical primitives:
   - distance metrics
   - hypothesis testing
   - power testing
   - abstract comparator interfaces
   These are shared across AB, AA, and matching workflows, which keeps the statistical logic separate from experiment-specific orchestration.

9. **Results and reporting**
   `hypex.reporters` and `hypex.ui` are the presentation layer.
   - Reporters format result objects for AA, AB, matching, and homogeneity workflows.
   - UI modules likely provide a user-facing wrapper around those reports.
   This is the boundary where raw statistical outputs become readable summaries such as `resume`, variance reduction reports, or match summaries.

10. **Extensions and optional dependencies**
   `hypex.extensions` isolates integrations with external libraries:
   - Faiss for nearest-neighbor search
   - SciPy stats/linalg
   - Statsmodels
   - encoder integrations
   - CUPAC support
   This is an important architectural boundary: the core API depends on these capabilities, but the implementation is modular so optional scientific packages are isolated.

11. **Supporting abstractions**
   Several packages provide the internal framework:
   - `operators`, `factory`, `forks`, `utils`
   - abstract base classes throughout the package
   - hypothesis schemes in `hypex/hypotheses/schemes/scheme.json`
   This indicates a plugin-like or strategy-based architecture, where test variants and computational steps are assembled from reusable components.

12. **Repository shape around the library**
   The rest of the repo supports the library itself:
   - `examples/` contains notebooks and a performance test harness
   - `docs/` is a full Sphinx documentation site
   - `tests/` and `unitests/` validate examples and tutorial behavior
   - CI and packaging are set up via GitHub Actions, `pyproject.toml`, and `tox.ini`
   So the repo is organized as a distributable Python package with documentation, reproducible examples, and regression tests.

13. **Overall data flow**
   The typical pipeline is:
   raw tabular data -> role assignment via `Dataset` -> preprocessing/transformers -> analyzer/executor/comparator logic -> reporter/UI output.
   Matching adds a feature-encoding + distance/search path in the middle, and AB testing can optionally branch through CUPED/CUPAC variance reduction before statistical comparison.

14. **Main architectural boundary to draw**
   For a diagram, the key split is between:
   - **public experiment facades** (`ABTest`, `AATest`, `Matching`, `Homogeneity`)
   - **internal execution engine** (dataset, transformers, analyzers, comparators, executor, reporters)
   - **optional acceleration/statistics backends** (`extensions`, `ml`, Faiss/SciPy/Statsmodels)
   That separation is the defining structure of the repository.

Main entry points: [`hypex/experiments`](https://github.com/sb-ai-lab/hypex/tree/master/hypex/experiments) (Experiments), [`hypex/analyzers`](https://github.com/sb-ai-lab/hypex/tree/master/hypex/analyzers) (Analyzers), [`hypex/matching.py`](https://github.com/sb-ai-lab/hypex/blob/master/hypex/matching.py) (Matching Flow), [`hypex/dataset`](https://github.com/sb-ai-lab/hypex/tree/master/hypex/dataset) (Dataset)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_public_api["Public API"]
  node_hypex_ab["AB Test<br/>facade<br/>[ab.py]"]
  node_hypex_aa["AA Test<br/>facade<br/>[aa.py]"]
  node_hypex_matching["Matching<br/>facade<br/>[matching.py]"]
  node_hypex_homogeneity["Homogeneity<br/>facade<br/>[homogeneity.py]"]
end

subgraph group_core_engine["Core Engine"]
  node_dataset[("Dataset<br/>role-aware data boundary")]
  node_transformers["Transformers<br/>preprocessing pipeline"]
  node_preprocessing["Preprocess<br/>prep facade<br/>[preprocessing.py]"]
  node_experiments["Experiments<br/>orchestration"]
  node_executor["Executor<br/>compute pipeline"]
  node_analyzers["Analyzers<br/>statistical engines"]
  node_comparators["Comparators<br/>statistical primitives"]
  node_reporters["Reporters<br/>result formatting"]
  node_ui["UI<br/>presentation layer"]
end

subgraph group_matching_stack["Matching Stack"]
  node_matching_path{{"Matching Flow<br/>matching pipeline<br/>[matching.py]"}}
  node_splitters["Splitters<br/>pairing helpers"]
  node_encoders["Encoders"]
  node_ml_faiss["Faiss ML<br/>accelerated search backend<br/>[faiss.py]"]
end

subgraph group_supporting["Supporting Code"]
  node_extensions["Extensions<br/>optional backends"]
  node_operators["Operators<br/>shared abstractions"]
  node_factory["Factory<br/>assembly layer"]
  node_forks["Forks<br/>variant adapters"]
  node_hypotheses["Hypotheses<br/>scheme registry"]
  node_utils["Utils<br/>shared helpers"]
end

subgraph group_repo_support["Repo Support"]
  node_docs_examples_tests["Docs & Tests<br/>repo support"]
end

node_hypex_ab -->|"uses"| node_experiments
node_hypex_aa -->|"uses"| node_experiments
node_hypex_matching -->|"uses"| node_matching_path
node_hypex_homogeneity -->|"uses"| node_experiments
node_experiments -->|"consumes"| node_dataset
node_dataset -->|"feeds"| node_transformers
node_preprocessing -->|"wraps"| node_transformers
node_transformers -->|"prepares for"| node_comparators
node_experiments -->|"selects"| node_analyzers
node_analyzers -->|"delegates"| node_executor
node_executor -->|"runs"| node_comparators
node_analyzers -->|"emits"| node_reporters
node_reporters -->|"formats for"| node_ui
node_matching_path -->|"encodes"| node_encoders
node_matching_path -->|"splits"| node_splitters
node_matching_path -->|"searches"| node_ml_faiss
node_encoders -->|"adapts"| node_extensions
node_ml_faiss -->|"adapts"| node_extensions
node_comparators -->|"uses"| node_extensions
node_analyzers -->|"applies"| node_hypotheses
node_factory -->|"assembles"| node_experiments
node_operators -->|"supports"| node_analyzers
node_forks -->|"specializes"| node_experiments
node_utils -->|"supports"| node_dataset
node_docs_examples_tests -.->|"covers"| node_hypex_ab
node_docs_examples_tests -.->|"covers"| node_dataset
node_docs_examples_tests -.->|"covers"| node_matching_path

click node_hypex_ab "https://github.com/sb-ai-lab/hypex/blob/master/hypex/ab.py"
click node_hypex_aa "https://github.com/sb-ai-lab/hypex/blob/master/hypex/aa.py"
click node_hypex_matching "https://github.com/sb-ai-lab/hypex/blob/master/hypex/matching.py"
click node_hypex_homogeneity "https://github.com/sb-ai-lab/hypex/blob/master/hypex/homogeneity.py"
click node_dataset "https://github.com/sb-ai-lab/hypex/tree/master/hypex/dataset"
click node_transformers "https://github.com/sb-ai-lab/hypex/tree/master/hypex/transformers"
click node_preprocessing "https://github.com/sb-ai-lab/hypex/blob/master/hypex/preprocessing.py"
click node_experiments "https://github.com/sb-ai-lab/hypex/tree/master/hypex/experiments"
click node_executor "https://github.com/sb-ai-lab/hypex/tree/master/hypex/executor"
click node_analyzers "https://github.com/sb-ai-lab/hypex/tree/master/hypex/analyzers"
click node_comparators "https://github.com/sb-ai-lab/hypex/tree/master/hypex/comparators"
click node_reporters "https://github.com/sb-ai-lab/hypex/tree/master/hypex/reporters"
click node_ui "https://github.com/sb-ai-lab/hypex/tree/master/hypex/ui"
click node_matching_path "https://github.com/sb-ai-lab/hypex/blob/master/hypex/matching.py"
click node_splitters "https://github.com/sb-ai-lab/hypex/tree/master/hypex/splitters"
click node_encoders "https://github.com/sb-ai-lab/hypex/tree/master/hypex/encoders"
click node_ml_faiss "https://github.com/sb-ai-lab/hypex/blob/master/hypex/ml/faiss.py"
click node_extensions "https://github.com/sb-ai-lab/hypex/tree/master/hypex/extensions"
click node_operators "https://github.com/sb-ai-lab/hypex/tree/master/hypex/operators"
click node_factory "https://github.com/sb-ai-lab/hypex/tree/master/hypex/factory"
click node_forks "https://github.com/sb-ai-lab/hypex/tree/master/hypex/forks"
click node_hypotheses "https://github.com/sb-ai-lab/hypex/tree/master/hypex/hypotheses"
click node_utils "https://github.com/sb-ai-lab/hypex/tree/master/hypex/utils"
click node_docs_examples_tests "https://github.com/sb-ai-lab/hypex/tree/master/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_hypex_ab,node_hypex_aa,node_hypex_matching,node_hypex_homogeneity toneBlue
class node_dataset,node_transformers,node_preprocessing,node_experiments,node_executor,node_analyzers,node_comparators,node_reporters,node_ui toneAmber
class node_matching_path,node_splitters,node_encoders,node_ml_faiss toneMint
class node_extensions,node_operators,node_factory,node_forks,node_hypotheses,node_utils toneRose
class node_docs_examples_tests toneIndigo
```

## Components

### Public API

Small facade layer for experiment types and user-facing entry points.

- [AB Test](https://github.com/sb-ai-lab/hypex/blob/master/hypex/ab.py): facade · Top-level AB testing entry point. · `hypex/ab.py`
- [AA Test](https://github.com/sb-ai-lab/hypex/blob/master/hypex/aa.py): facade · Top-level A/A testing entry point. · `hypex/aa.py`
- [Matching](https://github.com/sb-ai-lab/hypex/blob/master/hypex/matching.py): facade · Top-level matching entry point. · `hypex/matching.py`
- [Homogeneity](https://github.com/sb-ai-lab/hypex/blob/master/hypex/homogeneity.py): facade · Top-level homogeneity analysis entry point. · `hypex/homogeneity.py`

### Core Engine

Dataset boundary, preprocessing, orchestration, analyzers, comparators, and reporting.

- [Dataset](https://github.com/sb-ai-lab/hypex/tree/master/hypex/dataset): role-aware data boundary · Wraps tabular input and assigns semantic roles through backend abstractions. · `hypex/dataset`
- [Transformers](https://github.com/sb-ai-lab/hypex/tree/master/hypex/transformers): preprocessing pipeline · Cleans and reshapes data with casting, NA filling, filtering, shuffling, aggregation, and CUPED. · `hypex/transformers`
- [Preprocess](https://github.com/sb-ai-lab/hypex/blob/master/hypex/preprocessing.py): prep facade · Convenience layer for data preparation before analysis. · `hypex/preprocessing.py`
- [Experiments](https://github.com/sb-ai-lab/hypex/tree/master/hypex/experiments): orchestration · Coordinates analysis paths and experiment assembly. · `hypex/experiments`
- [Executor](https://github.com/sb-ai-lab/hypex/tree/master/hypex/executor): compute pipeline · Runs calculators and shared execution steps. · `hypex/executor`
- [Analyzers](https://github.com/sb-ai-lab/hypex/tree/master/hypex/analyzers): statistical engines · AB, AA, and matching analysis logic that consumes prepared datasets. · `hypex/analyzers`
- [Comparators](https://github.com/sb-ai-lab/hypex/tree/master/hypex/comparators): statistical primitives · Distance, hypothesis testing, power testing, and comparison interfaces. · `hypex/comparators`
- [Reporters](https://github.com/sb-ai-lab/hypex/tree/master/hypex/reporters): result formatting · Formats analysis outputs into readable reports for each workflow. · `hypex/reporters`
- [UI](https://github.com/sb-ai-lab/hypex/tree/master/hypex/ui): presentation layer · User-facing wrappers around report output. · `hypex/ui`

### Matching Stack

Feature encoding, splitting, and accelerated nearest-neighbor matching path.

- [Matching Flow](https://github.com/sb-ai-lab/hypex/blob/master/hypex/matching.py): matching pipeline · Feature encoding and matching workflow for causal pairing. · `hypex/matching.py`
- [Splitters](https://github.com/sb-ai-lab/hypex/tree/master/hypex/splitters): pairing helpers · Splits units for matching-oriented workflows. · `hypex/splitters`
- [Encoders](https://github.com/sb-ai-lab/hypex/tree/master/hypex/encoders): feature encoders · Encodes features before comparison or nearest-neighbor search. · `hypex/encoders`
- [Faiss ML](https://github.com/sb-ai-lab/hypex/blob/master/hypex/ml/faiss.py): accelerated search backend · Nearest-neighbor acceleration used by matching flows. · `hypex/ml/faiss.py`

### Supporting Code

Shared abstractions, utilities, extensions, and hypothesis schemes.

- [Extensions](https://github.com/sb-ai-lab/hypex/tree/master/hypex/extensions): optional backends · Isolates optional scientific and acceleration integrations such as Faiss, SciPy, Statsmodels, and CUPAC. · `hypex/extensions`
- [Operators](https://github.com/sb-ai-lab/hypex/tree/master/hypex/operators): shared abstractions · Strategy-like operator interfaces and implementations. · `hypex/operators`
- [Factory](https://github.com/sb-ai-lab/hypex/tree/master/hypex/factory): assembly layer · Creates and wires core experiment components. · `hypex/factory`
- [Forks](https://github.com/sb-ai-lab/hypex/tree/master/hypex/forks): variant adapters · Workflow variants and specialized branches. · `hypex/forks`
- [Hypotheses](https://github.com/sb-ai-lab/hypex/tree/master/hypex/hypotheses): scheme registry · Hypothesis models and scheme definitions. · `hypex/hypotheses`
- [Utils](https://github.com/sb-ai-lab/hypex/tree/master/hypex/utils): shared helpers · Constants, enums, models, errors, typings, and adapter helpers. · `hypex/utils`

### Repo Support

Examples, docs, and tests around the library package.

- [Docs & Tests](https://github.com/sb-ai-lab/hypex/tree/master/docs): repo support · Documentation site, examples, and regression tests around the library. · `docs`

## Connections

- AB Test → Experiments: uses · AB facade delegates orchestration to experiment layer.
- AA Test → Experiments: uses · AA facade delegates orchestration to experiment layer.
- Matching → Matching Flow: uses · Matching facade exposes the matching workflow.
- Homogeneity → Experiments: uses · Homogeneity entry point routes through shared experiment plumbing.
- Experiments → Dataset: consumes · Experiments operate on role-aware datasets.
- Dataset → Transformers: feeds · Prepared dataset flows into preprocessing.
- Preprocess → Transformers: wraps · Preprocessing is the user-facing preparation layer.
- Transformers → Comparators: prepares for · Cleaned data is passed to statistical comparison logic.
- Experiments → Analyzers: selects · Orchestration chooses the relevant analysis engine.
- Analyzers → Executor: delegates · Analyzers rely on shared execution/calculation pipeline.
- Executor → Comparators: runs · Execution stage invokes statistical primitives and calculators.
- Analyzers → Reporters: emits · Analysis results are packaged for reporting.
- Reporters → UI: formats for · Reports are exposed through user-facing UI wrappers.
- Matching Flow → Encoders: encodes · Matching flow starts with feature encoding.
- Matching Flow → Splitters: splits · Matching flow partitions units before pairing.
- Matching Flow → Faiss ML: searches · Matching flow can accelerate pairing with Faiss.
- Encoders → Extensions: adapts · Encoder integrations are isolated in extensions.
- Faiss ML → Extensions: adapts · Faiss backend is wrapped as optional extension.
- Comparators → Extensions: uses · Statistical routines rely on optional SciPy/Statsmodels backends.
- Analyzers → Hypotheses: applies · Analysis flows use hypothesis schemes and definitions.
- Factory → Experiments: assembles · Factory wires experiment objects and components.
- Operators → Analyzers: supports · Operators provide reusable execution abstractions.
- Forks → Experiments: specializes · Forked variants customize experiment behavior.
- Utils → Dataset: supports · Utilities provide models, errors, enums, and adapter helpers.
- Docs & Tests → AB Test: covers · Docs and tests exercise public experiment entry points.
- Docs & Tests → Dataset: covers · Tutorials and tests demonstrate dataset handling.
- Docs & Tests → Matching Flow: covers · Examples document the matching workflow.
