name: graph-build
description: "Routes MiroFish document upload, ontology generation, Zep graph
construction, project graph inspection, task polling, reset, and graph
deletion workflows."
disable-model-invocation: true
metadata:
disco-role: operating
license: AGPL 3.0
graph-build
Use this sub-skill when a task asks to create the first MiroFish project graph from seed documents, generate or debug the ontology, poll graph build progress, inspect graph data, reset a project graph, or delete a graph-backed project.
Route first
- For installation, API keys, ports, or Docker/local service startup, begin at the root MiroFish setup reference.
- For simulation creation, profile generation, or
simulation_config.json, route to the sibling simulation-setup sub-skill after the project status is graph_completed and a graph_id exists.
- For running/monitoring OASIS simulations, route to
simulation-run.
- For reports and report-agent chat, route to
reporting.
Read or run the bundled material
- Read references/workflows.md for the document-upload → ontology → graph-build → graph-inspection flow and the reset/delete decision points.
- Read references/api-reference.md when constructing
/api/graph calls or interpreting task/project responses.
- Read references/data-formats.md for accepted document types, ontology JSON shape, project/task/graph fields, and graph payload conventions.
- Read references/troubleshooting.md for upload, ontology, LLM JSON, Zep Cloud, build-task, and graph lifecycle failures.
- Run scripts/validate_ontology_payload.py when validating ontology JSON from a file or stdin. Use
python scripts/validate_ontology_payload.py --help to inspect options, or python scripts/validate_ontology_payload.py --self-test to check the validator without a live LLM or Zep account.
Minimal operating path
- Confirm the backend is running and configured with
LLM_API_KEY and ZEP_API_KEY.
- Submit seed files and a natural-language simulation requirement to ontology generation.
- Persist the returned project state and ontology; keep the
project_id.
- Start graph build for that project; capture the returned
task_id and provisional or final graph_id.
- Poll the task endpoint until it is
completed or failed.
- Only continue to simulation setup after the project status is
graph_completed and the graph data endpoint can return nodes/edges.
Guardrails
- Supported seed files are PDF, Markdown, and text; reject unsupported extensions before upload.
- Treat ontology field names as public graph schema. Keep entity names PascalCase, relation names UPPER_SNAKE_CASE, and attribute names snake_case without reserved names.
- Do not issue reset/delete while the graph has active build, simulation, memory-updater, or report consumers; use the lifecycle guidance in troubleshooting.
- Do not turn a Zep authentication/permission/transport error into an empty graph. Empty lists are valid data only after a successful read.