hirundo 0.1.7__tar.gz → 0.1.9__tar.gz

hirundo-0.1.9/PKG-INFO

@@ -0,0 +1,212 @@
+Metadata-Version: 2.1
+Name: hirundo
+Version: 0.1.9
+Summary: This package is used to interface with Hirundo's platform. It provides a simple API to optimize your ML datasets.
+Author-email: Hirundo <dev@hirundo.io>
+License: MIT License
+        
+        Copyright (c) 2024, Hirundo
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/Hirundo-io/hirundo-client
+Keywords: dataset,machine learning,data science,data engineering
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: types-PyYAML>=6.0.12
+Requires-Dist: pydantic>=2.7.1
+Requires-Dist: twine>=5.0.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: types-requests>=2.31.0
+Requires-Dist: typer>=0.12.3
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: stamina>=24.2.0
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: tqdm>=4.66.5
+Provides-Extra: dev
+Requires-Dist: pyyaml>=6.0.1; extra == "dev"
+Requires-Dist: types-PyYAML>=6.0.12; extra == "dev"
+Requires-Dist: pydantic>=2.7.1; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Requires-Dist: python-dotenv>=1.0.1; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Requires-Dist: types-setuptools>=69.5.0; extra == "dev"
+Requires-Dist: typer>=0.12.3; extra == "dev"
+Requires-Dist: httpx>=0.27.0; extra == "dev"
+Requires-Dist: stamina>=24.2.0; extra == "dev"
+Requires-Dist: httpx-sse>=0.4.0; extra == "dev"
+Requires-Dist: pytest>=8.2.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.6; extra == "dev"
+Requires-Dist: uv>=0.5.8; extra == "dev"
+Requires-Dist: pre-commit>=3.7.1; extra == "dev"
+Requires-Dist: virtualenv>=20.6.6; extra == "dev"
+Requires-Dist: ruff>=0.8.2; extra == "dev"
+Requires-Dist: bumpver; extra == "dev"
+Requires-Dist: platformdirs>=4.3.6; extra == "dev"
+Requires-Dist: safety>=3.2.13; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.4.7; extra == "docs"
+Requires-Dist: sphinx-autobuild>=2024.4.16; extra == "docs"
+Requires-Dist: sphinx-click>=5.0.1; extra == "docs"
+Requires-Dist: autodoc_pydantic>=2.2.0; extra == "docs"
+Requires-Dist: furo; extra == "docs"
+Requires-Dist: sphinx-multiversion; extra == "docs"
+Requires-Dist: esbonio; extra == "docs"
+Requires-Dist: starlette>0.40.0; extra == "docs"
+Requires-Dist: markupsafe>=3.0.2; extra == "docs"
+
+# Hirundo
+
+This package exposes access to Hirundo APIs for dataset optimization for Machine Learning.
+
+Dataset optimization is currently available for datasets labelled for classification and object detection.
+
+
+Support dataset storage configs include:
+   - Google Cloud (GCP) Storage
+   - Amazon Web Services (AWS) S3
+   - Git LFS (Large File Storage) repositories (e.g. GitHub or HuggingFace)
+
+Optimizing a classification dataset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently ``hirundo`` requires a CSV file with the following columns (all columns are required):
+   - ``image_path``: The location of the image within the dataset ``root``
+   - ``label``: The label of the image, i.e. which the class that was annotated for this image
+
+And outputs a CSV with the same columns and:
+   - ``suspect_level``: mislabel suspect level
+   - ``suggested_label``: suggested label
+   - ``suggested_label_conf``: suggested label confidence
+
+Optimizing an object detection (OD) dataset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently ``hirundo`` requires a CSV file with the following columns (all columns are required):
+   - ``image_path``: The location of the image within the dataset ``root``
+   - ``bbox_id``: The index of the bounding box within the dataset. Used to indicate label suspects
+   - ``label``: The label of the image, i.e. which the class that was annotated for this image
+   - ``x1``, ``y1``, ``x2``, ``y2``: The bounding box coordinates of the object within the image
+
+And outputs a CSV with the same columns and:
+   - ``suspect_level``: object mislabel suspect level
+   - ``suggested_label``: suggested object label
+   - ``suggested_label_conf``: suggested object label confidence
+
+Note: This Python package must be used alongside a Hirundo server, either the SaaS platform, a custom VPC deployment or an on-premises installation.
+
+
+## Installation
+
+You can install the codebase with a simple `pip install hirundo` to install the latest version of this package. If you prefer to install from the Git repository and/or need a specific version or branch, you can simply clone the repository, check out the relevant commit and then run `pip install .` to install that version. A full list of dependencies can be found in `requirements.txt`, but these will be installed automatically by either of these commands.
+
+## Usage
+
+Classification example:
+```python
+from hirundo import (
+    HirundoCSV,
+    LabelingType,
+    OptimizationDataset,
+    StorageGCP,
+    StorageConfig,
+    StorageTypes,
+)
+
+gcp_bucket = StorageGCP(
+    bucket_name="cifar100bucket",
+    project="Hirundo-global",
+    credentials_json=json.loads(os.environ["GCP_CREDENTIALS"]),
+)
+test_dataset = OptimizationDataset(
+    name="TEST-GCP cifar 100 classification dataset",
+    labeling_type=LabelingType.SINGLE_LABEL_CLASSIFICATION,
+    storage_config=StorageConfig(
+        name="cifar100bucket",
+        type=StorageTypes.GCP,
+        gcp=gcp_bucket,
+    ),
+    data_root_url=gcp_bucket.get_url(path="/pytorch-cifar/data"),
+    labeling_info=HirundoCSV(
+        csv_url=gcp_bucket.get_url(path="/pytorch-cifar/data/cifar100.csv"),
+    ),
+    classes=cifar100_classes,
+)
+
+test_dataset.run_optimization()
+results = test_dataset.check_run()
+print(results)
+```
+
+
+Object detection example:
+
+```python
+from hirundo import (
+    GitRepo,
+    HirundoCSV,
+    LabelingType,
+    OptimizationDataset,
+    StorageGit,
+    StorageConfig,
+    StorageTypes,
+)
+
+git_storage = StorageGit(
+    repo=GitRepo(
+        name="BDD-100k-validation-dataset",
+        repository_url="https://git@hf.co/datasets/hirundo-io/bdd100k-validation-only.git",
+    ),
+    branch="main",
+)
+test_dataset = OptimizationDataset(
+    name="TEST-HuggingFace-BDD-100k-validation-OD-validation-dataset",
+    labeling_type=LabelingType.OBJECT_DETECTION,
+    storage_config=StorageConfig(
+        name="BDD-100k-validation-dataset",
+        type=StorageTypes.GIT,
+        git=git_storage,
+    ),
+    data_root_url=git_storage.get_url(path="/BDD100K Val from Hirundo.zip/bdd100k"),
+    labeling_info=HirundoCSV(
+        csv_url=git_storage.get_url(
+            path="/BDD100K Val from Hirundo.zip/bdd100k/bdd100k.csv"
+        ),
+    ),
+    classes=[
+        "traffic light",
+        "traffic sign",
+        "car",
+        "pedestrian",
+        "bus",
+        "truck",
+        "rider",
+        "bicycle",
+        "motorcycle",
+        "train",
+        "other vehicle",
+        "other person",
+        "trailer",
+    ],
+)
+
+test_dataset.run_optimization()
+results = test_dataset.check_run()
+print(results)
+```
+
+Note: Currently we only support the main CPython release 3.9, 3.10 and 3.11. PyPy support may be introduced in the future.
+
+## Further documentation
+
+To learn more about how to use this library, please visit the [http://docs.hirundo.io/](documentation) or see the Google Colab examples.

hirundo-0.1.9/README.md

@@ -0,0 +1,145 @@
+# Hirundo
+
+This package exposes access to Hirundo APIs for dataset optimization for Machine Learning.
+
+Dataset optimization is currently available for datasets labelled for classification and object detection.
+
+
+Support dataset storage configs include:
+   - Google Cloud (GCP) Storage
+   - Amazon Web Services (AWS) S3
+   - Git LFS (Large File Storage) repositories (e.g. GitHub or HuggingFace)
+
+Optimizing a classification dataset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently ``hirundo`` requires a CSV file with the following columns (all columns are required):
+   - ``image_path``: The location of the image within the dataset ``root``
+   - ``label``: The label of the image, i.e. which the class that was annotated for this image
+
+And outputs a CSV with the same columns and:
+   - ``suspect_level``: mislabel suspect level
+   - ``suggested_label``: suggested label
+   - ``suggested_label_conf``: suggested label confidence
+
+Optimizing an object detection (OD) dataset
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Currently ``hirundo`` requires a CSV file with the following columns (all columns are required):
+   - ``image_path``: The location of the image within the dataset ``root``
+   - ``bbox_id``: The index of the bounding box within the dataset. Used to indicate label suspects
+   - ``label``: The label of the image, i.e. which the class that was annotated for this image
+   - ``x1``, ``y1``, ``x2``, ``y2``: The bounding box coordinates of the object within the image
+
+And outputs a CSV with the same columns and:
+   - ``suspect_level``: object mislabel suspect level
+   - ``suggested_label``: suggested object label
+   - ``suggested_label_conf``: suggested object label confidence
+
+Note: This Python package must be used alongside a Hirundo server, either the SaaS platform, a custom VPC deployment or an on-premises installation.
+
+
+## Installation
+
+You can install the codebase with a simple `pip install hirundo` to install the latest version of this package. If you prefer to install from the Git repository and/or need a specific version or branch, you can simply clone the repository, check out the relevant commit and then run `pip install .` to install that version. A full list of dependencies can be found in `requirements.txt`, but these will be installed automatically by either of these commands.
+
+## Usage
+
+Classification example:
+```python
+from hirundo import (
+    HirundoCSV,
+    LabelingType,
+    OptimizationDataset,
+    StorageGCP,
+    StorageConfig,
+    StorageTypes,
+)
+
+gcp_bucket = StorageGCP(
+    bucket_name="cifar100bucket",
+    project="Hirundo-global",
+    credentials_json=json.loads(os.environ["GCP_CREDENTIALS"]),
+)
+test_dataset = OptimizationDataset(
+    name="TEST-GCP cifar 100 classification dataset",
+    labeling_type=LabelingType.SINGLE_LABEL_CLASSIFICATION,
+    storage_config=StorageConfig(
+        name="cifar100bucket",
+        type=StorageTypes.GCP,
+        gcp=gcp_bucket,
+    ),
+    data_root_url=gcp_bucket.get_url(path="/pytorch-cifar/data"),
+    labeling_info=HirundoCSV(
+        csv_url=gcp_bucket.get_url(path="/pytorch-cifar/data/cifar100.csv"),
+    ),
+    classes=cifar100_classes,
+)
+
+test_dataset.run_optimization()
+results = test_dataset.check_run()
+print(results)
+```
+
+
+Object detection example:
+
+```python
+from hirundo import (
+    GitRepo,
+    HirundoCSV,
+    LabelingType,
+    OptimizationDataset,
+    StorageGit,
+    StorageConfig,
+    StorageTypes,
+)
+
+git_storage = StorageGit(
+    repo=GitRepo(
+        name="BDD-100k-validation-dataset",
+        repository_url="https://git@hf.co/datasets/hirundo-io/bdd100k-validation-only.git",
+    ),
+    branch="main",
+)
+test_dataset = OptimizationDataset(
+    name="TEST-HuggingFace-BDD-100k-validation-OD-validation-dataset",
+    labeling_type=LabelingType.OBJECT_DETECTION,
+    storage_config=StorageConfig(
+        name="BDD-100k-validation-dataset",
+        type=StorageTypes.GIT,
+        git=git_storage,
+    ),
+    data_root_url=git_storage.get_url(path="/BDD100K Val from Hirundo.zip/bdd100k"),
+    labeling_info=HirundoCSV(
+        csv_url=git_storage.get_url(
+            path="/BDD100K Val from Hirundo.zip/bdd100k/bdd100k.csv"
+        ),
+    ),
+    classes=[
+        "traffic light",
+        "traffic sign",
+        "car",
+        "pedestrian",
+        "bus",
+        "truck",
+        "rider",
+        "bicycle",
+        "motorcycle",
+        "train",
+        "other vehicle",
+        "other person",
+        "trailer",
+    ],
+)
+
+test_dataset.run_optimization()
+results = test_dataset.check_run()
+print(results)
+```
+
+Note: Currently we only support the main CPython release 3.9, 3.10 and 3.11. PyPy support may be introduced in the future.
+
+## Further documentation
+
+To learn more about how to use this library, please visit the [http://docs.hirundo.io/](documentation) or see the Google Colab examples.

{hirundo-0.1.7 → hirundo-0.1.9}/hirundo/__init__.py

@@ -1,35 +1,43 @@
 from .dataset_optimization import (
+    COCO,
+    YOLO,
+    HirundoCSV,
     HirundoError,
     OptimizationDataset,
+    RunArgs,
+    VisionRunArgs,
 )
 from .enum import (
     DatasetMetadataType,
-    LabellingType,
+    LabelingType,
 )
 from .git import GitRepo
 from .storage import (
+    StorageConfig,
     StorageGCP,
-    # StorageAzure,  TODO: Azure storage integration is coming soon
+    # StorageAzure,  TODO: Azure storage is coming soon
     StorageGit,
-    StorageIntegration,
-    StorageLink,
     StorageS3,
     StorageTypes,
 )
 
 __all__ = [
+    "COCO",
+    "YOLO",
+    "HirundoCSV",
     "HirundoError",
     "OptimizationDataset",
-    "LabellingType",
+    "RunArgs",
+    "VisionRunArgs",
+    "LabelingType",
     "DatasetMetadataType",
     "GitRepo",
-    "StorageLink",
     "StorageTypes",
     "StorageS3",
     "StorageGCP",
-    # "StorageAzure",  TODO: Azure storage integration is coming soon
+    # "StorageAzure",  TODO: Azure storage is coming soon
     "StorageGit",
-    "StorageIntegration",
+    "StorageConfig",
 ]
 
-__version__ = "0.1.7"
+__version__ = "0.1.9"

hirundo-0.1.9/hirundo/_constraints.py

@@ -0,0 +1,53 @@
+from typing import Annotated
+
+from pydantic import StringConstraints, UrlConstraints
+from pydantic_core import Url
+
+S3BucketUrl = Annotated[
+    str,
+    StringConstraints(
+        min_length=8,
+        max_length=1023,
+        pattern=r"s3?://[a-z0-9.-]{3,64}[/]?",  # Only allow real S3 bucket URLs
+    ),
+]
+
+StorageConfigName = Annotated[
+    str,
+    StringConstraints(
+        min_length=1,
+        max_length=255,
+        pattern=r"^[a-zA-Z0-9-_]+$",
+    ),
+]
+
+S3_MIN_LENGTH = 8
+S3_MAX_LENGTH = 1023
+S3_PATTERN = r"s3://[a-zA-Z0-9.-]{3,64}/[a-zA-Z0-9.-/]+"
+GCP_MIN_LENGTH = 8
+GCP_MAX_LENGTH = 1023
+GCP_PATTERN = r"gs://[a-zA-Z0-9.-]{3,64}/[a-zA-Z0-9.-/]+"
+
+RepoUrl = Annotated[
+    Url,
+    UrlConstraints(
+        allowed_schemes=[
+            "ssh",
+            "https",
+            "http",
+        ]
+    ),
+]
+HirundoUrl = Annotated[
+    Url,
+    UrlConstraints(
+        allowed_schemes=[
+            "file",
+            "https",
+            "http",
+            "s3",
+            "gs",
+            "ssh",
+        ]
+    ),
+]

hirundo-0.1.9/hirundo/_env.py

@@ -0,0 +1,26 @@
+import enum
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+class EnvLocation(enum.Enum):
+    DOTENV = Path.cwd() / ".env"
+    HOME = Path.home() / ".hirundo.conf"
+
+
+if os.path.exists(EnvLocation.DOTENV.value):
+    load_dotenv(EnvLocation.DOTENV.value)
+elif os.path.exists(EnvLocation.HOME.value):
+    load_dotenv(EnvLocation.HOME.value)
+
+API_HOST = os.getenv("API_HOST", "https://api.hirundo.io")
+API_KEY = os.getenv("API_KEY")
+
+
+def check_api_key():
+    if not API_KEY:
+        raise ValueError(
+            "API_KEY is not set. Please run `hirundo setup` to set the API key"
+        )

hirundo-0.1.9/hirundo/_http.py

@@ -0,0 +1,19 @@
+from requests import Response
+
+import hirundo.logger
+
+logger = hirundo.logger.get_logger(__name__)
+
+MINIMUM_CLIENT_SERVER_ERROR_CODE = 400
+
+
+def raise_for_status_with_reason(response: Response):
+    try:
+        if response.status_code >= MINIMUM_CLIENT_SERVER_ERROR_CODE:
+            response.reason = response.json().get("reason", None)
+            if response.reason is None:
+                response.reason = response.json().get("detail", None)
+    except Exception as e:
+        logger.debug("Could not parse response as JSON: %s", e)
+
+    response.raise_for_status()

{hirundo-0.1.7 → hirundo-0.1.9}/hirundo/_iter_sse_retrying.py

@@ -1,19 +1,27 @@
 import asyncio
 import time
+import typing
+import uuid
 from collections.abc import AsyncGenerator, Generator
-from typing import Union
 
 import httpx
-from httpx_sse import ServerSentEvent, aconnect_sse, connect_sse
+import requests
+import urllib3
+from httpx_sse import ServerSentEvent, SSEError, aconnect_sse, connect_sse
 from stamina import retry
 
+from hirundo._timeouts import READ_TIMEOUT
+from hirundo.logger import get_logger
+
+logger = get_logger(__name__)
+
 
 # Credit: https://github.com/florimondmanca/httpx-sse/blob/master/README.md#handling-reconnections
 def iter_sse_retrying(
     client: httpx.Client,
     method: str,
     url: str,
-    headers: Union[dict[str, str], None] = None,
+    headers: typing.Optional[dict[str, str]] = None,
 ) -> Generator[ServerSentEvent, None, None]:
     if headers is None:
         headers = {}
@@ -28,7 +36,13 @@ def iter_sse_retrying(
     #  This may happen when the server is overloaded and closes the connection or
     #  when Kubernetes restarts / replaces a pod.
     #  Likewise, this will likely be temporary, hence the retries.
-    @retry(on=(httpx.ReadError, httpx.RemoteProtocolError))
+    @retry(
+        on=(
+            httpx.ReadError,
+            httpx.RemoteProtocolError,
+            urllib3.exceptions.ReadTimeoutError,
+        )
+    )
     def _iter_sse():
         nonlocal last_event_id, reconnection_delay
 
@@ -44,13 +58,27 @@ def iter_sse_retrying(
             connect_headers["Last-Event-ID"] = last_event_id
 
         with connect_sse(client, method, url, headers=connect_headers) as event_source:
-            for sse in event_source.iter_sse():
-                last_event_id = sse.id
-
-                if sse.retry is not None:
-                    reconnection_delay = sse.retry / 1000
-
-                yield sse
+            try:
+                for sse in event_source.iter_sse():
+                    last_event_id = sse.id
+
+                    if sse.retry is not None:
+                        reconnection_delay = sse.retry / 1000
+
+                    yield sse
+            except SSEError:
+                logger.error("SSE error occurred. Trying regular request")
+                response = requests.get(
+                    url,
+                    headers=connect_headers,
+                    timeout=READ_TIMEOUT,
+                )
+                yield ServerSentEvent(
+                    event="",
+                    data=response.text,
+                    id=uuid.uuid4().hex,
+                    retry=None,
+                )
 
     return _iter_sse()
 
@@ -72,7 +100,13 @@ async def aiter_sse_retrying(
     #  This may happen when the server is overloaded and closes the connection or
     #  when Kubernetes restarts / replaces a pod.
     #  Likewise, this will likely be temporary, hence the retries.
-    @retry(on=(httpx.ReadError, httpx.RemoteProtocolError))
+    @retry(
+        on=(
+            httpx.ReadError,
+            httpx.RemoteProtocolError,
+            urllib3.exceptions.ReadTimeoutError,
+        )
+    )
     async def _iter_sse() -> AsyncGenerator[ServerSentEvent, None]:
         nonlocal last_event_id, reconnection_delay
 
@@ -86,12 +120,22 @@ async def aiter_sse_retrying(
         async with aconnect_sse(
             client, method, url, headers=connect_headers
         ) as event_source:
-            async for sse in event_source.aiter_sse():
-                last_event_id = sse.id
-
-                if sse.retry is not None:
-                    reconnection_delay = sse.retry / 1000
-
-                yield sse
+            try:
+                async for sse in event_source.aiter_sse():
+                    last_event_id = sse.id
+
+                    if sse.retry is not None:
+                        reconnection_delay = sse.retry / 1000
+
+                    yield sse
+            except SSEError:
+                logger.error("SSE error occurred. Trying regular request")
+                response = await client.get(url, headers=connect_headers)
+                yield ServerSentEvent(
+                    event="",
+                    data=response.text,
+                    id=uuid.uuid4().hex,
+                    retry=None,
+                )
 
     return _iter_sse()