Skip to content

Installation

Prerequisites

  • Python 3.12
  • uv package manager
  • A DeepSeek API key for the default cloud backend, or a local Ollama instance

Install Dependencies

uv sync --frozen

Optional extras:

# MCP server for ChatGPT/Codex/Claude-style external clients
uv sync --frozen --extra mcp

# Aligned peptide sequence logos (PyFAMSA is GPL-3.0; Linux wheels need glibc >= 2.34)
uv sync --frozen --extra peptide-logos

Retrosynthesis is optional and uses SynPlanner 1.7.0:

uv sync --frozen --extra retrosynthesis --extra mcp
uv run --no-sync chainlit run chainlit_app.py -w

Use uv run --no-sync after installing extras, or repeat the extras on each uv run; otherwise uv may remove them. SynPlanner's published dependencies support Linux x86_64 and macOS ARM64. Linux ARM64 currently lacks chytorch-synplan wheels; use the core installation there or run retrosynthesis on a supported host. The new version uses chython and its matching TSV rules and policy preset. Historical CGRtools-based manuscript results retain their original software and asset manifests.

Model checkpoints

Model weights are not shipped with the package. They download from Hugging Face on first use and are cached under ~/.cache/cs_copilot/models/, except chembed's, which huggingface_hub caches itself.

Model Repository Size
chembed SELFIES transformer VAE 3BioCompBio/chembed-default 227 MB
Peptide WAE axelrolov/wae_peptides —
GTM manifold (chembed latents) axelrolov/chemspacecopilot-gtm-chembed 3.5 MB

chembed is the small-molecule latent engine; the deepchemography LSTM autoencoder was retired after v0.4.0, and peptide design keeps the deepchemography WAE. A manifold is only valid for the latent space it was fitted on; see Tools. One is refit with:

uv run --no-sync python scripts/refit_gtm_manifold.py \
    --frameset gtm_frameset_training.csv \
    --output ~/.cache/cs_copilot/models/gtm-chembed/GTM_manifold_chembed_900_225.pkl.gz

Environment Configuration

For file-based configuration, copy .env.example to .env in the project root:

# Required only for the default DeepSeek provider
DEEPSEEK_API_KEY=your-api-key-here

# Optional model overrides (otherwise .modelconf is used)
# MODEL_PROVIDER=deepseek
# MODEL_ID=deepseek-chat
# OLLAMA_HOST=http://localhost:11434

# Optional — S3/MinIO storage (set USE_S3=true only when you want remote storage)
USE_S3=false
# When enabled:
S3_ENDPOINT_URL=http://localhost:9000
MINIO_ACCESS_KEY=cs_copilot
MINIO_SECRET_KEY=chempwd123
ASSETS_BUCKET=chatbot-assets

# Optional — ChEMBL local MySQL (faster queries, offline use)
# Download dump: https://chembl.gitbook.io/chembl-interface-documentation/downloads
# CHEMBL_MYSQL_HOST=localhost
# CHEMBL_MYSQL_PORT=3306
# CHEMBL_MYSQL_USER=chembl
# CHEMBL_MYSQL_PASSWORD=
# CHEMBL_MYSQL_DATABASE=chembl_36

The repository also includes a tracked .modelconf file. Edit it if you want to switch from the default DeepSeek backend to a local Ollama model.

Running the Application

Chainlit App

uv run chainlit run chainlit_app.py -w

Access the application at http://localhost:8000.

Notes:

  • The bundled chainlit.toml currently has [persistence] enabled = false.
  • The app sets a per-thread title from your first message; you can rename it in the UI.

Jupyter Notebook

An example workflow is available in notebooks/cs_copilot.ipynb.

Optional Services

S3/MinIO Storage

# Run the interactive setup script
python scripts/setup_s3.py

# Or build and start the pinned MinIO source image manually
docker build -f Dockerfile.minio --target server -t cs_copilot-minio:local .
docker run -d --name minio \
  -p 9000:9000 -p 9001:9001 \
  -v /mnt/data:/data \
  -e MINIO_ROOT_USER=cs_copilot \
  -e MINIO_ROOT_PASSWORD=chempwd123 \
  cs_copilot-minio:local server /data --console-address ":9001"

If the container already exists: docker start minio

Optional Chainlit Persistence

Chainlit persistence is disabled by default in chainlit.toml. Only set up PostgreSQL if you plan to enable Chainlit persistence manually.

docker run --name chainlit-pg -p 5432:5432 -d \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_USER=postgres \
  -e POSTGRES_DB=chainlit \
  postgres:16

export DATABASE_URL="postgresql://postgres:postgres@localhost:5432/chainlit"

If the container already exists: docker start chainlit-pg

ChEMBL Local Database (Optional)

By default the ChEMBL Downloader agent queries the ChEMBL REST API. For faster queries and offline use, you can point it at a local MySQL copy of ChEMBL instead.

Setup:

  1. Download the MySQL dump from the ChEMBL downloads page or directly from the EBI FTP.
  2. Load the dump into a MySQL 8+ server.
  3. Install project dependencies (MySQL support is included): 
    uv sync --frozen
  4. Set the environment variables: 
    CHEMBL_MYSQL_HOST=localhost
CHEMBL_MYSQL_PORT=3306
CHEMBL_MYSQL_USER=chembl
CHEMBL_MYSQL_PASSWORD=your-password
CHEMBL_MYSQL_DATABASE=chembl_36

When CHEMBL_MYSQL_HOST is set, the agent automatically uses MySQL. The REST API remains available as a fallback. Unset the variable to revert to REST-only mode.