How ur-whitelab/mdcrow works
Project Type and Purpose
• MDCrow is an open-source Python library (toolset) that exposes an LLM-driven agent for automating molecular dynamics tasks (setup, execution, analysis) in OpenMM.
• It is not a full-stack web app but a domain-specific CLI/module you import in Python or run in notebooks.
File-Structure Overview
• Top-level package: mdcrow/
• agent/ – orchestrates LLM interactions, memory, prompt construction.
• tools/ – a plugin registry of “tools” subdivided into base_tools/ which itself branches into
– analysis_tools/ (e.g. RMSD, PCA, RDF)
– preprocess_tools/ (e.g. PDB cleanup, packing, UniProt lookup)
– simulation_tools/ (OpenMM setup, run scripts)
– util_tools/ (registry management, search)
• utils/ – shared helpers (data handling, path registry, checkpointing).
• version, setup, tests, notebooks, CI configs.
Key Insights from README
• Uses LangChain’s Agent abstraction to load “tools,” manage conversation memory, and dispatch LLM calls.
• Supports multiple LLM providers via environment‐driven API keys (.env).
• Core dependency: OpenMM (conda environment), plus langchain and provider adapters.
a. Main Components
• Client code / Notebook / Python entrypoint (MDCrow class)
• Agent Core (LangChain Agent wrapper)
• Memory Store
• Prompt Manager
• Tool Registry / Dispatcher
• Tool Categories:
– Preprocessing Tools
– Simulation Tools
– Analysis Tools
– Utility Tools
• External Services & Libraries:
– LLM Provider APIs (OpenAI, TogetherAI, etc.)
– OpenMM library
– External Data APIs (UniProt)
• File System / Data Store (for inputs/outputs like PDBs, trajectories)
b. Relationships & Data Flows
1. User → MDCrow.run() → Agent Core
2. Agent Core ↔ Memory Store (to track dialogue/history)
3. Agent Core → Prompt Manager → formatted prompt
4. Prompt → LLM Provider API → LLM Response
5. Agent Core inspects LLM response → identifies tool call → Tool Registry
6. Tool Dispatcher → executes selected tool module (preprocess, sim, analysis)
7. Tool uses OpenMM or data libraries → produces results
8. Results → Agent Core → LLM (optional summarization) → User
c. Architectural Patterns & Principles
• Plugin/Registry pattern for tools: easy to extend by dropping new tool modules into the tools/ hierarchy.
• Separation of concerns:
• Agent orchestration (LLM interaction + memory)
• Tool implementations (MD workflows)
• Utility wrappers (I/O, search, registry)
• Dependency injection of LLM providers via environment variables.
d. Key Technologies & Frameworks
• Python 3.x, conda environment
• LangChain Agent API
• OpenAI / Anthropic / Together / Fireworks adapters
• OpenMM for molecular simulation
• Standard Python data & plotting libs (used inside tools)