clarity-api-sdk-python 0.3.36__tar.gz → 0.3.38__tar.gz

{clarity_api_sdk_python-0.3.36 → clarity_api_sdk_python-0.3.38}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clarity-api-sdk-python
-Version: 0.3.36
+Version: 0.3.38
 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

{clarity_api_sdk_python-0.3.36 → clarity_api_sdk_python-0.3.38}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "clarity-api-sdk-python"
-version = "0.3.36"
+version = "0.3.38"
 authors = [
   { name="Chesapeake Technology Inc.", email="support@chesapeaketech.com" },
 ]

{clarity_api_sdk_python-0.3.36 → clarity_api_sdk_python-0.3.38}/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.36
+Version: 0.3.38
 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

{clarity_api_sdk_python-0.3.36 → clarity_api_sdk_python-0.3.38}/src/cti/api/sonar_wiz_api.py

@@ -2116,7 +2116,9 @@ class SonarWizApi:
             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}")
+                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
@@ -2156,7 +2158,9 @@ class SonarWizApi:
                         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
+                    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).
@@ -2210,23 +2214,27 @@ class SonarWizApi:
         )
         return completed
 
-    def trigger_processing(self, survey_id: UUID) -> ProcessingJob:
-        """Trigger processing for a survey.
-
-        Creates a processing job and dispatches it via SQS.
+    def process(self, survey_id: UUID, target_phase: str = "products") -> ProcessingJob:
+        """Dispatch a pipeline run for a survey.
 
         Args:
             survey_id: Survey to process.
+            target_phase: Pipeline phase to run up to. Defaults to "products"
+                (full pipeline). "scan" runs only setup → scan. The engine's
+                pull-chain resolves any required predecessor phases.
 
         Returns:
             The created ProcessingJob.
         """
-        response = self._client.post(f"/api/v1/ingest/{survey_id}")
+        response = self._client.post(
+            "/api/v1/process",
+            json={"survey_id": str(survey_id), "target_phase": target_phase},
+        )
         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.
+        # The /process 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)
 

{clarity_api_sdk_python-0.3.36 → clarity_api_sdk_python-0.3.38}/src/cti/api/sonar_wiz_async_api.py

@@ -2164,7 +2164,9 @@ class SonarWizAsyncApi:
             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}")
+                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
@@ -2206,7 +2208,9 @@ class SonarWizAsyncApi:
                             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
+                        presigned_url = PartPresignedURL.model_validate(
+                            url_response.json()
+                        ).url
 
                         # Upload directly to S3/MinIO (not through API client)
                         put_response = await s3_client.put(presigned_url, content=chunk)
@@ -2246,27 +2250,29 @@ class SonarWizAsyncApi:
         )
         return completed
 
-    async def trigger_processing(
-        self, survey_id: UUID
+    async def process(
+        self, survey_id: UUID, target_phase: str = "products"
     ) -> ProcessingJob:
-        """Trigger processing for a survey.
-
-        Creates a processing job and dispatches it via SQS.
+        """Dispatch a pipeline run for a survey.
 
         Args:
             survey_id: Survey to process.
+            target_phase: Pipeline phase to run up to. Defaults to "products"
+                (full pipeline). "scan" runs only setup → scan. The engine's
+                pull-chain resolves any required predecessor phases.
 
         Returns:
             The created ProcessingJob.
         """
         response = await self._client.post(
-            f"/api/v1/ingest/{survey_id}",
+            "/api/v1/process",
+            json={"survey_id": str(survey_id), "target_phase": target_phase},
         )
         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.
+        # The /process endpoint returns a dict with job_id, not a full
+        # ProcessingJob. Fetch the full job record.
         if job_id := data.get("job_id"):
             return await self.get_job(job_id)
 

{clarity_api_sdk_python-0.3.36 → clarity_api_sdk_python-0.3.38}/src/cti/cli/main.py

@@ -18,10 +18,14 @@ app = typer.Typer(
     no_args_is_help=True,
 )
 
-list_app = typer.Typer(help="List resources (surveys, projects, jobs).", no_args_is_help=True)
+list_app = typer.Typer(
+    help="List resources (surveys, projects, jobs).", no_args_is_help=True
+)
 app.add_typer(list_app, name="list")
 
-delete_app = typer.Typer(help="Delete resources (rawfile, survey, project).", no_args_is_help=True)
+delete_app = typer.Typer(
+    help="Delete resources (rawfile, survey, project).", no_args_is_help=True
+)
 app.add_typer(delete_app, name="delete")
 
 
@@ -45,10 +49,21 @@ def _get_error_detail(e: httpx.HTTPStatusError) -> str:
 def upload(
     file: Path = typer.Argument(..., help="Path to sonar file (.xtf, .jsf, etc.)"),
     survey: UUID = typer.Option(..., "--survey", "-s", help="Survey ID to upload to"),
-    config_id: UUID | None = typer.Option(None, "--config", "-c", help="Raw file configuration ID (default: survey's default)"),
-    no_mappings: bool = typer.Option(False, "--no-mappings", help="Skip automatic device mapping creation"),
-    sidescan_stream: str = typer.Option("0", "--sidescan-stream", help="Source stream identifier for sidescan device"),
-    gnss_stream: str = typer.Option("1", "--gnss-stream", help="Source stream identifier for GNSS device"),
+    config_id: UUID | None = typer.Option(
+        None,
+        "--config",
+        "-c",
+        help="Raw file configuration ID (default: survey's default)",
+    ),
+    no_mappings: bool = typer.Option(
+        False, "--no-mappings", help="Skip automatic device mapping creation"
+    ),
+    sidescan_stream: str = typer.Option(
+        "0", "--sidescan-stream", help="Source stream identifier for sidescan device"
+    ),
+    gnss_stream: str = typer.Option(
+        "1", "--gnss-stream", help="Source stream identifier for GNSS device"
+    ),
     output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ) -> None:
     """Upload a sonar file to a survey.
@@ -75,7 +90,9 @@ def upload(
         typer.echo(f"Error: {_get_error_detail(e)}", err=True)
         raise typer.Exit(1)
 
-    typer.echo(f"Uploaded: {result.raw_file_id} ({result.file_name}, {result.file_size} bytes)")
+    typer.echo(
+        f"Uploaded: {result.raw_file_id} ({result.file_name}, {result.file_size} bytes)"
+    )
 
     # Auto-create device mappings
     if not no_mappings:
@@ -104,30 +121,45 @@ def upload(
                 else:
                     continue
 
-                api.create_raw_file_device_mapping(RawFileDeviceMappingCreate(
-                    raw_file_id=result.raw_file_id,
-                    device_id=device.device_id,
-                    source_stream_identifier=stream_id,
-                    input_srid=4326,
-                    input_timezone=tz,
-                ))
+                api.create_raw_file_device_mapping(
+                    RawFileDeviceMappingCreate(
+                        raw_file_id=result.raw_file_id,
+                        device_id=device.device_id,
+                        source_stream_identifier=stream_id,
+                        input_srid=4326,
+                        input_timezone=tz,
+                    )
+                )
                 typer.echo(f"Mapped: {device.name} → stream {stream_id}")
                 mappings_created += 1
 
             if mappings_created == 0:
-                typer.echo("Warning: no sidescan/GNSS devices found on survey platform — no mappings created", err=True)
+                typer.echo(
+                    "Warning: no sidescan/GNSS devices found on survey platform — no mappings created",
+                    err=True,
+                )
         except httpx.HTTPStatusError as e:
             if e.response.status_code == 404:
-                typer.echo("Warning: no platform found on survey — skipping device mappings. Run 'ftm init' first.", err=True)
+                typer.echo(
+                    "Warning: no platform found on survey — skipping device mappings. Run 'ftm init' first.",
+                    err=True,
+                )
             else:
-                typer.echo(f"Warning: failed to create device mappings: {_get_error_detail(e)}", err=True)
+                typer.echo(
+                    f"Warning: failed to create device mappings: {_get_error_detail(e)}",
+                    err=True,
+                )
 
     _output(
         {
             "raw_file_id": str(result.raw_file_id),
             "file_name": result.file_name,
             "file_size": result.file_size,
-            "state": result.state.value if hasattr(result.state, "value") else str(result.state),
+            "state": (
+                result.state.value
+                if hasattr(result.state, "value")
+                else str(result.state)
+            ),
         },
         output_json,
     )
@@ -136,16 +168,25 @@ def upload(
 @app.command()
 def process(
     survey: UUID = typer.Argument(..., help="Survey ID to process"),
-    wait: bool = typer.Option(False, "--wait", "-w", help="Wait for processing to complete"),
-    timeout: float = typer.Option(300, "--timeout", "-t", help="Wait timeout in seconds"),
+    target_phase: str = typer.Option(
+        "products",
+        "--target-phase",
+        help="Pipeline phase to run up to. 'products' (default) runs the full pipeline; 'scan' runs scan only.",
+    ),
+    wait: bool = typer.Option(
+        False, "--wait", "-w", help="Wait for processing to complete"
+    ),
+    timeout: float = typer.Option(
+        300, "--timeout", "-t", help="Wait timeout in seconds"
+    ),
     output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ) -> None:
     """Trigger processing for a survey."""
     api = get_api()
-    typer.echo(f"Triggering processing for survey {survey}...")
+    typer.echo(f"Triggering processing for survey {survey} (target: {target_phase})...")
 
     try:
-        job = api.trigger_processing(survey_id=survey)
+        job = api.process(survey_id=survey, target_phase=target_phase)
     except httpx.HTTPStatusError as e:
         typer.echo(f"Error: {_get_error_detail(e)}", err=True)
         raise typer.Exit(1)
@@ -234,12 +275,27 @@ def status(
 def init(
     project: str = typer.Option(..., "--project", "-p", help="Project name"),
     srid: str = typer.Option(..., "--srid", help="Projected CRS (e.g. EPSG:32618)"),
-    timezone: str = typer.Option("Etc/UTC", "--timezone", "-tz", help="IANA timezone (default: Etc/UTC)"),
-    org: str = typer.Option("Default Organization", "--org", "-o", help="Organization name (found or created)"),
-    survey_name: Optional[str] = typer.Option(None, "--survey", "-s", help="Survey name (default: project name)"),
-    description: Optional[str] = typer.Option(None, "--description", "-d", help="Survey description"),
-    platform_type: str = typer.Option("Towed Body", "--platform-type", help="Platform type name (from seed data)"),
-    platform_name: str = typer.Option("Platform", "--platform-name", help="Platform name"),
+    timezone: str = typer.Option(
+        "Etc/UTC", "--timezone", "-tz", help="IANA timezone (default: Etc/UTC)"
+    ),
+    org: str = typer.Option(
+        "Default Organization",
+        "--org",
+        "-o",
+        help="Organization name (found or created)",
+    ),
+    survey_name: Optional[str] = typer.Option(
+        None, "--survey", "-s", help="Survey name (default: project name)"
+    ),
+    description: Optional[str] = typer.Option(
+        None, "--description", "-d", help="Survey description"
+    ),
+    platform_type: str = typer.Option(
+        "Towed Body", "--platform-type", help="Platform type name (from seed data)"
+    ),
+    platform_name: str = typer.Option(
+        "Platform", "--platform-name", help="Platform name"
+    ),
     output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ) -> None:
     """Initialize a new project and survey for processing.
@@ -307,7 +363,10 @@ def init(
         pt = next((p for p in pt_list if p.name == platform_type), None)
         if not pt:
             available = ", ".join(p.name for p in pt_list)
-            typer.echo(f"Error: platform type '{platform_type}' not found. Available: {available}", err=True)
+            typer.echo(
+                f"Error: platform type '{platform_type}' not found. Available: {available}",
+                err=True,
+            )
             raise typer.Exit(1)
     except httpx.HTTPStatusError as e:
         typer.echo(f"Error listing platform types: {_get_error_detail(e)}", err=True)
@@ -338,21 +397,43 @@ def init(
     sidescan_dt = dt_by_enum.get("sidescan_sonar")
     gnss_dt = dt_by_enum.get("gnss_gps_position_sensor")
     if not sidescan_dt or not gnss_dt:
-        typer.echo("Error: required device types (sidescan_sonar, gnss_gps_position_sensor) not found in seed data", err=True)
+        typer.echo(
+            "Error: required device types (sidescan_sonar, gnss_gps_position_sensor) not found in seed data",
+            err=True,
+        )
         raise typer.Exit(1)
 
-    device_defaults = dict(channel=0, offset_x=0, offset_y=0, offset_z=0, offset_heading=0, offset_pitch=0, offset_roll=0, latency=0)
+    device_defaults = dict(
+        channel=0,
+        offset_x=0,
+        offset_y=0,
+        offset_z=0,
+        offset_heading=0,
+        offset_pitch=0,
+        offset_roll=0,
+        latency=0,
+    )
     try:
-        ss_device = api.create_device(DeviceCreate(
-            platform_id=new_platform.platform_id, device_type_id=sidescan_dt.device_type_id,
-            name="Sidescan", is_towed=True, **device_defaults,
-        ))
+        ss_device = api.create_device(
+            DeviceCreate(
+                platform_id=new_platform.platform_id,
+                device_type_id=sidescan_dt.device_type_id,
+                name="Sidescan",
+                is_towed=True,
+                **device_defaults,
+            )
+        )
         typer.echo(f"Created device: Sidescan ({ss_device.device_id})")
 
-        gnss_device = api.create_device(DeviceCreate(
-            platform_id=new_platform.platform_id, device_type_id=gnss_dt.device_type_id,
-            name="GNSS", is_towed=False, **device_defaults,
-        ))
+        gnss_device = api.create_device(
+            DeviceCreate(
+                platform_id=new_platform.platform_id,
+                device_type_id=gnss_dt.device_type_id,
+                name="GNSS",
+                is_towed=False,
+                **device_defaults,
+            )
+        )
         typer.echo(f"Created device: GNSS ({gnss_device.device_id})")
     except httpx.HTTPStatusError as e:
         typer.echo(f"Error creating device: {_get_error_detail(e)}", err=True)
@@ -379,7 +460,9 @@ def init(
 
 @list_app.command("surveys")
 def list_surveys(
-    project_name: Optional[str] = typer.Option(None, "--project", "-p", help="Filter by project name"),
+    project_name: Optional[str] = typer.Option(
+        None, "--project", "-p", help="Filter by project name"
+    ),
     output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ) -> None:
     """List surveys."""
@@ -396,18 +479,35 @@ def list_surveys(
         raise typer.Exit(0)
 
     if output_json:
-        typer.echo(json.dumps(
-            [{"survey_id": str(s.survey_id), "name": s.name, "project_id": str(s.project_id), "geodesy_srid": s.geodesy_srid, "timezone": s.timezone_name, "created": str(s.created_date)} for s in surveys],
-            indent=2, default=str,
-        ))
+        typer.echo(
+            json.dumps(
+                [
+                    {
+                        "survey_id": str(s.survey_id),
+                        "name": s.name,
+                        "project_id": str(s.project_id),
+                        "geodesy_srid": s.geodesy_srid,
+                        "timezone": s.timezone_name,
+                        "created": str(s.created_date),
+                    }
+                    for s in surveys
+                ],
+                indent=2,
+                default=str,
+            )
+        )
     else:
         for s in surveys:
-            typer.echo(f"  {s.survey_id}  {s.name}  (srid={s.geodesy_srid}, tz={s.timezone_name})")
+            typer.echo(
+                f"  {s.survey_id}  {s.name}  (srid={s.geodesy_srid}, tz={s.timezone_name})"
+            )
 
 
 @list_app.command("projects")
 def list_projects(
-    org_name: Optional[str] = typer.Option(None, "--org", "-o", help="Filter by organization name"),
+    org_name: Optional[str] = typer.Option(
+        None, "--org", "-o", help="Filter by organization name"
+    ),
     output_json: bool = typer.Option(False, "--json", "-j", help="Output as JSON"),
 ) -> None:
     """List projects."""
@@ -424,10 +524,21 @@ def list_projects(
         raise typer.Exit(0)
 
     if output_json:
-        typer.echo(json.dumps(
-            [{"project_id": str(p.project_id), "name": p.project_name, "organization_id": str(p.organization_id), "created": str(p.created_date)} for p in projects],
-            indent=2, default=str,
-        ))
+        typer.echo(
+            json.dumps(
+                [
+                    {
+                        "project_id": str(p.project_id),
+                        "name": p.project_name,
+                        "organization_id": str(p.organization_id),
+                        "created": str(p.created_date),
+                    }
+                    for p in projects
+                ],
+                indent=2,
+                default=str,
+            )
+        )
     else:
         for p in projects:
             typer.echo(f"  {p.project_id}  {p.project_name}")
@@ -447,16 +558,30 @@ def list_jobs(
         raise typer.Exit(0)
 
     if output_json:
-        typer.echo(json.dumps(
-            [{"job_id": str(j.job_id), "status": j.status, "job_type": j.job_type, "created_at": str(j.created_at), "completed_at": str(j.completed_at) if j.completed_at else None} for j in result.jobs],
-            indent=2, default=str,
-        ))
+        typer.echo(
+            json.dumps(
+                [
+                    {
+                        "job_id": str(j.job_id),
+                        "status": j.status,
+                        "job_type": j.job_type,
+                        "created_at": str(j.created_at),
+                        "completed_at": str(j.completed_at) if j.completed_at else None,
+                    }
+                    for j in result.jobs
+                ],
+                indent=2,
+                default=str,
+            )
+        )
     else:
         for j in result.jobs:
             typer.echo(f"  {j.job_id}  {j.status}  {j.job_type}  {j.created_at}")
 
 
-def _delete_resource(path: str, resource_label: str, resource_id: UUID, yes: bool) -> None:
+def _delete_resource(
+    path: str, resource_label: str, resource_id: UUID, yes: bool
+) -> None:
     """Confirm and DELETE a resource by its API path. Exits non-zero on error."""
     if not yes and not typer.confirm(f"Delete {resource_label} {resource_id}?"):
         typer.echo("Aborted.")

clarity_api_sdk_python-0.3.38/src/cti/model/raw_file_state.py

@@ -0,0 +1,21 @@
+"""Raw file state"""
+
+from enum import Enum
+
+
+class RawFileState(str, Enum):
+    """Status of a raw file through upload, scan, and ingest.
+
+    The legal transition graph is enforced server-side; this enum is a
+    passthrough carrying the value over the wire. See clarity-server
+    `model.raw_file_state` for the authoritative transition rules.
+    """
+
+    UPLOADING = "uploading"
+    READY = "ready"
+    ERROR_UPLOAD = "error_upload"
+    SCANNING = "scanning"
+    SCANNED = "scanned"
+    SCAN_ERROR = "scan_error"
+    ERROR_INGEST = "error_ingest"
+    INGEST_COMPLETE = "ingest_complete"