Causal Forge

Chinese README: README.zh-CN.md

An open-source causal analysis assembly line that forces language-level causal claims and data-level causal signals to collide, then keeps only the links that survive both sides of scrutiny.

What It Is

Causal Forge is a pipeline for building evidence-backed causal chains from two independent sources:

• top-down: causal statements extracted from policy texts, reports, speeches, and other natural-language documents
• bottom-up: candidate causal edges discovered from historical time-series or panel data
• crosscheck + validate: semantic alignment, intersection, and a five-gate validation pipeline

The project is built for teams that need causal reasoning they can explain, audit, and rerun, not just a one-off model output.

Why It Exists

Most organizations have two disconnected kinds of causal evidence:

• Experts and documents say things like "if A happens, B should follow", but those claims are hard to falsify.
• Data pipelines surface statistical relationships, but those relationships are often hard to explain in business terms.

Causal Forge puts those two worlds into the same workflow. If text evidence and data evidence agree, we deepen validation. If they disagree, we record the conflict. If one side is missing, we keep the candidate as incomplete rather than pretending it is settled.

What It Is Not

This project is	This project is not
A causal evidence assembly line	Another general-purpose causal inference library
A traceable knowledge workflow for causal links	A BI dashboard or reporting layer
A way to cross-check expert narratives with data	A black-box system that auto-generates truth
A research and audit tool for macro, policy, fundamentals, and attribution	A primary engine for HFT, market making, or execution

Core Idea

Only candidates supported by both sides can move forward:

Text claims (top-down) ----\
                             -> crosscheck -> validate -> chain forge
Data signals (bottom-up) --/

Each intersected candidate is then tested through five gates:

1. necessity
2. sufficiency
3. temporality
4. irreversibility
5. cross-regime stability

Only links that clear the full sequence are marked as forged=true.

Domain Fit

Best fit:

• Macro policy transmission
• Fundamental research
• Event-driven explanation
• Risk attribution
• Research-report verification

Less suitable:

• High-frequency trading signal generation
• Market making or execution systems
• Use cases that require a standalone real-time service today

Current Verified State

As of 2026-05-07, the latest validated MVP full run is runs/20260507T191841__e62028b__full.

• decisions=32
• callbacks=39
• intersected evidence links=14
• intersected unique variable edges=3
• forged evidence links=4
• forged unique variable edges=1
• canonical chains=1
• cross-method stable forged edge=FEDFUNDS -> INDPRO

Important nuance:

• The first fully forged variable edge is FEDFUNDS -> INDPRO.
• FEDFUNDS -> UNRATE is intersected but not yet forged.
• FEDFUNDS -> CPIAUCSL is intersected but still failing multiple gates.

So the main pipeline is real and usable, but coverage is still narrow.

Architecture

Raw corpus                            Raw data
(policy/research/speeches)            (csv/parquet/time series)
        |                                      |
        v                                      v
  [p01] topdown                          [p02] bottomup
        \                                      /
         \----------- [p03] crosscheck -------/
                          |
                          v
                    [p04] validate
                          |
                          v
                    [p05] chain forge
                          |
                          v
                    JSONL / Graph exports

Key modules:

• causalforge/schema/: typed contracts for Decision, Callback, CausalLink, and CausalChain
• causalforge/topdown/: language-to-structure extraction
• causalforge/bottomup/: data-driven causal discovery
• causalforge/crosscheck/: semantic and statistical alignment
• causalforge/validate/: the five-gate validation workflow
• causalforge/chain/: DAG assembly, pruning, and scoring
• causalforge/store/: JSONL and graph exports

Quick Start

Requirements:

• Python 3.11+
• uv recommended, or plain pip
• An LLM API key for top-down extraction

Install:

git clone https://github.com/your-org/causal-forge.git
cd causal-forge

uv venv && source .venv/bin/activate
uv pip install -e ".[causal,text,dev]"

Or with pip:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[causal,text,dev]"

Create local env vars:

cp .env.local.example .env.local

Then fill in one of:

• ANTHROPIC_API_KEY
• OPENAI_API_KEY
• another OpenAI-compatible key expected by causalforge/topdown/_llm_io.py

Sanity check:

causalforge hello
pytest -q

Run the full MVP pipeline:

python pipelines/p99_full.py --config config/mvp.yaml

Artifacts land under runs/<timestamp>/, including:

• REPORT.md
• cross_method_stability.json
• validate_summary.json
• edge_diagnostics.json
• chain exports

Security And Repo Hygiene

This repo is already set up to avoid common secret leaks:

• .env.local is ignored by .gitignore
• secrets/ is ignored
• runs/ is ignored because it can contain evidence payloads and generated artifacts

Before pushing publicly, still do a quick check:

git status --short
git diff --stat
rg -n "(API[_ -]?KEY|SECRET|TOKEN|PASSWORD|BEGIN OPENSSH PRIVATE KEY|BEGIN RSA PRIVATE KEY)" .

Do not commit real credentials. Use .env.local.example as the public template.

Documentation Map

• Current Status
• Core Ideas
• Architecture Overview
• Reference Projects
• Tech Stack
• Schema
• Roadmap
• MVP Scope

Contributing

See CONTRIBUTING.md.

Project expectations:

• Discuss larger features before opening a PR
• Version schema changes explicitly
• Keep tests green with pytest -q
• Treat failed causal links as useful evidence, not noise to delete

License

Apache-2.0. See LICENSE.