ascent-science 0.1.0__tar.gz

ascent_science-0.1.0/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: ascent-science
+Version: 0.1.0
+Summary: Python SDK for the Ascent Science algorithm and evidence platform
+Author: Ascent Science
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Ascent Science Python SDK
+
+The SDK is the supported Python client for an Ascent Science server. It does
+not install solver runtimes locally.
+
+```python
+from ascent import Client
+
+client = Client(endpoint="http://127.0.0.1:8000/v1", api_key="asc_live_...")
+job = client.algorithms.submit(
+    "GraphColoring",
+    inputs={"data_size": 32},
+    parameters={"nodes": 12, "edge_density": 0.2},
+    idempotency_key="graph-demo-1",
+)
+result = job.wait(timeout=60)
+print(result.result)
+```
+
+`ASCENT_ENDPOINT` and `ASCENT_API_KEY` can be used instead of constructor
+arguments. API keys are created in an authenticated browser session and shown
+only once.
+

ascent_science-0.1.0/README.md

@@ -0,0 +1,23 @@
+# Ascent Science Python SDK
+
+The SDK is the supported Python client for an Ascent Science server. It does
+not install solver runtimes locally.
+
+```python
+from ascent import Client
+
+client = Client(endpoint="http://127.0.0.1:8000/v1", api_key="asc_live_...")
+job = client.algorithms.submit(
+    "GraphColoring",
+    inputs={"data_size": 32},
+    parameters={"nodes": 12, "edge_density": 0.2},
+    idempotency_key="graph-demo-1",
+)
+result = job.wait(timeout=60)
+print(result.result)
+```
+
+`ASCENT_ENDPOINT` and `ASCENT_API_KEY` can be used instead of constructor
+arguments. API keys are created in an authenticated browser session and shown
+only once.
+

ascent_science-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ascent-science"
+version = "0.1.0"
+description = "Python SDK for the Ascent Science algorithm and evidence platform"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "LicenseRef-Proprietary"
+authors = [{name = "Ascent Science"}]
+classifiers = [
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+  "Typing :: Typed",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+ascent = ["py.typed"]

ascent_science-0.1.0/setup.cfg

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

ascent_science-0.1.0/src/ascent/__init__.py

@@ -0,0 +1,38 @@
+"""Public interface for the Ascent Science Python SDK."""
+
+from .async_client import AsyncClient, AsyncJob
+from .client import Client, Job
+from .errors import (
+    AscentError,
+    AuthenticationError,
+    JobFailedError,
+    JobTimeoutError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+from .models import JobResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AscentError",
+    "AsyncClient",
+    "AsyncJob",
+    "AuthenticationError",
+    "Client",
+    "Job",
+    "JobFailedError",
+    "JobResult",
+    "JobTimeoutError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServerError",
+    "TransportError",
+    "ValidationError",
+    "__version__",
+]

ascent_science-0.1.0/src/ascent/_transport.py

@@ -0,0 +1,86 @@
+"""Small JSON HTTP transport built on the Python standard library."""
+
+from __future__ import annotations
+
+import json
+import socket
+from urllib.error import HTTPError, URLError
+from urllib.parse import urlencode
+from urllib.request import Request, urlopen
+
+from .errors import (
+    AuthenticationError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    ValidationError,
+)
+
+
+ERROR_TYPES = {
+    400: ValidationError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ValidationError,
+    422: ValidationError,
+    429: RateLimitError,
+}
+
+
+class JsonTransport:
+    def __init__(self, endpoint, api_key, timeout=30.0, user_agent="ascent-science-python/0.1.0"):
+        endpoint = str(endpoint).strip().rstrip("/")
+        if not endpoint.startswith(("http://", "https://")):
+            raise ValueError("endpoint must start with http:// or https://")
+        if not api_key:
+            raise ValueError("api_key is required")
+        self.endpoint = endpoint
+        self.api_key = str(api_key)
+        self.timeout = float(timeout)
+        self.user_agent = user_agent
+
+    def request(self, method, path, *, payload=None, query=None, headers=None, timeout=None):
+        url = self.endpoint + "/" + path.lstrip("/")
+        if query:
+            url += "?" + urlencode(query)
+        body = None
+        request_headers = {
+            "Accept": "application/json",
+            "Authorization": "Bearer " + self.api_key,
+            "User-Agent": self.user_agent,
+        }
+        if payload is not None:
+            body = json.dumps(payload, ensure_ascii=False, allow_nan=False).encode("utf-8")
+            request_headers["Content-Type"] = "application/json"
+        request_headers.update(headers or {})
+        request = Request(url, data=body, method=method, headers=request_headers)
+        try:
+            with urlopen(request, timeout=self.timeout if timeout is None else timeout) as response:
+                raw = response.read()
+                return json.loads(raw.decode("utf-8")) if raw else None
+        except HTTPError as error:
+            try:
+                raw = error.read()
+            finally:
+                error.close()
+            try:
+                response = json.loads(raw.decode("utf-8")) if raw else {}
+            except (UnicodeDecodeError, json.JSONDecodeError):
+                response = {}
+            detail = response.get("error", response)
+            if isinstance(detail, dict):
+                message = detail.get("message") or detail.get("code") or str(detail)
+                details = detail.get("details")
+                request_id = detail.get("request_id") or error.headers.get("X-Request-Id")
+            else:
+                message, details = str(detail or error.reason), None
+                request_id = error.headers.get("X-Request-Id")
+            exception_type = ERROR_TYPES.get(error.code, ServerError if error.code >= 500 else TransportError)
+            raise exception_type(
+                message, status_code=error.code, request_id=request_id, details=details
+            ) from None
+        except (URLError, socket.timeout, TimeoutError, OSError) as error:
+            raise TransportError("Unable to reach Ascent endpoint: %s" % error) from error

ascent_science-0.1.0/src/ascent/async_client.py

@@ -0,0 +1,106 @@
+"""Async facade for applications using asyncio."""
+
+from __future__ import annotations
+
+import asyncio
+
+from .client import Client
+
+
+class AsyncJob:
+    def __init__(self, job):
+        self._job = job
+
+    async def refresh(self):
+        await asyncio.to_thread(self._job.refresh)
+        return self
+
+    async def cancel(self):
+        await asyncio.to_thread(self._job.cancel)
+        return self
+
+    async def logs(self, *, after=0, limit=200):
+        return await asyncio.to_thread(self._job.logs, after=after, limit=limit)
+
+    async def wait(self, *, timeout=None, poll_interval=0.25, max_interval=3.0):
+        return await asyncio.to_thread(
+            self._job.wait, timeout=timeout, poll_interval=poll_interval, max_interval=max_interval
+        )
+
+    def __getattr__(self, name):
+        return getattr(self._job, name)
+
+
+class AsyncAlgorithmsResource:
+    def __init__(self, resource):
+        self._resource = resource
+
+    async def list(self):
+        return await asyncio.to_thread(self._resource.list)
+
+    async def retrieve(self, name):
+        return await asyncio.to_thread(self._resource.retrieve, name)
+
+    async def submit(self, algorithm, **kwargs):
+        return AsyncJob(await asyncio.to_thread(self._resource.submit, algorithm, **kwargs))
+
+
+class AsyncJobsResource:
+    def __init__(self, resource):
+        self._resource = resource
+
+    async def list(self, *, limit=30):
+        jobs = await asyncio.to_thread(self._resource.list, limit=limit)
+        return [AsyncJob(job) for job in jobs]
+
+    async def retrieve(self, job_id):
+        return AsyncJob(await asyncio.to_thread(self._resource.retrieve, job_id))
+
+
+class AsyncPipelinesResource:
+    def __init__(self, resource):
+        self._resource = resource
+
+    async def submit(self, algorithms, data, **kwargs):
+        job = await asyncio.to_thread(self._resource.submit, algorithms, data, **kwargs)
+        return AsyncJob(job)
+
+
+class AsyncExperimentsResource:
+    def __init__(self, resource):
+        self._resource = resource
+
+    async def list(self, *, limit=30):
+        return await asyncio.to_thread(self._resource.list, limit=limit)
+
+    async def retrieve(self, experiment_id):
+        return await asyncio.to_thread(self._resource.retrieve, experiment_id)
+
+
+class AsyncEvidenceResource:
+    def __init__(self, resource):
+        self._resource = resource
+
+    async def bundle(self):
+        return await asyncio.to_thread(self._resource.bundle)
+
+
+class AsyncClient:
+    """Async facade with the same configuration as :class:`Client`."""
+
+    def __init__(self, **kwargs):
+        self._client = Client(**kwargs)
+        self.algorithms = AsyncAlgorithmsResource(self._client.algorithms)
+        self.jobs = AsyncJobsResource(self._client.jobs)
+        self.pipelines = AsyncPipelinesResource(self._client.pipelines)
+        self.experiments = AsyncExperimentsResource(self._client.experiments)
+        self.evidence = AsyncEvidenceResource(self._client.evidence)
+
+    async def close(self):
+        await asyncio.to_thread(self._client.close)
+
+    async def __aenter__(self):
+        return self
+
+    async def __aexit__(self, *args):
+        await self.close()

ascent_science-0.1.0/src/ascent/client.py

@@ -0,0 +1,167 @@
+"""Synchronous Ascent Science client and resource objects."""
+
+from __future__ import annotations
+
+import os
+import random
+import time
+from urllib.parse import quote
+
+from ._transport import JsonTransport
+from .errors import JobFailedError, JobTimeoutError
+from .models import JobResult
+
+
+class Job:
+    def __init__(self, client, value):
+        self._client = client
+        self._value = JobResult.from_dict(value)
+
+    def _replace(self, value):
+        self._value = JobResult.from_dict(value)
+        return self
+
+    def refresh(self):
+        return self._replace(self._client._request("GET", "jobs/" + self.id)["job"])
+
+    def cancel(self):
+        return self._replace(self._client._request("POST", "jobs/" + self.id + "/cancel", payload={})["job"])
+
+    def logs(self, *, after=0, limit=200):
+        return self._client._request("GET", "jobs/" + self.id + "/logs", query={"after": after, "limit": limit})["logs"]
+
+    def wait(self, *, timeout=None, poll_interval=0.25, max_interval=3.0):
+        deadline = None if timeout is None else time.monotonic() + float(timeout)
+        delay = max(0.05, float(poll_interval))
+        while True:
+            self.refresh()
+            if self.done:
+                if self.status == "succeeded":
+                    return self._value
+                if self.status == "timed_out":
+                    raise JobTimeoutError(self.error or "The server-side job timed out.")
+                raise JobFailedError(self.error or "Job ended with status %s." % self.status)
+            if deadline is not None and time.monotonic() >= deadline:
+                raise JobTimeoutError("Timed out while waiting for job %s." % self.id)
+            remaining = None if deadline is None else max(0.0, deadline - time.monotonic())
+            sleep_for = delay + random.uniform(0.0, min(0.1, delay / 4))
+            time.sleep(sleep_for if remaining is None else min(sleep_for, remaining))
+            delay = min(float(max_interval), delay * 1.5)
+
+    def __getattr__(self, name):
+        try:
+            return getattr(self._value, name)
+        except AttributeError:
+            raise AttributeError(name) from None
+
+    def __repr__(self):
+        return "Job(id=%r, status=%r)" % (self.id, self.status)
+
+
+class AlgorithmsResource:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self):
+        return self._client._request("GET", "algorithms")["categories"]
+
+    def retrieve(self, name):
+        return self._client._request("GET", "algorithms/" + quote(str(name), safe=""))
+
+    def submit(
+        self,
+        algorithm,
+        *,
+        inputs=None,
+        parameters=None,
+        execution=None,
+        dataset_version_id=None,
+        idempotency_key=None
+    ):
+        payload = {
+            "kind": "algorithm",
+            "algorithm": algorithm,
+            "input": inputs or {},
+            "parameters": parameters or {},
+            "execution": execution or {},
+        }
+        if dataset_version_id:
+            payload["dataset_version_id"] = dataset_version_id
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        response = self._client._request("POST", "jobs", payload=payload, headers=headers)
+        return Job(self._client, response["job"])
+
+
+class JobsResource:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, *, limit=30):
+        return [Job(self._client, item) for item in self._client._request("GET", "jobs", query={"limit": limit})["jobs"]]
+
+    def retrieve(self, job_id):
+        return Job(self._client, self._client._request("GET", "jobs/" + str(job_id))["job"])
+
+
+class PipelinesResource:
+    def __init__(self, client):
+        self._client = client
+
+    def submit(self, algorithms, data, *, iterations=50, execution=None, idempotency_key=None):
+        headers = {"Idempotency-Key": idempotency_key} if idempotency_key else None
+        response = self._client._request(
+            "POST",
+            "jobs",
+            payload={
+                "kind": "pipeline",
+                "input": {"algorithms": list(algorithms), "data": list(data), "iterations": iterations},
+                "execution": execution or {},
+            },
+            headers=headers,
+        )
+        return Job(self._client, response["job"])
+
+
+class ExperimentsResource:
+    def __init__(self, client):
+        self._client = client
+
+    def list(self, *, limit=30):
+        return self._client._request("GET", "experiments", query={"limit": limit})["experiments"]
+
+    def retrieve(self, experiment_id):
+        return self._client._request("GET", "experiments/" + str(experiment_id))
+
+
+class EvidenceResource:
+    def __init__(self, client):
+        self._client = client
+
+    def bundle(self):
+        return self._client._request("GET", "evidence")
+
+
+class Client:
+    """Client for the versioned Ascent HTTP API."""
+
+    def __init__(self, *, endpoint=None, api_key=None, timeout=30.0):
+        endpoint = endpoint or os.environ.get("ASCENT_ENDPOINT", "http://127.0.0.1:8000/v1")
+        api_key = api_key or os.environ.get("ASCENT_API_KEY") or os.environ.get("ASCENT_TOKEN")
+        self._transport = JsonTransport(endpoint, api_key, timeout=timeout)
+        self.algorithms = AlgorithmsResource(self)
+        self.jobs = JobsResource(self)
+        self.pipelines = PipelinesResource(self)
+        self.experiments = ExperimentsResource(self)
+        self.evidence = EvidenceResource(self)
+
+    def _request(self, method, path, **kwargs):
+        return self._transport.request(method, path, **kwargs)
+
+    def close(self):
+        return None
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

ascent_science-0.1.0/src/ascent/errors.py

@@ -0,0 +1,48 @@
+"""Public SDK exception hierarchy."""
+
+
+class AscentError(Exception):
+    """Base class for all SDK errors."""
+
+    def __init__(self, message, *, status_code=None, request_id=None, details=None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.request_id = request_id
+        self.details = details
+
+
+class AuthenticationError(AscentError):
+    pass
+
+
+class PermissionDeniedError(AscentError):
+    pass
+
+
+class NotFoundError(AscentError):
+    pass
+
+
+class ValidationError(AscentError):
+    pass
+
+
+class RateLimitError(AscentError):
+    pass
+
+
+class ServerError(AscentError):
+    pass
+
+
+class TransportError(AscentError):
+    pass
+
+
+class JobFailedError(AscentError):
+    pass
+
+
+class JobTimeoutError(AscentError):
+    pass
+

ascent_science-0.1.0/src/ascent/models.py

@@ -0,0 +1,56 @@
+"""Typed response objects exposed by the SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+TERMINAL_JOB_STATUSES = frozenset({"succeeded", "failed", "cancelled", "timed_out"})
+
+
+@dataclass(frozen=True)
+class JobResult:
+    id: str
+    kind: str
+    status: str
+    payload: Dict[str, Any]
+    result: Optional[Dict[str, Any]]
+    error: Optional[str]
+    created_at: str
+    started_at: Optional[str]
+    completed_at: Optional[str]
+    raw: Dict[str, Any]
+
+    @classmethod
+    def from_dict(cls, value):
+        return cls(
+            id=value["id"],
+            kind=value["kind"],
+            status=value["status"],
+            payload=value.get("payload") or {},
+            result=value.get("result"),
+            error=value.get("error"),
+            created_at=value["created_at"],
+            started_at=value.get("started_at"),
+            completed_at=value.get("completed_at"),
+            raw=dict(value),
+        )
+
+    @property
+    def done(self):
+        return self.status in TERMINAL_JOB_STATUSES
+
+    @property
+    def experiment(self):
+        return (self.result or {}).get("experiment")
+
+    @property
+    def output(self):
+        return (self.result or {}).get("output")
+
+    @property
+    def fingerprint(self):
+        experiment = self.experiment or {}
+        return experiment.get("fingerprint") or experiment.get("request_fingerprint")
+

ascent_science-0.1.0/src/ascent/py.typed

@@ -0,0 +1 @@
+

ascent_science-0.1.0/src/ascent_science.egg-info/PKG-INFO

@@ -0,0 +1,35 @@
+Metadata-Version: 2.4
+Name: ascent-science
+Version: 0.1.0
+Summary: Python SDK for the Ascent Science algorithm and evidence platform
+Author: Ascent Science
+License-Expression: LicenseRef-Proprietary
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# Ascent Science Python SDK
+
+The SDK is the supported Python client for an Ascent Science server. It does
+not install solver runtimes locally.
+
+```python
+from ascent import Client
+
+client = Client(endpoint="http://127.0.0.1:8000/v1", api_key="asc_live_...")
+job = client.algorithms.submit(
+    "GraphColoring",
+    inputs={"data_size": 32},
+    parameters={"nodes": 12, "edge_density": 0.2},
+    idempotency_key="graph-demo-1",
+)
+result = job.wait(timeout=60)
+print(result.result)
+```
+
+`ASCENT_ENDPOINT` and `ASCENT_API_KEY` can be used instead of constructor
+arguments. API keys are created in an authenticated browser session and shown
+only once.
+

ascent_science-0.1.0/src/ascent_science.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/ascent/__init__.py
+src/ascent/_transport.py
+src/ascent/async_client.py
+src/ascent/client.py
+src/ascent/errors.py
+src/ascent/models.py
+src/ascent/py.typed
+src/ascent_science.egg-info/PKG-INFO
+src/ascent_science.egg-info/SOURCES.txt
+src/ascent_science.egg-info/dependency_links.txt
+src/ascent_science.egg-info/top_level.txt

ascent_science-0.1.0/src/ascent_science.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ascent_science-0.1.0/src/ascent_science.egg-info/top_level.txt

@@ -0,0 +1 @@
+ascent