disk-kg 1.0.0__tar.gz

disk_kg-1.0.0/.gitignore

@@ -0,0 +1,23 @@
+# env
+.venv/
+.claude/
+.env
+
+# data
+datasets/
+
+# cache
+__pycache__/
+
+# config
+config/config.py
+config.toml
+
+# logs
+logs/
+
+# results
+results/
+
+# checkpoints
+checkpoints/

disk_kg-1.0.0/CLAUDE.md

@@ -0,0 +1,2 @@
+- 使用uv执行python脚本
+- 代码风格参考现有代码

disk_kg-1.0.0/NEO4J_GUIDE.md

@@ -0,0 +1,10 @@
+## cypher
+1. 查看所有实体和关系
+```
+MATCH (a)-[r]->(b) RETURN a, r, b
+```
+
+2. 删除所有实体和关系
+```
+MATCH (n) DETACH DELETE n
+```

disk_kg-1.0.0/OPT_ANALYSIS.md

@@ -0,0 +1,96 @@
+# DISK 项目：最小知识原则（迪米特法则）违反情况分析报告
+
+本文档基于对 `DISK` 项目核心模块（`disk.py`, `extractor/`, `merger/`, `manager/`, `models/`）的代码审计，指出其中违反**最小知识原则（Least Knowledge Principle / Law of Demeter）**的设计缺陷，并提出改进建议。
+
+---
+
+## 核心原则定义
+**最小知识原则（迪米特法则）**：一个软件实体应当尽可能少地与其他实体发生相互作用。即：只与你的直接朋友交谈，不跟“陌生人的朋友”说话。
+
+---
+
+## 1. 穿透访问内部属性（火车残骸现象）
+
+### 表现地点：`extractor/extractor.py`
+**代码示例：**
+```python
+# Extractor 类中直接访问了 Parser 内部的 embeddings 对象
+self.parser.embeddings.embed_query(entity["name"])
+```
+*   **分析：** `Extractor` 实例持有 `Parser`，而 `Parser` 持有 `embeddings`。`Extractor` 越过 `Parser` 直接操作其内部构件。
+*   **违反原因：** `Extractor` 知道了它不该知道的秘密——`Parser` 是如何实现向量化的。
+*   **后果：** 如果 `Parser` 未来更换了向量化方式（例如改为调用 REST API 而不再持有 `embeddings` 对象），`Extractor` 必须跟着修改代码。
+
+### 表现地点：`disk.py`
+**代码示例：**
+```python
+# DISK 类通过 manager 访问 kg 实例，再访问其内部的列表
+all_entities = self.kg_manager.kg.entities
+```
+*   **分析：** 典型的“火车残骸”式调用：`A -> B -> C -> D`。
+*   **改进建议：** `KGManager` 应提供 `get_all_entities()` 方法，隐藏 `KnowledgeGraph` 的内部结构。
+
+---
+
+## 2. 外部直接干预对象状态
+
+### 表现地点：`disk.py`
+**代码示例：**
+```python
+# DISK 主类直接修改了抽取器的内部属性
+self.entities_extractor.prompts = prompts
+self.relations_extractor.prompts = prompts
+self.extractor.prompts = prompts
+```
+*   **分析：** `DISK` 类在检测到语言后，直接覆盖了 `Extractor` 实例的成员变量。
+*   **违反原因：** 它假设了 `Extractor` 内部一定有一个名为 `prompts` 的属性，这破坏了封装性。
+*   **改进建议：** 应该在 `Extractor` 中定义 `update_language_config(prompts)` 方法。
+
+---
+
+## 3. 逻辑职责分配不当（上帝类倾向）
+
+### 表现地点：`merger/merger.py`
+**代码示例：**
+```python
+# Merger 手动拼凑新的 Entity 对象，深入了解其所有字段
+merged_entity = Entity(
+    name=e1.name,
+    label=e1.label,
+    embedding=emb1[idx1].tolist(),
+    description=e1.description if hasattr(e1, 'description') else "",
+)
+```
+*   **分析：** `Merger` 类作为一个工具类，却对 `Entity` 的构造函数、属性名（`description`）、甚至向量的转换细节（`tolist()`）了如指掌。
+*   **违反原因：** `Merger` 知道得太多了。它不仅知道如何合并，还知道如何“制造”实体。
+*   **改进建议：** 应该在 `Entity` 类中实现 `merge_with(other)` 方法。
+
+---
+
+## 4. 领域模型与持久化层的深度耦合
+
+### 表现地点：`models/neo4j_connector.py`
+**代码示例：**
+```python
+# 连接器深入读取实体的每一个字段来构建 Cypher 查询
+parameters = {
+    "name": entity.name, 
+    "embedding": entity.embedding, 
+    "description": entity.description if hasattr(entity, 'description') else ""
+}
+```
+*   **分析：** 数据库连接器应该只负责执行查询。目前它必须了解 `Entity` 所有的属性名称。
+*   **后果：** 只要 `Entity` 增加或修改一个字段（例如把 `name` 改为 `display_name`），连接器就会崩溃。
+*   **改进建议：** `Entity` 应该提供一个 `to_dict()` 方法，连接器只负责消费这个字典。
+
+---
+
+## 总结与改进方案
+
+项目目前的实现风格偏向于**过程式拼装**，类更像是带方法的“数据结构”。
+
+### 改进路线图：
+1.  **封装委派**：在 `Parser` 中提供 `embed(text)` 接口，禁止外部直接访问 `self.embeddings`。
+2.  **隐藏内部结构**：`KGManager` 应该作为 `KnowledgeGraph` 的唯一出口，禁止外部通过 `.kg` 属性进行链式访问。
+3.  **行为下移**：将属性合并、对象克隆、序列化等逻辑从 `Merger` 和 `Connector` 中移回 `Entity` 和 `Relation` 类中。
+4.  **接口契约**：使用方法调用代替直接属性赋值，确保对象内部状态的安全性。

disk_kg-1.0.0/PKG-INFO

@@ -0,0 +1,293 @@
+Metadata-Version: 2.4
+Name: disk-kg
+Version: 1.0.0
+Summary: DISK (Domain Incremental conStruction of Knowledge graph) - A tool for distilling text from documents, extracting entities and relations, and building domain knowledge graphs
+Author-email: Liu Huasheng <clipg@qq.com>, Wu Junkai <wu.junkai@qq.com>
+License: MIT
+Keywords: entity-extraction,knowledge-graph,llm,nlp,pdf-processing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: docx2txt>=0.9
+Requires-Dist: jieba
+Requires-Dist: langchain-community>=0.4.1
+Requires-Dist: langchain-core
+Requires-Dist: langchain-openai>=1.1.7
+Requires-Dist: neo4j
+Requires-Dist: numpy
+Requires-Dist: openai>=2.21.0
+Requires-Dist: pandas
+Requires-Dist: pdfplumber
+Requires-Dist: pillow
+Requires-Dist: pymupdf
+Requires-Dist: rapidocr-onnxruntime>=1.4.4
+Requires-Dist: tqdm
+Provides-Extra: dev
+Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: ipykernel>=6.0.0; extra == 'dev'
+Requires-Dist: jupyter>=1.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# DISK
+Domain Incremental conStruction of Knowledge graph.
+
+## Overview
+
+DISK is a comprehensive toolkit for extracting knowledge from PDF documents and building domain knowledge graphs through text distillation, entity/relation extraction, and semantic merging. The system provides a modular pipeline that transforms unstructured PDF documents into structured knowledge representations.
+
+### Core Capabilities
+
+- **Document Distillation**: Extract and validate text blocks, tables, and images from PDF documents
+- **Entity Extraction**: Identify and extract domain entities with semantic embeddings
+- **Relation Extraction**: Discover relationships between entities with contextual understanding
+- **Knowledge Graph Construction**: Build and manage knowledge graphs with incremental updates
+- **Semantic Merging**: Intelligently merge similar entities and relations using cosine similarity
+
+## Architecture
+
+### System Architecture
+
+```mermaid
+graph TB
+    subgraph "Input Layer"
+        PDF[PDF Document]
+    end
+
+    subgraph "Distillation Layer"
+        Distiller[PDF Distiller]
+        TextBlocks[Validated Text Blocks]
+    end
+
+    subgraph "Extraction Layer"
+        EntExtractor[Entity Extractor]
+        RelExtractor[Relation Extractor]
+        UnifiedExtractor[Unified Extractor]
+        Entities[(Entities + Embeddings)]
+        Relations[(Relations + Embeddings)]
+    end
+
+    subgraph "Processing Layer"
+        Merger[Semantic Merger]
+        Manager[KG Manager]
+    end
+
+    subgraph "Output Layer"
+        KG[Knowledge Graph]
+        Logs[Logs & Results]
+    end
+
+    subgraph "Configuration"
+        Config[LLM Config]
+        Embed[Embeddings Model]
+    end
+
+    PDF --> Distiller
+    Distiller --> TextBlocks
+
+    TextBlocks --> EntExtractor
+    TextBlocks --> RelExtractor
+    TextBlocks --> UnifiedExtractor
+
+    EntExtractor --> Entities
+    RelExtractor --> Relations
+    UnifiedExtractor --> Entities
+    UnifiedExtractor --> Relations
+
+    Entities --> Merger
+    Relations --> Merger
+    Merger --> Manager
+
+    Manager --> KG
+    Manager --> Logs
+
+    Config --> EntExtractor
+    Config --> RelExtractor
+    Config --> UnifiedExtractor
+    Embed --> EntExtractor
+    Embed --> RelExtractor
+    Embed --> UnifiedExtractor
+    Embed --> Merger
+
+    style PDF fill:#e1f5fe
+    style KG fill:#c8e6c9
+    style Distiller fill:#fff3e0
+    style Merger fill:#f3e5f5
+    style Manager fill:#e8f5e9
+```
+
+### Module Structure
+
+```mermaid
+graph LR
+    subgraph DISK
+        DiskMain[disk.py<br/>Main Entry Point]
+
+        subgraph Core
+            Distiller[distiller/<br/>PDF Distillation]
+            Extractor[extractor/<br/>Information Extraction]
+            MergerMod[merger/<br/>Knowledge Merging]
+            ManagerMod[manager/<br/>KG Management]
+        end
+
+        subgraph Support
+            Models[models/<br/>Data Models]
+            Utils[utils/<br/>Utilities]
+            ConfigMod[config/<br/>Configuration]
+        end
+    end
+
+    DiskMain --> Distiller
+    DiskMain --> Extractor
+    DiskMain --> MergerMod
+    DiskMain --> ManagerMod
+
+    Extractor --> Models
+    MergerMod --> Models
+    ManagerMod --> Models
+
+    Distiller --> Utils
+    Extractor --> Utils
+    ManagerMod --> Utils
+
+    DiskMain --> ConfigMod
+
+    style DiskMain fill:#1976d2,color:#fff
+    style Distiller fill:#ffa726
+    style Extractor fill:#42a5f5
+    style MergerMod fill:#ab47bc
+    style ManagerMod fill:#66bb6a
+```
+
+### Data Flow
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant DISK
+    participant Distiller
+    participant Extractor
+    participant Merger
+    participant Manager
+    participant KG
+
+    User->>DISK: build_knowledge_graph(pdf_path)
+    DISK->>Distiller: extract_text_blocks(pdf)
+    Distiller-->>DISK: validated_text_blocks
+
+    loop For each text block
+        DISK->>Extractor: extract_entities(text)
+        Extractor-->>DISK: entities + embeddings
+
+        DISK->>Extractor: extract_relations(text)
+        Extractor-->>DISK: relations + embeddings
+
+        DISK->>Merger: merge(new, existing)
+        Merger-->>DISK: merged entities/relations
+    end
+
+    DISK->>Manager: add_entities(entities)
+    DISK->>Manager: add_relations(relations)
+    Manager->>KG: update_knowledge_graph
+    DISK-->>User: Knowledge Graph
+```
+
+## Modules
+
+### Distillation Module (distiller/)
+
+- **pdf_distiller**
+    - extract **paragraphs** with intelligent validation
+    - extract **tables**(to be improved)
+    - extract **imgs**(to be improved)
+    - filter out low-quality text blocks (references, incomplete sentences)
+
+### Extraction Module (extractor/)
+
+- **entities_extractor**
+    - extract domain entities with labels and descriptions
+    - generate semantic embeddings for each entity
+
+- **relations_extractor**
+    - extract relationships between entities
+    - generate semantic embeddings for each relation
+
+- **extractor** (unified)
+    - extract both entities and relations in a single pass
+    - optimized for incremental processing
+
+### Processing Modules
+
+- **extract entities**
+- **extract relationships**
+- **semantic merging** (merger/)
+    - merge similar entities using cosine similarity
+    - update relations after entity merging
+    - configurable threshold (default: 0.8)
+- **construct knowledge graph** (manager/)
+    - incremental knowledge graph construction
+    - deduplication of entities and relations
+
+## Config
+
+**env**
+```bash
+# use uv to manage the environment
+uv venv
+uv sync
+```
+
+**LLM Configuration**
+
+1. Copy the example configuration file:
+```bash
+cp config.example.toml config.toml
+```
+
+2. Edit `config.toml` to set your API keys and preferences:
+
+```toml
+[disk]
+llm = "openai"  # Choose provider: openai, qwen, ollama, etc.
+
+[disk.embeddings]
+model = "text-embedding-3-small"
+api_key = "ai-..."
+api_url = "https://api.openai.com/v1"
+
+[model.openai]
+api_url = "https://api.openai.com/v1"
+api_key = "ai-..."
+model = "gpt-4o"
+
+[model.other]
+api_url = "https://api.otherprovider.com/v1"
+api_key = "sk-..."
+model = "gpt-4o"
+```
+
+3. Supported providers:
+   - **OpenAI** (default)
+   - **Qwen** (DashScope)
+   - **Kimi** (Moonshot)
+   - **Ollama** (Local)
+   - **All other providers** that support OpenAI-compatible APIs
+
+You can switch providers by changing the `llm` field in `[disk]` or using the runtime `switch()` function.
+
+
+## Contrast
+
+### merge
+- itext2kg
+```
+[INFO] Wohoo! Entity was matched --- [poor deep semantic understanding in traditional ie models:Limitation] --merged--> [cosine similarity ignores deep semantic differences:Limitation]
+```

disk_kg-1.0.0/PROJECT_OVERVIEW.md

@@ -0,0 +1,99 @@
+**项目概述**
+
+- **名称**: DISK
+- **简介**: DISK（Domain Incremental conStruction of Knowledge graph）是一个从文档（当前以 PDF 为主）中蒸馏文本、抽取实体与关系、构建并合并领域知识图谱的工具集。项目通过将 PDF 文本块提取、调用 LLM 进行结构化信息抽取、对实体关系做向量化并合并近似实体，逐步构建知识图谱。
+
+**设计目标**
+
+- **可扩展的文档蒸馏**: 支持从 PDF 提取段落、表格和图片（含 OCR）的功能模块。
+- **基于 LLM 的信息抽取**: 使用可替换的 LLM 与向量化接口完成实体与关系抽取以及嵌入生成。
+- **语义合并与知识管理**: 提供实体/关系合并策略及知识图（KG）管理接口，便于增量构建与持久化。
+
+**架构概览**
+
+- **输入**: PDF 文档
+- **阶段**: 蒸馏（distiller） -> 抽取（extractor） -> 合并（merger） -> 管理/构建（manager/models）
+- **输出**: `KnowledgeGraph` 实例（包含 `Entity` 与 `Relation`）
+
+**主要文件与模块说明**
+
+- **`disk.py`**: 
+  - **作用**: 提供 `DISK` 类作为主流程控制器，封装整个构建知识图的流水线。
+  - **关键方法**: `build_knowledge_graph`（分步：蒸馏 -> 抽实体 -> 抽关系 -> 构建 KG），`build_knowledge_graph_single_extractor`（用单一抽取器同时抽实体与关系并合并）。
+
+- **`distiller/pdf_distiller.py` (`PDFDistiller`)**:
+  - **作用**: 使用 `PyMuPDF`（fitz）、`pdfplumber`、`PaddleOCR` 等从 PDF 中提取文本块、表格与图片+OCR。
+  - **特点**: 将页面文本分块为「段落」，内置基本筛选（去除参考文献、短文本、非句子等）；提供表格与图片提取的多种策略与 TODO 优化点。
+
+- **`extractor/`**:
+  - **`extractor.py` (`Extractor`)**: 调用 `Parser`（基于 LangChain 风格）并使用预设 prompt（`utils.prompts.EXTRACT_PROMPT`）把文本解析为结构化 JSON（`RelationsSchema` / `EntitiesSchema`），随后为实体/关系生成 embedding 并返回嵌入化对象列表。
+  - 项目里还有拆分的 `EntitiesExtractor` 与 `RelationsExtractor`（在导入点可见），用于分别提取实体或关系以支持分步流水线。
+
+- **`merger/merger.py` (`Merger`)**:
+  - **作用**: 基于实体 embedding 的余弦相似度（PyTorch 实现）合并相近实体，并在合并后更新/合并关系集合。
+  - **阈值**: 可配置 `threshold`（默认 0.8），日志会输出相似度矩阵与合并信息到 `logs/` 目录。
+
+- **`manager/kg_manager.py` (`KGManager`)**:
+  - **作用**: 管理 `KnowledgeGraph` 实例，提供 `add_entities` 与 `add_relations` 等增量写入接口（包含去重逻辑）。
+
+- **`models/knowledge_graph.py`**:
+  - **核心类**: `Entity`（`label`, `name`, `embedding`）、`Relation`（`start_entity`, `end_entity`, `label`, `name`, `embedding`）、`KnowledgeGraph`（保存实体/关系列表）。
+
+- **`config/llm.py`**:
+  - **作用**: 提供默认 LLM 与 embeddings 的配置（示例中使用 Qwen via `ChatTongyi` 与 `DashScopeEmbeddings`），并示范如何替换为 Ollama/本地模型。
+  - **备注**: 真实使用前请在 `config/config.py`（或 `config/config.py` 中的 `api_key`）中配置 API key。
+
+- **`utils/parser.py`**:
+  - **作用**: 封装基于 LangChain 风格的 `JsonOutputParser` 与 `PromptTemplate`，将 LLM 的输出解析为 Pydantic 结构化对象。
+
+- **其他工具**:
+  - `utils/checkpoint_helper.py`: 用于保存与加载处理状态（代码中 `load_checkpoint` / `save_checkpoint` 被 `disk.py` 用于断点恢复）。
+  - `utils/prompts.py`、`utils/schemas.py`: 定义 prompt 模板与 pydantic 输出 schema，用于约束 LLM 输出格式。
+
+**运行与安装**
+
+- **环境**: 推荐 Python 3.10
+- **创建虚拟环境与安装依赖** (在 PowerShell 中运行):
+
+```powershell
+python -m venv .venv
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process; .\.venv\Scripts\Activate.ps1
+pip install -r requirements.txt
+```
+
+- **配置 LLM API key**:
+  - 编辑 `config/config.py` （或 `config/config.py` 中的 `api_key`）来填入你的 API Key。
+
+- **示例：用 `DISK` 构建知识图** (Python 交互或脚本):
+
+```python
+from disk import DISK
+from config.llm import llm, embeddings
+
+disk = DISK(llm=llm, embeddings=embeddings)
+kg = disk.build_knowledge_graph("path/to/your.pdf")
+print(len(kg.entities), len(kg.relations))
+```
+
+**测试与示例**
+
+- 仓库 `tests/` 下包含若干 Notebook 示例（`test_build_kg.ipynb`、`test_extractor.ipynb` 等），可作为快速上手的示例流程。
+
+**日志与结果目录**
+
+- 提取与合并过程会向 `../logs/` 写入诊断信息（相似度矩阵、提取段落、合并记录等）；提取输出也会追加到 `../results/`（`extracted_relations.json`/`extracted_entities.json`）。
+
+**扩展点与注意事项**
+
+- OCR、表格识别与多语言支持仍有优化空间（代码中标注了多处 TODO）。
+- 当前实体合并基于 embedding 的余弦阈值，可能需要更复杂的语义/规则合并策略以减少误合并。
+- LLM 调用和提示（`utils/prompts.py`）是抽取质量的关键，建议结合领域示例进一步工程化 prompt 与 schema。
+
+**下一步建议**
+
+- 添加单元测试覆盖关键模块（`distiller`、`extractor`、`merger`）以便回归检测。
+- 提供一个简单的 CLI 或示例脚本，用于批量处理 PDF 并导出 KG（如 JSON/GraphML）。
+
+---
+
+文档已生成：`PROJECT_OVERVIEW.md`（位于仓库根目录）。如需我把这些更改提交到 git、或补充具体示例/图示（比如架构流程图），我可以继续操作。