Skip to content

AGENTS.md

Latest commit

 

History

History
190 lines (148 loc) · 6.55 KB

AGENTS.md

File metadata and controls

190 lines (148 loc) · 6.55 KB

AGENTS.md - PyMolAI Setup Runbook for Claude Code, Codex, and Cursor

This guide is for coding agents and assistant workflows that need to install and configure PyMolAI for end users.

1) What You Are Setting Up

PyMolAI is an AI assistant layer integrated into the PyMOL Qt desktop UI.

Core points:

  • OpenRouter key enables AI agent turns.
  • OpenBio key is optional and only enables OpenBio gateway tools.
  • Internal PyMOL tools (run_pymol_command, capture_viewer_snapshot) are always available.

2) Minimal End-User Setup Flow

  1. Install project in a virtual environment.
  2. Launch PyMOL GUI.
  3. Open Display -> PyMolAI Settings -> OpenRouter API Key... and save/test key.
  4. For OpenBio access, sign up at https://openbio.tech/ and create an OpenBio API key.
  5. Optionally open Display -> PyMolAI Settings -> OpenBio API Key... and save/test key.
  6. Optionally set the model from Display -> PyMolAI Settings -> Model.

3) Agent-Safe Setup Scripts

macOS prerequisites (Homebrew)

The C++ extension requires native libraries not bundled in the Python package. Install them before the pip/uv install step:

brew install netcdf glew glm
# libxml2, freetype, and libpng are typically already present;
# install them too if the build fails looking for those headers.

macOS

git clone https://github.com/ravishar313/PyMolAI
cd PyMolAI
# Create venv with uv (Python 3.10+ for full claude-agent-sdk support)
uv venv .venv
source .venv/bin/activate

# Build and install — include netcdf in PREFIX_PATH alongside homebrew paths
PREFIX_PATH=/opt/homebrew:/opt/homebrew/opt/libxml2:/opt/homebrew/opt/netcdf \
  uv pip install --python .venv/bin/python --reinstall .

# PyQt5 must be installed explicitly. PyQt6 is also detected by PyMOL's Qt
# loader but has incompatible enum namespacing with this codebase.
uv pip install --python .venv/bin/python PyQt5

# Verify
.venv/bin/python -c "import keyring, openai; print('ok: keyring/openai')"
.venv/bin/python -c "import claude_agent_sdk; print('ok: claude-agent-sdk')"
.venv/bin/python -c "from PyQt5 import QtWidgets; print('ok: PyQt5')"

Windows (PowerShell)

git clone https://github.com/ravishar313/PyMolAI
cd PyMolAI
uv venv .venv --python 3.10
.\.venv\Scripts\Activate.ps1
$env:PREFIX_PATH = "C:\path\to\deps"
uv pip install --python .venv\Scripts\python.exe --reinstall .
uv pip install --python .venv\Scripts\python.exe PyQt5
python -c "import keyring, openai; print('ok: keyring/openai')"
python -c "import claude_agent_sdk; print('ok: claude-agent-sdk')"
python -c "from PyQt5 import QtWidgets; print('ok: PyQt5')"

4) Provider/Key Behavior

Environment variables:

  • OPENROUTER_API_KEY
  • ANTHROPIC_AUTH_TOKEN
  • OPENBIO_API_KEY
  • OPENBIO_BASE_URL
  • PYMOL_AI_OPENROUTER_KEY_SOURCE
  • PYMOL_AI_OPENBIO_KEY_SOURCE

Behavior contract:

  • Without OpenRouter key (or Anthropic auth token mapping), AI mode is disabled.
  • Without OpenBio key, OpenBio tools are not registered, but the app still works.
  • Model selector in settings is strict to supported models; /ai model <id> remains flexible.
  • Changing model while busy applies to the next turn and should show a user-facing notice.

Key storage:

  • UI save uses keyring and system keychain.
  • Runtime can load saved keys into process environment at startup.
  • Env key takes precedence when explicitly set.

5) Architecture (High-Level)

  • Runtime bootstraps keys from env/keyring.
  • Claude SDK loop maps OpenRouter env and builds tool server.
  • Tool registration:
    • Always: run_pymol_command, capture_viewer_snapshot
    • Conditional: openbio_api_* gateway tools only when OpenBio key is present
  • OpenBio API base defaults to https://api.openbio.tech unless overridden by OPENBIO_BASE_URL.

6) Troubleshooting Decision Tree

A) "AI disabled" in runtime

  • Check OPENROUTER_API_KEY (or ANTHROPIC_AUTH_TOKEN) exists.
  • Check PYMOL_AI_DISABLE is not 1.
  • Re-test via OpenRouter key dialog.

B) Missing Claude SDK functionality

  • Ensure Python is 3.10+.
  • Verify claude-agent-sdk import succeeds.

C) Key validation fails in dialogs

  • Confirm provider/key pairing (OpenRouter vs OpenBio keys are not interchangeable).
  • Check network/proxy restrictions.
  • Retry with known-good key.

D) OpenBio errors or blocked calls

  • Confirm OPENBIO_API_KEY is set.
  • Confirm base URL (OPENBIO_BASE_URL, if overridden).
  • Check firewall/proxy/edge restrictions for api.openbio.tech.

E) Keychain unavailable

  • Install/configure OS keychain backend for keyring.
  • If unavailable, use env vars as temporary fallback.

F) macOS build fails: netcdf.h not found

  • Run: brew install netcdf
  • Add /opt/homebrew/opt/netcdf to PREFIX_PATH in the install command.

G) macOS build fails: GL/glew.h not found

  • Run: brew install glew glm
  • /opt/homebrew in PREFIX_PATH covers these; ensure it is present.

H) PyMOL crashes on launch: AttributeError: type object 'Qt' has no attribute '...'

  • Cause: PyQt6 is installed but PyQt5 is not. PyMOL falls back to PyQt6 when PyQt5 is absent, but the chat UI code uses PyQt5-style flat enum access which is incompatible with PyQt6's namespaced enums.
  • Fix: uv pip install --python .venv/bin/python PyQt5
  • PyMOL's Qt loader tries PyQt5 first; once installed it will be selected automatically.

7) Support Boundaries and Safety

  • Never log or commit plaintext API keys.
  • Never hardcode keys into scripts.
  • Prefer UI save flow and keychain storage for end users.
  • Use masked key displays for status messaging.

8) Quick Diagnostics

Check Python and AI deps:

python -c "import sys; print(sys.version)"
python -c "import keyring, openai; print('deps ok')"
python -c "import claude_agent_sdk; print('claude sdk ok')"

Check environment visibility:

python - <<'PY'
import os
for k in [
    'OPENROUTER_API_KEY',
    'ANTHROPIC_AUTH_TOKEN',
    'OPENBIO_API_KEY',
    'OPENBIO_BASE_URL',
    'PYMOL_AI_OPENROUTER_KEY_SOURCE',
    'PYMOL_AI_OPENBIO_KEY_SOURCE',
]:
    v = os.getenv(k)
    print(k, 'set' if v else 'unset')
PY

Expected outcomes:

  • OpenRouter key set -> AI can run.
  • OpenBio key set -> OpenBio gateway tools become available.
  • OpenBio key unset -> only OpenBio tools are unavailable; core behavior remains.

Attribution

  • Upstream open-source PyMOL rights and trademark notices remain with Schrodinger, LLC.
  • PyMolAI fork-specific integration/packaging documentation is maintained in this fork with explicit attribution in LICENSE, AUTHORS, and DEVELOPERS.
  • Maintainer contact: