datamint 2.18.0__tar.gz → 2.18.2__tar.gz

{datamint-2.18.0 → datamint-2.18.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: datamint
-Version: 2.18.0
+Version: 2.18.2
 Summary: A library for interacting with the Datamint API, designed for efficient data management, processing and Deep Learning workflows.
 Requires-Python: >=3.10
 Classifier: Programming Language :: Python :: 3
@@ -12,6 +12,7 @@ Classifier: Programming Language :: Python :: 3.14
 Provides-Extra: detection
 Provides-Extra: dev
 Provides-Extra: docs
+Provides-Extra: examples
 Provides-Extra: nnunet
 Requires-Dist: Deprecated (>=1.2.0)
 Requires-Dist: Flask (<4)
@@ -23,6 +24,7 @@ Requires-Dist: backports-strenum ; python_version < "3.11"
 Requires-Dist: cachetools (>=6.0.0)
 Requires-Dist: certifi (>=2025.0.0)
 Requires-Dist: filelock (>=3.0) ; extra == "nnunet"
+Requires-Dist: h5py (>=3.0) ; extra == "examples"
 Requires-Dist: httpx
 Requires-Dist: humanize (>=4.0.0,<5.0.0)
 Requires-Dist: lazy-loader (>=0.3.0)
@@ -51,6 +53,7 @@ Requires-Dist: rich (>=10.0.0)
 Requires-Dist: segmentation-models-pytorch (>=0.5.0)
 Requires-Dist: setuptools (>=57.0) ; extra == "docs"
 Requires-Dist: sphinx (>=5.0) ; extra == "docs"
+Requires-Dist: sphinx-rtd-dark-mode (>=1.3.0) ; extra == "docs"
 Requires-Dist: sphinx-tabs (>=3.0.0) ; extra == "docs"
 Requires-Dist: sphinx_rtd_theme (>=2.0.0) ; extra == "docs"
 Requires-Dist: torch (>=1.2.0,!=2.3.0)
@@ -73,6 +76,61 @@ Datamint turns medical imaging ML work. Dataset management, annotation, training
 
 **Common use cases:** 🩻 Segmentation · 🏷️ Classification · 📦 Detection
 
+Datamint handles the full journey from **raw files** to a **deployed model**:
+
+```mermaid
+flowchart LR
+    Files(["📁 Your Files"])
+
+    subgraph s1 [1 · Ingest]
+        Resource(["📦 Resource"])
+    end
+
+    subgraph s2 [2 · Organize & Annotate]
+        direction TB
+        Project(["🗂️ Project"])
+        Annotations(["🏷️ Annotations"])
+        Project -.->|annotate| Annotations
+    end
+
+    subgraph s3 [3 · Train]
+        direction LR
+        Dataset(["🧮 Dataset"])
+        Trainer(["🧠 Trainer"])
+        Model(["📈 Model"])
+        Dataset -->|train| Trainer -->|register| Model
+    end
+
+    subgraph s4 [4 · Deploy & Predict]
+        direction LR
+        DeployJob(["🚀 Deploy Job"])
+        Inference(["🔮 Inference"])
+        DeployJob -->|predict| Inference
+    end
+
+    Files -->|upload| Resource
+    Resource -->|organize| Project
+    Project -->|load| Dataset
+    Model -->|deploy| DeployJob
+
+    classDef ingestNode fill:#ffffff,stroke:#1f6feb,stroke-width:2px,color:#0b2b4c
+    classDef organizeNode fill:#ffffff,stroke:#1a7f37,stroke-width:2px,color:#0b3a1c
+    classDef mlNode fill:#ffffff,stroke:#8250df,stroke-width:2px,color:#2c1a4d
+    classDef deployNode fill:#ffffff,stroke:#d1720f,stroke-width:2px,color:#4d2b00
+    classDef fileNode fill:#f6f8fa,stroke:#57606a,stroke-width:2px,color:#24292f
+
+    class Files fileNode
+    class Resource ingestNode
+    class Project,Annotations organizeNode
+    class Dataset,Trainer,Model mlNode
+    class DeployJob,Inference deployNode
+
+    style s1 fill:#dceeff,stroke:#1f6feb,stroke-width:2px,color:#0b2b4c
+    style s2 fill:#dbf5df,stroke:#1a7f37,stroke-width:2px,color:#0b3a1c
+    style s3 fill:#ecdcff,stroke:#8250df,stroke-width:2px,color:#2c1a4d
+    style s4 fill:#ffe8c7,stroke:#d1720f,stroke-width:2px,color:#4d2b00
+```
+
 ## 📋 Table of Contents
 
 - [See it in action](#-see-it-in-action)
@@ -83,7 +141,7 @@ Datamint turns medical imaging ML work. Dataset management, annotation, training
 
 ## 🎬 See it in action
 
-From a project name to a deployed, validated model, patient-wise splitting, training, and deployment included:
+**Create** a project, **split** the data, **train**, and **deploy**, all through the API:
 
 ![Datamint pipeline demo](assets/pipeline-demo.gif)
 
@@ -131,7 +189,7 @@ For instance, create the enviroment once with `python3 -m venv datamint-env` and
 **2. Configure your API key**
 
 ```bash
-datamint-config
+datamint config
 ```
 
 Follow the prompts (ask your administrator if you don't have a key yet). Environment variable and programmatic options are in the [Setup API Key guide](https://sonanceai.github.io/datamint-python-api/getting_started.html#setup-api-key).
@@ -139,7 +197,7 @@ Follow the prompts (ask your administrator if you don't have a key yet). Environ
 **3. Scaffold a project — the fastest way to start**
 
 ```bash
-datamint-init
+datamint init
 ```
 
 This is the recommended on-ramp: it asks for a project name and task type (**segmentation**, **classification**, or **detection**), then generates a ready-to-run, numbered set of scripts (`01_upload_data.py` → `06_deploy.py`) — upload data, train, and deploy by running them in order.
@@ -159,15 +217,21 @@ results = trainer.fit()
 
 ## 📚 Documentation
 
-| Resource | Description |
-|----------|-------------|
-| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | Step-by-step setup and basic usage |
-| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | Complete API documentation |
-| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ML workflow integration |
-| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | Built-in trainers, trainer lifecycle, and custom model integration |
-| [🛠️ Command Line Tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html) | Full reference for `datamint-upload`, `datamint-init`, and `datamint-config` |
-| [🔒 SSL Troubleshooting](https://sonanceai.github.io/datamint-python-api/ssl_troubleshooting.html) | Fixing `SSLCertVerificationError` |
-| [📓 Notebooks](notebooks/) | Numbered, runnable tutorials. Start at `01_getting_started` and work through annotations, datasets, experiment tracking, deployment, and a full end-to-end example |
+**Difficulty levels:**
+
+- ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) no ML knowledge needed 
+- ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow)assumes SDK familiarity, introduces ML/dataset concepts
+- ![Advanced](https://img.shields.io/badge/level-advanced-red) full training pipelines, custom models, 3D data, multi-step workflows.
+
+| Resource | Level | Description |
+|----------|-------|-------------|
+| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Step-by-step setup and basic usage |
+| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Complete API documentation |
+| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | ML workflow integration |
+| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Built-in trainers, trainer lifecycle, and custom model integration |
+| [🛠️ Command Line Tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Full reference for `datamint upload`, `datamint init`, and `datamint config` |
+| [🔒 SSL Troubleshooting](https://sonanceai.github.io/datamint-python-api/ssl_troubleshooting.html) | — | Fixing `SSLCertVerificationError` |
+| [📓 Notebooks](notebooks/) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) ![Advanced](https://img.shields.io/badge/level-advanced-red) | Numbered, runnable tutorials. Start at `01_getting_started` and work through annotations, datasets, experiment tracking, deployment, and a full end-to-end example |
 
 ## 🆘 Support
 

{datamint-2.18.0 → datamint-2.18.2}/README.md

@@ -11,6 +11,61 @@ Datamint turns medical imaging ML work. Dataset management, annotation, training
 
 **Common use cases:** 🩻 Segmentation · 🏷️ Classification · 📦 Detection
 
+Datamint handles the full journey from **raw files** to a **deployed model**:
+
+```mermaid
+flowchart LR
+    Files(["📁 Your Files"])
+
+    subgraph s1 [1 · Ingest]
+        Resource(["📦 Resource"])
+    end
+
+    subgraph s2 [2 · Organize & Annotate]
+        direction TB
+        Project(["🗂️ Project"])
+        Annotations(["🏷️ Annotations"])
+        Project -.->|annotate| Annotations
+    end
+
+    subgraph s3 [3 · Train]
+        direction LR
+        Dataset(["🧮 Dataset"])
+        Trainer(["🧠 Trainer"])
+        Model(["📈 Model"])
+        Dataset -->|train| Trainer -->|register| Model
+    end
+
+    subgraph s4 [4 · Deploy & Predict]
+        direction LR
+        DeployJob(["🚀 Deploy Job"])
+        Inference(["🔮 Inference"])
+        DeployJob -->|predict| Inference
+    end
+
+    Files -->|upload| Resource
+    Resource -->|organize| Project
+    Project -->|load| Dataset
+    Model -->|deploy| DeployJob
+
+    classDef ingestNode fill:#ffffff,stroke:#1f6feb,stroke-width:2px,color:#0b2b4c
+    classDef organizeNode fill:#ffffff,stroke:#1a7f37,stroke-width:2px,color:#0b3a1c
+    classDef mlNode fill:#ffffff,stroke:#8250df,stroke-width:2px,color:#2c1a4d
+    classDef deployNode fill:#ffffff,stroke:#d1720f,stroke-width:2px,color:#4d2b00
+    classDef fileNode fill:#f6f8fa,stroke:#57606a,stroke-width:2px,color:#24292f
+
+    class Files fileNode
+    class Resource ingestNode
+    class Project,Annotations organizeNode
+    class Dataset,Trainer,Model mlNode
+    class DeployJob,Inference deployNode
+
+    style s1 fill:#dceeff,stroke:#1f6feb,stroke-width:2px,color:#0b2b4c
+    style s2 fill:#dbf5df,stroke:#1a7f37,stroke-width:2px,color:#0b3a1c
+    style s3 fill:#ecdcff,stroke:#8250df,stroke-width:2px,color:#2c1a4d
+    style s4 fill:#ffe8c7,stroke:#d1720f,stroke-width:2px,color:#4d2b00
+```
+
 ## 📋 Table of Contents
 
 - [See it in action](#-see-it-in-action)
@@ -21,7 +76,7 @@ Datamint turns medical imaging ML work. Dataset management, annotation, training
 
 ## 🎬 See it in action
 
-From a project name to a deployed, validated model, patient-wise splitting, training, and deployment included:
+**Create** a project, **split** the data, **train**, and **deploy**, all through the API:
 
 ![Datamint pipeline demo](assets/pipeline-demo.gif)
 
@@ -69,7 +124,7 @@ For instance, create the enviroment once with `python3 -m venv datamint-env` and
 **2. Configure your API key**
 
 ```bash
-datamint-config
+datamint config
 ```
 
 Follow the prompts (ask your administrator if you don't have a key yet). Environment variable and programmatic options are in the [Setup API Key guide](https://sonanceai.github.io/datamint-python-api/getting_started.html#setup-api-key).
@@ -77,7 +132,7 @@ Follow the prompts (ask your administrator if you don't have a key yet). Environ
 **3. Scaffold a project — the fastest way to start**
 
 ```bash
-datamint-init
+datamint init
 ```
 
 This is the recommended on-ramp: it asks for a project name and task type (**segmentation**, **classification**, or **detection**), then generates a ready-to-run, numbered set of scripts (`01_upload_data.py` → `06_deploy.py`) — upload data, train, and deploy by running them in order.
@@ -97,15 +152,21 @@ results = trainer.fit()
 
 ## 📚 Documentation
 
-| Resource | Description |
-|----------|-------------|
-| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | Step-by-step setup and basic usage |
-| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | Complete API documentation |
-| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ML workflow integration |
-| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | Built-in trainers, trainer lifecycle, and custom model integration |
-| [🛠️ Command Line Tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html) | Full reference for `datamint-upload`, `datamint-init`, and `datamint-config` |
-| [🔒 SSL Troubleshooting](https://sonanceai.github.io/datamint-python-api/ssl_troubleshooting.html) | Fixing `SSLCertVerificationError` |
-| [📓 Notebooks](notebooks/) | Numbered, runnable tutorials. Start at `01_getting_started` and work through annotations, datasets, experiment tracking, deployment, and a full end-to-end example |
+**Difficulty levels:**
+
+- ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) no ML knowledge needed 
+- ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow)assumes SDK familiarity, introduces ML/dataset concepts
+- ![Advanced](https://img.shields.io/badge/level-advanced-red) full training pipelines, custom models, 3D data, multi-step workflows.
+
+| Resource | Level | Description |
+|----------|-------|-------------|
+| [🚀 Getting Started](https://sonanceai.github.io/datamint-python-api/getting_started.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Step-by-step setup and basic usage |
+| [📖 API Reference](https://sonanceai.github.io/datamint-python-api/client_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Complete API documentation |
+| [🔥 PyTorch Integration](https://sonanceai.github.io/datamint-python-api/pytorch_integration.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | ML workflow integration |
+| [🧠 Trainer Guide](https://sonanceai.github.io/datamint-python-api/trainer_api.html) | ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) | Built-in trainers, trainer lifecycle, and custom model integration |
+| [🛠️ Command Line Tools](https://sonanceai.github.io/datamint-python-api/command_line_tools.html) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) | Full reference for `datamint upload`, `datamint init`, and `datamint config` |
+| [🔒 SSL Troubleshooting](https://sonanceai.github.io/datamint-python-api/ssl_troubleshooting.html) | — | Fixing `SSLCertVerificationError` |
+| [📓 Notebooks](notebooks/) | ![Beginner](https://img.shields.io/badge/level-beginner-brightgreen) ![Intermediate](https://img.shields.io/badge/level-intermediate-yellow) ![Advanced](https://img.shields.io/badge/level-advanced-red) | Numbered, runnable tutorials. Start at `01_getting_started` and work through annotations, datasets, experiment tracking, deployment, and a full end-to-end example |
 
 ## 🆘 Support
 

{datamint-2.18.0 → datamint-2.18.2}/datamint/__init__.py

@@ -10,13 +10,14 @@ if TYPE_CHECKING:
     from .dataset.image_dataset import ImageDataset
     from .dataset.volume_dataset import VolumeDataset
     from .mlflow.flavors.validation import validate_model, ValidationReport, ValidationIssue, ModelValidationError
+    from .default_project import select_project
 
 else:
     import lazy_loader as lazy
 
     __getattr__, __dir__, __all__ = lazy.attach(
         __name__,
-        submodules=['dataset', "dataset.dataset"],
+        submodules=['dataset', "dataset.dataset", "examples"],
         submod_attrs={
             "api.client": ["Api"],
             # New modular dataset classes
@@ -24,6 +25,7 @@ else:
             "dataset.volume_dataset": ["VolumeDataset"],
             "mlflow.flavors.validation": ["validate_model", "ValidationReport",
                                           "ValidationIssue", "ModelValidationError"],
+            "default_project": ["select_project"],
         },
     )
 

{datamint-2.18.0 → datamint-2.18.2}/datamint/__main__.py

@@ -8,7 +8,10 @@ import sys
 _COMMANDS: dict[str, str] = {
     "config": "datamint.client_cmd_tools.datamint_config",
     "upload": "datamint.client_cmd_tools.datamint_upload",
-    "init": "datamint.client_cmd_tools.datamint_init"
+    "init": "datamint.client_cmd_tools.datamint_init",
+    "train": "datamint.client_cmd_tools.datamint_train",
+    "inference": "datamint.client_cmd_tools.datamint_inference",
+    "example": "datamint.client_cmd_tools.datamint_example",
 }
 
 
@@ -21,9 +24,9 @@ def _resolve_version() -> str:
 
 def _build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
-        prog="python -m datamint",
+        prog="datamint",
         description="Datamint command-line interface.",
-        epilog="Available commands: config, upload",
+        epilog=f"Available commands: {', '.join(_COMMANDS)}.",
     )
     parser.add_argument(
         "command",
@@ -41,11 +44,25 @@ def _build_parser() -> argparse.ArgumentParser:
 
 def main() -> None:
     parser = _build_parser()
-    # Parse only the first positional argument; leave the rest for the subcommand.
-    args, remaining = parser.parse_known_args()
+    argv = sys.argv[1:]
+
+    if not argv:
+        # Bare "datamint" with no subcommand: show help instead of an argparse error
+        parser.print_help()
+        sys.exit(0)
+
+    # Parse only the first token (the command name) so that flags meant for the subcommand
+    # (e.g. "datamint upload --help") are forwarded untouched instead of being swallowed by
+    # this top-level parser's own -h/--help/--version handling, which would otherwise trigger
+    # as soon as it sees them anywhere in the argument list.
+    args = parser.parse_args(argv[:1])
+    remaining = argv[1:]
 
     # Replace argv so the subcommand sees only its own arguments.
-    sys.argv = [f"datamint-{args.command}", *remaining]
+    # Note: a space (not a hyphen) so nested argparse usage lines read "datamint <command>"
+    # (argparse's default prog is os.path.basename(sys.argv[0]), which is the string as-is
+    # when it has no path separator).
+    sys.argv = [f"datamint {args.command}", *remaining]
 
     module_path = _COMMANDS[args.command]
     try:

{datamint-2.18.0 → datamint-2.18.2}/datamint/api/client.py

@@ -1,3 +1,5 @@
+from typing import Any
+
 from .base_api import ApiConfig, BaseApi
 from .endpoints import (ProjectsApi, ResourcesApi, AnnotationsApi,
                         ChannelsApi, UsersApi, DatasetsInfoApi,
@@ -30,6 +32,13 @@ class Api:
         'inference': InferenceApi,
     }
 
+    # (server_url, api_key, verify_ssl) signatures already verified successfully in
+    # this process. Lets check_connection=True skip a redundant network round-trip
+    # (e.g. one per DataLoader worker or dataset auto-refresh) once a given
+    # configuration is known to work. A changed value simply misses the cache,
+    # forcing a fresh check.
+    _verified_connections: set[tuple[str, str | None, bool | str]] = set()
+
     def __init__(self,
                  server_url: str | None = None,
                  api_key: str | None = None,
@@ -43,7 +52,9 @@ class Api:
             api_key: Optional API key for authentication
             timeout: Request timeout in seconds
             max_retries: Maximum number of retry attempts
-            check_connection: Whether to check connection on initialization
+            check_connection: Whether to check connection on initialization. Skipped
+                automatically if this exact (server_url, api_key, verify_ssl) combination
+                already passed a check earlier in this process.
             verify_ssl: Whether to verify SSL certificates. Default is True.
                 Set to False only in development environments with self-signed certificates.
                 Can also be a path to a CA bundle file for custom certificate verification.
@@ -87,7 +98,8 @@ class Api:
         self._highclient = None
         self._mlclient = None
         self._endpoints: dict[str, BaseApi] = {}
-        if check_connection:
+        self._connection_signature = (server_url, api_key, verify_ssl)
+        if check_connection and self._connection_signature not in Api._verified_connections:
             self.check_connection()
 
     def check_connection(self):
@@ -96,6 +108,7 @@ class Api:
         except Exception as e:
             raise NetworkError("Error connecting to the Datamint API."
                                " Please check your api_key and/or other configurations.") from e
+        Api._verified_connections.add(self._connection_signature)
 
     def close(self) -> None:
         """Close underlying HTTP clients and any shared aiohttp sessions.
@@ -133,7 +146,11 @@ class Api:
             client = self._client
         if name not in self._endpoints:
             api_class = self._API_MAP[name]
-            endpoint = api_class(self.config, client=client)
+            # Inject ProjectsApi into InferenceApi for project_name → project_id resolution
+            kwargs: dict[str, Any] = {}
+            if name == 'inference':
+                kwargs['projects_api'] = self.projects
+            endpoint = api_class(self.config, client=client, **kwargs)
             # Inject this API instance into the endpoint so it can inject into entities
             endpoint._api_instance = self
             self._endpoints[name] = endpoint

{datamint-2.18.0 → datamint-2.18.2}/datamint/api/endpoints/annotations_api.py

@@ -7,6 +7,7 @@ import asyncio
 import json
 import logging
 import os
+import warnings
 
 import aiohttp
 import httpx
@@ -39,6 +40,7 @@ from ..entity_base_api import ApiConfig, CreatableEntityApi, DeletableEntityApi
 if TYPE_CHECKING:
     from .resources_api import ResourcesApi
     from .models_api import ModelsApi
+    from datamint.entities import Project
 
 
 _LOGGER = logging.getLogger(__name__)
@@ -75,8 +77,8 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                  resource: str | Resource | Sequence[str | Resource] | None = None,
                  annotation_type: AnnotationType | str | None = None,
                  annotator_email: str | None = None,
-                 date_from: date | None = None,
-                 date_to: date | None = None,
+                 from_date: date | None = None,
+                 to_date: date | None = None,
                  dataset_id: str | None = None,
                  worklist_id: str | None = None,
                  status: Literal['new', 'published'] | None = None,
@@ -90,8 +92,8 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                  resource: str | Resource | Sequence[str | Resource] | None = None,
                  annotation_type: AnnotationType | str | None = None,
                  annotator_email: str | None = None,
-                 date_from: date | None = None,
-                 date_to: date | None = None,
+                 from_date: date | None = None,
+                 to_date: date | None = None,
                  dataset_id: str | None = None,
                  worklist_id: str | None = None,
                  status: Literal['new', 'published'] | None = None,
@@ -106,14 +108,17 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
         resource: str | Resource | Sequence[str | Resource] | None = None,
         annotation_type: AnnotationType | str | None = None,
         annotator_email: str | None = None,
-        date_from: date | None = None,
-        date_to: date | None = None,
+        from_date: date | None = None,
+        to_date: date | None = None,
         dataset_id: str | None = None,
         worklist_id: str | None = None,
         status: Literal['new', 'published'] | None = None,
         load_ai_segmentations: bool | None = None,
         limit: int | None = None,
         group_by_resource: bool = False,
+        *,
+        date_from: date | None = None,
+        date_to: date | None = None,
         **kwargs: Any,
     ) -> Sequence[Annotation] | Sequence[Sequence[Annotation]]:
         """
@@ -124,8 +129,8 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                 a list of resources, or None to retrieve annotations from all resources.
             annotation_type: Filter by annotation type (e.g., 'segmentation', 'category').
             annotator_email: Filter by annotator email address.
-            date_from: Filter annotations created on or after this date.
-            date_to: Filter annotations created on or before this date.
+            from_date: Filter annotations created on or after this date.
+            to_date: Filter annotations created on or before this date.
             dataset_id: Filter by dataset unique id.
             worklist_id: Filter by annotation worklist unique id.
             status: Filter by annotation status ('new' or 'published').
@@ -133,6 +138,8 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
             limit: Maximum number of annotations to return.
             group_by_resource: If True, return results grouped by resource.
                 For instance, the first index of the returned list will contain all annotations for the first resource.
+            date_from: (DEPRECATED) Use ``from_date`` instead.
+            date_to: (DEPRECATED) Use ``to_date`` instead.
 
         Returns:
             Sequence[Annotation] | Sequence[Sequence[Annotation]]: List of annotations, or list of lists if grouped by resource.
@@ -167,12 +174,23 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                 resource_annotations_map[ann.resource_id].append(ann)
             return [resource_annotations_map[rid] for rid in resource_ids]
 
+        if date_from is not None:
+            warnings.warn("The 'date_from' parameter is deprecated. "
+                          "Please use 'from_date' instead", DeprecationWarning)
+            if from_date is None:
+                from_date = date_from
+        if date_to is not None:
+            warnings.warn("The 'date_to' parameter is deprecated. "
+                          "Please use 'to_date' instead", DeprecationWarning)
+            if to_date is None:
+                to_date = date_to
+
         # Build search payload according to POST /annotations/search schema
         payload = {
             'annotation_type': annotation_type,
             'annotatorEmail': annotator_email,
-            'from': date_from.isoformat() if date_from is not None else None,
-            'to': date_to.isoformat() if date_to is not None else None,
+            'from': from_date.isoformat() if from_date is not None else None,
+            'to': to_date.isoformat() if to_date is not None else None,
             'dataset_id': dataset_id,
             'annotation_worklist_id': worklist_id,
             'status': status,
@@ -585,9 +603,11 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                                    imported_from: str | None = None,
                                    author_email: str | None = None,
                                    worklist_id: str | None = None,
-                                   ai_model_name: str | None = None,
+                                   model_name: str | None = None,
                                    transpose_segmentation: bool = False,
                                    source: str | None = 'imported',
+                                   *,
+                                   ai_model_name: str | None = None,
                                    ) -> list[str]:
         """
         Upload a 3D volume segmentation to a resource.
@@ -603,8 +623,9 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
             imported_from: The imported from value.
             author_email: The author email.
             worklist_id: The annotation worklist unique id.
-            ai_model_name: The AI model name.
+            model_name: The AI model name.
             transpose_segmentation: Whether to transpose the segmentation before uploading.
+            ai_model_name: (DEPRECATED) Use ``model_name`` instead.
             source: Annotation source tag. Defaults to 'imported' since this is a direct API
                 entry point; :meth:`upload_predictions` overrides it with 'model_pipeline'/'model_deploy'.
 
@@ -634,13 +655,19 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
         """
         import nest_asyncio
 
+        if ai_model_name is not None:
+            warnings.warn("The 'ai_model_name' parameter is deprecated. "
+                          "Please use 'model_name' instead", DeprecationWarning)
+            if model_name is None:
+                model_name = ai_model_name
+
         if isinstance(file_path, Path):
             file_path = str(file_path)
 
         if isinstance(file_path, str) and not os.path.exists(file_path):
             raise FileNotFoundError(f"File {file_path} not found.")
 
-        model_id = self._check_model(ai_model_name)
+        model_id = self._check_model(model_name)
 
         nest_asyncio.apply()
         loop = asyncio.get_event_loop()
@@ -668,8 +695,10 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                              discard_empty_segmentations: bool = True,
                              worklist_id: str | None = None,
                              transpose_segmentation: bool = False,
-                             ai_model_name: str | None = None,
+                             model_name: str | None = None,
                              source: str | None = 'imported',
+                             *,
+                             ai_model_name: str | None = None,
                              ) -> list[str]:
         """
         Upload frame-by-frame segmentations to a resource.
@@ -698,9 +727,10 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
             worklist_id: The annotation worklist unique id.
             model_id: The model unique id.
             transpose_segmentation: Whether to transpose the segmentation or not.
-            ai_model_name: Optional AI model name to associate with the segmentation.
+            model_name: Optional AI model name to associate with the segmentation.
             source: Annotation source tag. Defaults to 'imported' since this is a direct API
                 entry point; :meth:`upload_predictions` overrides it with 'model_pipeline'/'model_deploy'.
+            ai_model_name: (DEPRECATED) Use ``model_name`` instead.
 
         Returns:
             List of segmentation unique ids.
@@ -729,6 +759,12 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
         """
         import nest_asyncio
 
+        if ai_model_name is not None:
+            warnings.warn("The 'ai_model_name' parameter is deprecated. "
+                          "Please use 'model_name' instead", DeprecationWarning)
+            if model_name is None:
+                model_name = ai_model_name
+
         if isinstance(file_path, Path):
             file_path = str(file_path)
 
@@ -740,7 +776,7 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                 "NIfTI files are volume segmentations. Use `upload_volume_segmentation` instead."
             )
 
-        model_id = self._check_model(ai_model_name)
+        model_id = self._check_model(model_name)
 
         standardized_name = self.standardize_segmentation_names(name)
         _LOGGER.debug(f"Standardized segmentation names: {standardized_name}")
@@ -1149,7 +1185,7 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                     resource=resource,
                     file_path=mask,
                     name=ann.class_map,
-                    ai_model_name=model_name,
+                    model_name=model_name,
                     source=source,
                 )
                 annotation_ids.extend(ids)
@@ -1166,7 +1202,7 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
                     file_path=mask,
                     name=ann.identifier,
                     frame_index=ann.frame_index,
-                    ai_model_name=model_name,
+                    model_name=model_name,
                     source=source,
                 )
                 annotation_ids.extend(ids)
@@ -1550,6 +1586,8 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
     def patch(self,
               annotation: str | Annotation,
               identifier: str | None = None,
+              project: 'str | Project | None' = None,
+              *,
               project_id: str | None = None) -> None:
         """
         Partially update an annotation's metadata.
@@ -1557,14 +1595,22 @@ class AnnotationsApi(CreatableEntityApi[Annotation], DeletableEntityApi[Annotati
         Args:
             annotation: The annotation unique id or Annotation instance.
             identifier: Optional new identifier/label for the annotation.
-            project_id: Optional project ID to associate with the annotation.
+            project: Optional project ID or Project instance to associate with the annotation.
+            project_id: (DEPRECATED) Use ``project`` instead.
 
         Raises:
             ServerError: If the update fails.
         """
         annotation_id = self._entid(annotation)
 
-        payload = {'identifier': identifier, 'project_id': project_id}
+        if project_id is not None:
+            warnings.warn("The 'project_id' parameter is deprecated. "
+                          "Please use 'project' instead", DeprecationWarning)
+            if project is None:
+                project = project_id
+
+        payload = {'identifier': identifier,
+                  'project_id': self._entid(project) if project is not None else None}
         # remove None values
         payload = {k: v for k, v in payload.items() if v is not None}
         if len(payload) == 0: