refactor: BuilderArgs Protocol + ModelConfig/TrainConfig field deduplication

[Borda]

What does this PR do?

Item #7 — BuilderArgs Protocol:

• Add src/rfdetr/models/_types.py with @runtime_checkable BuilderArgs Protocol
  documenting the minimum attribute set for build_model() and
  build_criterion_and_postprocessors().
• Annotate both builder functions with args: "BuilderArgs".
• Export BuilderArgs from rfdetr.models.__all__.

Item #3 Phase A — field ownership deprecation warnings:

• TrainConfig.group_detr, .ia_bce_loss, .segmentation_head, .num_select
  emit DeprecationWarning when explicitly set (ownership moves to ModelConfig
  in v1.9).
• ModelConfig.cls_loss_coef emits DeprecationWarning when explicitly set
  (ownership moves to TrainConfig in v1.9).
• Fix _namespace.py: num_select always reads from ModelConfig (fixes the
  silent regression where TrainConfig.num_select=300 overrode model-specific
  values of 100–200).
• Fix _namespace.py: cls_loss_coef reads from TrainConfig by default, with
  backward-compat fallback to ModelConfig when explicitly set there and not on
  TrainConfig (Phase A transitional logic; Codex-supplied fix).

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• Refactoring (no functional changes)

Testing

• I have tested this change locally
• I have added/updated tests for this change

Additional Context

[Copilot]

Pull request overview

This PR introduces a typed BuilderArgs protocol for model builder functions and implements/validates a Phase A transition of config field ownership between ModelConfig and TrainConfig (with deprecation warnings), including fixing num_select precedence in the builder namespace.

Changes:

• Added BuilderArgs (typing.Protocol) and annotated build_model() / build_criterion_and_postprocessors() to accept it; exported via rfdetr.models.
• Added DeprecationWarning emission when deprecated fields are explicitly set on the “wrong” config object.
• Updated _namespace.build_namespace() to source num_select from ModelConfig unconditionally and to apply transitional precedence for cls_loss_coef; expanded tests and changelog accordingly.

Reviewed changes

Copilot reviewed 9 out of 9 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
src/rfdetr/models/_types.py	Adds BuilderArgs Protocol describing builder inputs.
src/rfdetr/models/lwdetr.py	Annotates builder functions to accept BuilderArgs.
src/rfdetr/models/__init__.py	Re-exports BuilderArgs from rfdetr.models.
src/rfdetr/config.py	Adds model/train config validators that emit deprecation warnings for field ownership transitions.
src/rfdetr/_namespace.py	Fixes namespace forwarding for num_select and implements transitional cls_loss_coef precedence logic.
tests/test_namespace.py	Adds tests for BuilderArgs satisfaction and for field ownership/precedence rules.
tests/training/test_args.py	Updates tests to expect deprecation warnings for explicit deprecated field usage.
tests/models/test_config.py	Adds coverage for deprecation warnings and non-warning defaults behavior.
CHANGELOG.md	Documents the new Protocol, deprecations, and the num_select regression fix under Unreleased.

Comments suppressed due to low confidence (1)

src/rfdetr/models/lwdetr.py:356

• build_model() is now typed as taking BuilderArgs, but later in this function it mutates args (e.g. setting args.num_feature_levels). If the stated goal is to eventually pass ModelConfig/TrainConfig directly, Pydantic configs forbid setting undeclared attributes, so this will break at runtime. Prefer computing derived values locally (or building a separate mutable namespace) instead of mutating the incoming args.

def build_model(args: "BuilderArgs"):
    # the `num_classes` naming here is somewhat misleading.
    # it indeed corresponds to `max_obj_id + 1`, where max_obj_id
    # is the maximum id for a class in your dataset. For example,
    # COCO has a max_obj_id of 90, so we pass `num_classes` to be 91.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76%. Comparing base (3cd6898) to head (d50fa7e).

❌ Your project check has failed because the head coverage (76%) is below the target coverage (95%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@          Coverage Diff           @@
##           develop   #841   +/-   ##
======================================
  Coverage       75%    76%           
======================================
  Files           92     93    +1     
  Lines         7148   7222   +74     
======================================
+ Hits          5383   5457   +74     
  Misses        1765   1765           

🚀 New features to boost your workflow:

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