<!--
For screenshots to look good, they should be small and ideally
all the same size. The script below lets you open the URLs in
the right size. Just paste this into the browser console and
press enter.
To take the screenshots with browser UI included on Mac, press
cmd+shift+4 followed by the spacebar, then click the window.
For consistency, stick to Chrome.
- - -
urls = [
'https://cps.foc-deepsearch.zurich.ibm.com',
'https://rxn.app.accelerate.science',
'https://sds.app.accelerate.science',
]
for (var i=0; i< urls.length; i++) {
window.open(urls[i], '_blank', 'width=1000,height=600');
}
-->
# Open Accelerated Discovery <!-- omit from toc -->
[](https://pypi.org/project/openad/)
[](https://pypi.org/project/openad/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://acceleratedscience.github.io/openad-docs/)
<br>
<!-- description -->
OpenAD is an open-source framework for molecular and materials discovery developed by IBM Research.
The OpenAD client is accessible from a command line interface, Jupyter Notebook and an API. It provides unified access to a variety of tools and AI models for literature knowledge extraction, forward and retrosynthesis prediction, generative methods and property inference. You can train models on your own data as well as visualize and filter candidate molecules.
<!-- /description -->
[Documentation](https://acceleratedscience.github.io/openad-docs/)
<br>
### See What's New <!-- omit from toc -->
<details>
<summary>See what's new in OpenAD</summary>
<div markdown="block">
- `%Openadd` has been added to the magic commands for commands that return data.
- New Macro Molecule viewer for visualising proteins
- Upgraded SkyPilot to 0.6.0
- Support for deploying in OpenShift AI/Open Data hub workbench or Podman/Docker image. [See the workbench repo](https://github.com/acceleratedscience/openad_workbench).
- Support for application API
- New property and dataset generation services.<br>We currently support the following model services:
- GT4SD Generation Services `git@github.com:acceleratedscience/generation_inference_service.git`
- GT4SD Property Services `git@github.com:acceleratedscience/property_inference_service.git`
- GT4SD MoleR Generation `git@github.com:acceleratedscience/moler_inference_service.git`
- GT4SD Molformer `git@github.com:acceleratedscience/molformer_inference_service.git`
Pre-Requisite is that you have a AWS Account and can launch your own EC2 Instances Or someone else can launch them for you and you can catalog a Remote Service via URL.
**Example:**
- Install a service
catalog model service from 'git@github.com:acceleratedscience/property_inference_service.git' as prop
- Start the service
model service up prop
- Wait until the service is ready
model service status
- Once the service is ready, you can run the following commands to test:
```
prop get molecule property [qed,esol] for [ C(C(C1C(=C(C(=O)O1)O)O)O)O ,[H-] ]
```
```
prop get molecule property esol for C(C(C1C(=C(C(=O)O1)O)O)O)O
```
- Examples are supplied in the sample Notebooks.<br>See `init_examples` under the [Jupyter installation instructions](#setting-up-jupyter) below for more information.
- To shut down the service
model service down prop
- Available commands for managing model services...
model service status
model service config <service_name>
model catalog list
uncatalog model service <service_name>
catalog model service from (remote) '<path or github>' as <service_name>
model service up <service_name> [no_gpu]
model service local up <service_name>
model service down <service_name>
</div>
</details>
<br>
### Before You Start <!-- omit from toc -->
<details>
<summary>Things you should know</summary>
<div markdown="block">
- OpenAD is available for Linux and MacOS
- We support Windows 11 via WSL 2 (ubuntu 22.04) - see [Installing on Windows](#installing-on-windows)
- When not installing into a virtual environment on MacOS, you may need to use `python3` and `pip3` instead of `python` and `pip` respectively
- When updating to 0.4.0 or above, first remove all toolkits by runnning `list toolkits` and then `remove toolkit <toolkit_name>`.
</div>
</details>
<br>
## Quick Install <!-- omit from toc -->
> **Note:** This will install OpenAD in your global space. If you wish to use a virtual environment, please see more [detailed instructions](#installation) below.
pip install openad
openad
Get started with Jupyter:
init_magic
init_examples
jupyter lab ~/openad_notebooks/Table_of_Contents.ipynb
If you get an error when running `init_magic`, you may first need to setup the default iPython profile for magic commands.
ipython profile create
<br>
---
<br>
## Table of Contents <!-- omit from toc -->
<!-- toc -->
- [Installation](#installation)
- [Getting Started - CLI](#getting-started---cli)
- [Getting Started - Jupyter](#getting-started---jupyter)
- [Setting up Jupyter](#setting-up-jupyter)
- [Launching OpenAD in Jupyter](#launching-openad-in-jupyter)
- [Interacting with the Toolkits](#interacting-with-the-toolkits)
- [Registration](#registration)
- [Adding a Toolkit](#adding-a-toolkit)
- [Sample Commands](#sample-commands)
- [Running Bash Commands (CLI)](#running-bash-commands-cli)
- [AI Assistant](#ai-assistant)
- [IBM BAM Setup](#ibm-bam-setup)
- [Ollama Setup](#ollama-setup)
- [Ollama Remote Setup with SkyPilot](#ollama-remote-setup-with-skypilot)
- [Run Ollama](#run-ollama)
- [Model Services](#model-services)
- [For Developers](#for-developers)
- [Installation for Development](#installation-for-development)
- [Testing a branch](#testing-a-branch)
- [Installing on Windows](#installing-on-windows)
- [Before You Start](#before-you-start)
- [Installing WSL](#installing-wsl)
- [Linux Notes](#linux-notes)
<!-- tocstop -->
<br>
---
<br>
<a name="installation"></a>
# Installation
> **Note:** Contributors should skip to [Installation for Development](#installation-for-development)
> **Note:** Linux users may want to check the [Linux Notes](#linux-notes)
> **Note:** If you prefer using poetry and you know what you're doing, you can skip the instructions below and run `poetry add openad` instead.
1. **Step 0: Before you start**<br>
Ensure you're running Python 3.10 or 3.11. There's multiple ways of updating Python, we'll use pyenv.
> **Note:** Due to an issue with one of our dependencies, Python 3.12 is not yet supported.
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
pyenv install 3.11
1. **Step 1: Set up your virtual environment** (optional)<br>
python3.11 -m venv ~/ad-venv
source ~/ad-venv/bin/activate
> **Note:** To exit the virtual environment, you can run `deactivate`
1. **Step 2: Installation**
pip install openad
<br>
# Getting Started - CLI
- **Enter the virtual environment**
> **Note:** If you just installed OpenAD, you probably already activated the virtual environment.
source ~/ad-venv/bin/activate
- **Enter the command shell**
openad
<!--  -->
<!-- <a href="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/screenshot-landing.png" target="_blank"><img src="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/screenshot-landing.png" /></a> -->
- **Exit the command shell**<br>
Hit `ctrl+c` or run:
exit
- **Run a single command from outside the command shell**
openad <command>
- **Exit the virtual environment**<br>
deactivate
<br>
# Getting Started - Jupyter
## Setting up Jupyter
The following commands only need to be run once after installation:
1. **Activate your virtual environment**
> **Note:** If you just installed OpenAD, you probably already activated the virtual environment.
source ~/ad-venv/bin/activate
1. **Create an iPython kernel**<br>
This ports your virtual environment to Jupyter.
python -m ipykernel install --user --name=ad-venv
> **Note:** To list your installed iPython kernels, you can run `jupyter kernelspec list`, and to remove the kernel you can run `jupyter kernelspec uninstall ad-venv`
1. **Install the magic commands**<br>
This enables OpenAD commands to be run within a Jupyter Notebook.
init_magic
<details>
<summary><b>Alternative:</b> Manually add magic commands</summary>
<div markdown="block">
If you don't want to activate magic commands in all Notebooks, you can instead activate them for individual Notebooks.
- Run `init_examples`
- Copy the file `~/openad_notebooks/openad.ipynb` to the same directory as the Notebook you wish to activate.
- In your Notebook, run this inside a code cell: `!run openad.ipynb`
</div>
</details>
1. **Install example Notebooks**<br>
This installs our example Notebooks at `~/openad_notebooks`.
init_examples
<br>
## Launching OpenAD in Jupyter
1. **Open any Notebook**<br>
The following command will open up the example Notebook:
jupyter lab ~/openad_notebooks/Table_of_Contents.ipynb
1. **Select the kernel**<br>
Make sure to select the "ad-venv" iPython kernel. You can do this under _Kernel > Change Kernel_, or in the latest versions of Jupyter by clicking the kernel name in the top right hand corner. If you don't see your iPython kernel, make sure you followed the Jupyter Setup instructions listed above.
<figure>
<a href="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-notebook-kernel.png" target="_blank"><img src="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-notebook-kernel.png"></a>
</figure>
<figure>
<a href="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-lab-kernel.png" target="_blank"><img src="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-lab-kernel.png"></a>
</figure>
1. **Magic Commands**<br>
Magic commands let you run terminal commands from within Jupyter. They are invoked by the `%openad` prefix. All OpenAD CLI commands can be accessed like this. For example:<br>
%openad list files
<br>
# Interacting with the Toolkits
OpenAD integrates with `DS4SD`, `RXN`, and has placeholder support for `ST4SD`.
> [!IMPORTANT]
> When running commands from Jupyter, prepend them with `%openad`
### Registration
Before you can interact with the toolkits, you'll need to register with each individual toolkit.
<details>
<summary>Register with DS4SD (Deep Search)</summary>
<div markdown="block">
1. First, you'll need to generate an API key on the Deep Search website.
- Visit the Deep Search website and create an account:<br>
[deepsearch-experience.res.ibm.com](https://deepsearch-experience.res.ibm.com)<br>
- Once logged in, click the Toolkit/API icon in the top right hand corner, then open the HTTP section
- Click the "Generate new API key" button<br>
<br>
<!--  -->
<a href="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/ds4sd-api-key.png" target="_blank"><img src="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/ds4sd-api-key.png" /></a>
1. Once inside the OpenAD client, you'll be prompted to authenticate when activating the Deep Search (DS4SD) toolkit. When running `set context ds4sd` :
- **Hostname:** [https://sds.app.accelerate.science](https://sds.app.accelerate.science)
- **Email:** Your email
- **API_key:** The DS4SD API key you obtained following the instructions above.
1. You should get a message saying you successfully logged in.
> **Note:** Your DS4SD auth config file is saved as `~/.openad/deepsearch_api.cred`. If you ever want to reset your DS4SD login information you can run `set context ds4sd reset`, or you can delete this file.<br>
</div>
</details>
<details>
<summary>Register with RXN</summary>
<div markdown="block">
1. First, you'll need to generate an API key on the RXN website.
- Sign up for an RXN account at [rxn.app.accelerate.science](https://rxn.app.accelerate.science)
- Obtain your API key by clicking the user profile icon in the top right hand corner and select "My profile".<br>
<br>
<!--  -->
<a href="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/rxn-api-key.png" target="_blank"><img src="https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/rxn-api-key.png" /></a>
1. When setting the context to RXN using `set context rxn` you'll be prompted to create a new auth configuration file:
- **Hostname:** [https://rxn.app.accelerate.science](https://rxn.app.accelerate.science)<br>
- **API_key:** The RXN API key you obtained following the instructions above.
1. You should get a message saying you successfully logged in.<br>
> **Note:** Your RXN auth config file is saved as `~/.openad/rxn_api.cred`. If you ever want to reset your RXN login information you can run `set context rxn reset`, or you can delete this file.<br>
</div>
</details>
### Adding a Toolkit
First install the toolkit, then set the context to this toolkit.
add toolkit ds4sd
set context ds4sd
### Sample Commands
# DS4SD
display all collections
# RXN
list rxn models
### Running Bash Commands (CLI)
To run a command in bash mode, prepend it with `openad` and make sure to escape quotes.
openad show molecules using file \'base_molecules.sdf\'
<br>
# AI Assistant
To enable our AI assistant, you'll either need access to [IBM BAM](https://bam.res.ibm.com/auth/signin) or use the free open source LLM [Ollama](https://ollama.com).
> **Note:** Ollama requires an 8GB GPU
> **Note:** Support for WatsonX is coming soon
<br>
## IBM BAM Setup
To use IBM BAM if you have access to it, simply provide your API key when prompted.
set llm bam
tell me <enter prompt>
<br>
## Ollama Setup
1. Install [Ollama](https://ollama.com/download) onto your platform.
1. Download the appropriate models.
ollama pull llama3:latest
ollama pull nomic-embed-text
1. Start the server if not already started.
ollama serve
That's it for local usage. If you want to run Ollama remotely, continue below.
### Ollama Remote Setup with SkyPilot
1. Check out our configuration file to launch ollama on SkyPilot: [ollama_setup.yaml](./openad/ollama_setup.yaml)
sky serve up ollama_setup.yaml
1. Set up local environment variables
- For windows `setx OLLAMA_HOST=<sky-server-ip>:11434`
- For Linux and macOS `export OLLAMA_HOST=<sky-server-ip>:11434`
- To reset to local use `OLLAMA_HOST=0.0.0.0:11434`
### Run Ollama
> **Note:** If prompted for an API key and none was setup, just leave the input empty.
set llm ollama
tell me <enter prompt>
<br>
# Model Services
To use the model services you'll need to have the AWS CLI installed to check if SkyPilot is enabled to deploy to AWS from your machine:
sky check
Launching any model service will take about 10 minutes to deploy. This can be monitored using the controller logs, e.g.:
sky serve logs sky-service-0af4 --controller
<br>
# For Developers
OpenAD is fully open source and we encourage contributions. We plan to provide documentation on how to integrate your own toolkits in the future.
If you have any questions in the meantime, please [reach out]({% link about.md %}).
<br>
## Installation for Development
<details>
<summary>Install using the setup wizard (uses poetry)</summary>
<div markdown="block">
1. **Step 1: Download the repo**
git clone https://github.com/acceleratedscience/open-ad-toolkit.git
> **Note:** To download a specific branch, you can run instead:<br> > `git clone -b <branch_name> https://github.com/acceleratedscience/open-ad-toolkit.git`
1. **Step 2: Launch the setup wizard**
cd open-ad-toolkit
./setup.sh
</div>
</details>
<details>
<summary>Install using pip</summary>
<div markdown="block">
1. **Step 0: Before you start**<br>
Ensure you're running Python 3.10.10 or above. There's multiple ways of doing this, we'll use pyenv.
git clone https://github.com/pyenv/pyenv.git ~/.pyenv
pyenv install 3.10
1. **Step 1: Set up your virtual environment** (optional)<br>
python -m venv ~/ad-venv
source ~/ad-venv/bin/activate
> **Note:** To exit the virtual environment, you can run `deactivate`
1. **Step 2: Download the repo**
git clone https://github.com/acceleratedscience/open-ad-toolkit.git
> **Note:** To download a specific branch, you can run instead:<br> > `git clone -b <branch_name> https://github.com/acceleratedscience/open-ad-toolkit.git`
1. **Step 2: Install the requirements**
cd open-ad-toolkit
pip install -e .
> **Note:** The -e flag stands for "editable". This means that instead of copying the package's files to the Python site-packages directory as in a regular installation, pip creates a symbolic link (symlink) from your package's source code directory into your Python environment.<br>This way you can make changes to the source code of the package, and those changes are immediately reflected in your Python environment. You don't need to reinstall the package every time you make a change.
</div>
</details>
<br>
## Testing a branch
To do a regular install from a particular branch, you can run:
pip install git+https://github.com/acceleratedscience/open-ad-toolkit.git@<branch_name>
<br>
# Installing on Windows
In order to run OpenAD on Windows 11, you will need to install the Ubuntu WSL package ("Windows Subsystem for Linux").
<br>
## Before You Start
- **Verify Windows version**<br>
To check if you are running Windows 11 or later, press `Win` + `R`, type "winver", and press `Enter`. A window will open showing your Windows version.
- **Verify WSL**<br>
To check if you already have WSL installed, run `wsl -l -v` into the terminal. To see more information about your current version of Ubuntu, run `lsb_release -a`
<br>
## Installing WSL
Install WSL and create a user called 'openad' or one of your choosing.
wsl --install Ubuntu-22.04
**Optional:** To setup an Ubuntu Python environment from scratch, continue to <a href="#linux-notes">Linux Notes</a>
<br>
# Linux Notes
If you wish to setup an Ubuntu Python environment from scratch, run:
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11-full
sudo apt install python3-pip
sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 100
sudo pip install pip --upgrade
You will need to restart your Linux session before running `pip install openad` so that the python libraries are in your path.
If you get an error when running `init_magic`, you may first need to setup the default iPython profile for magic commands.
ipython profile create
Raw data
{
"_id": null,
"home_page": "https://www.accelerate.science/",
"name": "openad",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.10",
"maintainer_email": null,
"keywords": "deepsearch, rxn, jupyter, magic commands, accelerated Discovery, science, retrosynthesis",
"author": "Phil Downey",
"author_email": "phil.downey1@ibm.com",
"download_url": "https://files.pythonhosted.org/packages/ae/43/8bc34ba154fe77878865e98521b5b6c3d55bee13bf76100f890e7f5388c9/openad-0.6.5.1.tar.gz",
"platform": null,
"description": "<!--\n\nFor screenshots to look good, they should be small and ideally\nall the same size. The script below lets you open the URLs in\nthe right size. Just paste this into the browser console and\npress enter.\n\nTo take the screenshots with browser UI included on Mac, press\ncmd+shift+4 followed by the spacebar, then click the window.\nFor consistency, stick to Chrome.\n\n- - -\n\nurls = [\n 'https://cps.foc-deepsearch.zurich.ibm.com',\n 'https://rxn.app.accelerate.science',\n 'https://sds.app.accelerate.science',\n\n]\nfor (var i=0; i< urls.length; i++) {\n window.open(urls[i], '_blank', 'width=1000,height=600');\n}\n\n-->\n\n# Open Accelerated Discovery <!-- omit from toc -->\n\n[](https://pypi.org/project/openad/)\n[](https://pypi.org/project/openad/)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/psf/black)\n[](https://acceleratedscience.github.io/openad-docs/)\n\n<br>\n\n<!-- description -->\n\nOpenAD is an open-source framework for molecular and materials discovery developed by IBM Research.\n\nThe OpenAD client is accessible from a command line interface, Jupyter Notebook and an API. It provides unified access to a variety of tools and AI models for literature knowledge extraction, forward and retrosynthesis prediction, generative methods and property inference. You can train models on your own data as well as visualize and filter candidate molecules.\n\n<!-- /description -->\n\n[Documentation](https://acceleratedscience.github.io/openad-docs/)\n\n<br>\n\n### See What's New <!-- omit from toc -->\n\n<details>\n<summary>See what's new in OpenAD</summary>\n<div markdown=\"block\">\n\n- `%Openadd` has been added to the magic commands for commands that return data.\n- New Macro Molecule viewer for visualising proteins\n- Upgraded SkyPilot to 0.6.0\n- Support for deploying in OpenShift AI/Open Data hub workbench or Podman/Docker image. [See the workbench repo](https://github.com/acceleratedscience/openad_workbench).\n- Support for application API\n- New property and dataset generation services.<br>We currently support the following model services:\n\n - GT4SD Generation Services `git@github.com:acceleratedscience/generation_inference_service.git`\n - GT4SD Property Services `git@github.com:acceleratedscience/property_inference_service.git`\n - GT4SD MoleR Generation `git@github.com:acceleratedscience/moler_inference_service.git`\n - GT4SD Molformer `git@github.com:acceleratedscience/molformer_inference_service.git`\n\n Pre-Requisite is that you have a AWS Account and can launch your own EC2 Instances Or someone else can launch them for you and you can catalog a Remote Service via URL.\n\n **Example:**\n\n - Install a service\n\n catalog model service from 'git@github.com:acceleratedscience/property_inference_service.git' as prop\n\n - Start the service\n\n model service up prop\n\n - Wait until the service is ready\n\n model service status\n\n - Once the service is ready, you can run the following commands to test:\n\n ```\n prop get molecule property [qed,esol] for [ C(C(C1C(=C(C(=O)O1)O)O)O)O ,[H-] ]\n ```\n\n ```\n prop get molecule property esol for C(C(C1C(=C(C(=O)O1)O)O)O)O\n ```\n\n - Examples are supplied in the sample Notebooks.<br>See `init_examples` under the [Jupyter installation instructions](#setting-up-jupyter) below for more information.\n\n - To shut down the service\n\n model service down prop\n\n - Available commands for managing model services...\n\n model service status\n model service config <service_name>\n model catalog list\n uncatalog model service <service_name>\n catalog model service from (remote) '<path or github>' as <service_name>\n model service up <service_name> [no_gpu]\n model service local up <service_name>\n model service down <service_name>\n\n</div>\n</details>\n\n<br>\n\n### Before You Start <!-- omit from toc -->\n\n<details>\n<summary>Things you should know</summary>\n<div markdown=\"block\">\n\n- OpenAD is available for Linux and MacOS\n- We support Windows 11 via WSL 2 (ubuntu 22.04) - see [Installing on Windows](#installing-on-windows)\n- When not installing into a virtual environment on MacOS, you may need to use `python3` and `pip3` instead of `python` and `pip` respectively\n- When updating to 0.4.0 or above, first remove all toolkits by runnning `list toolkits` and then `remove toolkit <toolkit_name>`.\n\n</div>\n</details>\n\n<br>\n\n## Quick Install <!-- omit from toc -->\n\n> **Note:** This will install OpenAD in your global space. If you wish to use a virtual environment, please see more [detailed instructions](#installation) below.\n\n pip install openad\n openad\n\nGet started with Jupyter:\n\n init_magic\n init_examples\n jupyter lab ~/openad_notebooks/Table_of_Contents.ipynb\n\nIf you get an error when running `init_magic`, you may first need to setup the default iPython profile for magic commands.\n\n ipython profile create\n\n<br>\n\n---\n\n<br>\n\n## Table of Contents <!-- omit from toc -->\n\n<!-- toc -->\n\n- [Installation](#installation)\n- [Getting Started - CLI](#getting-started---cli)\n- [Getting Started - Jupyter](#getting-started---jupyter)\n - [Setting up Jupyter](#setting-up-jupyter)\n - [Launching OpenAD in Jupyter](#launching-openad-in-jupyter)\n- [Interacting with the Toolkits](#interacting-with-the-toolkits)\n - [Registration](#registration)\n - [Adding a Toolkit](#adding-a-toolkit)\n - [Sample Commands](#sample-commands)\n - [Running Bash Commands (CLI)](#running-bash-commands-cli)\n- [AI Assistant](#ai-assistant)\n - [IBM BAM Setup](#ibm-bam-setup)\n - [Ollama Setup](#ollama-setup)\n - [Ollama Remote Setup with SkyPilot](#ollama-remote-setup-with-skypilot)\n - [Run Ollama](#run-ollama)\n- [Model Services](#model-services)\n- [For Developers](#for-developers)\n - [Installation for Development](#installation-for-development)\n - [Testing a branch](#testing-a-branch)\n- [Installing on Windows](#installing-on-windows)\n - [Before You Start](#before-you-start)\n - [Installing WSL](#installing-wsl)\n- [Linux Notes](#linux-notes)\n\n<!-- tocstop -->\n\n<br>\n\n---\n\n<br>\n\n<a name=\"installation\"></a>\n\n# Installation\n\n> **Note:** Contributors should skip to [Installation for Development](#installation-for-development)\n\n> **Note:** Linux users may want to check the [Linux Notes](#linux-notes)\n\n> **Note:** If you prefer using poetry and you know what you're doing, you can skip the instructions below and run `poetry add openad` instead.\n\n1. **Step 0: Before you start**<br>\n Ensure you're running Python 3.10 or 3.11. There's multiple ways of updating Python, we'll use pyenv.\n\n > **Note:** Due to an issue with one of our dependencies, Python 3.12 is not yet supported.\n\n git clone https://github.com/pyenv/pyenv.git ~/.pyenv\n pyenv install 3.11\n\n1. **Step 1: Set up your virtual environment** (optional)<br>\n\n python3.11 -m venv ~/ad-venv\n source ~/ad-venv/bin/activate\n\n > **Note:** To exit the virtual environment, you can run `deactivate`\n\n1. **Step 2: Installation**\n\n pip install openad\n\n<br>\n\n# Getting Started - CLI\n\n- **Enter the virtual environment**\n\n > **Note:** If you just installed OpenAD, you probably already activated the virtual environment.\n\n source ~/ad-venv/bin/activate\n\n- **Enter the command shell**\n\n openad\n\n <!--  -->\n <!-- <a href=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/screenshot-landing.png\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/screenshot-landing.png\" /></a> -->\n\n- **Exit the command shell**<br>\n Hit `ctrl+c` or run:\n\n exit\n\n- **Run a single command from outside the command shell**\n\n openad <command>\n\n- **Exit the virtual environment**<br>\n\n deactivate\n\n<br>\n\n# Getting Started - Jupyter\n\n## Setting up Jupyter\n\nThe following commands only need to be run once after installation:\n\n1. **Activate your virtual environment**\n\n > **Note:** If you just installed OpenAD, you probably already activated the virtual environment.\n\n source ~/ad-venv/bin/activate\n\n1. **Create an iPython kernel**<br>\n This ports your virtual environment to Jupyter.\n\n python -m ipykernel install --user --name=ad-venv\n\n > **Note:** To list your installed iPython kernels, you can run `jupyter kernelspec list`, and to remove the kernel you can run `jupyter kernelspec uninstall ad-venv`\n\n1. **Install the magic commands**<br>\n This enables OpenAD commands to be run within a Jupyter Notebook.\n\n init_magic\n\n <details>\n <summary><b>Alternative:</b> Manually add magic commands</summary>\n <div markdown=\"block\">\n\n If you don't want to activate magic commands in all Notebooks, you can instead activate them for individual Notebooks.\n\n - Run `init_examples`\n - Copy the file `~/openad_notebooks/openad.ipynb` to the same directory as the Notebook you wish to activate.\n - In your Notebook, run this inside a code cell: `!run openad.ipynb`\n\n </div>\n </details>\n\n1. **Install example Notebooks**<br>\n This installs our example Notebooks at `~/openad_notebooks`.\n\n init_examples\n\n<br>\n\n## Launching OpenAD in Jupyter\n\n1. **Open any Notebook**<br>\n The following command will open up the example Notebook:\n\n jupyter lab ~/openad_notebooks/Table_of_Contents.ipynb\n\n1. **Select the kernel**<br>\n Make sure to select the \"ad-venv\" iPython kernel. You can do this under _Kernel > Change Kernel_, or in the latest versions of Jupyter by clicking the kernel name in the top right hand corner. If you don't see your iPython kernel, make sure you followed the Jupyter Setup instructions listed above.\n\n <figure>\n <a href=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-notebook-kernel.png\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-notebook-kernel.png\"></a>\n </figure>\n <figure>\n <a href=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-lab-kernel.png\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/jupyter-lab-kernel.png\"></a>\n </figure>\n\n1. **Magic Commands**<br>\n Magic commands let you run terminal commands from within Jupyter. They are invoked by the `%openad` prefix. All OpenAD CLI commands can be accessed like this. For example:<br>\n\n %openad list files\n\n<br>\n\n# Interacting with the Toolkits\n\nOpenAD integrates with `DS4SD`, `RXN`, and has placeholder support for `ST4SD`.\n\n> [!IMPORTANT]\n> When running commands from Jupyter, prepend them with `%openad`\n\n### Registration\n\nBefore you can interact with the toolkits, you'll need to register with each individual toolkit.\n\n<details>\n<summary>Register with DS4SD (Deep Search)</summary>\n<div markdown=\"block\">\n\n1. First, you'll need to generate an API key on the Deep Search website.\n\n - Visit the Deep Search website and create an account:<br>\n [deepsearch-experience.res.ibm.com](https://deepsearch-experience.res.ibm.com)<br>\n - Once logged in, click the Toolkit/API icon in the top right hand corner, then open the HTTP section\n - Click the \"Generate new API key\" button<br>\n <br>\n <!--  -->\n <a href=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/ds4sd-api-key.png\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/ds4sd-api-key.png\" /></a>\n\n1. Once inside the OpenAD client, you'll be prompted to authenticate when activating the Deep Search (DS4SD) toolkit. When running `set context ds4sd` :\n\n - **Hostname:** [https://sds.app.accelerate.science](https://sds.app.accelerate.science)\n - **Email:** Your email\n - **API_key:** The DS4SD API key you obtained following the instructions above.\n\n1. You should get a message saying you successfully logged in.\n\n > **Note:** Your DS4SD auth config file is saved as `~/.openad/deepsearch_api.cred`. If you ever want to reset your DS4SD login information you can run `set context ds4sd reset`, or you can delete this file.<br>\n\n</div>\n</details>\n\n<details>\n<summary>Register with RXN</summary>\n<div markdown=\"block\">\n\n1. First, you'll need to generate an API key on the RXN website.\n\n - Sign up for an RXN account at [rxn.app.accelerate.science](https://rxn.app.accelerate.science)\n - Obtain your API key by clicking the user profile icon in the top right hand corner and select \"My profile\".<br>\n <br>\n <!--  -->\n <a href=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/rxn-api-key.png\" target=\"_blank\"><img src=\"https://raw.githubusercontent.com/acceleratedscience/open-ad-toolkit/main/assets/rxn-api-key.png\" /></a>\n\n1. When setting the context to RXN using `set context rxn` you'll be prompted to create a new auth configuration file:\n\n - **Hostname:** [https://rxn.app.accelerate.science](https://rxn.app.accelerate.science)<br>\n - **API_key:** The RXN API key you obtained following the instructions above.\n\n1. You should get a message saying you successfully logged in.<br>\n\n > **Note:** Your RXN auth config file is saved as `~/.openad/rxn_api.cred`. If you ever want to reset your RXN login information you can run `set context rxn reset`, or you can delete this file.<br>\n\n</div>\n</details>\n\n### Adding a Toolkit\n\nFirst install the toolkit, then set the context to this toolkit.\n\n add toolkit ds4sd\n set context ds4sd\n\n### Sample Commands\n\n # DS4SD\n display all collections\n\n # RXN\n list rxn models\n\n### Running Bash Commands (CLI)\n\nTo run a command in bash mode, prepend it with `openad` and make sure to escape quotes.\n\n openad show molecules using file \\'base_molecules.sdf\\'\n\n<br>\n\n# AI Assistant\n\nTo enable our AI assistant, you'll either need access to [IBM BAM](https://bam.res.ibm.com/auth/signin) or use the free open source LLM [Ollama](https://ollama.com).\n\n> **Note:** Ollama requires an 8GB GPU\n\n> **Note:** Support for WatsonX is coming soon\n\n<br>\n\n## IBM BAM Setup\n\nTo use IBM BAM if you have access to it, simply provide your API key when prompted.\n\n set llm bam\n tell me <enter prompt>\n\n<br>\n\n## Ollama Setup\n\n1. Install [Ollama](https://ollama.com/download) onto your platform.\n\n1. Download the appropriate models.\n\n ollama pull llama3:latest\n ollama pull nomic-embed-text\n\n1. Start the server if not already started.\n\n ollama serve\n\nThat's it for local usage. If you want to run Ollama remotely, continue below.\n\n### Ollama Remote Setup with SkyPilot\n\n1. Check out our configuration file to launch ollama on SkyPilot: [ollama_setup.yaml](./openad/ollama_setup.yaml)\n\n sky serve up ollama_setup.yaml\n\n1. Set up local environment variables\n\n - For windows `setx OLLAMA_HOST=<sky-server-ip>:11434`\n - For Linux and macOS `export OLLAMA_HOST=<sky-server-ip>:11434`\n - To reset to local use `OLLAMA_HOST=0.0.0.0:11434`\n\n### Run Ollama\n\n> **Note:** If prompted for an API key and none was setup, just leave the input empty.\n\n set llm ollama\n tell me <enter prompt>\n\n<br>\n\n# Model Services\n\nTo use the model services you'll need to have the AWS CLI installed to check if SkyPilot is enabled to deploy to AWS from your machine:\n\n sky check\n\nLaunching any model service will take about 10 minutes to deploy. This can be monitored using the controller logs, e.g.:\n\n sky serve logs sky-service-0af4 --controller\n\n<br>\n\n# For Developers\n\nOpenAD is fully open source and we encourage contributions. We plan to provide documentation on how to integrate your own toolkits in the future.\n\nIf you have any questions in the meantime, please [reach out]({% link about.md %}).\n\n<br>\n\n## Installation for Development\n\n<details>\n<summary>Install using the setup wizard (uses poetry)</summary>\n<div markdown=\"block\">\n\n1. **Step 1: Download the repo**\n\n git clone https://github.com/acceleratedscience/open-ad-toolkit.git\n\n > **Note:** To download a specific branch, you can run instead:<br> > `git clone -b <branch_name> https://github.com/acceleratedscience/open-ad-toolkit.git`\n\n1. **Step 2: Launch the setup wizard**\n\n cd open-ad-toolkit\n ./setup.sh\n\n</div>\n</details>\n\n<details>\n<summary>Install using pip</summary>\n<div markdown=\"block\">\n\n1. **Step 0: Before you start**<br>\n Ensure you're running Python 3.10.10 or above. There's multiple ways of doing this, we'll use pyenv.\n\n git clone https://github.com/pyenv/pyenv.git ~/.pyenv\n pyenv install 3.10\n\n1. **Step 1: Set up your virtual environment** (optional)<br>\n\n python -m venv ~/ad-venv\n source ~/ad-venv/bin/activate\n\n > **Note:** To exit the virtual environment, you can run `deactivate`\n\n1. **Step 2: Download the repo**\n\n git clone https://github.com/acceleratedscience/open-ad-toolkit.git\n\n > **Note:** To download a specific branch, you can run instead:<br> > `git clone -b <branch_name> https://github.com/acceleratedscience/open-ad-toolkit.git`\n\n1. **Step 2: Install the requirements**\n\n cd open-ad-toolkit\n pip install -e .\n\n > **Note:** The -e flag stands for \"editable\". This means that instead of copying the package's files to the Python site-packages directory as in a regular installation, pip creates a symbolic link (symlink) from your package's source code directory into your Python environment.<br>This way you can make changes to the source code of the package, and those changes are immediately reflected in your Python environment. You don't need to reinstall the package every time you make a change.\n\n</div>\n</details>\n\n<br>\n\n## Testing a branch\n\nTo do a regular install from a particular branch, you can run:\n\n pip install git+https://github.com/acceleratedscience/open-ad-toolkit.git@<branch_name>\n\n<br>\n\n# Installing on Windows\n\nIn order to run OpenAD on Windows 11, you will need to install the Ubuntu WSL package (\"Windows Subsystem for Linux\").\n\n<br>\n\n## Before You Start\n\n- **Verify Windows version**<br>\n To check if you are running Windows 11 or later, press `Win` + `R`, type \"winver\", and press `Enter`. A window will open showing your Windows version.\n\n- **Verify WSL**<br>\n To check if you already have WSL installed, run `wsl -l -v` into the terminal. To see more information about your current version of Ubuntu, run `lsb_release -a`\n\n<br>\n\n## Installing WSL\n\nInstall WSL and create a user called 'openad' or one of your choosing.\n\n wsl --install Ubuntu-22.04\n\n**Optional:** To setup an Ubuntu Python environment from scratch, continue to <a href=\"#linux-notes\">Linux Notes</a>\n\n<br>\n\n# Linux Notes\n\nIf you wish to setup an Ubuntu Python environment from scratch, run:\n\n sudo add-apt-repository ppa:deadsnakes/ppa\n sudo apt update\n sudo apt install python3.11-full\n sudo apt install python3-pip\n sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 100\n sudo pip install pip --upgrade\n\nYou will need to restart your Linux session before running `pip install openad` so that the python libraries are in your path.\n\nIf you get an error when running `init_magic`, you may first need to setup the default iPython profile for magic commands.\n\n ipython profile create\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Open Accelerated Discovery Client",
"version": "0.6.5.1",
"project_urls": {
"Documentation": "https://acceleratedscience.github.io/openad-docs/",
"Homepage": "https://www.accelerate.science/",
"Repository": "https://github.com/acceleratedscience/open-ad-toolkit"
},
"split_keywords": [
"deepsearch",
" rxn",
" jupyter",
" magic commands",
" accelerated discovery",
" science",
" retrosynthesis"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "a663f40c6c86daf5bc6ae35bb8f6373ccc61c50bb1c71842f1fc1e063cdc1136",
"md5": "7c196d2e5f80e445c470200894a7d441",
"sha256": "492453413cd7150c2fc20e91893c28af3639e7f5d3725a0cba04a1820aa55dae"
},
"downloads": -1,
"filename": "openad-0.6.5.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7c196d2e5f80e445c470200894a7d441",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.10",
"size": 31393595,
"upload_time": "2024-11-20T21:40:20",
"upload_time_iso_8601": "2024-11-20T21:40:20.973778Z",
"url": "https://files.pythonhosted.org/packages/a6/63/f40c6c86daf5bc6ae35bb8f6373ccc61c50bb1c71842f1fc1e063cdc1136/openad-0.6.5.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ae438bc34ba154fe77878865e98521b5b6c3d55bee13bf76100f890e7f5388c9",
"md5": "752198585f002f5e57ef5bcb3b33ee59",
"sha256": "ac7cbc1452f172ffbc366f2bfe63f2e55e674d9dd225e5046b38a9b7f646a0c7"
},
"downloads": -1,
"filename": "openad-0.6.5.1.tar.gz",
"has_sig": false,
"md5_digest": "752198585f002f5e57ef5bcb3b33ee59",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.10",
"size": 31115678,
"upload_time": "2024-11-20T21:42:10",
"upload_time_iso_8601": "2024-11-20T21:42:10.271920Z",
"url": "https://files.pythonhosted.org/packages/ae/43/8bc34ba154fe77878865e98521b5b6c3d55bee13bf76100f890e7f5388c9/openad-0.6.5.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-20 21:42:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "acceleratedscience",
"github_project": "open-ad-toolkit",
"travis_ci": true,
"coveralls": false,
"github_actions": true,
"lcname": "openad"
}
JSON
