Merge pull request #20 from JinyuanSun/relase_dev

# PyMOL ChatGPT Plugin

<!-- ![img](./assets/img.png) -->

## Table of contents

- [PyMOL ChatGPT Plugin](#pymol-chatgpt-plugin)

  - [Table of contents](#table-of-contents)

  - [Overview](#overview)

  - [ChatMol Website](#chatmol-website)

  - [Requirements \& Installation](#requirements--installation)

  - [ChatMol API Key Setup](#chatmol-api-key-setup)

  - [Usage](#usage)

    - [ChatMol as a Task Execution Agent](#chatmol-as-a-task-execution-agent)

    - [ChatMol as a Q\&A Chatbot](#chatmol-as-a-qa-chatbot)

    - [Want to start over again?](#want-to-start-over-again)

    - [ChatMol-Lite](#chatmol-lite)

    - [miniGUI](#minigui)

  - [License](#license)

## Overview

The PyMOL ChatGPT Plugin seamlessly integrates OpenAI's GPT-3.5-turbo model into PyMOL, enabling users to interact with PyMOL through natural language instructions. This powerful tool simplifies PyMOL tasks and provides suggestions, explanations, and guidance on various PyMOL-related topics.

The PyMOL ChatGPT Plugin seamlessly integrates OpenAI's large language models (GPT-3.5-turbo and text-davinci-003) into PyMOL, enabling users to interact with PyMOL using natural language instructions. This robust tool simplifies PyMOL tasks and offers suggestions, explanations, and guidance on a wide range of PyMOL-related topics. ChatMol provides various interaction modes with PyMOL, including the PyMOL command line, miniGUI chatbot, and web browsers.

## ChatMol Website

- The [official website](https://chatmol.org) of ChatMol. It provides all information about ChatMol development and use cases. 

- Visit the [official website](https://chatmol.org) for comprehensive information about its development and use cases.

- [ChatMol web-browser interface](http://xp.chatmol.org/chatmol.html) to interact with PyMOL via ChatMol.

- The [Online Chatbot](https://chatmol.org/qa/) is a Q&A system designed to answer questions related to PyMOL usage.

- [Online Chatbot](https://chatmol.org/qa/) to chat with.

- The [ChatMol web-browser interface](http://xp.chatmol.org/chatmol.html) allows you to submit PyMOL requests and execute them in PyMOL via ChatMol. (Please note that this feature is browser setting-dependent)

## Requirements & Installation

<img src="./assets/install.png" alt="alt text" width="400px" align="right"/>

## Requirements

- PyMOL

- PyMOL can be installed using `conda install -c conda-forge pymol-open-source`.

- OpenAI Python package: To install, enter `pip install openai` in the PyMOL command line.

- Install other dependencies: `pip install flask flask-cors chardet` in PyMOL command line.

![img](./assets/install.png)

## Installation

1. Download the plugin script `chatmol.py` and save it to a convenient location on your computer.

2. Open PyMOL.

3. In the PyMOL command line, enter `run /path/to/chatmol.py` (replace `/path/to` with the actual path to the script).

4. Create a .PyMOL folder in your home director for saving PyMOL related files, like ChatGPT API keys, PyMOL license file etc.

5. The plugin is now installed and ready to use.

- Download the plugin script `chatmol.py` and save it to a convenient location on your computer.

- Launch PyMOL.

- In the PyMOL command line, enter `run /path/to/chatmol.py` (replace `/path/to` with the actual path to the script).

- Create a .PyMOL folder in your home director for saving PyMOL-related files, like ChatGPT API keys, PyMOL license file, etc.

- The plugin is now installed and ready to use.

Alternatively, you can use the following command to load the plugin directly:

```

load https://raw.githubusercontent.com/JinyuanSun/ChatMol/main/chatmol.py

```

If you want a permentally installation, click `Plugin`, go to the `Plugin Manager`, navigate to the `Install New Plugin`, choose the local file or fetch from the url: `https://raw.githubusercontent.com/JinyuanSun/ChatMol/main/chatmol.py`

For permanent installation, click on `Plugin`, navigate to the `Plugin Manager`, go to `Install New Plugin`, and either choose the local file or fetch from the URL: `https://raw.githubusercontent.com/JinyuanSun/ChatMol/main/chatmol.py`

## ChatMol API Key Setup

Set your OpenAI API key by entering the following command in the PyMOL command line: `set_api_key your_api_key_here` (replace `your_api_key_here` with your actual API key). The API key will be stored in the same directory as the plugin script for future use.

## Usage

### ChatMol

1. Set your OpenAI API key by entering the following command in the PyMOL command line: `set_api_key your_api_key_here` (replace `your_api_key_here` with your actual API key). The API key will be saved in the same directory as the plugin script for future use.

2. Execute PyMOL commands automatically with the ChatGPT Plugin. In PyMOL command line, use `chat` as the wake up word for ChatGPT plugin, followed by a message of your PyMOL tasks or even a question for how to use some of the PyMOL commands. Detailed instructions on how to use PyMOL commands will be displaed and the commands will be executed automatically by default. For example, `chat Show me example to color a protein by its secondary structures`. An example protein molecule will be displayed in PyMOL 3D window with molecule colored by its seconary structure. 

ChatMol offers two interaction modes in the PyMOL command line: ChatMol and ChatMol-Lite. ChatMol directly utilizes OpenAI's GPT-3.5 model and requires an API key setup, whereas ChatMol-Lite is built on text-davinci-003 and supplemented with additional PyMol-related resources. Currently, ChatMol-Lite is undergoing rapid development, providing faster performance and eliminating the need for an API key setup for end users.

### ChatMol as a Task Execution Agent

The ChatGPT Plugin automates PyMOL tasks with ease. In the PyMOL command line, just enter `chat` as the trigger word for the ChatMol plugin, followed by your PyMOL task description or questions about specific PyMOL commands. After entering your requests, a set of instructions will appear, and the commands for completing your tasks will be automatically executed by default. For example, use `chat Show me how to color a protein by its secondary structures` to view a protein molecule in the PyMOL 3D window, with colors representing its secondary structures.

![img](./assets/img_ss.png)

### ChatMol as a Q&A Chatbot

ChatMol also serves as a Q&A chatbot, answering your queries about executing PyMOL tasks without actually performing the PyMOL. 

You can disable the automatic execution by adding a question mark `?` at the end of ChatMol prompt, e.g., `chat How do I align two proteins?`. You will receive a helpful response such as:

3. Ask ChatMol about how to perform PyMOL tasks without execution the PyMOL commands. You can disable the automatic execution by adding a question mark `?` at the end of ChatMol prompt, e.g., `chat How do I align two proteins?`. You will receive a helpful response such as:

```text

````

ChatGPT: To align two proteins in PyMOL, you can use the `align` command. Here's an example:

``

```

# Load two proteins

fetch 1ake

fetch 1tim

fetch 1ttt

# Align 1tim onto 1ake

align 1tim, 1ake

``

# Align the two proteins

align 1ake, 1ttt

# Show the aligned proteins

show cartoon

```

In this example, we first load two proteins using the `fetch` command. If you already have the proteins loaded, you can skip this step.

Next, we use the `align` command to align `1tim` onto `1ake`. The first argument is the object to be aligned (`1tim`), and the second argument is the reference object (`1ake`). PyMOL will align the two proteins based on their structural similarity, and create a new object with the aligned structure.

Next, we use the `align` command to align the two proteins. The first argument is the reference protein (the one that will not move), and the second argument is the mobile protein (the one that will be aligned to the reference). In this case, we're aligning 1ake to 1ttt.

You can also specify which atoms to use for the alignment by adding the `atommask` option. For example:

Finally, we use the `show` command to display the aligned proteins in cartoon representation.

``

# Align 1tim onto 1ake using only the backbone atoms

align 1tim and name CA+C+N+O, 1ake and name CA+C+N+O

``

Note that the `align` command will superimpose the mobile protein onto the reference protein, so that the two proteins have the same orientation and position.

In this example, we use the `and` operator to select only the backbone atoms (`CA`, `C`, `N`, and `O`) for both proteins. This can be useful if you only want to align the backbone of the proteins, and ignore any side chain differences.

```

````

  commands from each query will be saved internally. if you want to execute all saved commands, run `chat e` or `chat execute`. After execution, the stashed commands are cleared.

4. To start a new chat session, just enter the following in the PyMOL command line: `chat new`. This will let ChatMol clear the conversation history.

5. All above usage can be performed with a browser-based user interface: http://xp.chatmol.org/chatmol.html. It use a local communication channel between your browser and the ChatMol plugin in PyMOL. Also see the screenshots: https://chatmol.org/screenshots.html

### Want to start over again?

To start a new chat session, just enter the following in the PyMOL command line: `chat new`. This will let ChatMol clear the conversation history.

![img](./assets/img_ss.png)

### ChatMol-Lite

We found the response of gpt-3.5 is slow and people might don't have access to OpenAI's API, we developed chatmol-lite as an alternative. This is installed with the chatmol.

We found the response of gpt-3.5 is slow and people might don't have access to OpenAI's API, we developed chatmol-lite as an alternative. This is installed with the chatmol automatically. You can use it by typing `chatlite` in the PyMOL command line:

```bash

chatlite "Something you want chatmol to do for you"

```

**chatlite is different from the `chat`:**

1. Although it is a chatbot and have memory, it is design to directly execute commnads based on your instructions. 

**`chatlite` is different from the `chat`:**

1. Although it is a chatbot and have memory, it is designed to directly execute commnads based on your instructions. 

2. You can chat with ChatMol-Lite at [here](https://chatmol.org/qa/), the model is the same as the `chatlite`

3. It is much faster than the `chat` and you don't need to set up the OpenAI API key. And the response is more short than the `chat` .

### miniGUI

We also provide a miniGUI for ChatMol-Lite, which can be used as a task execution agent or Q&A chatbot. It retains your entire conversation history with ChatMol, and you have the flexibility to modify the execution plan suggested by ChatMol. For example, you can delete certain commands or add additional commands before sending them to PyMOL. You can launch the miniGUI from a terminal.

## Features

- Seamless integration with PyMOL.

- User-friendly command-line interface.

- Persistent API key storage for convenient one-time setup.

- Utilizes OpenAI's GPT-3.5-turbo model for powerful, context-aware suggestions and guidance.

```bash

git clone https://github.com/JinyuanSun/ChatMol.git

cd ChatMol/miniGUI

python miniGUI.py

```

Here is a screenshot of the miniGUI:

![img](./assets/chatmol_lite.png)

## Limitations

- The plugin relies on the OpenAI API, so an internet connection and API key are required for usage.

- The ChatGPT model's knowledge is based on the training data available up to September 

## Support

For any questions or issues related to the PyMOL ChatGPT Plugin, please refer to the official PyMOL mailing list or OpenAI's documentation and support resources.

## License

This project is released under the MIT License.

            self.end_headers()

            self.wfile.write(str(e).encode())

    def do_GET(self):

        if self.path == "/":

            self.send_response(HTTPStatus.OK)

            self._send_cors_headers()

            self.send_header("Content-Type", "text/html")

            self.end_headers()

            self.wfile.write(b'Hello, this is the local Pymol server.')

            return

        self.send_response(HTTPStatus.NOT_FOUND)

        self.end_headers()

def start_server():

    httpd = http.server.HTTPServer(('localhost', 8101), PyMOLCommandHandler)

    httpd.serve_forever()

# Save API Key in ~/.PyMOL/apikey.txt

API_KEY_FILE = os.path.expanduser('~')+"/.PyMOL/apikey.txt"

OPENAI_KEY_ENV = "OPENAI_API_KEY"

GPT_MODEL = "gpt-3.5-turbo"

def set_api_key(api_key):

    api_key = api_key.strip()

                  f" or by environment variable '{OPENAI_KEY_ENV}'.")

def chat_with_gpt(message):

def chat_with_gpt(message, max_history=10):

    global conversation_history

    conversation_history += f"User: {message}\nChatGPT:"

        messages = [

            {"role": "system", "content": "You are an AI language model specialized in providing command line code solutions related to PyMOL. Generate clear and effective solutions in a continuous manner. When providing demos or examples, try to use 'fetch' if object name is not provided. Prefer academic style visulizations. Code within triple backticks, comment and code should not in the same line."}

        ]

        message_parts = conversation_history.strip().split("\n")

        # Keep only the max_history latest exchanges to avoid making the conversation too long

        message_parts = conversation_history.strip().split("\n")[-2 * max_history:]

        for i, part in enumerate(message_parts):

            role = "user" if i % 2 == 0 else "assistant"

            messages.append({"role": role, "content": part})

        response = openai.ChatCompletion.create(

            model="gpt-3.5-turbo",

            model=GPT_MODEL,

            messages=messages,

            max_tokens=1024,

            max_tokens=256,

            n=1,

            temperature=0,

        )

        answer = response.choices[0].message['content'].strip()

        conversation_history += f"{answer}\n"

        else:

            print(command)

def start_chatgpt_cmd(message, execute:bool=True, lite:bool=True):

def start_chatgpt_cmd(message, execute:bool=True, lite:bool=False):

    if lite == True:

        chatlite(message)

        return 0

cmd.extend("set_api_key", set_api_key)

cmd.extend("chat", start_chatgpt_cmd)

cmd.extend("chatlite", chatlite)

 No newline at end of file

# A local GUI of ChatMol

# A GUI of ChatMol

## Requirements

- Python 3.6 or higher

## Usage

```bash

python local_gui.py

python miniGUI.py

```

def launch_pymol():

    """start a new process to launch PyMOL

    Only tested on MacOS, may be different on other OS

    """

    process = subprocess.Popen(["pymol", "pymol_server.py"], stdout=subprocess.PIPE, stderr=subprocess.PIPE)

    stdout, stderr = process.communicate()