zinet

Graph IR core package shared across SPL, ConceptBook, Graph-Code, Momagrid, and Solver domains.

graph.yaml is the common intermediate representation of the ZiNets ecosystem, the way LLVM IR is for compilers: front-ends emit it, back-ends consume it, and the shared validator and transforms live here once.

The format

Every graph has three layers, each a list of nodes:

version: "1.0"
imports: [./shared/tools.yaml]   # optional; resolved relative to this file
primitives:                      # leaves: must not have deps
  - id: x_units
    meta: {type: variable}
concepts:                        # composed from primitives and other concepts
  - id: capacity_constraint
    deps: [x_units, max_units]
    edge_types: {max_units: constraint}
    meta: {expression: "x_units <= max_units"}
applications:                    # capstones: nothing may depend on these
  - id: minimize_cost
    deps: [capacity_constraint]

• deps are the ids a node depends on (incoming edges).
• edge_types optionally types a dependency: depends_on (default), data_flow, prerequisite, constraint, inheritance.
• meta is an opaque domain payload that the core never interprets.

Install

From PyPI:

pip install zinet

From source, for development:

uv venv .venv && uv pip install -p .venv/bin/python -e ".[dev]"

CLI: zinet

zinet validate graph.yaml            # exit 1 on errors; warnings are printed but do not fail
zinet diff old.yaml new.yaml         # exit 1 when the graphs differ
zinet slice graph.yaml target_id -o part.yaml   # target plus its prerequisite closure
zinet render graph.yaml                              # svg to stdout (default)
zinet render graph.yaml --format mermaid             # mermaid flowchart text
zinet render graph.yaml --format png -o graph.png    # png and pdf need -o
zinet prettify graph.yaml                            # diff against canonical formatting (exit 1 if it would change)
zinet prettify graph.yaml --write                    # rewrite in place (refuses files with comments)
zinet schema -o schemas/graph.schema.json            # JSON Schema for editors and other tools

render supports svg, png, pdf, and mermaid. Mermaid needs nothing installed. The other formats need Graphviz's dot on PATH (apt install graphviz).

Exit code 2 means a usage, load, or render error. prettify exits 1 when a file is not in canonical form, so it can run in CI.

Specification

The format is specified in docs/SPECIFICATION.md. The machine-readable JSON Schema is schemas/graph.schema.json, regenerated with zinet schema -o schemas/graph.schema.json. A test fails if the committed schema is out of date.

Python API

from zinet import load_graph, validate, diff_graphs, slice_to, dump_graph

graph = load_graph("solver_pipeline.yaml")   # resolves imports
for issue in validate(graph):
    print(issue)
prereqs = slice_to(graph, "minimize_cost")

Checks

Layout

src/zinet/
  schema.py       Pydantic models: Graph, Node, Layer, EdgeType
  dag.py          topological order, ancestors (domain-agnostic)
  validator.py    structural checks -> Issue list
  io.py           load_graph (with imports), dump_graph, to_yaml
  prettify.py     canonical formatting for `zinet prettify`
  transforms/     diff_graphs, slice_to
  render.py       DOT and Mermaid generation, svg/png/pdf via `dot`
  cli.py          the `zinet` command
docs/SPECIFICATION.md   the graph.yaml format specification
schemas/graph.schema.json   generated JSON Schema
tests/            pytest suite; tests/fixtures holds one graph per domain

Design decisions

• Imports merge nodes without namespacing, so ids must be unique across the whole import tree.
• load_graph does not validate. Run validate separately for structural checks.
• Unknown top-level and node keys are rejected, so typos fail loudly. Domain data goes in meta.
• Only the core checks are here. Domain rules (for example, solver bounds) belong in the back-end.

Not yet implemented

• Domain-specific JSON Schema overlays (solver, spl, cba).
• graph.html interactive explorer (belongs to cba).
• Comment-preserving formatting. prettify --write refuses files with comments.
• spl3 integration, which is the next step: SPL scripts compiling to GraphIR.