dialogue-graph
A library for building, validating, visualizing, and serializing dialogue graphs. Use this when parsing scripts or creating branching narrative structures.
- License 许可
- Apache-2.0
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- dialogue-graph
- description
- A library for building, validating, visualizing, and serializing dialogue graphs. Use this when parsing scripts or creating branching narrative structures.
02 资源文件 1
- 脚本scripts/dialogue_graph.py5.7 KB
03 SKILL.md 正文
Dialogue Graph Skill
This skill provides a dialogue_graph module to easily build valid dialogue trees/graphs.
When to use
- Script Parsers: When converting text to data.
- Dialogue Editors: When building tools to edit conversation flow.
- Game Logic: When traversing a dialogue tree.
- Visualization: When generating visual diagrams of dialogue flows.
Output schema (important)
Many Dialogue Graph tasks (including SkillBench-style verifiers) expect this JSON shape:
{
"nodes": [{"id": "", "text": "", "speaker": "", "type": "line|choice"}],
"edges": [{"from": "", "to": "", "text": ""}]
}
Be careful with naming:
- Use edge keys
fromandtoin exported JSON. - Node fields are
id,text,speaker,type.
Terminal node convention: End
Some evaluators treat a terminal target named exactly "End" as a special sink:
- Edges may point to
"End". - The evaluator may not require an explicit
"End"node to exist. - The evaluator may exclude
"End"from reachability traversal.
Practical guidance for maximum compatibility:
- Prefer not to include an explicit node with
id == "End"unless you know the evaluator expects it. - If you do include an
Endnode, ensure your own validation logic matches the evaluator’s expectations; otherwise you can create a graph that is internally “valid” but fails external reachability checks.
How to use
Import the module:
from dialogue_graph import Graph, Node, Edge
1. The Graph Class
The main container.
graph = Graph()
2. Adding Nodes
Define content nodes.
# Regular line
graph.add_node(Node(id="Start", speaker="Guard", text="Halt!", type="line"))
# Choice hub
graph.add_node(Node(id="Choices", type="choice"))
3. Adding Edges
Connect nodes (transitions).
# Simple transition
graph.add_edge(Edge(source="Start", target="Choices", text=""))
# Choice transition (with text)
graph.add_edge(Edge(source="Choices", target="End", text="1. Run away"))
Important: Even if the internal Edge object uses source/target, your exported JSON for typical verifiers should use from/to.
4. Export
Serialize to JSON format for the engine/verifier.
data = graph.to_dict()
# Must return {"nodes": [...], "edges": [...]}
# where edges are {"from": ..., "to": ..., "text": ...}
json_str = graph.to_json()
5. Validation
Check for integrity.
errors = graph.validate()
# Returns list of strings, e.g., ["Edge 'Start'->'Unk' points to missing node 'Unk'"]
Recommended validation checks (common in benchmarks):
-
Edge endpoints
- Every edge
frommust exist innodes. - Every edge
tomust exist innodes, except whento == "End"(terminal sink convention).
- Every edge
-
Reachability
- All non-terminal nodes must be reachable from the first node (often
Start). - If the evaluator treats
Endspecially, do not requireEndto be reachable as a node; instead, require that at least one reachable node has an outgoing edge toEnd.
- All non-terminal nodes must be reachable from the first node (often
-
Choice-node semantics
type == "choice"nodes usually have outgoing edges whosetextis the option label (e.g.,"1. [Lie] ...").type == "line"nodes typically have a single outgoing edge withtext == "".
6. Visualization
Generate a PNG/SVG graph diagram.
# Requires: pip install graphviz
# Also requires Graphviz binary: https://graphviz.org/download/
graph.visualize('dialogue_graph') # Creates dialogue_graph.png
graph.visualize('output', format='svg') # Creates output.svg
The visualization includes:
- Diamond shapes for choice nodes (light blue)
- Rounded boxes for dialogue nodes (colored by speaker)
- Bold blue edges for skill-check choices like
[Lie],[Attack] - Gray edges for regular choices
- Black edges for simple transitions
7. Loading from JSON
Load an existing dialogue graph.
# From file
graph = Graph.from_file('dialogue.json')
# From dict
graph = Graph.from_dict({'nodes': [...], 'edges': [...]})
# From JSON string
graph = Graph.from_json(json_string)
04 同仓库更多 Skills
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms
video-frame-extraction
Extract frames from video files and save them as images using OpenCV
openai-vision
Analyze images and multi-frame sequences using OpenAI GPT vision models
image-ocr
Extract text content from images using Tesseract OCR via Python, including structured field extraction from receipts and forms