Add example notebook: causal discovery with a foundation model + GCM root cause analysis

[bloebp]

Adds a new GCM example notebook showing that a plain CSV of observational data is sufficient for a full causal analysis: the causal graph is inferred with FoundCause, a pretrained foundation model for causal discovery (see Paper), and DoWhy's GCM module runs the analyses on the discovered graph.

The scenario is a simulated bottling line (ground truth via DoWhy's random SCM generator, including a hidden confounder), covering graph discovery, falsification with falsify_graph, root cause analysis of a defect spike and distribution-change attribution of a throughput drop.

[Copilot]

Pull request overview

Adds a new advanced documentation example notebook that demonstrates end-to-end causal discovery (via FoundCause) followed by DoWhy GCM analyses (graph falsification, anomaly attribution/root-cause analysis, and distribution-change attribution), and exposes it in the example notebook index.

Changes:

• Adds a new GCM example notebook: causal discovery from observational CSV data using FoundCause, then GCM-based analyses on the discovered graph.
• Updates the example notebook index to feature and include the new notebook in the Real world-inspired examples section.
• Ignores the local FoundCause model cache directory created when running the notebook.

Reviewed changes

Copilot reviewed 2 out of 4 changed files in this pull request and generated 3 comments.

File	Description
docs/source/example_notebooks/nb_index.rst	Adds the new notebook to the grid cards and toctree so it appears in the rendered docs.
docs/source/example_notebooks/gcm_causal_discovery_foundcause.ipynb	New advanced notebook demonstrating causal discovery + GCM analyses on a simulated bottling-line scenario.
.gitignore	Ignores the notebook-created foundcause_model/ cache directory under docs/source/example_notebooks/.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bloebp]

@emrekiciman any concerns left?

[github-actions]

🤖 This is an automated response from Repo Assist.

This is a really compelling addition — a complete end-to-end causal analysis pipeline from observational data using a foundation model for structure learning is exactly the kind of showcase example that will help new users appreciate the power of combining GCM with modern causal discovery.

A few observations worth discussing before merge:

Dependencies / setup: FoundCause is not part of DoWhy's standard extras. The notebook presumably requires a pip install foundcause step — it would help to have that cell early and prominently, ideally with a note on approximate download size (foundation models can be large). The .gitignore addition for the model cache is a nice touch.

CI / notebook execution: The notebook tests job in CI runs all notebooks in example_notebooks/. Since FoundCause needs an external model download and significant compute, this notebook might cause CI timeouts or failures on machines without internet access. Consider adding # %% [markdown] metadata or a nbmake skip marker — see how nb_index.rst lists other skipped notebooks — to keep CI green.

Minor nit: The .gitignore entry docs/source/example_notebooks/foundcause_model/ lacks a trailing newline after the last existing entry. No functional issue, but worth keeping consistent with the repo's gitignore style.

Great contribution from the FoundCause team — this showcases a genuinely useful workflow. Happy to see it merged once the CI question is resolved.

Generated by 🌈 Repo Assist, see workflow run. Learn more.

To install this agentic workflow, run

gh aw add githubnext/agentics/workflows/repo-assist.md@11c9a2c442e519ff2b427bf58679f5a525353f76

[emrekiciman]

nice notebook. stepped through and it ran well on a clean install, was easy to understand. thanks for making the additional edits to emphasize that the foundcause output requires validation before use.