rtl-buddy-graph-extract

Clean-room, stdlib-only extractor feeding the binding tier of rtl-buddy's design knowledge graph (epic rtl_buddy#375): deterministic extraction over verif Python and spec markdown into NetworkX node-link JSON, plus a merge-graphs union used by rb graph build as a cross-check.

It implements the CLI contract rtl_buddy/graph/extract.py consumes. The contract is owned by rtl-buddy and evolves to serve it — it descends historically from shapes once assumed of the upstream Graphify project (the idea source, credit where due), but rtl-buddy is fully decoupled from that tool and claims no compatibility with it. See docs/extract-contract.md for the full contract.

Usage

rb-graph-extract extract --format node-link --output binding/graph.json \
    verif/**/*.py spec/**/*.md
rb-graph-extract merge-graphs --format node-link --output merged.json \
    design/graph.json config/graph.json binding/graph.json

Normally you never run it by hand — rb graph build invokes it when installed and degrades gracefully when not.

• Only --format node-link is supported.
• Deterministic only: there is no semantic/LLM pass and no flag to request one.
• No dependencies outside the Python standard library.

Installing (git pin until the first PyPI release)

There is no PyPI release yet. Consume it via a uv git source:

# pyproject.toml of the consuming project
[project.optional-dependencies]
graph-extract = ["rtl-buddy-graph-extract"]

[tool.uv.sources]
rtl-buddy-graph-extract = { git = "https://github.com/rtl-buddy/rtl-buddy-graph-extract" }

or as a standalone tool:

uv tool install git+https://github.com/rtl-buddy/rtl-buddy-graph-extract

Once a PyPI release exists the [tool.uv.sources] pin is dropped and the dependency resolves normally.

Development

uv run --group test pytest
uv run --group lint ruff check .
uv run --group lint ruff format --check .

Versioning is tag-driven via hatch-vcs, matching rtl_buddy and rtl-buddy-view; the label-driven release workflow will be added when PyPI publishing is set up.