Metadata-Version: 2.4
Name: causal-engine
Version: 3.3.0
Summary: Causal Inference Engine - causal reasoning SDK for games, history, law, and beyond
Author: TeryR
License: MIT
Project-URL: Repository, https://github.com/TeryR/causal-engine
Keywords: causal-inference,knowledge-graph,causality,reasoning-engine
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: networkx>=3.0
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: psycopg2-binary>=2.9
Requires-Dist: pg8000>=1.30
Requires-Dist: dependency-injector>=4.40
Requires-Dist: click>=8.0
Requires-Dist: requests>=2.28
Requires-Dist: fastapi>=0.100
Requires-Dist: uvicorn[standard]>=0.24
Requires-Dist: pydantic>=2.0
Requires-Dist: httpx>=0.24
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"

# 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（已有历史数据）**

```python
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+）**

```python
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 索引，支持语义相似度搜索：

```python
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. 启动数据库

```bash
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. 使用因果引擎

```python
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. 导入知识

```bash
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 |

---

## 文档

- [架构文档](docs/ARCHITECTURE.md) — 系统架构详细说明
- [项目总览](PROJECT_OVERVIEW.md) — 完整项目信息
- [开发者指南](docs/DEVELOPER_GUIDE.md) — 开发和测试
- [部署指南](docs/DEPLOYMENT_GUIDE.md) — 生产环境部署
- [知识 API](docs/KNOWLEDGE_API.md) — 知识查询接口
- [搜索功能](docs/SEARCH_FEATURE_GUIDE.md) — 语义搜索使用
