aid-sdk 0.1.0__py3-none-any.whl

aid_sdk/__init__.py

@@ -0,0 +1,66 @@
+"""
+AID SDK - Python client for the AID Service Platform.
+
+Usage::
+
+    from aid_sdk import JobClient
+
+    with JobClient({"base_url": "http://localhost:8080"}) as client:
+        job = client.submit_job(
+            solver_type="forming",
+            files={"input": "file_001"},
+            params={
+                "material": {"materialId": "DC04", "thickness": 0.8},
+                "processType": "drawing",
+                "processParams": {"binderForce": 200, "frictionCoeff": 0.15, "punchStroke": 120},
+            },
+        )
+
+        job.on("progress", lambda data: print(f"Progress: {data['progress']}%"))
+        job.on("job_complete", lambda data: print(f"Done: {data}"))
+
+        job.wait_for_completion()
+"""
+
+from aid_sdk.client import JobClient
+from aid_sdk.errors import (
+    AIDError,
+    FileUploadException,
+    InvalidTaskStateException,
+    SolverExecutionException,
+    TaskNotFoundException,
+    UnauthorizedException,
+)
+from aid_sdk.events import EventEmitter
+from aid_sdk.file_helper import FileHelper
+from aid_sdk.job import Job
+from aid_sdk.models import FileIds, IterationInfo, JobStatus, Message, TaskHistory
+from aid_sdk.poller import MessagePoller
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Core
+    "JobClient",
+    "Job",
+    # Events & Polling
+    "EventEmitter",
+    "MessagePoller",
+    # File operations
+    "FileHelper",
+    # Models
+    "JobStatus",
+    "TaskHistory",
+    "IterationInfo",
+    "Message",
+    "FileIds",
+    # Errors
+    "AIDError",
+    "TaskNotFoundException",
+    "InvalidTaskStateException",
+    "UnauthorizedException",
+    "FileUploadException",
+    "SolverExecutionException",
+    # Meta
+    "__version__",
+]

aid_sdk/client.py

@@ -0,0 +1,166 @@
+"""
+AID SDK JobClient.
+
+Main entry point for interacting with the AID service platform.
+"""
+import asyncio
+import logging
+import os
+from typing import Any, Dict, List, Optional, Union
+
+from aid_sdk.file_helper import FileHelper
+from aid_sdk.http_client import HttpClient
+from aid_sdk.job import Job
+from aid_sdk.models import FileIds
+
+logger = logging.getLogger(__name__)
+
+# Default configuration values
+_DEFAULT_BASE_URL = "http://localhost:8080"
+_DEFAULT_API_KEY = "dev-skip-auth-local"
+_DEFAULT_TIMEOUT = 30  # seconds
+_DEFAULT_POLL_INTERVAL = 2.0  # seconds
+
+
+class JobClient:
+    """AID service client for submitting and managing simulation jobs.
+
+    Supports the context-manager protocol for automatic resource cleanup::
+
+        with JobClient(config) as client:
+            job = client.submit_job("forming", files, params)
+            job.wait_for_completion()
+
+    Args:
+        config: Optional configuration dict with keys:
+            - ``base_url`` (str): AID service base URL.
+            - ``api_key`` (str): API key for authentication.
+            - ``timeout`` (int): HTTP request timeout in seconds.
+            - ``poll_interval`` (float): Message poll interval in seconds.
+    """
+
+    def __init__(self, config: Optional[Dict[str, Any]] = None) -> None:
+        cfg = config or {}
+
+        self._base_url: str = cfg.get(
+            "base_url",
+            os.environ.get("SOLVER_API_URL", _DEFAULT_BASE_URL),
+        )
+        self._api_key: str = cfg.get(
+            "api_key",
+            os.environ.get("SOLVER_API_KEY", _DEFAULT_API_KEY),
+        )
+        self._timeout: int = int(cfg.get("timeout", _DEFAULT_TIMEOUT))
+        self._poll_interval: float = float(cfg.get("poll_interval", _DEFAULT_POLL_INTERVAL))
+
+        self._http = HttpClient(
+            base_url=self._base_url,
+            api_key=self._api_key,
+            timeout=self._timeout,
+        )
+        self._file_helper = FileHelper(self._http)
+        self._jobs: List[Job] = []
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def submit_job(
+        self,
+        solver_type: str,
+        files: Union[List[str], Dict[str, str], FileIds, None] = None,
+        params: Optional[Dict[str, Any]] = None,
+        job_name: Optional[str] = None,
+    ) -> Job:
+        """Synchronously submit a new simulation job.
+
+        Args:
+            solver_type: Solver type (forming / thermal / springback).
+            files: Input file IDs (list or grouped dict). Local paths are NOT
+                automatically uploaded; use ``FileHelper`` or pass pre-uploaded IDs.
+            params: Solver parameters.
+            job_name: Optional human-readable job name.
+
+        Returns:
+            A :class:`Job` instance with polling started.
+        """
+        body: Dict[str, Any] = {
+            "solverType": solver_type,
+            "params": params or {},
+        }
+        if files is not None:
+            body["files"] = files
+        if job_name is not None:
+            body["jobName"] = job_name
+
+        resp = self._http.post("/api/v1/submit", body)
+        data = resp.get("data", resp)
+
+        job = Job(
+            task_id=data.get("taskId", data.get("task_id", "")),
+            http_client=self._http,
+            file_helper=self._file_helper,
+            poll_interval=self._poll_interval,
+            status=data.get("status", "ACTIVE"),
+            current_iteration=data.get(
+                "currentIteration", data.get("current_iteration", 1)
+            ),
+        )
+
+        # Auto-start polling
+        job.start_polling()
+        self._jobs.append(job)
+
+        logger.info(
+            "job_submitted: task_id=%s solver_type=%s", job.task_id, solver_type
+        )
+        return job
+
+    async def submit_job_async(
+        self,
+        solver_type: str,
+        files: Union[List[str], Dict[str, str], FileIds, None] = None,
+        params: Optional[Dict[str, Any]] = None,
+        job_name: Optional[str] = None,
+    ) -> Job:
+        """Asynchronously submit a new simulation job.
+
+        Runs the synchronous submit in an executor to avoid blocking the event loop.
+
+        Args:
+            solver_type: Solver type.
+            files: Input file IDs.
+            params: Solver parameters.
+            job_name: Optional job name.
+
+        Returns:
+            A :class:`Job` instance.
+        """
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.submit_job(solver_type, files, params, job_name),
+        )
+
+    @property
+    def file_helper(self) -> FileHelper:
+        """Access the file helper for direct upload/download operations."""
+        return self._file_helper
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "JobClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Stop all job pollers and close the HTTP session."""
+        for job in self._jobs:
+            job.stop_polling()
+        self._jobs.clear()
+        self._http.close()
+        logger.info("job_client_closed")

aid_sdk/errors.py

@@ -0,0 +1,91 @@
+"""
+AID SDK Exception Classes.
+
+Defines structured error types mapping to AID service error codes.
+"""
+from typing import Optional
+
+
+class AIDError(Exception):
+    """Base exception for all AID SDK errors.
+
+    Attributes:
+        code: AID error code (e.g. TASK_3000, AUTH_6000).
+        message: Human-readable error description.
+        http_status: HTTP status code from the server response, if applicable.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        http_status: Optional[int] = None,
+    ) -> None:
+        self.code = code
+        self.message = message
+        self.http_status = http_status
+        super().__init__(f"[{code}] {message}")
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}(code={self.code!r}, "
+            f"message={self.message!r}, http_status={self.http_status!r})"
+        )
+
+
+class TaskNotFoundException(AIDError):
+    """Raised when the requested task does not exist (TASK_3000 / HTTP 404)."""
+
+    def __init__(self, message: str = "任务不存在", http_status: int = 404) -> None:
+        super().__init__(code="TASK_3000", message=message, http_status=http_status)
+
+
+class InvalidTaskStateException(AIDError):
+    """Raised when an operation is invalid for the current task state.
+
+    Covers TASK_3001 (not in continuable state) and TASK_3002 (already completed).
+    """
+
+    def __init__(
+        self,
+        code: str = "TASK_3001",
+        message: str = "任务未处于可操作状态",
+        http_status: int = 400,
+    ) -> None:
+        super().__init__(code=code, message=message, http_status=http_status)
+
+
+class UnauthorizedException(AIDError):
+    """Raised on authentication / authorization failure (AUTH_6000 / HTTP 401)."""
+
+    def __init__(
+        self,
+        code: str = "AUTH_6000",
+        message: str = "未授权访问",
+        http_status: int = 401,
+    ) -> None:
+        super().__init__(code=code, message=message, http_status=http_status)
+
+
+class FileUploadException(AIDError):
+    """Raised when a file upload operation fails (FILE_7001 / HTTP 500)."""
+
+    def __init__(
+        self,
+        message: str = "文件上传失败",
+        code: str = "FILE_7001",
+        http_status: Optional[int] = 500,
+    ) -> None:
+        super().__init__(code=code, message=message, http_status=http_status)
+
+
+class SolverExecutionException(AIDError):
+    """Raised when the solver encounters an execution error (SOLVER_2000 / HTTP 500)."""
+
+    def __init__(
+        self,
+        message: str = "求解器执行失败",
+        code: str = "SOLVER_2000",
+        http_status: Optional[int] = 500,
+    ) -> None:
+        super().__init__(code=code, message=message, http_status=http_status)

aid_sdk/events.py

@@ -0,0 +1,85 @@
+"""
+AID SDK EventEmitter.
+
+Simple publish-subscribe event system for job message callbacks.
+"""
+import logging
+import threading
+from typing import Any, Callable, Dict, List
+
+logger = logging.getLogger(__name__)
+
+# Valid event names
+VALID_EVENTS = frozenset({
+    "progress",
+    "log",
+    "iteration_complete",
+    "iteration_error",
+    "job_complete",
+})
+
+
+class EventEmitter:
+    """Thread-safe event emitter supporting on/off/emit operations."""
+
+    def __init__(self) -> None:
+        self._listeners: Dict[str, List[Callable[..., Any]]] = {}
+        self._lock = threading.Lock()
+
+    def on(self, event: str, callback: Callable[..., Any]) -> None:
+        """Register a callback for the given event.
+
+        Args:
+            event: Event name (progress, log, iteration_complete, iteration_error, job_complete).
+            callback: Function to invoke when the event fires.
+        """
+        with self._lock:
+            self._listeners.setdefault(event, []).append(callback)
+
+    def off(self, event: str, callback: Callable[..., Any]) -> None:
+        """Remove a previously registered callback.
+
+        Args:
+            event: Event name.
+            callback: The exact callable that was registered.
+        """
+        with self._lock:
+            listeners = self._listeners.get(event, [])
+            try:
+                listeners.remove(callback)
+            except ValueError:
+                pass
+
+    def emit(self, event: str, data: Any = None) -> None:
+        """Fire an event, invoking all registered listeners with the given data.
+
+        Exceptions raised by listeners are logged and swallowed to prevent
+        one bad callback from breaking the polling loop.
+
+        Args:
+            event: Event name.
+            data: Payload passed to each listener.
+        """
+        with self._lock:
+            listeners = list(self._listeners.get(event, []))
+
+        for cb in listeners:
+            try:
+                cb(data)
+            except Exception as exc:
+                logger.error(
+                    "event_callback_error: event=%s callback=%s error=%s",
+                    event, cb, exc,
+                )
+
+    def remove_all_listeners(self, event: str = None) -> None:
+        """Remove all listeners, optionally for a specific event only.
+
+        Args:
+            event: If provided, only clear listeners for this event; otherwise clear all.
+        """
+        with self._lock:
+            if event is not None:
+                self._listeners.pop(event, None)
+            else:
+                self._listeners.clear()

aid_sdk/file_helper.py

@@ -0,0 +1,175 @@
+"""
+AID SDK File Helper.
+
+Handles file upload and download through OSS presigned URLs obtained from the AID service.
+"""
+import logging
+import os
+import uuid
+from typing import Any, Dict, List, Optional, Union
+
+import requests
+
+from aid_sdk.errors import FileUploadException
+from aid_sdk.http_client import HttpClient
+
+logger = logging.getLogger(__name__)
+
+
+class FileHelper:
+    """Utility for uploading input files and downloading result files via OSS."""
+
+    def __init__(self, http_client: HttpClient) -> None:
+        self._http = http_client
+
+    # ------------------------------------------------------------------
+    # Upload
+    # ------------------------------------------------------------------
+
+    def get_upload_url(self, file_key: str, expires: int = 3600) -> dict:
+        """Request a presigned upload URL from the AID service.
+
+        Args:
+            file_key: The OSS object key for the file.
+            expires: URL validity in seconds (default 3600).
+
+        Returns:
+            Dict with ``upload_url``, ``file_key``, ``expires_at``.
+        """
+        resp = self._http.post("/api/v1/files/upload_url", {
+            "file_key": file_key,
+            "expires": expires,
+        })
+        return resp.get("data", resp)
+
+    def upload_file(self, local_path: str, file_key: Optional[str] = None, expires: int = 3600) -> str:
+        """Upload a local file to OSS using a presigned URL.
+
+        Args:
+            local_path: Path to the local file.
+            file_key: OSS object key. If not provided, derived from the filename with a UUID prefix.
+            expires: URL validity in seconds.
+
+        Returns:
+            The ``file_key`` of the uploaded file.
+
+        Raises:
+            FileUploadException: On any upload failure.
+        """
+        if not os.path.isfile(local_path):
+            raise FileUploadException(message=f"文件不存在: {local_path}")
+
+        if file_key is None:
+            filename = os.path.basename(local_path)
+            file_key = f"uploads/{uuid.uuid4().hex[:8]}/{filename}"
+
+        try:
+            info = self.get_upload_url(file_key, expires)
+        except Exception as exc:
+            raise FileUploadException(message=f"获取上传 URL 失败: {exc}") from exc
+
+        upload_url = info.get("upload_url", "")
+        if not upload_url:
+            raise FileUploadException(message="服务端未返回有效的 upload_url")
+
+        try:
+            with open(local_path, "rb") as fh:
+                put_resp = requests.put(upload_url, data=fh, timeout=300)
+            if put_resp.status_code not in (200, 201, 204):
+                raise FileUploadException(
+                    message=f"OSS 上传失败: HTTP {put_resp.status_code}"
+                )
+        except requests.RequestException as exc:
+            raise FileUploadException(message=f"OSS 上传网络错误: {exc}") from exc
+
+        logger.info("file_uploaded: local=%s file_key=%s", local_path, file_key)
+        return file_key
+
+    def upload_files(
+        self,
+        files: Union[List[str], Dict[str, str]],
+        expires: int = 3600,
+    ) -> Union[List[str], Dict[str, str]]:
+        """Batch upload multiple files.
+
+        Args:
+            files:
+                - A list of local paths → returns a list of file_keys.
+                - A dict mapping logical names to local paths → returns a dict mapping names to file_keys.
+            expires: URL validity in seconds.
+
+        Returns:
+            Matching structure of file_keys.
+        """
+        if isinstance(files, dict):
+            result: Dict[str, str] = {}
+            for name, path in files.items():
+                result[name] = self.upload_file(path, expires=expires)
+            return result
+        else:
+            return [self.upload_file(p, expires=expires) for p in files]
+
+    # ------------------------------------------------------------------
+    # Download
+    # ------------------------------------------------------------------
+
+    def get_download_url(self, file_key: str, expires: int = 3600) -> dict:
+        """Request a presigned download URL from the AID service.
+
+        Args:
+            file_key: The OSS object key.
+            expires: URL validity in seconds.
+
+        Returns:
+            Dict with ``download_url``, ``expires_at``.
+        """
+        resp = self._http.post("/api/v1/files/download_url", {
+            "file_key": file_key,
+            "expires": expires,
+        })
+        return resp.get("data", resp)
+
+    def download_file(
+        self,
+        file_key: str,
+        dest_dir: str,
+        filename: Optional[str] = None,
+        expires: int = 3600,
+    ) -> str:
+        """Download a file from OSS to a local directory.
+
+        Args:
+            file_key: OSS object key.
+            dest_dir: Local directory to save the file.
+            filename: Local filename override; defaults to the last segment of ``file_key``.
+            expires: URL validity in seconds.
+
+        Returns:
+            Full path to the downloaded local file.
+        """
+        info = self.get_download_url(file_key, expires)
+        download_url = info.get("download_url", "")
+        if not download_url:
+            raise FileUploadException(
+                code="FILE_7002", message="服务端未返回有效的 download_url"
+            )
+
+        if filename is None:
+            filename = file_key.rsplit("/", 1)[-1] or "downloaded_file"
+
+        os.makedirs(dest_dir, exist_ok=True)
+        local_path = os.path.join(dest_dir, filename)
+
+        try:
+            with requests.get(download_url, stream=True, timeout=300) as r:
+                r.raise_for_status()
+                with open(local_path, "wb") as fh:
+                    for chunk in r.iter_content(chunk_size=8192):
+                        fh.write(chunk)
+        except requests.RequestException as exc:
+            raise FileUploadException(
+                code="FILE_7002", message=f"OSS 下载失败: {exc}"
+            ) from exc
+
+        logger.info("file_downloaded: file_key=%s local=%s", file_key, local_path)
+        return local_path

aid_sdk/http_client.py

@@ -0,0 +1,157 @@
+"""
+AID SDK HTTP Client.
+
+Encapsulates HTTP requests with retry logic and unified error handling.
+"""
+import logging
+import time
+from typing import Any, Dict, Optional
+
+import requests
+
+from aid_sdk.errors import (
+    AIDError,
+    InvalidTaskStateException,
+    TaskNotFoundException,
+    UnauthorizedException,
+)
+
+logger = logging.getLogger(__name__)
+
+# Default retry configuration
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_RETRY_BASE_DELAY = 1.0  # seconds
+
+
+def _map_error(status_code: int, detail: dict) -> AIDError:
+    """Map an HTTP error response to the appropriate SDK exception."""
+    code = detail.get("code", "SYSTEM_9000") if isinstance(detail, dict) else "SYSTEM_9000"
+    message = detail.get("message", str(detail)) if isinstance(detail, dict) else str(detail)
+
+    if code == "TASK_3000" or (status_code == 404 and code.startswith("TASK")):
+        return TaskNotFoundException(message=message, http_status=status_code)
+
+    if code in ("TASK_3001", "TASK_3002", "TASK_3003"):
+        return InvalidTaskStateException(code=code, message=message, http_status=status_code)
+
+    if status_code == 401 or code.startswith("AUTH_6"):
+        return UnauthorizedException(code=code, message=message, http_status=status_code)
+
+    return AIDError(code=code, message=message, http_status=status_code)
+
+
+class HttpClient:
+    """HTTP client wrapper with retry logic and AID-specific error handling."""
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str,
+        timeout: int = 30,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        })
+        if api_key:
+            self._session.headers["Authorization"] = f"Bearer {api_key}"
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> dict:
+        """Send a GET request and return the parsed response body."""
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, json_body: Optional[dict] = None) -> dict:
+        """Send a POST request and return the parsed response body."""
+        return self._request("POST", path, json_body=json_body)
+
+    def delete(self, path: str) -> dict:
+        """Send a DELETE request and return the parsed response body."""
+        return self._request("DELETE", path)
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        params: Optional[Dict[str, Any]] = None,
+        json_body: Optional[dict] = None,
+    ) -> dict:
+        """Execute an HTTP request with exponential-backoff retry on 5xx errors."""
+        url = f"{self._base_url}{path}"
+        last_error: Optional[Exception] = None
+
+        for attempt in range(self._max_retries):
+            try:
+                resp = self._session.request(
+                    method,
+                    url,
+                    params=params,
+                    json=json_body,
+                    timeout=self._timeout,
+                )
+
+                if resp.status_code >= 500:
+                    # Server error → retry with exponential backoff
+                    last_error = Exception(
+                        f"HTTP {resp.status_code}: {resp.text[:200]}"
+                    )
+                    logger.warning(
+                        "http_retry: attempt=%d/%d status=%d url=%s",
+                        attempt + 1, self._max_retries, resp.status_code, url,
+                    )
+                else:
+                    return self._handle_response(resp)
+
+            except requests.ConnectionError as exc:
+                last_error = exc
+                logger.warning(
+                    "http_retry: attempt=%d/%d error=%s url=%s",
+                    attempt + 1, self._max_retries, exc, url,
+                )
+            except requests.Timeout as exc:
+                last_error = exc
+                logger.warning(
+                    "http_retry: attempt=%d/%d timeout url=%s",
+                    attempt + 1, self._max_retries, url,
+                )
+
+            # Exponential backoff before next attempt
+            if attempt < self._max_retries - 1:
+                delay = DEFAULT_RETRY_BASE_DELAY * (2 ** attempt)
+                time.sleep(delay)
+
+        # All retries exhausted
+        raise AIDError(
+            code="SYSTEM_9001",
+            message=f"请求失败，已重试 {self._max_retries} 次: {last_error}",
+        )
+
+    def _handle_response(self, resp: requests.Response) -> dict:
+        """Parse response JSON; raise SDK exceptions on 4xx errors."""
+        try:
+            body = resp.json()
+        except ValueError:
+            body = {}
+
+        if resp.status_code >= 400:
+            detail = body.get("detail", body)
+            raise _map_error(resp.status_code, detail)
+
+        return body

aid_sdk/job.py

@@ -0,0 +1,235 @@
+"""
+AID SDK Job.
+
+Represents a submitted simulation job with event-driven messaging.
+"""
+import logging
+from typing import Any, Callable, Dict, List, Optional, Union
+
+from aid_sdk.events import EventEmitter
+from aid_sdk.file_helper import FileHelper
+from aid_sdk.http_client import HttpClient
+from aid_sdk.models import FileIds, JobStatus, TaskHistory
+from aid_sdk.poller import MessagePoller
+
+logger = logging.getLogger(__name__)
+
+
+class Job:
+    """Represents a running or completed AID simulation job.
+
+    A Job instance is returned by ``JobClient.submit_job``. It provides methods
+    for continuing, completing, and cancelling the job, as well as event-driven
+    message polling.
+
+    Attributes:
+        task_id: Unique task identifier assigned by the server.
+        status: Current lifecycle status.
+        current_iteration: The latest iteration number.
+    """
+
+    def __init__(
+        self,
+        task_id: str,
+        http_client: HttpClient,
+        file_helper: FileHelper,
+        poll_interval: float = 2.0,
+        status: str = "ACTIVE",
+        current_iteration: int = 1,
+    ) -> None:
+        self.task_id: str = task_id
+        self.status: str = status
+        self.current_iteration: int = current_iteration
+
+        self._http = http_client
+        self._file_helper = file_helper
+        self._poll_interval = poll_interval
+
+        self._emitter = EventEmitter()
+        self._poller: Optional[MessagePoller] = None
+
+    # ------------------------------------------------------------------
+    # Task operations
+    # ------------------------------------------------------------------
+
+    def continue_job(
+        self,
+        files: Union[List[str], Dict[str, str], FileIds, None] = None,
+        params: Optional[Dict[str, Any]] = None,
+    ) -> "Job":
+        """Synchronously continue this job with a new iteration.
+
+        Args:
+            files: New input file IDs (list or grouped dict). If local paths are
+                provided they will be uploaded to OSS first.
+            params: New solver parameters for this iteration.
+
+        Returns:
+            This Job instance (updated in place).
+        """
+        body: Dict[str, Any] = {
+            "taskId": self.task_id,
+            "params": params or {},
+        }
+        if files is not None:
+            body["files"] = files
+
+        resp = self._http.post("/api/v1/continue", body)
+        data = resp.get("data", resp)
+
+        self.status = data.get("status", self.status)
+        self.current_iteration = data.get(
+            "currentIteration", data.get("current_iteration", self.current_iteration + 1)
+        )
+
+        # Ensure polling is running for the new iteration
+        if self._poller is not None and not self._poller.is_running:
+            self._poller.start()
+
+        return self
+
+    def complete_job(self) -> bool:
+        """Mark this job as completed.
+
+        Returns:
+            True on success.
+        """
+        resp = self._http.post(f"/api/v1/tasks/{self.task_id}/complete")
+        data = resp.get("data", resp)
+        self.status = data.get("status", "COMPLETED")
+        self.stop_polling()
+        return True
+
+    def cancel(self) -> bool:
+        """Cancel this job.
+
+        Returns:
+            True on success.
+        """
+        resp = self._http.delete(f"/api/v1/tasks/{self.task_id}/cancel")
+        data = resp.get("data", resp)
+        self.status = data.get("status", "CANCELLED")
+        self.stop_polling()
+        return True
+
+    # ------------------------------------------------------------------
+    # Queries
+    # ------------------------------------------------------------------
+
+    def get_status(self) -> dict:
+        """Query the current task status from the server.
+
+        Returns:
+            Raw status dict from the API.
+        """
+        resp = self._http.get(f"/api/v1/tasks/{self.task_id}/status")
+        data = resp.get("data", resp)
+        # Sync local state
+        self.status = data.get("status", self.status)
+        self.current_iteration = data.get(
+            "currentIteration", data.get("current_iteration", self.current_iteration)
+        )
+        return data
+
+    def get_history(self) -> dict:
+        """Fetch the full task history including all iterations.
+
+        Returns:
+            Raw history dict from the API.
+        """
+        resp = self._http.get(f"/api/v1/tasks/{self.task_id}/history")
+        return resp.get("data", resp)
+
+    def get_result_url(
+        self,
+        iteration: Optional[int] = None,
+        file_key: Optional[str] = None,
+    ) -> Union[str, dict]:
+        """Get result file download URL(s).
+
+        Args:
+            iteration: Iteration number. Defaults to the latest.
+            file_key: Specific file key. If omitted, returns all files.
+
+        Returns:
+            A single URL string if ``file_key`` is given, otherwise a dict
+            mapping file keys to URLs.
+        """
+        params: Dict[str, Any] = {}
+        if iteration is not None:
+            params["iteration"] = iteration
+        if file_key is not None:
+            params["fileKey"] = file_key
+
+        resp = self._http.get(
+            f"/api/v1/tasks/{self.task_id}/result",
+            params=params if params else None,
+        )
+        return resp.get("data", resp)
+
+    # ------------------------------------------------------------------
+    # Event system
+    # ------------------------------------------------------------------
+
+    def on(self, event: str, callback: Callable[..., Any]) -> None:
+        """Register an event callback.
+
+        Supported events: ``progress``, ``log``, ``iteration_complete``,
+        ``iteration_error``, ``job_complete``.
+
+        Args:
+            event: Event name.
+            callback: Function invoked with the event payload dict.
+        """
+        self._emitter.on(event, callback)
+
+    def off(self, event: str, callback: Callable[..., Any]) -> None:
+        """Remove a previously registered event callback.
+
+        Args:
+            event: Event name.
+            callback: The exact callable to remove.
+        """
+        self._emitter.off(event, callback)
+
+    # ------------------------------------------------------------------
+    # Polling
+    # ------------------------------------------------------------------
+
+    def start_polling(self) -> None:
+        """Start the background message poller (daemon thread)."""
+        if self._poller is None:
+            self._poller = MessagePoller(
+                http_client=self._http,
+                task_id=self.task_id,
+                emitter=self._emitter,
+                poll_interval=self._poll_interval,
+            )
+        self._poller.start()
+
+    def stop_polling(self) -> None:
+        """Stop the background message poller."""
+        if self._poller is not None:
+            self._poller.stop()
+
+    def wait_for_completion(self, timeout: Optional[float] = None) -> dict:
+        """Block until the job completes or the timeout expires.
+
+        This is a convenience method that starts polling (if not already running)
+        and waits for the ``job_complete`` event.
+
+        Args:
+            timeout: Maximum seconds to wait. ``None`` means wait indefinitely.
+
+        Returns:
+            The completion payload dict, or an empty dict on timeout.
+        """
+        if self._poller is None:
+            self.start_polling()
+        elif not self._poller.is_running:
+            self.start_polling()
+
+        completed = self._poller.completed_event.wait(timeout=timeout)
+        if completed and self._poller.completion_data:
+            return self._poller.completion_data
+        return {}

aid_sdk/models.py

@@ -0,0 +1,109 @@
+"""
+AID SDK Data Models.
+
+Lightweight dataclass definitions for SDK request/response structures.
+"""
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+
+# Type alias for file identifiers: list of IDs or grouped dict
+FileIds = Union[List[str], Dict[str, Any]]
+
+
+@dataclass
+class JobStatus:
+    """Snapshot of a job's current state."""
+    task_id: str
+    status: str  # ACTIVE | RUNNING | WAITING_USER | FAILED | COMPLETED | CANCELLED
+    current_iteration: int = 0
+    total_iterations: int = 0
+    progress: int = 0
+    stage: str = ""
+    created_at: Optional[int] = None
+    updated_at: Optional[int] = None
+
+    @classmethod
+    def from_response(cls, data: dict) -> "JobStatus":
+        """Build from API response dict (camelCase keys)."""
+        return cls(
+            task_id=data.get("taskId", data.get("task_id", "")),
+            status=data.get("status", "ACTIVE"),
+            current_iteration=data.get("currentIteration", data.get("current_iteration", 0)),
+            total_iterations=data.get("totalIterations", data.get("total_iterations", 0)),
+            progress=data.get("progress", 0),
+            stage=data.get("stage", ""),
+            created_at=data.get("createdAt", data.get("created_at")),
+            updated_at=data.get("updatedAt", data.get("updated_at")),
+        )
+
+
+@dataclass
+class IterationInfo:
+    """Per-iteration detail from task history."""
+    iteration_num: int
+    process_type: str = ""
+    status: str = "PENDING"
+    input_file_ids: FileIds = field(default_factory=dict)
+    result_file_ids: FileIds = field(default_factory=dict)
+    params: Dict[str, Any] = field(default_factory=dict)
+    progress: int = 0
+    stage: str = ""
+    started_at: Optional[int] = None
+    finished_at: Optional[int] = None
+
+
+@dataclass
+class TaskHistory:
+    """Full task history including all iterations."""
+    task_id: str
+    status: str
+    total_iterations: int
+    iterations: List[IterationInfo] = field(default_factory=list)
+
+    @classmethod
+    def from_response(cls, data: dict) -> "TaskHistory":
+        """Build from API response dict."""
+        iterations = []
+        for it in data.get("iterations", []):
+            iterations.append(
+                IterationInfo(
+                    iteration_num=it.get("iterationNum", it.get("iteration_num", 0)),
+                    process_type=it.get("processType", it.get("process_type", "")),
+                    status=it.get("status", "PENDING"),
+                    input_file_ids=it.get("inputFileIds", it.get("input_file_ids", {})),
+                    result_file_ids=it.get("resultFileIds", it.get("result_file_ids", {})),
+                    params=it.get("params", {}),
+                    progress=it.get("progress", 0),
+                    stage=it.get("stage", ""),
+                    started_at=it.get("startedAt", it.get("started_at")),
+                    finished_at=it.get("finishedAt", it.get("finished_at")),
+                )
+            )
+        return cls(
+            task_id=data.get("taskId", data.get("task_id", "")),
+            status=data.get("status", "ACTIVE"),
+            total_iterations=data.get("totalIterations", data.get("total_iterations", 0)),
+            iterations=iterations,
+        )
+
+
+@dataclass
+class Message:
+    """A single message from the polling stream."""
+    seq: int
+    type: str  # progress | log | status
+    data: Dict[str, Any]
+    task_id: str = ""
+    timestamp: Optional[int] = None
+
+    @classmethod
+    def from_response(cls, raw: dict) -> "Message":
+        """Build from polling response dict."""
+        return cls(
+            seq=raw.get("seq", 0),
+            type=raw.get("type", ""),
+            data=raw.get("data", {}),
+            task_id=raw.get("taskId", raw.get("task_id", "")),
+            timestamp=raw.get("timestamp"),
+        )

aid_sdk/poller.py

@@ -0,0 +1,183 @@
+"""
+AID SDK Message Poller.
+
+Background daemon thread that periodically fetches messages from the AID service
+and dispatches them through the EventEmitter.
+"""
+import logging
+import threading
+import time
+from typing import Any, Callable, Optional
+
+from aid_sdk.events import EventEmitter
+from aid_sdk.http_client import HttpClient
+from aid_sdk.models import Message
+
+logger = logging.getLogger(__name__)
+
+
+class MessagePoller:
+    """Background daemon thread that polls ``GET /api/v1/tasks/{task_id}/messages``
+    and dispatches events.
+
+    Message deduplication is based on the ``seq`` field.
+    """
+
+    def __init__(
+        self,
+        http_client: HttpClient,
+        task_id: str,
+        emitter: EventEmitter,
+        poll_interval: float = 2.0,
+    ) -> None:
+        self._http = http_client
+        self._task_id = task_id
+        self._emitter = emitter
+        self._poll_interval = poll_interval
+
+        self._last_seq: int = 0
+        self._running = False
+        self._thread: Optional[threading.Thread] = None
+
+        # Completion signal for wait_for_completion
+        self._completed = threading.Event()
+        self._completion_data: Optional[dict] = None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    @property
+    def is_running(self) -> bool:
+        """Whether the poller thread is currently active."""
+        return self._running
+
+    @property
+    def completed_event(self) -> threading.Event:
+        """Threading event that is set when a job_complete message is received."""
+        return self._completed
+
+    @property
+    def completion_data(self) -> Optional[dict]:
+        """The payload of the job_complete message, once available."""
+        return self._completion_data
+
+    def start(self) -> None:
+        """Start the background polling daemon thread."""
+        if self._running:
+            return
+        self._running = True
+        self._thread = threading.Thread(
+            target=self._poll_loop,
+            name=f"aid-poller-{self._task_id}",
+            daemon=True,
+        )
+        self._thread.start()
+        logger.info("poller_started: task_id=%s interval=%.1fs", self._task_id, self._poll_interval)
+
+    def stop(self) -> None:
+        """Signal the poller to stop and wait for the thread to exit."""
+        self._running = False
+        if self._thread is not None:
+            self._thread.join(timeout=self._poll_interval * 2)
+            self._thread = None
+        logger.info("poller_stopped: task_id=%s", self._task_id)
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _poll_loop(self) -> None:
+        """Main polling loop executed in the daemon thread."""
+        while self._running:
+            try:
+                self._fetch_and_dispatch()
+            except Exception as exc:
+                logger.warning(
+                    "poller_error: task_id=%s error=%s", self._task_id, exc
+                )
+
+            # Sleep in small increments so stop() is responsive
+            elapsed = 0.0
+            while elapsed < self._poll_interval and self._running:
+                time.sleep(min(0.5, self._poll_interval - elapsed))
+                elapsed += 0.5
+
+    def _fetch_and_dispatch(self) -> None:
+        """Fetch new messages and emit corresponding events."""
+        try:
+            resp = self._http.get(
+                f"/api/v1/tasks/{self._task_id}/messages",
+                params={"since": self._last_seq, "limit": 100},
+            )
+        except Exception:
+            # Messages endpoint may not be available yet; degrade silently
+            return
+
+        data = resp.get("data", resp)
+        messages_raw = data if isinstance(data, list) else data.get("messages", [])
+
+        for raw in messages_raw:
+            msg = Message.from_response(raw)
+
+            # Dedup: skip messages we've already processed
+            if msg.seq <= self._last_seq:
+                continue
+            self._last_seq = msg.seq
+
+            self._dispatch_message(msg)
+
+    def _dispatch_message(self, msg: Message) -> None:
+        """Map a message to an event and emit it."""
+        if msg.type == "progress":
+            self._emitter.emit("progress", {
+                "iteration_num": msg.data.get("iterationNum", msg.data.get("iteration_num")),
+                "progress": msg.data.get("progress", 0),
+                "stage": msg.data.get("stage", ""),
+                "step": msg.data.get("step"),
+                "total_steps": msg.data.get("totalSteps", msg.data.get("total_steps")),
+            })
+
+        elif msg.type == "log":
+            self._emitter.emit("log", {
+                "iteration_num": msg.data.get("iterationNum", msg.data.get("iteration_num")),
+                "level": msg.data.get("level", "INFO"),
+                "message": msg.data.get("message", ""),
+                "timestamp": msg.timestamp,
+            })
+
+        elif msg.type == "status":
+            status = msg.data.get("status", "")
+            if status == "SUCCESS":
+                self._emitter.emit("iteration_complete", {
+                    "iteration_num": msg.data.get("iterationNum", msg.data.get("iteration_num")),
+                    "result_file_ids": msg.data.get("resultFileIds", msg.data.get("result_file_ids", {})),
+                    "total_time": msg.data.get("totalTime", msg.data.get("total_time")),
+                    "summary": msg.data.get("summary"),
+                })
+            elif status == "FAILED":
+                self._emitter.emit("iteration_error", {
+                    "iteration_num": msg.data.get("iterationNum", msg.data.get("iteration_num")),
+                    "code": msg.data.get("errorCode", msg.data.get("error_code", "")),
+                    "message": msg.data.get("errorMsg", msg.data.get("error_msg", "")),
+                    "details": msg.data.get("details"),
+                })
+            elif status == "COMPLETED":
+                payload = {
+                    "task_id": self._task_id,
+                    "total_iterations": msg.data.get("totalIterations", msg.data.get("total_iterations")),
+                }
+                self._emitter.emit("job_complete", payload)
+                self._completion_data = payload
+                self._completed.set()
+                self._running = False
+
+        elif msg.type == "job_complete":
+            payload = {
+                "task_id": self._task_id,
+                "total_iterations": msg.data.get("totalIterations", msg.data.get("total_iterations")),
+            }
+            self._emitter.emit("job_complete", payload)
+            self._completion_data = payload
+            self._completed.set()
+            self._running = False

aid_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: aid-sdk
+Version: 0.1.0
+Summary: Python SDK for AID Service Platform - CAE Stamping Simulation Task Management
+Requires-Python: >=3.8
+Requires-Dist: requests>=2.28.0
+Requires-Dist: typing-extensions>=4.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.0; extra == "dev"
+Dynamic: requires-python

aid_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+aid_sdk/__init__.py,sha256=hVg9kU0YWtZzbMzrw9ByhmqTPhKradeFd_HQxE5J_Yc,1740
+aid_sdk/client.py,sha256=hA95qWFhbhC5FvaDkd4c6C4xzS9ZhIoR6OVHr7hELLQ,5513
+aid_sdk/config_loader.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aid_sdk/errors.py,sha256=5nZujHNHPPJ4HIebQZAnhuI12VdTxnVuldI017tiPUQ,2836
+aid_sdk/events.py,sha256=jlAVu23LuO2GQoIDIw3v_QteJ5-oQMXKW4C_bkp7cho,2662
+aid_sdk/file_helper.py,sha256=W53w3o1ySmsqGX_0gSTSLm_EaRbJZlG0eIjMtmUu7ho,6285
+aid_sdk/http_client.py,sha256=i9XPWb_ySSyXPub4LYMr2kdRkZ7JfcNgxPkilulVbMY,5605
+aid_sdk/job.py,sha256=C3FUX5XxB0adkigtmKOC7sVgJc1bQTY4ehF6OxhljAE,7893
+aid_sdk/models.py,sha256=vkczPO7NgVHklJcrzaV571brY49fAFrCDrntGIn4UbE,3960
+aid_sdk/poller.py,sha256=wE2DgftH0NnrBIm003m6VhOcBACkDhMSEBHsRjhKCLE,7075
+aid_sdk/sls_poller.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aid_sdk-0.1.0.dist-info/METADATA,sha256=ifU_AovmpHabTfGSOGk-sev0e-UFO4qz40up4WoKx1A,380
+aid_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+aid_sdk-0.1.0.dist-info/top_level.txt,sha256=8mBla07brDr9b7R1BSZmfGSvo0tpd3owIsfr7ImmB3s,8
+aid_sdk-0.1.0.dist-info/RECORD,,

aid_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

aid_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+aid_sdk