feat(sdk): add graph traversal support for Infrahub 1.10+

[minitriga]

Overview

Adds graph-traversal support to the SDK (requires Infrahub 1.10+), letting users discover how nodes are connected without knowing the relationship path in advance. Purely additive — no existing signatures change.

What's new

Three client methods, each with a sync equivalent:

• traverse_paths(source, destination, ...) — find the shortest path(s) between two nodes.
• path_exists(source, destination, ...) — boolean convenience wrapper for checks (requests a single path).
• reachable_nodes(source, target_kinds, ...) — find every node of given kinds reachable from a source, with the path to each.

Ergonomics:

• source/destination accept a node UUID string or an InfrahubNode instance.
• Kind filters accept kind-name strings or generated protocol classes (mix freely).
• Each result PathNode is a lightweight identity exposing .fetch() to resolve the full node (store-backed).
• Calling against a pre-1.10 server raises a clear VersionNotSupportedError instead of an opaque GraphQL failure.

Implementation notes

• New infrahub_sdk/graph_traversal/ package: typed pydantic result models (models.py) and GraphQL query strings + input builders (query.py). Pure logic is isolated so it's unit-tested without HTTP.
• New VersionNotSupportedError exception.
• Added to docs generation (tasks.py), a how-to guide, generated SDK reference, and a changelog fragment.

Testing

• pytest tests/unit/sdk/test_graph_traversal.py — 23 passed (pure-logic builders/parsing + client methods mocked at the transport boundary, async + sync).
• ruff check clean; lint-docs 0 errors.

🤖 Generated with Claude Code

---

Summary by cubic

Adds graph traversal to the Python SDK for Infrahub 1.10+, enabling shortest-path and dependency discovery across any relationships. Supports INFP-531 (Phase 1) by exposing traversal APIs the UI and GraphQL layer can use.

• New Features

  • SDK: InfrahubClient.traverse_paths(), reachable_nodes(), and path_exists() (with sync equivalents) to find shortest paths, discover reachable nodes by kind, and check connectivity.
  • Ergonomics: accept node IDs or InfrahubNode; kind filters accept strings or protocol classes; results include PathNode.fetch() to resolve full nodes from the client store.
  • Compatibility: pre-1.10 servers raise VersionNotSupportedError with a clear message.

• Bug Fixes

  • Clear errors for unsaved nodes used as traversal inputs (NodeNotSavedError, wrapped with role-specific context).
  • Safer schema kind resolution when save is missing in _get_schema_name.
  • More robust related-node detection using isinstance(InfrahubNodeBase) to avoid false positives.
  • Docs: added full Args in traversal docstrings; guide clarifies default-excluded kinds and how to detect truncated results; wording tweak to satisfy Vale (avoid “UUIDs”).
  • Include GraphQL operationName in requests for better tracing.
  • Tests: register traversal annotations in the async/sync parity map.

^{Written for commit 1fbfe9b. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying infrahub-sdk-python with    Cloudflare Pages

Latest commit:	1fbfe9b
Status:	✅  Deploy successful!
Preview URL:	https://1bc57d87.infrahub-sdk-python.pages.dev
Branch Preview URL:	https://infp-531-graph-traversal.infrahub-sdk-python.pages.dev

View logs

[cubic-dev-ai]

3 issues found across 38 files

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[codecov]

Codecov Report

❌ Patch coverage is 93.45238% with 11 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
infrahub_sdk/client.py	87.50%	8 Missing ⚠️
infrahub_sdk/graph_traversal/models.py	96.77%	1 Missing and 1 partial ⚠️
infrahub_sdk/schema/__init__.py	66.66%	0 Missing and 1 partial ⚠️

@@             Coverage Diff             @@
##           develop    #1090      +/-   ##
===========================================
- Coverage    82.32%   82.07%   -0.25%     
===========================================
  Files          135      138       +3     
  Lines        11992    11870     -122     
  Branches      1793     1783      -10     
===========================================
- Hits          9872     9742     -130     
- Misses        1571     1581      +10     
+ Partials       549      547       -2     

Flag	Coverage Δ
integration-tests	41.10% <1.78%> (-1.46%)	⬇️
python-3.10	55.22% <49.40%> (-0.79%)	⬇️
python-3.11	55.22% <49.40%> (-0.81%)	⬇️
python-3.12	55.22% <49.40%> (-0.81%)	⬇️
python-3.13	55.22% <49.40%> (-0.81%)	⬇️
python-3.14	55.20% <49.40%> (-0.81%)	⬇️
python-filler-3.12	22.70% <44.04%> (+0.33%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
infrahub_sdk/exceptions.py	89.80% <100.00%> (+0.69%)	⬆️
infrahub_sdk/graph_traversal/__init__.py	100.00% <100.00%> (ø)
infrahub_sdk/graph_traversal/query.py	100.00% <100.00%> (ø)
infrahub_sdk/node/related_node.py	91.09% <100.00%> (+0.04%)	⬆️
infrahub_sdk/schema/__init__.py	73.56% <66.66%> (+0.06%)	⬆️
infrahub_sdk/graph_traversal/models.py	96.77% <96.77%> (ø)
infrahub_sdk/client.py	75.54% <87.50%> (+0.86%)	⬆️

... and 2 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[ajtmccarty]

looks good. few small comments