v2 plugin: 4 tools, single agent loop

chatmol_claude_test.py

chatmol_claude_test.py

model_info.json

model_info.json

ollama.sh

ollama.sh

cmds.txt

CLAUDE.md

.claude/

 No newline at end of file

# ChatMol PyMOL Plugin

# ChatMol PyMOL Plugin

This is a PyMOL plugin built by ChatMol, for automating the process of creating a biomoelcular figure in PyMOL. 

An LLM-powered agentic plugin for PyMOL that translates natural language into molecular visualizations.

## Versions

| Directory | Description                                                                                                                                      |

| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |

| `v1/`     | Original plugin — direct LLM-to-command translation. Supports OpenAI, Anthropic, DeepSeek, Ollama, and the free ChatMol service.                 |

| `v2/`     | Agentic plugin — tool-calling loop with session inspection, vision feedback, and Qt5 GUI. Uses OpenRouter and other OpenAI-compatible providers. |

## v2 — Agentic Plugin

### Installation

### Installation

We provide a up-to-date version of the plugin on our website. You can download the plugin from [here](https://chatmol.com/pymol_plugins/chatmol-latest.py). Or, in PyMOL command line, you can run the following command to install the plugin:

In PyMOL's command line:

```python

```python

load https://chatmol.com/pymol_plugins/chatmol-latest.py

run /path/to/pymol_plugin/v2/chatmol.py

```

```

### Supported LLM providers

### Supported Providers

| Provider  | Models               | GPU Required | API Key Required | Notes               |

| --------- | -------------------- | ------------ | ---------------- | ------------------- |

v2 routes through OpenAI-compatible APIs. Configure via `set_provider`:

| OpenAI    | GPT Models           | No           | Yes              | Commercial API      |

| Anthropic | Claude Models        | No           | Yes              | Commercial API      |

| Provider        | Models                                | API Key Env Var      |

| DeepSeek  | DeepSeek Models      | No           | Yes              | Commercial API      |

| --------------- | ------------------------------------- | -------------------- |

| Ollama    | LLaMA, Mixtral, etc. | Yes          | No               | Self-hosted models  |

| OpenRouter      | GPT-4o, GPT-5.2, Gemini 3 Flash, etc. | `OPENROUTER_API_KEY` |

| ChatMol   | ChatMol Model        | No           | No               | Free hosted service |

| DeepSeek        | DeepSeek V3, DeepSeek R1              | `DEEPSEEK_API_KEY`   |

| Kimi (Moonshot) | Kimi K2.5                             | `MOONSHOT_API_KEY`   |

| GLM (Zhipu)     | GLM-5                                 | `GLM_API_KEY`        |

### Quick Start

### Usage

1. The most easy way to get started is to use the `chatlite` command in PyMOL. 

```pymol

```pymol

chatlite "show me a protein"

# Set your API key (saved to ~/.PyMOL/chatmol_config.json)

```

set_api_key sk-or-xxxx

2. Comercial API providers

# Chat with the agent

- OpenAI, Anthropic, and DeepSeek require an API key. You can get an API key from the respective provider's website.

chat fetch 1ubq and show as cartoon

- We suggest adding the API key to the environment variable:

```bash

# Multi-step request

export OPENAI_API_KEY=sk-proj-xxxx

chat fetch 3wzm, show enzyme-substrate interactions in chain A with publication quality

export ANTHROPIC_API_KEY=sk-ant-xxxx

export DEEPSEEK_API_KEY=sk-xxxx

```

or you can use the `set_api_key` command in PyMOL:

```python

set_api_key openai, sk-proj-xxxx

set_api_key anthropic, sk-ant-xxxx

set_api_key deepseek, sk-xxxx

```

```

- Currently supported models are:

| **Provider** | **Models**                                                                                                |

![](./demo.png)

| ------------ | --------------------------------------------------------------------------------------------------------- |

| OpenAI       | gpt-4o, gpt-4o-mini                                                                                       |

| Anthropic    | claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022, claude-3-opus-20240229, claude-3-5-sonnet-20240620 |

| DeepSeek     | deepseek-chat                                                                                             |

Use `update_model` command to get the latest models from the provider.

### Commands

```pymol

| Command                | Description                                       |

update_model deepseek-chat

| ---------------------- | ------------------------------------------------- |

```

| `chat <message>`       | Send a message to the agent                       |

| `set_provider <name>`  | Switch provider (openrouter, deepseek, kimi, glm) |

| `set_api_key <key>`    | Set API key for the current provider              |

| `set_model <model>`    | Set the text model                                |

| `set_vision_model <m>` | Set the vision model for visual QA                |

| `reset_conversation`   | Clear conversation history                        |

| `save_conversation`    | Save conversation to JSON                         |

| `load_conversation`    | Load conversation from JSON                       |

| `chatmol_config`       | Show current configuration                        |

| `chatmol_settings`     | Open the Qt settings dialog                       |

| `chatmol_gui`          | Open the Qt chat bar                              |

Once the model and API key are set, you can use the `chat` command to generate text from the model.

### Architecture

```pymol

chat "show me a protein"

```

3. Self-hosted models

The v2 plugin uses a simple agentic loop: call the LLM, execute tool calls, repeat until the LLM produces a final text response.

- Ollama provides self-hosted models. You can use any model you like, tell the plugin to use ollama models by adding `@ollama` to the model name. Refer to the [Ollama documentation](https://ollama.com/docs) for more information.

```pymol

update_model phi-4@ollama

```

### Examples

**4 tools:**

**1. ChatMol as a Task Execution Agent**

| Tool                 | Purpose                                                    |

| -------------------- | ---------------------------------------------------------- |

| `inspect_session`    | Get current PyMOL state (objects, chains, atoms)           |

| `run_pymol_commands` | Execute arbitrary PyMOL commands (with safety blocklist)   |

| `render`             | Export image (preview or publication quality)              |

| `capture_viewport`   | Screenshot + vision model analysis for iterative visual QA |

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.

The LLM knows PyMOL — it uses `cmd.select`, `cmd.show`, `cmd.color`, `cmd.distance`, `preset.ligand_sites_hq`, etc. all through `run_pymol_commands`. A safety blocklist prevents destructive commands (`quit`, `reinitialize`, shell commands).

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

**Qt5 GUI:** When PyMOL has Qt available, a chat bar docks to the bottom of the main window with a settings dialog, execution trace panel, and animated thinking indicator.

**2. ChatMol as a Q&A Chatbot**

### Configuration

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

Settings are persisted to `~/.PyMOL/chatmol_config.json`:

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:

````

- `provider` — API provider name

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

- `api_keys` — per-provider API keys

- `text_model` — model for chat completions

- `vision_model` — model for visual QA (capture_viewport)

- `temperature`, `max_tokens`, `max_iterations`, `max_tool_calls`

```

## v1 — Original Plugin

# Load two proteins

fetch 1ake

fetch 1ttt

# Align the two proteins

### Installation

align 1ake, 1ttt

# Show the aligned proteins

```python

show cartoon

load https://chatmol.com/pymol_plugins/chatmol-latest.py

```

```

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

### Supported Providers

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.

| Provider  | Models               | GPU Required | API Key Required | Notes               |

| --------- | -------------------- | ------------ | ---------------- | ------------------- |

| OpenAI    | GPT Models           | No           | Yes              | Commercial API      |

| Anthropic | Claude Models        | No           | Yes              | Commercial API      |

| DeepSeek  | DeepSeek Models      | No           | Yes              | Commercial API      |

| Ollama    | LLaMA, Mixtral, etc. | Yes          | No               | Self-hosted models  |

| ChatMol   | ChatMol Model        | No           | No               | Free hosted service |

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

### Quick Start

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.

```pymol

# Free service, no API key needed

chatlite show me a protein

````

# With an API key

  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.

set_api_key openai, sk-proj-xxxx

chat show me a protein

```

**3. Want to start over again?**

For self-hosted models via Ollama:

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.

```pymol

 No newline at end of file

update_model phi-4@ollama

```