causaliq-knowledge

The CausalIQ Knowledge project represents a novel approach to causal discovery by combining the traditional statistical structure learning algorithms with the contextual understanding and reasoning capabilities of Large Language Models. This integration enables more interpretable, domain-aware, and human-friendly causal discovery workflows. It is part of the CausalIQ ecosystem for intelligent causal discovery.

Status

🚧 Active Development - this repository is currently in active development, which involves:

• Adding new knowledge features, in particular knowledge from LLMs
• Migrating functionality which provides knowledge based on standard reference networks from the legacy monolithic discovery repo
• Ensuring CausalIQ development standards are met

Quick Start

from causaliq_knowledge.llm import LLMKnowledge

# Query an LLM about a potential causal relationship
knowledge = LLMKnowledge(models=["groq/llama-3.1-8b-instant"])
result = knowledge.query_edge("smoking", "lung_cancer")

print(f"Exists: {result.exists}, Direction: {result.direction}")
print(f"Confidence: {result.confidence}")
print(f"Reasoning: {result.reasoning}")

Features

✅ Currently implemented releases:

• v0.1.0 - Foundation LLM [January 2026]: Foundation release establishing LLM client infrastructure for causal graph generation.

• v0.2.0 - Additional LLMs [January 2026]: Expanded LLM provider support from 2 to 7 providers.

• v0.3.0 - LLM Caching [January 2026]: SQLite-based response caching with CLI tools for cache management.

• v0.4.0 - Graph Generation [February 2026]: CLI tools and CausalIQ workflows for LLM-generated causal graphs.

• v0.5.0 - Workflow Integration [February 2026]: Integration into CausalIQ Workflows including writing results to cache.

• v0.6.0 - PDG Generation [April 2026]: PDG output with separate existence and orientation probabilities, multi-sampling support, and improved LLM response handling.

🛣️ Upcoming Releases (speculative)

• Release v0.7.0 - LLM Provider Cost Tracking: Query LLM provider APIs for usage and cost statistics.

• Release v0.8.0 - Enhanced LLM Context: Background literature supplied to LLMs

• Release v0.9.0 - Legacy Reference: Support for deriving knowledge from reference networks and migration of functionality from legacy discovery repo

Implementation Approach

Technology Stack

• Vendor-Specific API Clients: Direct integration with LLM providers using httpx
• Pydantic: Structured response validation
• Click: Command-line interface

Why Vendor-Specific APIs (not LiteLLM/LangChain)?

We use direct vendor-specific API clients rather than wrapper libraries:

This approach keeps the package lightweight, reliable, and easy to debug.

Supported LLM Providers

Upcoming Key Innovations

🧠 LLMs support Causal Discovery and Inference

• Initially LLM will work with graph averaging to resolve uncertain edges (use entropy to decide edges with uncertain existence or direction)
• Integration into structure learning algorithms to provide knowledge for "uncertain" areas of the graph
• LLMs analyse learning process and errors to suggest improved algorithms
• LLMs used to preprocess text and visual data so they can be used as inputs to structure learning

🤝 Human Engagement

• Natural language constraints: Specify domain knowledge in plain English
• Expert knowledge incorporation by converting expert understanding into algorithmic constraints
• LLMs convert natural language questions to causal queries
• Interactive causal discovery where structure learning or LLMs identify areas of causal uncertainty and can test causal hypotheses through dialogue

🪟 Transparency and interpretability

• LLMs interpret structure learning process and outputs, including their uncertainties
• LLMs interpret causal inference results including uncertainties
• Contextual graph interpretation to explain variable meanings and relationships
• Uncertainty communication with clear explanation of confidence levels and limitations
• Report generation including automated research summaries and methodology descriptions

🔒 Stability and reproducibility

• Cache queries and responses so that experiments are stable and repeatable even if LLMs themselves are not
• Stable randomisation of e.g. data sub-sampling

💰 Efficient use of LLM resources (important as an independent researcher)

• Cache queries and results so that knowledge can be re-used
• Evaluation and development of simple context-adapted LLMs

Upcoming Integration with CausalIQ Ecosystem

• 🔍 CausalIQ Discovery makes use of this package to learn more accurate graphs.
• 🧪 CausalIQ Analysis uses this package to explain the learning process, intelligently combine and explain results.
• 🔮 CausalIQ Predict uses this package to explain predictions made by learnt models.

Documentation

• User Guide - Getting started
• Architecture Overview - Design and components
• LLM Integration Design - Detailed LLM design
• Roadmap - Release planning

Supported Python Versions: 3.9, 3.10, 3.11, 3.12, 3.13
Default Python Version: 3.11