Skip to content

Architecture

This section describes how badgers is structured, why it is structured that way, and which of those claims are enforced automatically.

It follows a trimmed arc42 outline — only the sections that carry information for a single-process Python library — plus a C4 level-1 context diagram and a log of architecture decision records (ADRs).

How to read this section

Page Question it answers Changes how often
System context Who uses badgers, and what does it depend on? Rarely
Building blocks Which modules exist, and which may depend on which? When a package is added
Runtime scenarios What happens during a generate() call? When a flow changes
Quality goals What does "good architecture" mean here, testably? Rarely
Causal defect family How do the causal generators, DGPs and backends fit together? When the causal API changes
Decisions Why is it like this, and what was rejected? Append-only

The one-paragraph version

badgers is a library of generators: objects exposing generate(X, **params) -> Xt that augment data with quality deficits (outliers, missing values, noise, drift, imbalance, typos, …). Everything modality-specific (e.g., tabular_data, time.series, text, etc.) lives under badgers.generators; everything reusable lives under badgers.core. The core is split into four independent concerns — the generator contract, the selector contract (which rows get a deficit), the sampler contract (what values replace them), and the DGP contract (how a causal model propagates a deficit). A generator composes these; it never reimplements them.

What is enforced, not just documented

Architecture documents rot. The structural claims on these pages are therefore split into two halves: a narrative half (this section) and an enforced half — import contracts checked by import-linter in CI. If the code ever contradicts the building blocks page, the build fails.

# run the contracts locally
lint-imports

The contracts live in pyproject.toml under [tool.importlinter]; see ADR-0007 for the full list and the reasoning.

Contract Meaning
core must not depend on generators The foundation never imports a concrete generator.
generators must not import DGP backends Generators are backend-blind; backends are injected.
core.dgp must not import generators The DGP protocol does not know about deficits.
the library must not import the benchmarks package benchmarks/ is a consumer, never a dependency.
Layered architecture: generators -> dgp -> selectors -> utils Dependency direction is one-way.

Import hygiene is additionally pinned by tests/core/test_import_hygiene.py, which asserts that importing badgers.core.dgp never pulls pymc, pytensor or dowhy into sys.modules.

Conventions used on these pages

  • Module paths are written as badgers.core.selectors, not as file paths.
  • Diagrams are Mermaid and are rendered by mkdocs-material; they are hand-written and deliberately few, because hand-written diagrams are the part that rots fastest.
  • API-level detail is not duplicated here — it is generated from docstrings into the API reference. If you want to know what a class does, read the API reference; if you want to know why it exists, read this section.