docs(agents): refine AGENTS.md

[Borda]

This pull request significantly expands and clarifies the AGENTS.md guidelines for contributors and AI agents, bringing them into closer alignment with the project's architecture and conventions. The updates introduce detailed descriptions of the repository structure, coding and testing standards, and explicit rules for extending, deprecating, and testing APIs. The document now provides a comprehensive, structured reference for both human and AI contributors.

Key improvements and additions:

Repository Structure and Design Patterns

• Added a detailed table and descriptions of all core modules in src/supervision/, including the purpose of each, and clarified the use of Detections as the central data structure. Key design patterns (e.g., vectorization, extensibility, stateless functions) are now explicitly documented.

Coding Standards and Dependencies

• Updated conventions for formatting, linting, and type hints: pre-commit hooks are now listed explicitly, and mypy is enforced. Provided a list of required runtime dependencies and clarified lazy-import rules for heavy frameworks.
• Clarified function/class promotion rules and docstring requirements, emphasizing Google-style docstrings with usage examples and deterministic doctests.

Testing and Doctest Conventions

• Introduced a comprehensive section on test conventions, including the AAA structure, class grouping, parametrization, and docstring requirements for tests. Added detailed doctest rules to ensure deterministic and reproducible examples.

Feature Implementation and API Extension

• Added step-by-step instructions for extending Detections with new metadata, including the use of constants from config.py. Provided a template for adding new model connectors and clarified where VLM connectors should reside.

Deprecation and Refactoring

• Added explicit deprecation guidelines, including mechanisms for module-level, parameter, and public API deprecation, with required version annotations. Clarified the process for refactoring, emphasizing the use of deprecation machinery when changing public APIs. [1] [2]

Test Baseline and Pre-Commit Process

• Improved instructions for pre-commit and test verification: contributors are now required to capture a baseline of test results before making changes and must ensure no new test failures are introduced.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 80%. Comparing base (8a40630) to head (9b851ce).

Additional details and impacted files

@@           Coverage Diff           @@
##           develop   #2308   +/-   ##
=======================================
  Coverage       80%     80%           
=======================================
  Files           66      66           
  Lines         8787    8787           
=======================================
  Hits          7046    7046           
  Misses        1741    1741           

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR expands AGENTS.md into a more comprehensive contributor/agent reference, documenting repository architecture, coding conventions, testing expectations, and API extension/deprecation patterns to better align day-to-day contributions with the supervision codebase structure.

Changes:

• Adds a detailed repository architecture/module map and highlights key design patterns centered around Detections.
• Codifies conventions for formatting, typing, dependencies, doctests, and test structure.
• Documents guidance for extending Detections, adding model/VLM connectors, and deprecating/refactoring public APIs.