Skip to content

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

refactor(文件结构): 重构示例文件和参考文档的组织结构

yifanfeng975f588b5ae653
diff --git a/hyperextract-skills/README.md b/hyperextract-skills/README.md
index be2ccf0..9cd5b1d 100644
--- a/hyperextract-skills/README.md
+++ b/hyperextract-skills/README.md
@@ -85,22 +85,34 @@ hyperextract-skills/
├── brainstorm/
│ └── SKILL.md # Requirements exploration
├── record-designer/
-│ └── SKILL.md # Record type design
+│ ├── SKILL.md # Record type design
+│ ├── cases/ # Example templates (YAML)
+│ │ ├── earnings-summary.yaml
+│ │ ├── product-features.yaml
+│ │ └── entity-registry.yaml
+│ └── references/ # Design patterns
+│ ├── field.md
+│ └── identifier.md
├── graph-designer/
-│ └── SKILL.md # Graph type design
+│ ├── SKILL.md # Graph type design
+│ ├── cases/ # Example templates (YAML)
+│ │ ├── corporate-ownership.yaml
+│ │ ├── battle-analysis.yaml
+│ │ └── meeting-records.yaml
+│ └── references/ # Design patterns
+│ ├── entity.md
+│ ├── relation.md
+│ ├── hypergraph.md
+│ └── dimensions.md
├── yaml-validator/
-│ └── SKILL.md # YAML validation
-├── multilingual/
-│ └── SKILL.md # Multi-language conversion
-└── examples/ # Example templates
- ├── model/
- ├── list/
- ├── set/
- ├── graph/
- ├── hypergraph/
- ├── temporal_graph/
- ├── spatial_graph/
- └── spatio_temporal_graph/
+│ ├── SKILL.md # YAML validation
+│ └── references/ # Validation rules
+│ ├── rules-syntax.md
+│ ├── rules-types.md
+│ ├── rules-identifiers.md
+│ └── rules-errors.md
+└── multilingual/
+ └── SKILL.md # Multi-language conversion
```
## License
diff --git a/hyperextract-skills/examples/graph/knowledge_graph.yaml b/hyperextract-skills/examples/graph/knowledge_graph.yaml
deleted file mode 100644
index 150ff0b..0000000
--- a/hyperextract-skills/examples/graph/knowledge_graph.yaml
+++ /dev/null
@@ -1,68 +0,0 @@
-language: zh
-name: knowledge_graph
-type: graph
-tags: [general]
-description: '通用知识图谱模板 - 从非结构化文本中提取关键实体、实体类型及实体之间的显式关系,适用于新闻、百科、制度和说明类文本的基础结构化建模。'
-
-output:
- description: '由实体节点和关系边组成的通用知识图谱结果,用于表达文本中的核心对象及其语义连接。'
- entities:
- description: '文本中可独立识别、可作为关系端点的实体节点。'
- fields:
- - name: name
- type: str
- description: '实体在文本中的标准称呼或最稳定名称。'
- - name: type
- type: str
- description: '实体类别,如人物、地点、组织、物品、概念、事件、制度、技术等。'
- - name: description
- type: str
- description: '对实体身份、含义或在当前文本中作用的简要说明。'
- required: false
- relations:
- description: '实体之间的显式语义关系边。'
- fields:
- - name: source
- type: str
- description: '关系起点实体,必须对应已提取实体的 name。'
- - name: target
- type: str
- description: '关系终点实体,必须对应已提取实体的 name。'
- - name: type
- type: str
- description: '关系类型,应使用简洁明确的语义词,如包含、属于、合作、影响、导致、相关等。'
- - name: description
- type: str
- description: '对关系依据、方向或上下文含义的简要说明。'
- required: false
-
-guideline:
- target:
- zh: '你是一位知识抽取与知识图谱构建专家。请基于给定文本识别关键实体,并构建仅由这些实体组成的二元关系图。'
- rules_for_entities:
- zh:
- - '提取对理解文本事实、结构或逻辑有价值的实体,避免无意义的泛称和临时短语。'
- - 'name 使用原文中最明确、最稳定的称呼;同一实体在全文中保持命名一致。'
- - 'type 需概括实体类别,可使用人物、地点、组织、物品、概念、事件、制度、技术等标签。'
- - 'description 用 1 句话概括实体的身份、属性或在文本中的作用;若信息不足可留空。'
- rules_for_relations:
- zh:
- - '仅在文本明确表达两个实体之间存在语义联系时创建关系,不要凭常识补充隐含关系。'
- - 'source 和 target 必须直接引用已提取实体的 name,不能新造实体名称。'
- - 'type 使用简洁、方向清晰的关系词,如包含、属于、相关、影响、合作、竞争、导致、位于、使用等。'
- - 'description 简要说明关系依据、作用方式或上下文;若文本没有额外信息可留空。'
- - '避免重复关系;若同一对实体存在多种不同关系,可分别记录。'
-
-identifiers:
- entity_id: name
- relation_id: '{source}|{target}'
- relation_members:
- source: source
- target: target
-
-options:
- extraction_mode: two_stage
-
-display:
- entity_label: '{name} ({type})'
- relation_label: '{type}'
diff --git a/hyperextract-skills/examples/hypergraph/compliance_logic.yaml b/hyperextract-skills/examples/hypergraph/compliance_logic.yaml
deleted file mode 100644
index 047c6f2..0000000
--- a/hyperextract-skills/examples/hypergraph/compliance_logic.yaml
+++ /dev/null
@@ -1,117 +0,0 @@
-language: zh
-name: compliance_logic
-type: hypergraph
-tags: [general]
-description:
- zh: '规定条文超图 - 面向制度、细则、办法、规范、指引、规程等规定类文本,提取条文中涉及的名词性要素,并用 action 概括这些要素之间被要求执行的行为。'
-
-output:
- description:
- zh: '由名词性实体节点和规定超边组成的结构化结果。节点只保留规定中涉及的人、部门、文件、场所、物品等要素;超边表示一条独立规定,action 用于概括这些要素之间被要求执行的行为。'
- entities:
- description:
- zh: '规定涉及的基础节点。只提取名词或名词短语,不提取动作本身。'
- fields:
- - name: name
- type: str
- description:
- zh: '实体名称,尽量直接使用原文中的稳定称呼;同一对象若同时出现全称、简称或缩写,应统一为一个名称。'
- - name: category
- type: str
- description:
- zh: '实体类型,应尽量使用清晰、稳定的名词类别,如人员、部门、组织、岗位、文件表单、证件、场所、设备、物品、时间要求、其他。'
- - name: description
- type: str
- description:
- zh: '用一句话说明该实体在当前规定中的含义或作用。'
- required: false
- default: ''
- relations:
- description:
- zh: '表达规定条文的超边。每条超边对应一条独立规定,由相关实体构成,action 负责概括这些实体之间被要求执行的行为。'
- fields:
- - name: ruleType
- type: str
- description:
- zh: '规定类型,用于概括该条规定在规定什么。优先使用:职责分工、行为要求、流程程序、其他。'
- - name: participants
- type: list[str]
- description:
- zh: '构成该条规定基本内容的实体名称列表,必须直接使用已提取节点的 name。只放实体,不要把动作短语放进 participants。'
- - name: action
- type: str
- description:
- zh: '该条规定涉及的核心行为概括,用 1 句话说明这些实体之间被要求执行什么行为。action 承担行为表达,不要把 action 再拆成实体。'
- - name: sourceClause
- type: str
- description:
- zh: '规定来源的条款编号、标题或出处标识,尽量写最近的编号或小节定位。'
- required: false
- default: ''
-
-guideline:
- target:
- zh: '你是一位规定条文结构化分析专家。请从规定类文本中提取每条规定涉及的名词性要素,并用 action 写清这些要素之间被要求执行的行为。'
- rules_for_entities:
- zh:
- - '提取名词或名词短语形式的实体'
- - '优先提取规定中真正参与行为的要素,如人员、岗位、部门、组织、文件表单、证件、场所、设备、物品、时间要求等。根据文本的具体内容和你的知识来决定具体的类别。'
- - 'name 尽量保持原文中的稳定称呼;同一对象不要重复命名。'
- - '如果某个词只是行为本身,例如“登记”“审批”“填写交接记录”,不要单独作为实体。'
- - '对于“访客证”“登记表”“样品库”“前台”“每日18:00前”这类名词性短语,可以作为实体提取。'
- - 'category 要尽量使用少数、容易理解的类别,不要为了细分而临时创造模糊类别。'
- rules_for_relations:
- zh:
- - '每条超边只表达一条独立规定,并连接这条规定涉及的相关实体。'
- - 'ruleType 优先使用:职责分工、行为要求、流程程序、其他。根据文本的具体内容和你的知识来决定具体的类别。'
- - 'participants 必须直接引用已提取节点的 name,只放名词性实体,不放动作短语。'
- - 'action 用 1 句话概括这条规定要求这些实体之间发生什么行为。'
- - |
- 完整示例(输入):
- 1. 访客进入样品库前,应在前台登记并领取访客证。
- 2. 安全部门每日18:00前回收当日访客证,并存档登记表。
- - |
- 完整示例(输出):
- entities:
- - name: 访客
- category: 人员
- description: 进入样品库并需履行登记要求的外来人员。
- - name: 样品库
- category: 场所
- description: 访客进入前需要满足规定要求的区域。
- - name: 前台
- category: 场所
- description: 办理登记和领取访客证的地点。
- - name: 访客证
- category: 证件
- description: 访客登记后领取并在离开前回收的证件。
- - name: 安全部门
- category: 部门
- description: 负责回收访客证并保存记录的管理部门。
- - name: 登记表
- category: 文件表单
- description: 记录访客登记信息并需要存档的表单。
- - name: 每日18:00前
- category: 时间要求
- description: 安全部门执行回收和存档要求的截止时间要求。
- relations:
- - ruleType: 流程程序
- participants: [访客, 样品库, 前台, 访客证]
- action: 规定访客进入样品库前,应在前台登记并领取访客证。
- sourceClause: 1
- - ruleType: 流程程序
- participants: [安全部门, 访客证, 登记表, 每日18:00前]
- action: 规定安全部门每日18:00前回收当日访客证,并存档登记表。
- sourceClause: 2
-
-identifiers:
- entity_id: name
- relation_id: '{sourceClause}|{ruleType}|{action}'
- relation_members: participants
-
-options:
- extraction_mode: one_stage
-
-display:
- entity_label: '{name} ({category})'
- relation_label: '[{ruleType}] {action}'
diff --git a/hyperextract-skills/examples/list/clause_list.yaml b/hyperextract-skills/examples/list/clause_list.yaml
deleted file mode 100644
index d78f9bb..0000000
--- a/hyperextract-skills/examples/list/clause_list.yaml
+++ /dev/null
@@ -1,50 +0,0 @@
-language: zh
-name: clause_list
-type: list
-tags: [general]
-description:
- zh: '规章条文清单 - 将规章制度、操作手册或合规文本拆解为逐条的原子化条文,便于索引、检索、比对与问答。'
-
-output:
- description:
- zh: '由逐条拆解后的规章条文组成的列表结果。'
- fields:
- - name: clauseId
- type: str
- description:
- zh: '条文编号,如第1条、第2条、第2.1款、第3项等。'
- - name: title
- type: str
- description:
- zh: '条文标题、主题或该条的简短概括;原文未明确给出时可留空。'
- required: false
- default: ''
- - name: content
- type: str
- description:
- zh: '条文正文内容,尽量保持与原文一致,避免改写。'
- - name: category
- type: str
- description:
- zh: '条文分类,如总则、权利义务、程序、处罚、附则、其他。'
- required: false
- default: '其他'
-
-guideline:
- target:
- zh: '你是一位专业的规章制度条文拆解专家。请将输入文本按其自然结构拆解为可独立引用、可检索的逐条条文。'
- rules:
- zh:
- - '按原文的自然层级和编号结构拆解条文,如第X条、第X款、第X项等。'
- - '每一项输出都应对应一个独立、可单独引用的条文单元。'
- - 'clauseId 必须尽量使用原文中的编号;若原文无明确编号,可使用稳定且简洁的顺序标识。'
- - 'content 应保留该条的核心正文,尽量与原文一致,不要总结式改写。'
- - 'title 仅在原文明确存在标题、主题或能够从该条主旨中直接提炼时填写;否则留空。'
- - 'category 需尽量归入总则、权利义务、程序、处罚、附则、其他之一。'
- - '不要遗漏任何实质性条文,也不要把多个独立条文合并成一条。'
- - '目录、页眉页脚、签章、编号噪音、纯格式性重复内容通常不作为条文输出。'
-
-options: {}
-
-display:
- label: '{clauseId}({title})'
diff --git a/hyperextract-skills/examples/model/news_summary.yaml b/hyperextract-skills/examples/model/news_summary.yaml
deleted file mode 100644
index a29a7a1..0000000
--- a/hyperextract-skills/examples/model/news_summary.yaml
+++ /dev/null
@@ -1,32 +0,0 @@
-language: zh
-name: NewsSummary
-type: model
-tags: [news]
-description: '新闻摘要 - 从新闻报道中提取关键信息'
-
-output:
- description: '新闻报道的结构化摘要'
- fields:
- - name: title
- type: str
- description: '新闻标题'
- - name: publication_date
- type: str
- description: '发布日期'
- required: false
- - name: source
- type: str
- description: '新闻来源'
- required: false
- - name: summary
- type: str
- description: '新闻摘要'
-
-guideline:
- target: '你是一位新闻编辑。请从新闻报道中提取关键信息。'
- rules:
- - 'title 保留原文标题'
- - 'summary 用 2-3 句话概括核心内容'
-
-display:
- label: '{title}'
diff --git a/hyperextract-skills/examples/set/entity_registry.yaml b/hyperextract-skills/examples/set/entity_registry.yaml
deleted file mode 100644
index 2abb4e4..0000000
--- a/hyperextract-skills/examples/set/entity_registry.yaml
+++ /dev/null
@@ -1,45 +0,0 @@
-language: zh
-name: entity_registry
-type: set
-tags: [general]
-description:
- zh: '实体注册表模板 - 从任意文本中识别并去重关键实体,汇总为可复用的实体清单。'
-
-output:
- description:
- zh: '去重后的实体列表结果,用于形成基础实体台账。'
- fields:
- - name: name
- type: str
- description:
- zh: '实体名称,优先使用文本中最稳定、最清晰的称呼。'
- - name: category
- type: str
- description:
- zh: '实体类型,如人物、机构、地点、产品、概念、事件、制度、其他。'
- - name: description
- type: str
- description:
- zh: '对实体身份、含义或在文本中作用的简要说明。'
- required: false
- default: ''
-
-guideline:
- target:
- zh: '你是一位实体识别专家。请从文本中识别具有独立意义的实体,并将重复出现的同一实体合并为一条记录。'
- rules:
- zh:
- - '提取对理解文本内容有意义的实体,如人物、机构、地点、产品、概念、事件、制度等。'
- - 'name 使用文本中最清晰、最稳定的称呼;同一实体若有简称或别称,应统一为一个名称。'
- - 'category 用于概括实体类型,尽量准确且可复用。'
- - 'description 用 1 句话说明实体是谁、是什么或在文本中的作用;信息不足时可留空。'
- - '对同一实体进行去重,不要因表述差异重复输出多条。'
- - '不要把纯代词、泛称、临时描述短语或无独立指代意义的词语当作实体。'
-
-identifiers:
- item_id: name
-
-options: {}
-
-display:
- label: name
diff --git a/hyperextract-skills/examples/spatial_graph/purchase_record.yaml b/hyperextract-skills/examples/spatial_graph/purchase_record.yaml
deleted file mode 100644
index 24d1908..0000000
--- a/hyperextract-skills/examples/spatial_graph/purchase_record.yaml
+++ /dev/null
@@ -1,54 +0,0 @@
-language: zh
-name: PurchaseRecord
-type: spatial_graph
-tags: [commerce]
-description: '购买记录图 - 记录购买关系及购买发生地点'
-
-output:
- description: '购买关系图,关系边包含购买地点'
- entities:
- description: '买家、卖家和商品节点'
- fields:
- - name: name
- type: str
- description: '实体名称'
- - name: type
- type: str
- description: '实体类型:买家、卖家、商品'
- relations:
- description: '购买关系边'
- fields:
- - name: source
- type: str
- description: '源实体(买家)'
- - name: target
- type: str
- description: '目标实体(商品)'
- - name: amount
- type: str
- description: '购买金额'
- required: false
- - name: location
- type: str
- description: '购买发生地点'
-
-guideline:
- target: '你是一位商业分析专家。请提取购买关系和购买地点信息。'
- rules_for_entities:
- - '提取买家、卖家和商品'
- rules_for_relations:
- - 'source 必须是买家,target 必须是商品'
- rules_for_location:
- - 'location 记录购买发生的地点'
-
-identifiers:
- entity_id: name
- relation_id: '{source}|{target}'
- relation_members:
- source: source
- target: target
- location_field: location
-
-display:
- entity_label: '{name} ({type})'
- relation_label: '购买地点: {location}'
diff --git a/hyperextract-skills/examples/spatio_temporal_graph/social_meeting.yaml b/hyperextract-skills/examples/spatio_temporal_graph/social_meeting.yaml
deleted file mode 100644
index 476b88a..0000000
--- a/hyperextract-skills/examples/spatio_temporal_graph/social_meeting.yaml
+++ /dev/null
@@ -1,61 +0,0 @@
-language: zh
-name: SocialMeeting
-type: spatio_temporal_graph
-tags: [social]
-description: '社交会面图 - 记录人物之间的会面关系,包含会面时间和地点'
-
-output:
- description: '社交会面关系图,关系边包含会面时间和地点'
- entities:
- description: '人物节点'
- fields:
- - name: name
- type: str
- description: '人物姓名'
- - name: role
- type: str
- description: '社会角色'
- required: false
- relations:
- description: '会面关系边'
- fields:
- - name: source
- type: str
- description: '源实体(人物A)'
- - name: target
- type: str
- description: '目标实体(人物B)'
- - name: meeting_type
- type: str
- description: '会面类型'
- required: false
- - name: event_date
- type: str
- description: '会面时间'
- - name: location
- type: str
- description: '会面地点'
-
-guideline:
- target: '你是一位社交分析专家。请提取人物之间的会面关系。'
- rules_for_entities:
- - '提取所有涉及的人物'
- rules_for_relations:
- - 'source 和 target 是会面的双方'
- rules_for_time:
- - 'event_date 记录会面时间'
- rules_for_location:
- - 'location 记录会面地点'
-
-identifiers:
- entity_id: name
- relation_id: '{source}|{target}|{event_date}'
- relation_members:
- source: source
- target: target
- time_field: event_date
- location_field: location
-
-display:
- entity_label: '{name}'
- relation_label: '{event_date} @ {location}'
diff --git a/hyperextract-skills/examples/temporal_graph/biographical_timeline.yaml b/hyperextract-skills/examples/temporal_graph/biographical_timeline.yaml
deleted file mode 100644
index ccc5902..0000000
--- a/hyperextract-skills/examples/temporal_graph/biographical_timeline.yaml
+++ /dev/null
@@ -1,104 +0,0 @@
-language: zh
-name: biographical_timeline
-type: temporal_graph
-tags: [general]
-description:
- zh: '人物生平时间线 - 从传记、自传、回忆录等人物叙事文本中提取带时间的生平事件,并组织为时间线。'
-
-output:
- description:
- zh: '由人物相关实体和生平事件关系组成的时间线结果,用于还原人物经历、角色变化与关键转折。'
- entities:
- description:
- zh: '文本中与人物生平相关、可作为事件端点的实体。'
- fields:
- - name: name
- type: str
- description:
- zh: '实体在文本中的稳定名称或常用称呼。'
- - name: type
- type: str
- description:
- zh: '实体类型,如人物、地点、组织、作品、奖项、身份、物品、概念、其他。'
- - name: description
- type: str
- description:
- zh: '对实体身份、角色或在当前文本中作用的简要说明。'
- required: false
- relations:
- description:
- zh: '围绕人物经历构建的事件关系边。'
- fields:
- - name: source
- type: str
- description:
- zh: '事件发起者或经历者,通常为人物主体或触发事件的相关实体。'
- - name: target
- type: str
- description:
- zh: '与该事件直接相关的对象实体,如地点、学校、组织、人物、作品、奖项等。'
- - name: eventType
- type: str
- description:
- zh: '事件类型。使用能够概括事件本身的简洁词语或短语,优先具体、直观、可区分;通常可用动词,如出生、入学、任职、结婚、出版、获奖。可参考示例,但不必局限于示例,也可以根据文本语义自行创造更贴切的标签。'
- - name: eventDate
- type: str
- description:
- zh: '事件时间。优先保留文本中最精确的时间表达;可为年份、年月、年月日,必要时可保留时间段。'
- required: false
- - name: details
- type: str
- description:
- zh: '事件补充说明,可记录身份、地点、机构、结果或上下文。'
- required: false
-
-guideline:
- target:
- zh: '你是一位专业的人物传记事件抽取专家。请围绕人物主体,从文本中提取与其生平经历直接相关的实体和事件,并构建可信的时间线。'
- rules_for_entities:
- zh:
- - '优先提取与人物主体生平经历直接相关的实体,如人物、地点、组织、作品、奖项、身份称谓等。'
- - '为每个实体指定尽量准确的类型,并优先使用文本中的稳定称呼。'
- - '不必为纯背景概念、空泛评价或无法成为事件端点的内容单独建实体。'
- rules_for_relations:
- zh:
- - '仅从已提取实体中创建事件边,source 和 target 都必须对应实体 name。'
- - '事件应代表可放入人物时间线的经历、转折、公开活动或身份变化,不要把纯评价、性格描述或静态背景知识当作事件。'
- - '若一句话包含多个独立事件,应拆分为多条关系;若同一事件同时涉及时间、地点、组织、身份,可在 details 中补充。'
- - 'eventType 应使用能够概括事件本身的简洁词语或短语,优先具体、直观、可区分;通常可用动词或动宾结构。'
- - '优先写贴近原文语义的具体标签,不要过度抽象。例如优先写“入学、毕业、留学”而不是“教育”,优先写“任职、升迁、离任”而不是“工作”,优先写“出版、获奖、发明”而不是“成就”。'
- - '可参考但不限于以下示例:出生、逝世、迁居、入学、毕业、任职、结婚、合作、出版、获奖、参战、归国、隐居。'
- - '允许根据文本语义自行创造更贴切的标签,例如拜师、出道、登基、封侯、退赛、复出等;不要求必须使用示例中的词。'
- - '仅在确实无法提炼出更具体的事件标签时,才使用较泛的词。'
- - '时间信息为可选,仅在文本明确给出或能根据明确相对时间可靠换算时才填写。'
- rules_for_time:
- zh:
- - '当前观察日期:{observation_time}'
- - '相对时间解析(基于观察日期):'
- - '- "去年" → {observation_time} 前一年'
- - '- "今年" → {observation_time} 所属年份'
- - '- "明年" → {observation_time} 后一年'
- - '- "昨天/今天/明天" → {observation_time} 前/当/后一天'
- - '- "十年前/五年后" → {observation_time} 前/后相应年数'
- - '- "年初/年末" → 当年 1月1日/12月31日'
- - '- "朝代" → 保留朝代名称'
- - '明确时间:优先保留文本中最精确的原始格式'
- - '- 年份(如 429年、2023年)→ 429、2023'
- - '- 年-月、年-月-日、时间段(如 1937-1945)→ 保持原格式'
- - '若只有模糊阶段性表达且无法可靠换算,不要强行补时间'
- - '缺失时间:留空'
-
-identifiers:
- entity_id: name
- relation_id: '{source}|{target}'
- relation_members:
- source: source
- target: target
- time_field: 'eventDate'
-
-options:
- extraction_mode: two_stage
-
-display:
- entity_label: '{name} ({type})'
- relation_label: '{eventType}({eventDate})'
diff --git a/hyperextract-skills/graph-designer/SKILL.md b/hyperextract-skills/graph-designer/SKILL.md
index e66f2a0..450d66e 100644
--- a/hyperextract-skills/graph-designer/SKILL.md
+++ b/hyperextract-skills/graph-designer/SKILL.md
@@ -113,15 +113,26 @@ identifiers:
location_field: location
```
+## Cases by Type
+
+**Important**: Load only the case matching user's selected type.
+
+| Type | Case File |
+|------|-----------|
+| graph | [cases/corporate-ownership.yaml](cases/corporate-ownership.yaml) |
+| hypergraph | [cases/battle-analysis.yaml](cases/battle-analysis.yaml) |
+| spatio_temporal_graph | [cases/meeting-records.yaml](cases/meeting-records.yaml) |
+
## Reference Files
-| Topic | Reference File |
-|-------|---------------|
-| Entity design patterns | [reference-entity.md](reference-entity.md) |
-| Relation design patterns | [reference-relation.md](reference-relation.md) |
-| Hypergraph design | [reference-hypergraph.md](reference-hypergraph.md) |
-| Dimension design | [reference-dimensions.md](reference-dimensions.md) |
-| Complete examples | [examples.md](examples.md) |
+**Important**: Check these files only when needed for the specific design task.
+
+| Topic | When to Check |
+|-------|--------------|
+| [references/entity.md](references/entity.md) | When designing output.entities |
+| [references/relation.md](references/relation.md) | When designing output.relations |
+| [references/hypergraph.md](references/hypergraph.md) | For hypergraph type only |
+| [references/dimensions.md](references/dimensions.md) | For temporal_graph/spatial_graph types |
---
@@ -148,7 +159,3 @@ identifiers:
- [ ] relation_id template correct?
- [ ] relation_members configured?
- [ ] time/location_field specified?
-
----
-
-See [examples.md](examples.md) for complete YAML examples.
diff --git a/hyperextract-skills/graph-designer/cases/battle-analysis.yaml b/hyperextract-skills/graph-designer/cases/battle-analysis.yaml
new file mode 100644
index 0000000..58fd0dd
--- /dev/null
+++ b/hyperextract-skills/graph-designer/cases/battle-analysis.yaml
@@ -0,0 +1,49 @@
+language: en
+name: BattleAnalysis
+type: hypergraph
+tags: [history, military]
+description: 'Extract historical battle information'
+
+output:
+ entities:
+ description: 'Historical figures and factions'
+ fields:
+ - name: name
+ type: str
+ relations:
+ description: 'Battle events with participants'
+ fields:
+ - name: battle_name
+ type: str
+ - name: attackers
+ type: list
+ description: 'Attacking side'
+ - name: defenders
+ type: list
+ description: 'Defending side'
+ - name: commanders
+ type: list
+ description: 'Key commanders'
+ required: false
+ - name: outcome
+ type: str
+ - name: year
+ type: str
+ required: false
+
+guideline:
+ target: 'You are a military history expert. Extract battle information.'
+ rules_for_entities:
+ - 'Extract all mentioned figures and factions'
+ rules_for_relations:
+ - 'Identify attackers and defenders clearly'
+ - 'Include key commanders if mentioned'
+
+identifiers:
+ entity_id: name
+ relation_id: '{battle_name}'
+ relation_members: [attackers, defenders, commanders]
+
+display:
+ entity_label: '{name}'
+ relation_label: '{battle_name}: {outcome}'
diff --git a/hyperextract-skills/graph-designer/cases/corporate-ownership.yaml b/hyperextract-skills/graph-designer/cases/corporate-ownership.yaml
new file mode 100644
index 0000000..4c81029
--- /dev/null
+++ b/hyperextract-skills/graph-designer/cases/corporate-ownership.yaml
@@ -0,0 +1,48 @@
+language: en
+name: CorporateOwnershipGraph
+type: graph
+tags: [finance, corporate]
+description: 'Extract company ownership and control relationships'
+
+output:
+ entities:
+ description: 'Company and person entities'
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name'
+ - name: category
+ type: str
+ description: 'Company or Person'
+ relations:
+ description: 'Ownership and control relationships'
+ fields:
+ - name: source
+ type: str
+ - name: target
+ type: str
+ - name: relation_type
+ type: str
+ - name: percentage
+ type: str
+ required: false
+
+guideline:
+ target: 'You are a corporate analysis expert. Extract company relationships.'
+ rules_for_entities:
+ - 'Extract company and person entities only'
+ - 'Category must be Company or Person'
+ rules_for_relations:
+ - 'Only extract ownership and control relationships'
+ - 'Common types: owns, controls, invested_in, subsidiary_of'
+
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{relation_type}|{target}'
+ relation_members:
+ source: source
+ target: target
+
+display:
+ entity_label: '{name} ({category})'
+ relation_label: '{relation_type}'
diff --git a/hyperextract-skills/graph-designer/cases/meeting-records.yaml b/hyperextract-skills/graph-designer/cases/meeting-records.yaml
new file mode 100644
index 0000000..04f847e
--- /dev/null
+++ b/hyperextract-skills/graph-designer/cases/meeting-records.yaml
@@ -0,0 +1,49 @@
+language: en
+name: MeetingRecords
+type: spatio_temporal_graph
+tags: [business, collaboration]
+description: 'Extract meeting information'
+
+output:
+ entities:
+ description: 'People and organizations'
+ fields:
+ - name: name
+ type: str
+ relations:
+ description: 'Meeting events'
+ fields:
+ - name: meeting_title
+ type: str
+ - name: attendees
+ type: list
+ - name: meeting_date
+ type: str
+ - name: location
+ type: str
+ required: false
+ - name: summary
+ type: str
+ required: false
+
+guideline:
+ target: 'You are a business analyst. Extract meeting information.'
+ rules_for_entities:
+ - 'Extract all mentioned participants'
+ rules_for_relations:
+ - 'Extract time and location if mentioned'
+ rules_for_time:
+ - 'Use ISO format when possible'
+ rules_for_location:
+ - 'Keep structured locations as-is'
+
+identifiers:
+ entity_id: name
+ relation_id: '{meeting_title}|{meeting_date}'
+ relation_members: attendees
+ time_field: meeting_date
+ location_field: location
+
+display:
+ entity_label: '{name}'
+ relation_label: '{meeting_title} @ {meeting_date}'
diff --git a/hyperextract-skills/graph-designer/examples.md b/hyperextract-skills/graph-designer/examples.md
deleted file mode 100644
index d15de41..0000000
--- a/hyperextract-skills/graph-designer/examples.md
+++ /dev/null
@@ -1,183 +0,0 @@
-# Graph Type Examples
-
-Complete YAML examples for graph types. See [SKILL.md](SKILL.md) for workflow.
-
----
-
-## Example 1: Corporate Ownership (graph)
-
-```yaml
-language: en
-name: CorporateOwnershipGraph
-type: graph
-tags: [finance, corporate]
-description: 'Extract company ownership and control relationships'
-
-output:
- entities:
- description: 'Company and person entities'
- fields:
- - name: name
- type: str
- description: 'Entity name'
- - name: category
- type: str
- description: 'Company or Person'
- relations:
- description: 'Ownership and control relationships'
- fields:
- - name: source
- type: str
- - name: target
- type: str
- - name: relation_type
- type: str
- - name: percentage
- type: str
- required: false
-
-guideline:
- target: 'You are a corporate analysis expert. Extract company relationships.'
- rules_for_entities:
- - 'Extract company and person entities only'
- - 'Category must be Company or Person'
- rules_for_relations:
- - 'Only extract ownership and control relationships'
- - 'Common types: owns, controls, invested_in, subsidiary_of'
-
-identifiers:
- entity_id: name
- relation_id: '{source}|{relation_type}|{target}'
- relation_members:
- source: source
- target: target
-
-display:
- entity_label: '{name} ({category})'
- relation_label: '{relation_type}'
-```
-
----
-
-## Example 2: Battle Analysis (hypergraph nested)
-
-```yaml
-language: en
-name: BattleAnalysis
-type: hypergraph
-tags: [history, military]
-description: 'Extract historical battle information'
-
-output:
- entities:
- description: 'Historical figures and factions'
- fields:
- - name: name
- type: str
- relations:
- description: 'Battle events with participants'
- fields:
- - name: battle_name
- type: str
- - name: attackers
- type: list
- description: 'Attacking side'
- - name: defenders
- type: list
- description: 'Defending side'
- - name: commanders
- type: list
- description: 'Key commanders'
- required: false
- - name: outcome
- type: str
- - name: year
- type: str
- required: false
-
-guideline:
- target: 'You are a military history expert. Extract battle information.'
- rules_for_entities:
- - 'Extract all mentioned figures and factions'
- rules_for_relations:
- - 'Identify attackers and defenders clearly'
- - 'Include key commanders if mentioned'
-
-identifiers:
- entity_id: name
- relation_id: '{battle_name}'
- relation_members: [attackers, defenders, commanders]
-
-display:
- entity_label: '{name}'
- relation_label: '{battle_name}: {outcome}'
-```
-
----
-
-## Example 3: Meeting Records (spatio_temporal_graph)
-
-```yaml
-language: en
-name: MeetingRecords
-type: spatio_temporal_graph
-tags: [business, collaboration]
-description: 'Extract meeting information'
-
-output:
- entities:
- description: 'People and organizations'
- fields:
- - name: name
- type: str
- relations:
- description: 'Meeting events'
- fields:
- - name: meeting_title
- type: str
- - name: attendees
- type: list
- - name: meeting_date
- type: str
- - name: location
- type: str
- required: false
- - name: summary
- type: str
- required: false
-
-guideline:
- target: 'You are a business analyst. Extract meeting information.'
- rules_for_entities:
- - 'Extract all mentioned participants'
- rules_for_relations:
- - 'Extract time and location if mentioned'
- rules_for_time:
- - 'Use ISO format when possible'
- rules_for_location:
- - 'Keep structured locations as-is'
-
-identifiers:
- entity_id: name
- relation_id: '{meeting_title}|{meeting_date}'
- relation_members: attendees
- time_field: meeting_date
- location_field: location
-
-display:
- entity_label: '{name}'
- relation_label: '{meeting_title} @ {meeting_date}'
-```
-
----
-
-## Quick Reference
-
-| Type | Example | Key Config |
-|------|---------|------------|
-| graph | Corporate ownership | source/target |
-| hypergraph (simple) | Contract clauses | participants string |
-| hypergraph (nested) | Battle analysis | [groups] list |
-| temporal_graph | Career timeline | + time_field |
-| spatial_graph | Purchase locations | + location_field |
-| spatio_temporal | Meeting records | + time + location |
diff --git a/hyperextract-skills/graph-designer/reference-dimensions.md b/hyperextract-skills/graph-designer/references/dimensions.md
similarity index 100%
rename from hyperextract-skills/graph-designer/reference-dimensions.md
rename to hyperextract-skills/graph-designer/references/dimensions.md
diff --git a/hyperextract-skills/graph-designer/reference-entity.md b/hyperextract-skills/graph-designer/references/entity.md
similarity index 100%
rename from hyperextract-skills/graph-designer/reference-entity.md
rename to hyperextract-skills/graph-designer/references/entity.md
diff --git a/hyperextract-skills/graph-designer/reference-hypergraph.md b/hyperextract-skills/graph-designer/references/hypergraph.md
similarity index 100%
rename from hyperextract-skills/graph-designer/reference-hypergraph.md
rename to hyperextract-skills/graph-designer/references/hypergraph.md
diff --git a/hyperextract-skills/graph-designer/reference-relation.md b/hyperextract-skills/graph-designer/references/relation.md
similarity index 100%
rename from hyperextract-skills/graph-designer/reference-relation.md
rename to hyperextract-skills/graph-designer/references/relation.md
diff --git a/hyperextract-skills/record-designer/SKILL.md b/hyperextract-skills/record-designer/SKILL.md
index 2543383..653ddda 100644
--- a/hyperextract-skills/record-designer/SKILL.md
+++ b/hyperextract-skills/record-designer/SKILL.md
@@ -84,13 +84,24 @@ identifiers:
item_id: [deduplication field]
```
+## Cases by Type
+
+**Important**: Load only the case matching user's selected type.
+
+| Type | Case File |
+|------|-----------|
+| model | [cases/earnings-summary.yaml](cases/earnings-summary.yaml) |
+| list | [cases/product-features.yaml](cases/product-features.yaml) |
+| set | [cases/entity-registry.yaml](cases/entity-registry.yaml) |
+
## Reference Files
-| Topic | Reference File |
-|-------|---------------|
-| Field design patterns | [reference-field.md](reference-field.md) |
-| Identifier configuration | [reference-identifier.md](reference-identifier.md) |
-| Complete examples | [examples.md](examples.md) |
+**Important**: Check these files only when needed for the specific design task.
+
+| Topic | When to Check |
+|-------|--------------|
+| [references/field.md](references/field.md) | When designing output.fields |
+| [references/identifier.md](references/identifier.md) | For set type only |
## Design Checklist
@@ -100,7 +111,3 @@ identifiers:
- [ ] Default values are safe/meaningful?
- [ ] For set: item_id can uniquely identify records?
- [ ] Display label references correct fields?
-
----
-
-See [examples.md](examples.md) for complete YAML examples.
diff --git a/hyperextract-skills/record-designer/cases/earnings-summary.yaml b/hyperextract-skills/record-designer/cases/earnings-summary.yaml
new file mode 100644
index 0000000..ec7d036
--- /dev/null
+++ b/hyperextract-skills/record-designer/cases/earnings-summary.yaml
@@ -0,0 +1,38 @@
+language: en
+name: EarningsCallSummary
+type: model
+tags: [finance]
+description: 'Extract key financial metrics from earnings call transcripts'
+
+output:
+ description: 'Earnings call summary'
+ fields:
+ - name: company_name
+ type: str
+ description: 'Company name'
+ required: true
+ default: ''
+ - name: revenue
+ type: str
+ description: 'Revenue amount'
+ required: false
+ default: 'N/A'
+ - name: quarter
+ type: str
+ description: 'Fiscal quarter'
+ required: true
+ default: ''
+ - name: key_highlights
+ type: list
+ description: 'Key highlights from the call'
+ required: false
+
+guideline:
+ target: 'You are a financial analyst. Extract key metrics from earnings calls.'
+ rules:
+ - 'Extract revenue in the format shown in text (including currency)'
+ - 'Use N/A if revenue is not mentioned'
+ - 'Extract quarter as Q1/Q2/Q3/Q4 format'
+
+display:
+ label: '{company_name} - {quarter}'
diff --git a/hyperextract-skills/record-designer/cases/entity-registry.yaml b/hyperextract-skills/record-designer/cases/entity-registry.yaml
new file mode 100644
index 0000000..4ec9870
--- /dev/null
+++ b/hyperextract-skills/record-designer/cases/entity-registry.yaml
@@ -0,0 +1,32 @@
+language: en
+name: EntityRegistry
+type: set
+tags: [entity, registry]
+description: 'Extract and deduplicate entity mentions'
+
+output:
+ description: 'Entity registry'
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name'
+ - name: category
+ type: str
+ description: 'Entity type'
+ - name: source
+ type: str
+ description: 'Source document'
+ required: false
+
+guideline:
+ target: 'You are a knowledge engineer. Extract entities and deduplicate.'
+ rules:
+ - 'Extract all mentioned entities'
+ - 'Deduplicate by name'
+ - 'Keep first occurrence of each entity'
+
+identifiers:
+ item_id: name
+
+display:
+ label: '{name} ({category})'
diff --git a/hyperextract-skills/record-designer/cases/product-features.yaml b/hyperextract-skills/record-designer/cases/product-features.yaml
new file mode 100644
index 0000000..ea9fc38
--- /dev/null
+++ b/hyperextract-skills/record-designer/cases/product-features.yaml
@@ -0,0 +1,28 @@
+language: en
+name: ProductFeatures
+type: list
+tags: [product, features]
+description: 'Extract product features'
+
+output:
+ description: 'Product feature list'
+ fields:
+ - name: order
+ type: int
+ description: 'Feature order'
+ - name: feature
+ type: str
+ description: 'Feature name'
+ - name: description
+ type: str
+ description: 'Feature description'
+ required: false
+
+guideline:
+ target: 'You are a product analyst. Extract product features.'
+ rules:
+ - 'Extract features in order they appear'
+ - 'Include brief description if available'
+
+display:
+ label: '{order}. {feature}'
diff --git a/hyperextract-skills/record-designer/examples.md b/hyperextract-skills/record-designer/examples.md
deleted file mode 100644
index 0e53459..0000000
--- a/hyperextract-skills/record-designer/examples.md
+++ /dev/null
@@ -1,132 +0,0 @@
-# Record Type Examples
-
-Complete YAML examples for record types. See [SKILL.md](SKILL.md) for workflow.
-
----
-
-## Example 1: Earnings Call Summary (model)
-
-```yaml
-language: en
-name: EarningsCallSummary
-type: model
-tags: [finance]
-description: 'Extract key financial metrics from earnings call transcripts'
-
-output:
- description: 'Earnings call summary'
- fields:
- - name: company_name
- type: str
- description: 'Company name'
- required: true
- default: ''
- - name: revenue
- type: str
- description: 'Revenue amount'
- required: false
- default: 'N/A'
- - name: quarter
- type: str
- description: 'Fiscal quarter'
- required: true
- default: ''
- - name: key_highlights
- type: list
- description: 'Key highlights from the call'
- required: false
-
-guideline:
- target: 'You are a financial analyst. Extract key metrics from earnings calls.'
- rules:
- - 'Extract revenue in the format shown in text (including currency)'
- - 'Use N/A if revenue is not mentioned'
- - 'Extract quarter as Q1/Q2/Q3/Q4 format'
-
-display:
- label: '{company_name} - {quarter}'
-```
-
----
-
-## Example 2: Product Features (list)
-
-```yaml
-language: en
-name: ProductFeatures
-type: list
-tags: [product, features]
-description: 'Extract product features'
-
-output:
- description: 'Product feature list'
- fields:
- - name: order
- type: int
- description: 'Feature order'
- - name: feature
- type: str
- description: 'Feature name'
- - name: description
- type: str
- description: 'Feature description'
- required: false
-
-guideline:
- target: 'You are a product analyst. Extract product features.'
- rules:
- - 'Extract features in order they appear'
- - 'Include brief description if available'
-
-display:
- label: '{order}. {feature}'
-```
-
----
-
-## Example 3: Entity Registry (set)
-
-```yaml
-language: en
-name: EntityRegistry
-type: set
-tags: [entity, registry]
-description: 'Extract and deduplicate entity mentions'
-
-output:
- description: 'Entity registry'
- fields:
- - name: name
- type: str
- description: 'Entity name'
- - name: category
- type: str
- description: 'Entity type'
- - name: source
- type: str
- description: 'Source document'
- required: false
-
-guideline:
- target: 'You are a knowledge engineer. Extract entities and deduplicate.'
- rules:
- - 'Extract all mentioned entities'
- - 'Deduplicate by name'
- - 'Keep first occurrence of each entity'
-
-identifiers:
- item_id: name
-
-display:
- label: '{name} ({category})'
-```
-
----
-
-## Quick Reference
-
-| Type | Example | Key Config |
-|------|---------|------------|
-| model | Earnings summary | No identifiers |
-| list | Feature list | No identifiers, order field |
-| set | Entity registry | item_id required |
diff --git a/hyperextract-skills/record-designer/reference-field.md b/hyperextract-skills/record-designer/references/field.md
similarity index 100%
rename from hyperextract-skills/record-designer/reference-field.md
rename to hyperextract-skills/record-designer/references/field.md
diff --git a/hyperextract-skills/record-designer/reference-identifier.md b/hyperextract-skills/record-designer/references/identifier.md
similarity index 100%
rename from hyperextract-skills/record-designer/reference-identifier.md
rename to hyperextract-skills/record-designer/references/identifier.md
diff --git a/hyperextract-skills/yaml-validator/SKILL.md b/hyperextract-skills/yaml-validator/SKILL.md
index 6226dc7..06be24a 100644
--- a/hyperextract-skills/yaml-validator/SKILL.md
+++ b/hyperextract-skills/yaml-validator/SKILL.md
@@ -63,12 +63,23 @@ description: |
## Reference Files
-| Topic | Reference File |
-|-------|---------------|
-| Syntax validation | [rules-syntax.md](rules-syntax.md) |
-| Type-specific rules | [rules-types.md](rules-types.md) |
-| Identifier rules | [rules-identifiers.md](rules-identifiers.md) |
-| Common errors | [patterns-errors.md](patterns-errors.md) |
+**Important**: Check these files only when needed during validation process.
+
+| Topic | When to Check |
+|-------|--------------|
+| [references/rules-syntax.md](references/rules-syntax.md) | Always (first step) |
+| [references/rules-types.md](references/rules-types.md) | Type-specific validation |
+| [references/rules-identifiers.md](references/rules-identifiers.md) | Identifier configuration check |
+| [references/rules-errors.md](references/rules-errors.md) | When errors are found |
+
+## Validation Order
+
+**Recommended order**: Follow this sequence for efficient validation:
+
+1. **Syntax** → [rules-syntax.md](references/rules-syntax.md) - Check YAML validity first
+2. **Structure** → [rules-types.md](references/rules-types.md) - Validate based on type
+3. **Identifiers** → [rules-identifiers.md](references/rules-identifiers.md) - Check identifier config
+4. **Errors** → [rules-errors.md](references/rules-errors.md) - Look up fixes if needed
## Error Message Format
@@ -95,7 +106,3 @@ description: |
### Overall Assessment
✅ Configuration valid
```
-
----
-
-See [patterns-errors.md](patterns-errors.md) for common error patterns and fixes.
diff --git a/hyperextract-skills/yaml-validator/patterns-errors.md b/hyperextract-skills/yaml-validator/references/rules-errors.md
similarity index 100%
rename from hyperextract-skills/yaml-validator/patterns-errors.md
rename to hyperextract-skills/yaml-validator/references/rules-errors.md
diff --git a/hyperextract-skills/yaml-validator/rules-identifiers.md b/hyperextract-skills/yaml-validator/references/rules-identifiers.md
similarity index 100%
rename from hyperextract-skills/yaml-validator/rules-identifiers.md
rename to hyperextract-skills/yaml-validator/references/rules-identifiers.md
diff --git a/hyperextract-skills/yaml-validator/rules-syntax.md b/hyperextract-skills/yaml-validator/references/rules-syntax.md
similarity index 100%
rename from hyperextract-skills/yaml-validator/rules-syntax.md
rename to hyperextract-skills/yaml-validator/references/rules-syntax.md
diff --git a/hyperextract-skills/yaml-validator/rules-types.md b/hyperextract-skills/yaml-validator/references/rules-types.md
similarity index 100%
rename from hyperextract-skills/yaml-validator/rules-types.md
rename to hyperextract-skills/yaml-validator/references/rules-types.md