clarity-api-sdk-python 0.3.34__tar.gz → 0.3.35__tar.gz

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clarity-api-sdk-python
-Version: 0.3.34
+Version: 0.3.35
 Summary: A Python SDK to connect to the CTI Clarity API server.
 Author-email: "Chesapeake Technology Inc." <support@chesapeaketech.com>
 Project-URL: Homepage, https://github.com/chesapeake-tech/clarity-api-sdk-python
@@ -16,6 +16,7 @@ Requires-Dist: httpx_auth>=0.23.1
 Requires-Dist: httpx-retries>=0.4.5
 Requires-Dist: pydantic==2.12.3
 Requires-Dist: structlog==25.4.0
+Requires-Dist: typer>=0.15
 Provides-Extra: dev
 Requires-Dist: black==25.9.0; extra == "dev"
 Requires-Dist: build==1.3.0; extra == "dev"

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clarity-api-sdk-python"
-version = "0.3.34"
+version = "0.3.35"
 authors = [
   { name="Chesapeake Technology Inc.", email="support@chesapeaketech.com" },
 ]
@@ -25,6 +25,7 @@ dependencies = [
     "httpx-retries>=0.4.5",
     "pydantic==2.12.3",
     "structlog==25.4.0",
+    "typer>=0.15",
 ]
 
 [project.optional-dependencies]
@@ -43,6 +44,9 @@ dev = [
 brotli = ["httpx[brotli]>=0.28.1"]
 http2 = ["httpx[http2]>=0.28.1"]
 
+[project.scripts]
+ftm = "cti.cli.__main__:main"
+
 [project.urls]
 "Homepage" = "https://github.com/chesapeake-tech/clarity-api-sdk-python"
 

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/src/clarity_api_sdk_python.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clarity-api-sdk-python
-Version: 0.3.34
+Version: 0.3.35
 Summary: A Python SDK to connect to the CTI Clarity API server.
 Author-email: "Chesapeake Technology Inc." <support@chesapeaketech.com>
 Project-URL: Homepage, https://github.com/chesapeake-tech/clarity-api-sdk-python
@@ -16,6 +16,7 @@ Requires-Dist: httpx_auth>=0.23.1
 Requires-Dist: httpx-retries>=0.4.5
 Requires-Dist: pydantic==2.12.3
 Requires-Dist: structlog==25.4.0
+Requires-Dist: typer>=0.15
 Provides-Extra: dev
 Requires-Dist: black==25.9.0; extra == "dev"
 Requires-Dist: build==1.3.0; extra == "dev"

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/src/clarity_api_sdk_python.egg-info/SOURCES.txt

@@ -3,6 +3,7 @@ pyproject.toml
 src/clarity_api_sdk_python.egg-info/PKG-INFO
 src/clarity_api_sdk_python.egg-info/SOURCES.txt
 src/clarity_api_sdk_python.egg-info/dependency_links.txt
+src/clarity_api_sdk_python.egg-info/entry_points.txt
 src/clarity_api_sdk_python.egg-info/requires.txt
 src/clarity_api_sdk_python.egg-info/top_level.txt
 src/cti/__init__.py
@@ -14,6 +15,10 @@ src/cti/api/client.py
 src/cti/api/session.py
 src/cti/api/sonar_wiz_api.py
 src/cti/api/sonar_wiz_async_api.py
+src/cti/cli/__init__.py
+src/cti/cli/__main__.py
+src/cti/cli/client.py
+src/cti/cli/main.py
 src/cti/logger/__init__.py
 src/cti/logger/logger.py
 src/cti/model/__init__.py
@@ -45,4 +50,7 @@ src/cti/model/sidescan_ping_source.py
 src/cti/model/source.py
 src/cti/model/survey.py
 src/cti/model/target.py
-src/cti/model/tow_system.py
+src/cti/model/tow_system.py
+tests/test_cli.py
+tests/test_sdk_async_methods.py
+tests/test_sdk_methods.py

clarity_api_sdk_python-0.3.35/src/clarity_api_sdk_python.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+ftm = cti.cli.__main__:main

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/src/clarity_api_sdk_python.egg-info/requires.txt

@@ -5,6 +5,7 @@ httpx_auth>=0.23.1
 httpx-retries>=0.4.5
 pydantic==2.12.3
 structlog==25.4.0
+typer>=0.15
 
 [brotli]
 httpx[brotli]>=0.28.1

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/src/cti/api/async_client.py

@@ -25,20 +25,24 @@ class ClarityApiAsyncClient(AsyncClient):
 
     def __init__(self):
 
-        # credentials for Clarity API
-        cti_credentials = OAuth2ClientCredentials(
-            token_url=(
-                f'{os.environ.get("KEYCLOAK_SERVER_URL", "missing KEYCLOAK_SERVER_URL")}/realms/'
-                f'{os.environ.get("KEYCLOAK_REALM", "missing KEYCLOAK_REALM")}'
-                "/protocol/openid-connect/token"
-            ),
-            client_id=os.environ.get(
-                "KEYCLOAK_CLIENT_ID", "missing KEYCLOAK_CLIENT_ID"
-            ),
-            client_secret=os.environ.get(
-                "KEYCLOAK_CLIENT_SECRET", "missing KEYCLOAK_CLIENT_SECRET"
-            ),
-        )
+        # In local dev mode, skip OAuth2 authentication — the server
+        # accepts unauthenticated requests when CLARITY_PLATFORM=local.
+        if os.environ.get("CLARITY_PLATFORM") == "local":
+            cti_credentials = None
+        else:
+            cti_credentials = OAuth2ClientCredentials(
+                token_url=(
+                    f'{os.environ.get("KEYCLOAK_SERVER_URL", "missing KEYCLOAK_SERVER_URL")}/realms/'
+                    f'{os.environ.get("KEYCLOAK_REALM", "missing KEYCLOAK_REALM")}'
+                    "/protocol/openid-connect/token"
+                ),
+                client_id=os.environ.get(
+                    "KEYCLOAK_CLIENT_ID", "missing KEYCLOAK_CLIENT_ID"
+                ),
+                client_secret=os.environ.get(
+                    "KEYCLOAK_CLIENT_SECRET", "missing KEYCLOAK_CLIENT_SECRET"
+                ),
+            )
 
         # retry mechanism for API requests
         retry = Retry(total=12, backoff_factor=0.5)

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/src/cti/api/client.py

@@ -22,20 +22,24 @@ class ClarityApiClient(Client):
 
     def __init__(self):
 
-        # credentials for Clarity API
-        cti_credentials = OAuth2ClientCredentials(
-            token_url=(
-                f'{os.environ.get("KEYCLOAK_SERVER_URL", "missing KEYCLOAK_SERVER_URL")}/realms/'
-                f'{os.environ.get("KEYCLOAK_REALM", "missing KEYCLOAK_REALM")}'
-                "/protocol/openid-connect/token"
-            ),
-            client_id=os.environ.get(
-                "KEYCLOAK_CLIENT_ID", "missing KEYCLOAK_CLIENT_ID"
-            ),
-            client_secret=os.environ.get(
-                "KEYCLOAK_CLIENT_SECRET", "missing KEYCLOAK_CLIENT_SECRET"
-            ),
-        )
+        # In local dev mode, skip OAuth2 authentication — the server
+        # accepts unauthenticated requests when CLARITY_PLATFORM=local.
+        if os.environ.get("CLARITY_PLATFORM") == "local":
+            cti_credentials = None
+        else:
+            cti_credentials = OAuth2ClientCredentials(
+                token_url=(
+                    f'{os.environ.get("KEYCLOAK_SERVER_URL", "missing KEYCLOAK_SERVER_URL")}/realms/'
+                    f'{os.environ.get("KEYCLOAK_REALM", "missing KEYCLOAK_REALM")}'
+                    "/protocol/openid-connect/token"
+                ),
+                client_id=os.environ.get(
+                    "KEYCLOAK_CLIENT_ID", "missing KEYCLOAK_CLIENT_ID"
+                ),
+                client_secret=os.environ.get(
+                    "KEYCLOAK_CLIENT_SECRET", "missing KEYCLOAK_CLIENT_SECRET"
+                ),
+            )
 
         # retry mechanism for API requests
         retry = Retry(total=12, backoff_factor=0.5)

{clarity_api_sdk_python-0.3.34 → clarity_api_sdk_python-0.3.35}/src/cti/api/sonar_wiz_api.py

@@ -4,8 +4,14 @@ Provides strongly-typed methods for interacting with the SonarWiz API,
 using Pydantic models for request and response validation.
 """
 
+import os
+import time
+from pathlib import Path
+from urllib.parse import urlparse
 from uuid import UUID
 
+import httpx
+
 from cti.model.altitude_source import AltitudeSource
 from cti.model.altitude_source import AltitudeSourceCreate
 from cti.model.altitude_source import AltitudeSourceUpdate
@@ -49,6 +55,7 @@ from cti.model.position_source import PositionSourceCreate
 from cti.model.position_source import PositionSourceUpdate
 from cti.model.processing_job import JobStatusCallback
 from cti.model.processing_job import ProcessingJob
+from cti.model.processing_job import ProcessingJobCreate
 from cti.model.processing_job import ProcessingJobList
 from cti.model.processing_log import ProcessingLog
 from cti.model.processing_log import ProcessingLogCreate
@@ -110,11 +117,11 @@ class SonarWizApi:
     Pydantic models for responses. HTTP errors are allowed to propagate.
     """
 
-    def __init__(self, client: ClarityApiClient):
-        """Initialize API wrapper with ClarityApiClient.
+    def __init__(self, client: ClarityApiClient | httpx.Client):
+        """Initialize API wrapper with an HTTP client.
 
         Args:
-            client: ClarityApiClient instance (handles auth and HTTP).
+            client: ClarityApiClient or plain httpx.Client (for local dev).
         """
         super().__init__()
         self._client = client
@@ -446,7 +453,7 @@ class SonarWizApi:
             Created project instance.
         """
         response = self._client.post(
-            "/api/v1/projects/", json=project.model_dump(mode="json")
+            "/api/v1/projects", json=project.model_dump(mode="json")
         )
         response.raise_for_status()
         return Project.model_validate(response.json())
@@ -1999,6 +2006,22 @@ class SonarWizApi:
 
     # ── Processing Jobs ──────────────────────────────────────────────────
 
+    def create_job(self, job_data: ProcessingJobCreate) -> ProcessingJob:
+        """Create a new processing job.
+
+        Args:
+            job_data: Job creation data with survey_id and job_type.
+
+        Returns:
+            Created processing job instance.
+        """
+        response = self._client.post(
+            "/api/v1/jobs",
+            json=job_data.model_dump(mode="json"),
+        )
+        response.raise_for_status()
+        return ProcessingJob.model_validate(response.json())
+
     def get_job(self, job_id: UUID | str) -> ProcessingJob:
         """Get processing job by ID.
 
@@ -2057,3 +2080,196 @@ class SonarWizApi:
         )
         response.raise_for_status()
         return ProcessingJob.model_validate(response.json())
+
+    # ── High-Level Workflow Methods ──────────────────────────────────────
+
+    def upload_file(
+        self,
+        survey_id: UUID,
+        file_path: str | Path,
+        raw_file_configuration_id: UUID | None = None,
+        chunk_size: int = 5 * 1024 * 1024,
+    ) -> RawFile:
+        """Upload a sonar file to a survey via multipart S3 upload.
+
+        Handles the full upload flow: create raw file record, upload parts
+        via presigned URLs, and complete the multipart upload.
+
+        Args:
+            survey_id: Survey to upload to.
+            file_path: Local path to the sonar file (.xtf, .jsf, etc.).
+            raw_file_configuration_id: Optional config ID. If None, uses the
+                survey's default configuration.
+            chunk_size: Size of each upload part in bytes (default 5MB, S3 minimum).
+
+        Returns:
+            Completed RawFile with state="ready".
+        """
+        file_path = Path(file_path)
+        file_size = file_path.stat().st_size
+
+        # Look up default raw file configuration if not provided
+        if raw_file_configuration_id is None:
+            response = self._client.get(
+                f"/api/v1/surveys/{survey_id}/rawfileconfigurations"
+            )
+            response.raise_for_status()
+            configs = [RawFileConfiguration.model_validate(c) for c in response.json()]
+            if not configs:
+                raise ValueError(f"No raw file configuration found for survey {survey_id}")
+            raw_file_configuration_id = configs[0].raw_file_configuration_id
+
+        # Initiate multipart upload
+        raw_file_create = RawFileCreate(
+            survey_id=survey_id,
+            raw_file_configuration_id=raw_file_configuration_id,
+            file_name=file_path.name,
+            file_size=file_size,
+        )
+        response = self._client.post(
+            "/api/v1/rawfiles/upload",
+            json=raw_file_create.model_dump(mode="json"),
+        )
+        response.raise_for_status()
+        raw_file = RawFileWithUpload.model_validate(response.json())
+
+        logger.info(
+            "upload_started",
+            raw_file_id=str(raw_file.raw_file_id),
+            file_name=file_path.name,
+            file_size=file_size,
+        )
+
+        # Upload parts
+        parts: list[dict] = []
+        part_number = 0
+        try:
+            with httpx.Client(timeout=120) as s3_client, open(file_path, "rb") as f:
+                while True:
+                    chunk = f.read(chunk_size)
+                    if not chunk:
+                        break
+                    part_number += 1
+
+                    # Get presigned URL for this part
+                    url_response = self._client.get(
+                        f"/api/v1/rawfiles/{raw_file.raw_file_id}/upload-parts/{part_number}/url"
+                    )
+                    url_response.raise_for_status()
+                    presigned_url = PartPresignedURL.model_validate(url_response.json()).url
+
+                    # The server generates presigned URLs using its S3_ENDPOINT_URL,
+                    # which may be a Docker-internal hostname (e.g. minio:9000).
+                    # If the client has its own S3_ENDPOINT_URL (e.g. localhost:9000),
+                    # rewrite the URL so it's reachable from the client's network.
+                    client_s3_endpoint = os.environ.get("S3_ENDPOINT_URL")
+                    if client_s3_endpoint:
+                        parsed_presigned = urlparse(presigned_url)
+                        parsed_client = urlparse(client_s3_endpoint)
+                        presigned_url = presigned_url.replace(
+                            f"{parsed_presigned.scheme}://{parsed_presigned.netloc}",
+                            f"{parsed_client.scheme}://{parsed_client.netloc}",
+                            1,
+                        )
+
+                    # Upload directly to S3/MinIO (not through API client)
+                    put_response = s3_client.put(presigned_url, content=chunk)
+                    put_response.raise_for_status()
+                    etag = put_response.headers.get("ETag", "").strip('"')
+
+                    parts.append({"ETag": etag, "PartNumber": part_number})
+                    logger.debug(
+                        "upload_part_complete",
+                        part=part_number,
+                        etag=etag,
+                    )
+        except Exception:
+            logger.error(
+                "upload_failed",
+                raw_file_id=str(raw_file.raw_file_id),
+                parts_uploaded=part_number,
+            )
+            raise
+
+        # Complete multipart upload
+        complete_body = CompleteMultipartUploadBody(
+            parts=[Part(ETag=p["ETag"], PartNumber=p["PartNumber"]) for p in parts]
+        )
+        complete_response = self._client.post(
+            f"/api/v1/rawfiles/{raw_file.raw_file_id}/upload-complete",
+            json=complete_body.model_dump(mode="json"),
+        )
+        complete_response.raise_for_status()
+        completed = RawFile.model_validate(complete_response.json())
+
+        logger.info(
+            "upload_complete",
+            raw_file_id=str(completed.raw_file_id),
+            state=completed.state,
+            parts=part_number,
+        )
+        return completed
+
+    def trigger_processing(self, survey_id: UUID) -> ProcessingJob:
+        """Trigger processing for a survey.
+
+        Creates a processing job and dispatches it via SQS.
+
+        Args:
+            survey_id: Survey to process.
+
+        Returns:
+            The created ProcessingJob.
+        """
+        response = self._client.post(f"/api/v1/ingest/{survey_id}")
+        response.raise_for_status()
+        data = response.json()
+
+        # The ingest endpoint returns a dict with job_id, not a full ProcessingJob.
+        # Fetch the full job record.
+        if job_id := data.get("job_id"):
+            return self.get_job(job_id)
+
+        return ProcessingJob.model_validate(data)
+
+    def wait_for_job(
+        self,
+        job_id: UUID | str,
+        timeout: float = 300,
+        poll_interval: float = 5,
+    ) -> ProcessingJob:
+        """Poll a processing job until it reaches a terminal state.
+
+        Args:
+            job_id: Job UUID to poll.
+            timeout: Maximum seconds to wait (default 5 minutes).
+            poll_interval: Seconds between polls (default 5).
+
+        Returns:
+            The completed or failed ProcessingJob.
+
+        Raises:
+            TimeoutError: If the job doesn't reach a terminal state within timeout.
+        """
+        terminal_states = {"completed", "failed", "cancelled"}
+        deadline = time.monotonic() + timeout
+
+        while time.monotonic() < deadline:
+            job = self.get_job(job_id)
+            if job.status in terminal_states:
+                return job
+
+            elapsed = timeout - (deadline - time.monotonic())
+            logger.debug(
+                "wait_for_job_poll",
+                job_id=str(job_id),
+                status=job.status,
+                phase=job.current_phase,
+                progress=job.progress,
+                elapsed=round(elapsed, 1),
+            )
+            time.sleep(poll_interval)
+
+        raise TimeoutError(
+            f"Job {job_id} did not complete within {timeout}s (last status: {job.status})"
+        )