destiny_sdk 0.3.0a0__tar.gz → 0.4.1__tar.gz

{destiny_sdk-0.3.0a0 → destiny_sdk-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: destiny_sdk
-Version: 0.3.0a0
+Version: 0.4.1
 Summary: A software development kit (sdk) to support interaction with the DESTINY repository
 Author-email: Adam Hamilton <adam@futureevidence.org>, Andrew Harvey <andrew@futureevidence.org>, Daniel Breves <daniel@futureevidence.org>, Jack Walmisley <jack@futureevidence.org>
 License-Expression: Apache-2.0

{destiny_sdk-0.3.0a0 → destiny_sdk-0.4.1}/pyproject.toml

@@ -33,7 +33,7 @@ license = "Apache-2.0"
 name = "destiny_sdk"
 readme = "README.md"
 requires-python = "~=3.12"
-version = "0.3.0-alpha"
+version = "0.4.1"
 
 [tool.pytest.ini_options]
 addopts = ["--color=yes", "--import-mode=importlib", "--verbose"]

{destiny_sdk-0.3.0a0 → destiny_sdk-0.4.1}/src/destiny_sdk/client.py

@@ -8,6 +8,9 @@ from pydantic import UUID4, HttpUrl
 
 from destiny_sdk.robots import (
     EnhancementRequestRead,
+    RobotEnhancementBatch,
+    RobotEnhancementBatchRead,
+    RobotEnhancementBatchResult,
     RobotResult,
 )
 
@@ -89,3 +92,50 @@ class Client:
         )
         response.raise_for_status()
         return EnhancementRequestRead.model_validate(response.json())
+
+    def send_robot_enhancement_batch_result(
+        self, robot_enhancement_batch_result: RobotEnhancementBatchResult
+    ) -> RobotEnhancementBatchRead:
+        """
+        Send a RobotEnhancementBatchResult to destiny repository.
+
+        Signs the request with the client's secret key.
+
+        :param robot_enhancement_batch_result: The RobotEnhancementBatchResult to send
+        :type robot_enhancement_batch_result: RobotEnhancementBatchResult
+        :return: The RobotEnhancementBatchRead object from the response.
+        :rtype: RobotEnhancementBatchRead
+        """
+        response = self.session.post(
+            f"/robot-enhancement-batches/{robot_enhancement_batch_result.request_id}/results/",
+            json=robot_enhancement_batch_result.model_dump(mode="json"),
+        )
+        response.raise_for_status()
+        return RobotEnhancementBatchRead.model_validate(response.json())
+
+    def poll_robot_enhancement_batch(
+        self, robot_id: UUID4, limit: int = 10
+    ) -> RobotEnhancementBatch | None:
+        """
+        Poll for a robot enhancement batch.
+
+        Signs the request with the client's secret key.
+
+        :param robot_id: The ID of the robot to poll for
+        :type robot_id: UUID4
+        :param limit: The maximum number of pending enhancements to return
+        :type limit: int
+        :return: The RobotEnhancementBatch object from the response, or None if no
+            batches available
+        :rtype: RobotEnhancementBatch | None
+        """
+        response = self.session.post(
+            "/robot-enhancement-batches/",
+            params={"robot_id": str(robot_id), "limit": limit},
+        )
+        # HTTP 204 No Content indicates no batches available
+        if response.status_code == httpx.codes.NO_CONTENT:
+            return None
+
+        response.raise_for_status()
+        return RobotEnhancementBatch.model_validate(response.json())

{destiny_sdk-0.3.0a0 → destiny_sdk-0.4.1}/src/destiny_sdk/imports.py

@@ -19,13 +19,11 @@ class ImportRecordStatus(StrEnum):
     - `created`: Created, but no processing has started.
     - `started`: Processing has started on the batch.
     - `completed`: Processing has been completed.
-    - `cancelled`: Processing was cancelled by calling the API.
     """
 
     CREATED = auto()
     STARTED = auto()
     COMPLETED = auto()
-    CANCELLED = auto()
 
 
 class ImportBatchStatus(StrEnum):
@@ -35,21 +33,15 @@ class ImportBatchStatus(StrEnum):
     - `created`: Created, but no processing has started.
     - `started`: Processing has started on the batch.
     - `failed`: Processing has failed.
-    - `retrying`: Processing has failed, but is being retried.
-    - `indexing`: The imports have been saved and are being indexed.
-    - `indexing_failed`: The imports have been saved but were not indexed.
+    - `partially_failed`: Some references succeeded while others failed.
     - `completed`: Processing has been completed.
-    - `cancelled`: Processing was cancelled by calling the API.
     """
 
     CREATED = auto()
     STARTED = auto()
-    RETRYING = auto()
     FAILED = auto()
-    INDEXING = auto()
-    INDEXING_FAILED = auto()
+    PARTIALLY_FAILED = auto()
     COMPLETED = auto()
-    CANCELLED = auto()
 
 
 class CollisionStrategy(StrEnum):
@@ -96,15 +88,15 @@ class ImportResultStatus(StrEnum):
       more information.
     - `failed`: The reference failed to be created. See the result's `failure_details`
       field for more information.
-    - `cancelled`: Processing was cancelled by calling the API.
+    - `retrying`: Processing has failed, but is being retried.
     """
 
     CREATED = auto()
     STARTED = auto()
     COMPLETED = auto()
-    CANCELLED = auto()
     PARTIALLY_FAILED = auto()
     FAILED = auto()
+    RETRYING = auto()
 
 
 class _ImportRecordBase(BaseModel):
@@ -186,9 +178,8 @@ with each line formatted according to
     )
     callback_url: HttpUrl | None = Field(
         default=None,
-        description="""
-The URL to which the processor should send a callback when the batch has been processed.
-        """,
+        deprecated=True,
+        description="This field is currently a no-op.",
     )
 
 

{destiny_sdk-0.3.0a0 → destiny_sdk-0.4.1}/src/destiny_sdk/robots.py

@@ -52,6 +52,23 @@ None, the repository will assume that the result file is ready for processing.
     )
 
 
+class RobotEnhancementBatchResult(BaseModel):
+    """Used to indicate that the robot has finished processing a batch."""
+
+    request_id: UUID4
+    error: RobotError | None = Field(
+        default=None,
+        description="""
+Error the robot encountered while creating enhancements. If this field is populated,
+we assume the entire robot enhancement batch failed,
+rather than an individual reference.
+If there was an error with processing an individual reference, it should be passed in
+the result file and this field should be left as None. Vice-versa, if this field is
+None, the repository will assume that the result file is ready for processing.
+""",
+    )
+
+
 class RobotResultValidationEntry(_JsonlFileInputMixIn, BaseModel):
     """A single entry in the validation result file for a batch enhancement request."""
 
@@ -110,6 +127,37 @@ If the URL expires, a new one can be generated using
     )
 
 
+class RobotEnhancementBatch(BaseModel):
+    """A robot enhancement batch from the repo to a robot."""
+
+    id: UUID4
+    reference_storage_url: HttpUrl = Field(
+        description="""
+The URL at which the set of references are stored. The file is a jsonl
+with each line formatted according to
+:class:`Reference <libs.sdk.src.destiny_sdk.references.Reference>`, one
+reference per line.
+Each reference may have identifiers or enhancements attached, as
+required by the robot.
+If the URL expires, a new one can be generated using
+``GET /robot-enhancement-batches/{batch_id}/``.
+"""
+    )
+    result_storage_url: HttpUrl = Field(
+        description="""
+The URL at which the set of enhancements are to be stored. The file is to be a jsonl
+with each line formatted according to
+:class:`EnhancementResultEntry <libs.sdk.src.destiny_sdk.robots.EnhancementResultEntry>`.
+If the URL expires, a new one can be generated using
+``GET /robot-enhancement-batches/{batch_id}/``.
+"""  # noqa: E501
+    )
+    extra_fields: dict | None = Field(
+        default=None,
+        description="Extra fields to pass to the robot. TBC.",
+    )
+
+
 class EnhancementRequestStatus(StrEnum):
     """
     The status of an enhancement request.
@@ -117,6 +165,7 @@ class EnhancementRequestStatus(StrEnum):
     **Allowed values**:
     - `received`: Enhancement request has been received by the repo.
     - `accepted`: Enhancement request has been accepted by the robot.
+    - `processing`: Enhancement request is being processed by the robot.
     - `rejected`: Enhancement request has been rejected by the robot.
     - `partial_failed`: Some enhancements failed to create.
     - `failed`: All enhancements failed to create.
@@ -128,6 +177,7 @@ class EnhancementRequestStatus(StrEnum):
 
     RECEIVED = auto()
     ACCEPTED = auto()
+    PROCESSING = auto()
     REJECTED = auto()
     PARTIAL_FAILED = auto()
     FAILED = auto()
@@ -210,6 +260,70 @@ If the URL expires, a new one can be generated using
     )
 
 
+class _RobotEnhancementBatchBase(BaseModel):
+    """
+    Base robot enhancement batch class.
+
+    A robot enhancement batch is a batch of pending enhancements the robot has picked up
+    for processing.
+    """
+
+    robot_id: UUID4 = Field(
+        description="The robot to be used to create the enhancements."
+    )
+    source: str | None = Field(
+        default=None,
+        description="The source of the batch enhancement request.",
+    )
+
+
+class RobotEnhancementBatchRead(_RobotEnhancementBatchBase):
+    """Core robot enhancement batch class."""
+
+    id: UUID4
+    reference_data_url: HttpUrl | None = Field(
+        default=None,
+        description="""
+The URL at which the set of references are stored. The file is a jsonl with each line
+formatted according to
+:class:`Reference <libs.sdk.src.destiny_sdk.references.Reference>`.
+, one reference per line.
+Each reference may have identifiers or enhancements attached, as
+required by the robot.
+If the URL expires, a new one can be generated using
+``GET /enhancement-requests/{request_id}/``.
+        """,
+    )
+    result_storage_url: HttpUrl | None = Field(
+        default=None,
+        description="""
+The URL at which the set of enhancements are stored. The file is to be a jsonl
+with each line formatted according to
+:class:`EnhancementResultEntry <libs.sdk.src.destiny_sdk.robots.EnhancementResultEntry>`.
+This field is only relevant to robots.
+If the URL expires, a new one can be generated using
+``GET /robot-enhancement-batches/{batch_id}/``.
+        """,  # noqa: E501
+    )
+    validation_result_url: HttpUrl | None = Field(
+        default=None,
+        description="""
+The URL at which the result of the enhancement request is stored.
+This file is a txt file, one line per reference, with either an error
+or a success message.
+If the URL expires, a new one can be generated using
+``GET /robot-enhancement-batches/{batch_id}/``.
+        """,
+    )
+    error: str | None = Field(
+        default=None,
+        description="Error encountered during the enhancement process. This "
+        "is only used if the entire enhancement batch failed, rather than an "
+        "individual reference. If there was an error with processing an individual "
+        "reference, it is passed in the validation result file.",
+    )
+
+
 class _RobotBase(BaseModel):
     """
     Base Robot class.

{destiny_sdk-0.3.0a0 → destiny_sdk-0.4.1}/tests/unit/test_client.py

@@ -5,7 +5,12 @@ import uuid
 
 import pytest
 from destiny_sdk.client import Client, create_signature
-from destiny_sdk.robots import EnhancementRequestRead, RobotError, RobotResult
+from destiny_sdk.robots import (
+    RobotEnhancementBatchRead,
+    RobotEnhancementBatchResult,
+    RobotError,
+)
+from pydantic import HttpUrl
 from pytest_httpx import HTTPXMock
 
 
@@ -17,34 +22,36 @@ def frozen_time(monkeypatch):
     monkeypatch.setattr(time, "time", frozen_timestamp)
 
 
-def test_verify_hmac_headers_sent(httpx_mock: HTTPXMock, frozen_time) -> None:  # noqa: ARG001
-    """Test that request is authorized with a signature."""
+def test_verify_hmac_headers_sent(
+    httpx_mock: HTTPXMock,
+    frozen_time,  # noqa: ARG001
+) -> None:
+    """Test that robot enhancement batch result request is authorized."""
     fake_secret_key = "asdfhjgji94523q0uflsjf349wjilsfjd9q23"
     fake_robot_id = uuid.uuid4()
     fake_destiny_repository_url = "https://www.destiny-repository-lives-here.co.au/v1"
 
-    fake_robot_result = RobotResult(
+    fake_batch_result = RobotEnhancementBatchResult(
         request_id=uuid.uuid4(), error=RobotError(message="Cannot process this batch")
     )
 
-    expected_response_body = EnhancementRequestRead(
-        reference_ids=[uuid.uuid4()],
+    expected_response_body = RobotEnhancementBatchRead(
         id=uuid.uuid4(),
         robot_id=uuid.uuid4(),
-        request_status="failed",
+        error="Cannot process this batch",
     )
 
     expected_signature = create_signature(
         secret_key=fake_secret_key,
-        request_body=fake_robot_result.model_dump_json().encode(),
+        request_body=fake_batch_result.model_dump_json().encode(),
         client_id=fake_robot_id,
         timestamp=time.time(),
     )
 
     httpx_mock.add_response(
         url=fake_destiny_repository_url
-        + "/enhancement-requests/"
-        + f"{fake_robot_result.request_id}/results/",
+        + "/robot-enhancement-batches/"
+        + f"{fake_batch_result.request_id}/results/",
         method="POST",
         match_headers={
             "Authorization": f"Signature {expected_signature}",
@@ -55,11 +62,11 @@ def test_verify_hmac_headers_sent(httpx_mock: HTTPXMock, frozen_time) -> None:
     )
 
     Client(
-        base_url=fake_destiny_repository_url,
+        base_url=HttpUrl(fake_destiny_repository_url),
         secret_key=fake_secret_key,
         client_id=fake_robot_id,
-    ).send_robot_result(
-        robot_result=fake_robot_result,
+    ).send_robot_enhancement_batch_result(
+        robot_enhancement_batch_result=fake_batch_result,
     )
 
     callback_request = httpx_mock.get_requests()

{destiny_sdk-0.3.0a0 → destiny_sdk-0.4.1}/uv.lock

@@ -63,7 +63,7 @@ wheels = [
 
 [[package]]
 name = "destiny-sdk"
-version = "0.3.0a0"
+version = "0.4.1"
 source = { editable = "." }
 dependencies = [
     { name = "cachetools" },