Skip to content

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

docs: 添加超提取技能文档和参考文件

yifanfeng9746e9614add91
diff --git a/hyperextract-skills/SKILL.md b/hyperextract-skills/SKILL.md
index f4d9f49..65c78b1 100644
--- a/hyperextract-skills/SKILL.md
+++ b/hyperextract-skills/SKILL.md
@@ -1,69 +1,105 @@
---
name: hyper-extract
description: |
- Hyper-Extract Knowledge Template Design Assistant. Helps users design YAML configuration templates through natural language dialogue.
-
- ## Supported Types (8 AutoTypes)
- ### Record Types
- - model: Single structured object
- - list: List of homogeneous objects
- - set: Deduplicated object set
- ### Graph Types
- - graph: Binary relation graph
- - hypergraph: Multi-entity relation hypergraph
- - temporal_graph: Temporal graph with time dimension
- - spatial_graph: Spatial graph with location dimension
- - spatio_temporal_graph: Combined temporal and spatial
-
- ## Workflow
- 1. brainstorm: Explore requirements, discuss type details
- 2. record-designer OR graph-designer: Design structure + rules
- 3. yaml-validator: Validate configuration (optional)
- 4. multilingual: Multi-language conversion (optional)
+ Hyper-Extract Knowledge Template Designer. Creates YAML configs for data extraction.
---
-# Hyper-Extract Knowledge Template Design Assistant
+# Hyper-Extract
-## How to Use
+## Overview
-### Mode 1: Start from Requirements
-Describe your scenario, we'll explore together to clarify needs and determine the type.
+Hyper-Extract helps users design YAML configuration templates for structured data extraction.
-### Mode 2: Start from Type
-Already know the type? Jump directly to the designer.
+## Workflow
-### Mode 3: Start from Example
-Have a reference template? We'll analyze and adapt it.
+```
+User → brainstorm → designer → validator → multilingual
+```
+
+## Skills
+
+| Skill | Purpose | When to Use |
+|-------|---------|-------------|
+| brainstorm | Explore requirements, determine types | First step, when unsure |
+| record-designer | Design model/list/set structures | For Record types |
+| graph-designer | Design graph/hypergraph structures | For Graph types |
+| yaml-validator | Validate YAML correctness | Optional, after design |
+| multilingual | Multi-language support | Optional |
+
+---
+
+## Skill Workflow
-## Sub-Skills
+### Step 1: brainstorm
+Discuss requirements, determine type, create design draft.
-| Skill | Purpose |
-|-------|---------|
-| brainstorm | Deep discussion about requirements and type-specific details |
-| record-designer | Design model/list/set structures |
-| graph-designer | Design graph/hypergraph/etc structures |
-| yaml-validator | Validate YAML correctness |
-| multilingual | Multi-language support |
+### Step 2: designer
+Generate YAML based on design draft:
+- record-designer → model/list/set
+- graph-designer → graph/hypergraph/temporal/spatial
-## Calling Sub-Skills
+### Step 3: validator (optional)
+Validate YAML syntax and structure.
+### Step 4: multilingual (optional)
+Add multi-language support.
+
+---
+
+## Supported Types
+
+| Type | Description |
+|------|-------------|
+| model | Single structured object |
+| list | Ordered list of items |
+| set | Deduplicated set |
+| graph | Binary relations (A→B) |
+| hypergraph | Multi-entity relations |
+| temporal_graph | + time dimension |
+| spatial_graph | + space dimension |
+| spatio_temporal_graph | + time + space |
+
+---
+
+## Hypergraph Grouping
+
+| Type | relation_members | Use Case |
+|------|-----------------|----------|
+| Simple | `participants` (string) | Flat list |
+| Nested | `[group_a, group_b]` (list) | Semantic roles |
+
+---
+
+## Skill Calling Conventions
+
+### brainstorm → designer
+
+Pass design draft:
+```markdown
+## Type: hypergraph
+## Groups: [attackers, defenders]
+## Fields: [battle_name, outcome]
+```
+
+### designer → validator (optional)
+
+```markdown
+## Generated YAML
+[yaml content]
```
-[Invoke brainstorm]
-User description: [description]
-Current understanding: [if any]
-[Invoke record-designer]
-Type: [model/list/set]
-Requirements: [from brainstorm]
+---
-[Invoke graph-designer]
-Type: [graph/hypergraph/temporal_graph/spatial_graph/spatio_temporal_graph]
-Requirements: [from brainstorm]
+## Type Determination Quick Reference
-[Invoke yaml-validator]
-YAML: [configuration]
-Scope: [all/syntax/semantics]
+```
+Need relationships?
+├─ No → model / list / set
+└─ Yes → graph / hypergraph
+ ├─ Binary → graph
+ └─ Multi-entity → hypergraph
-[Invoke multilingual]
-Language: [target language]
++ time → temporal_graph
++ space → spatial_graph
++ both → spatio_temporal_graph
```
diff --git a/hyperextract-skills/brainstorm/SKILL.md b/hyperextract-skills/brainstorm/SKILL.md
index ec4e8d6..fffeb17 100644
--- a/hyperextract-skills/brainstorm/SKILL.md
+++ b/hyperextract-skills/brainstorm/SKILL.md
@@ -1,93 +1,134 @@
---
name: hyper-extract-brainstorm
description: |
- Hyper-Extract Requirements Brainstorming Assistant. Explore user requirements and discuss detailed design for each type.
-
- ## What We Explore
- - Input: Source, domain, structure
- - Output: What to extract, how to use
- - Type-specific discussions:
- * Record types: Item structure, field design, deduplication
- * Graph types: Entity types, relation types, multi-type nodes
- * Hypergraph: Participant types, outcome structure, reasoning needs
- * Temporal/spatial: Time/location on edges, format handling, observation reference
-
- ## Output
- 1. Requirements summary
- 2. Recommended type
- 3. Type-specific design specs
+ Requirements Brainstorming for Hyper-Extract. Helps users discuss requirements and determine types.
+ Use when exploring extraction needs or unsure which type to use.
---
# Brainstorm: Requirements Exploration
-## Phase 1: Input & Output
+## Workflow
-**Input**: Source, domain, structure level, length
-**Output**: What to extract and how to use
+1. Clarify input/output
+2. Discuss type details
+3. Output design draft → Pass to designer
-## Phase 2: Type Determination
+---
-- "Complete summary" → **model**
-- "List of items" → **list**
-- "Deduplicated entities" → **set**
-- "Relationships between entities" → **graph**
-- "Multi-party relationships" → **hypergraph**
-- "Events with time" → **temporal_graph**
-- "Events with location" → **spatial_graph**
-- "Events with time + location" → **spatio_temporal_graph**
+## Type Determination
-## Phase 3: Type-Specific Discussion
+### Decision Tree
-### Record Types (model/list/set)
+```
+Need to model relationships?
+├─ No → Record types
+│ ├─ Single object → model
+│ ├─ Ordered list → list
+│ └─ Deduplicated set → set
+└─ Yes → Graph types
+ ├─ Binary (A→B) → graph
+ └─ Multi-entity (A+B+C→D)
+ ├─ Flat list → hypergraph (simple)
+ └─ Role groups → hypergraph (nested)
+
+After graph:
+├─ + time dimension → temporal_graph
+├─ + space dimension → spatial_graph
+└─ + both → spatio_temporal_graph
+```
-- Item structure and fields
-- For set: deduplication field
-- For list: nested structure, order
+### Quick Reference
-### Graph Types
+| Intent | Type |
+|--------|------|
+| Summary/card | model |
+| Ordered items | list |
+| Deduplicated entities | set |
+| Binary relations | graph |
+| Multi-party events | hypergraph |
+| + time | temporal_graph |
+| + space | spatial_graph |
+| + time + space | spatio_temporal_graph |
-1. **Entity types**: What entities to extract?
-2. **Entity fields**: name, category, description?
-3. **Relation types**: What relationships?
-4. **Relation fields**: Binary or complex?
+---
-### Hypergraph
+## Discussion Questions
-- Participants: Who/what participates?
-- Outcome: What result/conclusion?
-- Reasoning: Evidence needed?
+### For All Types
+- What is the input source?
+- What to extract?
+- Key fields needed?
-### Dimension Evolution (temporal/spatial)
+### For Graph Types
+- Entity types and granularity?
+- Relation types (predefined or custom)?
+- Multi-type nodes?
-After basic graph design, discuss:
+### For Hypergraph
+- Simple or nested grouping?
+- How many semantic groups?
+- Group names?
-**Time dimension?**
-- Does the relation have time? (e.g., "A bought from B on date X")
-- Is time on node (birth_date) or edge (event_date)?
-- If time needs to be a relation dimension → upgrade to **temporal_graph**
-- Extract time to edge, add `time_field` in identifiers
+### For Temporal/Spatial
+- Time/space on edge or node?
+- Format handling?
-**Location dimension?**
-- Does the relation have location? (e.g., "A bought from B at location Y")
-- Is location on node (hq) or edge (transaction location)?
-- If location needs to be a relation dimension → upgrade to **spatial_graph**
-- Extract location to edge, add `location_field` in identifiers
+---
-**Both?**
-- Need both time and location → **spatio_temporal_graph**
+## Output: Design Draft
-## Output Format
+### For Record Types (model/list/set)
```markdown
-## Requirements Summary
-- Input: ...
-- Output: ...
-- Quality: ...
+## Type: [model/list/set]
-## Type Recommendation
-**Type**: [type]
-**Confidence**: High/Medium/Low
+## Fields
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| [name] | str | yes | ... |
-## Design Specs
-[Based on type discussion]
+## Notes
+[Any special requirements]
```
+
+### For Graph Types (graph/hypergraph/temporal/spatial)
+
+```markdown
+## Type: [graph/hypergraph/temporal/spatial]
+
+## Entities
+| Field | Type | Description |
+|-------|------|-------------|
+| name | str | Entity name |
+| category | str | Entity type |
+
+## Relations
+| Field | Type | Description |
+|-------|------|-------------|
+| [field] | str/list | ... |
+
+## Identifiers
+- entity_id: name
+- relation_id: '{...}'
+- relation_members: [...]
+
+## Notes
+[Any special requirements]
+```
+
+### Type-Specific Fields
+
+| Type | Additional Fields |
+|------|-------------------|
+| hypergraph | Participants or Groups |
+| temporal_graph | time_field |
+| spatial_graph | location_field |
+| spatio_temporal_graph | time_field + location_field |
+
+---
+
+## Pass to Designer
+
+After brainstorm, invoke the appropriate designer:
+- model/list/set → record-designer
+- graph/hypergraph/temporal/spatial → graph-designer
diff --git a/hyperextract-skills/graph-designer/SKILL.md b/hyperextract-skills/graph-designer/SKILL.md
index 5368c22..e66f2a0 100644
--- a/hyperextract-skills/graph-designer/SKILL.md
+++ b/hyperextract-skills/graph-designer/SKILL.md
@@ -1,358 +1,154 @@
---
name: hyper-extract-graph-designer
description: |
- Hyper-Extract Graph Designer. Designs structure, identifiers, display, and extraction rules for graph/hypergraph/temporal/spatial types.
-
- ## Applicable Types
- - graph: Binary relations
- - hypergraph: Multi-entity relations
- - temporal_graph: + time dimension
- - spatial_graph: + space dimension
- - spatio_temporal_graph: + time + space
-
- ## Complete Output
- - output.entities
- - output.relations
- - guideline
- - identifiers
- - display
+ Graph Type Designer for Hyper-Extract. Generates YAML for graph/hypergraph types.
+ Use after brainstorm with design draft.
---
# Graph Designer: graph/hypergraph/temporal/spatial
-## Type Confirmation
-
-- **graph**: Simple binary relations (A→B)
-- **hypergraph**: Multi-party relations (A+B+C→D)
-- **temporal_graph**: Binary relations + time
-- **spatial_graph**: Binary relations + space
-- **spatio_temporal_graph**: Binary relations + time + space
-
-## Part 1: Entity Design (output.entities)
-
-### Standard Entity Fields
-
-```yaml
-entities:
- description: 'Node/entity definitions'
- fields:
- - name: name
- type: str
- description: 'Entity name (unique identifier)'
- - name: category
- type: str
- description: 'Entity type/category'
- - name: description
- type: str
- description: 'Brief description'
- required: false
- default: ''
-```
-
-### Multi-Type Node Considerations
-
-If nodes can have multiple categories:
-
-```yaml
- - name: category
- type: list
- description: 'Entity types (can be multiple)'
-```
-
-### Domain-Specific Fields
-
-Add fields based on your domain:
+## Input from Brainstorm
-```yaml
- - name: role
- type: str
- description: 'Role in current context'
- required: false
- default: ''
-```
-
-## Part 2: Relation Design (output.relations)
-
-### For graph/temporal/spatial (Binary Relations)
-
-```yaml
-relations:
- description: 'Edge/relation definitions'
- fields:
- - name: source
- type: str
- description: 'Source entity name'
- - name: target
- type: str
- description: 'Target entity name'
- - name: relation_type
- type: str
- description: 'Type of relationship'
-```
+Receive design specs from brainstorm:
+- Entity types and fields
+- Relation types and fields
+- Hypergraph grouping strategy
+- Time/location requirements
-### Predefined Relation Types
+## Workflow
-Common types (can be customized):
+1. **Confirm type** based on brainstorm specs
+2. **Design entities** (output.entities)
+3. **Design relations** (output.relations)
+4. **Configure identifiers** (identifiers)
+5. **Set display** (display)
+6. **Write guideline** (guideline)
+7. **Review and output YAML**
-| Category | Relation Types |
-|----------|---------------|
-| Social | owns, works_for, married_to, parent_of |
-| Organizational | subsidiary_of, competitor_of, partner_with |
-| Causal | causes, enables, prevents, leads_to |
-| Spatial | located_at, adjacent_to, part_of |
-| Temporal | preceded_by, followed_by, concurrent_with |
-
-### For hypergraph (Multi-Entity Relations)
-
-```yaml
-relations:
- description: 'Hyperedge definitions'
- fields:
- - name: relation_type
- type: str
- description: 'Type of relationship'
- - name: participants
- type: list
- description: 'List of participating entity names'
- - name: outcome
- type: str
- description: 'Result or conclusion'
- - name: reasoning
- type: str
- description: 'Explanation or evidence'
- required: false
- default: ''
-```
-
-### For temporal_graph (Add time field on edges)
+## Type Confirmation
-```yaml
- - name: event_date
- type: str
- description: 'When the relation occurred'
- required: false
- default: ''
-```
+| Type | relation_members | Additional Config |
+|------|-----------------|-------------------|
+| graph | `{source, target}` | - |
+| hypergraph (simple) | `participants` (string) | - |
+| hypergraph (nested) | `[group_a, group_b]` (list) | - |
+| temporal_graph | + type | `time_field` |
+| spatial_graph | + type | `location_field` |
+| spatio_temporal | + both | `time_field` + `location_field` |
-### For spatial_graph (Add location field on edges)
+## Output Template
```yaml
- - name: location
- type: str
- description: 'Where the relation occurred'
- required: false
- default: ''
-```
+language: en
-## Part 3: Extraction Rules (guideline)
+name: [TemplateName]
+type: [type]
+tags: [...]
+description: '...'
-### Target Setting
+output:
+ entities:
+ description: '...'
+ fields:
+ - name: name
+ type: str
+ - name: category
+ type: str
+ relations:
+ description: '...'
+ fields:
+ # Type-specific fields
-```yaml
guideline:
- target: 'You are a [domain] expert. Extract knowledge graph from text.'
-```
+ target: 'You are a [domain] expert...'
+ rules_for_entities: [...]
+ rules_for_relations: [...]
-### Entity Extraction Rules
-
-```yaml
- rules_for_entities:
- - 'Entity names must match exactly with text'
- - 'Each entity must have a clear category'
- - 'Only extract entities explicitly mentioned'
-```
-
-### Relation Extraction Rules
-
-```yaml
- rules_for_relations:
- - 'Only create edges for explicitly stated relations'
- - 'source and target must reference extracted entities'
- - 'Use predefined relation types when possible'
-```
-
-### For temporal_graph (Time handling rules)
-
-```yaml
- rules_for_time:
- - 'Observation time: {observation_time}'
- - 'Absolute dates: Keep as-is (e.g., 2024-01-01)'
- - 'Relative time: Convert to absolute (last year → previous year from observation)'
- - 'Fuzzy time: Leave empty, do not guess'
-```
-
-### For spatial_graph (Location handling rules)
+identifiers:
+ entity_id: name
+ relation_id: '...'
+ relation_members: ...
-```yaml
- rules_for_location:
- - 'Observation location: {observation_location}'
- - 'Structured locations: Keep as-is (e.g., Beijing, China)'
- - 'Fuzzy locations: Use observation_location (here → observation)'
- - 'Coordinates: Keep as-is'
+display:
+ entity_label: '{name} ({category})'
+ relation_label: '...'
```
-## Part 4: Identifier Rules (identifiers)
+## Quick Config Reference
-### For binary relations (graph/temporal/spatial)
+### Binary Relations (graph)
```yaml
identifiers:
- entity_id: name
- relation_id: '{source}|{relation_type}|{target}'
relation_members:
source: source
target: target
```
-### For hypergraph
-
-The `relation_members` is a **string** pointing to the participants field name (type: list).
+### Hypergraph Simple
```yaml
identifiers:
- entity_id: name
- relation_id: '{ruleType}|{action}'
- relation_members: participants # STRING, points to list field
+ relation_members: participants # STRING
```
-### For complex cases (relation_members as list)
-
-When a relation involves multiple sources of participants:
+### Hypergraph Nested
```yaml
identifiers:
- entity_id: name
- relation_id: '{relation_type}'
- relation_members: [source_participants, target_participants]
+ relation_members: [group_a, group_b] # LIST
```
-The system will unpack the lists and use the combined set as members.
-
-### For temporal_graph (Add time identifier)
+### Temporal
```yaml
+identifiers:
time_field: event_date
```
-### For spatial_graph (Add location identifier)
+### Spatial
```yaml
+identifiers:
location_field: location
```
-### Identifier Template Syntax
-
-- `{field_name}`: Insert field value
-- `{source}`: Source entity name
-- `{relation_type}`: Relation type
-- `{target}`: Target entity name
-
-## Part 5: Display Configuration (display)
-
-### For binary relations
+## Reference Files
-```yaml
-display:
- entity_label: '{name} ({category})'
- relation_label: '{relation_type}'
-```
+| 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) |
-### For hypergraph
-
-```yaml
-display:
- entity_label: '{name} ({category})'
- relation_label: '[{ruleType}] {outcome}'
-```
+---
## Design Checklist
### Entities
- [ ] Entity types cover key concepts?
- [ ] Entity granularity appropriate?
-- [ ] Multi-type nodes handled correctly?
+- [ ] Multi-type nodes handled?
- [ ] No redundant fields?
### Relations
- [ ] Relation types semantically clear?
-- [ ] source/target reference defined entities?
+- [ ] source/target reference entities?
- [ ] No ambiguous relations?
-### Hypergraph Specific
+### Hypergraph
- [ ] Participant count reasonable?
-- [ ] Outcome clearly defined?
-- [ ] Reasoning/evidence needed?
+- [ ] Grouping strategy clear?
+- [ ] Outcome defined?
### Identifiers
- [ ] entity_id references name field?
- [ ] relation_id template correct?
-- [ ] relation_members configured correctly (string for hypergraph)?
-- [ ] time_field/location_field specified for temporal/spatial?
-
-## Complete Output Example
-
-```yaml
-language: en
+- [ ] relation_members configured?
+- [ ] time/location_field specified?
-name: CompanyRelationshipGraph
-type: graph
-tags: [finance, corporate]
-description: 'Extract company ownership and relationship graphs'
-
-output:
- entities:
- description: 'Company and person entities'
- fields:
- - name: name
- type: str
- description: 'Entity name'
- - name: category
- type: str
- description: 'Entity type: Company, Person'
- - name: description
- type: str
- description: 'Brief description'
- required: false
- default: ''
- relations:
- description: 'Ownership and control relationships'
- fields:
- - name: source
- type: str
- description: 'Source entity'
- - name: target
- type: str
- description: 'Target entity'
- - name: relation_type
- type: str
- description: 'owns, controls, invested_in'
-
-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'
- - 'Names must match text exactly'
- rules_for_relations:
- - 'Only extract ownership and control relationships'
- - 'Common types: owns, controls, invested_in, subsidiary_of'
- - 'source and target must be extracted entities'
-
-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}'
-```
-
-## Next Steps
+---
-After graph design:
-1. Review with user
-2. Optional: yaml-validator
-3. Optional: multilingual
+See [examples.md](examples.md) for complete YAML examples.
diff --git a/hyperextract-skills/graph-designer/examples.md b/hyperextract-skills/graph-designer/examples.md
new file mode 100644
index 0000000..d15de41
--- /dev/null
+++ b/hyperextract-skills/graph-designer/examples.md
@@ -0,0 +1,183 @@
+# 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/reference-dimensions.md
new file mode 100644
index 0000000..5b23c6d
--- /dev/null
+++ b/hyperextract-skills/graph-designer/reference-dimensions.md
@@ -0,0 +1,136 @@
+# Dimension Design Reference
+
+Time and space dimension patterns. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Temporal Graph
+
+### Add Time Field to Relations
+
+```yaml
+relations:
+ fields:
+ - name: source
+ type: str
+ - name: target
+ type: str
+ - name: relation_type
+ type: str
+ - name: event_date
+ type: str
+ description: 'When the relation occurred'
+ required: false
+ default: ''
+```
+
+### Configure Time Identifier
+
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{relation_type}|{target}|{event_date}'
+ relation_members:
+ source: source
+ target: target
+ time_field: event_date
+```
+
+### Time Handling Rules
+
+```yaml
+guideline:
+ rules_for_time:
+ - 'Observation time: {observation_time}'
+ - 'Absolute dates: Keep as-is (e.g., 2024-01-01)'
+ - 'Relative time: Convert to absolute'
+ - 'Fuzzy time: Leave empty, do not guess'
+```
+
+---
+
+## Spatial Graph
+
+### Add Location Field to Relations
+
+```yaml
+relations:
+ fields:
+ - name: source
+ type: str
+ - name: target
+ type: str
+ - name: relation_type
+ type: str
+ - name: location
+ type: str
+ description: 'Where the relation occurred'
+ required: false
+ default: ''
+```
+
+### Configure Location Identifier
+
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{relation_type}|{target}|{location}'
+ relation_members:
+ source: source
+ target: target
+ location_field: location
+```
+
+### Location Handling Rules
+
+```yaml
+guideline:
+ rules_for_location:
+ - 'Observation location: {observation_location}'
+ - 'Structured: Keep as-is (e.g., Beijing, China)'
+ - 'Fuzzy: Use observation_location'
+ - 'Coordinates: Keep as-is'
+```
+
+---
+
+## Spatio-Temporal Graph
+
+Combines both dimensions:
+
+```yaml
+relations:
+ fields:
+ - name: source
+ type: str
+ - name: target
+ type: str
+ - name: relation_type
+ type: str
+ - name: event_date
+ type: str
+ - name: location
+ type: str
+
+identifiers:
+ time_field: event_date
+ location_field: location
+```
+
+---
+
+## Dimension Selection Checklist
+
+### Time Dimension?
+
+- [ ] Relation has temporal aspect?
+- [ ] Same entities can have multiple relations at different times?
+- [ ] Time is edge property, not node property?
+- [ ] **If 3+ yes → temporal_graph**
+
+### Location Dimension?
+
+- [ ] Relation has spatial aspect?
+- [ ] Same entities can have relations at different locations?
+- [ ] Location is edge property, not node property?
+- [ ] **If 3+ yes → spatial_graph**
diff --git a/hyperextract-skills/graph-designer/reference-entity.md b/hyperextract-skills/graph-designer/reference-entity.md
new file mode 100644
index 0000000..f55304a
--- /dev/null
+++ b/hyperextract-skills/graph-designer/reference-entity.md
@@ -0,0 +1,115 @@
+# Entity Design Reference
+
+Entity design patterns for graph types. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Basic Entity Fields
+
+```yaml
+entities:
+ description: 'Node/entity definitions'
+ fields:
+ - name: name
+ type: str
+ description: 'Entity name (unique identifier)'
+ - name: category
+ type: str
+ description: 'Entity type/category'
+ - name: description
+ type: str
+ description: 'Brief description'
+ required: false
+ default: ''
+```
+
+---
+
+## Multi-Type Nodes
+
+If nodes can have multiple categories:
+
+```yaml
+ - name: category
+ type: list
+ description: 'Entity types (can be multiple)'
+```
+
+---
+
+## Domain-Specific Fields
+
+Add fields based on your domain:
+
+```yaml
+ - name: role
+ type: str
+ description: 'Role in current context'
+ required: false
+ default: ''
+ - name: importance
+ type: str
+ description: 'Importance level: high, medium, low'
+ required: false
+ default: 'medium'
+```
+
+---
+
+## Common Patterns
+
+### Single Type Entities
+
+```yaml
+entities:
+ description: 'Organization entities'
+ fields:
+ - name: name
+ type: str
+ - name: description
+ type: str
+ required: false
+```
+
+### Multi-Type Entities
+
+```yaml
+entities:
+ description: 'Mixed entity types'
+ fields:
+ - name: name
+ type: str
+ - name: category
+ type: str
+ - name: description
+ type: str
+ required: false
+```
+
+### Typed Entities
+
+```yaml
+entities:
+ description: 'Typed entities'
+ fields:
+ - name: name
+ type: str
+ - name: entity_type
+ type: str
+ - name: subtype
+ type: str
+ required: false
+ - name: description
+ type: str
+ required: false
+```
+
+---
+
+## Design Principles
+
+1. **Name is primary**: Always include a name/identifier field
+2. **Category helps**: Include category for multi-type graphs
+3. **Description optional**: Add if entities need context
+4. **Domain fields**: Add domain-specific attributes as needed
+5. **Avoid redundancy**: Don't repeat information from relations
diff --git a/hyperextract-skills/graph-designer/reference-hypergraph.md b/hyperextract-skills/graph-designer/reference-hypergraph.md
new file mode 100644
index 0000000..973da2e
--- /dev/null
+++ b/hyperextract-skills/graph-designer/reference-hypergraph.md
@@ -0,0 +1,109 @@
+# Hypergraph Design Reference
+
+Hypergraph design patterns for graph types. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Simple Hypergraph
+
+Flat list of participants:
+
+```yaml
+relations:
+ description: 'Hyperedge definitions'
+ fields:
+ - name: event_name
+ type: str
+ description: 'Event/relation name'
+ - name: participants
+ type: list
+ description: 'List of participating entity names'
+ - name: action
+ type: str
+ description: 'What happened'
+ - name: outcome
+ type: str
+ description: 'Result or conclusion'
+ required: false
+```
+
+### Identifier Configuration
+
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{event_name}|{action}'
+ relation_members: participants # STRING
+```
+
+---
+
+## Nested Hypergraph (Semantic Grouping)
+
+Participants grouped by semantic role:
+
+```yaml
+relations:
+ description: 'Hyperedge with semantic grouping'
+ fields:
+ - name: event_name
+ type: str
+ - name: group_a
+ type: list
+ description: 'Group A participants'
+ - name: group_b
+ type: list
+ description: 'Group B participants'
+ - name: group_c
+ type: list
+ description: 'Group C participants'
+ required: false
+ - name: outcome
+ type: str
+ - name: reasoning
+ type: str
+ required: false
+```
+
+### Identifier Configuration
+
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{event_name}'
+ relation_members: [group_a, group_b, group_c] # LIST
+```
+
+---
+
+## Common Grouping Patterns
+
+| Scenario | Groups | Use Case |
+|----------|--------|----------|
+| Battle | attackers, defenders | Military conflicts |
+| Political | attackers, defenders, planners, turncoats | Political struggles |
+| Transaction | buyers, sellers, intermediaries | Commercial transactions |
+| Project | leaders, developers, designers, testers | Software projects |
+| Meeting | organizers, speakers, attendees | Business meetings |
+| Contract | parties, witnesses | Legal documents |
+| Negotiation | side_a, side_b, mediators | Diplomatic talks |
+
+---
+
+## Design Principles
+
+1. **Group Count**: 2-5 groups per hyperedge is ideal
+2. **Semantic Names**: Use meaningful role names
+3. **Avoid Overlap**: Members usually in one group
+4. **Consistent Structure**: Same groups across relations
+5. **Clear Outcomes**: Always include outcome field
+
+---
+
+## Design Checklist
+
+- [ ] How many semantic groups?
+- [ ] What are the group names?
+- [ ] Can members belong to multiple groups?
+- [ ] Is there an outcome/result?
+- [ ] Is reasoning needed?
diff --git a/hyperextract-skills/graph-designer/reference-relation.md b/hyperextract-skills/graph-designer/reference-relation.md
new file mode 100644
index 0000000..01ea913
--- /dev/null
+++ b/hyperextract-skills/graph-designer/reference-relation.md
@@ -0,0 +1,88 @@
+# Relation Design Reference
+
+Relation design patterns for graph types. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Binary Relations
+
+### Basic Structure
+
+```yaml
+relations:
+ description: 'Edge/relation definitions'
+ fields:
+ - name: source
+ type: str
+ description: 'Source entity name'
+ - name: target
+ type: str
+ description: 'Target entity name'
+ - name: relation_type
+ type: str
+ description: 'Type of relationship'
+```
+
+### With Properties
+
+```yaml
+relations:
+ fields:
+ - name: source
+ type: str
+ - name: target
+ type: str
+ - name: relation_type
+ type: str
+ - name: strength
+ type: str
+ required: false
+ - name: description
+ type: str
+ required: false
+```
+
+---
+
+## Common Relation Types
+
+| Category | Types |
+|----------|-------|
+| Social | owns, works_for, married_to, parent_of, sibling_of |
+| Organizational | subsidiary_of, competitor_of, partner_with, acquired_by |
+| Causal | causes, enables, prevents, leads_to, results_in |
+| Spatial | located_at, adjacent_to, part_of, contains |
+| Temporal | preceded_by, followed_by, concurrent_with, overlaps |
+| Dependency | depends_on, requires, imports, exports |
+
+---
+
+## Identifier Configuration
+
+### Binary Relations
+
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{relation_type}|{target}'
+ relation_members:
+ source: source
+ target: target
+```
+
+### Identifier Template Syntax
+
+- `{field_name}`: Insert field value
+- `{source}`: Source entity name
+- `{relation_type}`: Relation type
+- `{target}`: Target entity name
+
+---
+
+## Design Principles
+
+1. **Source and Target**: Required for binary relations
+2. **Relation Type**: Use predefined or custom types
+3. **Properties**: Add optional fields for edge attributes
+4. **Clear Names**: Use semantic relation type names
+5. **Consistency**: Keep relation types consistent
diff --git a/hyperextract-skills/record-designer/SKILL.md b/hyperextract-skills/record-designer/SKILL.md
index 24266d4..2543383 100644
--- a/hyperextract-skills/record-designer/SKILL.md
+++ b/hyperextract-skills/record-designer/SKILL.md
@@ -1,115 +1,96 @@
---
name: hyper-extract-record-designer
description: |
- Hyper-Extract Record Designer. Designs structure, identifiers, display, and extraction rules for model/list/set types.
-
- ## Applicable Types
- - model: Single object
- - list: Object list
- - set: Deduplicated set
-
- ## Complete Output
- - output.fields
- - guideline (target + rules)
- - identifiers.item_id (set only)
- - display.label
+ Record Type Designer for Hyper-Extract. Generates YAML for model/list/set types.
+ Use after brainstorm with design draft.
---
# Record Designer: model/list/set
-## Type Confirmation
-
-- **model**: Extract a single complete object
-- **list**: Extract list of homogeneous objects
-- **set**: Extract deduplicated set of objects
-
-## Part 1: Field Design (output.fields)
+## Input from Brainstorm
-### Field Definition Template
-
-```yaml
-output:
- description: 'Output structure description'
- fields:
- - name: field_name # snake_case, must be unique
- type: str/int/float/list # data type
- description: 'What this field means'
- required: true/false # is this mandatory?
- default: 'value' # default when missing
-```
+Receive design specs from brainstorm:
+- What fields to extract
+- Field types and requirements
+- Deduplication needs (for set)
-### Field Type Guidelines
+## Workflow
-| Type | Use When | Example |
-|------|----------|---------|
-| str | Text values | names, descriptions |
-| int | Whole numbers | counts, years |
-| float | Decimal numbers | prices, percentages |
-| list | Multiple values | tags, categories |
+1. **Confirm type** (model/list/set)
+2. **Design fields** (output.fields)
+3. **Configure identifiers** (identifiers.item_id for set)
+4. **Set display** (display.label)
+5. **Write guideline** (guideline)
+6. **Review and output YAML**
-### Usually Needed Fields
+## Type Confirmation
-- At minimum, most records need a `name` or `title` field
+| Type | Identifiers | Use Case |
+|------|-------------|----------|
+| model | Not needed | Single object |
+| list | Not needed | Ordered items |
+| set | `item_id` required | Deduplicated entities |
-### Optional Fields
+## Output Template
-- description: Brief explanation
-- category: Type or classification
-- Domain-specific fields
+```yaml
+language: en
-## Part 2: Extraction Rules (guideline)
+name: [TemplateName]
+type: [model/list/set]
+tags: [...]
+description: '...'
-### Target Setting
+output:
+ description: '...'
+ fields:
+ - name: field_name
+ type: str/int/float/list
+ description: '...'
+ required: true/false
+ default: '...'
-```yaml
guideline:
- target: 'You are a [domain] expert. Extract [goal] from text.'
-```
+ target: 'You are a [domain] expert...'
+ rules: [...]
-### Rules for Records
+identifiers: {} # Or item_id for set
-```yaml
- rules:
- - 'Rule 1: What to extract'
- - 'Rule 2: How to handle edge cases'
- - 'Rule 3: Quality standards'
+display:
+ label: '{field_name}'
```
-### Rule Writing Guidelines
-
-1. Be specific about what to extract
-2. Include edge case handling
-3. Set quality standards
-4. Prioritize important rules first
+## Type-Specific Output
-## Part 3: Identifier Rules (identifiers)
-
-### For set types, configure deduplication:
+### model
```yaml
-identifiers:
- item_id: field_name # Deduplicate based on this field
+type: model
+identifiers: {} # Not needed
```
-### For model/list types:
-
-Usually not needed, or use empty:
+### list
```yaml
-identifiers: {}
+type: list
+identifiers: {} # Not needed
```
-## Part 4: Display Configuration (display)
+### set
```yaml
-display:
- label: '{field_name}' # How to display each record
+type: set
+identifiers:
+ item_id: [deduplication field]
```
-### Label Template Syntax
+## Reference Files
-- `{field_name}`: Insert field value
-- Example: `'{company_name}'` → "Acme Corp"
+| 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) |
## Design Checklist
@@ -120,49 +101,6 @@ display:
- [ ] For set: item_id can uniquely identify records?
- [ ] Display label references correct fields?
-## Complete Output Example
-
-```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: ''
-
-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}'
-```
-
-## Next Steps
+---
-After record design:
-1. Review with user
-2. Optional: yaml-validator
-3. Optional: multilingual
+See [examples.md](examples.md) for complete YAML examples.
diff --git a/hyperextract-skills/record-designer/examples.md b/hyperextract-skills/record-designer/examples.md
new file mode 100644
index 0000000..0e53459
--- /dev/null
+++ b/hyperextract-skills/record-designer/examples.md
@@ -0,0 +1,132 @@
+# 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/reference-field.md
new file mode 100644
index 0000000..687be82
--- /dev/null
+++ b/hyperextract-skills/record-designer/reference-field.md
@@ -0,0 +1,87 @@
+# Field Design Reference
+
+Field design patterns for record types. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Field Definition Template
+
+```yaml
+output:
+ description: 'Output structure description'
+ fields:
+ - name: field_name # snake_case, must be unique
+ type: str/int/float/list # data type
+ description: 'What this field captures'
+ required: true/false # is this mandatory?
+ default: 'value' # default when missing
+```
+
+---
+
+## Field Type Guidelines
+
+| Type | Use When | Example |
+|------|----------|---------|
+| str | Text values | names, descriptions |
+| int | Whole numbers | counts, years |
+| float | Decimal numbers | prices, percentages |
+| list | Multiple values | tags, categories |
+
+---
+
+## Common Patterns
+
+### Information Card
+
+```yaml
+output:
+ fields:
+ - name: title
+ type: str
+ required: true
+ - name: category
+ type: str
+ - name: description
+ type: str
+ - name: tags
+ type: list
+ required: false
+```
+
+### Structured Record
+
+```yaml
+output:
+ fields:
+ - name: name
+ type: str
+ - name: status
+ type: str
+ - name: value
+ type: float
+ - name: notes
+ type: str
+ required: false
+```
+
+### Ordered List
+
+```yaml
+output:
+ fields:
+ - name: order
+ type: int
+ - name: item
+ type: str
+```
+
+---
+
+## Design Principles
+
+1. **Clear Names**: Use snake_case, semantic names
+2. **Appropriate Types**: Match data type to content
+3. **Required vs Optional**: Only required if truly needed
+4. **Safe Defaults**: Provide meaningful defaults
+5. **Complete Descriptions**: Explain what field captures
diff --git a/hyperextract-skills/record-designer/reference-identifier.md b/hyperextract-skills/record-designer/reference-identifier.md
new file mode 100644
index 0000000..ef2b630
--- /dev/null
+++ b/hyperextract-skills/record-designer/reference-identifier.md
@@ -0,0 +1,70 @@
+# Identifier Design Reference
+
+Identifier configuration for record types. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## When Identifiers Are Needed
+
+| Type | Identifiers Needed | Purpose |
+|------|-------------------|---------|
+| model | No | Single object, no deduplication |
+| list | No | Ordered items, position-based |
+| set | **Yes** | Deduplication required |
+
+---
+
+## Set Type: Deduplication Key
+
+### Single Field Deduplication
+
+```yaml
+identifiers:
+ item_id: name # Deduplicate based on name field
+```
+
+### Multi-Field Deduplication
+
+```yaml
+identifiers:
+ item_id: '{name}|{category}' # Deduplicate by combination
+```
+
+---
+
+## Model/List Types
+
+Usually not needed:
+
+```yaml
+identifiers: {}
+```
+
+Or simply omit:
+
+```yaml
+# identifiers field not present
+```
+
+---
+
+## Label Template Syntax
+
+```yaml
+display:
+ label: '{field_name}' # How to display each record
+```
+
+Examples:
+- `'{name}'` → "Company ABC"
+- `'{name} - {category}'` → "Company ABC - Technology"
+- `'{order}. {item}'` → "1. First item"
+
+---
+
+## Design Principles
+
+1. **For Set**: Choose a field that uniquely identifies each record
+2. **Multi-Field**: Use template syntax for combined keys
+3. **For Display**: Create human-readable labels
+4. **Consistency**: Keep label templates consistent
diff --git a/hyperextract-skills/yaml-validator/SKILL.md b/hyperextract-skills/yaml-validator/SKILL.md
index 871b656..6226dc7 100644
--- a/hyperextract-skills/yaml-validator/SKILL.md
+++ b/hyperextract-skills/yaml-validator/SKILL.md
@@ -1,143 +1,76 @@
---
name: hyper-extract-yaml-validator
description: |
- Hyper-Extract YAML Validator. Checks configuration completeness, correctness, and best practices.
-
- ## Validation Levels
- - ERROR: Must fix, otherwise won't work
- - WARNING: Should fix, may affect quality
- - INFO: Reference info, recommended to follow
+ YAML Validator for Hyper-Extract. Validates configuration syntax and structure.
+ Use optional after design to check for errors.
---
# YAML Validator
-## Validation Checklist
-
-### 1. Required Fields
-
-- [ ] language
-- [ ] name
-- [ ] type (one of 8 valid types)
-- [ ] tags
-- [ ] description
-- [ ] output
-- [ ] guideline
-
-### 2. Type-Specific Validation
-
-#### Record Types
-
-```yaml
-output:
- description: '...' # ✓ Exists
- fields: # ✓ Exists
- - name: ... # ✓ Each field has name
- type: ... # ✓ Has type
- description: ... # ✓ Has description
-```
-
-#### Graph Types
-
-```yaml
-output:
- entities: # ✓ Exists
- description: '...'
- fields:
- - name: name
- - name: category
- relations: # ✓ Exists
- description: '...'
- fields:
- - name: source # ✓ Binary relations
- - name: target # ✓ OR
- - name: participants # ✓ Hypergraph
-```
+## Validation Workflow
-#### Temporal Graph
+1. **Syntax check**: YAML is valid
+2. **Required fields**: All required fields present
+3. **Type check**: Valid AutoType value
+4. **Identifiers check**: Proper configuration for type
+5. **Field validation**: Types and descriptions present
-```yaml
-identifiers:
- time_field: '...' # ✓ Must exist
-```
+## Quick Validation Checklist
-#### Spatial Graph
+### All Types
```yaml
-identifiers:
- location_field: '...' # ✓ Must exist
+- [ ] language: zh/en
+- [ ] name: PascalCase
+- [ ] type: valid AutoType
+- [ ] tags: lowercase array
+- [ ] description: non-empty
+- [ ] output: exists
+- [ ] guideline: exists
```
-### 3. Field Value Validation
-
-| Field | Valid Values | Common Errors |
-|-------|-------------|---------------|
-| type | model, list, set, graph, hypergraph, temporal_graph, spatial_graph, spatio_temporal_graph | Typo: "graphh" |
-| language | Single: zh/en; Multi: [zh, en] | Non-standard: "chinese" |
-| extraction_mode | one_stage, two_stage | Typo: "two-stage" |
-
-### 4. Naming Conventions
-
-- [ ] name: PascalCase (e.g., EarningsCallSummary)
-- [ ] tags: lowercase (e.g., [finance, medicine])
-- [ ] field names: snake_case (e.g., company_name)
-- [ ] relation_type: Usually Chinese (e.g., 拥有, 影响)
-
-### 5. Identifiers Configuration
-
-#### Binary Relations
+### Graph Types
```yaml
-identifiers:
- entity_id: name # ✓ References entity field
- relation_id: '{source}|...' # ✓ Template syntax correct
- relation_members: # ✓ Map correctly
- source: source
- target: target
+- [ ] output.entities: exists
+- [ ] output.relations: exists
+- [ ] identifiers.entity_id: exists
+- [ ] identifiers.relation_id: exists
+- [ ] identifiers.relation_members: configured
```
-#### Hypergraph
+### Hypergraph
```yaml
-identifiers:
- entity_id: name
- relation_id: '{ruleType}|{action}'
- relation_members: participants # ✓ STRING, not dict
+- [ ] relation_members is string OR list
+- [ ] If list: all fields are type: list
```
-#### Complex (relation_members as list)
+### Temporal/Spatial
```yaml
-identifiers:
- entity_id: name
- relation_id: '{relation_type}'
- relation_members: [field1, field2] # ✓ List of field names
-```
-
-## Error Messages
-
-### Missing Required Field
-
-```
-ERROR: Missing required field 'output'
-Fix: Add output field definition
+- [ ] identifiers.time_field: configured (temporal)
+- [ ] identifiers.location_field: configured (spatial)
```
-### Invalid Type Value
+## Validation Levels
-```
-ERROR: type value 'graphh' is not valid
-Valid values: model, list, set, graph, hypergraph, temporal_graph, spatial_graph, spatio_temporal_graph
-Fix: Correct to 'graph'
-```
+| Level | Meaning | Action |
+|-------|---------|--------|
+| ERROR | Must fix | Won't work without fix |
+| WARNING | Should fix | May affect quality |
+| INFO | Reference | Recommended to follow |
-### Missing Identifiers
+## Reference Files
-```
-ERROR: graph type requires identifiers.relation_members
-Fix: Add relation_members configuration
-```
+| 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) |
-## Output Format
+## Error Message Format
```markdown
## Validation Results
@@ -156,18 +89,13 @@ Fix: Add relation_members configuration
### Semantic Validation
⚠️ 2 warnings
-- WARNING: 'company_name' field description too brief
-- WARNING: Missing options.extraction_mode, recommend 'two_stage'
-
-### Best Practices
-⚠️ 1 suggestion
-- INFO: Consider adding identifiers for better deduplication
+- WARNING: [message]
+- WARNING: [message]
### Overall Assessment
-✅ Configuration valid, ready for Hyper-Extract
+✅ Configuration valid
+```
-## Fix Suggestions
+---
-1. Add extraction_mode: 'two_stage' to options
-2. Expand 'company_name' description to be more specific
-```
+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/patterns-errors.md
new file mode 100644
index 0000000..f762ffd
--- /dev/null
+++ b/hyperextract-skills/yaml-validator/patterns-errors.md
@@ -0,0 +1,121 @@
+# Common Error Patterns
+
+Common YAML configuration errors and fixes. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Missing Required Field
+
+```
+ERROR: Missing required field 'output'
+Fix: Add output field definition
+```
+
+**Fix**:
+```yaml
+output:
+ description: '...'
+ fields:
+ - name: field1
+ type: str
+```
+
+---
+
+## Invalid Type Value
+
+```
+ERROR: type value 'graphh' is not valid
+Valid values: model, list, set, graph, hypergraph, temporal_graph, spatial_graph, spatio_temporal_graph
+Fix: Correct to 'graph'
+```
+
+**Fix**:
+```yaml
+type: graph # Correct
+```
+
+---
+
+## Missing Identifiers
+
+```
+ERROR: graph type requires identifiers.relation_members
+Fix: Add relation_members configuration
+```
+
+**Fix**:
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{source}|{relation_type}|{target}'
+ relation_members:
+ source: source
+ target: target
+```
+
+---
+
+## Hypergraph Grouping Errors
+
+### ❌ Field type should be list
+
+```yaml
+# Wrong
+- name: attackers
+ type: str
+
+# Correct
+- name: attackers
+ type: list
+```
+
+### ❌ Format mismatch
+
+```yaml
+# Wrong: participants is str, but using list format
+relation_members: [participants]
+
+# Correct: simple hypergraph
+relation_members: participants
+
+# Correct: nested hypergraph
+relation_members: [attackers, defenders]
+```
+
+---
+
+## Missing Time/Location Field
+
+```
+ERROR: temporal_graph requires identifiers.time_field
+Fix: Add time_field configuration
+```
+
+**Fix**:
+```yaml
+identifiers:
+ time_field: event_date
+```
+
+---
+
+## Naming Convention Errors
+
+| Error | Fix |
+|-------|-----|
+| name: "earnings_call" | name: "EarningsCall" |
+| tags: [Finance] | tags: [finance] |
+| field_name: "companyName" | field_name: "company_name" |
+
+---
+
+## Quick Reference
+
+| Error | Quick Fix |
+|-------|-----------|
+| Missing output | Add output section |
+| Invalid type | Check valid types |
+| Missing identifiers | Add identifiers section |
+| Wrong relation_members type | String vs List |
+| Missing time_field | Add to identifiers |
diff --git a/hyperextract-skills/yaml-validator/rules-identifiers.md b/hyperextract-skills/yaml-validator/rules-identifiers.md
new file mode 100644
index 0000000..77ffc73
--- /dev/null
+++ b/hyperextract-skills/yaml-validator/rules-identifiers.md
@@ -0,0 +1,75 @@
+# Identifier Validation Rules
+
+Identifier configuration validation. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Binary Relations (graph/temporal/spatial)
+
+```yaml
+identifiers:
+ entity_id: name # ✓ References entity field
+ relation_id: '{source}|...' # ✓ Template syntax correct
+ relation_members: # ✓ Map correctly
+ source: source
+ target: target
+```
+
+---
+
+## Hypergraph
+
+### Simple Hypergraph
+
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{ruleType}|{action}'
+ relation_members: participants # STRING
+```
+
+### Nested Hypergraph
+
+```yaml
+identifiers:
+ entity_id: name
+ relation_id: '{event_name}'
+ relation_members: [attackers, defenders] # LIST
+```
+
+---
+
+## Temporal Graph
+
+```yaml
+identifiers:
+ time_field: event_date # ✓ Must exist
+```
+
+---
+
+## Spatial Graph
+
+```yaml
+identifiers:
+ location_field: location # ✓ Must exist
+```
+
+---
+
+## Common Identifier Errors
+
+1. **Missing identifiers**: Required but not present
+2. **Wrong format**: relation_members type mismatch
+3. **Invalid reference**: Referenced field doesn't exist
+4. **Missing time/location field**: Required for temporal/spatial
+
+---
+
+## Validation Checklist
+
+- [ ] identifiers.entity_id exists
+- [ ] identifiers.relation_id exists
+- [ ] identifiers.relation_members configured
+- [ ] time_field configured (temporal types)
+- [ ] location_field configured (spatial types)
diff --git a/hyperextract-skills/yaml-validator/rules-syntax.md b/hyperextract-skills/yaml-validator/rules-syntax.md
new file mode 100644
index 0000000..7930f3d
--- /dev/null
+++ b/hyperextract-skills/yaml-validator/rules-syntax.md
@@ -0,0 +1,84 @@
+# Syntax Validation Rules
+
+Syntax validation for YAML configurations. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Required Fields
+
+All configurations must have:
+
+```yaml
+- [ ] language: zh/en
+- [ ] name: PascalCase
+- [ ] type: valid AutoType
+- [ ] tags: lowercase array
+- [ ] description: non-empty string
+- [ ] output: exists
+- [ ] guideline: exists
+```
+
+---
+
+## Naming Conventions
+
+| Field | Convention | Example |
+|-------|-----------|---------|
+| name | PascalCase | `EarningsCallSummary` |
+| tags | lowercase array | `[finance, earnings]` |
+| field names | snake_case | `company_name` |
+
+---
+
+## Valid AutoType Values
+
+```
+model, list, set, graph, hypergraph,
+temporal_graph, spatial_graph, spatio_temporal_graph
+```
+
+Common errors:
+- Typo: `"graphh"` → should be `"graph"`
+- Non-standard: `"binary_graph"` → not valid
+
+---
+
+## YAML Structure
+
+### Required Structure
+
+```yaml
+language: en
+name: TemplateName
+type: [type]
+tags: [...]
+description: '...'
+output: {...}
+guideline: {...}
+```
+
+### Optional Structure
+
+```yaml
+identifiers: {...}
+display: {...}
+options: {...}
+```
+
+---
+
+## Common Syntax Errors
+
+1. **Invalid YAML**: Missing colon, incorrect indentation
+2. **Missing quotes**: Special characters in strings
+3. **Type errors**: Wrong type for field value
+4. **Missing required fields**: Required fields not present
+
+---
+
+## Validation Tips
+
+1. Check YAML is valid first
+2. Verify all required fields present
+3. Check naming conventions
+4. Validate field value types
diff --git a/hyperextract-skills/yaml-validator/rules-types.md b/hyperextract-skills/yaml-validator/rules-types.md
new file mode 100644
index 0000000..3987978
--- /dev/null
+++ b/hyperextract-skills/yaml-validator/rules-types.md
@@ -0,0 +1,82 @@
+# Type-Specific Validation Rules
+
+Type-specific validation for YAML configurations. See [SKILL.md](SKILL.md) for workflow.
+
+---
+
+## Record Types (model/list/set)
+
+```yaml
+output:
+ description: '...' # ✓ Exists
+ fields: # ✓ Exists
+ - name: ... # ✓ Each field has name
+ type: ... # ✓ Has type
+ description: ... # ✓ Has description
+```
+
+### model
+
+- No identifiers needed
+- Single output structure
+
+### list
+
+- No identifiers needed
+- Ordered items
+
+### set
+
+- identifiers.item_id required
+- Deduplication key
+
+---
+
+## Graph Types
+
+```yaml
+output:
+ entities: # ✓ Exists
+ description: '...'
+ fields:
+ - name: name
+ - name: category
+ relations: # ✓ Exists
+ description: '...'
+ fields:
+ - name: source # ✓ Binary relations
+ - name: target # ✓ OR
+ - name: participants # ✓ Hypergraph
+```
+
+### graph
+
+- Binary relations (source/target)
+- identifiers with {source, target}
+
+### hypergraph
+
+- Multi-entity relations
+- identifiers.relation_members: string OR list
+
+### temporal_graph
+
+- identifiers.time_field required
+
+### spatial_graph
+
+- identifiers.location_field required
+
+### spatio_temporal_graph
+
+- Both time_field and location_field required
+
+---
+
+## Field Value Validation
+
+| Field | Valid Values | Common Errors |
+|-------|-------------|---------------|
+| type | 8 valid types | Typo: "graphh" |
+| language | zh/en or [zh, en] | Non-standard: "chinese" |
+| extraction_mode | one_stage, two_stage | Typo: "two-stage" |
diff --git a/hyperextract/templates/presets/general/base_temporal_graph.yaml b/hyperextract/templates/presets/general/base_temporal_graph.yaml
index dac0752..e8ac4d9 100644
--- a/hyperextract/templates/presets/general/base_temporal_graph.yaml
+++ b/hyperextract/templates/presets/general/base_temporal_graph.yaml
@@ -1,60 +1,76 @@
-language: zh
+language: [zh, en]
+
name: base_temporal_graph
type: temporal_graph
tags: [general]
+
description:
zh: '基础时序图谱模板 - 从文本中提取实体之间的关系,并在文本提供时间信息时为关系补充时间属性,用于表达事实、事件或状态的连接及其时间上下文。'
+ en: 'Base Temporal Graph Template - Extracts relationships between entities from text and supplements temporal attributes to relations when time information is provided, expressing the connections of facts, events, or states with their temporal context.'
output:
- description:
+ description:
zh: '包含实体节点、关系边及可选时间信息的时序图谱结构。'
+ en: 'Temporal graph structure containing entity nodes, relation edges, and optional temporal information.'
entities:
- description:
+ description:
zh: '文本中可独立识别、可参与关系连接的实体节点。'
+ en: 'Entity nodes that can be independently identified and participate in relation connections in the text.'
fields:
- name: name
type: str
description:
zh: '实体名称,使用文本中最明确、最稳定的称呼。'
+ en: 'Entity name, using the most explicit and stable designation in the text.'
- name: type
type: str
description:
zh: '实体类型,如人物、地点、组织、物品、概念、事件、制度、其他。'
+ en: 'Entity type, such as person, location, organization, object, concept, event, institution, or other.'
- name: description
type: str
description:
zh: '对实体身份、含义或其在当前文本中作用的简要说明。'
+ en: 'Brief description of the entity identity, meaning, or its role in the current text.'
required: false
+
relations:
- description:
+ description:
zh: '实体之间的关系边;若文本提供时间,可在关系上补充时间属性。'
+ en: 'Relation edges between entities; temporal attributes can be added to relations if the text provides time information.'
fields:
- name: source
type: str
description:
zh: '关系起点实体,必须对应已提取实体的 name。'
+ en: 'Source entity of the relation, must correspond to the name of an extracted entity.'
- name: target
type: str
description:
zh: '关系终点实体,必须对应已提取实体的 name。'
+ en: 'Target entity of the relation, must correspond to the name of an extracted entity.'
- name: eventType
type: str
description:
zh: '关系类型,用简洁词语概括两个实体之间的连接方式。'
+ en: 'Relation type, concisely describing the connection between two entities.'
- name: eventDate
type: str
description:
zh: '关系对应的时间;无明确时间时可留空。'
+ en: 'Time associated with the relation; can be left empty if no explicit time is available.'
required: false
- name: details
type: str
description:
zh: '对关系的简要补充说明;无额外信息时可留空。'
+ en: 'Brief supplementary explanation for the relation; can be left empty if no additional information is available.'
required: false
guideline:
target:
zh: '你是一位时序知识图谱构建专家。请从文本中提取关键实体,以及这些实体之间的关系;如果文本提供了明确时间,再为关系补充时间属性。'
+ en: 'You are an expert in temporal knowledge graph construction. Extract key entities and their relationships from the text; if the text provides explicit time information, supplement temporal attributes to the relations.'
rules_for_entities:
zh:
- '提取对理解文本事实、事件过程和时间演变有价值,且能够参与关系连接的实体。'
@@ -62,6 +78,12 @@ guideline:
- 'name 使用原文中最稳定、最清晰的称呼;同一实体在全文中保持命名一致。'
- 'description 用 1 句话概括实体身份、含义或其在文本中的作用;信息不足时可留空。'
- '优先保留在文本中与其他实体存在明确联系的实体;对既不关键也没有明确关系支撑的边缘实体,可不提取。'
+ en:
+ - 'Extract entities that are valuable for understanding text facts, event processes, and temporal evolution, and that can participate in relation connections.'
+ - 'Assign appropriate types to each entity, such as person, location, organization, object, concept, event, institution, or other.'
+ - 'Use the most stable and clear designation in the source text for names; maintain consistent naming for the same entity throughout the text.'
+ - 'Use one sentence to summarize entity identity, meaning, or its role in the text; can be left empty if information is insufficient.'
+ - 'Prioritize retaining entities that have clear connections with other entities in the text; edge entities that are neither critical nor supported by explicit relations may be omitted.'
rules_for_relations:
zh:
- '仅在文本明确表达两个实体之间存在关系、事件或状态变化时创建关系边。'
@@ -71,21 +93,38 @@ guideline:
- 'eventDate 是可选字段;没有明确时间时也要保留关系边,并将 eventDate 留空。'
- 'details 只补充必要背景或结果,没有额外信息时可留空。'
- '无法确定具体关系对象时,不要强行构造边。'
+ en:
+ - 'Create relation edges only when the text explicitly expresses that a relationship, event, or state change exists between two entities.'
+ - 'Source and target must directly reference the name of an extracted entity; do not create new unextracted entities.'
+ - 'Extract the relation edge as long as the text supports the establishment of the relationship.'
+ - 'Use concise relational words for eventType, such as belongs to, located at, employed by, cooperates with, participates in, affects, publishes, signs, related to, etc.'
+ - 'eventDate is an optional field; retain the relation edge even without explicit time, and leave eventDate empty.'
+ - 'details should only supplement necessary background or results; can be left empty if no additional information is available.'
+ - 'Do not forcibly construct edges when the specific relation target cannot be determined.'
rules_for_time:
zh:
- '当前观察日期:{observation_time}'
- 'eventDate 是可选字段;仅在文本明确提供时间,或可依据相对时间可靠换算时填写。'
- '没有明确时间时,仍应保留关系边,并将 eventDate 留空。'
- - '相对时间以 observation_time 为基准解析,如“去年/今年/明年”“昨天/今天/明天”“十年前/五年后”。'
+ - '相对时间以 observation_time 为基准解析,如"去年/今年/明年""昨天/今天/明天""十年前/五年后"。'
- '若文本给出明确年份,则写为 YYYY;若给出完整日期,则写为 YYYY-MM-DD;保留文本可确定的最细粒度。'
- - '“年初/年末”可解析为当年 1 月 1 日或 12 月 31 日;朝代、时期名称或模糊历史时间可按原文保留。'
+ - '"年初/年末"可解析为当年 1 月 1 日或 12 月 31 日;朝代、时期名称或模糊历史时间可按原文保留。'
- '若时间只对应关系成立、变化或终止中的某一时点,则记录最直接相关的那个时间。'
- '无法可靠确定时间时留空,不要根据常识补写。'
+ en:
+ - 'Current observation date: {observation_time}'
+ - 'eventDate is an optional field; fill in only when the text explicitly provides time or when relative time can be reliably converted.'
+ - 'Retain the relation edge even without explicit time, and leave eventDate empty.'
+ - 'Parse relative time based on observation_time, such as "last year/this year/next year," "yesterday/today/tomorrow," "ten years ago/in five years."'
+ - 'If the text provides an explicit year, write as YYYY; if it provides a complete date, write as YYYY-MM-DD; preserve the finest granularity that can be determined from the text.'
+ - '"Beginning/end of year" can be parsed as January 1st or December 31st of that year; dynasty names, period names, or vague historical times can be kept in the original text.'
+ - 'If the time corresponds to only one point among the establishment, change, or termination of the relation, record the most directly relevant time.'
+ - 'Leave empty when time cannot be reliably determined; do not fill in based on common sense.'
identifiers:
entity_id: name
relation_id: '{source}|{eventType}|{details}'
- relation_members:
+ relation_members:
source: source
target: target
time_field: 'eventDate'