Add portable molecore_foundry env spec + agent setup docs

.envrc

@@ -0,0 +1,34 @@
+# Foundry environment activation (direnv)
+#
+# Goal:
+# - `cd` into this repo (or any subdir) => activate local venv
+# - `cd` out                           => revert to previous environment
+#
+# This relies on your shell's direnv hook (no custom `cd` wrapper).
+
+source .venv/bin/activate
+export FOUNDRY_ENV_ACTIVE=1
+
+# AtomWorks mirrors (recommended):
+# - Keep CCD local (small)
+# - Keep PDB mirror optional (large)
+#
+# If you have Borg's foundry databases mounted locally, prefer:
+#   borg:/runtime/databases/foundry/  ->  ~/mounts/foundry_databases/
+# With mirrors at:
+#   ~/mounts/foundry_databases/ccd
+#   ~/mounts/foundry_databases/pdb
+#
+# Otherwise, fall back to repo-local CCD (small) under .foundry_mirrors/ccd.
+FOUNDRY_DB="$HOME/mounts/foundry_databases"
+if [[ -d "$FOUNDRY_DB/ccd" ]]; then
+  export CCD_MIRROR_PATH="$FOUNDRY_DB/ccd"
+else
+  export CCD_MIRROR_PATH="$PWD/.foundry_mirrors/ccd"
+fi
+
+if [[ -d "$FOUNDRY_DB/pdb" ]]; then
+  export PDB_MIRROR_PATH="$FOUNDRY_DB/pdb"
+fi
+
+

.gitignore

@@ -136,6 +136,7 @@ celerybeat.pid
 # Environments
 .env
 .venv
+local-pyproject.toml
 env/
 venv/
 ENV/
@@ -206,6 +207,9 @@ wandb/
 # Hydra
 .hydra/
 
+# AtomWorks / Foundry local mirrors (large; keep out of git)
+.foundry_mirrors/
+
 # Logs
 logs/
 

molecore_env_portable/README.md

@@ -0,0 +1,89 @@
+# molecore_foundry Portable Environment
+
+This is a portable Python environment specification designed for biomolecular modeling workflows, optimized for both macOS and Linux platforms.
+
+## What's Included
+
+### Core Dependencies (Always Installed)
+- **atomworks** (2.2.0) - Unified framework for biomolecular structure processing
+- **biotite** (1.4.0) - Computational structural biology toolkit
+- **torch** (2.9.1) - Machine learning framework
+- **numpy** (2.2.6) - Scientific computing
+- **pandas** (2.3.3) - Data analysis
+- **scipy** (1.16.3) - Scientific computing
+- **requests** - HTTP library
+- **python-dotenv** - Environment variable management
+- **pyyaml** - YAML parsing
+- **ipykernel** - Jupyter notebook support
+- **jupyterlab** - Advanced notebook interface
+- **tqdm** - Progress bars
+
+### Bio + Database Access (Recommended)
+- **biopython** - Biological computation
+- **rcsbsearchapi** - PDB database search
+- **bioservices** - Biological web services
+- **httpx** - Modern HTTP client
+- **gget** - Sequence/structure fetching
+
+### Visualization
+- **matplotlib** - Plotting
+- **seaborn** - Statistical visualization
+- **py3dmol** - 3D molecular visualization
+- **nglview** - Jupyter molecular viewer
+
+### Agentic Workflows
+- **openai** - OpenAI API client
+- **anthropic** - Anthropic API client
+- **groq** - Groq API client
+
+### Cloud Computing
+- **modal** - Serverless cloud platform
+
+## Setup Instructions
+
+### On macOS (CPU)
+```bash
+uv python install 3.12
+uv venv molecore_foundry --python 3.12
+source molecore_foundry/bin/activate
+pip install -r requirements.txt
+```
+
+### On Linux (GPU - Optional CUDA)
+```bash
+uv python install 3.12
+uv venv molecore_foundry --python 3.12
+source molecore_foundry/bin/activate
+pip install -r requirements.txt
+# For CUDA support (optional):
+pip install --upgrade torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+```
+
+### Verification
+```bash
+python -c "
+import torch, atomworks, biotite, numpy as np, pandas as pd, scipy
+import requests, rcsbsearchapi, openai, modal
+print('✅ All packages imported successfully!')
+print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')
+"
+```
+
+## Usage Notes
+
+- **AtomWorks**: Requires PDB/CCD mirror paths for full functionality (set `PDB_MIRROR_PATH` and `CCD_MIRROR_PATH`)
+- **PyTorch**: CPU version installed by default; upgrade to CUDA version on GPU machines
+- **Modal**: Requires account setup and API keys for cloud deployment
+- **PyRosetta**: Install separately using `pyrosetta-installer` if needed
+
+## Environment Variables
+
+Optional but recommended:
+```bash
+export PDB_MIRROR_PATH=/path/to/pdb/mirror
+export CCD_MIRROR_PATH=/path/to/ccd/mirror
+```
+
+## File Structure
+- `requirements.txt` - Complete package list for reproduction
+- `README.md` - This documentation

molecore_env_portable/clean_requirements.txt

@@ -0,0 +1,16 @@
+beautifulsoup4 @ file:///home/conda/feedstock_root/build_artifacts/beautifulsoup4_1705564648255/work
+lxml==6.0.2
+nltk==3.9.2
+pandas @ file:///Users/runner/miniforge3/conda-bld/pandas_1715897646986/work
+PyGithub==2.8.1
+pymolPy3==0.1.2
+python-dateutil @ file:///home/conda/feedstock_root/build_artifacts/python-dateutil_1709299778482/work
+python-dotenv==1.0.1
+PyYAML @ file:///Users/runner/miniforge3/conda-bld/pyyaml_1695373486380/work
+requests @ file:///home/conda/feedstock_root/build_artifacts/requests_1717057054362/work
+selenium==4.39.0
+sendgrid==6.12.5
+spacy==3.8.11
+SQLAlchemy==2.0.45
+tenacity==9.0.0
+webdriver-manager==4.0.2

molecore_env_portable/requirements.txt

@@ -0,0 +1,15 @@
+beautifulsoup4 @ file:///home/conda/feedstock_root/build_artifacts/beautifulsoup4_1705564648255/work
+lxml==6.0.2
+nltk==3.9.2
+pandas @ file:///Users/runner/miniforge3/conda-bld/pandas_1715897646986/work
+PyGithub==2.8.1
+python-dateutil @ file:///home/conda/feedstock_root/build_artifacts/python-dateutil_1709299778482/work
+python-dotenv==1.0.1
+PyYAML @ file:///Users/runner/miniforge3/conda-bld/pyyaml_1695373486380/work
+requests @ file:///home/conda/feedstock_root/build_artifacts/requests_1717057054362/work
+selenium==4.39.0
+sendgrid==6.12.5
+spacy==3.8.11
+SQLAlchemy==2.0.45
+tenacity==9.0.0
+webdriver-manager==4.0.2

molecore_env_portable/setup.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+# molecore_foundry Environment Setup Script
+# This script sets up the molecore_foundry environment on macOS or Linux
+
+set -e
+
+echo "🚀 Setting up molecore_foundry environment..."
+
+# Check if uv is installed
+if ! command -v uv &> /dev/null; then
+    echo "❌ uv is not installed. Please install uv first:"
+    echo "curl -LsSf https://astral.sh/uv/install.sh | sh"
+    exit 1
+fi
+
+# Install Python 3.12 if not available
+echo "📦 Installing Python 3.12..."
+uv python install 3.12
+
+# Create virtual environment
+echo "🏗️  Creating virtual environment..."
+uv venv molecore_foundry --python 3.12
+
+# Activate environment
+echo "🔄 Activating environment..."
+source molecore_foundry/bin/activate
+
+# Install packages
+echo "📦 Installing packages..."
+pip install -r requirements.txt
+
+# Verify installation
+echo "🔍 Verifying installation..."
+python -c "
+import torch, atomworks, biotite, numpy as np, pandas as pd, scipy
+import requests, rcsbsearchapi, openai, modal
+print('✅ All packages imported successfully!')
+print(f'PyTorch: {torch.__version__}, CUDA: {torch.cuda.is_available()}')
+"
+
+echo ""
+echo "🎉 Environment setup complete!"
+echo ""
+echo "To use the environment:"
+echo "source molecore_foundry/bin/activate"
+echo ""
+echo "For CUDA support on Linux (optional):"
+echo "pip install --upgrade torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124"

tools/envs/molecore_foundry/AGENT_SETUP.md

@@ -0,0 +1,96 @@
+## Agent instructions: build environments (any platform)
+
+This repo supports two related setups:
+
+- **Global default bio env** (recommended): `~/.venvs/molecore_foundry`
+- **Repo env** (recommended when working on Foundry): `./.venv` in the repo root (direnv-enabled via `.envrc`)
+
+### Prereqs (all platforms)
+
+- Install `uv`
+- Python: **3.12** (Foundry requires `>=3.12`)
+
+---
+
+## A) Global default env (portable across macOS/Linux)
+
+Create and activate:
+
+```bash
+uv python install 3.12
+uv venv ~/.venvs/molecore_foundry --python 3.12
+source ~/.venvs/molecore_foundry/bin/activate
+```
+
+Install the default package set (from this repo’s env spec):
+
+```bash
+uv pip install -e /path/to/foundry/tools/envs/molecore_foundry
+```
+
+### Linux GPU: CUDA PyTorch (opt-in)
+
+On GPU machines, override CPU torch with a CUDA wheel:
+
+```bash
+# cu124 (recommended)
+uv pip install --upgrade torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
+
+# or cu121
+uv pip install --upgrade torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
+```
+
+### PyRosetta (optional)
+
+Install installer + run it:
+
+```bash
+uv pip install pyrosetta-installer
+python -c "import pyrosetta_installer; pyrosetta_installer.install_pyrosetta(silent=True)"
+python -c "import pyrosetta; pyrosetta.init('-mute all'); print('PyRosetta OK')"
+```
+
+### PyMOL (optional)
+
+- The env installs `pymolpy3` (wrapper). Full PyMOL is usually installed separately (system/Homebrew/conda).
+
+Verify wrapper import:
+
+```bash
+python -c "import pymolPy3; print('pymolPy3 OK')"
+```
+
+---
+
+## B) Repo env (Foundry dev in this repository)
+
+From the repo root:
+
+```bash
+uv python install 3.12
+uv venv --python 3.12
+source .venv/bin/activate
+uv pip install -e ".[all,dev]"
+```
+
+If you use `direnv`, allow the repo once:
+
+```bash
+direnv allow
+```
+
+---
+
+## Mirrors and Borg mount (optional but recommended)
+
+AtomWorks can use mirrors for PDB/CCD. This repo’s `.envrc` prefers a Borg-mounted databases directory:
+
+- Remote: `borg:/runtime/databases/foundry/`
+- Local mountpoint: `~/mounts/foundry_databases/`
+- Mirrors:
+  - `~/mounts/foundry_databases/ccd`
+  - `~/mounts/foundry_databases/pdb` (large; optional)
+
+macOS note: `sshfs` requires macFUSE to be installed and permitted by macOS security policy.
+
+