dragoneye-python 0.5.1__tar.gz → 1.0.1__tar.gz

dragoneye_python-1.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dragoneye
+
+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.

dragoneye_python-1.0.1/PKG-INFO

@@ -0,0 +1,505 @@
+Metadata-Version: 2.4
+Name: dragoneye-python
+Version: 1.0.1
+Summary: Official Python SDK for the Dragoneye computer vision API
+Author-email: Dragoneye <support@dragoneye.ai>
+License-Expression: MIT
+Project-URL: Homepage, https://dragoneye.ai
+Project-URL: Documentation, https://docs.dragoneye.ai/integrating/python-sdk
+Project-URL: Repository, https://github.com/dragoneyeAI/dragoneye-python
+Project-URL: Playground, https://playground.dragoneye.ai/
+Project-URL: Issues, https://github.com/dragoneyeAI/dragoneye-python/issues
+Keywords: dragoneye,computer-vision,image-classification,video-classification,machine-learning,ai
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests
+Requires-Dist: pydantic>=2
+Requires-Dist: typing-extensions>=4.0.0
+Requires-Dist: backoff>=2.0.0
+Requires-Dist: aiohttp
+Requires-Dist: polars>=1.0.0
+Dynamic: license-file
+
+# dragoneye-python
+
+[![PyPI version](https://img.shields.io/pypi/v/dragoneye-python.svg)](https://pypi.org/project/dragoneye-python/)
+[![Python Versions](https://img.shields.io/pypi/pyversions/dragoneye-python.svg)](https://pypi.org/project/dragoneye-python/)
+[![License: MIT](https://img.shields.io/pypi/l/dragoneye-python.svg)](https://github.com/dragoneyeAI/dragoneye-python/blob/main/LICENSE)
+
+The official Python SDK for [Dragoneye](https://dragoneye.ai) — build and call custom computer vision models from Python.
+
+Describe what you want to detect in plain English on the [Dragoneye Playground](https://playground.dragoneye.ai/), and the AI Model Builder assembles a vision model with your categories and attributes. This SDK lets you run that model on images and videos and get back structured predictions with bounding boxes, category scores, and attribute scores.
+
+- 📘 **Full documentation:** https://docs.dragoneye.ai/integrating/python-sdk
+- 🎮 **Playground:** https://playground.dragoneye.ai/
+- 🐍 **PyPI:** https://pypi.org/project/dragoneye-python/
+
+---
+
+## Using the Python SDK
+
+If you're integrating with our APIs using Python, the Dragoneye SDK streamlines the process with minimal setup. Here's how you can get started and explore the types and endpoints in detail.
+
+## Installation
+
+Install the package using pip.
+
+```bash
+pip install dragoneye-python
+```
+
+## Quick Start
+
+> **Tip — Prerequisites**: Don't have an API key yet? See [Creating an Access Token](https://docs.dragoneye.ai/account-management/creating-access-token).
+
+To call the classifier, follow these steps:
+
+```python
+import asyncio
+from dragoneye import Dragoneye, Image, Video
+
+async def main():
+    # The api_key can also be set via the DRAGONEYE_API_KEY environment variable.
+    client = Dragoneye(api_key="<YOUR_ACCESS_TOKEN>")
+
+    # Example: predict from an image
+    image = Image.from_path("photo.jpg")
+    image_result = await client.classification.predict_image(
+        media=image,
+        model_name="recognize_anything/your_model_name",  # change to your desired model
+    )
+
+    # Example: predict from a video
+    # NOTE! When loading a file, you can optionally pass a file name or identifier
+    # that you use to identify your own files.
+    video = Video.from_path(
+        path="example.mp4",
+        name="any-file-name",
+    )
+    video_result = await client.classification.predict_video(
+        media=video,
+        model_name="recognize_anything/your_model_name",
+    )
+
+    # Accessing image results
+    for obj in image_result.object_predictions:
+        bbox = obj.normalizedBbox
+        for pred in obj.predictions:
+            print(f"Category: {pred.category.name} ({pred.category.score:.2f})")
+            for attr in pred.attributes:
+                top_option = max(attr.options, key=lambda o: o.score)
+                print(f"  {attr.name}: {top_option.name} ({top_option.score:.2f})")
+
+asyncio.run(main())
+```
+
+> **Note — Model names**: Model names follow the format `recognize_anything/model_name`. Use the name you specified when creating the model.
+
+### Example Video Response
+
+Below is an example of what a `ClassificationPredictVideoResponse` looks like for a Building Detection model. The response maps each sampled frame's timestamp (in microseconds) to the objects detected in that frame:
+
+```python
+ClassificationPredictVideoResponse(
+    prediction_task_uuid="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+    original_file_name="any-file-name",
+    frames_per_second=1,
+    timestamp_us_to_predictions={
+        0: [
+            ClassificationVideoObjectPrediction(
+                frame_id="frame_0",
+                timestamp_microseconds=0,
+                normalizedBbox=(0.12, 0.25, 0.55, 0.78),
+                predictions=[
+                    ClassificationCategoryPrediction(
+                        category=ClassificationCategory(
+                            id=2084323334,
+                            name="House (detached)",
+                            score=0.92,
+                        ),
+                        attributes=[
+                            ClassificationAttributeResponse(
+                                attribute_id=1371766615,
+                                name="Building Exterior Color",
+                                options=[
+                                    ClassificationAttributeOption(option_id=3498033303, name="White / Off-white", score=0.85),
+                                    ClassificationAttributeOption(option_id=496739380, name="Light gray", score=0.10),
+                                    # ... remaining options omitted for brevity
+                                ],
+                            ),
+                            ClassificationAttributeResponse(
+                                attribute_id=448392115,
+                                name="Building Exterior Material",
+                                options=[
+                                    ClassificationAttributeOption(option_id=3887467550, name="Wood (incl. timber siding)", score=0.78),
+                                    ClassificationAttributeOption(option_id=562768697, name="Brick", score=0.12),
+                                    # ...
+                                ],
+                            ),
+                            ClassificationAttributeResponse(
+                                attribute_id=4240554102,
+                                name="Building Size (Stories)",
+                                options=[
+                                    ClassificationAttributeOption(option_id=3067238669, name="2 stories", score=0.91),
+                                    ClassificationAttributeOption(option_id=2398426374, name="1 story", score=0.06),
+                                    # ...
+                                ],
+                            ),
+                        ],
+                    ),
+                ],
+            ),
+            ClassificationVideoObjectPrediction(
+                frame_id="frame_0",
+                timestamp_microseconds=0,
+                normalizedBbox=(0.60, 0.30, 0.88, 0.75),
+                predictions=[
+                    ClassificationCategoryPrediction(
+                        category=ClassificationCategory(
+                            id=3212613421,
+                            name="Garage (detached)",
+                            score=0.87,
+                        ),
+                        attributes=[
+                            # ... attributes omitted for brevity
+                        ],
+                    ),
+                ],
+            ),
+        ],
+        1000000: [
+            # Objects detected at t=1s (1,000,000 microseconds)
+            # ...
+        ],
+    },
+)
+```
+
+Each timestamp key (e.g., `0`, `1000000`) corresponds to a sampled frame. Within each frame, every detected object has its own bounding box, category prediction with a confidence score, and attribute predictions with scored options.
+
+---
+
+## Client
+
+**`Dragoneye`**
+
+The main client used to interact with the API.
+
+```python
+client = Dragoneye(
+    api_key="<YOUR_ACCESS_TOKEN>",
+    max_retries=10,
+    max_backoff_time=120,
+)
+```
+
+**Arguments:**
+
+- `api_key` (Optional[str]): Your API key. If omitted, the SDK reads from the `DRAGONEYE_API_KEY` environment variable.
+- `max_retries` (int): Maximum retry attempts on rate-limit (429) responses. Default: `10`.
+- `max_backoff_time` (int): Maximum backoff time in seconds for exponential backoff. Default: `120`.
+
+---
+
+## Media Classes
+
+`Image` and `Video` are used to wrap media before passing it to a prediction endpoint. Each class restricts the MIME type to its respective media type (`image/*` or `video/*`).
+
+### Constructors
+
+**`from_path`**
+
+```python
+media = Image.from_path(
+    path="photo.jpg",
+    name="my-photo",          # optional identifier
+    mime_type=None,            # auto-detected from extension by default
+    guess_from_extension=True, # set False to require explicit mime_type
+    read_into_memory=False,    # set True to load bytes into memory immediately
+)
+```
+
+**`from_bytes`**
+
+```python
+media = Image.from_bytes(
+    data=raw_bytes,
+    mime_type="image/jpeg",
+    name="my-photo",  # optional
+)
+```
+
+**`from_stream`**
+
+```python
+media = Video.from_stream(
+    stream=open("clip.mp4", "rb"),
+    mime_type="video/mp4",
+    name="my-clip",  # optional
+)
+```
+
+---
+
+## Types and Endpoints
+
+### Types
+
+The response types form a nested hierarchy. Here's how they fit together for image predictions:
+
+```
+ClassificationPredictImageResponse
+└── object_predictions: [ClassificationObjectPrediction]
+    ├── normalizedBbox: (x1, y1, x2, y2)
+    └── predictions: [ClassificationCategoryPrediction]
+        ├── category: ClassificationCategory (id, name, score)
+        └── attributes: [ClassificationAttributeResponse]
+            └── options: [ClassificationAttributeOption] (option_id, name, score)
+```
+
+For video predictions, `ClassificationPredictVideoResponse` maps timestamps to lists of `ClassificationVideoObjectPrediction` (which extends `ClassificationObjectPrediction` with `frame_id` and `timestamp_microseconds`).
+
+---
+
+**`ClassificationCategory`**
+Represents a predicted category.
+
+Attributes:
+
+- `id` (int): Unique identifier for the category.
+- `name` (str): The name of the category.
+- `score` (float): Confidence score for the prediction.
+
+**`ClassificationAttributeOption`**
+Represents a single option within an attribute prediction.
+
+Attributes:
+
+- `option_id` (int): Unique identifier for the option.
+- `name` (str): The name of the option.
+- `score` (float): Confidence score for this option.
+
+**`ClassificationAttributeResponse`**
+Represents a predicted attribute with its possible options.
+
+Attributes:
+
+- `attribute_id` (int): Unique identifier for the attribute.
+- `name` (str): The name of the attribute.
+- `options` (List[ClassificationAttributeOption]): The predicted options for this attribute.
+
+**`ClassificationCategoryPrediction`**
+Represents a category prediction along with its associated attribute predictions.
+
+Attributes:
+
+- `category` (ClassificationCategory): The predicted category.
+- `attributes` (List[ClassificationAttributeResponse]): Attribute predictions for this category.
+
+**`ClassificationObjectPrediction`**
+Represents the prediction of a detected object in an image.
+
+Attributes:
+
+- `normalizedBbox` (NormalizedBbox): A bounding box for the detected object (coordinates are normalized).
+- `predictions` (List[ClassificationCategoryPrediction]): Category and attribute predictions for this object.
+
+**`ClassificationVideoObjectPrediction`**
+Extends `ClassificationObjectPrediction` with video-specific fields.
+
+Attributes:
+
+- `normalizedBbox` (NormalizedBbox): A bounding box for the detected object.
+- `predictions` (List[ClassificationCategoryPrediction]): Category and attribute predictions.
+- `frame_id` (str): Identifier for the frame.
+- `timestamp_microseconds` (int): Timestamp of the frame in microseconds.
+
+**`ClassificationPredictImageResponse`**
+The response object returned after predicting an image.
+
+Attributes:
+
+- `object_predictions` (List[ClassificationObjectPrediction]): Detected objects and their predictions.
+- `prediction_task_uuid` (str): The unique identifier for the prediction task.
+- `original_file_name` (Optional[str]): The file name of the original media, if provided.
+
+**`ClassificationPredictVideoResponse`**
+The response object returned after predicting a video.
+
+Attributes:
+
+- `timestamp_us_to_predictions` (Dict[int, List[ClassificationVideoObjectPrediction]]): A mapping from timestamp (in microseconds) to object predictions for that frame.
+- `frames_per_second` (int): The number of frames per second that were sampled.
+- `prediction_task_uuid` (str): The unique identifier for the prediction task.
+- `original_file_name` (Optional[str]): The file name of the original media, if provided.
+
+**`PredictionTaskStatusResponse`**
+Represents the status of a prediction task.
+
+Attributes:
+
+- `prediction_task_uuid` (str): The unique identifier for the task.
+- `prediction_type` (str): Either `"image"` or `"video"`.
+- `status` (str): The current task status (`predicted`, `failed`, etc.).
+
+**`NormalizedBbox`**
+Type alias for normalized bounding boxes, represented as a tuple of four float values.
+
+---
+
+### Endpoints
+
+#### `client.classification.predict_image`
+
+```python
+await client.classification.predict_image(
+    media: Image,
+    model_name: str,
+    timeout_seconds: Optional[int] = None,
+) -> ClassificationPredictImageResponse
+```
+
+Performs a classification prediction on a single image.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `media` | `Image` | *required* | An `Image` object (from `from_path`, `from_bytes`, or `from_stream`). |
+| `model_name` | `str` | *required* | The name of the model to use for prediction. |
+| `timeout_seconds` | `Optional[int]` | `None` | Maximum wait time in seconds. Raises `PredictionTimeoutException` on timeout. `None` polls indefinitely. |
+
+**Returns:** `ClassificationPredictImageResponse` — detected objects and their predictions.
+
+---
+
+#### `client.classification.predict_video`
+
+```python
+await client.classification.predict_video(
+    media: Video,
+    model_name: str,
+    frames_per_second: int = 1,
+    timeout_seconds: Optional[int] = None,
+) -> ClassificationPredictVideoResponse
+```
+
+Performs a classification prediction on a video.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `media` | `Video` | *required* | A `Video` object (from `from_path`, `from_bytes`, or `from_stream`). |
+| `model_name` | `str` | *required* | The name of the model to use for prediction. |
+| `frames_per_second` | `int` | `1` | How many frames per second to sample from the video. |
+| `timeout_seconds` | `Optional[int]` | `None` | Maximum wait time in seconds. Raises `PredictionTimeoutException` on timeout. `None` polls indefinitely. |
+
+**Returns:** `ClassificationPredictVideoResponse` — frame-level prediction results.
+
+---
+
+#### `client.classification.status`
+
+```python
+await client.classification.status(
+    prediction_task_uuid: str,
+) -> PredictionTaskStatusResponse
+```
+
+Checks the status of a prediction task.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prediction_task_uuid` | `str` | *required* | The UUID of the prediction task. |
+
+**Returns:** `PredictionTaskStatusResponse` — the task's current status.
+
+---
+
+#### `client.classification.get_image_results`
+
+```python
+await client.classification.get_image_results(
+    prediction_task_uuid: str,
+) -> ClassificationPredictImageResponse
+```
+
+Retrieves the results of a completed image prediction task.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prediction_task_uuid` | `str` | *required* | The UUID of the prediction task. |
+
+**Returns:** `ClassificationPredictImageResponse`
+
+---
+
+#### `client.classification.get_video_results`
+
+```python
+await client.classification.get_video_results(
+    prediction_task_uuid: str,
+) -> ClassificationPredictVideoResponse
+```
+
+Retrieves the results of a completed video prediction task.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `prediction_task_uuid` | `str` | *required* | The UUID of the prediction task. |
+
+**Returns:** `ClassificationPredictVideoResponse`
+
+---
+
+## Error Handling
+
+The SDK defines the following exception types:
+
+| Exception | When it's raised |
+|-----------|-----------------|
+| `PredictionTimeoutException` | The prediction did not complete within the specified `timeout_seconds`. |
+| `PredictionTaskError` | The prediction task failed on the server. |
+| `PredictionUploadError` | The media file could not be uploaded. |
+| `PredictionTaskBeginError` | The prediction task could not be started. |
+| `PredictionTaskResultsUnavailableError` | Results were requested for a task that has not completed. |
+
+```python
+from dragoneye import Dragoneye, Image
+from dragoneye.types.exception import (
+    PredictionTimeoutException,
+    PredictionTaskError,
+    PredictionUploadError,
+)
+
+try:
+    result = await client.classification.predict_image(
+        media=image,
+        model_name="recognize_anything/your_model_name",
+        timeout_seconds=60,
+    )
+except PredictionTimeoutException:
+    print("Prediction timed out — try increasing timeout_seconds")
+except PredictionUploadError:
+    print("Failed to upload media — check file path and format")
+except PredictionTaskError:
+    print("Prediction task failed on the server")
+```
+
+---
+
+## Notes
+
+- All public methods are **asynchronous**. Use `asyncio.run` or an async loop to call them.
+- For images, use `predict_image` with an `Image` object. For videos, use `predict_video` with a `Video` object. Passing the wrong media type will raise a `ValueError`.
+- Predictions are executed as tasks: the SDK automatically handles task creation, media upload, polling, and result retrieval.
+- The SDK automatically retries on rate-limit (429) responses using exponential backoff. You can configure this behavior via the `max_retries` and `max_backoff_time` parameters on the `Dragoneye` client.