#69 - Add Python bindings API documentation

.claude/rules/docs-sync.md

@@ -2,24 +2,26 @@
 
 These rules ensure documentation stays in sync with code changes in the DAQIRI repository.
 
-> **Path freshness.** The doc paths listed below (e.g. `docs/api-guide.md`, `docs/getting-started.md`, `docs/tutorials/*.md`) reflect the repo layout at the time of writing. If a doc has been renamed, moved, or split, treat the path as a starting point: confirm the current location with `grep -r` or by reading `mkdocs.yml`'s nav before acting on it. The CI gate in `.github/workflows/docs.yml` enforces internal-link/anchor/nav correctness on every PR.
+> **Path freshness.** The doc paths listed below (e.g. `docs/api-reference/*.md`, `docs/getting-started.md`, `docs/tutorials/*.md`) reflect the repo layout at the time of writing. If a doc has been renamed, moved, or split, treat the path as a starting point: confirm the current location with `grep -r` or by reading `mkdocs.yml`'s nav before acting on it. The CI gate in `.github/workflows/docs.yml` enforces internal-link/anchor/nav correctness on every PR.
 
 ## When to check for doc impact
 
 When the user is committing, pushing, or otherwise wrapping up a change that touches the files below, consider whether the related docs may need updating. The intent is a single check at the commit/PR checkpoint, not after every individual edit.
 
 ### API surface changes (high impact)
 - `src/common.h` — public free-function API (`get_rx_burst`, `get_packet_ptr`, `set_udp_header`, etc.). Any signature change, new function, removed function, or changed parameter semantics may need updating in:
-  - `docs/api-guide.md` (markdown reference)
+  - `docs/api-reference/cpp.md` (C++ markdown reference)
+  - `docs/api-reference/python.md` (Python bindings reference — update when the binding surface changes alongside the C++ API)
   - `docs/daqiri-api.html` (standalone HTML API page)
   - `CLAUDE.md` (Architecture section's API summary)
-- `src/types.h` — public types (`BurstParams`, `Status`, `NetworkConfig`, enums like `MemoryKind`, `Direction`, `SocketProtocol`). Struct field changes, new enum values, or renamed types may need updating in the API docs and `CLAUDE.md` (Architecture / BurstParams discussion).
-- `src/manager.h` — `Manager` virtual interface and `ManagerFactory`. Changes here affect the backend abstraction docs in `docs/api-guide.md` and the Manager-abstraction subsection in `CLAUDE.md`.
+- `src/types.h` — public types (`BurstParams`, `Status`, `NetworkConfig`, enums like `MemoryKind`, `Direction`, `SocketProtocol`). Struct field changes, new enum values, or renamed types may need updating in the API docs (`docs/api-reference/cpp.md`, `docs/api-reference/python.md`, `docs/daqiri-api.html`) and `CLAUDE.md` (Architecture / BurstParams discussion).
+- `src/manager.h` — `Manager` virtual interface and `ManagerFactory`. Changes here affect the backend abstraction docs in `docs/api-reference/cpp.md` and the Manager-abstraction subsection in `CLAUDE.md`.
+- `python/daqiri_common_pybind.cpp` — pybind11 binding surface. Any added/removed/renamed `m.def(...)`, changed pybind signature, new enum/class binding, or changed GIL-release behavior may need updating in `docs/api-reference/python.md` (function reference tables, enums/classes tables, GIL Behavior section).
 
 ### Backend and build changes (medium impact)
 - `src/managers/*/` — adding a new backend or changing backend behavior may need updating in:
   - `docs/getting-started.md` (build instructions, backend selection)
-  - `docs/configuration.md` (YAML config options)
+  - `docs/api-reference/configuration.md` (YAML config options)
   - `docs/tutorials/configuration-walkthrough.md` (tutorial config walkthrough)
   - `README.md` (Backends table)
   - `CLAUDE.md` (Manager abstraction / backend descriptions)
@@ -64,13 +66,15 @@ When the user is committing, pushing, or otherwise wrapping up a change that tou
 
 | Source file | Docs to check |
 |---|---|
-| `src/common.h` | `docs/api-guide.md`, `docs/daqiri-api.html`, `CLAUDE.md` |
-| `src/types.h` | `docs/api-guide.md`, `docs/daqiri-api.html`, `CLAUDE.md` |
-| `src/manager.h` | `docs/api-guide.md`, `CLAUDE.md` |
-| `src/managers/*/` | `docs/getting-started.md`, `docs/configuration.md`, `docs/tutorials/configuration-walkthrough.md`, `README.md`, `CLAUDE.md` |
+| `src/common.h` | `docs/api-reference/cpp.md`, `docs/api-reference/python.md`, `docs/daqiri-api.html`, `CLAUDE.md` |
+| `src/types.h` | `docs/api-reference/cpp.md`, `docs/api-reference/python.md`, `docs/daqiri-api.html`, `CLAUDE.md` |
+| `src/manager.h` | `docs/api-reference/cpp.md`, `CLAUDE.md` |
+| `src/managers/*/` | `docs/getting-started.md`, `docs/api-reference/configuration.md`, `docs/tutorials/configuration-walkthrough.md`, `README.md`, `CLAUDE.md` |
 | `src/CMakeLists.txt` | `docs/getting-started.md`, `CLAUDE.md`, `README.md` |
 | `src/kernels.cu` | `docs/tutorials/benchmarking_examples.md`, `CLAUDE.md` |
+| `python/daqiri_common_pybind.cpp` | `docs/api-reference/python.md`, `CLAUDE.md` |
 | `examples/*.cpp` | `docs/tutorials/benchmarking_examples.md`, `docs/tutorials/configuration-walkthrough.md`, `CLAUDE.md` |
 | `examples/*.yaml` | `docs/tutorials/benchmarking_examples.md`, `docs/tutorials/configuration-walkthrough.md`, `CLAUDE.md` |
+| `examples/*.py` | `docs/api-reference/python.md`, `CLAUDE.md` |
 | `mkdocs.yml` | `docs/index.html` (nav links) |
 | Any `docs/*` rename/move | `README.md` (Documentation table), `CLAUDE.md` (Documentation section), `mkdocs.yml`, `docs/index.html` |

AGENTS.md

@@ -67,7 +67,7 @@ clang-format -style=file -i -fallback-style=none <files>
 `ManagerFactory` (also in `manager.h`) is a singleton that instantiates the active backend. `daqiri_init(...)` resolves which backend to use from the `NetworkConfig` and then delegates everything through the `Manager` vtable. There is only ever **one** active `Manager` per process.
 
 ### Zero-copy / BurstParams
-All packet data flows through `BurstParams`, a batch of packets. Only pointers are passed between NIC, DAQIRI internals, and the application — the caller reads directly from the buffers the NIC DMA'd into. **The caller must explicitly free bursts**; a missed free drains the pool and produces `NO_FREE_BURST_BUFFERS` / `NO_FREE_PACKET_BUFFERS` errors and NIC drops. See `docs/api-guide.md`.
+All packet data flows through `BurstParams`, a batch of packets. Only pointers are passed between NIC, DAQIRI internals, and the application — the caller reads directly from the buffers the NIC DMA'd into. **The caller must explicitly free bursts**; a missed free drains the pool and produces `NO_FREE_BURST_BUFFERS` / `NO_FREE_PACKET_BUFFERS` errors and NIC drops. See `docs/api-reference/cpp.md`.
 
 ### Segments & HDS
 A single packet can span multiple **segments** (contiguous memory regions), each in CPU or GPU memory. The header-data split (HDS) mode puts headers in segment 0 (CPU) and payload in segment 1 (GPU), enabling GPUDirect zero-copy payload paths. Batched-GPU and CPU-only modes use a single segment.
@@ -91,16 +91,17 @@ The web docs live in `docs/` and are built with [MkDocs Material](https://squidf
 
 **Structure:**
 - `docs/index.html` — custom HTML landing page (not generated by MkDocs, hand-maintained)
-- `docs/daqiri-api.html` — standalone HTML API reference (hand-maintained)
-- `docs/api-guide.md`, `docs/getting-started.md`, `docs/configuration.md` — core markdown docs
+- `docs/api-reference/cpp.md`, `docs/api-reference/python.md`, `docs/api-reference/configuration.md` — API reference docs
+- `docs/daqiri-api.html` — standalone HTML C++ API reference (hand-maintained)
+- `docs/getting-started.md` — core getting-started docs
 - `docs/tutorials/` — tutorial walkthroughs (background, system config, benchmarking, config files)
 - `docs/stylesheets/extra.css` — custom theme overrides
 
 **Keeping docs in sync with code:** before committing changes, scan for the recurring drift hotspots:
-- **Backend list** (`src/managers/*/`) — README Backends table, `docs/getting-started.md`, `docs/configuration.md`
+- **Backend list** (`src/managers/*/`) — README Backends table, `docs/getting-started.md`, `docs/api-reference/configuration.md`
 - **CMake options / `DAQIRI_MGR` default** (`src/CMakeLists.txt:137`) — README Quick Start, `docs/getting-started.md`, this file's Build & run section
 - **Benchmark binary or YAML names** (`examples/`) — the benchmark table above, `docs/tutorials/benchmarking_examples.md`, and the "Choosing an example config" decision tree in `docs/tutorials/configuration-walkthrough.md` (every YAML must have a leaf; CI's `scripts/check_doc_refs.py` enforces coverage)
-- **Public API** (`src/common.h`, `src/types.h`, `src/manager.h`) — `docs/api-guide.md`, `docs/daqiri-api.html`
+- **Public API** (`src/common.h`, `src/types.h`, `src/manager.h`) — `docs/api-reference/cpp.md`, `docs/api-reference/python.md`, `docs/daqiri-api.html`
 - **Doc reorganization** (any rename in `docs/`) — `docs/index.html` landing page, `mkdocs.yml` nav, README Documentation table
 
 The full mapping with rationale lives in the docs-sync agent rule. Internal-link, anchor, and nav drift is enforced by CI (`.github/workflows/docs.yml`); content drift (stale binary names, defaults) is still a manual check at commit time.

README.md

@@ -79,8 +79,9 @@ running the benchmarks.
 Reference material for the DAQIRI codebase:
 
 - [Getting Started](docs/getting-started.md) — System requirements, build/install instructions, and CMake options
-- [Configuration Reference](docs/configuration.md) — Full YAML config reference for all backends
-- [API Guide](docs/api-guide.md) — BurstParams, RX/TX workflows, buffer lifecycle, status codes
+- [C++ API Reference](docs/api-reference/cpp.md) — BurstParams, RX/TX workflows, buffer lifecycle, status codes
+- [Python API Reference](docs/api-reference/python.md) — Python bindings, workflow examples, enums, config classes, and helper functions
+- [Configuration YAML Reference](docs/api-reference/configuration.md) — Full YAML config reference for all backends
 - [Contributing](CONTRIBUTING.md) — Contribution guidelines, coding standards, DCO sign-off
 
 ## Tutorials