adaptorch-client 0.1.0__tar.gz

adaptorch_client-0.1.0/LICENSE

@@ -0,0 +1,14 @@
+Copyright (c) 2026 ClassicMate. All rights reserved.
+
+This software and associated documentation files (the "Software") are proprietary
+and confidential. Unauthorized copying, distribution, modification, public
+display, or any use of the Software other than as expressly authorized by ClassicMate
+is strictly prohibited.
+
+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.

adaptorch_client-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: adaptorch-client
+Version: 0.1.0
+Summary: Typed standard-library client for the AdaptOrch API
+Author: ClassicMate
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://adaptorch.com
+Project-URL: Repository, https://github.com/dmae97/Adaptorch-MCP
+Project-URL: Issues, https://github.com/dmae97/Adaptorch-MCP/issues
+Project-URL: Documentation, https://github.com/dmae97/Adaptorch-MCP#readme
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pytest>=8.2; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# adaptorch-client
+
+Typed, standard-library Python client for the AdaptOrch User API.
+
+## Install
+
+The package is currently distributed from this repository rather than PyPI. Install
+it from the package subdirectory:
+
+```bash
+pip install "adaptorch-client @ git+https://github.com/dmae97/Adaptorch-MCP.git#subdirectory=packages/adaptorch-client"
+```
+
+## First run
+
+Create an `ado_live_*` key at <https://adaptorch.com/app/api-keys>. The raw key is
+shown once; keep it in an environment variable and never commit it.
+
+```python
+import os
+
+from adaptorch_client import AdaptOrchClient, ClientConfig
+
+client = AdaptOrchClient(
+    ClientConfig(
+        api_url="https://adaptorch.com",
+        api_key=os.environ["ADAPTORCH_API_KEY"],
+    )
+)
+run = client.submit_run(
+    {
+        "subtasks": [{"id": "check", "description": "Reply with the word ready"}],
+        "dependencies": [],
+    },
+    idempotency_key="11111111-1111-4111-8111-111111111111",
+)
+print(run.run_id, run.status)
+```
+
+`api_url` is the origin only; do not append `/v1`. The client sends tenant keys
+as `X-API-Key`, includes a UUID idempotency key on submissions, and exposes
+`capabilities()`, `whoami()`, run listing/detail/cancel, evidence, and artifacts.
+
+See [`../../docs/adaptorchctl-usage.ko.md`](../../docs/adaptorchctl-usage.ko.md) for the current CLI and API usage guide.
+
+## License
+
+Proprietary — Copyright ClassicMate. All rights reserved. See [LICENSE](https://github.com/dmae97/Adaptorch-MCP/blob/main/LICENSE).

adaptorch_client-0.1.0/README.md

@@ -0,0 +1,48 @@
+# adaptorch-client
+
+Typed, standard-library Python client for the AdaptOrch User API.
+
+## Install
+
+The package is currently distributed from this repository rather than PyPI. Install
+it from the package subdirectory:
+
+```bash
+pip install "adaptorch-client @ git+https://github.com/dmae97/Adaptorch-MCP.git#subdirectory=packages/adaptorch-client"
+```
+
+## First run
+
+Create an `ado_live_*` key at <https://adaptorch.com/app/api-keys>. The raw key is
+shown once; keep it in an environment variable and never commit it.
+
+```python
+import os
+
+from adaptorch_client import AdaptOrchClient, ClientConfig
+
+client = AdaptOrchClient(
+    ClientConfig(
+        api_url="https://adaptorch.com",
+        api_key=os.environ["ADAPTORCH_API_KEY"],
+    )
+)
+run = client.submit_run(
+    {
+        "subtasks": [{"id": "check", "description": "Reply with the word ready"}],
+        "dependencies": [],
+    },
+    idempotency_key="11111111-1111-4111-8111-111111111111",
+)
+print(run.run_id, run.status)
+```
+
+`api_url` is the origin only; do not append `/v1`. The client sends tenant keys
+as `X-API-Key`, includes a UUID idempotency key on submissions, and exposes
+`capabilities()`, `whoami()`, run listing/detail/cancel, evidence, and artifacts.
+
+See [`../../docs/adaptorchctl-usage.ko.md`](../../docs/adaptorchctl-usage.ko.md) for the current CLI and API usage guide.
+
+## License
+
+Proprietary — Copyright ClassicMate. All rights reserved. See [LICENSE](https://github.com/dmae97/Adaptorch-MCP/blob/main/LICENSE).

adaptorch_client-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "adaptorch-client"
+version = "0.1.0"
+description = "Typed standard-library client for the AdaptOrch API"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "LicenseRef-Proprietary"
+license-files = ["LICENSE"]
+authors = [{ name = "ClassicMate" }]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://adaptorch.com"
+Repository = "https://github.com/dmae97/Adaptorch-MCP"
+Issues = "https://github.com/dmae97/Adaptorch-MCP/issues"
+Documentation = "https://github.com/dmae97/Adaptorch-MCP#readme"
+
+[project.optional-dependencies]
+dev = ["build>=1.2", "mypy>=1.10", "pytest>=8.2", "ruff>=0.6"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+adaptorch_client = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true
+files = ["src"]

adaptorch_client-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

adaptorch_client-0.1.0/src/adaptorch_client/__init__.py

@@ -0,0 +1,38 @@
+"""Public AdaptOrch API client."""
+
+from adaptorch_client.client import AdaptOrchClient
+from adaptorch_client.config import ClientConfig, validate_api_url
+from adaptorch_client.errors import AdaptOrchAPIError
+from adaptorch_client.models import (
+    Artifact,
+    CapabilitySet,
+    EvidenceCheck,
+    JSONMapping,
+    JSONValue,
+    PayloadResult,
+    Principal,
+    Run,
+)
+from adaptorch_client.responses import (
+    ArtifactListResponse,
+    EvidenceReport,
+    RunListResponse,
+)
+
+__all__ = [
+    "AdaptOrchAPIError",
+    "AdaptOrchClient",
+    "Artifact",
+    "ArtifactListResponse",
+    "CapabilitySet",
+    "ClientConfig",
+    "EvidenceCheck",
+    "EvidenceReport",
+    "JSONMapping",
+    "JSONValue",
+    "PayloadResult",
+    "Principal",
+    "Run",
+    "RunListResponse",
+    "validate_api_url",
+]

adaptorch_client-0.1.0/src/adaptorch_client/client.py

@@ -0,0 +1,122 @@
+"""Synchronous AdaptOrch API client."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from urllib.parse import quote, urlencode
+
+from adaptorch_client.config import ClientConfig
+from adaptorch_client.models import CapabilitySet, JSONValue, Principal, Run
+from adaptorch_client.responses import (
+    ArtifactListResponse,
+    EvidenceReport,
+    RunListResponse,
+)
+from adaptorch_client.transport import HTTPTransport, RequestSpec
+
+_IDEMPOTENCY_KEY_RE = re.compile(
+    r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE
+)
+
+
+class AdaptOrchClient:
+    """Small synchronous client for the AdaptOrch v1 API."""
+
+    __slots__ = ("_transport",)
+
+    def __init__(self, config: ClientConfig) -> None:
+        self._transport = HTTPTransport(config)
+
+    def capabilities(self) -> CapabilitySet:
+        """Return API capabilities."""
+        return CapabilitySet.from_payload(
+            self._transport.request(RequestSpec("GET", "/v1/capabilities"))
+        )
+
+    def whoami(self) -> Principal:
+        """Return the authenticated principal."""
+        return Principal.from_payload(
+            self._transport.request(RequestSpec("GET", "/v1/whoami"))
+        )
+
+    def submit_run(
+        self,
+        spec: Mapping[str, JSONValue],
+        idempotency_key: str,
+    ) -> Run:
+        """Submit one run without retrying the POST request."""
+        self._require_idempotency_key(idempotency_key)
+        return Run.from_payload(
+            self._transport.request(
+                RequestSpec(
+                    "POST",
+                    "/v1/runs",
+                    payload=spec,
+                    headers={"Idempotency-Key": idempotency_key},
+                )
+            )
+        )
+
+    def list_runs(
+        self,
+        status: str | None = None,
+        project_id: str | None = None,
+    ) -> RunListResponse:
+        """List runs, optionally filtered by status and project."""
+        filters: list[tuple[str, str]] = []
+        if status is not None:
+            filters.append(("status", status))
+        if project_id is not None:
+            filters.append(("project_id", project_id))
+        query = f"?{urlencode(filters)}" if filters else ""
+        return RunListResponse.from_payload(
+            self._transport.request(RequestSpec("GET", f"/v1/runs{query}"))
+        )
+
+    def get_run(self, run_id: str) -> Run:
+        """Return one run."""
+        return Run.from_payload(
+            self._transport.request(RequestSpec("GET", f"/v1/runs/{self._segment(run_id)}"))
+        )
+
+    def cancel_run(self, run_id: str, reason: str | None = None) -> Run:
+        """Cancel one run with an optional reason."""
+        payload: dict[str, JSONValue] = {} if reason is None else {"reason": reason}
+        return Run.from_payload(
+            self._transport.request(
+                RequestSpec(
+                    "PUT",
+                    f"/v1/runs/{self._segment(run_id)}/cancel",
+                    payload=payload,
+                )
+            )
+        )
+
+    def get_evidence(self, run_id: str) -> EvidenceReport:
+        """Return the evidence report for one run."""
+        return EvidenceReport.from_payload(
+            self._transport.request(
+                RequestSpec("GET", f"/v1/runs/{self._segment(run_id)}/evidence")
+            )
+        )
+
+    def list_artifacts(self, run_id: str) -> ArtifactListResponse:
+        """List artifacts for one run."""
+        return ArtifactListResponse.from_payload(
+            self._transport.request(
+                RequestSpec("GET", f"/v1/runs/{self._segment(run_id)}/artifacts")
+            )
+        )
+
+    @staticmethod
+    def _segment(value: str) -> str:
+        if not value:
+            raise ValueError("path segment must not be empty")
+        encoded = quote(value, safe="")
+        return encoded.replace(".", "%2E") if value in {".", ".."} else encoded
+
+    @staticmethod
+    def _require_idempotency_key(value: str) -> None:
+        if not _IDEMPOTENCY_KEY_RE.fullmatch(value):
+            raise ValueError("idempotency_key must be a hyphenated UUID")

adaptorch_client-0.1.0/src/adaptorch_client/config.py

@@ -0,0 +1,72 @@
+"""Validated client configuration."""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from urllib.parse import urlsplit
+
+_LOOPBACK_HOSTS = frozenset({"localhost", "127.0.0.1", "::1"})
+_UNSAFE_URL_CHARACTERS = frozenset({"\\", "?", "#"})
+
+
+def validate_api_url(api_url: str) -> str:
+    """Validate an AdaptOrch API base URL and return it without a trailing slash.
+
+    Raise ``ValueError`` for surrounding whitespace, control characters,
+    backslashes, embedded credentials, a path, query, or fragment, port 0,
+    a missing host, or plain HTTP on a non-loopback host.
+    """
+    if api_url != api_url.strip() or any(
+        character in _UNSAFE_URL_CHARACTERS or ord(character) < 32 or ord(character) == 127
+        for character in api_url
+    ):
+        raise ValueError("api_url contains unsafe characters")
+
+    try:
+        parsed = urlsplit(api_url)
+        hostname = parsed.hostname
+        port = parsed.port
+    except ValueError as error:
+        raise ValueError("api_url is invalid") from error
+
+    if hostname is None or not parsed.netloc:
+        raise ValueError("api_url must include a host")
+    if port == 0:
+        raise ValueError("api_url port must be positive")
+    if parsed.username is not None or parsed.password is not None:
+        raise ValueError("api_url must not include credentials")
+    if parsed.path not in {"", "/"} or parsed.query or parsed.fragment:
+        raise ValueError("api_url must not include a path, query, or fragment")
+    if parsed.scheme == "http" and hostname not in _LOOPBACK_HOSTS:
+        raise ValueError("HTTP is allowed only for exact loopback hosts")
+    if parsed.scheme not in {"http", "https"}:
+        raise ValueError("api_url must use HTTPS or loopback HTTP")
+    return api_url.rstrip("/")
+
+
+@dataclass(frozen=True, slots=True)
+class ClientConfig:
+    """Connection settings for the AdaptOrch API."""
+
+    api_url: str
+    api_key: str = field(repr=False)
+    timeout_seconds: float = 30.0
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "api_url", validate_api_url(self.api_url))
+        if not self.api_key.strip() or any(
+            ord(character) < 32 or ord(character) == 127 or ord(character) > 255
+            for character in self.api_key
+        ):
+            raise ValueError("api_key must be a non-empty HTTP header value")
+        if not math.isfinite(self.timeout_seconds) or self.timeout_seconds <= 0:
+            raise ValueError("timeout_seconds must be positive and finite")
+
+    @property
+    def auth_headers(self) -> Mapping[str, str]:
+        """Return the sole authentication header valid for this credential."""
+        if self.api_key.startswith("ado_"):
+            return {"X-API-Key": self.api_key}
+        return {"Authorization": f"Bearer {self.api_key}"}

adaptorch_client-0.1.0/src/adaptorch_client/errors.py

@@ -0,0 +1,23 @@
+"""Sanitized public client errors."""
+
+from __future__ import annotations
+
+
+class AdaptOrchAPIError(RuntimeError):
+    """A sanitized API, transport, or response failure."""
+
+    __slots__ = ("code", "status_code")
+
+    code: str | None
+    status_code: int | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        code: str | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.status_code = status_code
+        self.code = code

adaptorch_client-0.1.0/src/adaptorch_client/models.py

@@ -0,0 +1,223 @@
+"""Typed v1 contract records parsed from direct (envelope-free) JSON responses."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Self, TypeAlias
+
+from adaptorch_client.errors import AdaptOrchAPIError
+
+JSONValue: TypeAlias = bool | int | float | str | list["JSONValue"] | dict[str, "JSONValue"] | None
+JSONMapping: TypeAlias = dict[str, JSONValue]
+
+
+def contract_error(path: str, expected: str) -> AdaptOrchAPIError:
+    """Return a sanitized contract-violation error naming only the field path."""
+    return AdaptOrchAPIError(f"AdaptOrch response field {path!r} must be {expected}")
+
+
+def field_path(path: str, key: str) -> str:
+    """Compose a dotted field path that stays readable at the response root."""
+    return f"{path}.{key}" if path else key
+
+
+def require_object(value: JSONValue, path: str) -> JSONMapping:
+    """Return ``value`` when it is a JSON object, else raise a contract error."""
+    if not isinstance(value, dict):
+        raise contract_error(path, "a JSON object")
+    return value
+
+
+def require_array(value: JSONValue, path: str) -> list[JSONValue]:
+    """Return ``value`` when it is a JSON array, else raise a contract error."""
+    if not isinstance(value, list):
+        raise contract_error(path, "a JSON array")
+    return value
+
+
+def stored_copy(payload: Mapping[str, JSONValue]) -> JSONMapping:
+    """Return an independent deep copy of a raw response payload."""
+    return deepcopy(dict(payload))
+
+
+def string_at(record: JSONMapping, key: str, path: str) -> str:
+    """Return the required string field ``key``, else raise a contract error."""
+    value = record.get(key)
+    if not isinstance(value, str):
+        raise contract_error(field_path(path, key), "a string")
+    return value
+
+
+def optional_string_at(record: JSONMapping, key: str, path: str) -> str | None:
+    """Return the optional string field ``key``; absent or null becomes ``None``."""
+    if record.get(key) is None:
+        return None
+    return string_at(record, key, path)
+
+
+def _string_tuple_at(record: JSONMapping, key: str, path: str) -> tuple[str, ...]:
+    values: list[str] = []
+    array_path = field_path(path, key)
+    for index, item in enumerate(require_array(record.get(key), array_path)):
+        if not isinstance(item, str):
+            raise contract_error(f"{array_path}[{index}]", "a string")
+        values.append(item)
+    return tuple(values)
+
+
+def _optional_size_at(record: JSONMapping, key: str, path: str) -> int | None:
+    value = record.get(key)
+    if value is None:
+        return None
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise contract_error(field_path(path, key), "a non-negative integer")
+    return value
+
+
+def _optional_links_at(record: JSONMapping, key: str, path: str) -> dict[str, str] | None:
+    value = record.get(key)
+    if value is None:
+        return None
+    links_path = field_path(path, key)
+    links: dict[str, str] = {}
+    for relation, target in require_object(value, links_path).items():
+        if not isinstance(target, str):
+            raise contract_error(f"{links_path}.{relation}", "a string")
+        links[relation] = target
+    return links
+
+
+@dataclass(frozen=True, slots=True)
+class PayloadResult:
+    """A record that keeps its raw JSON payload, unknown additive fields included."""
+
+    _payload: JSONMapping
+
+    def to_payload(self) -> JSONMapping:
+        """Return an independent JSON-compatible payload."""
+        return deepcopy(self._payload)
+
+
+@dataclass(frozen=True, slots=True)
+class CapabilitySet(PayloadResult):
+    """Direct ``GET /v1/capabilities`` record; unknown run kinds are preserved."""
+
+    api_version: str
+    run_types: tuple[str, ...]
+    features: tuple[str, ...]
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, JSONValue]) -> Self:
+        """Validate one raw capability response against the v1 contract."""
+        record = stored_copy(payload)
+        return cls(
+            record,
+            api_version=string_at(record, "api_version", ""),
+            run_types=_string_tuple_at(record, "run_types", "") if "run_types" in record else (),
+            features=_string_tuple_at(record, "features", ""),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Principal(PayloadResult):
+    """Direct ``GET /v1/whoami`` record from the v1 contract."""
+
+    subject_id: str
+    project_id: str | None
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, JSONValue]) -> Self:
+        """Validate one raw principal response against the v1 contract."""
+        record = stored_copy(payload)
+        return cls(
+            record,
+            subject_id=string_at(record, "subject_id", ""),
+            project_id=optional_string_at(record, "project_id", ""),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Run(PayloadResult):
+    """Direct ``Run`` record; unknown ``status`` enum strings are preserved."""
+
+    run_id: str
+    status: str
+    # status is liveness: did the run finish. result_status is the outcome: was
+    # the answer accepted. Both are absent while a run is still queued, and a
+    # finished run can carry a non-OK result, so they must not be conflated.
+    result_status: str | None
+    topology: str | None
+    kind: str | None
+    phase: str | None
+    created_at: str | None
+    policy_version: str | None
+    links: dict[str, str] | None
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, JSONValue]) -> Self:
+        """Validate one raw run response against the v1 contract."""
+        return cls._parse(stored_copy(payload), "")
+
+    @classmethod
+    def parse_at(cls, value: JSONValue, path: str) -> Self:
+        """Parse one nested run record located at ``path``."""
+        return cls._parse(deepcopy(require_object(value, path)), path)
+
+    @classmethod
+    def _parse(cls, record: JSONMapping, path: str) -> Self:
+        return cls(
+            record,
+            run_id=string_at(record, "run_id", path),
+            status=string_at(record, "status", path),
+            result_status=optional_string_at(record, "result_status", path),
+            topology=optional_string_at(record, "topology", path),
+            kind=optional_string_at(record, "kind", path),
+            phase=optional_string_at(record, "phase", path),
+            created_at=optional_string_at(record, "created_at", path),
+            policy_version=optional_string_at(record, "policy_version", path),
+            links=_optional_links_at(record, "links", path),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class EvidenceCheck:
+    """One evidence check; unknown ``status`` strings are preserved."""
+
+    name: str
+    status: str
+
+    @classmethod
+    def parse_at(cls, value: JSONValue, path: str) -> Self:
+        """Parse one contract record located at ``path``."""
+        record = require_object(value, path)
+        return cls(
+            name=string_at(record, "name", path),
+            status=string_at(record, "status", path),
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class Artifact:
+    """``Artifact`` record; only ``artifact_id`` and ``name`` are required."""
+
+    artifact_id: str
+    name: str
+    media_type: str | None
+    size_bytes: int | None
+    sha256: str | None
+    download_url: str | None
+
+    @classmethod
+    def parse_at(cls, value: JSONValue, path: str) -> Self:
+        """Parse one contract record located at ``path``."""
+        record = require_object(value, path)
+        return cls(
+            artifact_id=string_at(record, "artifact_id", path),
+            name=string_at(record, "name", path),
+            media_type=optional_string_at(record, "media_type", path),
+            size_bytes=_optional_size_at(record, "size_bytes", path),
+            sha256=optional_string_at(record, "sha256", path),
+            download_url=optional_string_at(record, "download_url", path),
+        )