ace-engine-sdk 0.2.0__py3-none-any.whl

ace_engine/__init__.py

@@ -0,0 +1,6 @@
+from .client import AceClient
+from .results import AceError, BinaryResult
+
+Client = AceClient
+__version__ = "0.2.0"
+__all__ = ["AceClient", "Client", "AceError", "BinaryResult", "__version__"]

ace_engine/client.py

@@ -0,0 +1,676 @@
+"""Public ACE APIs: private assets, billed inferences, IQA jobs and file APIs."""
+
+import mimetypes
+import re
+import time
+import uuid
+from pathlib import Path
+from urllib.parse import urlsplit
+
+import requests
+from requests.adapters import HTTPAdapter
+
+from .results import AceError, BinaryResult
+
+
+class AceClient:
+    """Synchronous client. Methods return server envelopes unless strict mode is enabled.
+
+    Instances own a Session and should not be shared between concurrent threads.
+    No request is automatically retried, and redirects never forward credentials.
+    """
+
+    MODELS = frozenset(("mnet", "icaa17k"))
+    IQA_METRICS = frozenset(
+        (
+            "sharpness",
+            "color_accuracy",
+            "saturation",
+            "exposure",
+            "contrast",
+            "noise",
+            "holistic",
+            "overall_iqa",
+        )
+    )
+    DEFAULT_IQA_METRICS = ("sharpness", "exposure", "contrast", "noise")
+    PENDING_TASKS = frozenset(("QUEUED", "RUNNING", "CANCEL_REQUESTED"))
+    TERMINAL_TASKS = frozenset(("SUCCEEDED", "PARTIAL", "FAILED", "CANCELLED"))
+
+    def __init__(
+        self,
+        base_url="https://ace-aesthetics.cn",
+        access_key_id=None,
+        sign=None,
+        timeout=120,
+        *,
+        access_key_secret=None,
+        token=None,
+        api_prefix="/ibt",
+        raise_for_errors=False,
+    ):
+        if not isinstance(base_url, str):
+            raise ValueError("base_url must be an HTTP(S) URL")
+        parsed = urlsplit(base_url)
+        if (
+            parsed.scheme not in ("https", "http")
+            or not parsed.hostname
+            or parsed.username
+            or parsed.password
+            or parsed.query
+            or parsed.fragment
+            or any(c.isspace() for c in base_url)
+        ):
+            raise ValueError("base_url must be HTTP(S), without credentials, query or fragment")
+        if sign is not None and access_key_secret is not None and sign != access_key_secret:
+            raise ValueError("sign and access_key_secret must match when both are supplied")
+        secret = access_key_secret if access_key_secret is not None else sign
+        if token is not None and (access_key_id is not None or secret is not None):
+            raise ValueError("Use either API-Key credentials or a user token, not both")
+        credentials = (token,) if token is not None else (access_key_id, secret)
+        if any(
+            not isinstance(value, str) or not value.strip() or "\r" in value or "\n" in value
+            for value in credentials
+        ):
+            raise ValueError("Provide a complete API-Key pair or a user token")
+        if not isinstance(api_prefix, str) or (
+            api_prefix and not re.fullmatch(r"(?:/[A-Za-z0-9_-]+)+/?", api_prefix)
+        ):
+            raise ValueError("api_prefix must be empty or a root-relative path")
+        if not self._positive(timeout):
+            raise ValueError("timeout must be a positive number of seconds")
+        self.base_url = base_url.rstrip("/")
+        prefix = api_prefix.rstrip("/")
+        self.api_url = (
+            self.base_url
+            if not prefix or self.base_url.endswith(prefix)
+            else self.base_url + prefix
+        )
+        self.access_key_id, self.sign, self.token = access_key_id, secret, token
+        self.timeout = timeout
+        self.raise_for_errors = raise_for_errors
+        self.session = requests.Session()
+        self.session.mount("https://", HTTPAdapter(max_retries=0))
+        self.session.mount("http://", HTTPAdapter(max_retries=0))
+        self._closed = False
+
+    @staticmethod
+    def _positive(value):
+        return (
+            isinstance(value, (int, float))
+            and not isinstance(value, bool)
+            and 0 < value < float("inf")
+        )
+
+    @staticmethod
+    def new_idempotency_key():
+        return str(uuid.uuid4())
+
+    @staticmethod
+    def _ok(value):
+        return (
+            isinstance(value, dict)
+            and str(value.get("code")) == "200"
+            and value.get("success") is not False
+        )
+
+    def _redact(self, value):
+        if isinstance(value, str):
+            for credential in (self.sign, self.token, self.access_key_id):
+                if credential:
+                    value = value.replace(credential, "[REDACTED]")
+            return value
+        if isinstance(value, list):
+            return [self._redact(item) for item in value]
+        if isinstance(value, dict):
+            return {key: self._redact(item) for key, item in value.items()}
+        return value
+
+    def _finish(self, value):
+        if self._ok(value):
+            return value
+        value = self._redact(value)
+        if self.raise_for_errors:
+            raise AceError(value)
+        return value
+
+    def _failure(self, code, message, *, context=None, error_type="client", **extra):
+        value = {
+            "code": str(code),
+            "success": False,
+            "message": message,
+            "data": None,
+            "errorType": error_type,
+            **extra,
+        }
+        if context:
+            value["meta"] = dict(context)
+        return self._finish(value)
+
+    def _key(self, value):
+        key = self.new_idempotency_key() if value is None else value
+        if not isinstance(key, str) or not re.fullmatch(r"[A-Za-z0-9._:-]{1,128}", key):
+            raise ValueError(
+                "idempotency_key must contain 1-128 letters, digits, '.', '_', ':' or '-'"
+            )
+        return key
+
+    @staticmethod
+    def _identifier(value):
+        if not isinstance(value, str) or str(uuid.UUID(value)) != value:
+            raise ValueError("Expected a canonical UUID")
+        return value
+
+    def _request(
+        self,
+        method,
+        path,
+        *,
+        data=None,
+        files=None,
+        json=None,
+        context=None,
+        binary=None,
+        legacy=False,
+        timeout=None,
+    ):
+        if self._closed:
+            return self._failure(400, "Client is closed", context=context)
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = "Bearer " + self.token
+        elif not legacy:
+            headers.update({"X-API-Key-Id": self.access_key_id, "X-API-Key-Secret": self.sign})
+        if context and context.get("idempotencyKey"):
+            headers["Idempotency-Key"] = context["idempotencyKey"]
+        if binary:
+            headers["Accept"] = binary + "/*, application/json"
+        try:
+            response = self.session.request(
+                method,
+                self.api_url + path,
+                headers=headers,
+                data=data,
+                files=files,
+                json=json,
+                timeout=self.timeout if timeout is None else timeout,
+                allow_redirects=False,
+            )
+        except requests.RequestException as error:
+            return self._failure(
+                500,
+                "Network request failed ({})".format(type(error).__name__),
+                context=context,
+                error_type="network",
+                retryable=method == "GET" or bool(context and context.get("idempotencyKey")),
+                outcomeUnknown=method != "GET",
+                httpStatus=None,
+            )
+        try:
+            status = response.status_code
+            content_type = response.headers.get("Content-Type", "").split(";", 1)[0].lower()
+            request_id = response.headers.get("X-Request-Id")
+            if (
+                binary
+                and 200 <= status < 300
+                and (
+                    content_type.startswith(binary + "/")
+                    or content_type == "application/octet-stream"
+                )
+            ):
+                return BinaryResult(response.content, content_type, request_id)
+            try:
+                value = response.json()
+            except ValueError:
+                return self._failure(
+                    status if status >= 300 else 502,
+                    "Unexpected non-JSON response (HTTP {})".format(status),
+                    context=context,
+                    error_type="protocol",
+                    httpStatus=status,
+                    retryable=status in (429, 502, 503, 504),
+                    outcomeUnknown=method != "GET",
+                )
+            if not isinstance(value, dict):
+                return self._failure(
+                    502,
+                    "Expected a JSON response object",
+                    context=context,
+                    error_type="protocol",
+                    httpStatus=status,
+                )
+            value = dict(value)
+            meta = value.get("meta")
+            value["meta"] = {
+                **(dict(context) if context else {}),
+                **(meta if isinstance(meta, dict) else {}),
+            }
+            if request_id:
+                value["meta"].setdefault("requestId", request_id)
+            if not 200 <= status < 300:
+                value.update({"success": False, "httpStatus": status})
+                if str(value.get("code", "200")) == "200":
+                    value["code"] = str(status)
+                value.setdefault("message", "HTTP {}".format(status))
+                value.setdefault("retryable", status in (429, 502, 503, 504))
+                value.setdefault("errorType", "http")
+            elif not self._ok(value):
+                value.setdefault("code", "502")
+                value["success"] = False
+                value.setdefault("message", "Server did not confirm success")
+                value.setdefault("errorType", "business")
+                value["httpStatus"] = status
+            elif binary:
+                return self._failure(
+                    502,
+                    "Expected binary output but received JSON",
+                    context=context,
+                    error_type="protocol",
+                    httpStatus=status,
+                )
+            return self._finish(value)
+        finally:
+            response.close()
+
+    def _upload(
+        self, path, file_path, *, fields=None, kind="image", context=None, legacy=False, binary=None
+    ):
+        try:
+            file = Path(file_path)
+            if not file.is_file():
+                return self._failure(
+                    404, "Input file does not exist", context=context, error_type="file"
+                )
+            size = file.stat().st_size
+            limit = (100 if kind == "video" else 20) * 1024 * 1024
+            if not 0 < size <= limit:
+                return self._failure(
+                    413 if size > limit else 400,
+                    "Input file is empty or exceeds the size limit",
+                    context=context,
+                    error_type="file",
+                )
+            media = mimetypes.guess_type(file.name)[0] or "application/octet-stream"
+            with file.open("rb") as source:
+                return self._request(
+                    "POST",
+                    path,
+                    files={"file": (file.name, source, media)},
+                    data=fields,
+                    legacy=legacy,
+                    context=context,
+                    binary=binary,
+                )
+        except (OSError, TypeError, ValueError):
+            return self._failure(
+                400, "Input file cannot be read", context=context, error_type="file"
+            )
+
+    def upload_asset(self, image_path):
+        """Upload a private image, returning data.assetId. No inference is started."""
+        return self._upload("/v1/assets", image_path)
+
+    def import_asset(self, image_url):
+        """Ask the backend to import an allowed URL; the SDK never downloads it."""
+        if not isinstance(image_url, str) or not image_url.strip():
+            return self._failure(400, "image_url is required")
+        return self._request("POST", "/v1/assets/import", json={"imageUrl": image_url})
+
+    def get_asset(self, asset_id):
+        try:
+            self._identifier(asset_id)
+        except (ValueError, TypeError, AttributeError):
+            return self._failure(400, "Invalid asset_id")
+        return self._request("GET", "/v1/assets/" + asset_id)
+
+    def infer(self, model, asset_id, *, idempotency_key=None):
+        try:
+            if model not in self.MODELS:
+                raise ValueError("Supported models are mnet and icaa17k")
+            self._identifier(asset_id)
+            key = self._key(idempotency_key)
+        except (ValueError, TypeError, AttributeError) as error:
+            return self._failure(400, str(error))
+        return self._request(
+            "POST",
+            "/v1/inferences/" + model,
+            json={"assetId": asset_id},
+            context={"assetId": asset_id, "idempotencyKey": key, "model": model},
+        )
+
+    def get_inference(self, request_id):
+        try:
+            self._identifier(request_id)
+        except (ValueError, TypeError, AttributeError):
+            return self._failure(400, "Invalid request_id")
+        return self._request("GET", "/v1/inferences/" + request_id)
+
+    def _model(self, model, image_path, asset_id, key, legacy):
+        try:
+            key = self._key(key)
+        except ValueError as error:
+            return self._failure(400, str(error))
+        if (image_path is None) == (asset_id is None):
+            return self._failure(400, "Provide exactly one of image_path or asset_id")
+        if legacy:
+            if asset_id is not None:
+                return self._failure(400, "legacy=True requires an image file")
+            return self._file(model, image_path, idempotency_key=key)
+        if image_path is not None:
+            reply = self._upload(
+                "/v1/assets",
+                image_path,
+                context={"idempotencyKey": key, "model": model, "stage": "upload"},
+            )
+            if not self._ok(reply):
+                return reply
+            asset_id = (
+                reply.get("data", {}).get("assetId")
+                if isinstance(reply.get("data"), dict)
+                else None
+            )
+            if not asset_id:
+                return self._failure(
+                    502,
+                    "Upload response omitted assetId",
+                    context={"idempotencyKey": key},
+                    error_type="protocol",
+                )
+        return self.infer(model, asset_id, idempotency_key=key)
+
+    def mnet(self, image_path=None, *, asset_id=None, idempotency_key=None, legacy=False):
+        return self._model("mnet", image_path, asset_id, idempotency_key, legacy)
+
+    def icaa17k(self, image_path=None, *, asset_id=None, idempotency_key=None, legacy=False):
+        return self._model("icaa17k", image_path, asset_id, idempotency_key, legacy)
+
+    def _file(
+        self, endpoint, file_path, *, fields=None, kind="image", binary=None, idempotency_key=None
+    ):
+        if self.token:
+            return self._failure(
+                400,
+                "File compatibility APIs require API-Key credentials; use asset/inference or IQA task APIs for user tokens",
+            )
+        payload = {"accessKeyId": self.access_key_id, "sign": self.sign}
+        if fields:
+            payload.update(fields)
+        return self._upload(
+            "/api/file/" + endpoint,
+            file_path,
+            fields=payload,
+            kind=kind,
+            binary=binary,
+            legacy=True,
+            context={"idempotencyKey": idempotency_key} if idempotency_key else None,
+        )
+
+    # Existing names and server response fields remain intact.
+    def sharpness(self, image_path):
+        return self._file("sharpness", image_path)
+
+    def color(self, image_path):
+        return self._file("color", image_path)
+
+    def contrast(self, image_path):
+        return self._file("contrast", image_path)
+
+    def evaluate_all(self, image_path):
+        return self._file("evaluate_all", image_path)
+
+    def noise(self, image_path):
+        return self._file("noise", image_path)
+
+    def roc4mllm(self, image_path):
+        return self._file("roc4mllm", image_path)
+
+    def physique(self, image_path):
+        return self._file("physique", image_path)
+
+    def human(self, image_path):
+        return self._file("human", image_path)
+
+    def exposure(self, image_path):
+        return self._file("exposure", image_path)
+
+    def holistic(self, image_path):
+        return self._file("holistic", image_path)
+
+    def overall_iqa(self, image_path):
+        return self._file("overall_iqa", image_path)
+
+    def paa(self, image_path):
+        return self._file("paa", image_path)
+
+    def creative_crop(self, image_path):
+        return self._file("creative-crop", image_path, binary="image")
+
+    def highlight(self, video_path, *, query=""):
+        return self._file(
+            "highlight", video_path, fields={"query": query}, kind="video", binary="video"
+        )
+
+    def videomamba(self, video_path, *, query=""):
+        return self._file("videomamba", video_path, fields={"query": query}, kind="video")
+
+    def acellm(self, image_path, *, selections=("exposure",)):
+        if (
+            not isinstance(selections, (list, tuple))
+            or not selections
+            or any(not isinstance(item, str) for item in selections)
+        ):
+            return self._failure(400, "selections must be a non-empty list of metric names")
+        return self._file(
+            "acellm", image_path, fields={"selections": list(selections)}, binary="image"
+        )
+
+    def iqa_health(self):
+        return self._request("GET", "/v1/iqa/health")
+
+    def get_iqa_config(self):
+        return self._request("GET", "/v1/iqa/config")
+
+    def configure_iqa(self, config):
+        if not isinstance(config, dict):
+            return self._failure(400, "config must be an object")
+        return self._request("PUT", "/v1/iqa/config", json=config)
+
+    def upload_iqa_asset(self, file_path, *, kind="image"):
+        if kind not in ("image", "video"):
+            return self._failure(400, "kind must be image or video")
+        return self._upload("/v1/iqa/assets", file_path, kind=kind, fields={"kind": kind})
+
+    def create_iqa_task(
+        self, asset_ids, *, selections=DEFAULT_IQA_METRICS, kind="image", idempotency_key=None
+    ):
+        try:
+            if (
+                kind not in ("image", "video")
+                or not isinstance(asset_ids, (list, tuple))
+                or not 1 <= len(asset_ids) <= (1 if kind == "video" else 50)
+            ):
+                raise ValueError("Provide 1-50 image asset IDs or one video asset ID")
+            if len(set(asset_ids)) != len(asset_ids):
+                raise ValueError("asset_ids must not contain duplicates")
+            for asset_id in asset_ids:
+                self._identifier(asset_id)
+            if (
+                not isinstance(selections, (list, tuple))
+                or not selections
+                or len(set(selections)) != len(selections)
+                or not self.IQA_METRICS.issuperset(selections)
+            ):
+                raise ValueError("Invalid IQA selections")
+            base = self.IQA_METRICS - {"holistic", "overall_iqa"}
+            if "holistic" in selections and not base.intersection(selections):
+                raise ValueError("holistic requires at least one base metric")
+            if kind == "video" and "overall_iqa" in selections:
+                raise ValueError("overall_iqa is not available for video tasks")
+            key = self._key(idempotency_key)
+        except (ValueError, TypeError, AttributeError) as error:
+            return self._failure(400, str(error))
+        return self._request(
+            "POST",
+            "/v1/iqa/tasks",
+            json={"assetIds": list(asset_ids), "selections": list(selections), "kind": kind},
+            context={"idempotencyKey": key, "assetIds": list(asset_ids)},
+        )
+
+    def list_iqa_tasks(self):
+        return self._request("GET", "/v1/iqa/tasks")
+
+    def _iqa_task(self, task_id, cancel=False, timeout=None):
+        try:
+            self._identifier(task_id)
+        except (ValueError, TypeError, AttributeError):
+            return self._failure(400, "Invalid task_id")
+        return self._request(
+            "POST" if cancel else "GET",
+            "/v1/iqa/tasks/" + task_id + ("/cancel" if cancel else ""),
+            context={"taskId": task_id},
+            timeout=timeout,
+        )
+
+    def get_iqa_task(self, task_id):
+        return self._iqa_task(task_id)
+
+    def cancel_iqa_task(self, task_id):
+        return self._iqa_task(task_id, cancel=True)
+
+    def wait_iqa_task(self, task_id, *, wait_timeout=300, poll_interval=1):
+        if not self._positive(wait_timeout) or not self._positive(poll_interval):
+            return self._failure(400, "wait_timeout and poll_interval must be positive seconds")
+        deadline = time.monotonic() + wait_timeout
+        while True:
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                return self._failure(
+                    408,
+                    "Stopped waiting; the server task has NOT been cancelled",
+                    context={"taskId": task_id},
+                    error_type="wait_timeout",
+                    retryable=True,
+                )
+            reply = self._iqa_task(task_id, timeout=min(self.timeout, remaining))
+            if not self._ok(reply):
+                return reply
+            task = reply.get("data")
+            status = task.get("status") if isinstance(task, dict) else None
+            if status in self.TERMINAL_TASKS:
+                if status not in ("SUCCEEDED", "PARTIAL"):
+                    return self._failure(
+                        409 if status == "CANCELLED" else 500,
+                        task.get("message") or "IQA task {}".format(status),
+                        context={"taskId": task_id},
+                        error_type="task",
+                        task=task,
+                    )
+                return reply
+            if status not in self.PENDING_TASKS:
+                return self._failure(
+                    502,
+                    "Unknown IQA task status",
+                    context={"taskId": task_id},
+                    error_type="protocol",
+                )
+            time.sleep(min(poll_interval, max(0, deadline - time.monotonic())))
+
+    def iqa(
+        self,
+        file_paths,
+        *,
+        selections=DEFAULT_IQA_METRICS,
+        kind="image",
+        wait=True,
+        idempotency_key=None,
+        wait_timeout=300,
+        poll_interval=1,
+    ):
+        paths = [file_paths] if isinstance(file_paths, (str, Path)) else file_paths
+        if not isinstance(paths, (list, tuple)) or not 1 <= len(paths) <= (
+            1 if kind == "video" else 50
+        ):
+            return self._failure(400, "Provide 1-50 image paths or one video path")
+        # Validate before uploading: a bad selection or missing second file must
+        # not leave avoidable partial uploads in the user's private storage.
+        try:
+            key = self._key(idempotency_key)
+            if (
+                kind not in ("image", "video")
+                or not isinstance(selections, (list, tuple))
+                or not selections
+                or len(set(selections)) != len(selections)
+                or not self.IQA_METRICS.issuperset(selections)
+            ):
+                raise ValueError("Invalid IQA selections or media kind")
+            if "holistic" in selections and not (
+                self.IQA_METRICS - {"holistic", "overall_iqa"}
+            ).intersection(selections):
+                raise ValueError("holistic requires at least one base metric")
+            if kind == "video" and "overall_iqa" in selections:
+                raise ValueError("overall_iqa is not available for video tasks")
+            if wait and (not self._positive(wait_timeout) or not self._positive(poll_interval)):
+                raise ValueError("wait_timeout and poll_interval must be positive seconds")
+            for path in paths:
+                file = Path(path)
+                if (
+                    not file.is_file()
+                    or not 0 < file.stat().st_size <= (100 if kind == "video" else 20) * 1024 * 1024
+                ):
+                    raise ValueError("Input file is missing, empty or too large")
+        except (ValueError, TypeError, OSError) as error:
+            return self._failure(400, str(error))
+        assets = []
+        for path in paths:
+            uploaded = self._upload(
+                "/v1/iqa/assets",
+                path,
+                kind=kind,
+                fields={"kind": kind},
+                context={"idempotencyKey": key, "assetIds": list(assets), "stage": "upload"},
+            )
+            if not self._ok(uploaded):
+                return uploaded
+            asset_id = (
+                uploaded.get("data", {}).get("assetId")
+                if isinstance(uploaded.get("data"), dict)
+                else None
+            )
+            if not asset_id:
+                return self._failure(502, "Upload response omitted assetId", error_type="protocol")
+            assets.append(asset_id)
+        created = self.create_iqa_task(
+            assets, selections=selections, kind=kind, idempotency_key=key
+        )
+        if not self._ok(created) or not wait:
+            return created
+        task_id = (
+            created.get("data", {}).get("taskId") if isinstance(created.get("data"), dict) else None
+        )
+        if not task_id:
+            return self._failure(
+                502,
+                "Task response omitted taskId",
+                error_type="protocol",
+                context=created.get("meta"),
+            )
+        try:
+            result = self.wait_iqa_task(
+                task_id, wait_timeout=wait_timeout, poll_interval=poll_interval
+            )
+        except AceError as error:
+            error.response["meta"] = {**created.get("meta", {}), **error.response.get("meta", {})}
+            raise AceError(error.response) from None
+        result["meta"] = {**created.get("meta", {}), **result.get("meta", {})}
+        return result
+
+    def close(self):
+        if not self._closed:
+            self.session.close()
+            self._closed = True
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, exc_type, exc, traceback):
+        self.close()

ace_engine/results.py

@@ -0,0 +1,32 @@
+"""Error details and binary output helpers; no credentials are logged."""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+
+class AceError(RuntimeError):
+    """Raised only when ``raise_for_errors=True``; inspect ``response`` to recover."""
+
+    def __init__(self, response):
+        self.response = response
+        self.code = str(response.get("code", "500"))
+        self.http_status = response.get("httpStatus")
+        self.request_id = response.get("requestId") or response.get("meta", {}).get("requestId")
+        self.task_id = response.get("meta", {}).get("taskId")
+        self.idempotency_key = response.get("meta", {}).get("idempotencyKey")
+        super().__init__("ACE {}: {}".format(self.code, response.get("message", "Request failed")))
+
+
+@dataclass(frozen=True)
+class BinaryResult:
+    content: bytes
+    content_type: str
+    request_id: Optional[str] = None
+
+    def save(self, path, *, overwrite=False):
+        """Save only on explicit request. Existing files are protected by default."""
+        target = Path(path)
+        with target.open("wb" if overwrite else "xb") as output:
+            output.write(self.content)
+        return target

ace_engine_sdk-0.2.0.dist-info/METADATA

@@ -0,0 +1,248 @@
+Metadata-Version: 2.4
+Name: ace-engine-sdk
+Version: 0.2.0
+Summary: AceEngine image quality evaluation SDK
+Home-page: https://github.com/YuqiPlus/ACEngine-Client
+Author: YuqiPlus
+Author-email: silverwjq@163.com
+License-Expression: MIT
+Project-URL: Documentation, https://github.com/YuqiPlus/ACEngine-Client#readme
+Project-URL: Source, https://github.com/YuqiPlus/ACEngine-Client
+Project-URL: Issues, https://github.com/YuqiPlus/ACEngine-Client/issues
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.25.0
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: license-expression
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# ACEngine Client SDK
+
+用于调用 ACE 美学计算服务的 Python SDK。支持 MNet / ICAA17K 的私有资源调用、IQA 图片/视频异步任务，以及现有单项评分和图像/视频处理接口。
+
+本文档对应 **SDK 0.2.0**，需要 Python 3.9 或更新版本。发行状态以 PyPI 和 GitHub 的实际版本为准；尚未发布的改动请使用本地源码安装。维护者首次发布步骤见 [PUBLISHING.md](PUBLISHING.md)。
+
+## 安装
+
+发布到 PyPI 后，用户可以直接安装：
+
+```bash
+pip install ace-engine-sdk
+```
+
+```bash
+# GitHub 主分支
+pip install --upgrade git+https://github.com/YuqiPlus/ACEngine-Client.git
+
+# 本地开发
+pip install -e .
+
+# 已有的 0.1.0 标签（不含本轮新功能）
+pip install git+https://github.com/YuqiPlus/ACEngine-Client.git@v0.1.0
+```
+
+HTTPS 不通时可以使用 SSH（需要已经配置 GitHub SSH 密钥）：
+
+```bash
+pip install git+ssh://git@github.com/YuqiPlus/ACEngine-Client.git
+```
+
+代理、证书和网络连接由本机配置，不在 SDK 中固定代理地址，也不关闭 HTTPS 证书验证。卸载包名为 `ace-engine-sdk`：
+
+```bash
+pip show ace-engine-sdk
+pip uninstall ace-engine-sdk
+```
+
+## 快速开始
+
+密钥放在环境变量里，勿写进共享代码。示例占位符需要替换成控制台颁发的有效凭证：
+
+```bash
+export ACE_ENGINE_ACCESS_KEY_ID="your-key-id"
+export ACE_ENGINE_ACCESS_KEY_SECRET="your-key-secret"
+```
+
+Windows PowerShell：
+
+```powershell
+$env:ACE_ENGINE_ACCESS_KEY_ID="your-key-id"
+$env:ACE_ENGINE_ACCESS_KEY_SECRET="your-key-secret"
+```
+
+```python
+import os
+from ace_engine import AceClient
+
+with AceClient(
+    access_key_id=os.environ["ACE_ENGINE_ACCESS_KEY_ID"],
+    access_key_secret=os.environ["ACE_ENGINE_ACCESS_KEY_SECRET"],
+    raise_for_errors=True,
+) as client:
+    response = client.mnet("photo.png")
+    print(response["data"])  # 保留后端原始模型字段
+    print(response["meta"])  # requestId、assetId、costCents、durationMs、replayed 等
+```
+
+默认服务为 `https://ace-aesthetics.cn`，接口前缀为 `/ibt`。`base_url` 也接受 `https://ace-aesthetics.cn/ibt`，不会重复拼接前缀。自建网关可以配置 `base_url` 和 `api_prefix`；只有直接连接不带统一前缀的网关时才使用 `api_prefix=""`。
+
+旧的三参数构造 `AceClient(base_url, access_key_id, sign)` 继续可用，`sign` 是 `access_key_secret` 的兼容名称。两者同时传入时必须一致。`from ace_engine import Client` 也是同一客户端的别名。
+
+## 上传一次，调用多个模型
+
+下面使用 `client` 的片段应放在上面的 `with AceClient(...) as client:` 代码块内；离开代码块后连接已关闭。
+
+```python
+uploaded = client.upload_asset("photo.png")
+asset_id = uploaded["data"]["assetId"]
+
+mnet_key = client.new_idempotency_key()
+response = client.mnet(asset_id=asset_id, idempotency_key=mnet_key)
+
+# 新的模型调用意图使用新的幂等键
+icaa_key = client.new_idempotency_key()
+response = client.icaa17k(asset_id=asset_id, idempotency_key=icaa_key)
+
+# 检查资源 / 查询已经提交的调用，不重新执行模型
+asset = client.get_asset(asset_id)
+status = client.get_inference(response["meta"]["requestId"])
+```
+
+`client.infer("mnet", asset_id, idempotency_key=...)` 和 `client.infer("icaa17k", ...)` 提供相同的底层入口。`mnet("photo.png")`、`icaa17k("photo.png")` 自动先上传再调用。
+
+`import_asset(image_url)` 将网址交给服务端的允许来源检查；SDK 不下载任意网址，也不绕过后端来源限制。资源属于凭证对应的用户/团队，会按服务端保留策略过期；不能假定资源永久有效。
+
+### 幂等、错误和计费
+
+一次逻辑调用使用一个幂等键，网络超时或响应丢失后的恢复必须沿用原键。不同模型或不同图片使用新键。
+
+```python
+from ace_engine import AceError
+
+key = client.new_idempotency_key()  # 调用前由业务持久化保存 key 和 asset_id
+try:
+    response = client.infer("mnet", asset_id, idempotency_key=key)
+except AceError as error:
+    print(error.code, error.request_id, error.idempotency_key)
+    # 有 request_id 时先 get_inference(request_id) 查看 RUNNING / SETTLING / SUCCEEDED / FAILED。
+    # 状态允许恢复时，再使用同一个模型、asset_id、key 调用 infer。
+    # 不要因超时直接换一个新 key。
+```
+
+SDK **不自动重试模型 POST，不在错误后自动换旧接口重发**。MNet / ICAA 的服务端负责幂等、结算和余额检查；SDK 透传其 `costCents` 等实际字段，不估算费用、不伪造结果。`replayed=True` 表示服务端返回此前调用的结果，不是一次新的计费意图。
+
+默认 `raise_for_errors=False`，兼容 0.1 的字典返回方式，调用方应检查 `code` / `success`。HTTP 和业务错误保留原始业务码、说明、请求编号和 HTTP 状态（`httpStatus`）。本地或网络错误使用 `errorType` 区分。
+
+网络/协议异常可能带 `outcomeUnknown=True`：这表示客户端不能确认提交结果，不能据此推断模型未运行或未扣款。错误中的 `meta` 保留可用的 `assetId`、`idempotencyKey`、`taskId` 等恢复信息。密钥和令牌会从 SDK 返回的错误中脱敏；SDK 不打印请求或凭证，不跟随重定向发送凭证。
+
+`raise_for_errors=True` 会抛出 `AceError`，其 `.response` 保留相同的错误字典。响应数据及费用字段以实际部署版本为准。
+
+## IQA 异步评估
+
+```python
+# 一张或多张图片；默认等待完成
+response = client.iqa(
+    ["photo1.png", "photo2.jpg"],
+    selections=["sharpness", "exposure", "contrast", "noise"],
+    wait_timeout=300,
+)
+print(response["data"]["status"])
+print(response["data"].get("result"))
+```
+
+图片每任务最多 50 张，视频每任务 1 个。图片单文件上限 20 MiB，视频 100 MiB；还受服务端实际配额限制。支持的指标为：`sharpness`、`color_accuracy`、`saturation`、`exposure`、`contrast`、`noise`、`holistic`、`overall_iqa`。`holistic` 需要至少一项基础指标；视频不支持 `overall_iqa`。
+
+异步提交、查询和取消：
+
+```python
+asset = client.upload_iqa_asset("clip.mp4", kind="video")
+asset_ids = [asset["data"]["assetId"]]
+key = client.new_idempotency_key()
+created = client.create_iqa_task(
+    asset_ids, kind="video", selections=["exposure"], idempotency_key=key,
+)
+task_id = created["data"]["taskId"]
+
+response = client.get_iqa_task(task_id)
+response = client.wait_iqa_task(task_id, wait_timeout=600, poll_interval=2)
+# client.cancel_iqa_task(task_id)  # 只有显式调用才请求取消
+# client.list_iqa_tasks()
+```
+
+也可以 `client.iqa("photo.png", selections=["exposure"], wait=False)`，返回已创建的任务。`wait_timeout` 只限制客户端等待，超时不会自动取消、重建或重新扣费；保存错误 `meta.taskId` 后继续查询。
+
+`SUCCEEDED` 是完成，`PARTIAL` 表示部分结果可用（需要检查任务里的 errors），`FAILED` / `CANCELLED` 在等待接口中作为错误返回。查询接口保留服务端原始状态。等待网络中断后继续查询原任务，不要重新上传并创建另一个任务。若创建响应丢失，应使用原 `asset_ids`、指标、kind 和幂等键恢复；IQA 重传文件会产生新资源 ID，不能假定与原任务等价。
+
+MNet/ICAA 的资源与 IQA 的资源是不同接口管理的资源，不能混用 ID。IQA 输出可能包含短期签名图片/CSV/视频链接；保留签名参数，失效后重新查询任务，SDK 不向这些链接转发账户凭证。
+
+`get_iqa_config()` 读取配置；`configure_iqa(config)` 显式提交服务端要求的完整权重/阈值对象。`iqa()` 不会暗中修改账户默认设置，也不支持旧网页中曾出现但服务端并无对应参数的 `weights={...}` 用法。
+
+## 兼容的单项文件接口
+
+以下方法接受本地图片，继续调用对应的 `/api/file/...` 接口：
+
+| 方法 | 用途 |
+| --- | --- |
+| `sharpness(path)` | 清晰度 |
+| `color(path)` | 色彩 |
+| `contrast(path)` | 对比度 |
+| `noise(path)` | 噪声 |
+| `exposure(path)` | 曝光 |
+| `holistic(path)` | 综合质量 |
+| `evaluate_all(path)` | 服务端定义的综合评估 |
+| `overall_iqa(path)` | 高分辨率整体质量 |
+| `roc4mllm(path)` | 多模态评价 |
+| `physique(path)` / `paa(path)` | 体态评价 |
+| `human(path)` | 人像评价 |
+
+这些接口使用 API-Key 表单鉴权，保留服务端各自的数据字段，不统一捏造成 `{score, level}`。实际可用性取决于部署的模型服务、凭证权限和余额。
+
+MNet / ICAA 默认走新资源接口；只有明确连接旧版服务时才使用 `client.mnet(path, legacy=True)` 或 `client.icaa17k(path, legacy=True)`。普通单项文件接口没有统一幂等保障，超时后不能盲目重发；SDK 不自动重试。
+
+## 图像和视频输出
+
+```python
+from ace_engine import BinaryResult
+
+result = client.creative_crop("photo.jpg")
+if isinstance(result, BinaryResult):
+    result.save("crop.jpg")  # 默认拒绝覆盖已有文件
+
+# 返回 BinaryResult，保留真实 Content-Type
+result = client.acellm("photo.jpg", selections=["exposure"])
+result = client.highlight("clip.mp4", query="a person running")
+
+# JSON 响应
+result = client.videomamba("clip.mp4", query="a person running")
+```
+
+二进制成功返回 `BinaryResult(content, content_type, request_id)`；失败仍按统一错误机制处理，不把 JSON 报错写成图片或视频。内容在内存中，只有显式 `.save()` 才写文件；覆盖需要 `overwrite=True`。
+
+## 网站登录令牌
+
+已有有效普通用户 JWT 时，可使用 `AceClient(token=token)` 访问新资源、模型调用和正式 IQA 任务接口。SDK 不负责登录、验证码或刷新令牌。API-Key 与 JWT 必须选择一种，不能混传；旧的单项文件接口需要 API-Key，不自动切换鉴权身份。
+
+## 命令行示例与验证
+
+```bash
+python test_my_sdk.py photo.png --model mnet
+python test_my_sdk.py photo.png --model icaa17k --idempotency-key your-persisted-key
+python test_my_sdk.py photo.png --model iqa --selections exposure noise
+
+python -m unittest discover -s tests -v
+python -m build
+```
+
+`ACE_ENGINE_BASE_URL`、`ACE_ENGINE_API_PREFIX`、`ACE_ENGINE_ACCESS_KEY_ID`、`ACE_ENGINE_ACCESS_KEY_SECRET`（兼容 `ACE_ENGINE_SIGN`）及 `ACE_ENGINE_TOKEN` 可供示例程序使用。测试使用隔离的本机 HTTP 服务，不依赖真实密钥、不执行模型、不产生费用。实际联调需另用测试账号核对模型、状态和账单，不能用传输测试代替真实验证。

ace_engine_sdk-0.2.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+ace_engine/__init__.py,sha256=a5m-azvaDT7qUcmgP0eRTC5RG7XycvlW6HZJF97PIkY,193
+ace_engine/client.py,sha256=xWQIVz_66yQ5P5HdpAhBc4eNeYa1KEt7VOeilZSEUcY,26503
+ace_engine/results.py,sha256=lPUrVw-LMDrPVkNkKNhGu7sopw8r4H1nLkl7zQ2cJGM,1204
+ace_engine_sdk-0.2.0.dist-info/licenses/LICENSE,sha256=OvNOOjocN-n1WCW2_siK2OJfa3Q7e4aTdVSWXBCLrbM,1059
+ace_engine_sdk-0.2.0.dist-info/METADATA,sha256=Kgo7Kmjw4FW222GVujmJ9NjcuZnp3UWt1NXW2YHK01w,11571
+ace_engine_sdk-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+ace_engine_sdk-0.2.0.dist-info/top_level.txt,sha256=dEM0eD9JZwrERUWhi_9U6w3PRGswZ6k80hch2nkcd0M,11
+ace_engine_sdk-0.2.0.dist-info/RECORD,,

ace_engine_sdk-0.2.0.dist-info/WHEEL

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

ace_engine_sdk-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ACE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ace_engine_sdk-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+ace_engine