Merge branch 'main' into sb/add-batch-methods

Author: shntu

.github/workflows/publish.yml

@@ -30,3 +30,35 @@ jobs:
           PYPI_TEST_PASSWORD: ${{ secrets.PYPI_TEST_PASSWORD }}
         run: |
           make publish -e PYPI_USERNAME=$PYPI_USERNAME -e PYPI_PASSWORD=$PYPI_PASSWORD -e PYPI_TEST_PASSWORD=$PYPI_TEST_PASSWORD
+
+  deploy-docs:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: 🛎️ Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.8'
+
+      - name: 📚 Install MkDocs and dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install mkdocs-material mkdocstrings mkdocstrings[python]
+          pip install ".[dev]"
+
+      - name: 🏗️ Build documentation
+        run: |
+          mkdocs build
+
+      - name: 🚀 Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

.github/workflows/test.yml

@@ -8,10 +8,13 @@ on:
 
 jobs:
   build:
-    runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+        os: ["ubuntu-latest", "windows-latest"]
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    env:
+      PYTHONUTF8: 1
 
     steps:
       - name: 🛎️ Checkout

.gitignore

@@ -154,3 +154,4 @@ tests/manual/data
 README.roboflow.txt
 *.zip
 .DS_Store
+.claude

CLAUDE.md

@@ -0,0 +1,115 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+### Running Tests
+```bash
+python -m unittest
+```
+
+### Linting and Code Quality
+```bash
+# Format code with ruff
+make style
+
+# Check code quality (includes ruff and mypy)
+make check_code_quality
+
+# Individual commands
+ruff format roboflow
+ruff check roboflow --fix
+mypy roboflow
+```
+
+### Building Documentation
+```bash
+# Install documentation dependencies
+python -m pip install mkdocs mkdocs-material mkdocstrings mkdocstrings[python]
+
+# Serve documentation locally
+mkdocs serve
+```
+
+### Installing Development Environment
+```bash
+# Create virtual environment
+python3 -m venv env
+source env/bin/activate
+
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Install pre-commit hooks
+pip install pre-commit
+pre-commit install
+```
+
+## Architecture Overview
+
+The Roboflow Python SDK follows a hierarchical object model that mirrors the Roboflow platform structure:
+
+### Core Components
+
+1. **Roboflow** (`roboflow/__init__.py`) - Entry point and authentication
+   - Handles API key management and workspace initialization
+   - Provides `login()` for CLI authentication
+   - Creates workspace connections
+
+2. **Workspace** (`roboflow/core/workspace.py`) - Manages Roboflow workspaces
+   - Lists and accesses projects
+   - Handles dataset uploads and model deployments
+   - Manages workspace-level operations
+
+3. **Project** (`roboflow/core/project.py`) - Represents a computer vision project
+   - Manages project metadata and versions
+   - Handles image/annotation uploads
+   - Supports different project types (object-detection, classification, etc.)
+
+4. **Version** (`roboflow/core/version.py`) - Dataset version management
+   - Downloads datasets in various formats
+   - Deploys models
+   - Provides access to trained models for inference
+
+5. **Model Classes** (`roboflow/models/`) - Type-specific inference models
+   - `ObjectDetectionModel` - Bounding box predictions
+   - `ClassificationModel` - Image classification
+   - `InstanceSegmentationModel` - Pixel-level segmentation
+   - `SemanticSegmentationModel` - Class-based segmentation
+   - `KeypointDetectionModel` - Keypoint predictions
+
+### API Adapters
+
+- **rfapi** (`roboflow/adapters/rfapi.py`) - Low-level API communication
+- **deploymentapi** (`roboflow/adapters/deploymentapi.py`) - Model deployment operations
+
+### CLI Interface
+
+The `roboflow` command line tool (`roboflow/roboflowpy.py`) provides:
+- Authentication: `roboflow login`
+- Dataset operations: `roboflow download`, `roboflow upload`, `roboflow import`
+- Inference: `roboflow infer`
+- Project/workspace management: `roboflow project`, `roboflow workspace`
+
+### Key Design Patterns
+
+1. **Hierarchical Access**: Always access objects through their parent (Workspace → Project → Version → Model)
+2. **API Key Flow**: API key is passed down through the object hierarchy
+3. **Format Flexibility**: Supports multiple dataset formats (YOLO, COCO, Pascal VOC, etc.)
+4. **Batch Operations**: Upload and download operations support concurrent processing
+
+## Project Configuration
+
+- **Python Version**: 3.8+
+- **Main Dependencies**: See `requirements.txt`
+- **Entry Point**: `roboflow=roboflow.roboflowpy:main`
+- **Code Style**: Enforced by ruff with Google docstring convention
+- **Type Checking**: mypy configured for Python 3.8
+
+## Important Notes
+
+- API keys are stored in `~/.config/roboflow/config.json` (Unix) or `~/roboflow/config.json` (Windows)
+- The SDK supports both hosted inference (Roboflow platform) and local inference (via Roboflow Inference)
+- Pre-commit hooks automatically run formatting and linting checks
+- Test files intentionally excluded from linting: `tests/manual/debugme.py`

Dockerfile.dev

@@ -1,9 +1,17 @@
-FROM python:3.8
-RUN apt-get update && apt-get install -y make libgl1-mesa-glx && rm -rf /var/lib/apt/lists/*
+FROM python:3.10
+RUN apt-get update && apt-get install -y make curl libgl1-mesa-glx && rm -rf /var/lib/apt/lists/*
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:${PATH}"
+
 WORKDIR /roboflow-python
 COPY .devcontainer/bashrc_ext /root/bashrc_ext
 RUN echo "source /root/bashrc_ext" >> ~/.bashrc
-COPY ./setup.py ./pyproject.toml ./README.md ./requirements.txt ./
+
+COPY ./requirements.txt ./
+RUN uv pip install --system -r requirements.txt
+
+COPY ./setup.py ./pyproject.toml ./README.md ./
 COPY roboflow/__init__.py ./roboflow/__init__.py
-RUN pip install -e ".[dev]"
+RUN uv pip install --system -e ".[dev]"
+
 COPY . .

roboflow/__init__.py

@@ -15,7 +15,7 @@
 from roboflow.models import CLIPModel, GazeModel  # noqa: F401
 from roboflow.util.general import write_line
 
-__version__ = "1.1.58"
+__version__ = "1.1.65"
 
 
 def check_key(api_key, model, notebook, num_retries=0):

roboflow/adapters/deploymentapi.py

@@ -9,10 +9,13 @@ class DeploymentApiError(Exception):
     pass
 
 
-def add_deployment(api_key, machine_type, duration, delete_on_expiration, deployment_name, inference_version):
+def add_deployment(
+    api_key, creator_email, machine_type, duration, delete_on_expiration, deployment_name, inference_version
+):
     url = f"{DEDICATED_DEPLOYMENT_URL}/add"
     params = {
         "api_key": api_key,
+        "creator_email": creator_email,
         # "security_level": security_level,
         "duration": duration,
         "delete_on_expiration": delete_on_expiration,
@@ -69,6 +72,22 @@ def get_deployment_usage(api_key, deployment_name, from_timestamp, to_timestamp)
     return response.status_code, response.json()
 
 
+def pause_deployment(api_key, deployment_name):
+    url = f"{DEDICATED_DEPLOYMENT_URL}/pause"
+    response = requests.post(url, json={"api_key": api_key, "deployment_name": deployment_name})
+    if response.status_code != 200:
+        return response.status_code, response.text
+    return response.status_code, response.json()
+
+
+def resume_deployment(api_key, deployment_name):
+    url = f"{DEDICATED_DEPLOYMENT_URL}/resume"
+    response = requests.post(url, json={"api_key": api_key, "deployment_name": deployment_name})
+    if response.status_code != 200:
+        return response.status_code, response.text
+    return response.status_code, response.json()
+
+
 def delete_deployment(api_key, deployment_name):
     url = f"{DEDICATED_DEPLOYMENT_URL}/delete"
     response = requests.post(url, json={"api_key": api_key, "deployment_name": deployment_name})

roboflow/core/workspace.py

@@ -301,10 +301,11 @@ def upload_dataset(
         """  # noqa: E501 // docs
         if dataset_format != "NOT_USED":
             print("Warning: parameter 'dataset_format' is deprecated and will be removed in a future release")
-        parsed_dataset = folderparser.parsefolder(dataset_path)
         project, created = self._get_or_create_project(
             project_id=project_name, license=project_license, type=project_type
         )
+        is_classification = project.type == "classification"
+        parsed_dataset = folderparser.parsefolder(dataset_path, is_classification=is_classification)
         if created:
             print(f"Created project {project.id}")
         else:
@@ -361,15 +362,19 @@ def _save_annotation(image_id, imagedesc):
 
             annotationdesc = imagedesc.get("annotationfile")
             if isinstance(annotationdesc, dict):
-                if annotationdesc.get("rawText"):
+                if annotationdesc.get("type") == "classification_folder":
+                    annotation_path = annotationdesc.get("classification_label")
+                elif annotationdesc.get("rawText"):
                     annotation_path = annotationdesc
-                else:
+                elif annotationdesc.get("file"):
                     annotation_path = f"{location}{annotationdesc['file']}"
-                labelmap = annotationdesc.get("labelmap")
+                    labelmap = annotationdesc.get("labelmap")
 
                 if isinstance(labelmap, str):
                     labelmap = load_labelmap(labelmap)
-            else:
+
+            # If annotation_path is still None at this point, then no annotation will be saved.
+            if annotation_path is None:
                 return None, None
 
             annotation, upload_time, _retry_attempts = project.save_annotation(
@@ -619,7 +624,13 @@ def _upload_zip(
         try:
             res.raise_for_status()
         except Exception as e:
-            print(f"An error occured when getting the model deployment URL: {e}")
+            error_message = str(e)
+            status_code = str(res.status_code)
+
+            print("\n\033[91m❌ ERROR\033[0m: Failed to get model deployment URL")
+            print("\033[93mDetails\033[0m:", error_message)
+            print("\033[93mStatus\033[0m:", status_code)
+            print(f"\033[93mResponse\033[0m:\n{res.text}\n")
             return
 
         # Upload the model to the signed URL

roboflow/deployment.py

@@ -61,6 +61,8 @@ def add_deployment_parser(subparsers):
     deployment_usage_deployment_parser = deployment_subparsers.add_parser(
         "usage_deployment", help="get usage of a specific dedicated deployments"
     )
+    deployment_pause_parser = deployment_subparsers.add_parser("pause", help="pause a dedicated deployment")
+    deployment_resume_parser = deployment_subparsers.add_parser("resume", help="resume a dedicated deployment")
     deployment_delete_parser = deployment_subparsers.add_parser("delete", help="delete a dedicated deployment")
     deployment_log_parser = deployment_subparsers.add_parser("log", help="show log info for a dedicated deployment")
 
@@ -77,7 +79,13 @@ def add_deployment_parser(subparsers):
     #     "-s", "--security_level", help="security level (protected)", default="protected"
     # )
     deployment_add_parser.add_argument(
-        "-m", "--machine_type", help="machine type, run `roboflow deployment machine_type` to see available options"
+        "-m",
+        "--machine_type",
+        help="machine type, run `roboflow deployment machine_type` to see available options",
+        required=True,
+    )
+    deployment_add_parser.add_argument(
+        "-e", "--creator_email", help="your email address (must be added to the workspace)", required=True
     )
     deployment_add_parser.add_argument(
         "-t",
@@ -87,7 +95,7 @@ def add_deployment_parser(subparsers):
         default=3,
     )
     deployment_add_parser.add_argument(
-        "-e", "--no_delete_on_expiration", help="keep when expired (default: False)", action="store_true"
+        "-nodel", "--no_delete_on_expiration", help="keep when expired (default: False)", action="store_true"
     )
     deployment_add_parser.add_argument(
         "-v",
@@ -128,6 +136,14 @@ def add_deployment_parser(subparsers):
         "-t", "--to_timestamp", help="end time stamp in ISO8601 format (YYYY-MM-DD HH:MM:SS)", default=None
     )
 
+    deployment_pause_parser.set_defaults(func=pause_deployment)
+    deployment_pause_parser.add_argument("-a", "--api_key", help="api key")
+    deployment_pause_parser.add_argument("deployment_name", help="deployment name")
+
+    deployment_resume_parser.set_defaults(func=resume_deployment)
+    deployment_resume_parser.add_argument("-a", "--api_key", help="api key")
+    deployment_resume_parser.add_argument("deployment_name", help="deployment name")
+
     deployment_delete_parser.set_defaults(func=delete_deployment)
     deployment_delete_parser.add_argument("-a", "--api_key", help="api key")
     deployment_delete_parser.add_argument("deployment_name", help="deployment name")
@@ -163,6 +179,7 @@ def add_deployment(args):
         exit(1)
     status_code, msg = deploymentapi.add_deployment(
         api_key,
+        args.creator_email,
         # args.security_level,
         args.machine_type,
         args.duration,
@@ -241,6 +258,30 @@ def get_deployment_usage(args):
     print(json.dumps(msg, indent=2))
 
 
+def pause_deployment(args):
+    api_key = args.api_key or load_roboflow_api_key(None)
+    if api_key is None:
+        print("Please provide an api key")
+        exit(1)
+    status_code, msg = deploymentapi.pause_deployment(api_key, args.deployment_name)
+    if status_code != 200:
+        print(f"{status_code}: {msg}")
+        exit(status_code)
+    print(json.dumps(msg, indent=2))
+
+
+def resume_deployment(args):
+    api_key = args.api_key or load_roboflow_api_key(None)
+    if api_key is None:
+        print("Please provide an api key")
+        exit(1)
+    status_code, msg = deploymentapi.resume_deployment(api_key, args.deployment_name)
+    if status_code != 200:
+        print(f"{status_code}: {msg}")
+        exit(status_code)
+    print(json.dumps(msg, indent=2))
+
+
 def delete_deployment(args):
     api_key = args.api_key or load_roboflow_api_key(None)
     if api_key is None: