agrowell-ikh-client 0.1.0__tar.gz

agrowell_ikh_client-0.1.0/.gitignore

@@ -0,0 +1,65 @@
+# These are some examples of commonly ignored file patterns.
+# You should customize this list as applicable to your project.
+# Learn more about .gitignore:
+#     https://www.atlassian.com/git/tutorials/saving-changes/gitignore
+
+# Node artifact files
+node_modules/
+dist/
+
+# Compiled Java class files
+*.class
+
+# Compiled Python bytecode
+*.py[cod]
+
+# Log files
+*.log
+
+# Package files
+*.jar
+
+# Maven
+target/
+dist/
+
+# JetBrains IDE
+.idea/
+
+# Unit test reports
+TEST*.xml
+
+# Generated by MacOS
+.DS_Store
+
+# Generated by Windows
+Thumbs.db
+
+# Applications
+*.app
+*.exe
+*.war
+
+# Large media files
+*.mp4
+*.tiff
+*.avi
+*.flv
+*.mov
+*.wmv
+
+# Python virtual environments
+.venv/
+venv/
+.env
+
+# Python build / test caches
+__pycache__/
+*.egg-info/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+

agrowell_ikh_client-0.1.0/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, up2metric P.C.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of up2metric P.C. nor the names of its contributors
+   may be used to endorse or promote products derived from this software
+   without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

agrowell_ikh_client-0.1.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: agrowell-ikh-client
+Version: 0.1.0
+Summary: Python SDK bridging the I Know How (IKH) robot with the Agro-Well greenhouse platform.
+Project-URL: Homepage, https://up2metric.com
+Project-URL: Repository, https://bitbucket.org/up2metricPC/agro-well-ikh-client
+Project-URL: Issues, https://bitbucket.org/up2metricPC/agro-well-ikh-client/issues
+Author-email: "up2metric P.C." <info@up2metric.com>
+License: BSD 3-Clause License
+        
+        Copyright (c) 2026, up2metric P.C.
+        All rights reserved.
+        
+        Redistribution and use in source and binary forms, with or without
+        modification, are permitted provided that the following conditions are met:
+        
+        1. Redistributions of source code must retain the above copyright notice,
+           this list of conditions and the following disclaimer.
+        
+        2. Redistributions in binary form must reproduce the above copyright notice,
+           this list of conditions and the following disclaimer in the documentation
+           and/or other materials provided with the distribution.
+        
+        3. Neither the name of up2metric P.C. nor the names of its contributors
+           may be used to endorse or promote products derived from this software
+           without specific prior written permission.
+        
+        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+        AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+        IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+License-File: LICENSE
+Keywords: agro-well,apriltag,keycloak,object-placement,robotics,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: fpdf2<3,>=2.8
+Requires-Dist: httpx<0.29,>=0.27
+Requires-Dist: pydantic-settings<3,>=2.3
+Requires-Dist: pydantic<3,>=2.7
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: minio
+Requires-Dist: minio>=7.2; extra == 'minio'
+Description-Content-Type: text/markdown
+
+# agrowell-ikh-client
+
+A small, typed Python SDK that bridges the **I Know How (IKH)** robot with the
+**Agro-Well** greenhouse platform.
+
+**v1 scope:**
+
+1. **Authenticate** to the platform via Keycloak (client-credentials / machine-to-machine).
+2. **Read anchors** — resolve a detected AprilTag to its platform anchor (and its AR pose).
+3. **Commission (align)** — from a reference anchor, compute the anchor-group transform that
+   maps the robot's **ROS** measurements onto the platform **AR** scene, write it, and emit a
+   quantitative **validation report**. The ROS ↔ Three.js conversion happens **internally**.
+
+> **Status:** v1 boilerplate. Some platform-side prerequisites must be confirmed before
+> live integration — see [Open items](#open-items). Open-source under the
+> [BSD 3-Clause License](LICENSE).
+
+## Installation
+
+Released under the [BSD 3-Clause License](#license). Install from PyPI:
+
+```bash
+pip install agrowell-ikh-client
+```
+
+Or from a built wheel:
+
+```bash
+pip install ./agrowell_ikh_client-<version>-py3-none-any.whl
+```
+
+Requires Python 3.10+.
+
+## Configuration
+
+Read from `AGROWELL_`-prefixed environment variables (and an optional `.env` file), or
+passed explicitly via `Settings`. Copy [`.env.example`](.env.example) to `.env` and fill
+in the values from the Agro-Well platform team.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AGROWELL_KEYCLOAK_BASE_PATH` | ✅ | — | Keycloak base URL |
+| `AGROWELL_KEYCLOAK_REALM` | | `AGRO-WELL` | Keycloak realm |
+| `AGROWELL_KEYCLOAK_CLIENT_ID` | ✅ | — | Service-account client id |
+| `AGROWELL_KEYCLOAK_CLIENT_SECRET` | ✅ | — | Service-account client secret |
+| `AGROWELL_API_BASE_URL` | ✅ | — | object-placement REST base URL |
+| `AGROWELL_API_PATH_PREFIX` | | `/v1` | API path prefix (`/v1` or `/api/v1`) |
+| `AGROWELL_ORGANIZATION_ID` | ✅ | — | Organization the robot belongs to (scopes all anchor reads/writes) |
+| `AGROWELL_FACILITY_ID` | ✅ | — | Facility the robot is installed at (== platform scene id; scopes every read to that facility) |
+| `AGROWELL_DEV_MODE` | | `false` | Collect a validation report during commissioning and emit it on `close()` |
+| `AGROWELL_VERIFY_SSL` | | `true` | TLS certificate verification |
+| `AGROWELL_HTTP_TIMEOUT_SECONDS` | | `10.0` | Request timeout |
+| `AGROWELL_HTTP_MAX_RETRIES` | | `3` | Retry budget for idempotent requests |
+
+## Quickstart
+
+```python
+from agrowell_ikh_client import AgroWellClient, ScannedTag
+
+with AgroWellClient.from_env() as client:
+    # Discover the anchors visible to your organization (raw platform models, AR frame):
+    anchors = client.api.anchors.list()
+
+    # Commission: on each AprilTag detection, pass the robot's measured pose (ROS frame).
+    # The SDK resolves the anchor, computes the anchor-group transform, and writes it.
+    for detection in detections:                  # your detector's per-frame loop
+        client.alignment.update_group(
+            ScannedTag(
+                apriltag_id=detection.id,
+                translation=(1.20, 0.0, 3.45),    # metres, ROS frame
+                quaternion=(0.0, 0.0, 0.0, 1.0),  # (x, y, z, w)
+            )
+        )
+```
+
+The robot needs only its **organization** (from config) and the **AprilTag ids** it scans.
+It never handles anchor UUIDs, anchors-groups, scenes, or raw 4×4 matrices — those are
+resolved or converted internally. Poses cross the SDK boundary in the **ROS** frame; the
+raw reads under `client.api.*` return platform models in the **AR (Three.js)** frame.
+
+## The rigid-isometry property (why the between-anchor check works)
+
+The internal ROS → Three.js conversion is a **rigid isometry** — a pure rotation of axes
+(`det = +1`, no scale or handedness flip), so distances and angles between anchors are
+preserved. The commissioning report exploits this: in the relative transform between two
+anchors the anchor-group transform `G` cancels, so a residual there can only come from the
+ROS ↔ AR conversion itself (a handedness/axis flip or a metre/centimetre mix-up), not from a
+single mis-placed anchor. That is what makes the between-anchor check a clean, objective
+signal even though there is no visual validation. (See `tests/test_simulation.py`.)
+
+## Commissioning (alignment + validation)
+
+After the 3 anchors are AR-calibrated in the web app, the robot aligns its ROS frame to the
+scene by writing the **anchor-group transform**. On **each** AprilTag detection it calls
+`update_group`, which resolves the anchor's AR pose, computes the group transform `G` from
+that AR pose and the detected ROS pose (`G = T_ar ∘ inverse(convert(T_ros))`), and PATCHes the
+group. This runs many times during a commissioning session.
+
+Because updating that transform moves the whole scene subtree together, there is **no visual
+validation**. So, with `AGROWELL_DEV_MODE=true`, the client collects each anchor's server
+("before") and ROS-computed ("after") pose and emits one **validation report** on `close()`.
+
+```python
+from agrowell_ikh_client import AgroWellClient, ScannedTag, ObjectStoreSink
+
+# AGROWELL_DEV_MODE=true enables the report; the sink is where it is uploaded.
+# Sinks: ObjectStoreSink (presigned URL), MinioSink.from_settings(settings) (direct MinIO/S3,
+# needs the 'minio' extra), or LocalFileSink (disk).
+with AgroWellClient.builder().with_report_sink(
+    ObjectStoreSink(presign=mint_upload_url)  # mint_upload_url(key) -> presigned PUT URL
+).build() as client:
+    for tag in detections:                     # the robot's per-detection loop
+        client.alignment.update_group(
+            ScannedTag(tag.id, tag.translation, tag.quaternion)  # ROS frame
+        )
+    # on exit: one report (per-anchor errors + between-anchor conversion check) is uploaded
+```
+
+The report (`ValidationReport`, render with `report.to_text()`) carries per-anchor
+position/orientation errors and aggregates, **plus a pairwise (between-anchor) check that the
+ROS → AR conversion holds** — in the relative transform between two anchors `G` cancels, so it
+isolates conversion errors (handedness/axis flips, metre/centimetre mix-ups) from a single
+mis-placed anchor. Try it offline: `python examples/simulate_commissioning.py`.
+
+## Usage
+
+```python
+# Raw request layer, grouped by resource category (client.api.<category>).
+
+# List the anchors visible to your organization (raw platform models, AR frame).
+# No group/scene needed; the org context scopes the result.
+anchors = client.api.anchors.list()                  # or .list(registered=False)
+
+# Resolve a single detected tag to its anchor. Raises AnchorNotFoundError if none match,
+# AmbiguousAnchorError if more than one does:
+anchor = client.api.anchors.resolve_by_tag(42)
+if anchor.image_anchor and anchor.image_anchor.transform:
+    x, y, z = anchor.image_anchor.transform.translation   # AR (Three.js) frame
+
+# Commission: per detection, compute + write the anchor-group transform from a ROS pose.
+client.alignment.update_group(
+    ScannedTag(42, translation=(1.2, 0.0, 3.45), quaternion=(0.0, 0.0, 0.0, 1.0))
+)
+```
+
+### Coordinate frames (internal)
+
+The robot speaks only **ROS** (REP-103: X-forward, Y-left, Z-up, right-handed, metres,
+quaternions). The platform stores transforms in the **Three.js** AR frame (right-handed,
+Y-up). The SDK converts at the boundary automatically (`ROS_X = −AR_Z`, `ROS_Y = −AR_X`,
+`ROS_Z = AR_Y`); it is not a user-facing option. If the platform's AR engine ever changes,
+that is a one-line internal change.
+
+### Error handling
+
+All errors derive from `AgroWellError`. HTTP errors map to typed exceptions
+(`BadRequestError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ServerError`, …),
+each carrying `status_code`, `response_body`, and `request_url`. `AnchorNotFoundError` is
+raised when no anchor matches a tag, and `AmbiguousAnchorError` when more than one does.
+
+### Advanced: dependency injection
+
+```python
+client = (
+    AgroWellClient.builder()
+    .with_settings(settings)
+    .add_request_hook(my_tracing_hook)
+    .with_token_store(my_token_store)
+    .build()
+)
+```
+
+## Architecture
+
+```
+AgroWellClient (facade)
+  ├─ api/        ObjectPlacementApi → .anchors, .anchor_groups   (raw request layer, by category)
+  └─ alignment   commissioning workflow (composes api: read anchor → compute G → write group)
+        │
+        └─>  transport/ (httpx)  ──>  auth/ + models/
+```
+
+- `api/` is the **single reusable request layer**, grouped by resource category
+  (`client.api.anchors`, `client.api.anchor_groups`); domain resources like
+  `resources/alignment` compose it rather than issuing requests directly, so each endpoint
+  lives in exactly one place and a new category is one module plus one line.
+- `Transport`, `AuthStrategy`, `TokenStore` are `typing.Protocol`s (dependency inversion):
+  implementations swap and fake in tests without touching call sites.
+- **Sync today, async-ready:** the synchronous `HttpxTransport` sits behind the `Transport`
+  seam, so an async transport can be added additively later.
+- Logging uses a `NullHandler`; nothing is emitted unless your application configures it.
+- Pure math (`geometry.py`, `validation.py`) has no I/O; the validation report uploads via a
+  pluggable `ReportSink` (`reporting/sinks.py`).
+
+## Development
+
+```bash
+make install      # uv sync --extra dev   (or: python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]")
+make check        # ruff + mypy (strict) + pytest
+pytest -m integration   # live smoke test (requires AGROWELL_* env)
+```
+
+Tests use `respx` to mock httpx and a `FakeTransport` (the `Transport` Protocol) for pure
+unit tests — no network and no ROS install required.
+
+## Open items
+
+These do not block using the SDK, but must be resolved for live integration.
+
+1. **Organization is mandatory:** every anchor read/write is scoped to an organization. The
+   SDK sends `Grpc-Metadata-organization` (`AGROWELL_ORGANIZATION_ID`, required) — **and** the
+   Keycloak token must carry a matching `organization` claim, or the platform returns
+   `ErrOrgHeaderMissing` / `ErrOrgMembershipDenied`.
+2. **Group WRITE needs a backend change (blocker):** anchor reads accept the robot's
+   client-credentials token, but `UpdateAnchorsGroup` (the commissioning write) currently
+   requires a *user* token. The platform must relax that RPC to accept machine tokens (org
+   kept) before the robot can write the group transform.
+3. **Report upload:** `ObjectStoreSink` PUTs the report to a presigned URL; a backend endpoint
+   must mint it (so no object-store credentials live on the robot).
+4. **Confirm conventions:** `localization_provider_id` vs `anchor.anchors_group_id` for the
+   PATCH, and the `TransformMatrix` orientation / multiplication order (verify with one real
+   anchor round-trip).
+5. **Anchors must pre-exist** and be AR-calibrated (with `apriltag_id`s) for the organization.
+6. **API prefix:** confirm `/v1` vs `/api/v1` (`AGROWELL_API_PATH_PREFIX`).
+7. **Keycloak client:** a service-account client in realm `AGRO-WELL` (+ secret).
+8. **Distribution:** released under the [BSD 3-Clause License](LICENSE) and publishable to
+   public PyPI. Scrub the repo (and git history) for secrets / internal hosts before any
+   public release — see `.env` (gitignored) and `examples/`.
+
+## License
+
+**BSD 3-Clause License.** Copyright (c) 2026 up2metric P.C. See [`LICENSE`](LICENSE).
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided the copyright notice and the conditions in `LICENSE` are retained. For
+inquiries, contact info@up2metric.com.

agrowell_ikh_client-0.1.0/README.md

@@ -0,0 +1,235 @@
+# agrowell-ikh-client
+
+A small, typed Python SDK that bridges the **I Know How (IKH)** robot with the
+**Agro-Well** greenhouse platform.
+
+**v1 scope:**
+
+1. **Authenticate** to the platform via Keycloak (client-credentials / machine-to-machine).
+2. **Read anchors** — resolve a detected AprilTag to its platform anchor (and its AR pose).
+3. **Commission (align)** — from a reference anchor, compute the anchor-group transform that
+   maps the robot's **ROS** measurements onto the platform **AR** scene, write it, and emit a
+   quantitative **validation report**. The ROS ↔ Three.js conversion happens **internally**.
+
+> **Status:** v1 boilerplate. Some platform-side prerequisites must be confirmed before
+> live integration — see [Open items](#open-items). Open-source under the
+> [BSD 3-Clause License](LICENSE).
+
+## Installation
+
+Released under the [BSD 3-Clause License](#license). Install from PyPI:
+
+```bash
+pip install agrowell-ikh-client
+```
+
+Or from a built wheel:
+
+```bash
+pip install ./agrowell_ikh_client-<version>-py3-none-any.whl
+```
+
+Requires Python 3.10+.
+
+## Configuration
+
+Read from `AGROWELL_`-prefixed environment variables (and an optional `.env` file), or
+passed explicitly via `Settings`. Copy [`.env.example`](.env.example) to `.env` and fill
+in the values from the Agro-Well platform team.
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `AGROWELL_KEYCLOAK_BASE_PATH` | ✅ | — | Keycloak base URL |
+| `AGROWELL_KEYCLOAK_REALM` | | `AGRO-WELL` | Keycloak realm |
+| `AGROWELL_KEYCLOAK_CLIENT_ID` | ✅ | — | Service-account client id |
+| `AGROWELL_KEYCLOAK_CLIENT_SECRET` | ✅ | — | Service-account client secret |
+| `AGROWELL_API_BASE_URL` | ✅ | — | object-placement REST base URL |
+| `AGROWELL_API_PATH_PREFIX` | | `/v1` | API path prefix (`/v1` or `/api/v1`) |
+| `AGROWELL_ORGANIZATION_ID` | ✅ | — | Organization the robot belongs to (scopes all anchor reads/writes) |
+| `AGROWELL_FACILITY_ID` | ✅ | — | Facility the robot is installed at (== platform scene id; scopes every read to that facility) |
+| `AGROWELL_DEV_MODE` | | `false` | Collect a validation report during commissioning and emit it on `close()` |
+| `AGROWELL_VERIFY_SSL` | | `true` | TLS certificate verification |
+| `AGROWELL_HTTP_TIMEOUT_SECONDS` | | `10.0` | Request timeout |
+| `AGROWELL_HTTP_MAX_RETRIES` | | `3` | Retry budget for idempotent requests |
+
+## Quickstart
+
+```python
+from agrowell_ikh_client import AgroWellClient, ScannedTag
+
+with AgroWellClient.from_env() as client:
+    # Discover the anchors visible to your organization (raw platform models, AR frame):
+    anchors = client.api.anchors.list()
+
+    # Commission: on each AprilTag detection, pass the robot's measured pose (ROS frame).
+    # The SDK resolves the anchor, computes the anchor-group transform, and writes it.
+    for detection in detections:                  # your detector's per-frame loop
+        client.alignment.update_group(
+            ScannedTag(
+                apriltag_id=detection.id,
+                translation=(1.20, 0.0, 3.45),    # metres, ROS frame
+                quaternion=(0.0, 0.0, 0.0, 1.0),  # (x, y, z, w)
+            )
+        )
+```
+
+The robot needs only its **organization** (from config) and the **AprilTag ids** it scans.
+It never handles anchor UUIDs, anchors-groups, scenes, or raw 4×4 matrices — those are
+resolved or converted internally. Poses cross the SDK boundary in the **ROS** frame; the
+raw reads under `client.api.*` return platform models in the **AR (Three.js)** frame.
+
+## The rigid-isometry property (why the between-anchor check works)
+
+The internal ROS → Three.js conversion is a **rigid isometry** — a pure rotation of axes
+(`det = +1`, no scale or handedness flip), so distances and angles between anchors are
+preserved. The commissioning report exploits this: in the relative transform between two
+anchors the anchor-group transform `G` cancels, so a residual there can only come from the
+ROS ↔ AR conversion itself (a handedness/axis flip or a metre/centimetre mix-up), not from a
+single mis-placed anchor. That is what makes the between-anchor check a clean, objective
+signal even though there is no visual validation. (See `tests/test_simulation.py`.)
+
+## Commissioning (alignment + validation)
+
+After the 3 anchors are AR-calibrated in the web app, the robot aligns its ROS frame to the
+scene by writing the **anchor-group transform**. On **each** AprilTag detection it calls
+`update_group`, which resolves the anchor's AR pose, computes the group transform `G` from
+that AR pose and the detected ROS pose (`G = T_ar ∘ inverse(convert(T_ros))`), and PATCHes the
+group. This runs many times during a commissioning session.
+
+Because updating that transform moves the whole scene subtree together, there is **no visual
+validation**. So, with `AGROWELL_DEV_MODE=true`, the client collects each anchor's server
+("before") and ROS-computed ("after") pose and emits one **validation report** on `close()`.
+
+```python
+from agrowell_ikh_client import AgroWellClient, ScannedTag, ObjectStoreSink
+
+# AGROWELL_DEV_MODE=true enables the report; the sink is where it is uploaded.
+# Sinks: ObjectStoreSink (presigned URL), MinioSink.from_settings(settings) (direct MinIO/S3,
+# needs the 'minio' extra), or LocalFileSink (disk).
+with AgroWellClient.builder().with_report_sink(
+    ObjectStoreSink(presign=mint_upload_url)  # mint_upload_url(key) -> presigned PUT URL
+).build() as client:
+    for tag in detections:                     # the robot's per-detection loop
+        client.alignment.update_group(
+            ScannedTag(tag.id, tag.translation, tag.quaternion)  # ROS frame
+        )
+    # on exit: one report (per-anchor errors + between-anchor conversion check) is uploaded
+```
+
+The report (`ValidationReport`, render with `report.to_text()`) carries per-anchor
+position/orientation errors and aggregates, **plus a pairwise (between-anchor) check that the
+ROS → AR conversion holds** — in the relative transform between two anchors `G` cancels, so it
+isolates conversion errors (handedness/axis flips, metre/centimetre mix-ups) from a single
+mis-placed anchor. Try it offline: `python examples/simulate_commissioning.py`.
+
+## Usage
+
+```python
+# Raw request layer, grouped by resource category (client.api.<category>).
+
+# List the anchors visible to your organization (raw platform models, AR frame).
+# No group/scene needed; the org context scopes the result.
+anchors = client.api.anchors.list()                  # or .list(registered=False)
+
+# Resolve a single detected tag to its anchor. Raises AnchorNotFoundError if none match,
+# AmbiguousAnchorError if more than one does:
+anchor = client.api.anchors.resolve_by_tag(42)
+if anchor.image_anchor and anchor.image_anchor.transform:
+    x, y, z = anchor.image_anchor.transform.translation   # AR (Three.js) frame
+
+# Commission: per detection, compute + write the anchor-group transform from a ROS pose.
+client.alignment.update_group(
+    ScannedTag(42, translation=(1.2, 0.0, 3.45), quaternion=(0.0, 0.0, 0.0, 1.0))
+)
+```
+
+### Coordinate frames (internal)
+
+The robot speaks only **ROS** (REP-103: X-forward, Y-left, Z-up, right-handed, metres,
+quaternions). The platform stores transforms in the **Three.js** AR frame (right-handed,
+Y-up). The SDK converts at the boundary automatically (`ROS_X = −AR_Z`, `ROS_Y = −AR_X`,
+`ROS_Z = AR_Y`); it is not a user-facing option. If the platform's AR engine ever changes,
+that is a one-line internal change.
+
+### Error handling
+
+All errors derive from `AgroWellError`. HTTP errors map to typed exceptions
+(`BadRequestError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ServerError`, …),
+each carrying `status_code`, `response_body`, and `request_url`. `AnchorNotFoundError` is
+raised when no anchor matches a tag, and `AmbiguousAnchorError` when more than one does.
+
+### Advanced: dependency injection
+
+```python
+client = (
+    AgroWellClient.builder()
+    .with_settings(settings)
+    .add_request_hook(my_tracing_hook)
+    .with_token_store(my_token_store)
+    .build()
+)
+```
+
+## Architecture
+
+```
+AgroWellClient (facade)
+  ├─ api/        ObjectPlacementApi → .anchors, .anchor_groups   (raw request layer, by category)
+  └─ alignment   commissioning workflow (composes api: read anchor → compute G → write group)
+        │
+        └─>  transport/ (httpx)  ──>  auth/ + models/
+```
+
+- `api/` is the **single reusable request layer**, grouped by resource category
+  (`client.api.anchors`, `client.api.anchor_groups`); domain resources like
+  `resources/alignment` compose it rather than issuing requests directly, so each endpoint
+  lives in exactly one place and a new category is one module plus one line.
+- `Transport`, `AuthStrategy`, `TokenStore` are `typing.Protocol`s (dependency inversion):
+  implementations swap and fake in tests without touching call sites.
+- **Sync today, async-ready:** the synchronous `HttpxTransport` sits behind the `Transport`
+  seam, so an async transport can be added additively later.
+- Logging uses a `NullHandler`; nothing is emitted unless your application configures it.
+- Pure math (`geometry.py`, `validation.py`) has no I/O; the validation report uploads via a
+  pluggable `ReportSink` (`reporting/sinks.py`).
+
+## Development
+
+```bash
+make install      # uv sync --extra dev   (or: python3.11 -m venv .venv && .venv/bin/pip install -e ".[dev]")
+make check        # ruff + mypy (strict) + pytest
+pytest -m integration   # live smoke test (requires AGROWELL_* env)
+```
+
+Tests use `respx` to mock httpx and a `FakeTransport` (the `Transport` Protocol) for pure
+unit tests — no network and no ROS install required.
+
+## Open items
+
+These do not block using the SDK, but must be resolved for live integration.
+
+1. **Organization is mandatory:** every anchor read/write is scoped to an organization. The
+   SDK sends `Grpc-Metadata-organization` (`AGROWELL_ORGANIZATION_ID`, required) — **and** the
+   Keycloak token must carry a matching `organization` claim, or the platform returns
+   `ErrOrgHeaderMissing` / `ErrOrgMembershipDenied`.
+2. **Group WRITE needs a backend change (blocker):** anchor reads accept the robot's
+   client-credentials token, but `UpdateAnchorsGroup` (the commissioning write) currently
+   requires a *user* token. The platform must relax that RPC to accept machine tokens (org
+   kept) before the robot can write the group transform.
+3. **Report upload:** `ObjectStoreSink` PUTs the report to a presigned URL; a backend endpoint
+   must mint it (so no object-store credentials live on the robot).
+4. **Confirm conventions:** `localization_provider_id` vs `anchor.anchors_group_id` for the
+   PATCH, and the `TransformMatrix` orientation / multiplication order (verify with one real
+   anchor round-trip).
+5. **Anchors must pre-exist** and be AR-calibrated (with `apriltag_id`s) for the organization.
+6. **API prefix:** confirm `/v1` vs `/api/v1` (`AGROWELL_API_PATH_PREFIX`).
+7. **Keycloak client:** a service-account client in realm `AGRO-WELL` (+ secret).
+8. **Distribution:** released under the [BSD 3-Clause License](LICENSE) and publishable to
+   public PyPI. Scrub the repo (and git history) for secrets / internal hosts before any
+   public release — see `.env` (gitignored) and `examples/`.
+
+## License
+
+**BSD 3-Clause License.** Copyright (c) 2026 up2metric P.C. See [`LICENSE`](LICENSE).
+Redistribution and use in source and binary forms, with or without modification, are
+permitted provided the copyright notice and the conditions in `LICENSE` are retained. For
+inquiries, contact info@up2metric.com.