causal-engine 3.3.0

Causal Inference Engine - causal reasoning SDK for games, history, law, and beyond

Generic Causal Architecture

通用因果推断引擎 — 从任意文本中提取因果知识，进行链式推理和隐含关系发现。

古籍、哲学、经济学、法律文书... 任何文本都是燃料，引擎本身是通用的。

---

核心数据（当前数据源：166 部古籍）

指标	数值
数据源	166 部古籍（当前），可扩展至任意文本
知识条目	19,908 条
统一实体	18,573 个
实体关系	8,522 条
传递性发现	1,872 条（含 106 条跨文本）
嵌入维度	1024 维（BGE-large-zh-v1.5）

---

核心能力

1. 知识提取与对齐

从任意文本中提取因果关系，并通过语义相似度进行实体对齐：

任意文本 → LLM 提取 → 知识条目(19,908) → 实体对齐(18,573) → 关系增强(8,522)

• 支持 causes / enables / correlates / prevents 四种关系类型
• 实体对齐：名称分组 + 嵌入相似度（≥0.80 自动合并）
• 关系增强：知识级→实体级，去重 + 置信度聚合

2. 因果链式推理

在实体关系图上进行传递性推理，发现隐含因果关系：

方式一：PostgreSQL（已有历史数据）

from generic_causal_architecture.core import CausalEngine
from generic_causal_architecture.storage import PostgreSQLStorage

storage = PostgreSQLStorage("postgresql://postgres:causal_password@localhost:5432/causal_db")
storage.initialize()

engine = CausalEngine(storage)  # KG Reasoner 自动加载

# 追踪因果链
chains = engine.trace_chain("格物", direction="forward", max_depth=4)
# → 格物 → 致知 → 诚意 → 知行合一 (conf=0.680)

# 查找两个概念间的路径
paths = engine.find_chain_between("心即理", "致良知")
# → 心即理 → 知行合一 → 致良知 (conf=0.810)

# 批量发现隐含关系
discovered = engine.discover_relations(min_confidence=0.55)
# → 1872 条隐含因果，106 条跨典籍

方式二：MemoryStorage（无需数据库，v3.3.0+）

from generic_causal_architecture.core import CausalEngine
from generic_causal_architecture.storage import MemoryStorage

storage = MemoryStorage()
storage.initialize()

# 加载规则数据（从 PostgreSQL 导出的 JSON）
storage.load_rules("data/causal_rules.json")

engine = CausalEngine(storage)
engine.enable_kg_reasoner()  # 手动加载 KG Reasoner

# 因果链追踪（与 PostgreSQL 方式相同）
chains = engine.trace_chain("商鞅变法", direction="forward", max_depth=4)

3. 七步因果检验

CausalEngine 内置严格的因果推断流程：

1. 时序检查 — 原因必须在结果之前
2. 必要性检查 — 没有原因，结果是否还会发生
3. 充分性检查 — 有原因，结果是否一定发生
4. 直接性检查 — 是否有中间事件
5. 混杂因素检查 — 是否有共同原因
6. 证据强度检查 — 证据是否充分
7. 机制解释检查 — 是否有合理机制

4. 语义搜索

基于 pgvector 的 1024 维嵌入 + HNSW 索引，支持语义相似度搜索：

results = storage.semantic_search("修身治国", top_k=10)

---

系统架构

┌──────────────────────────────────────────────────────────┐
│                     CausalEngine                         │
│  ┌─────────────────┐  ┌──────────────────────────────┐  │
│  │  七步因果检验     │  │  KnowledgeGraphReasoner      │  │
│  │  (两事件推断)     │  │  (链式推理 + 传递性发现)      │  │
│  └─────────────────┘  └──────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘
                            │
┌──────────────────────────────────────────────────────────┐
│                  数据层 (PostgreSQL)                      │
│  ┌────────────┐ ┌─────────────┐ ┌─────────────────────┐ │
│  │ knowledge  │ │ unified_    │ │ entity_relations    │ │
│  │ 19,908 条  │ │ entities    │ │ 8,522 条            │ │
│  │ +1024d emb │ │ 18,573 个   │ │ (4 种关系类型)       │ │
│  └────────────┘ └─────────────┘ └─────────────────────┘ │
└──────────────────────────────────────────────────────────┘

数据处理流水线

任意文本 (当前: 166部古籍)
    │
    ▼  LLM 提取 (DeepSeek / SiliconFlow)
knowledge 表 (19,908 条, 含 1024d 嵌入)
    │
    ▼  实体对齐 (名称分组 + 嵌入相似度)
unified_entities 表 (18,573 个)
    │
    ▼  关系增强 (知识级→实体级, 置信度聚合)
entity_relations 表 (8,522 条)
    │
    ▼  KG Reasoner (链式推理)
隐含关系发现 (1,872 条)

---

模块结构

generic_causal_architecture/
├── core/                          # 核心引擎
│   ├── causal_engine.py           # 因果推断引擎 (七步检验 + KG Reasoner)
│   └── kg_reasoner.py             # 知识图谱链式推理器
│
├── storage/                       # 存储层
│   ├── storage_interface.py       # 抽象接口 (EventData, CausalRelation)
│   ├── postgresql_storage.py      # PostgreSQL + Apache AGE + pgvector
│   ├── sqlite_storage.py          # SQLite (测试用)
│   └── memory_storage.py          # 内存 (测试用)
│
├── adapters/                      # 领域适配器
│   ├── domain_adapter.py          # 抽象基类
│   ├── history_adapter.py         # 历史领域
│   └── natural_science_adapter.py # 自然科学领域
│
├── methods/                       # 方法论
│   ├── lancet_method.py           # 柳叶刀方法 (分层任务分解)
│   └── iterative_workflow.py      # 迭代工作流
│
├── llm/                           # LLM 集成
│   ├── provider.py                # 抽象 Provider
│   └── providers/                 # OpenAI / Claude / Ollama
│
├── knowledge/                     # 知识管理
│   ├── models.py                  # KnowledgeUnit, Theory, Method, Concept
│   ├── extractor.py               # 知识提取器
│   ├── built_in.py                # 内置知识库
│   └── updater.py                 # 知识更新器
│
├── books/                         # 古籍文献管理
│   ├── models.py                  # Book, BookSection
│   ├── postgresql_storage.py      # PostgreSQL 存储
│   └── manager.py                 # BookManager
│
├── graph/                         # 因果图
│   └── causal_graph.py            # Apache AGE 图管理
│
├── simulation/                    # 模拟
│   └── multi_agent_simulator.py   # 多 Agent 模拟器 (骨架)
│
├── integrations/                  # 第三方集成
│   ├── langextract_integration.py # LangExtract
│   └── mirofish_integration.py    # MiroFish
│
├── api/                           # Web API
│   └── main.py                    # FastAPI 应用
│
├── config/                        # 配置
│   └── config.py
│
└── orchestrator.py                # LLM 编排器

---

快速开始

1. 启动数据库

docker run -d --name causal-postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_PASSWORD=causal_password \
  -e POSTGRES_DB=causal_db \
  -p 5432:5432 \
  apache/age:latest

2. 使用因果引擎

from generic_causal_architecture.core import CausalEngine
from generic_causal_architecture.storage import PostgreSQLStorage

storage = PostgreSQLStorage("postgresql://postgres:causal_password@localhost:5432/causal_db")
storage.initialize()

engine = CausalEngine(storage)

# KG Reasoner 已自动加载
stats = engine.get_stats()
print(stats)  # kg_nodes: 18573, kg_edges: 8522

# 因果链追踪
chains = engine.trace_chain("道", direction="forward", max_depth=3)

# 隐含关系发现
discovered = engine.discover_relations(min_confidence=0.60)

3. 导入知识

python scripts/extract_knowledge.py --input docs/示例_论语结构化.json
python scripts/import_knowledge.py --source shiji-kb

---

技术栈

组件	技术
数据库	PostgreSQL + Apache AGE + pgvector
嵌入模型	BGE-large-zh-v1.5 (1024维)
LLM	DeepSeek / SiliconFlow / OpenAI / Claude / Ollama
图查询	Cypher (Apache AGE)
向量搜索	HNSW 索引
Web API	FastAPI
连接池	SQLAlchemy

---

文档

• 架构文档 — 系统架构详细说明
• 项目总览 — 完整项目信息
• 开发者指南 — 开发和测试
• 部署指南 — 生产环境部署
• 知识 API — 知识查询接口
• 搜索功能 — 语义搜索使用