Skip to content

Hypergraph is more powerful. Transform unstructured text into structured knowledge with LLMs. Graphs, hypergraphs, and spatio-temporal extractions — with one command.

feat: 更新 README 文档,添加历史文化领域及相关文档类型;扩展知识类型模块,增加行业和中医领域的初始化文件

yifanfeng971fcbc96bab75
diff --git a/hyperextract/templates/README.md b/hyperextract/templates/README.md
index 24359e6..d2cd546 100644
--- a/hyperextract/templates/README.md
+++ b/hyperextract/templates/README.md
@@ -13,9 +13,9 @@ This library is organized by **Domain**, ensuring that the extraction logic matc
| **`medicine`** | Medicine & Health | Clinical Records, Guidelines, Drug Info |
| **`tcm`** | Traditional Chinese Medicine | Case Records, Herbology, Acupuncture |
| **`industry`** | Industry | Maintenance, Safety, Operations |
+| **`history`** | History & Culture | Chronicles, Timelines, Archives |
| **`biology`** | Biological Science | Genomics, Proteomics, Ecology |
| **`legal`** | Legal & Compliance | Contracts, Judgments, Regulations |
-| **`history`** | History & Culture | Chronicles, Timelines, Archives |
| **`literature`** | Literature & Fiction | Scripts, Novels, World Building |
| **`travel`** | Travel & Geography | Itineraries, Guides, Spatial Maps |
| **`news`** | News & Media | Investigative Reports, Breaking News |
@@ -29,8 +29,8 @@ This library is organized by **Domain**, ensuring that the extraction logic matc
### 1. `general` (General Purpose)
The default choice for unstructured text that doesn't fit a specific industry.
* **Wikipedia Articles / Encyclopedias**: Comprehensive descriptions of entities with structured infobox-like attributes.
-* **Biographies**: Life stories of individuals, focusing on key life events and relationships.
-* **Company "About Us" Pages**: Corporate self-descriptions focusing on history, mission, and key personnel.
+* **Biographies & Memoirs**: Life stories of individuals, focusing on key life events and relationships.
+* **Non-fiction Books (Popular Science)**: Books that cover broad topics (e.g., "Sapiens", "Thinking, Fast and Slow") with cross-domain concepts and arguments.
### 2. `finance` (Finance)
Optimized for complex financial relationships, market sentiment, and temporal events.
@@ -41,6 +41,7 @@ Optimized for complex financial relationships, market sentiment, and temporal ev
### 3. `medicine` (Medicine)
Focuses on causality, standardized terminology (UMLS mappings), and precise relationships.
+* **Medical Textbooks & Monographs**: Systematized knowledge of anatomy, pathology, and treatment protocols (e.g., "Principles of Neural Science").
* **Clinical Practice Guidelines**: Standardized procedures for treating diseases, defining "Symptom -> Diagnosis -> Treatment" decision trees.
* **Discharge Summaries**: Narrative records of a patient's hospital stay, including admission reason, hospital course, and discharge instructions.
* **Pathology Reports**: Microscopic descriptions of tissue samples, detailing tumor grades, invasion depths, and histological features.
@@ -60,25 +61,28 @@ Focuses on unstructured operational data in manufacturing, energy, and power sec
* **Shift Handover Logs**: Summaries written by operators regarding equipment status changes, anomalies, and ongoing issues.
* **Technical Specifications / Datasheets**: Semi-structured text describing equipment parameters, design standards, and performance curves.
-### 6. `biology` (Biology)
+### 6. `history` (History)
+Heavily focused on long-span timelines and social networks.
+* **Historical Monographs**: Academic books analyzing specific eras, events, or figures with rich causal analysis and citations.
+* **Chronicles & Annals**: Year-by-year records of events, focusing on temporal sequencing and regime changes.
+* **Oral History Transcripts**: First-person narratives, often non-linear and focused on personal experiences within historical events.
+* **Archival Correspondence**: Personal exchanges revealing social networks, hidden intents, and dates of specific interactions.
+
+### 7. `biology` (Biology)
Goes beyond genomics to include proteomics, metabolism, and ecology.
+* **Biological Monographs**: Specialized books detailing species taxonomy, evolutionary history, or complex biological systems.
* **Protein Structure Summaries (PDB Headers)**: Descriptions of protein crystal structures, ligand binding sites, and post-translational modifications.
* **Metabolic Pathway Descriptions**: Texts explaining biochemical cascades, detailing enzymes, substrates, products, and regulation mechanisms.
* **Ecological Survey Reports**: Documents recording species distribution, abundance, and habitat characteristics in specific geographic areas.
* **Taxonomic Descriptions**: Detailed physical characterizations of organisms used for classification and identification.
-### 7. `legal` (Legal)
+### 8. `legal` (Legal)
Handles precise logical conditions, obligations, and citations.
+* **Legal Treatises / Commentaries**: Scholarly books analyzing legal principles, statutes, and case law logic.
* **Master Service Agreements (MSA)**: Contracts defining long-term business relationships, liability limits, and intellectual property rights.
* **Court Judgments**: Final rulings by judges, containing fact-finding sections, legal reasoning, and citations of precedents.
* **Regulatory Compliance Filings**: Detailed reports submitted to government bodies regarding data privacy, anti-money laundering, or environmental impact.
-### 8. `history` (History)
-Heavily focused on long-span timelines and social networks.
-* **Chronicles & Annals**: Year-by-year records of events, focusing on temporal sequencing and regime changes.
-* **Oral History Transcripts**: First-person narratives, often non-linear and focused on personal experiences within historical events.
-* **Archival Correspondence**: Personal exchanges revealing social networks, hidden intents, and dates of specific interactions.
-
### 9. `literature` (Literature & Fiction)
Focuses on narrative structure, character interactions, and world-building.
* **Screenplays / Scripts**: Highly structured texts (Scene Heading, Action, Dialogue) ideal for extracting character interaction graphs.
@@ -96,6 +100,7 @@ Focuses on the "5Ws" (Who, What, Where, When, Why) and causality.
* **Breaking News Wires**: Short, factual updates focusing on immediate events and entities.
### 12. `agriculture` (Agriculture)
+* **Agricultural Manuals**: Technical guides on crop management, planting standards, and pest control techniques.
* **Crop Scouting Reports**: Observations of crop growth stages, pest identification, and disease severity.
* **Soil Analysis Reports**: Textual descriptions of soil chemical properties and corresponding fertilizer recommendations.
diff --git a/hyperextract/templates/README_ZH.md b/hyperextract/templates/README_ZH.md
index d8fe84d..c6987d2 100644
--- a/hyperextract/templates/README_ZH.md
+++ b/hyperextract/templates/README_ZH.md
@@ -13,9 +13,9 @@
| **`medicine`** | 医疗健康 | 临床指南、病历、药品文档 |
| **`tcm`** | 中医中药 | 医案、本草、方剂、经络 |
| **`industry`** | 工业 | 运维日志、安全报告、技术规格 |
+| **`history`** | 历史文化 | 编年史、信札、口述历史 |
| **`biology`** | 生物科学 | 蛋白组、代谢通路、生态调查 |
| **`legal`** | 法律合规 | 合同协议、判决书、监管文件 |
-| **`history`** | 历史文化 | 编年史、信札、口述历史 |
| **`literature`** | 文学与剧情 | 剧本、小说、设定集 |
| **`travel`** | 旅游与地理 | 行程单、导览指南 |
| **`news`** | 新闻传媒 | 调查报道、突发快讯 |
@@ -26,11 +26,11 @@
## 领域详情与典型文档
-### 1. `general` (通用领域)
+### 1. `general` (General Purpose)
适用于无法归类或多领域交叉的文本,通过提取基础实体和SPO关系构建通用图谱。
* **维基百科/百度百科条目**:对实体(人物、组织、地点)的综合性描述,包含结构化的属性信息。
-* **人物传记**:记录个人生平事迹、主要成就及社会关系的叙事性文本。
-* **企业官网“关于我们”**:描述公司历史、愿景及核心团队的官方文本。
+* **人物传记与回忆录**:记录个人生平事迹、主要成就及社会关系的叙事性文本。
+* **非虚构类书籍 (大社科/科普)**:跨领域、概念性的书籍(如《人类简史》、《思考,快与慢》),侧重提取通用概念与论点。
### 2. `finance` (金融)
专注于提取复杂的交易关系、市场观点及时间敏感事件。
@@ -41,6 +41,7 @@
### 3. `medicine` (医学)
专注于疾病诊疗逻辑、标准化术语映射及因果关系提取。
+* **医学教科书与专著**:系统性阐述解剖、病理、药理及治疗原则的专业书籍(如《神经科学原理》)。
* **临床诊疗指南 (Clinical Guidelines)**:权威机构发布的标准化文档,定义了“症状-诊断-治疗-预后”的决策路径。
* **出院小结 (Discharge Summaries)**:患者住院全过程的叙述性记录,包含入院主诉、诊疗经过及出院医嘱。
* **病理报告 (Pathology Reports)**:对组织样本的微观描述,包含肿瘤分级、侵润深度及细胞学特征。
@@ -60,24 +61,28 @@
* **交接班记录 (Shift Handover)**:运行人员记录的设备状态变化、异常参数及遗留问题。
* **技术规格书 (Technical Specifications)**:描述设备额定参数、材质标准及性能曲线的半结构化文本。
-### 6. `biology` (生物科学)
+### 6. `history` (历史)
+专注于长跨度的时间线梳理及人物社会网络构建。
+* **历史专著**:对特定断代、事件或人物进行深度因果分析与考证的学术书籍。
+* **编年史 (Chronicles)**:按严格时间顺序记录的历史事件,侧重于时序演变。
+* **口述历史 (Oral History)**:亲历者的第一人称回忆录,包含非线性叙事及个人视角细节。
+* **档案馆藏信札 (Archival Correspondence)**:历史人物间的往来书信,揭示隐秘的社交网络和事件细节。
+
+### 7. `biology` (生物科学)
从单一的基因组扩展到蛋白质组学、代谢通路及生态学。
+* **生物学专著**:详述物种分类、进化历史或复杂生物系统机制的学术书籍。
* **蛋白质结构摘要 (Protein Structure Summaries)**:描述蛋白质晶体结构、配体结合位点及修饰位点的文本。
* **代谢通路描述 (Metabolic Pathways)**:解释生物化学反应级联的文本,涉及酶、底物、产物及调控机制。
* **生态调查报告 (Ecological Surveys)**:记录特定区域内物种分布、种群数量及生境特征的考察文档。
* **分类学描述 (Taxonomic Descriptions)**:对物种形态特征、鉴别要点及系统发育关系的详细记录。
-### 7. `legal` (法律)
+### 8. `legal` (法律)
专注于提取权利义务逻辑、条件约束及法律事实。
+* **法学专著与评注**:对法律原则、法条逻辑及判例法进行深度学理解析的书籍。
* **主服务协议 (MSA)**:定义长期商业合作框架的合同,包含责任限制、知识产权归属及违约条款。
* **法院判决书 (Judgments)**:法官对案件的最终裁定,包含事实认定、法律推理及判例引用。
* **合规申报文件 (Compliance Filings)**:企业提交给监管机构的关于数据合规、反洗钱或环境影响的详细陈述。
-### 8. `history` (历史)
-专注于长跨度的时间线梳理及人物社会网络构建。
-* **编年史 (Chronicles)**:按严格时间顺序记录的历史事件,侧重于时序演变。
-* **口述历史 (Oral History)**:亲历者的第一人称回忆录,包含非线性叙事及个人视角细节。
-* **档案馆藏信札 (Archival Correspondence)**:历史人物间的往来书信,揭示隐秘的社交网络和事件细节。
### 9. `literature` (文学与影视)
专注于叙事结构分析、角色互动及世界观设定。
@@ -96,6 +101,7 @@
* **突发新闻电讯 (Breaking News)**:短小精悍、注重时效性和事实要素的实时消息。
### 12. `agriculture` (农业)
+* **农业技术手册**:关于作物种植规范、田间管理标准及病虫害防治技术的指导书。
* **巡田报告 (Crop Scouting Reports)**:对作物生长阶段及病虫害情况的实地观察记录。
* **土壤分析报告 (Soil Analysis)**:描述土壤化学成分及对应施肥建议的文本。
diff --git a/hyperextract/templates/en/industry/__init__.py b/hyperextract/templates/en/industry/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/hyperextract/templates/en/tcm/__init__.py b/hyperextract/templates/en/tcm/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/hyperextract/templates/zh/industry/__init__.py b/hyperextract/templates/zh/industry/__init__.py
new file mode 100644
index 0000000..e69de29
diff --git a/hyperextract/types/__init__.py b/hyperextract/types/__init__.py
index d81883d..db9d7af 100644
--- a/hyperextract/types/__init__.py
+++ b/hyperextract/types/__init__.py
@@ -1,8 +1,49 @@
"""Types - Core data structures for automatic knowledge extraction.
-This module contains the fundamental, reusable data structure primitives that can
-automatically extract knowledge from text. These are the "building blocks" of the
-Hyper-Extract framework.
+This module exports the fundamental "AutoType" primitives of the Hyper-Extract framework.
+Each AutoType is designed to extract a specific structure of knowledge from unstructured text,
+handling the complexities of LLM interaction, text chunking, and result merging automatically.
+
+# 🚀 AutoType Selection Guide (知识类型选择指南)
+
+| Class | Structure | Core Use Case | Key Feature |
+| :--- | :--- | :--- | :--- |
+| **`AutoModel`** | Single Object | Document Summaries, Metadata | Merges all chunks into ONE consistent object |
+| **`AutoList`** | List[Item] | Event Logs, Todo Lists | Appends items from all chunks commonly |
+| **`AutoSet`** | Set[Item] | Entity Registries, Glossaries | Deduplicates items by key & merges details |
+| **`AutoGraph`** | Nodes + Edges | Social Networks, Concept Maps | Enforces structural consistency (Node-Edge) |
+| **`AutoHypergraph`** | Nodes + Hyperedges | Complex Events, Narratives | Edges connect 2+ nodes (N-ary relations) |
+| **`AutoTemporalGraph`** | Graph + Time | Timelines, History, News | Resolves relative time ("yesterday") |
+| **`AutoSpatialGraph`** | Graph + Space | Physical Spaces, 3D Mapping | Resolves relative location ("nearby") |
+| **`AutoSpatioTemporalGraph`** | Graph + Time + Space | Event Networks, Travel | Resolves both time & location context |
+
+# 📚 Detailed Scope Description
+
+## 1. Scalar & Document Types (标量与文档型)
+* **`AutoModel`**: Designed for **"One Document -> One Object"**.
+ * *Scope*: When you need to summarize a whole file into a single structure (e.g., "Research Report" with fields for summary, author, conclusion).
+ * *Logic*: It treats every text chunk as a partial view of the *same* object and uses LLM to merge them.
+
+## 2. Collection Types (集合型)
+* **`AutoList`**: Designed for **"Many Independent Items"**.
+ * *Scope*: Extracting simple lists where duplicates might be acceptable or order matters (e.g., extraction of all "Key Quotes" in a text).
+* **`AutoSet`**: Designed for **"Unique Entity Collection"**.
+ * *Scope*: When you need a deduplicated registry (e.g., "RPG Monster Manual").
+ * *Logic*: You define a unique key (e.g., monster name). If the same monster appears in chunk 1 and chunk 10, `AutoSet` intelligently merges their attributes.
+
+## 3. Graph Types (图谱型)
+* **`AutoGraph`**: Standard pairwise knowledge graph.
+ * *Scope*: Modeling relationships between two entities (Source -> Target). Great for standard Knowledge Graphs.
+* **`AutoHypergraph`**: For higher-order relationships.
+ * *Scope*: When a "relationship" involves a group (e.g., "Meeting" involves A, B, and C).
+
+## 4. Context-Aware Graphs (时空感知型)
+These types inject "Observation Context" (Current Time/Location) into the LLM prompt.
+* **`AutoTemporalGraph`**: For time-sensitive extraction.
+ * *Scope*: Analyzing news or logs where "current time" matters for resolving relative dates.
+* **`AutoSpatialGraph`**: For location-sensitive extraction.
+ * *Scope*: Analyzing descriptions of physical environments relative to an observer.
+* **`AutoSpatioTemporalGraph`**: The combination of both above.
"""
from .base import BaseAutoType