Skip to content

AGENTS.md

Latest commit

 

History

History
103 lines (71 loc) · 3.95 KB

AGENTS.md

File metadata and controls

103 lines (71 loc) · 3.95 KB

AGENTS.md

Infrahub Python SDK - async/sync client for Infrahub infrastructure management.

Product context

The SDK is the foundational library for programmatically interacting with Infrahub. It abstracts away the underlying API so developers can work with infrastructure data using native Python objects.

Primary audience: Network automation engineers and software developers.

Three main use cases:

  • Automate inside Infrahub — Write transforms, generators, and checks that run as part of Infrahub's pipeline.
  • Integrate with external systems — Query and sync data between Infrahub and existing tools. infrahubctl and the Infrahub Ansible collection both use this SDK internally.
  • Build custom applications — Use Infrahub as a data backend for Python projects entirely outside of Infrahub's own pipeline.

Why the SDK over direct API calls: eliminates the need to learn Infrahub's API structure, provides Python-native interfaces with built-in auth, adds advanced capabilities (batching, caching, tracking), and reduces boilerplate.

Commands

uv sync --all-groups --all-extras   # Install all deps
uv run invoke format                # Format code
uv run invoke lint                  # Full pipeline: ruff, yamllint, ty, mypy, markdownlint, vale
uv run invoke lint-code             # All linters for Python code
uv run invoke docs-generate         # Generate all docs (CLI + SDK)
uv run invoke docs-validate         # Check generated docs match committed version
uv run pytest tests/unit/           # Unit tests
uv run pytest tests/integration/    # Integration tests

Tech stack

Python 3.10-3.13, UV, pydantic >=2.0, httpx, graphql-core

Code pattern

# Always provide both async and sync versions
client = InfrahubClient()           # async
client = InfrahubClientSync()       # sync

node = await client.get(kind="NetworkDevice")
await node.save()

Project structure

infrahub_sdk/
├── client.py           # Main client implementations
├── config.py           # Pydantic configuration
├── node/               # Node system (core data model)
├── ctl/                # CLI (infrahubctl)
└── pytest_plugin/      # Custom pytest plugin

Markdown style

When editing .md or .mdx files, run uv run invoke lint-docs before committing.

Key rules:

  • Use text language for directory structure code blocks
  • Add blank lines before and after lists
  • Always specify language in fenced code blocks (python, bash, text)

Boundaries

✅ Always

  • Run uv run invoke format lint-code before committing Python code
  • Run uv run invoke docs-generate after creating, modifying or deleting CLI commands, SDK config, or Python docstrings
  • Run markdownlint before committing markdown changes
  • Follow async/sync dual pattern for new features
  • Use type hints on all function signatures

⚠️ Ask first

  • Adding new dependencies
  • Changing public API signatures

🚫 Never

  • Push to GitHub automatically (always wait for user approval)
  • Mix async/sync inappropriately
  • Modify generated code (protocols.py)
  • Bypass type checking without justification

Knowledge base

Deep-dive docs on architecture and workflows live in dev/knowledge/. Read these before making changes to the areas they cover.

Subdirectory guides