# ur-whitelab/mdcrow architecture

> Architecture diagram of the GitHub repository ur-whitelab/mdcrow, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ur-whitelab/mdcrow
- Repository: https://github.com/ur-whitelab/mdcrow

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Layer
    User["User / Notebook / Client"]:::external
    User -->|"runs run() on"| MDCrow

    %% Agent Layer
    sub
```
