autovision-framework 0.3.0__py3-none-any.whl

autovision/__init__.py

@@ -0,0 +1,134 @@
+# Copyright (c) 2026 AutoVision contributors. Apache-2.0.
+"""AutoVision: enterprise visual model training framework.
+
+Public API:
+
+- :func:`autovision.pretrain` — self-supervised pretraining / distillation.
+- :func:`autovision.detection` / :func:`autovision.load_model` — object
+  detection model handles (``train / val / predict / export``).
+- :func:`autovision.ensure_coco8` — bundled synthetic smoke dataset.
+- :func:`autovision.list_models` — all models exposed by registered packages.
+- :func:`autovision.list_methods` — all registered pretraining methods.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import torch
+
+from autovision import errors
+from autovision._compat import install_graphmodule_deepcopy_fix
+from autovision._version import __version__
+from autovision.cli import (
+    PretrainConfig,
+    PretrainResult,
+    TaskTrainResult,
+    pretrain,
+    train_depth_estimation,
+    train_image_classification,
+    train_instance_segmentation,
+    train_object_detection,
+    train_oriented_object_detection,
+    train_panoptic_segmentation,
+    train_pose_estimation,
+    train_semantic_segmentation,
+)
+from autovision.cli.extract_video_frames import extract_video_frames
+from autovision.cli.model_handle import (
+    DetectionModel,
+    detection,
+    evaluate_object_detection,
+    load_model,
+)
+from autovision.data.coco8 import ensure_coco8
+from autovision.encoders import list_models
+from autovision.errors import AutoVisionError
+from autovision.export import benchmark, measure_model_cost
+from autovision.features import embed
+from autovision.plugins import (
+    PluginInfo,
+    discover_plugins,
+    list_plugins,
+    register_plugin,
+)
+from autovision.pretext import list_methods
+from autovision.registry.catalog import (
+    describe_model,
+    get_model_entry,
+    list_task_models,
+)
+from autovision.runtime.checkpoint import CHECKPOINT_AUTOVISION_KEY
+from autovision.tasks.task_model_helpers import load_task_model
+
+# Third-party defect shims must be installed before any model construction.
+install_graphmodule_deepcopy_fix()
+
+__all__ = [
+    "AutoVisionError",
+    "DetectionModel",
+    "PluginInfo",
+    "PretrainConfig",
+    "PretrainResult",
+    "__version__",
+    "detection",
+    "describe_model",
+    "discover_plugins",
+    "errors",
+    "get_model_entry",
+    "list_methods",
+    "list_models",
+    "list_plugins",
+    "list_task_models",
+    "register_plugin",
+    "embed",
+    "benchmark",
+    "measure_model_cost",
+    "ensure_coco8",
+    "evaluate_object_detection",
+    "extract_video_frames",
+    "load_embedding_model",
+    "load_model",
+    "load_task_model",
+    "pretrain",
+    "train_image_classification",
+    "train_instance_segmentation",
+    "train_object_detection",
+    "train_oriented_object_detection",
+    "train_panoptic_segmentation",
+    "train_semantic_segmentation",
+    "train_depth_estimation",
+    "train_pose_estimation",
+]
+
+
+def load_embedding_model(path: str | Path, device: str | None = None) -> Any:
+    """Load an exported embedding model (``exported_models/*.pt``).
+
+    Rebuilds the ``FeatureExtractor`` from the exported metadata. The backbone
+    must be resolvable via ``model_name`` recorded in the export — the
+    export stores the state dict and normalization args; the backbone name
+    is part of the run config, so this loader accepts it explicitly.
+    """
+    from autovision.encoders import FeatureExtractor, get_wrapped_model
+    from autovision.encoders._model_helpers import load_state_dict_compat
+
+    raw = torch.load(path, map_location="cpu", weights_only=True)
+    if not isinstance(raw, dict) or "kind" not in raw:
+        raise ValueError(f"File '{path}' is not an exported AutoVision model.")
+    model_name = raw.get("model_name")
+    if model_name is None:
+        raise ValueError(
+            f"Export '{path}' does not record 'model_name'; pass the model "
+            f"specification to rebuild the backbone."
+        )
+    wrapper = get_wrapped_model(model_name)
+    embedding_model = FeatureExtractor(
+        wrapped_model=wrapper, embed_dim=raw.get("embed_dim")
+    )
+    load_state_dict_compat(embedding_model, raw["state_dict"])
+    if device is not None:
+        embedding_model.to(device)
+    embedding_model.eval()
+    return embedding_model

autovision/_compat.py

@@ -0,0 +1,57 @@
+# Copyright (c) 2026 AutoVision contributors. Apache-2.0.
+"""Compatibility shims for known third-party defects.
+
+Imported once by :mod:`autovision` (see package ``__init__``) so that every
+``copy.deepcopy`` site in the codebase — EMA trackers, distillation teachers,
+export benchmarks — is protected from the GraphModule defect below.
+"""
+
+from __future__ import annotations
+
+import copy
+
+__all__ = ["install_graphmodule_deepcopy_fix"]
+
+_PATCH_FLAG = "_autovision_graphmodule_deepcopy_fix"
+# Plain attributes torchvision's GraphModule stores in __init__ and swaps in
+# train(); torch.fx.GraphModule.__deepcopy__ does not carry them over.
+_GRAPH_ATTRS = ("train_graph", "eval_graph")
+
+
+def install_graphmodule_deepcopy_fix() -> None:
+    """Keep torchvision ``GraphModule`` train/eval graphs alive across deepcopy.
+
+    ``torch.fx.GraphModule.__deepcopy__`` rebuilds the copy with ``__new__``
+    plus the fx base-class ``__init__`` and only restores a fixed list of
+    hook attributes. torchvision's ``feature_extraction.GraphModule`` and
+    ``DualGraphModule`` (used by the RT-DETR / DFINE hybrid encoders) store
+    ``train_graph`` / ``eval_graph`` as plain attributes and swap
+    ``self.graph`` inside ``train()`` — the fx copy drops them, so any
+    ``.eval()`` / ``.train()`` on a deepcopied model raises
+    ``AttributeError: 'GraphModule' object has no attribute 'eval_graph'``.
+
+    The fx implementation already deep-copied the full ``__dict__`` into an
+    intermediate module, so re-copying the two graphs here is served by the
+    shared memo. Idempotent; a no-op without torchvision.
+    """
+    try:
+        from torchvision.models import feature_extraction as _fe
+    except ImportError:  # torchvision is optional for pure-pretraining flows
+        return
+    for graph_module_cls in (
+        getattr(_fe, "GraphModule", None),
+        getattr(_fe, "DualGraphModule", None),
+    ):
+        if graph_module_cls is None or getattr(graph_module_cls, _PATCH_FLAG, False):
+            continue
+        setattr(graph_module_cls, _PATCH_FLAG, True)
+        fx_deepcopy = graph_module_cls.__deepcopy__
+
+        def __deepcopy__(self, memo, _fx_deepcopy=fx_deepcopy):  # noqa: N807
+            res = _fx_deepcopy(self, memo)
+            for attr in _GRAPH_ATTRS:
+                if attr in self.__dict__ and not hasattr(res, attr):
+                    setattr(res, attr, copy.deepcopy(self.__dict__[attr], memo))
+            return res
+
+        graph_module_cls.__deepcopy__ = __deepcopy__

autovision/_license.py

@@ -0,0 +1,13 @@
+# Copyright (c) 2026 AutoVision contributors. Apache-2.0.
+"""License notice embedded into checkpoints and exported models."""
+
+__all__ = ["LICENSE_INFO"]
+
+LICENSE_INFO = (
+    "AutoVision License Notice\n"
+    "\n"
+    "The AutoVision framework is licensed under Apache-2.0. Trained model "
+    "weights may be subject to additional licenses: check the licenses of the "
+    "backbone models, teacher weights, and training data used for a given "
+    "run before any production use."
+)

autovision/_version.py

@@ -0,0 +1,15 @@
+# Copyright (c) 2026 AutoVision contributors. Apache-2.0.
+"""Single source of truth for the framework version (no import cycles).
+
+Read by three consumers, all of which must stay consistent:
+
+- ``pyproject.toml`` packaging (``[tool.setuptools.dynamic]``, static AST
+  read — keep the assignment a plain string literal);
+- the public ``autovision.__version__`` export;
+- release tooling / tests (version vs ``CHANGELOG.md`` vs the ``vX.Y.Z``
+  release tag, see ``docs/release_process.md``).
+"""
+
+__all__ = ["__version__"]
+
+__version__ = "0.3.0"

autovision/augment/__init__.py

@@ -0,0 +1,27 @@
+# Copyright (c) 2026 AutoVision contributors. Apache-2.0.
+"""Transforms: argument models, view pipelines, and method transforms."""
+
+from autovision.augment.method_transform import MethodTransform, MultiViewTransform
+from autovision.augment.transform_args import (
+    ColorJitterArgs,
+    GaussianBlurArgs,
+    MethodTransformArgs,
+    NormalizeArgs,
+    RandomFlipArgs,
+    RandomResizeArgs,
+    SolarizeArgs,
+)
+from autovision.augment.view_transform import ViewTransform
+
+__all__ = [
+    "ColorJitterArgs",
+    "GaussianBlurArgs",
+    "MethodTransform",
+    "MethodTransformArgs",
+    "MultiViewTransform",
+    "NormalizeArgs",
+    "RandomFlipArgs",
+    "RandomResizeArgs",
+    "SolarizeArgs",
+    "ViewTransform",
+]

autovision/augment/detection/__init__.py

@@ -0,0 +1,42 @@
+# Copyright (c) 2026 AutoVision contributors. Apache-2.0.
+"""Detection transform family (torchvision v2 based, step scheduled)."""
+
+from autovision.augment.detection.args import (
+    OrientedObjectDetectionTransformArgs,
+    RTDETRDetectionTransformArgs,
+    ScaleJitterArgs,
+)
+from autovision.augment.detection.collate import (
+    RTDETRDetectionCollateFunction,
+    TwoViewDetectionCollateFunction,
+)
+from autovision.augment.detection.oriented_transform import (
+    OrientedObjectDetectionCollateFunction,
+    OrientedObjectDetectionTransform,
+    build_oriented_val_transform_args,
+)
+from autovision.augment.detection.schedule import (
+    StepSchedule,
+    resolve_detection_step_schedule,
+)
+from autovision.augment.detection.transform import (
+    RTDETRDetectionTransform,
+    StepScheduledCompose,
+    build_val_transform_args,
+)
+
+__all__ = [
+    "OrientedObjectDetectionCollateFunction",
+    "OrientedObjectDetectionTransform",
+    "OrientedObjectDetectionTransformArgs",
+    "RTDETRDetectionCollateFunction",
+    "RTDETRDetectionTransform",
+    "RTDETRDetectionTransformArgs",
+    "ScaleJitterArgs",
+    "StepSchedule",
+    "StepScheduledCompose",
+    "TwoViewDetectionCollateFunction",
+    "build_oriented_val_transform_args",
+    "build_val_transform_args",
+    "resolve_detection_step_schedule",
+]

autovision/augment/detection/args.py

@@ -0,0 +1,168 @@
+# Copyright (c) 2026 AutoVision contributors. Apache-2.0.
+"""Detection transform arguments with step-window policies."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import Field
+
+from autovision.augment.task_transform import TaskTransformArgs
+from autovision.augment.transform_args import NormalizeArgs
+from autovision.config.base import PydanticConfig
+from autovision.types import ImageSizeTuple
+
+__all__ = [
+    "OrientedObjectDetectionTransformArgs",
+    "RTDETRDetectionTransformArgs",
+    "ScaleJitterArgs",
+]
+
+
+class ScaleJitterArgs(PydanticConfig):
+    sizes: list[int]
+    prob: float = 1.0
+    #: Step at which batch scale jitter turns OFF (the baseline disables it
+    #: for the final no-augmentation window). ``None`` keeps it on for the
+    #: whole run; ``"auto"`` resolves to the shared step schedule.
+    step_stop: int | None | str = None
+
+
+class OrientedObjectDetectionTransformArgs(TaskTransformArgs):
+    """Oriented (YOLO-OBB) detection recipe.
+
+    Rotated-box pipeline: flips mirror corners, resize scales corners,
+    polygons are sanitized by px² shoelace area. IoU-crop / zoom-out /
+    scale-jitter / mixup are omitted — the torchvision v2 implementations
+    behind them are axis-aligned-box-only.
+    """
+
+    image_size: ImageSizeTuple = (640, 640)
+    photometric_distort_prob: float | None = 0.5
+    horizontal_flip_prob: float = 0.5
+    vertical_flip_prob: float = 0.0
+    normalize: NormalizeArgs = Field(default_factory=NormalizeArgs)
+    min_bbox_size_px: float = 4.0
+
+
+class RTDETRDetectionTransformArgs(TaskTransformArgs):
+    """Detection recipe (train defaults; the val recipe disables them)."""
+
+    image_size: ImageSizeTuple | Literal["auto"] = "auto"
+    num_channels: int | Literal["auto"] = "auto"
+    photometric_distort_prob: float | None = 0.5
+    random_zoom_out_prob: float | None = 0.5
+    random_iou_crop_prob: float | None = 0.8
+    horizontal_flip_prob: float = 0.5
+    vertical_flip_prob: float = 0.0
+    scale_jitter: ScaleJitterArgs | None = Field(
+        default_factory=lambda: ScaleJitterArgs(
+            sizes=[480, 512, 544, 576, 608, 640, 640, 640, 672, 704, 736, 768, 800]
+        )
+    )
+    mixup_prob: float | None = 0.5
+    #: Copy-paste blending (baseline AV-DETR CopyBlend, XOR with mixup in
+    #: the collate): paste up to ``num_objects`` object crops sampled from
+    #: the batch pool into each image, beta-blended. Default off; the
+    #: VisDrone/official recipes disable both mixup and copyblend.
+    copyblend_prob: float | None = None
+    copyblend_area_threshold: int = 100
+    copyblend_num_objects: int = 3
+    copyblend_expand_ratios: tuple[float, float] = (0.1, 0.25)
+    #: Step at which copy-paste blending turns ON (baseline CopyBlend
+    #: window is ``[step_start, step_stop)`` with the start shared with
+    #: the photometric family). An unresolved ``"auto"`` keeps it OFF —
+    #: the baseline's fail-closed gate.
+    copyblend_step_start: int | str = "auto"
+    copyblend_step_stop: int | None | str = "auto"
+    mixup_step_start: int | str = "auto"
+    mixup_step_stop: int | None | str = "auto"
+    #: Mosaic (4-tile sample-level paste; off by default — the AV-DETR
+    #: family enables it per the baseline recipe). Mosaic samples skip the
+    #: zoom-out and IoU-crop ops for that step.
+    mosaic_prob: float | None = None
+    mosaic_output_size: int = 320
+    mosaic_step_start: int | str = "auto"
+    mosaic_step_stop: int | None | str = "auto"
+    #: Box-aware background erasure (rf-detr-ssl-v2 design doc 8): erase a
+    #: uniform random subset of ``random_erase_cell``-px background cells per
+    #: view while protecting every margin-dilated GT box (any-overlap), so
+    #: Hungarian matching never sees an evidence-free box. None = off.
+    random_erase_prob: float | None = None
+    random_erase_ratio: float = Field(default=0.4, gt=0.0, le=1.0)
+    random_erase_padding: float = Field(default=0.15, ge=0.0)
+    #: Cell edge in px. On a ViT backbone this aligns with the patch size;
+    #: on ConvNeXt (stride-4 stages) 16px is an empirical granularity
+    #: choice, not a structural alignment.
+    random_erase_cell: int = Field(default=16, ge=1)
+    #: Constrained foreground erasure (design doc V2): box interiors become
+    #: erasable behind a per-box reservation, so every object keeps at least
+    #: ``random_erase_min_keep`` patches (boxes with at most that many cells
+    #: stay fully protected).
+    random_erase_interior: bool = False
+    random_erase_min_keep: int = Field(default=2, ge=1)
+    #: Step at which erasure turns OFF (the Dome aug-stop cadence: training
+    #: ends on the dense distribution it deploys with). "auto" resolves
+    #: to the shared step schedule; None keeps the constant ratio for
+    #: the whole run (the reference-recommended first setting).
+    random_erase_step_stop: int | None | str = "auto"
+    normalize: NormalizeArgs = Field(default_factory=NormalizeArgs)
+    min_bbox_size_px: float = 4.0
+
+    # Step windows (auto: resolved from the training schedule).
+    photometric_step_start: int | str = "auto"
+    photometric_step_stop: int | None | str = "auto"
+    zoom_out_step_start: int | str = "auto"
+    zoom_out_step_stop: int | None | str = "auto"
+    iou_crop_step_start: int | str = "auto"
+    iou_crop_step_stop: int | None | str = "auto"
+
+    def resolve_auto_fields(self, **kwargs) -> None:
+        num_channels = kwargs.get("num_channels")
+        if self.image_size == "auto":
+            default = kwargs.get("default_image_size", (640, 640))
+            self.image_size = tuple(default)  # type: ignore[assignment]
+        if self.num_channels == "auto":
+            self.num_channels = (
+                num_channels if num_channels is not None else len(self.normalize.mean)
+            )
+
+    def resolve_step_schedule(
+        self, total_steps: int, train_num_batches: int, gradient_accumulation_steps: int
+    ) -> None:
+        from autovision.augment.detection.schedule import (
+            resolve_detection_step_schedule,
+        )
+
+        steps_per_epoch = max(
+            1, train_num_batches // max(1, gradient_accumulation_steps)
+        )
+        schedule = resolve_detection_step_schedule(total_steps, steps_per_epoch)
+        for op, start_attr, stop_attr in (
+            ("photometric", "photometric_step_start", "photometric_step_stop"),
+            ("zoom_out", "zoom_out_step_start", "zoom_out_step_stop"),
+            ("iou_crop", "iou_crop_step_start", "iou_crop_step_stop"),
+            ("mixup", "mixup_step_start", "mixup_step_stop"),
+            ("mosaic", "mosaic_step_start", "mosaic_step_stop"),
+        ):
+            start, stop = schedule.window(op)
+            if getattr(self, start_attr) == "auto":
+                setattr(self, start_attr, start)
+            if getattr(self, stop_attr) == "auto":
+                setattr(self, stop_attr, stop)
+        if self.scale_jitter is not None and self.scale_jitter.step_stop == "auto":
+            self.scale_jitter.step_stop = schedule.stop
+        if self.copyblend_step_start == "auto":
+            # Baseline CopyBlend shares the photometric family's start.
+            self.copyblend_step_start = schedule.start
+        if self.copyblend_step_stop == "auto":
+            # Same photometric-family stop window as the baseline; leaving
+            # "auto" unresolved made the collate treat it as None and kept
+            # copyblend on for the WHOLE run.
+            self.copyblend_step_stop = schedule.stop
+        if self.random_erase_step_stop == "auto":
+            self.random_erase_step_stop = schedule.stop
+
+    def resolve_incompatible(self) -> None:
+        if self.num_channels != 3:
+            self.photometric_distort_prob = None