---

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

1. Confirm the backend is running and configured with LLM_API_KEY and ZEP_API_KEY.
2. Submit seed files and a natural-language simulation requirement to ontology generation.
3. Persist the returned project state and ontology; keep the project_id.
4. Start graph build for that project; capture the returned task_id and provisional or final graph_id.
5. Poll the task endpoint until it is completed or failed.
6. 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.