docs: add API design principles to contribution guidelines

- Update AGENTS.md with detailed API design principles for consistency.
- Expand CONTRIBUTING.md to include a new "API Design Principles" section.

Author: Borda

.github/CONTRIBUTING.md

@@ -12,6 +12,7 @@ Please read and adhere to our [Code of Conduct](https://supervision.roboflow.com
 
 - [Contribution Guidelines](#contribution-guidelines)
     - [Contributing Features](#contributing-features)
+    - [API Design Principles](#api-design-principles)
 - [How to Contribute Changes](#how-to-contribute-changes)
 - [Installation for Contributors](#installation-for-contributors)
 - [Code Style and Quality](#code-style-and-quality)
@@ -41,6 +42,38 @@ For example, counting objects that cross a line anywhere on an image is a common
 
 Before you contribute a new feature, consider submitting an Issue to discuss the feature so the community can weigh in and assist.
 
+### API Design Principles
+
+Supervision APIs should remain generic, composable, and predictable across model
+families. Before adding a new integration, annotator option, or data conversion
+method, check the existing `sv.Detections`, `sv.KeyPoints`, and annotator
+patterns and follow these principles:
+
+1. **Model integrations normalize raw external outputs into existing Supervision
+    containers.** Use `sv.Detections` for detection, segmentation, and other
+    instance-level predictions that include boxes, masks, class ids, confidence
+    scores, or extra per-instance fields. Use `sv.KeyPoints` for standalone
+    keypoint or pose predictions.
+2. **Do not add a `from_<model>` method when the model already returns a
+    Supervision object.** `from_*` methods are for converting raw outputs from
+    external packages such as Ultralytics, Transformers, Inference, or MediaPipe.
+    If a model's `predict()` method already returns `sv.Detections`, keep that
+    result type and store additional structured payloads in `detections.data` or
+    `detections.metadata` using documented keys.
+3. **Annotators render data; filtering and visibility are container state.**
+    Filtering by confidence, class id, tracker id, geometry, or custom data should
+    happen before annotation through the container slicing APIs, for example
+    `detections[detections.confidence > 0.7]` or an equivalent `sv.KeyPoints`
+    filter. Per-point presentation state, such as a `KeyPoints.visible` mask, may
+    live on the container and be honored consistently by annotators.
+4. **Annotator constructor arguments should describe visual presentation, not
+    model-quality gates.** Use constructor arguments for color, thickness,
+    opacity, text, position, style, and generic visualization parameters such as
+    sigma levels. Annotators may skip invalid geometry defensively, including
+    missing points, zero-area boxes, non-finite coordinates, or points marked
+    invisible on the container. They should not introduce confidence thresholds or
+    model-specific quality gates as rendering options.
+
 ## How to Contribute Changes
 
 First, fork this repository to your own GitHub account. Click "fork" in the top corner of the `supervision` repository to get started:

AGENTS.md

@@ -46,6 +46,18 @@ All work must follow the conventions of the `supervision` library
 - Follow existing naming patterns.
 - Maintain backward compatibility unless explicitly allowed.
 - Prefer functional utilities over complex classes unless justified.
+- Treat [.github/CONTRIBUTING.md](.github/CONTRIBUTING.md#api-design-principles)
+    as the canonical API design reference.
+- Keep model integrations aligned with existing containers: models that already
+    return `sv.Detections` should continue to do so, with extra payloads stored
+    in `data` or `metadata` under documented keys.
+- Reserve `from_*` methods for converting raw outputs from external packages
+    into Supervision containers; do not add one-off adapters for outputs that are
+    already `sv.Detections` or `sv.KeyPoints`.
+- Annotators render already-selected data. Do filtering by confidence, class id,
+    tracker id, geometry, or custom fields before annotation with container
+    slicing APIs, not annotator constructor arguments. Container-level visibility
+    masks may be honored by annotators when documented consistently.
 
 ### Performance