Causal-Copilot: An Autonomous Causal Analysis Agent [Demo] • [Code] • [Technical Report] --- News 04/16/2025: We release Causal-Copilot-V2 …
Causal-Copilot: An Autonomous Causal Analysis Agent [Demo] • [Code] • [Technical Report] --- News 04/16/2025: We release Causal-Copilot-V2 …
Causal-Copilot: An Autonomous Causal Analysis Agent
[Demo] • [Code] • [Technical Report]
04/16/2025: We release Causal-Copilot-V2 and the official Technical Report. The new version supports automatically using 20 state-of-the-art causal analysis techniques, spanning from causal discovery, causal inference, and other analysis algorithms.
11/04/2024: We release Causal-Copilot-V1, the first autonomous causal analysis agent.
Identifying causality lets scientists look past correlations and uncover the mechanisms behind natural and social phenomena. Although many advanced methods for causal discovery now exist, their varied assumptions and technical complexity often discourage non‑experts from using them.
Causal‑Copilot addresses this gap. Guided by a LLM, it automates the full causal‑analysis workflow: data inspection, algorithm and hyperparameter selection, code generation, uncertainty assessment, and PDF report creation— all triggered through simple dialogue. By combining LLM‑driven domain knowledge with state‑of‑the‑art causal techniques, Causal‑Copilot lets researchers focus on scientific insight instead of implementation details.
Try out our interactive demo: Causal-Copilot Live Demo
We provide some examples of our system automatically generated reports for open-source datasets generated as follows:
Causal‑Copilot adopts a modular architecture built around five primary components—Simulation, User Interaction, Preprocessing, Algorithm Selection, and Postprocessing—that together deliver an end‑to‑end causal analysis pipeline. A large language model (LLM) sits at the core of the framework, coordinating data flow among these modules while tapping into auxiliary resources such as a causality‑focused knowledge base and a library of local algorithms. All modules communicate via unified interfaces that pass structured metadata and intermediate results, allowing the LLM to supervise execution seamlessly. This organization preserves clear separation of concerns, simplifies extension, and makes it straightforward to integrate new capabilities into the system.
Causal-Copilot integrates over twenty state-of-the-art causal analysis algorithms, broadly categorized into causal discovery, causal inference, and auxiliary analysis tools.
Try out our interactive demo: Causal-Copilot Live Demo
We strongly recommend using Docker for the most stable and reliable installation, as it handles all system dependencies including LaTeX packages automatically.
Prerequisites:
For CPU version:
# Build the Docker image
docker build -f Dockerfile.cpu -t causal-copilot-cpu .
# Run the container
docker run -it --rm -v $(pwd):/app -p 7860:7860 causal-copilot-cpuFor GPU version:
# Build the Docker image
docker build -f Dockerfile.gpu -t causal-copilot-gpu .
# Run the container with GPU support
docker run -it --rm --gpus all -v $(pwd):/app -p 7860:7860 causal-copilot-gpu** Using Ollama with Docker:** If you are running Ollama on your host machine and want to connect to it from inside the Docker container, set the following environment variable in your .env file:
OLLAMA_BASE_URL=http://host.docker.internal:11434This is because localhost inside a container refers to the container itself, not the host machine. host.docker.internal is a special DNS name that resolves to the host.
On native Linux Docker Engine, add --add-host=host.docker.internal:host-gateway to the docker run command if host.docker.internal does not resolve automatically.
⚠️ Note: Conda environment installation might not be stable and may have compatibility issues with LaTeX dependencies required for report generation. We recommend using Docker instead.
Prerequisites:
requirements_cpu.txt and requirements_gpu.txt)tinyTeX)Step 1: Create Python 3.10 Environment
# Create a new conda environment with Python 3.10
conda create -n causal-copilot python=3.10 -y
conda activate causal-copilotStep 2: Run Setup Script
For CPU version:
bash setup_cpu.shFor GPU version (if you have NVIDIA GPU):
bash setup_gpu.shFor lightweight maintainer checks, install the development tools in a Python 3.10 environment and run:
pip install -r requirements_dev.txt
bash scripts/verify.shThe default verification command runs syntax-level linting, smoke tests, and Python bytecode compilation for owned project code. LLM, Ollama, and LaTeX integration checks are opt-in because they require external services or system tooling:
RUN_LLM_TESTS=1 pytest causal_discovery/tests/selection_test.py
RUN_OLLAMA_TESTS=1 pytest llm/test_ollama.py
RUN_LATEX_TESTS=1 pytest test_latex_functionality.pyCausal-Copilot uses environment variables for configuration. Create a .env file in the project root directory:
** LLM Support:**
⚠️ Performance Note: Local LLM processing speed depends on your machine specifications. Instruction-following capabilities may vary across models and can affect analysis quality and runtime duration.
Step 1: Copy the example configuration
cp .env.example .envStep 2: Configure your settings
The key environment variables you need to configure:
| Variable | Description | Default | Required |
|---|---|---|---|
LLM_PROVIDER |
LLM provider (openai, ollama, openrouter) |
ollama |
✅ |
LLM_MODEL |
Model name (e.g., gpt-4, llama3.2, mistral) |
llama3.2 |
✅ |
OPENAI_API_KEY |
OpenAI API key | - | ⚠️ (if using OpenAI) |
OLLAMA_BASE_URL |
Ollama server base URL | http://localhost:11434 |
⚠️ (if using Ollama) |
OUTPUT_REPORT_DIR |
Directory for generated reports in chatbot demo | output_report |
❌ |
OUTPUT_GRAPH_DIR |
Directory for generated graphs in chatbot demo | output_graph |
❌ |
Example configurations:
For OpenAI:
LLM_PROVIDER=openai
LLM_MODEL=gpt-4o
OPENAI_API_KEY=sk-your-openai-api-key-hereFor Openrouter:
LLM_PROVIDER=openrouter
LLM_MODEL=anthropic/claude-sonnet-4
OPENROUTER_API_KEY=sk-or-your-openrouter-api-key-hereFor Ollama (local):
LLM_PROVIDER=ollama
LLM_MODEL=llama3.2
OLLAMA_BASE_URL=http://localhost:11434⚠️ Important Notes:
.env file secure and never commit it to version controlollama pull llama3.2There are two ways to use Causal-Copilot:
Use the CLI for focused causal discovery analysis:
python main.py --data-file your_data.csv --initial_query "your user query"Features:
Use the web interface for comprehensive causal analysis:
python web_demo/demo.pyFeatures:
Access: After running the command, open your browser and navigate to the provided local URL (typically http://localhost:7860 or public gradio set if you set share=True).
Distributed under the MIT License. See LICENSE for more information.
No open issues yet, or sync has not completed.