Metadata-Version: 2.1
Name: easyaskcos
Version: 2.1.0
Summary: Python wrapper for the ASKCOS API
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
Requires-Dist: requests
Requires-Dist: dynaconf
Requires-Dist: pyyaml
Requires-Dist: pydantic
Provides-Extra: dev
Requires-Dist: bumpver; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: isort; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"

EasyAskcos
=======================================

Python wrapper for the ASKCOS API

Installation
------------

Installing this package depends on a working `installation of Python`_ with pip.
To install the package, run:

.. code-block:: shell

   pip install git+ssh://git@github.com:syngenta/EasyAskcos.git

.. _installation of Python: https://www.python.org/downloads/

For Development
---------------

When working on the development of this package, the developer wants to work
directly on the source code while still using the packaged installation. For
that, run:

.. code-block:: shell

   git clone git@github.com:syngenta/EasyAskcos.git
   pip install -e easyaskcos/[dev]

Configuration
---------------

This package requires some configuration parameters to work,
including some secretes and settings.
After installation, and before the first usage, the useR should run the following command


.. code-block:: shell

   easyaskcos_configure

this command generates the user_home/easyaskcos directory and places into it two files:

(1) settings.toml populated with defaults settings. The user can review and modify these values if necessary
(2) .secrets.toml containing the keys for the necessary secrets. The user must replace the placeholders with the correct values


Usage: ASKCOS V1
------------------

Let's initialize the wrapper.

.. code-block:: python

    from easyaskcos.wrapper import AskcosWrapper

    wrapper = AskcosWrapper()

It will connect to the url provided in the settings file, however it is possible to define a different base url by indicating it during the initialization of the wrapper

.. code-block:: python

    from easyaskcos.wrapper import AskcosWrapper

    wrapper = AskcosWrapper(base_url="https://some.server")

Now it is possible to access various endpoints provided by the Askcos API
in a simple and straightforward manner.

Perform prediction for retrosynthetic trees

.. code-block:: python

    response = wrapper.predict_retrosynthetic_tree("CCC(O)=O")
    # to check the status of the response
    prediction_id = response["prediction_id"]
    results = wrapper.get_results(prediction_id)
    print(results["status"])
    # upon "SUCCESS", the results can be inspected
    retrosynthetic_trees = results["output"]

To inspect the available template sets for the retrosynthetic predictions

.. code-block:: python

    sets = wrapper.list_template_sets()

Each string in the returned list can be assigned to the "template_set" argument of the
"predict_retrosynthetic_tree" method; by default the "reaxys" template is used.

.. code-block:: python

    response = wrapper.predict_retrosynthetic_tree("CCC(O)=O", template_set="pistachio")

Perform prediction for chemical reactions

.. code-block:: python

    response = wrapper.predict_forward("CC(=O)c1cc(Cl)ccc1Oc1ccc(Cl)cc1Cl.O=C(OO)c1cccc(Cl)c1")
    # to check the status of the response
    prediction_id = response["prediction_id"]
    results = wrapper.get_results(prediction_id)
    print(results["status"])
    # upon "SUCCESS", the results can be inspected
    reactions = results["output"]


Usage: ASKCOS V2
------------------

With the release of the new ASKCOS V2 platform, that soon will completely
replace the previous version, we included in this package also the SDK for the new version.
The usage remain overall very similar to how it is for version 1, starting
with the initialization of the wrapper:

.. code-block:: python

    from easyaskcos.wrapper import AskcosWrapperV2

    wrapper = AskcosWrapperV2()


Also in this case it will automatically connect to the url provided in the settings file, but it is always possible
to specify a different base url as follows:

.. code-block:: python

    from easyaskcos.wrapper import AskcosWrapperV2

    wrapper = AskcosWrapperV2(base_url="https://some.server")


Some endpoints of ASKCOS V2 require authentication. In order to get the token necessary to access
these endpoints, you need to define your username and password for the ASKCOS V2 platform.
This can be done either by adding this information in the .secrets.yaml file created by the initial
configuration, or by passing these arguments while instantiating the wrapper.

.. code-block:: python

    from easyaskcos.wrapper import AskcosWrapperV2

    wrapper = AskcosWrapperV2(user_name="my_username",
                              password="my_password")


For example, the endpoint for searching retrosynthetic trees for a given target molecule
in an asynchronous way, requires the authentication. If you included the necessary credentials
in the settings or while instantiating the wrapper, EasyAskcos will take care of handling
the authentication for you:

.. code-block:: python

    from easyaskcos.wrapper import AskcosWrapperV2

    wrapper = AskcosWrapperV2(user_name="my_username",
                              password="my_password")
    # Retrieve the task ID associated with your prediction
    task_id = wrapper.predict_retrosynthetic_tree_async("CCC(O)=O")
    # Retrieve the results
    results = wrapper.get_results(task_id)
    print(results["status"])
    # upon "SUCCESS", the results can be inspected
    reactions = results["response"]["output"]

In the new version of ASKCOS, There is also an endpoint for retrosynthetic
predictions that works synchronously, which does not require authentication.
So you will need to just run:


.. code-block:: python

    from easyaskcos.wrapper import AskcosWrapperV2

    results = wrapper.predict_retrosynthetic_tree("CCC(O)=O")


The endpoints for the other types of predictions
(forward, impurities and reaction conditions) are still asynchronous:

.. code-block:: python

    task_id = wrapper.predict_forward([
                    "CS(=N)(=O)Cc1cccc(Br)c1.Nc1cc(Br)ccn1",
                    "CCO.CC(=O)O"
                  ],)

    results = wrapper.get_results(task_id)
    print(results["status"])
    # upon "SUCCESS", the results can be inspected
    reactions = results["response"]["output"]
