pendingai 0.0.1__tar.gz

pendingai-0.0.1/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.1
+Name: pendingai
+Version: 0.0.1
+Summary: Pending AI CLI Cheminformatics Platform tool
+Author: Pending AI
+Author-email: support@pending.ai
+Requires-Python: >=3.8.0,<4.0.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: httpx (>=0.27.2,<0.28.0)
+Requires-Dist: pydantic (>=2.7.1,<3.0.0)
+Requires-Dist: typer[all] (>=0.12.3,<0.13.0)
+Description-Content-Type: text/markdown
+
+# Pending.ai CLI
+
+Owner: @JBercich
+
+Command-line tool for using the Pending.ai Cheminformatics Platform.
+
+- [`retro`](#retrosynthesis-platform) - Molecule retrosynthesis using machine-learning MCTS inference for generating synthesis routes.
+
+## Getting Started
+
+> [!NOTE]
+> The pending.ai CLI will soon be available on PyPi.
+
+### Build from Source
+
+The CLI tool can be built using the `poetry` build tool. Clone the repository locally
+and install the package for immediate use.
+
+```shell
+git clone https://github.com/pendingai/pendingai-cli.git
+cd pendingai-cli
+pip install poetry
+poetry build
+poetry install
+```
+
+The CLI can be used by now running `pendingai --help` to display the available commands.
+
+```shell
+pendingai --version
+> 0.0.1
+```
+
+### Authenticating the Client
+
+> [!WARNING]
+> To authenticate against different environments, use `pendingai --env <envname> login`
+> to generate access tokens for different authenticate tenants.
+
+Authorised platform access requires a valid set of user credentials. You can register a
+device code using `pendingai login` to retrieve and cache an access token to use the
+different services.
+
+### Retrosynthesis Platform
+
+```shell
+pendingai retro --help
+```
+
+The Pending.ai retrosynthesis service requires authentication credentials with attached
+billing information to submit query molecules for synthesis. You will be notified if the
+billed `query` request fails with no charge.
+
+Below are some typical use cases:
+
+```shell
+# Inspect available engines and libraries for synthesis requests
+pendingai retro engines
+pendingai retro libraies
+
+# Submit a query molecule and inspect the results
+pendingai retro query --smi <molecule>
+pendingai retro status --id <query-id>
+pendingai retro view --id <query-id> --json > result.json
+
+# Submit a file batch of results
+pendingai retro query --batch-file <smi-filepath>
+pendingai retro status --batch-file <ids-filepath>
+pendingai retro view --batch-file <ids-filepath> --json > results.json
+```
+

pendingai-0.0.1/README.md

@@ -0,0 +1,70 @@
+# Pending.ai CLI
+
+Owner: @JBercich
+
+Command-line tool for using the Pending.ai Cheminformatics Platform.
+
+- [`retro`](#retrosynthesis-platform) - Molecule retrosynthesis using machine-learning MCTS inference for generating synthesis routes.
+
+## Getting Started
+
+> [!NOTE]
+> The pending.ai CLI will soon be available on PyPi.
+
+### Build from Source
+
+The CLI tool can be built using the `poetry` build tool. Clone the repository locally
+and install the package for immediate use.
+
+```shell
+git clone https://github.com/pendingai/pendingai-cli.git
+cd pendingai-cli
+pip install poetry
+poetry build
+poetry install
+```
+
+The CLI can be used by now running `pendingai --help` to display the available commands.
+
+```shell
+pendingai --version
+> 0.0.1
+```
+
+### Authenticating the Client
+
+> [!WARNING]
+> To authenticate against different environments, use `pendingai --env <envname> login`
+> to generate access tokens for different authenticate tenants.
+
+Authorised platform access requires a valid set of user credentials. You can register a
+device code using `pendingai login` to retrieve and cache an access token to use the
+different services.
+
+### Retrosynthesis Platform
+
+```shell
+pendingai retro --help
+```
+
+The Pending.ai retrosynthesis service requires authentication credentials with attached
+billing information to submit query molecules for synthesis. You will be notified if the
+billed `query` request fails with no charge.
+
+Below are some typical use cases:
+
+```shell
+# Inspect available engines and libraries for synthesis requests
+pendingai retro engines
+pendingai retro libraies
+
+# Submit a query molecule and inspect the results
+pendingai retro query --smi <molecule>
+pendingai retro status --id <query-id>
+pendingai retro view --id <query-id> --json > result.json
+
+# Submit a file batch of results
+pendingai retro query --batch-file <smi-filepath>
+pendingai retro status --batch-file <ids-filepath>
+pendingai retro view --batch-file <ids-filepath> --json > results.json
+```

pendingai-0.0.1/pyproject.toml

@@ -0,0 +1,52 @@
+# pendingai-cli project configuration
+
+[tool.poetry]
+name = "pendingai"
+description = "Pending AI CLI Cheminformatics Platform tool"
+authors = ["Pending AI <support@pending.ai>"]
+readme = "README.md"
+version = "0.0.1" # See `pending_cli/__init__.py`
+
+[tool.poetry.dependencies]
+python = "^3.8.0"
+typer = { extras = ["all"], version = "^0.12.3" }
+pydantic = "^2.7.1"
+httpx = "^0.27.2"
+
+[tool.poetry.group.test.dependencies]
+pytest = "^8.1.1"
+
+[tool.poetry.scripts]
+# Adding an entry CLI command from a shell; naming can be changed by modifying the name
+# of the script (and requires changes in the top-level repository README.md) to align;
+# see typer docs for more info https://typer.tiangolo.com/tutorial/package/#add-a-script
+pendingai = "pendingai.main:cli"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.mypy]
+strict = false
+ignore_missing_imports = true
+no_implicit_optional = false
+
+[tool.interrogate]
+fail-under = 95
+ignore-module = true
+ignore-init-method = true
+ignore-init-module = true
+ignore-property-decorators = true
+quiet = false
+verbose = true
+
+[tool.ruff]
+line-length = 89
+indent-width = 4
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.ruff.lint.isort]
+combine-as-imports = true
+force-sort-within-sections = false

pendingai-0.0.1/src/pendingai/__init__.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+import enum
+import logging
+import logging.config
+import typing
+
+import httpx
+from rich.logging import RichHandler
+
+__appname__: str = "pendingai"
+__version__: str = "0.0.1"
+
+logging.basicConfig(
+    level=logging.WARNING,
+    format="%(name)s %(message)s",
+    datefmt="[%X]",
+    handlers=[RichHandler(tracebacks_suppress=[httpx])],
+)
+logging.getLogger("httpcore.connection").setLevel(logging.WARNING)
+logging.getLogger("httpcore.http11").setLevel(logging.WARNING)
+logging.getLogger("httpx").setLevel(logging.WARNING)
+
+
+@enum.unique
+class Environment(str, enum.Enum):
+    """
+    Deployment environment used for building client connection strings,
+    authentication flows for the device or refresh tokens, and controls
+    cached state data between different environments
+    """
+
+    DEVELOPMENT = "dev"
+    STAGING = "stage"
+    PRODUCTION = "prod"
+
+
+@enum.unique
+class Command(str, enum.Enum):
+    """
+    Runtime command used for naming commands and linking the client
+    service domain prefix.
+    """
+
+    DOCKING = "docking"
+    GENERATOR = "generator"
+    RETRO = "retro"
+    RETROGRAPH = "retrograph"
+
+
+__all__: typing.List[str] = ["__appname__", "__version_", "Environment", "Command"]

pendingai-0.0.1/src/pendingai/auth/__init__.py

@@ -0,0 +1,38 @@
+#!/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+import typing
+
+from pendingai import Environment
+from pendingai.auth.device_code import DeviceCode, DeviceCodeAuthorization
+
+# Environment-dependent constants are stored in dictionaries as runtime
+# app logic uses an environment input optional to control access to the
+# different resorce authentication tenants.
+
+
+class AuthenticationEnvironment:
+    """Container class for environment-dependent module constants."""
+
+    DOMAIN: typing.Dict[Environment, str] = {
+        Environment.DEVELOPMENT: "pendingai-dev.au.auth0.com",
+        Environment.STAGING: "pendingai-stage.au.auth0.com",
+        Environment.PRODUCTION: "pendingai.us.auth0.com",
+    }
+    CLIENT_ID: typing.Dict[Environment, str] = {
+        Environment.DEVELOPMENT: "GM1gfvGCnokIySbVO7vjmkRy4tVx5WYm",
+        Environment.STAGING: "PDWKoudtiP4WZV7aQt5YZbb5xlcmN6ju",
+        Environment.PRODUCTION: "dH69BCxGo4MyCcMWi64ZBq2YZx3UIoh1",
+    }
+    AUDIENCE: typing.Dict[Environment, str] = {
+        Environment.DEVELOPMENT: "api.dev.pending.ai/external-api",
+        Environment.STAGING: "api.stage.pending.ai/external-api",
+        Environment.PRODUCTION: "api.pending.ai/external-api",
+    }
+
+
+__all__: typing.List[str] = [
+    "AuthenticationEnvironment",
+    "DeviceCodeAuthorization",
+    "DeviceCode",
+]

pendingai-0.0.1/src/pendingai/auth/device_code.py

@@ -0,0 +1,194 @@
+#!/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+import datetime
+import time
+import typing
+import webbrowser
+
+import httpx
+import pydantic
+from rich.console import Console
+
+_MAX_RETRIES: int = 10
+
+std: Console = Console()
+
+
+class DeviceCode(pydantic.BaseModel):
+    """Device code access token data model."""
+
+    access_token: str
+    refresh_token: str
+    id_token: str
+    token_type: str
+    expires_in: int
+    scope: str
+
+    @pydantic.computed_field  # type: ignore
+    @property
+    def expires_at(self) -> int:
+        """Computed field `expires_at`. Requires `expires_in`."""
+        return int(
+            (
+                datetime.datetime.utcnow() + datetime.timedelta(seconds=self.expires_in)
+            ).timestamp()
+        )
+
+    def is_expired(self) -> bool:
+        """Check device code has reached `expires_at` timestamp."""
+        return self.expires_at < datetime.datetime.utcnow().timestamp()
+
+
+class DeviceCodeAuthorization:
+    """
+    Device code authentication is used wrapping the Auth0 sdk flow. The
+    class instance will immediately execute the authorization process if
+    given a valid domain, audience and client, retriving a device code
+    token and id/refresh tokens.
+
+    Args:
+        domain (str): Auth0 domain name for the authorization flow.
+        client_id (str): Application client id for a device code token.
+        audience (str): Application audience being authenticated.
+    """
+
+    _scopes: str = "openid profile email offline_access"
+    _grant_type: str = "urn:ietf:params:oauth:grant-type:device_code"
+
+    def __init__(self, *, domain: str, client_id: str, audience: str):
+        self._domain: str = domain
+        self._client_id: str = client_id
+        self._audience: str = audience
+
+    def _request_device_code(self) -> httpx.Response:
+        """
+        Request for a device code from Auth0. Scopes are defined at the
+        class level to include oidc response claims and an `id_token`,
+        and an `offline_access` scope to get a `refresh_token`.
+
+        Returns:
+            httpx.Response: Auth0 device code response.
+        """
+        return httpx.post(
+            url=f"https://{self._domain}/oauth/device/code",
+            data={
+                "client_id": self._client_id,
+                "audience": self._audience,
+                "scope": self._scopes,
+            },
+        )
+
+    def _request_access_code(self, device_code: str) -> httpx.Response:
+        """
+        Request for an access token from Auth0 using the device code
+        authorization flow. A `refresh_token` and `id_token` should also
+        be returned by Auth0.
+
+        Args:
+            device_code (str): Device code received from requesting the
+                authorization flow from Auth0.
+
+        Returns:
+            httpx.Response: Auth0 access token response.
+        """
+        return httpx.post(
+            url=f"https://{self._domain}/oauth/token",
+            data={
+                "client_id": self._client_id,
+                "audience": self._audience,
+                "grant_type": self._grant_type,
+                "device_code": device_code,
+            },
+        )
+
+    def _request_refresh_token(self, refresh_token: str) -> httpx.Response:
+        """
+        Request for a refresh token from Auth0 using the device code
+        authorization flow. A `refresh_token` and `id_token` should also
+        be returned by Auth0 from the token rotation setting.
+
+        Args:
+            refresh_token (str): Refresh token.
+
+        Returns:
+            httpx.Response: Auth0 refresh token response.
+        """
+        return httpx.post(
+            url=f"https://{self._domain}/oauth/token",
+            data={
+                "client_id": self._client_id,
+                "audience": self._audience,
+                "grant_type": "refresh_token",
+                "refresh_token": refresh_token,
+            },
+        )
+
+    def execute_flow(self) -> DeviceCode:
+        """
+        Execute the device code authentication flow to obtain a token.
+
+        Raises:
+            RuntimeError: Authentication failed due to tenant details.
+            RuntimeError: Authentication failed due to unknown errors.
+
+        Returns:
+            DeviceCode: New device code token.
+        """
+
+        # Generate the device code, request and process response
+        device_code_response: httpx.Response = self._request_device_code()
+        if device_code_response.status_code != 200:
+            raise RuntimeError("Failed authenticating device, unauthorized access")
+        device_code_data: typing.Dict[str, typing.Any] = device_code_response.json()
+
+        # Redirect to the authentication portal for the device
+        uri: str = device_code_data["verification_uri_complete"]
+        std.print("1. On your computer or mobile device navigate to: ", uri)
+        std.print("2. Enter the following code: ", device_code_data["user_code"])
+        time.sleep(2)
+        webbrowser.open(uri)
+
+        # Ping Auth0 for the access token requiring user authentication
+        retries: int = 0
+        authenticated: bool = False
+        device_code: str = device_code_data["device_code"]
+        while not authenticated:
+            if retries == _MAX_RETRIES:
+                std.print("Authentication timed out with maximum retries, try again.")
+                raise RuntimeError("Maximum retries timed out device authorization")
+            std.print("Checking for completed device authentication...")
+            access_code_response: httpx.Response = self._request_access_code(device_code)
+            if access_code_response.status_code == 200:
+                authenticated = True
+                std.print("Successfully logged into the Pending.ai Platform")
+                return DeviceCode.model_validate(access_code_response.json())
+            else:
+                error_data: typing.Dict[str, typing.Any] = access_code_response.json()
+                if error_data["error"] == "authorization_pending":
+                    time.sleep(device_code_data["interval"])
+                    retries += 1
+                    continue
+                raise RuntimeError(error_data["error_description"])
+        raise RuntimeError("Unable to authenticate user")
+
+    def refresh_token(self, refresh_token: str) -> DeviceCode:
+        """
+        Execute the refresh token authentication flow to obtain a token.
+
+        Args:
+            refresh_token (str): Refresh token being refreshed.
+
+        Returns:
+            DeviceCode: New device code token.
+        """
+        refresh_response: httpx.Response = self._request_refresh_token(refresh_token)
+        try:
+            if refresh_response.status_code == 200:
+                return DeviceCode.model_validate(refresh_response.json())
+        except pydantic.ValidationError:
+            pass
+        raise RuntimeError("Failed to refresh access token")
+
+
+__all__: typing.List[str] = ["DeviceCode", "DeviceCodeAuthorization"]

pendingai-0.0.1/src/pendingai/client/__init__.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+import typing
+
+from pendingai import Command, Environment
+from pendingai.client.client import Client
+
+# Environment-dependent constants are stored in dictionaries as runtime
+# app logic uses an environment input optional to control access to the
+# different resorce client domains.
+
+
+class ClientEnvironment:
+    """Container class for environment-dependent module constants."""
+
+    DOMAIN: typing.Dict[Environment, str] = {
+        Environment.DEVELOPMENT: "https://api.dev.pending.ai/",
+        Environment.STAGING: "https://api.stage.pending.ai/",
+        Environment.PRODUCTION: "https://api.pending.ai/",
+    }
+    SERVICE_DOMAIN: typing.Dict[Command, str] = {
+        Command.DOCKING: "/docking/v1/",
+        Command.GENERATOR: "/generator/v1/",
+        Command.RETRO: "/retro/v2/",
+        Command.RETROGRAPH: "/retrograph/v1/",
+    }
+
+
+__all__: typing.List[str] = ["ClientEnvironment", "Client"]

pendingai-0.0.1/src/pendingai/client/client.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+import typing
+from urllib.parse import urljoin
+
+import httpx
+
+
+class Client:
+    """
+    HTTPX client wrapper class for controlling requests to the external
+    service APIs. Basic method control is managed through http methods
+    for a specified domain determined by the app runtime environment.
+
+    Args:
+        domain (str): Environment-dependent app domain url.
+        service_domain (str): Service prefix domain and version.
+        access_token (str, optional): Token for authenticated requests.
+    """
+
+    _timeout: int = 10
+
+    def __init__(
+        self,
+        *,
+        domain: str,
+        service_domain: str,
+        access_token: typing.Optional[str] = None,
+    ):
+        self._domain: str = domain
+        self._service_domain: str = service_domain
+        self._access_token: typing.Optional[str] = access_token
+        self._client: httpx.Client = self._setup_client()
+
+    def _setup_client(self) -> httpx.Client:
+        """
+        Initialisation of the HTTPX client instance for the specific
+        service domain. The optional access token header can be given
+        as the header fields used in all requests to the domain.
+
+        Returns:
+            httpx.Client: Initialised HTTPX client instance.
+        """
+        headers: typing.Dict[str, str] = {}
+        if self._access_token is not None:
+            headers["Authorization"] = f"Bearer {self._access_token}"
+        url: str = urljoin(self._domain, self._service_domain)
+        return httpx.Client(base_url=url, headers=headers, timeout=self._timeout)
+
+    def __del__(self) -> None:
+        """Client connection is closed once the instance is OOM."""
+        self._client.close()
+
+    def get(self, *args, **kwargs) -> httpx.Response:
+        """Client method wrapper for making a `GET` request."""
+        return self._client.get(*args, **kwargs)
+
+    def post(self, *args, **kwargs) -> httpx.Response:
+        """Client method wrapper for making a `POST` request."""
+        return self._client.post(*args, **kwargs)
+
+    def patch(self, *args, **kwargs) -> httpx.Response:
+        """Client method wrapper for making a `PATCH` request."""
+        return self._client.patch(*args, **kwargs)
+
+    def put(self, *args, **kwargs) -> httpx.Response:
+        """Client method wrapper for making a `PUT` request."""
+        return self._client.put(*args, **kwargs)
+
+    def delete(self, *args, **kwargs) -> httpx.Response:
+        """Client method wrapper for making a `DELETE` request."""
+        return self._client.delete(*args, **kwargs)
+
+    def options(self, *args, **kwargs) -> httpx.Response:
+        """Client method wrapper for making a `OPTIONS` request."""
+        return self._client.options(*args, **kwargs)
+
+    def head(self, *args, **kwargs) -> httpx.Response:
+        """Client method wrapper for making a `HEAD` request."""
+        return self._client.head(*args, **kwargs)
+
+
+__all__: typing.List[str] = ["Client"]

pendingai-0.0.1/src/pendingai/commands/__init__.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+# -*- coding:utf-8 -*-
+
+import typing
+
+import httpx
+import typer
+from rich.console import Console
+
+from pendingai import Command
+from pendingai.client import Client, ClientEnvironment
+
+std: Console = Console()
+
+
+def add_client_callback(ctx: typer.Context):
+    """
+    Auxiliary callback method for calling command callback methods with
+    a static service domain determined by the `Command` set in `main.py`
+    and verified access permission by hitting the service `/alive`.
+
+    Args:
+        ctx (typer.Context): App runtime context.
+    """
+    command: Command = Command._value2member_map_[ctx.command.name]  # type: ignore
+    ctx.obj.client = Client(
+        domain=ClientEnvironment.DOMAIN[ctx.obj.environment],
+        service_domain=ClientEnvironment.SERVICE_DOMAIN[command],
+        access_token=ctx.obj.access_token,
+    )
+    response: httpx.Reponse = ctx.obj.client.get("/alive")
+    if response.status_code != 200:
+        std.print(
+            f"User is not authorized for the '{ctx.command.name}' Platform. "
+            + "Try logging in again. If the problem is unexpected, contact support "
+            + "services (see <pendingai --help>).",
+            width=90,
+            highlight=False,
+        )
+        raise typer.Exit(2)
+
+
+__all__: typing.List[str] = ["add_client_callback"]