Metadata-Version: 2.5
Name: rtl-buddy-graph-extract
Version: 0.1.0
Summary: Clean-room, stdlib-only extractor implementing the Graphify CLI contract rb graph build consumes: verif Python + spec markdown -> node-link JSON binding tier.
Author-email: Loh Zhi-Hern <hernloh@users.noreply.github.com>
License-Expression: BSD-3-Clause
License-File: LICENSE
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# 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](https://github.com/safishamsi/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](docs/extract-contract.md) for the full
contract.

## Usage

```sh
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:

```toml
# 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:

```sh
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

```sh
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.
