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.mdindex f4d9f49..65c78b1 100644--- a/hyperextract-skills/SKILL.md+++ b/hyperextract-skills/SKILL.md@@ -1,69 +1,105 @@---name: hyper-extractdescription: |- 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.mdindex ec4e8d6..fffeb17 100644--- a/hyperextract-skills/brainstorm/SKILL.md+++ b/hyperextract-skills/brainstorm/SKILL.md@@ -1,93 +1,134 @@---name: hyper-extract-brainstormdescription: |- 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-designerdiff --git a/hyperextract-skills/graph-designer/SKILL.md b/hyperextract-skills/graph-designer/SKILL.mdindex 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-designerdescription: |- 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-```yamlguideline:- 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)```yamlidentifiers:- entity_id: name- relation_id: '{source}|{relation_type}|{target}'relation_members:source: sourcetarget: target```-### For hypergraph--The `relation_members` is a **string** pointing to the participants field name (type: list).+### Hypergraph Simple```yamlidentifiers:- 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```yamlidentifiers:- 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 relationsdiff --git a/hyperextract-skills/graph-designer/reference-hypergraph.md b/hyperextract-skills/graph-designer/reference-hypergraph.mdnew file mode 100644index 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.mdnew file mode 100644index 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 consistentdiff --git a/hyperextract-skills/record-designer/SKILL.md b/hyperextract-skills/record-designer/SKILL.mdindex 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-designerdescription: |- 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: '...'-```yamlguideline:- 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 capturesdiff --git a/hyperextract-skills/record-designer/reference-identifier.md b/hyperextract-skills/record-designer/reference-identifier.mdnew file mode 100644index 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 consistentdiff --git a/hyperextract-skills/yaml-validator/SKILL.md b/hyperextract-skills/yaml-validator/SKILL.mdindex 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-validatordescription: |- 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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.mdnew file mode 100644index 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 typesdiff --git a/hyperextract-skills/yaml-validator/rules-types.md b/hyperextract-skills/yaml-validator/rules-types.mdnew file mode 100644index 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.yamlindex 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_graphtype: temporal_graphtags: [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: nametype: strdescription:zh: '实体名称,使用文本中最明确、最稳定的称呼。'+ en: 'Entity name, using the most explicit and stable designation in the text.'- name: typetype: strdescription:zh: '实体类型,如人物、地点、组织、物品、概念、事件、制度、其他。'+ en: 'Entity type, such as person, location, organization, object, concept, event, institution, or other.'- name: descriptiontype: strdescription: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: sourcetype: strdescription:zh: '关系起点实体,必须对应已提取实体的 name。'+ en: 'Source entity of the relation, must correspond to the name of an extracted entity.'- name: targettype: strdescription:zh: '关系终点实体,必须对应已提取实体的 name。'+ en: 'Target entity of the relation, must correspond to the name of an extracted entity.'- name: eventTypetype: strdescription:zh: '关系类型,用简洁词语概括两个实体之间的连接方式。'+ en: 'Relation type, concisely describing the connection between two entities.'- name: eventDatetype: strdescription:zh: '关系对应的时间;无明确时间时可留空。'+ en: 'Time associated with the relation; can be left empty if no explicit time is available.'required: false- name: detailstype: strdescription:zh: '对关系的简要补充说明;无额外信息时可留空。'+ en: 'Brief supplementary explanation for the relation; can be left empty if no additional information is available.'required: falseguideline: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: namerelation_id: '{source}|{eventType}|{details}'- relation_members:+ relation_members:source: sourcetarget: targettime_field: 'eventDate'