Causal Cartographer: From Mapping to Reasoning Over Counterfactual Worlds

Introduction

Repository for the Causal Cartographer project. This framework is a twofold LLM-based approach for causal extraction and counterfactual inference.

(1) Extraction agents can extract causal knowledge from natural language text and compose causal world models.

(2) The built causal world models allow the creation of counterfactual scenarios based on the extracted causal knowledge.

(3) Reasoning agents perform counterfactual causal inference on natural language followin causal constraints.

Installation

python -m venv env
source env/bin/activate
pip install -r requirements.txt

On Windows, use env\Scripts\activate or env\Scripts\Activate.ps1 instead of source env/bin/activate.

A subscription to an LLM API provider may be required.

Usage

The framework provides several scripts for different tasks:

Causal Discovery

Use run_discovery.py to extract causal graphs from text data:

# Basic usage
python src/run_discovery.py --api_key YOUR_API_KEY

# Custom data directory and model
python src/run_discovery.py --data_dir path/to/data --model_base model-name --api_key YOUR_API_KEY

# Resume from a previous graph
python src/run_discovery.py --resume path/to/graph.gml --api_key YOUR_API_KEY

# Process limited number of documents
python src/run_discovery.py --max_docs 10 --api_key YOUR_API_KEY

Causal Inference and Evaluation

Use run_evaluation.py to evaluate causal inference on existing graphs:

# Evaluate using an existing graph
python src/run_evaluation.py --graph_path path/to/graph.gml --api_key YOUR_API_KEY

# Evaluate using a dataset
python src/run_evaluation.py --dataset_path path/to/dataset.csv --api_key YOUR_API_KEY

# Generate dataset without evaluation
python src/run_evaluation.py --graph_path path/to/graph.gml --build_dataset_only --dataset_save_path data/dataset --api_key YOUR_API_KEY

# Customize inference parameters
python src/run_evaluation.py --graph_path path/to/graph.gml --max_interventions 2 --mixing_functions none --api_key YOUR_API_KEY

Graph Visualization Tool

The project includes an interactive graph visualization tool that helps you explore causal graphs generated by the agents. The visualization tool provides features like clustering, world attribute filtering, and detailed node/edge information.

To use the visualization tool:

# Launch the visualization tool
python src/visualize_graph.py

# Open a specific graph file directly
python src/visualize_graph.py --graph data/results/causal_graph_2025-03-04_13-36-23.gml

# Customize the port (default is 5000)
python src/visualize_graph.py --port 8080

Features

• Interactive Graph Exploration: Pan, zoom, and click on nodes/edges to view attributes
• Cluster-Based Visualization: Nodes are automatically clustered and color-coded based on their connectivity
• World Attribute Filtering: Highlight nodes that share specific world attributes
• Graph Physics Controls: Adjust the physics simulation for better visualization of large graphs
• Information Panel: View detailed information about nodes and edges by clicking on them

List of Agents

Agent Name	Description	Standalone	Component	Dependencies	Implementation
Causal Discovery Agents
atomic_discovery_agent	Agent that builds a simple networkx causal graph from a text snippet using pre-trained commonsense knowledge.	✅	✅	networkx	✅
atomic_rag_agent	Agent that extracts causal graphs using retrieval augmented generation (RAG) for improved contextual understanding.	✅	✅	networkx	✅
self_iterative_agent	Agent that recursively builds a networkx causal graph from a text snippet or a topic. Stops after a predefined number of steps.	✅	✅	networkx	✅
Causal Inference Agents
causal_inference_agent	Agent that performs counterfactual causal inference on a networkx causal graph using an LLM as an inference engine.	✅	✅	networkx	✅
backward_inference_agent	Agent that performs backward causal reasoning from effects to potential causes.	✅	✅	networkx	✅
cot_agent	Agent that performs causal inference using chain-of-thought reasoning for more transparent decision making.	✅	✅		✅

License

This project is licensed under the MIT License - see the LICENSE file for details.