# AGENTS.md — Repository Guide for Coding Agents

This file is for autonomous/agentic coding in `/workspaces/zed-playground`.
Primary active Python workspace: `/workspaces/zed-playground/py_workspace`.

---

## 1) Environment & Scope

- Python package manager: **uv**
- Python version: **3.12+**
- Core deps (py_workspace): `pyzed`, `opencv-python`, `click`, `numpy`, `scipy`, `loguru`, `awkward`, `jaxtyping`
- Dev deps: `pytest`, `basedpyright`
- Treat `py_workspace/loguru/` and `py_workspace/tmp/` as non-primary project areas unless explicitly asked.

---

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

### Python (py_workspace)

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

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

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

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

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 by keyword:
```bash
uv run pytest -k "depth and refine"
```

Useful verbosity / fail-fast options:
```bash
uv run pytest -x -vv
```

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

### C++ sample project (body tracking)

Run from:
`/workspaces/zed-playground/playground/body tracking/multi-camera/cpp/build`

```bash
cmake ..
make -j4
./ZED_BodyFusion <config_file.json>
```

---

## 3) Rules Files Scan (Cursor / Copilot)

As of latest scan:
- No `.cursorrules` found
- No `.cursor/rules/` found
- No `.github/copilot-instructions.md` found

If these files are later added, treat them as higher-priority local policy and update this guide.

---

## 4) Code Style Conventions (Python)

### Imports
- Prefer grouping: stdlib → third-party → local modules.
- ZED imports use `import pyzed.sl as sl`.
- In package modules (`aruco/*`), use relative imports (`from .pose_math import ...`).
- In top-level scripts, absolute package imports are common (`from aruco... import ...`).

### Formatting & structure
- 4-space indentation, PEP8-style layout.
- Keep functions focused; isolate heavy logic into helper functions.
- Favor explicit CLI options via `click.option` rather than positional ambiguity.

### Typing
- Type hints are expected on public and most internal functions.
- Existing code uses both `typing.Optional/List/Dict` and modern `|` syntax; stay consistent with surrounding file.
- Use `jaxtyping` shape hints when already used in module (`TYPE_CHECKING` guard pattern).
- Avoid `Any` unless unavoidable (OpenCV / pyzed boundaries).

### Naming
- `snake_case`: functions, variables, modules.
- `PascalCase`: classes.
- `UPPER_SNAKE_CASE`: constants (e.g., dictionary maps).

### Docstrings
- Include concise purpose + `Args` / `Returns` where helpful.
- For matrix/array-heavy functions, document expected shape and units.

### Logging & user output
- CLI-facing messaging: use `click.echo`.
- Diagnostic/internal logs: use `loguru` (`logger.debug/info/warning`).
- Keep debug noise behind `--debug` style flag where possible.

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

---

## 5) Testing Conventions

- Framework: `pytest`
- Numeric assertions: prefer `numpy.testing.assert_allclose` where appropriate.
- Exception checks: `pytest.raises(..., match=...)`.
- Add tests under `py_workspace/tests/`.
- If adding behavior in `aruco/*`, add or update corresponding tests (`test_depth_*`, `test_alignment`, etc.).

---

## 6) ZED-Specific Project Guidance

### Architecture reminder: Streaming vs Fusion
- Streaming API: send compressed video, compute depth/tracking on host.
- Fusion API: publish metadata (bodies/poses), lightweight host fusion.
- There is no built-in “stream depth map” mode in the same way as metadata fusion.

### Depth units
- Be explicit with coordinate units and keep units consistent end-to-end.
- Marker geometry/parquet conventions in this repo are meter-based; do not mix mm/m silently.

### Threading
- OpenCV GUI (`cv2.imshow`, `cv2.waitKey`) belongs on main thread.
- Capture/grab work in worker threads with queue handoff.

### Network config
- Use `zed_network_utils.py` and `zed_settings/inside_network.json` conventions.

---

## 7) Agent Execution Checklist

Before editing:
1. Identify target workspace (`py_workspace` vs playground C++).
2. Confirm commands from this file and nearby module docs.
3. Search for existing tests covering the area.

After editing:
1. Run focused test(s) first, then broader test run as needed.
2. Run `uv run basedpyright` for type regressions.
3. Keep diffs minimal and avoid unrelated file churn.

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