Overview page sdk

.vale/styles/spelling-exceptions.txt

@@ -138,3 +138,4 @@ yamllint
 YouTube
 vscode
 VSCode
+walkthrough

AGENTS.md

@@ -2,6 +2,20 @@
 
 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
 
 ```bash

docs/docs/python-sdk/introduction.mdx

@@ -1,37 +1,157 @@
 ---
-title: Python SDK
+title: Python SDK overview
 ---
-import VideoPlayer from '../../src/components/VideoPlayer';
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import ReferenceLink from '@site/src/components/Card';
+import VideoPlayer from '@site/src/components/VideoPlayer';
 
-The Infrahub Python SDK greatly simplifies how you can interact with Infrahub programmatically.
+# Infrahub Python SDK
 
-## Videos
+The Infrahub Python SDK is a client library for interacting with [Infrahub](https://docs.infrahub.app/) programmatically. It handles authentication, query construction, and data serialization so you can work with infrastructure data using native Python objects instead of raw API calls.
+
+## What you can do with it
+
+The SDK covers three main use cases:
+
+- **Automate inside Infrahub** — Write [transforms](https://docs.infrahub.app/topics/transformation), [generators](https://docs.infrahub.app/topics/generator), and [checks](https://docs.infrahub.app/topics/check) that run as part of Infrahub's pipeline.
+- **Integrate with external systems** — Query and sync data between Infrahub and your existing tools.
+- **Build custom applications** — Use Infrahub as a data backend for your own Python projects.
+
+Under the hood, tools like [`infrahubctl`](/infrahubctl/infrahubctl) and the [Infrahub Ansible collection](https://docs.infrahub.app/ansible) both use this SDK.
+
+## A quick look
+
+<Tabs groupId="async-sync">
+<TabItem value="Async" default>
+
+```python
+import asyncio
+from infrahub_sdk import InfrahubClient
+
+
+async def main():
+    client = InfrahubClient()
+
+    # Create a new tag and save it
+    tag = await client.create(
+        kind="BuiltinTag",
+        name="staging",
+        description="Resources in the staging environment",
+    )
+    await tag.save()
+
+    # Query all tags
+    tags = await client.all(kind="BuiltinTag")
+    for tag in tags:
+        print(f"{tag.name.value} — {tag.description.value}")
+
+
+asyncio.run(main())
+
+```
+
+</TabItem>
+<TabItem value="Sync">
+
+```python
+from infrahub_sdk import InfrahubClientSync
+
+client = InfrahubClientSync()
+
+# Create a new tag and save it
+tag = client.create(
+    kind="BuiltinTag",
+    name="staging",
+    description="Resources in the staging environment",
+)
+tag.save()
+
+# Query all tags
+tags = client.all(kind="BuiltinTag")
+for tag in tags:
+    print(f"{tag.name.value} — {tag.description.value}")
+
+```
+
+</TabItem>
+</Tabs>
+
+Both async and sync clients expose the same API. Choose async for applications that benefit from concurrent I/O (transforms, large-scale sync scripts) and sync for straightforward scripting.
+
+## Why use the SDK over direct API calls
+
+| Concern | Raw API | SDK |
+| ------- | ------- | --- |
+| Authentication | Manual token management, JWT refresh | Handled automatically |
+| Querying | Build GraphQL queries by hand | `client.get()`, `client.all()`, `client.filters()` |
+| Mutations | Construct and POST GraphQL mutations | `node.save()`, `node.delete()` |
+| Concurrency | Roll your own async batching | Built-in `batch` with concurrency control |
+| Typing | Maintain type definitions manually | Schema-driven type export using protocols |
+
+:::tip
+The SDK removes the boilerplate so you can focus on the logic that matters to your infrastructure.
+:::
+
+## Key capabilities
+
+- **CRUD operations** — Create, read, update, and delete any node type defined in your schema.
+- **Batch execution** — Group multiple queries into a batch with configurable concurrency limits.
+- **Tracking** — Tag operations with identifiers for auditing and idempotent updates.
+- **Store** — Cache retrieved nodes locally to reduce redundant queries.
+- **GraphQL escape hatch** — Run arbitrary GraphQL queries when the high-level API doesn't cover your use case.
+
+## Video walkthrough
 
 <center>
   <VideoPlayer url='https://www.youtube.com/live/RbRz8_t0FBs?feature=shared' light />
 </center>
 
-## Blog posts
+## Installation
+
+<Tabs groupId="installation">
+<TabItem value="uv" default>
+
+```bash
+uv add infrahub-sdk
+```
+
+Extras are available for additional functionality:
+
+```bash
+uv add 'infrahub-sdk[ctl]'    # Adds the infrahubctl CLI
+uv add 'infrahub-sdk[tests]'  # Adds the testing framework for transforms and checks
+uv add 'infrahub-sdk[all]'    # Everything
+```
+
+</TabItem>
+<TabItem value="pip">
 
-- [Querying Data in Infrahub via the Python SDK](https://www.opsmill.com/querying-data-in-infrahub-via-the-python-sdk/)
-- [Creating, Modifying, and Deleting Data in Infrahub Using the Python SDK](https://www.opsmill.com/infrahub-python-sdk-create-modify-delete/)
+```bash
+pip install infrahub-sdk
+```
 
-## Guides
+Extras are available for additional functionality:
 
-- [Installing infrahub-sdk](./guides/installation.mdx)
-- [Creating a client](./guides/client.mdx)
-- [Querying data in Infrahub](./guides/query_data.mdx)
-- [Managing nodes](./guides/create_update_delete.mdx)
-- [Managing branches](./guides/branches.mdx)
-- [Using the client store](./guides/store.mdx)
-- [Using the client tracking mode](./guides/tracking.mdx)
+```bash
+pip install 'infrahub-sdk[ctl]'    # Adds the infrahubctl CLI
+pip install 'infrahub-sdk[tests]'  # Adds the testing framework for transforms and checks
+pip install 'infrahub-sdk[all]'    # Everything
+```
 
-## Topics
+</TabItem>
+</Tabs>
 
-- [Understanding tracking in the Python SDK](./topics/tracking.mdx)
+<ReferenceLink title="Installation guide" url="/python-sdk/guides/installation" />
 
-## Reference
+## Next steps
 
-- [Client configuration](./reference/config.mdx)
-- [Compatibility matrix](./reference/compatibility.mdx)
-- [Python SDK Release Notes](https://github.com/opsmill/infrahub-sdk-python/releases)
+- **[Hello world example](./guides/client.mdx#hello-world-example)** — Your first client connection and query.
+- **[Create and configure a client](./guides/client.mdx)** — Set up authentication, proxy settings, and client options.
+- **[Query data](./guides/query_data.mdx)** — Retrieve nodes with filters and GraphQL.
+- **[Create, update, and delete nodes](./guides/create_update_delete.mdx)** — Manage infrastructure data programmatically.
+- **[Work with branches](./guides/branches.mdx)** — Use Infrahub's branch workflow from Python.
+- **[Batch operations](./guides/batch.mdx)** — Optimize performance for bulk operations.
+- **[Client configuration reference](./reference/config.mdx)** — All available configuration options.
+- **[Compatibility matrix](./reference/compatibility.mdx)**
+- **[Python SDK Release Notes](https://github.com/opsmill/infrahub-sdk-python/releases)**