waveium 0.2.0__py3-none-any.whl

waveium/models/environments.py

@@ -0,0 +1,247 @@
+"""Environment models for the Waveium SDK."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from .common import EnvironmentType, _fmt_dt, _tabulate
+
+
+class BoundsInput(BaseModel):
+    """Bounding box input for environment creation."""
+
+    min: List[float] = Field(description="Southwest corner [lat_min, lon_min]")
+    max: List[float] = Field(description="Northeast corner [lat_max, lon_max]")
+
+
+class RouteInput(BaseModel):
+    """Address-based route input for environment creation."""
+
+    start: str = Field(description="Start address")
+    end: str = Field(description="End address")
+    area: str = Field(description="Geographic area for geocoding")
+    transport_mode: Optional[str] = Field(
+        default="walk",
+        description="Transport mode: walk, bike, drive",
+    )
+
+
+class CreateEnvironmentRequest(BaseModel):
+    """Request to create a new environment."""
+
+    name: str = Field(
+        description="Environment name",
+        min_length=1,
+        max_length=255,
+    )
+    description: Optional[str] = Field(
+        default=None, description="Environment description"
+    )
+    environment_type: Optional[EnvironmentType] = Field(
+        default="outdoor",
+        description="Type: outdoor, indoor, underground",
+    )
+    bounds: Optional[BoundsInput] = Field(
+        default=None, description="Direct WGS84 bounding box"
+    )
+    track_file_id: Optional[str] = Field(
+        default=None, description="Uploaded track file ID"
+    )
+    route: Optional[RouteInput] = Field(
+        default=None, description="Address-based route"
+    )
+    margin: Optional[float] = Field(
+        default=None,
+        description="Margin in meters",
+        ge=0,
+        le=1000,
+    )
+    auto_create_scene: Optional[bool] = Field(
+        default=None, description="Auto-create scene"
+    )
+    scene_name: Optional[str] = Field(
+        default=None,
+        description="Name for auto-created scene",
+        max_length=255,
+    )
+    stations: Optional[Dict[str, List[float]]] = Field(
+        default=None, description="Station positions"
+    )
+    parameters: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Type-specific generation parameters",
+    )
+
+
+class UpdateEnvironmentRequest(BaseModel):
+    """Request to update an existing environment."""
+
+    name: Optional[str] = Field(
+        default=None,
+        description="New name",
+        min_length=1,
+        max_length=255,
+    )
+    description: Optional[str] = Field(
+        default=None, description="New description"
+    )
+    parameters: Optional[Dict[str, Any]] = Field(
+        default=None,
+        description="Updated generation parameters",
+    )
+
+
+class EnvironmentResponse(BaseModel):
+    """Full environment response from the API."""
+
+    environment_id: str = Field(description="Environment ID")
+    organization_id: str = Field(description="Organization ID")
+    created_by_user_id: Optional[str] = Field(
+        default=None, description="Creator user ID"
+    )
+    name: str = Field(description="Environment name")
+    description: Optional[str] = Field(default=None, description="Description")
+    environment_type: EnvironmentType = Field(description="Environment type")
+    parameters: Dict[str, Any] = Field(description="Generation parameters")
+    parameters_hash: str = Field(description="Hash of parameters")
+    bounds: Optional[Dict[str, Any]] = Field(
+        default=None, description="Environment bounds"
+    )
+    status: str = Field(description="Environment status")
+    storage_path: str = Field(description="Storage path")
+    storage_size_bytes: Optional[int] = Field(
+        default=None, description="Storage size"
+    )
+    created_at: datetime = Field(description="Creation timestamp")
+    started_at: Optional[datetime] = Field(
+        default=None, description="Start timestamp"
+    )
+    completed_at: Optional[datetime] = Field(
+        default=None, description="Completion timestamp"
+    )
+    exit_code: Optional[int] = Field(default=None, description="Exit code")
+    error_message: Optional[str] = Field(
+        default=None, description="Error message"
+    )
+    scene_count: Optional[int] = Field(
+        default=None, description="Number of scenes"
+    )
+    reused: bool = Field(
+        default=False,
+        description="Whether existing was returned",
+    )
+
+
+class CreateEnvironmentResponse(BaseModel):
+    """Response from creating an environment."""
+
+    environment: EnvironmentResponse = Field(
+        description="Created or reused environment"
+    )
+    scene: Optional[Dict[str, Any]] = Field(
+        default=None, description="Auto-created scene"
+    )
+    reused: bool = Field(
+        default=False,
+        description="Whether existing was returned",
+    )
+
+
+class EnvironmentListItem(BaseModel):
+    """Summary item for environment listings."""
+
+    environment_id: str = Field(description="Environment ID")
+    name: str = Field(description="Name")
+    description: Optional[str] = Field(default=None, description="Description")
+    environment_type: EnvironmentType = Field(description="Type")
+    status: str = Field(description="Status")
+    created_at: datetime = Field(description="Created at")
+    completed_at: Optional[datetime] = Field(
+        default=None, description="Completed at"
+    )
+    scene_count: Optional[int] = Field(default=None, description="Scene count")
+
+
+class PaginatedEnvironmentResponse(BaseModel):
+    """Paginated list of environments."""
+
+    environments: List[EnvironmentListItem] = Field(
+        description="List of environments"
+    )
+    total: int = Field(description="Total count")
+    limit: int = Field(description="Page size")
+    offset: int = Field(description="Offset")
+
+    def __repr__(self) -> str:
+        page = (self.offset // self.limit) + 1 if self.limit else 1
+        total_pages = (
+            (self.total + self.limit - 1) // self.limit if self.limit else 1
+        )
+        header = (
+            f"PaginatedEnvironmentResponse: {self.total} environments"
+            f" (page {page}/{total_pages})"
+        )
+        if not self.environments:
+            return header
+
+        rows = []
+        for env in self.environments:
+            rows.append(
+                (
+                    env.environment_id,
+                    env.status,
+                    env.name,
+                    env.environment_type,
+                    _fmt_dt(env.created_at),
+                    (
+                        str(env.scene_count)
+                        if env.scene_count is not None
+                        else "-"
+                    ),
+                )
+            )
+
+        table = _tabulate(
+            ("ID", "Status", "Name", "Type", "Created", "Scenes"),
+            rows,
+        )
+        return f"{header}\n{table}"
+
+
+class SimilarEnvironmentResponse(BaseModel):
+    """Response listing similar environments."""
+
+    similar_environments: List[EnvironmentListItem] = Field(
+        description="Similar environments"
+    )
+    parameters_hash: str = Field(description="Parameters hash")
+
+
+class EnvironmentUploadRequest(BaseModel):
+    """Request to initiate an environment file upload."""
+
+    filename: str = Field(description="Filename", min_length=1, max_length=255)
+    content_type: Optional[str] = Field(
+        default="application/json", description="MIME type"
+    )
+
+
+class EnvironmentUploadResponse(BaseModel):
+    """Response with signed upload URL for environment files."""
+
+    upload_id: str = Field(description="Upload ID")
+    upload_url: str = Field(description="Signed upload URL")
+    method: str = Field(default="PUT", description="HTTP method")
+    expires_at: datetime = Field(description="URL expiration")
+    file_id: str = Field(description="File ID for use in parameters")
+
+
+class EnvironmentUploadCompleteResponse(BaseModel):
+    """Response after completing an environment file upload."""
+
+    file_id: str = Field(description="File ID")
+    message: str = Field(
+        default="Upload completed successfully",
+        description="Status message",
+    )

waveium/models/events.py

@@ -0,0 +1,132 @@
+"""SSE event models for the Waveium SDK."""
+
+import json
+from typing import Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+
+class ExecutionProgress(BaseModel):
+    """Detailed progress information for a running execution."""
+
+    overall_percent: Optional[str] = Field(
+        default=None, description="Overall completion percentage"
+    )
+    overall_waypoints: Optional[str] = Field(
+        default=None,
+        description="Overall waypoint progress (e.g. '4586/11466')",
+    )
+    entities_completed: Optional[str] = Field(
+        default=None, description="Entity completion count (e.g. '0/1')"
+    )
+    entity: Optional[str] = Field(
+        default=None, description="Current entity identifier"
+    )
+    entity_progress: Optional[str] = Field(
+        default=None, description="Current entity progress percentage"
+    )
+    entity_waypoint: Optional[str] = Field(
+        default=None, description="Current entity waypoint progress"
+    )
+
+
+class StatusEvent(BaseModel):
+    """A status update event from an SSE stream."""
+
+    event_type: Literal["status"] = "status"
+    resource_id: str = Field(description="ID of the resource")
+    status: str = Field(description="Current resource status")
+    started_at: Optional[str] = Field(
+        default=None, description="When processing started"
+    )
+    completed_at: Optional[str] = Field(
+        default=None, description="When processing completed"
+    )
+    error_message: Optional[str] = Field(
+        default=None, description="Error message if failed"
+    )
+    progress: Optional[ExecutionProgress] = Field(
+        default=None, description="Detailed progress (executions only)"
+    )
+
+
+class TimeoutEvent(BaseModel):
+    """Server-side SSE connection timeout event.
+
+    The server sends this when its 5-minute connection limit
+    is reached. The client should reconnect immediately.
+    """
+
+    event_type: Literal["timeout"] = "timeout"
+    message: Optional[str] = Field(default=None, description="Timeout message")
+
+
+class ErrorEvent(BaseModel):
+    """An error event from an SSE stream."""
+
+    event_type: Literal["error"] = "error"
+    message: str = Field(description="Error message")
+    code: Optional[str] = Field(default=None, description="Error code")
+
+
+ServerEvent = Union[StatusEvent, TimeoutEvent, ErrorEvent]
+
+# Terminal statuses shared across resource types
+TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})
+
+# Resource ID field names in SSE payloads
+_RESOURCE_ID_FIELDS = (
+    "execution_id",
+    "environment_id",
+    "scene_id",
+)
+
+
+def parse_server_event(event_type: str, data: str) -> ServerEvent:
+    """Parse a raw SSE event into a typed ServerEvent model.
+
+    Args:
+        event_type: The SSE event type field (status, timeout, error).
+        data: The JSON-encoded event data string.
+
+    Returns:
+        A typed ServerEvent instance.
+
+    Raises:
+        ValueError: If event_type is unknown or data is invalid JSON.
+    """
+    try:
+        payload = json.loads(data)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Invalid SSE event data: {e}") from e
+
+    resource_id = ""
+    for field in _RESOURCE_ID_FIELDS:
+        if field in payload:
+            resource_id = payload[field]
+            break
+
+    if event_type == "status":
+        return StatusEvent(
+            resource_id=resource_id,
+            status=payload.get("status", "unknown"),
+            started_at=payload.get("started_at"),
+            completed_at=payload.get("completed_at"),
+            error_message=payload.get("error_message"),
+            progress=(
+                ExecutionProgress(**payload["progress"])
+                if payload.get("progress")
+                else None
+            ),
+        )
+    elif event_type == "timeout":
+        return TimeoutEvent(
+            message=payload.get("message"),
+        )
+    elif event_type == "error":
+        return ErrorEvent(
+            message=payload.get("message", "Unknown error"),
+            code=payload.get("code"),
+        )
+    else:
+        raise ValueError(f"Unknown SSE event type: {event_type}")

waveium/models/executions.py

@@ -0,0 +1,145 @@
+"""Execution models for the Waveium SDK."""
+
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from .common import _fmt_dt, _tabulate
+
+
+class CreateExecutionRequest(BaseModel):
+    """Request to create a new execution."""
+
+    name: Optional[str] = Field(
+        default=None,
+        description="Execution name",
+        max_length=255,
+    )
+    parameters: Optional[Dict[str, Any]] = Field(
+        default=None, description="Execution parameters"
+    )
+
+
+class UpdateExecutionRequest(BaseModel):
+    """Request to update an execution."""
+
+    name: str = Field(
+        description="New execution name",
+        min_length=1,
+        max_length=255,
+    )
+
+
+class ExecutionResponse(BaseModel):
+    """Full execution response from the API."""
+
+    execution_id: str = Field(description="Execution ID")
+    scene_id: str = Field(description="Scene ID")
+    organization_id: str = Field(description="Organization ID")
+    created_by_user_id: Optional[str] = Field(
+        default=None, description="Creator user ID"
+    )
+    name: Optional[str] = Field(default=None, description="Execution name")
+    execution_number: int = Field(description="Execution number")
+    parameters: Dict[str, Any] = Field(description="Execution parameters")
+    status: str = Field(description="Execution status")
+    attempt_number: Optional[int] = Field(
+        default=None, description="Attempt number"
+    )
+    storage_path: str = Field(description="Storage path")
+    storage_size_bytes: Optional[int] = Field(
+        default=None, description="Storage size"
+    )
+    cloud_run_execution_id: Optional[str] = Field(
+        default=None, description="Cloud Run execution ID"
+    )
+    created_at: datetime = Field(description="Created at")
+    started_at: Optional[datetime] = Field(
+        default=None, description="Started at"
+    )
+    completed_at: Optional[datetime] = Field(
+        default=None, description="Completed at"
+    )
+    exit_code: Optional[int] = Field(default=None, description="Exit code")
+    error_message: Optional[str] = Field(
+        default=None, description="Error message"
+    )
+    output_metadata: Optional[Dict[str, Any]] = Field(
+        default=None, description="Output metadata"
+    )
+
+
+class ExecutionListItem(BaseModel):
+    """Summary item for execution listings."""
+
+    execution_id: str = Field(description="Execution ID")
+    scene_id: str = Field(description="Scene ID")
+    name: Optional[str] = Field(default=None, description="Name")
+    execution_number: int = Field(description="Execution number")
+    status: str = Field(description="Status")
+    created_at: datetime = Field(description="Created at")
+    started_at: Optional[datetime] = Field(
+        default=None, description="Started at"
+    )
+    completed_at: Optional[datetime] = Field(
+        default=None, description="Completed at"
+    )
+    parameters: Optional[Dict[str, Any]] = Field(
+        default=None, description="Parameters"
+    )
+
+
+class PaginatedExecutionResponse(BaseModel):
+    """Paginated list of executions."""
+
+    executions: List[ExecutionListItem] = Field(
+        description="List of executions"
+    )
+    total: int = Field(description="Total count")
+    limit: int = Field(description="Page size")
+    offset: int = Field(description="Offset")
+
+    def __repr__(self) -> str:
+        page = (self.offset // self.limit) + 1 if self.limit else 1
+        total_pages = (
+            (self.total + self.limit - 1) // self.limit if self.limit else 1
+        )
+        header = (
+            f"PaginatedExecutionResponse: {self.total} executions"
+            f" (page {page}/{total_pages})"
+        )
+        if not self.executions:
+            return header
+
+        rows = []
+        for ex in self.executions:
+            rows.append(
+                (
+                    ex.execution_id,
+                    ex.status,
+                    ex.name or "-",
+                    ex.scene_id,
+                    _fmt_dt(ex.created_at),
+                )
+            )
+
+        table = _tabulate(
+            ("ID", "Status", "Name", "Scene", "Created"),
+            rows,
+        )
+        return f"{header}\n{table}"
+
+
+class ExecutionProgressResponse(BaseModel):
+    """Progress information for an execution."""
+
+    execution_id: str = Field(description="Execution ID")
+    status: str = Field(description="Execution status")
+    progress: Optional[Dict[str, Any]] = Field(
+        default=None, description="Progress data"
+    )
+    last_log_timestamp: Optional[datetime] = Field(
+        default=None, description="Last log timestamp"
+    )
+    message: Optional[str] = Field(default=None, description="Progress message")

waveium/models/files.py

@@ -0,0 +1,158 @@
+"""File models for the Waveium SDK."""
+
+from datetime import datetime
+from typing import List, Optional
+
+from pydantic import BaseModel, Field
+
+from .common import _tabulate
+
+
+def _fmt_size(n: int) -> str:
+    """Format byte count as human-readable size."""
+    if n < 1024:
+        return f"{n} B"
+    elif n < 1024 * 1024:
+        return f"{n / 1024:.1f} KB"
+    elif n < 1024 * 1024 * 1024:
+        return f"{n / (1024 * 1024):.1f} MB"
+    else:
+        return f"{n / (1024 * 1024 * 1024):.2f} GB"
+
+
+class FileInfo(BaseModel):
+    """File metadata common to all resource types."""
+
+    file_id: str = Field(description="URL-safe file identifier")
+    filename: str = Field(description="Filename")
+    subdir: str = Field(description="Subdirectory")
+    file_size_bytes: int = Field(description="File size in bytes")
+    checksum: Optional[str] = Field(default=None, description="File checksum")
+
+
+def _files_repr(
+    label: str,
+    resource_id: str,
+    total_files: int,
+    total_size_bytes: int,
+    files: List["FileInfo"],
+) -> str:
+    """Build a tabular repr for file list responses."""
+    header = (
+        f"{label}: {total_files} files, "
+        f"{_fmt_size(total_size_bytes)} ({resource_id})"
+    )
+    if not files:
+        return header
+
+    rows = []
+    for file_info in files:
+        rows.append(
+            (
+                file_info.filename,
+                file_info.subdir,
+                _fmt_size(file_info.file_size_bytes),
+            )
+        )
+
+    table = _tabulate(("Filename", "Subdir", "Size"), rows)
+    return f"{header}\n{table}"
+
+
+class EnvironmentFilesResponse(BaseModel):
+    """List of files in an environment."""
+
+    environment_id: str = Field(description="Environment ID")
+    total_files: int = Field(description="Total file count")
+    total_size_bytes: int = Field(description="Total size in bytes")
+    files: List[FileInfo] = Field(description="List of files")
+
+    def __repr__(self) -> str:
+        return _files_repr(
+            "EnvironmentFilesResponse",
+            self.environment_id,
+            self.total_files,
+            self.total_size_bytes,
+            self.files,
+        )
+
+
+class SceneFilesResponse(BaseModel):
+    """List of files in a scene."""
+
+    scene_id: str = Field(description="Scene ID")
+    total_files: int = Field(description="Total file count")
+    total_size_bytes: int = Field(description="Total size in bytes")
+    files: List[FileInfo] = Field(description="List of files")
+
+    def __repr__(self) -> str:
+        return _files_repr(
+            "SceneFilesResponse",
+            self.scene_id,
+            self.total_files,
+            self.total_size_bytes,
+            self.files,
+        )
+
+
+class ExecutionFilesResponse(BaseModel):
+    """List of files in an execution."""
+
+    execution_id: str = Field(description="Execution ID")
+    total_files: int = Field(description="Total file count")
+    total_size_bytes: int = Field(description="Total size in bytes")
+    files: List[FileInfo] = Field(description="List of files")
+
+    def __repr__(self) -> str:
+        return _files_repr(
+            "ExecutionFilesResponse",
+            self.execution_id,
+            self.total_files,
+            self.total_size_bytes,
+            self.files,
+        )
+
+
+class FileDownloadResponse(BaseModel):
+    """Signed download URL for a file."""
+
+    file_id: str = Field(description="File ID")
+    filename: str = Field(description="Filename")
+    download_url: str = Field(description="Signed download URL")
+    method: str = Field(default="GET", description="HTTP method")
+    expires_at: datetime = Field(description="URL expiration")
+    file_size_bytes: int = Field(description="File size in bytes")
+    checksum: Optional[str] = Field(default=None, description="File checksum")
+
+
+class BatchDownloadFile(BaseModel):
+    """File entry in a batch download response."""
+
+    file_id: str = Field(description="File ID")
+    filename: str = Field(description="Filename")
+    subdir: Optional[str] = Field(default=None, description="Subdirectory")
+    download_url: str = Field(description="Signed download URL")
+    method: str = Field(default="GET", description="HTTP method")
+    expires_at: datetime = Field(description="URL expiration")
+    file_size_bytes: int = Field(description="File size in bytes")
+    checksum: Optional[str] = Field(default=None, description="File checksum")
+
+
+class BatchDownloadResponse(BaseModel):
+    """Batch download response with signed URLs."""
+
+    model_config = {"extra": "allow"}
+
+    total_files: int = Field(description="Total file count")
+    total_size_bytes: int = Field(description="Total size in bytes")
+    expires_at: datetime = Field(description="URLs expiration")
+    files: List[BatchDownloadFile] = Field(description="List of download URLs")
+
+
+class ArchiveDownloadResponse(BaseModel):
+    """Response for zip archive download."""
+
+    download_url: str = Field(description="Signed GCS URL")
+    filename: str = Field(description="Archive filename")
+    size: int = Field(description="Archive size in bytes")
+    expires_at: datetime = Field(description="URL expiration")