# AGENTS.md — Python Workspace Guide

This file defines coding-agent guidance for:
`/workspaces/zed-playground/py_workspace`

Use this as the primary reference for Python work in this repository.

---

## 1) Scope & Environment

- Package manager: **uv**
- Python: **3.12+**
- Project file: `pyproject.toml`
- Main package/work area: top-level scripts + `aruco/` + `tests/`
- Non-primary/vendor-like areas (avoid unless explicitly asked):
  - `loguru/`
  - `tmp/`
  - `libs/`

Core dependencies include:
- `pyzed`, `opencv-python`, `click`, `numpy`, `scipy`
- `loguru`, `awkward`, `jaxtyping`, `pyarrow`, `pandas`

Dev dependencies:
- `pytest`, `basedpyright`

---

## 2) Build / Run / Lint / Test Commands

Run commands from:
`/workspaces/zed-playground/py_workspace`

Environment sync:
```bash
uv sync
uv run python -V
```

Run common scripts:
```bash
uv run streaming_receiver.py --help
uv run recording_multi.py
uv run calibrate_extrinsics.py --help
```

Type-check / lint-equivalent:
```bash
uv run basedpyright
```

Run all tests:
```bash
uv run pytest
```

Run a single test file:
```bash
uv run pytest tests/test_depth_refine.py
```

Run a single test function:
```bash
uv run pytest tests/test_depth_refine.py::test_refine_extrinsics_with_depth_with_offset
```

Run subset by keyword:
```bash
uv run pytest -k "depth and refine"
```

Useful options:
```bash
uv run pytest -x -vv
```

Notes from `pyproject.toml`:
- `testpaths = ["tests"]`
- `norecursedirs = ["loguru", "tmp", "libs"]`

---

## 3) Rules Files (Cursor / Copilot)

Latest scan in this workspace found:
- No `.cursorrules`
- No `.cursor/rules/`
- No `.github/copilot-instructions.md`

If these files appear later, treat them as higher-priority local instructions.

---

## 4) Python Code Style Conventions

### Imports
- Group imports: standard library → third-party → local modules.
- Use ZED import style:
  - `import pyzed.sl as sl`
- In package modules (`aruco/*`), prefer relative imports:
  - `from .pose_math import ...`
- In top-level scripts, absolute imports are common:
  - `from aruco.detector import ...`

### Formatting & structure
- 4-space indentation.
- PEP8-style layout.
- Keep functions focused and composable.
- Prefer explicit CLI options over positional ambiguity.

### Typing
- Add type hints on public and most internal functions.
- Existing code uses both:
  - `typing.Optional/List/Dict/Tuple`
  - modern `|` unions
  Stay consistent with the surrounding file.
- When arrays/matrices are central, use `jaxtyping` shape aliases (with `TYPE_CHECKING` guards) where already established.
- Avoid broad `Any` unless unavoidable at library boundaries (OpenCV/pyzed interop).

### Naming
- `snake_case`: functions, variables, modules.
- `PascalCase`: classes.
- `UPPER_SNAKE_CASE`: constants.

### Docstrings
- Use concise purpose + `Args` / `Returns`.
- Document expected array shapes and units for geometry/math functions.

### Logging & output
- User-facing CLI output: `click.echo`.
- Diagnostic logs: `loguru` (`logger.debug/info/warning`).
- Keep verbose logs behind a `--debug` flag.

### Error handling
- Raise specific exceptions (`ValueError`, `FileNotFoundError`, etc.) with actionable messages.
- For CLI fatal paths, use `click.UsageError` or `SystemExit(1)` patterns.
- Validate early (shape/range/None) before expensive compute.

---

## 5) Testing Conventions

- Framework: `pytest`
- Numerical checks: use `numpy.testing.assert_allclose` where appropriate.
- Exception checks: `pytest.raises(..., match=...)`.
- Place/add tests under `tests/`.
- For `aruco/*` behavior changes, update related tests (`test_depth_*`, `test_alignment`, etc.).

---

## 6) Project-Specific ZED Guidance

### Streaming vs Fusion architecture
- Streaming API sends compressed video; host computes depth/tracking.
- Fusion API sends metadata; host does lightweight fusion.
- Do not assume built-in depth-map streaming parity with metadata fusion.

### Units
- Keep units explicit and consistent end-to-end.
- Marker parquet geometry is meter-based in this workspace.
- Be careful with ZED depth unit configuration and conversions.

### Threading
- OpenCV GUI (`cv2.imshow`, `cv2.waitKey`) should stay on main thread.
- Use worker thread(s) for grab/retrieve and queue handoff patterns.

### Network config
- Follow `zed_network_utils.py` and `zed_settings/inside_network.json` patterns.

---

## 7) Agent Workflow Checklist

Before editing:
1. Identify target file/module and nearest existing pattern.
2. Confirm expected command(s) from this guide.
3. Check for relevant existing tests.

After editing:
1. Run focused tests first.
2. Run broader test selection as needed.
3. Run `uv run basedpyright` on final pass.
4. Keep changes minimal and avoid unrelated churn.

If uncertain:
- Prefer small, verifiable changes.
- Document assumptions in PR/commit notes.