{"owner":"roboflow","repo":"supervision","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md",".github/copilot-instructions.md"],"skills":{"AGENTS.md":"# Agent Guidelines for `supervision`\n\nBehave like a senior contributor: precise, efficient, maintainable. When this file and [CONTRIBUTING.md](.github/CONTRIBUTING.md) conflict, **CONTRIBUTING.md wins**.\n\n______________________________________________________________________\n\n## 1. Before You Code\n\n- Read the task thoroughly; group clarifications into one ask.\n- Outline a plan before making changes.\n- Check whether the feature already exists under a different name.\n- Confirm alignment with `src/supervision/` architecture.\n\n______________________________________________________________________\n\n## 2. Repository Architecture\n\n**Package root**: `src/supervision/` — all library code. **Tests**: `tests/` — mirrors `src/supervision/`. **Public API**: `src/supervision/__init__.py`.\n\n```\nsrc/supervision/\n├── detection/\n│   ├── core.py          — Detections dataclass; all model connectors as classmethods\n│   ├── compact_mask.py  — compact mask representation\n│   ├── vlm.py           — VLM connectors (Florence-2, Gemini, Qwen, PaliGemma)\n│   ├── utils/           — pure NumPy helpers: boxes, converters, iou_and_nms, masks, polygons\n│   ├── line_zone.py     — LineZone\n│   └── tools/           — InferenceSlicer, PolygonZone, CSVSink, JSONSink, DetectionsSmoother\n├── annotators/core.py   — BoxAnnotator, MaskAnnotator, LabelAnnotator, … each: .annotate(scene, detections)\n├── key_points/          — KeyPoints, EdgeAnnotator, VertexAnnotator (use this, NOT keypoint/ — see §4)\n├── tracker/             — DEPRECATED\n├── dataset/core.py      — DetectionDataset / ClassificationDataset (YOLO / COCO / Pascal VOC)\n├── geometry/core.py     — Point, Rect, Vector, Position\n├── metrics/             — mAP, confusion matrix (requires --extra metrics)\n├── utils/internal.py    — warn_deprecated, deprecated_parameter, internal helpers\n└── config.py            — string constants; always import from here, never use literals\n```\n\n### Key design patterns\n\n- **`Detections` is the lingua franca** — every connector, tracker, and annotator speaks `Detections`. New connector = `@classmethod from_<framework>(cls, result) -> Detections`.\n- **Annotators are composable** — receive `scene` (BGR `np.ndarray`) + `detections`, return annotated copy.\n- **`data` dict extensibility** — per-detection metadata in `detections.data` as `np.ndarray` aligned with `xyxy`. Keys are constants from `config.py`.\n- **Vectorized throughout** — NumPy arrays, no Python loops in hot paths. Never write `for det in detections`.\n- **Lazy-import heavy deps** — `torch`, `transformers`, `ultralytics` must be imported inside the function that needs them, never at module top level.\n\n______________________________________________________________________\n\n## 3. Agent-Critical Rules\n\nThese supplement [CONTRIBUTING.md](.github/CONTRIBUTING.md) — covering gaps or agent-specific failure modes.\n\n**Doc headings**: `###` max in docstrings and docs. `####` renders identically to bold in mkdocs — use `**bold**` instead.\n\n**Type hints**: required on all new code. mypy is enforced by pre-commit (`.pre-commit-config.yaml`).\n\n**Function docstrings**: every new or modified function, including private helpers and tests, must have a succinct docstring explaining its purpose. Put function-level why/what/how context inside the function docstring, not in a comment before the function. Public APIs still require the full Google-style structure described below.\n\n**Readable argument lists**: do not put multi-branch conditional expressions inside function or constructor arguments. If an argument needs more than a simple `a if condition else b`, assign it to a named local variable before the call.\n\n**Inline comments**: write code so the intent is clear from names, small helpers, and straightforward control flow. For non-trivial logic inside a function that still needs context, add concise inline comments explaining why the code exists, what invariant it protects, and how the tricky part works. Do not put comments before functions; use the function docstring instead. Do not comment obvious assignments, mechanical plumbing, lint-only changes, typing-only changes, or pure docs edits.\n\n**Doctest determinism** — output must be reproducible across platforms:\n\n- Use `# doctest: +ELLIPSIS` for floats that vary by platform.\n- Seed any RNG before calling it.\n- Never assert `dict` or `set` iteration order.\n- No network or filesystem access outside `supervision/assets/`.\n\n**⚠ Test structure** — agents frequently fail here; read [CONTRIBUTING.md §Tests](.github/CONTRIBUTING.md#-tests) carefully: AAA structure, class grouping, parametrize with `pytest.param(..., id=\"slug\")`, one-line docstring per test.\n\nFor branching, commit, code style, and API design conventions see [CONTRIBUTING.md](.github/CONTRIBUTING.md).\n\n______________________________________________________________________\n\n## 4. Deprecated Module Aliases\n\n`supervision.keypoint` deprecated since `0.27.0`, removed in `0.31.0`. Always import from `supervision.key_points`, not `supervision.keypoint`.\n\n______________________________________________________________________\n\n## 5. Deprecating APIs\n\n**Minimum window**: deprecated APIs must remain for at least **3 minor releases** before removal. Example: deprecated in `0.29.0` → removed in `0.32.0`.\n\n- Module-level: `supervision.utils.internal.warn_deprecated` in the deprecated module's own `__init__.py`\n- Parameter renamed (old→new): `supervision.utils.internal.deprecated_parameter` decorator\n- Public function, method, or class: `@deprecated` from `pydeprecate`\n\nAlways name the version introduced and the removal version:\n\n```python\nwarn_deprecated(\"'foo' deprecated in `0.29.0`, removed in `0.32.0`. Use 'bar'.\")\n```\n\n______________________________________________________________________\n\n## 6. Implementing Features\n\n- Minimal implementation; type hints and Google docstrings with usage examples.\n- Tests covering new functionality and edge cases (see [CONTRIBUTING.md §Tests](.github/CONTRIBUTING.md#-tests)).\n- Update docstrings and mkdocs entries as needed.\n- Update [docs/changelog.md](docs/changelog.md) for every functional change or bug fix, including user-visible behavior changes. Skip changelog entries for lint-only, type-only, formatting-only, and pure documentation-only changes.\n\n**Extending `Detections`**: store metadata in `detections.data` as `np.ndarray` aligned with `xyxy`; define the key as a constant in `config.py` (e.g. `CLASS_NAME_DATA_FIELD`, `ORIENTED_BOX_COORDINATES`).\n\n**New model connector** (`detection/core.py`):\n\n```python\n@classmethod\ndef from_myframework(cls, result) -> \"Detections\":\n    import myframework  # noqa: F401 — lazy import\n\n    xyxy = ...  # (N, 4)\n    return cls(\n        xyxy=xyxy,\n        confidence=...,\n        class_id=...,\n        data={CLASS_NAME_DATA_FIELD: np.array([...])},\n    )\n```\n\nVLM connectors go in `detection/vlm.py`, not `core.py`.\n\n______________________________________________________________________\n\n## 7. Bugs & Refactoring\n\n**Bugs**: reproduce → write failing test → minimal fix → verify no regressions.\n\n**Refactoring**: preserve behavior and API; reduce duplication; avoid sweeping changes unless requested; apply §5 deprecation when removing public API.\n\n______________________________________________________________________\n\n## 8. Before You Commit\n\n```bash\nuv run pytest --cov=supervision\nuv run pre-commit run --all-files\n```\n\nCapture a baseline before changes to avoid introducing new failures:\n\n```bash\nSTASH_BEFORE=$(git rev-parse refs/stash 2>/dev/null)\ngit stash push --include-untracked\nuv run pytest -q 2>&1 | tee /tmp/baseline.txt\n[ \"$(git rev-parse refs/stash 2>/dev/null)\" != \"$STASH_BEFORE\" ] && git stash pop\nuv run pytest -q 2>&1 | tee /tmp/after.txt\ndiff /tmp/baseline.txt /tmp/after.txt\n```\n\nAny test passing in baseline but failing after = blocker.\n","CLAUDE.md":"# Claude Code Project Instructions\n\n<!-- Imports AGENTS.md, which contains agent roles, behavioral rules, and coding constraints for this project. -->\n\n@AGENTS.md\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for Supervision\n\nThis file provides context-aware guidance for GitHub Copilot when working in the Supervision repository.\n\n______________________________________________________________________\n\n## 📚 Repository Overview\n\n**Supervision** is a Python library providing reusable computer vision utilities for working with object detection models (YOLO, SAM, etc.). It offers tools for detections processing, tracking, annotation, and dataset management.\n\n- **Languages**: Python 3.10+\n- **Key Dependencies**: NumPy, OpenCV, SciPy\n- **License**: MIT\n\n______________________________________________________________________\n\n## 🏗️ Project Structure\n\n```\nsupervision/\n├── src/\n│   └── supervision/     # Main library code\n│       ├── detection/   # Detection utilities\n│       ├── draw/        # Annotation and visualization\n│       ├── tracker/     # Object tracking\n│       ├── dataset/     # Dataset management\n│       └── utils/       # Shared utilities\n├── tests/               # Test suite (mirrors src/supervision/)\n├── docs/                # MkDocs documentation\n└── examples/            # Usage examples\n```\n\n______________________________________________________________________\n\n## 🔧 Development Commands\n\n**Setup:**\n\n```bash\n# Install dependencies\nuv sync --group dev --group docs --extra metrics\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n**Quality Checks:**\n\n```bash\n# Run all pre-commit hooks (formatting, linting, type checking)\nuv run pre-commit run --all-files\n\n# Run tests with coverage\nuv run pytest --cov=supervision\n```\n\n**Documentation:**\n\n```bash\n# Serve docs locally at http://127.0.0.1:8000\nuv run mkdocs serve\n```\n\n______________________________________________________________________\n\n## 💻 Code Conventions\n\n### General Guidelines\n\n- Follow **[AGENTS.md](../AGENTS.md)** for task-based development workflows\n- Reference **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed contribution guidelines\n- All code must pass `pre-commit` hooks before committing\n\n### Code Style\n\n- **Formatting**: Enforced by `ruff-format`, `prettier` (pre-commit)\n- **Linting**: Enforced by `ruff-check` (pre-commit)\n- **Type Hints**: Required on all new code\n- **Docstrings**: Required using [Google Python style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods)\n  - Must include usage examples with primitive values\n  - Serve as runnable documentation\n\n### Performance\n\n- Avoid unnecessary NumPy array copies\n- Prefer vectorized operations over Python loops\n- Use OpenCV operations efficiently\n\n### API Design\n\n- Follow existing naming patterns for consistency\n- Maintain backward compatibility unless explicitly breaking\n- Prefer functional utilities over complex classes\n\n______________________________________________________________________\n\n## 🧪 Testing Requirements\n\nAll new features must include:\n\n- Unit tests covering happy path and edge cases\n- Tests for `None`, empty inputs, large arrays, boundary conditions\n- Clear test names describing what they validate\n- Proper assertions (not just \"no exception raised\")\n\n______________________________________________________________________\n\n## 📝 Documentation Requirements\n\nFor new public functions/classes:\n\n- Google-style docstrings with parameters, returns, exceptions\n- Usage examples in docstrings\n- Entry in appropriate `docs/*.md` file\n- Reference in `mkdocs.yml` navigation\n\n______________________________________________________________________\n\n## 🔍 Pull Request Reviews\n\n**When reviewing PRs, follow the comprehensive [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines).**\n\nQuick checklist:\n\n- Tests included and passing\n- Docstrings follow Google style with examples\n- Pre-commit hooks pass\n- Breaking changes documented\n- Score code quality, testing, docs (n/5 scale)\n- Use inline comments + GitHub suggestion format\n\n______________________________________________________________________\n\n## 🌿 Branching & Commits\n\n- Branch from `develop` using prefixes: `feat/`, `fix/`, `docs/`, `refactor/`, `perf/`, `test/`, `chore/`\n- Use **conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `perf:`, `test:`, `chore:`\n- All PRs target `develop` branch\n\n______________________________________________________________________\n\n## 🎯 Context-Aware Behavior\n\n- **For general development tasks**: Follow [AGENTS.md](../AGENTS.md)\n- **For pull request reviews**: Follow [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines)\n- **For detailed processes**: Consult [CONTRIBUTING.md](CONTRIBUTING.md)\n"},"files":{"AGENTS.md":"# Agent Guidelines for `supervision`\n\nBehave like a senior contributor: precise, efficient, maintainable. When this file and [CONTRIBUTING.md](.github/CONTRIBUTING.md) conflict, **CONTRIBUTING.md wins**.\n\n______________________________________________________________________\n\n## 1. Before You Code\n\n- Read the task thoroughly; group clarifications into one ask.\n- Outline a plan before making changes.\n- Check whether the feature already exists under a different name.\n- Confirm alignment with `src/supervision/` architecture.\n\n______________________________________________________________________\n\n## 2. Repository Architecture\n\n**Package root**: `src/supervision/` — all library code. **Tests**: `tests/` — mirrors `src/supervision/`. **Public API**: `src/supervision/__init__.py`.\n\n```\nsrc/supervision/\n├── detection/\n│   ├── core.py          — Detections dataclass; all model connectors as classmethods\n│   ├── compact_mask.py  — compact mask representation\n│   ├── vlm.py           — VLM connectors (Florence-2, Gemini, Qwen, PaliGemma)\n│   ├── utils/           — pure NumPy helpers: boxes, converters, iou_and_nms, masks, polygons\n│   ├── line_zone.py     — LineZone\n│   └── tools/           — InferenceSlicer, PolygonZone, CSVSink, JSONSink, DetectionsSmoother\n├── annotators/core.py   — BoxAnnotator, MaskAnnotator, LabelAnnotator, … each: .annotate(scene, detections)\n├── key_points/          — KeyPoints, EdgeAnnotator, VertexAnnotator (use this, NOT keypoint/ — see §4)\n├── tracker/             — DEPRECATED\n├── dataset/core.py      — DetectionDataset / ClassificationDataset (YOLO / COCO / Pascal VOC)\n├── geometry/core.py     — Point, Rect, Vector, Position\n├── metrics/             — mAP, confusion matrix (requires --extra metrics)\n├── utils/internal.py    — warn_deprecated, deprecated_parameter, internal helpers\n└── config.py            — string constants; always import from here, never use literals\n```\n\n### Key design patterns\n\n- **`Detections` is the lingua franca** — every connector, tracker, and annotator speaks `Detections`. New connector = `@classmethod from_<framework>(cls, result) -> Detections`.\n- **Annotators are composable** — receive `scene` (BGR `np.ndarray`) + `detections`, return annotated copy.\n- **`data` dict extensibility** — per-detection metadata in `detections.data` as `np.ndarray` aligned with `xyxy`. Keys are constants from `config.py`.\n- **Vectorized throughout** — NumPy arrays, no Python loops in hot paths. Never write `for det in detections`.\n- **Lazy-import heavy deps** — `torch`, `transformers`, `ultralytics` must be imported inside the function that needs them, never at module top level.\n\n______________________________________________________________________\n\n## 3. Agent-Critical Rules\n\nThese supplement [CONTRIBUTING.md](.github/CONTRIBUTING.md) — covering gaps or agent-specific failure modes.\n\n**Doc headings**: `###` max in docstrings and docs. `####` renders identically to bold in mkdocs — use `**bold**` instead.\n\n**Type hints**: required on all new code. mypy is enforced by pre-commit (`.pre-commit-config.yaml`).\n\n**Function docstrings**: every new or modified function, including private helpers and tests, must have a succinct docstring explaining its purpose. Put function-level why/what/how context inside the function docstring, not in a comment before the function. Public APIs still require the full Google-style structure described below.\n\n**Readable argument lists**: do not put multi-branch conditional expressions inside function or constructor arguments. If an argument needs more than a simple `a if condition else b`, assign it to a named local variable before the call.\n\n**Inline comments**: write code so the intent is clear from names, small helpers, and straightforward control flow. For non-trivial logic inside a function that still needs context, add concise inline comments explaining why the code exists, what invariant it protects, and how the tricky part works. Do not put comments before functions; use the function docstring instead. Do not comment obvious assignments, mechanical plumbing, lint-only changes, typing-only changes, or pure docs edits.\n\n**Doctest determinism** — output must be reproducible across platforms:\n\n- Use `# doctest: +ELLIPSIS` for floats that vary by platform.\n- Seed any RNG before calling it.\n- Never assert `dict` or `set` iteration order.\n- No network or filesystem access outside `supervision/assets/`.\n\n**⚠ Test structure** — agents frequently fail here; read [CONTRIBUTING.md §Tests](.github/CONTRIBUTING.md#-tests) carefully: AAA structure, class grouping, parametrize with `pytest.param(..., id=\"slug\")`, one-line docstring per test.\n\nFor branching, commit, code style, and API design conventions see [CONTRIBUTING.md](.github/CONTRIBUTING.md).\n\n______________________________________________________________________\n\n## 4. Deprecated Module Aliases\n\n`supervision.keypoint` deprecated since `0.27.0`, removed in `0.31.0`. Always import from `supervision.key_points`, not `supervision.keypoint`.\n\n______________________________________________________________________\n\n## 5. Deprecating APIs\n\n**Minimum window**: deprecated APIs must remain for at least **3 minor releases** before removal. Example: deprecated in `0.29.0` → removed in `0.32.0`.\n\n- Module-level: `supervision.utils.internal.warn_deprecated` in the deprecated module's own `__init__.py`\n- Parameter renamed (old→new): `supervision.utils.internal.deprecated_parameter` decorator\n- Public function, method, or class: `@deprecated` from `pydeprecate`\n\nAlways name the version introduced and the removal version:\n\n```python\nwarn_deprecated(\"'foo' deprecated in `0.29.0`, removed in `0.32.0`. Use 'bar'.\")\n```\n\n______________________________________________________________________\n\n## 6. Implementing Features\n\n- Minimal implementation; type hints and Google docstrings with usage examples.\n- Tests covering new functionality and edge cases (see [CONTRIBUTING.md §Tests](.github/CONTRIBUTING.md#-tests)).\n- Update docstrings and mkdocs entries as needed.\n- Update [docs/changelog.md](docs/changelog.md) for every functional change or bug fix, including user-visible behavior changes. Skip changelog entries for lint-only, type-only, formatting-only, and pure documentation-only changes.\n\n**Extending `Detections`**: store metadata in `detections.data` as `np.ndarray` aligned with `xyxy`; define the key as a constant in `config.py` (e.g. `CLASS_NAME_DATA_FIELD`, `ORIENTED_BOX_COORDINATES`).\n\n**New model connector** (`detection/core.py`):\n\n```python\n@classmethod\ndef from_myframework(cls, result) -> \"Detections\":\n    import myframework  # noqa: F401 — lazy import\n\n    xyxy = ...  # (N, 4)\n    return cls(\n        xyxy=xyxy,\n        confidence=...,\n        class_id=...,\n        data={CLASS_NAME_DATA_FIELD: np.array([...])},\n    )\n```\n\nVLM connectors go in `detection/vlm.py`, not `core.py`.\n\n______________________________________________________________________\n\n## 7. Bugs & Refactoring\n\n**Bugs**: reproduce → write failing test → minimal fix → verify no regressions.\n\n**Refactoring**: preserve behavior and API; reduce duplication; avoid sweeping changes unless requested; apply §5 deprecation when removing public API.\n\n______________________________________________________________________\n\n## 8. Before You Commit\n\n```bash\nuv run pytest --cov=supervision\nuv run pre-commit run --all-files\n```\n\nCapture a baseline before changes to avoid introducing new failures:\n\n```bash\nSTASH_BEFORE=$(git rev-parse refs/stash 2>/dev/null)\ngit stash push --include-untracked\nuv run pytest -q 2>&1 | tee /tmp/baseline.txt\n[ \"$(git rev-parse refs/stash 2>/dev/null)\" != \"$STASH_BEFORE\" ] && git stash pop\nuv run pytest -q 2>&1 | tee /tmp/after.txt\ndiff /tmp/baseline.txt /tmp/after.txt\n```\n\nAny test passing in baseline but failing after = blocker.\n","CLAUDE.md":"# Claude Code Project Instructions\n\n<!-- Imports AGENTS.md, which contains agent roles, behavioral rules, and coding constraints for this project. -->\n\n@AGENTS.md\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for Supervision\n\nThis file provides context-aware guidance for GitHub Copilot when working in the Supervision repository.\n\n______________________________________________________________________\n\n## 📚 Repository Overview\n\n**Supervision** is a Python library providing reusable computer vision utilities for working with object detection models (YOLO, SAM, etc.). It offers tools for detections processing, tracking, annotation, and dataset management.\n\n- **Languages**: Python 3.10+\n- **Key Dependencies**: NumPy, OpenCV, SciPy\n- **License**: MIT\n\n______________________________________________________________________\n\n## 🏗️ Project Structure\n\n```\nsupervision/\n├── src/\n│   └── supervision/     # Main library code\n│       ├── detection/   # Detection utilities\n│       ├── draw/        # Annotation and visualization\n│       ├── tracker/     # Object tracking\n│       ├── dataset/     # Dataset management\n│       └── utils/       # Shared utilities\n├── tests/               # Test suite (mirrors src/supervision/)\n├── docs/                # MkDocs documentation\n└── examples/            # Usage examples\n```\n\n______________________________________________________________________\n\n## 🔧 Development Commands\n\n**Setup:**\n\n```bash\n# Install dependencies\nuv sync --group dev --group docs --extra metrics\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n**Quality Checks:**\n\n```bash\n# Run all pre-commit hooks (formatting, linting, type checking)\nuv run pre-commit run --all-files\n\n# Run tests with coverage\nuv run pytest --cov=supervision\n```\n\n**Documentation:**\n\n```bash\n# Serve docs locally at http://127.0.0.1:8000\nuv run mkdocs serve\n```\n\n______________________________________________________________________\n\n## 💻 Code Conventions\n\n### General Guidelines\n\n- Follow **[AGENTS.md](../AGENTS.md)** for task-based development workflows\n- Reference **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed contribution guidelines\n- All code must pass `pre-commit` hooks before committing\n\n### Code Style\n\n- **Formatting**: Enforced by `ruff-format`, `prettier` (pre-commit)\n- **Linting**: Enforced by `ruff-check` (pre-commit)\n- **Type Hints**: Required on all new code\n- **Docstrings**: Required using [Google Python style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods)\n  - Must include usage examples with primitive values\n  - Serve as runnable documentation\n\n### Performance\n\n- Avoid unnecessary NumPy array copies\n- Prefer vectorized operations over Python loops\n- Use OpenCV operations efficiently\n\n### API Design\n\n- Follow existing naming patterns for consistency\n- Maintain backward compatibility unless explicitly breaking\n- Prefer functional utilities over complex classes\n\n______________________________________________________________________\n\n## 🧪 Testing Requirements\n\nAll new features must include:\n\n- Unit tests covering happy path and edge cases\n- Tests for `None`, empty inputs, large arrays, boundary conditions\n- Clear test names describing what they validate\n- Proper assertions (not just \"no exception raised\")\n\n______________________________________________________________________\n\n## 📝 Documentation Requirements\n\nFor new public functions/classes:\n\n- Google-style docstrings with parameters, returns, exceptions\n- Usage examples in docstrings\n- Entry in appropriate `docs/*.md` file\n- Reference in `mkdocs.yml` navigation\n\n______________________________________________________________________\n\n## 🔍 Pull Request Reviews\n\n**When reviewing PRs, follow the comprehensive [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines).**\n\nQuick checklist:\n\n- Tests included and passing\n- Docstrings follow Google style with examples\n- Pre-commit hooks pass\n- Breaking changes documented\n- Score code quality, testing, docs (n/5 scale)\n- Use inline comments + GitHub suggestion format\n\n______________________________________________________________________\n\n## 🌿 Branching & Commits\n\n- Branch from `develop` using prefixes: `feat/`, `fix/`, `docs/`, `refactor/`, `perf/`, `test/`, `chore/`\n- Use **conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `perf:`, `test:`, `chore:`\n- All PRs target `develop` branch\n\n______________________________________________________________________\n\n## 🎯 Context-Aware Behavior\n\n- **For general development tasks**: Follow [AGENTS.md](../AGENTS.md)\n- **For pull request reviews**: Follow [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines)\n- **For detailed processes**: Consult [CONTRIBUTING.md](CONTRIBUTING.md)\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Agent Guidelines for `supervision`\n\nBehave like a senior contributor: precise, efficient, maintainable. When this file and [CONTRIBUTING.md](.github/CONTRIBUTING.md) conflict, **CONTRIBUTING.md wins**.\n\n______________________________________________________________________\n\n## 1. Before You Code\n\n- Read the task thoroughly; group clarifications into one ask.\n- Outline a plan before making changes.\n- Check whether the feature already exists under a different name.\n- Confirm alignment with `src/supervision/` architecture.\n\n______________________________________________________________________\n\n## 2. Repository Architecture\n\n**Package root**: `src/supervision/` — all library code. **Tests**: `tests/` — mirrors `src/supervision/`. **Public API**: `src/supervision/__init__.py`.\n\n```\nsrc/supervision/\n├── detection/\n│   ├── core.py          — Detections dataclass; all model connectors as classmethods\n│   ├── compact_mask.py  — compact mask representation\n│   ├── vlm.py           — VLM connectors (Florence-2, Gemini, Qwen, PaliGemma)\n│   ├── utils/           — pure NumPy helpers: boxes, converters, iou_and_nms, masks, polygons\n│   ├── line_zone.py     — LineZone\n│   └── tools/           — InferenceSlicer, PolygonZone, CSVSink, JSONSink, DetectionsSmoother\n├── annotators/core.py   — BoxAnnotator, MaskAnnotator, LabelAnnotator, … each: .annotate(scene, detections)\n├── key_points/          — KeyPoints, EdgeAnnotator, VertexAnnotator (use this, NOT keypoint/ — see §4)\n├── tracker/             — DEPRECATED\n├── dataset/core.py      — DetectionDataset / ClassificationDataset (YOLO / COCO / Pascal VOC)\n├── geometry/core.py     — Point, Rect, Vector, Position\n├── metrics/             — mAP, confusion matrix (requires --extra metrics)\n├── utils/internal.py    — warn_deprecated, deprecated_parameter, internal helpers\n└── config.py            — string constants; always import from here, never use literals\n```\n\n### Key design patterns\n\n- **`Detections` is the lingua franca** — every connector, tracker, and annotator speaks `Detections`. New connector = `@classmethod from_<framework>(cls, result) -> Detections`.\n- **Annotators are composable** — receive `scene` (BGR `np.ndarray`) + `detections`, return annotated copy.\n- **`data` dict extensibility** — per-detection metadata in `detections.data` as `np.ndarray` aligned with `xyxy`. Keys are constants from `config.py`.\n- **Vectorized throughout** — NumPy arrays, no Python loops in hot paths. Never write `for det in detections`.\n- **Lazy-import heavy deps** — `torch`, `transformers`, `ultralytics` must be imported inside the function that needs them, never at module top level.\n\n______________________________________________________________________\n\n## 3. Agent-Critical Rules\n\nThese supplement [CONTRIBUTING.md](.github/CONTRIBUTING.md) — covering gaps or agent-specific failure modes.\n\n**Doc headings**: `###` max in docstrings and docs. `####` renders identically to bold in mkdocs — use `**bold**` instead.\n\n**Type hints**: required on all new code. mypy is enforced by pre-commit (`.pre-commit-config.yaml`).\n\n**Function docstrings**: every new or modified function, including private helpers and tests, must have a succinct docstring explaining its purpose. Put function-level why/what/how context inside the function docstring, not in a comment before the function. Public APIs still require the full Google-style structure described below.\n\n**Readable argument lists**: do not put multi-branch conditional expressions inside function or constructor arguments. If an argument needs more than a simple `a if condition else b`, assign it to a named local variable before the call.\n\n**Inline comments**: write code so the intent is clear from names, small helpers, and straightforward control flow. For non-trivial logic inside a function that still needs context, add concise inline comments explaining why the code exists, what invariant it protects, and how the tricky part works. Do not put comments before functions; use the function docstring instead. Do not comment obvious assignments, mechanical plumbing, lint-only changes, typing-only changes, or pure docs edits.\n\n**Doctest determinism** — output must be reproducible across platforms:\n\n- Use `# doctest: +ELLIPSIS` for floats that vary by platform.\n- Seed any RNG before calling it.\n- Never assert `dict` or `set` iteration order.\n- No network or filesystem access outside `supervision/assets/`.\n\n**⚠ Test structure** — agents frequently fail here; read [CONTRIBUTING.md §Tests](.github/CONTRIBUTING.md#-tests) carefully: AAA structure, class grouping, parametrize with `pytest.param(..., id=\"slug\")`, one-line docstring per test.\n\nFor branching, commit, code style, and API design conventions see [CONTRIBUTING.md](.github/CONTRIBUTING.md).\n\n______________________________________________________________________\n\n## 4. Deprecated Module Aliases\n\n`supervision.keypoint` deprecated since `0.27.0`, removed in `0.31.0`. Always import from `supervision.key_points`, not `supervision.keypoint`.\n\n______________________________________________________________________\n\n## 5. Deprecating APIs\n\n**Minimum window**: deprecated APIs must remain for at least **3 minor releases** before removal. Example: deprecated in `0.29.0` → removed in `0.32.0`.\n\n- Module-level: `supervision.utils.internal.warn_deprecated` in the deprecated module's own `__init__.py`\n- Parameter renamed (old→new): `supervision.utils.internal.deprecated_parameter` decorator\n- Public function, method, or class: `@deprecated` from `pydeprecate`\n\nAlways name the version introduced and the removal version:\n\n```python\nwarn_deprecated(\"'foo' deprecated in `0.29.0`, removed in `0.32.0`. Use 'bar'.\")\n```\n\n______________________________________________________________________\n\n## 6. Implementing Features\n\n- Minimal implementation; type hints and Google docstrings with usage examples.\n- Tests covering new functionality and edge cases (see [CONTRIBUTING.md §Tests](.github/CONTRIBUTING.md#-tests)).\n- Update docstrings and mkdocs entries as needed.\n- Update [docs/changelog.md](docs/changelog.md) for every functional change or bug fix, including user-visible behavior changes. Skip changelog entries for lint-only, type-only, formatting-only, and pure documentation-only changes.\n\n**Extending `Detections`**: store metadata in `detections.data` as `np.ndarray` aligned with `xyxy`; define the key as a constant in `config.py` (e.g. `CLASS_NAME_DATA_FIELD`, `ORIENTED_BOX_COORDINATES`).\n\n**New model connector** (`detection/core.py`):\n\n```python\n@classmethod\ndef from_myframework(cls, result) -> \"Detections\":\n    import myframework  # noqa: F401 — lazy import\n\n    xyxy = ...  # (N, 4)\n    return cls(\n        xyxy=xyxy,\n        confidence=...,\n        class_id=...,\n        data={CLASS_NAME_DATA_FIELD: np.array([...])},\n    )\n```\n\nVLM connectors go in `detection/vlm.py`, not `core.py`.\n\n______________________________________________________________________\n\n## 7. Bugs & Refactoring\n\n**Bugs**: reproduce → write failing test → minimal fix → verify no regressions.\n\n**Refactoring**: preserve behavior and API; reduce duplication; avoid sweeping changes unless requested; apply §5 deprecation when removing public API.\n\n______________________________________________________________________\n\n## 8. Before You Commit\n\n```bash\nuv run pytest --cov=supervision\nuv run pre-commit run --all-files\n```\n\nCapture a baseline before changes to avoid introducing new failures:\n\n```bash\nSTASH_BEFORE=$(git rev-parse refs/stash 2>/dev/null)\ngit stash push --include-untracked\nuv run pytest -q 2>&1 | tee /tmp/baseline.txt\n[ \"$(git rev-parse refs/stash 2>/dev/null)\" != \"$STASH_BEFORE\" ] && git stash pop\nuv run pytest -q 2>&1 | tee /tmp/after.txt\ndiff /tmp/baseline.txt /tmp/after.txt\n```\n\nAny test passing in baseline but failing after = blocker.\n","category":"root","tokens":1961},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Claude Code Project Instructions\n\n<!-- Imports AGENTS.md, which contains agent roles, behavioral rules, and coding constraints for this project. -->\n\n@AGENTS.md\n","category":"root","tokens":41},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# GitHub Copilot Instructions for Supervision\n\nThis file provides context-aware guidance for GitHub Copilot when working in the Supervision repository.\n\n______________________________________________________________________\n\n## 📚 Repository Overview\n\n**Supervision** is a Python library providing reusable computer vision utilities for working with object detection models (YOLO, SAM, etc.). It offers tools for detections processing, tracking, annotation, and dataset management.\n\n- **Languages**: Python 3.10+\n- **Key Dependencies**: NumPy, OpenCV, SciPy\n- **License**: MIT\n\n______________________________________________________________________\n\n## 🏗️ Project Structure\n\n```\nsupervision/\n├── src/\n│   └── supervision/     # Main library code\n│       ├── detection/   # Detection utilities\n│       ├── draw/        # Annotation and visualization\n│       ├── tracker/     # Object tracking\n│       ├── dataset/     # Dataset management\n│       └── utils/       # Shared utilities\n├── tests/               # Test suite (mirrors src/supervision/)\n├── docs/                # MkDocs documentation\n└── examples/            # Usage examples\n```\n\n______________________________________________________________________\n\n## 🔧 Development Commands\n\n**Setup:**\n\n```bash\n# Install dependencies\nuv sync --group dev --group docs --extra metrics\n\n# Install pre-commit hooks\nuv run pre-commit install\n```\n\n**Quality Checks:**\n\n```bash\n# Run all pre-commit hooks (formatting, linting, type checking)\nuv run pre-commit run --all-files\n\n# Run tests with coverage\nuv run pytest --cov=supervision\n```\n\n**Documentation:**\n\n```bash\n# Serve docs locally at http://127.0.0.1:8000\nuv run mkdocs serve\n```\n\n______________________________________________________________________\n\n## 💻 Code Conventions\n\n### General Guidelines\n\n- Follow **[AGENTS.md](../AGENTS.md)** for task-based development workflows\n- Reference **[CONTRIBUTING.md](CONTRIBUTING.md)** for detailed contribution guidelines\n- All code must pass `pre-commit` hooks before committing\n\n### Code Style\n\n- **Formatting**: Enforced by `ruff-format`, `prettier` (pre-commit)\n- **Linting**: Enforced by `ruff-check` (pre-commit)\n- **Type Hints**: Required on all new code\n- **Docstrings**: Required using [Google Python style](https://google.github.io/styleguide/pyguide.html#383-functions-and-methods)\n  - Must include usage examples with primitive values\n  - Serve as runnable documentation\n\n### Performance\n\n- Avoid unnecessary NumPy array copies\n- Prefer vectorized operations over Python loops\n- Use OpenCV operations efficiently\n\n### API Design\n\n- Follow existing naming patterns for consistency\n- Maintain backward compatibility unless explicitly breaking\n- Prefer functional utilities over complex classes\n\n______________________________________________________________________\n\n## 🧪 Testing Requirements\n\nAll new features must include:\n\n- Unit tests covering happy path and edge cases\n- Tests for `None`, empty inputs, large arrays, boundary conditions\n- Clear test names describing what they validate\n- Proper assertions (not just \"no exception raised\")\n\n______________________________________________________________________\n\n## 📝 Documentation Requirements\n\nFor new public functions/classes:\n\n- Google-style docstrings with parameters, returns, exceptions\n- Usage examples in docstrings\n- Entry in appropriate `docs/*.md` file\n- Reference in `mkdocs.yml` navigation\n\n______________________________________________________________________\n\n## 🔍 Pull Request Reviews\n\n**When reviewing PRs, follow the comprehensive [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines).**\n\nQuick checklist:\n\n- Tests included and passing\n- Docstrings follow Google style with examples\n- Pre-commit hooks pass\n- Breaking changes documented\n- Score code quality, testing, docs (n/5 scale)\n- Use inline comments + GitHub suggestion format\n\n______________________________________________________________________\n\n## 🌿 Branching & Commits\n\n- Branch from `develop` using prefixes: `feat/`, `fix/`, `docs/`, `refactor/`, `perf/`, `test/`, `chore/`\n- Use **conventional commits**: `feat:`, `fix:`, `docs:`, `refactor:`, `perf:`, `test:`, `chore:`\n- All PRs target `develop` branch\n\n______________________________________________________________________\n\n## 🎯 Context-Aware Behavior\n\n- **For general development tasks**: Follow [AGENTS.md](../AGENTS.md)\n- **For pull request reviews**: Follow [PR Review Guidelines](CONTRIBUTING.md#pr-review-guidelines)\n- **For detailed processes**: Consult [CONTRIBUTING.md](CONTRIBUTING.md)\n","category":".github","tokens":1140}]}