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.py9.9 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.
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"))
add_node is idempotent for identical re-registrations: calling it twice with the same id and attributes is a no-op (so convergence nodes like End can be safely re-added by multiple code paths). Re-adding the same id with different attributes still raises ValueError. Use graph.ensure_node(node) when you want strictly idempotent behavior without raising.
3. Adding Edges
Connect nodes (transitions).
# Simple transition
graph.add_edge(Edge(source="Start", target="Choices"))
# Choice transition (with text)
graph.add_edge(Edge(source="Choices", target="End", text="1. Run away"))
IMPORTANT — targets must exist as nodes. Every edge target (including End) must correspond to a registered node. Whenever you add an edge whose target is End, you must also ensure the End node exists in the graph. Example:
# Register the terminal node once; safe to call repeatedly thanks to ensure_node
graph.ensure_node(Node(id="End", text="", speaker="", type="line"))
graph.add_edge(Edge(source="Choices", target="End", text="1. Run away"))
graph.add_edge(Edge(source="Combat", target="End", text="")) # multiple paths may converge on End
4. End Node Convention
End is the single legal terminal node in a dialogue graph.
- Shape:
{"id": "End", "text": "", "speaker": "", "type": "line"}. - Registration: must appear in
graph.nodes(not just as an edge target). Register it exactly once; useensure_nodeso convergent branches are safe. - Convergence: multiple edges may point to
End. - Outgoing:
Endmay have zero outgoing edges. - Reachability:
Endmust still be reachable from the root (first-declared) node via the edge set.
5. Export
Serialize to JSON format for the engine.
data = graph.to_dict()
# returns {"nodes": [...], "edges": [...]}
json_str = graph.to_json()
For tasks that also require a Graphviz DOT file (e.g., /app/dialogue.dot), use to_dot():
dot_src = graph.to_dot()
with open('/app/dialogue.dot', 'w', encoding='utf-8') as f:
f.write(dot_src)
to_dot() emits:
shape=boxfortype=="line"nodes,shape=diamondfortype=="choice"nodes,shape=doublecirclefor theEndnode,- escaped labels (
\→\\,"→\", newlines →\n), - an explicit declaration for the
Endnode (even if it would otherwise appear only as an edge target).
Note:
graph.visualize(...)renders a PNG/SVG via the Graphviz binary withcleanup=True, which deletes the intermediate.dotfile. It is not a substitute forto_dot()when a persistent.dotartifact is required.
6. Validation
Check for integrity.
errors = graph.validate()
# Returns list of strings, e.g.,
# ["Edge 'Start'->'Unk' points to missing node 'Unk'",
# "Node 'Orphan' is not reachable from root 'Start'"]
validate() checks:
- Every edge
sourcecorresponds to an existing node id. - Every edge
targetcorresponds to an existing node id — includingEnd, which must be a registered node. - All nodes are reachable from the first-declared (root) node via BFS over the directed edges.
7. 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)
- Double-circle for the
Endnode - Bold blue edges for skill-check choices like
[Lie],[Attack] - Gray edges for regular choices
- Black edges for simple transitions
Visualization reads only nodes present in graph.nodes; register End yourself (see §3/§4) to keep JSON, DOT, and PNG output consistent.
8. 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