CausalEngine implementation Wiki

This wiki helps lab developers familiar with Python find the package’s execution paths and module responsibilities. English is the default language for the HTML tool and its documentation, including this Wiki. Runtime API baseline: 0.1.0a13, with CSCM_capo at 2062d7ac. The module map describes the consolidated source layout. The original walkthrough and historical validation tables retain their earlier source revisions. Start with the complete runnable walkthrough or Document. Browser Wiki: causalscience.ai/docs/causalengine/wiki/.

Start here

• Install the public CausalScience package.
• Use six graph-free APIs: BD/SBD/conditional FD/UCA means and paired ATE/CATE.
• API contracts, schema and causal assumptions.
• Whole-call benchmark versus shared-component timing.
• Current validation and implementation map.

A file having current callers does not mean every function in it has been executed or validated. tian.py, identify.py, and examples.py have callers in current execution paths. tutorials/example_scm.py supports checkout tutorials; it is not an installed-package runtime module.

1. Key distinctions

• Query: a question specifying the action nodes to intervene on and the outcome nodes of interest.
• Typed expression / indexed copy: a structured formula that records variable roles and uses distinct slots for an original variable’s natural value and fixed intervention value.
• Identification: finding a formula for a graph query in terms of the observational distribution.
• Estimation: using that formula and observational data to numerically estimate a causal mean.
• Witness: graph information that can be checked to verify a selected criterion.
• Backend: an implementation that executes a formula. The choices here are native, finite, and score.
• Cluster: one graph node represented by multiple data columns. It is not split into separate graph nodes.

Identification status ACCEPT does not guarantee estimation accuracy or confidence-interval coverage. UNKNOWN also differs from NOT_IDENTIFIABLE: a budget-limited search may simply be unfinished.

2. End-to-end execution

The processing list shows processing flow. Its arrows do not all represent direct Python imports.

1. causalengine public API → random_generator
2. random_generator → SCM + scm_registry
3. SCM + scm_registry → observational data + graph schema
4. causalengine public API → BDSCM / CSCM task presets
5. BDSCM / CSCM task presets → SCM + scm_registry
6. BDSCM / CSCM task presets → separate generator truth / episodes
7. causalengine public API → estimators: BD / SBD / FD / supplied UCA
8. estimators: BD / SBD / FD / supplied UCA → finite / score: vendored UCA compiler and score engine
9. causalengine public API → effects: paired ATE / baseline CATE
10. effects: paired ATE / baseline CATE → estimators: BD / SBD / FD / supplied UCA
11. causalengine public API → identification_engine.identify_query
12. identification_engine.identify_query → verified criterion witness + typed formula
13. observational data + graph schema → identification_engine.fit_query_mean
14. verified criterion witness + typed formula → identification_engine.fit_query_mean
15. identification_engine.fit_query_mean → native mean: specialized adapters / normalized executor
16. identification_engine.fit_query_mean → finite / score: vendored UCA compiler and score engine
17. native mean: specialized adapters / normalized executor → result + diagnostics
18. finite / score: vendored UCA compiler and score engine → result + diagnostics

Public entry points are defined in src/causalengine/init.py. identify_query processes a graph query without data. fit_query_mean defaults to FMC→MC certification and a UCA full score with XGBoost backward regressions. Graph-only identify_query keeps its producer order. See the default UCA guide for a discrete-action example and inference boundaries.

3. Installation and public API

Start with the public installation guide for Python 3.11+, a project environment, and troubleshooting. Repository access is not required to install the public PyPI distribution:

python -m pip install CausalScience
python -m causalscience.demo

Use import causalscience from any project directory. CausalEngine remains the project/repository name; the CausalEngine PyPI name request remains pending. No separate paper repository or sys.path modification is required.

from causalscience import random_scm, identify_query, fit_query_mean

model, X, Y = random_scm(
    4, 0, 1, 1, seednum=13, equation_families='linear',
    max_graphs=8, max_retries=1,
)
rows = model.sample_observational(3000, seed=14)
identified = identify_query(model.graph, X, Y)
fitted = fit_query_mean(
    model.graph, X, Y, rows, {x: 1 for x in X},
    params={'booster': 'gblinear', 'eta': 1}, backend='native',
)
print(identified['status'], fitted.get('estimation_status'))
print(fitted.get('estimate'))

The scalar action in this example is 1. Specify vector actions at the full width of their graph node. See the installed demo for scalar/cluster generation, query selection, and comparison with an independent intervention reference. Not every query on a random graph is identifiable; always inspect the returned status.

4. Core module map

All runtime Python code is canonical under src/causalengine/. Source and installed modules use the same package-relative imports; the build does not rewrite or copy root implementations. Use causalscience.* for the public Python interface; source-module paths in this map retain causalengine for provenance. See the repository map.

These local sources locate the main functions in the inspected working tree:

• identification_engine.identify_query: identification and dispatch
• identification_engine.fit_query_mean: estimation and backend selection
• identify.ID_return_Ctree: ID decomposition
• tian.mtc_expression: Tian/MTC typed expression
• indexed_identification.fit_normalized_mean: native mean
• indexed_identification.fit_normalized_score: score adapter

In particular, identify.py is not the public dispatcher. The public function is identify_query in identification_engine.py. indexed_identification.py is not a duplicate name for that layer: it represents and executes expressions while distinguishing original variables from their indexed copies.

4a. Model and preset layer

An SCM (structural causal model) fixes one generation function per graph node. BDSCM is the back-door task preset; CSCM adds a hidden common cause. The 14 core modules above live beside the preset and public API modules under src/causalengine/. The installed package also has these source-owned modules and data:

X in these presets is one vector graph node, A a scalar binary action, and Y a scalar outcome. Sampling returns observed X, A, and Y separately from generator truth. CSCM sample truth conditions on U (e_xu, mu0_xu, mu1_xu). The separate truth_at(x) query returns observed-X arm means (mu0, mu1) with analytic or numerical diagnostics; it uses the known SCM and is not an observational-data estimator. Generic model edits return plain SCM copies; analytic preset truth is not supplied for arbitrary new mechanisms. See the preset calling guide.

CSCM_capo is a separate direct-CAPO outcome parameterization. It preserves CSCM X/A generation and shared seeds, and supports Gaussian-family continuous, Bernoulli binary and Poisson count outcomes. Its truth_at(X) directly reads mu0/mu1; sampling uses numerical conditional centering, whose convergence diagnostics are not certified error bounds. Existing CSCM keeps its original outcome law and posterior-integrated CAPO query.

The default CSCM has U → X, U → A, and U → Y. The current common API returns UNKNOWN for its A-to-Y query even with max_seconds=None; the _paper_names bridge excludes hidden nodes with more than two children, so fixed_MC, MC, Product, and indexed report UNSUPPORTED. This is a current engine boundary, not a non-identification proof. The tested unconfounded=True variant returns ACCEPT via BD.

5. Methods and estimation routes

Public METHODS exposes these 12 identifiers:

BD, AC, SBD, FD, Tian, MTCv1, MTCv2, WMC, fixed_MC, MC, Product, indexed.

• BD means back-door, AC adjustment criterion, SBD sequential back-door, and FD front-door.
• MTCv1/v2 select two versions of the manuscript criterion expression; WMC uses a grouped-kernel witness; fixed_MC uses a fixed partition; MC searches partitions.
• Tian selects the singleton Tian route, Product an ID-trace-based route, and indexed indexed identification.
• Graph-only identify_query(method='auto') tries producers in its existing order.
• Default fit_query_mean first checks FMC (fixed_MC), then MC with the remaining budget; FMC acceptance already certifies MC. UNKNOWN remains an unfinished search status.
• Specifying a method selects that producer. AC and BD are different criteria.
• Every query is preprocessed first. Values for pruned original actions are still validated.
• native uses a dedicated BD/AC/SBD adapter or the normalized-expression executor.
• Eligible continuous-vector affine FD uses the common normalized route and observational-data stabilization.
• finite passes explicit scalar finite alphabets to the actual UCA compiler and score engine.
• score (default) connects a verified formula to the full score with XGBoost backward regressions. Point-score support/learning assumptions are explicit; finite/affine causal inference requires an additional model declaration.
• Even after identification is accepted, estimation can be UNSUPPORTED if the backend cannot execute the formula/domain.

See fit_query_mean for the branch conditions and the public result guide for status, estimation_status, attempted, and failure handling.

No single function in tian.py handles every method. MC/indexed use the vendored-engine boundary, while Product uses an ID trace. The identify_query source linked above is authoritative for the actual branches.

6. The three vendored engine snapshots

These provenance-tracked modules are canonical package source files. Runtime does not search a separate paper checkout. Original snapshot hashes and license status are recorded in SOURCES.json and NOTICE.txt. Public distribution was authorized by Yonghan Jung on October 26, 2026 under the existing noncommercial license; prior MIT rights remain intact. See LICENSING.md. The candidate’s uca_estimation.py has a local minimum-L2 weighting patch. SOURCES.json preserves its original upstream hash separately from the current bundled hash; source and wheel now have identical package-relative imports.

7. Files outside the package runtime

The editor’s tutorials.graph_editor.generate_scm builds the real SCM and returns columns, rows, shape, and model descriptions; tutorials.graph_editor.EditorHandler serves the page and /generate on loopback. From the checkout, run python -B -m tutorials.graph_editor --port 8765, then visit http://127.0.0.1:8765. The inspected limits are 1–50 nodes, node dimensions 1–8, and 0–1000 output rows. This prototype retains its Korean UI; the installed identification tool defaults to English. The earlier snapshot was checked with test_graph_editor.py, including the local HTTP handler; actual browser interaction/layout was not tested.

The committed organization pass on October 26 moved the six checkout test modules (test_adjustment, test_frontdoor, test_SBD, test_identification, test_indexed_identification, test_graph_editor) into tests/checkout/. Run PYTHONPATH=src python -B -m unittest discover -s tests/checkout -v; the SCM suite is now in that same directory. Run installed-package contracts in a separate process to preserve their lazy-import checks. The two tutorials/demo_*.py research demos remain source-only; some options require an explicit external engine directory. These organization changes were published before a13. They separate checkout research tooling from the installed runtime; they are not pending implementation.

8. Validation scope

The October 27 source-layout check passed 226 source cases and 79 installed cases (67 unittest plus 12 function-based BDSCM checks), with no skips. Ten demo/CLI checks passed; source and installed public demo outputs matched. The separate experimental component retained four pre-existing failures (84/88), reproduced at the prior HEAD. These local layout checks did not create a published revision or establish statistical accuracy/coverage. See the current guide and dated historical records.

For the published a13 baseline bd14e4dc on October 26, 60 distinct tests passed with zero skips: 38 installed contracts and 22 graph-engine regressions. Seven API-guide Python blocks passed. The whole-call API pilot completed 20/20 trials. See the current validation record.

The remaining records describe earlier snapshots. The a11 record includes its original XGBoost/FMC→MC checks; it is not the latest test count.

The October 26 local organization pass used separate processes:

The two skipped classes are UCAAdapterTests and CommonEngineTests: their optional flat-import uca_compiler was not on PYTHONPATH. Class-level skips are separate from the 212 executed, passing test cases. The six relocated SCM editor tests passed within the checkout suite. No runtime source changed.

For the candidate, the weight suite passed 7 tests, the HTML HTTP suite 4 tests, and the public API suite 8 tests, using an installed wheel outside the checkout. See the candidate verification record. The following table preserves the earlier 0.1.0a9 documentation-pass results.

The earlier 0.1.0a9 documentation pass ran these checks using an existing Python 3.11.14 environment; no dependencies were added:

The installed checks ran outside the checkout against an existing local 0.1.0a9 installation target. Before execution, all 28 package source/data files were matched against this working tree, applying setup.py’s import rewrite to the 13 root modules and 3 vendored snapshots; there were no mismatches. This pass did not rebuild a wheel or retest a fresh installation. Commands and the exact runtime are recorded in the guide’s verification record.

The previous Wiki described commit 89732069 and recorded 48 passing checks, wheel-payload identity, and demo runs. Those are historical records, not the evidence for the current snapshot. The current tests do not validate every graph/function or all methods’ finite-sample accuracy and interval coverage.

Native means are generally plug-in estimates. The affine protocol for backend='score' assumes population affine closure, finite moments, full rank, and nuisance-rate conditions. The finite protocol also requires fixed alphabets and positive support. Numerical diagnostics cannot establish all these population assumptions. Intervals for vector outcomes are coordinatewise, not automatically simultaneous intervals. Earlier weak-design FD stress tests sometimes fell below nominal 95% coverage. A returned confidence interval must therefore not be treated as a guarantee of causal coverage.

9. Suggested reading order

1. src/causalengine/__init__.py: the names users import.
2. src/causalengine/demo.py: the smallest end-to-end example.
3. SCM.py and random_generator.py: graph/model generation versus dataset seeds.
4. identification_engine.identify_query: criterion selection and statuses.
5. The selected adjustment / SBD / frontdoor / tian module: witness contents.
6. identification_engine.fit_query_mean: specialized/normalized/score dispatch.
7. indexed_identification and statmodules: copies, regression boundaries, and fitting.
8. The vendored compiler/score engine and provenance, only when needed.

Graph-free point estimation (current a13)

The graph-free guide documents the new public estimate_bd, estimate_sbd, estimate_fd and estimate_uca entry points, schema/support declarations, conditional front-door covariates and caller-assumed provenance. Implementation: src/causalengine/estimators.py. Graph-based fit_query_mean keeps its existing verification route.

For sequential actions and time-varying covariates, see the ordered SBD example.

Effects and whole-call timing (a13)

• ATE/CATE and baseline-anchor conditions.
• Four graph-free APIs: exact-truth accuracy and full-call runtime.

The graph-free facades live in estimators.py; paired effects and baseline-anchor checks live in effects.py. The current namespace includes CSCM_capo and retains 12 graph criterion selectors; see __all__ for the authoritative export list.