# fermiq/drugagent architecture

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

- Interactive diagram: https://gitdiagram.com/fermiq/drugagent
- Repository: https://github.com/fermiq/drugagent

## Overview

##### Project Type & Purpose
- This is a back‐end, full-pipeline ML framework (“DrugAgent”) for automated, LLM-driven drug-discovery programming.
- It orchestrates two collaborating large-language-model agents—a Planner (for high-level solution planning) and an Instructor (for code synthesis)—against benchmark “env” tasks (ADMET, DTI, HTS).

##### Core Directory Analysis
- Top-level scripts & entrypoints:
- runner.py            ← orchestrator that bootstraps tasks, agents, and environment
- environment.py       ← generic env interface for benchmark tasks
- prepare_task.py      ← turns raw datasets into agent-readable tasks
- eval.py              ← local evaluation harness (complemented by MLAgentBench.eval)
- retriever.py         ← optional data/information retriever (e.g., literature or embeddings)
- Agents:
- agents/agent_planner.py & actions_planner.py
- agents/agent_instructor.py & actions_instructor.py
- agents/agent.py      ← shared base class for multi-agent behavior
- Domain-specific tooling:
- agent_tools/         ← drug_utils, protein_utils, featurizer, pybiomed_helper, plus precomputed embeddings
- Benchmarks:
- benchmarks/{admet,dti,hts}/env/*.py & scripts/*.py
- tasks.json           ← master task list
- Support:
- schema.py            ← standard definitions for task metadata
- utils.py             ← cross-cutting utilities
- high_level_actions.py & low_level_actions.py ← predefined action vocabularies
- Logging & outputs:
- runner spawns workspace/ and log-dir/ (agent_log/, env_log/, traces/)
- eval harness reads these logs for metrics

- Orchestration Layer (runner.py + prepare_task.py + schema.py + environment.py + retriever.py)
- Agent Layer
– Planner Agent (agents/agent_planner.py + actions_planner.py)
– Instructor Agent (agents/agent_instructor.py + actions_instructor.py)
- Domain Tools (agent_tools/…)
- Benchmark Environments (benchmarks/{admet,dti,hts}/env & scripts)
- Evaluation & Logging (eval.py + MLAgentBench.eval + log directories)
- External Services (OpenAI/GPT API & any embedding store)
1. Runner → Prepare_Task → Benchmark Env (loads data)
2. Runner ↔ Planner Agent (requests high-level strategies)
3. Planner Agent → Instructor Agent (passes refined sub-tasks)
4. Instructor Agent → agent_tools (invokes featurizer/embeddings)
5. Instructor Agent → LLM API (concrete code synthesis)
6. Instructor Agent → Runner (executes code in workspace)
7. Runner → Env (executes generated code, collects feedback)
8. Runner → Logging (agent_log, env_log, traces)
9. eval.py/MLAgentBench.eval → Logs (post-run metrics)
c. Architectural Patterns & Principles:
- Multi-agent orchestration (master/worker pattern)
- Separation of concerns (planning vs. implementation)
- Plugin-style domain toolboxes
- Benchmark-environment abstraction (Gym-style interface)
- File-based logging for reproducibility
d. Key Technologies & Frameworks:
- Python 3.10
- OpenAI GPT API (configurable via --llm-name arguments)
- MLAgentBench (underlying evaluation framework)
- Conda environment
- Domain dependencies in requirements.txt (e.g., PyBiomed, ESM embeddings)

## Diagram (Mermaid)

```mermaid
graph TB
  %% Orchestration Layer
  subgraph "Orchestration Layer"
    runner["runner.py"]:::orchestration
    prepare_task["prepare_task.py"]:::orchestration
    schema["schema.py"]:::orchestration
    environment["environment.py"]:::orchestration
    retriever["retriever.py"]:::orchestration
  end

  %% Agent Layer
  subgraph "Agent Layer"
    agent_base["agents/agent.py"]:::agents
    planner_logic["agents/agent_planner.py"]:::agents
    planner_actions["agents/actions_planner.py"]:::agents
    instructor_logic["agents/agent_instructor.py"]:::agents
    instructor_actions["agents/actions_instructor.py"]:::agents
  end

  %% Domain Tools
  subgraph "Domain Tools"
    drug_utils["drug_utils.py"]:::domain
    protein_utils["protein_utils.py"]:::domain
    featurizer["featurizer.py"]:::domain
    pybiomed_helper["pybiomed_helper.py"]:::domain
    embeddings["protein_to_esm_embedding.pkl"]:::domain
  end

  %% Benchmark Environments
  subgraph "Benchmark Environments"
    subgraph "ADMET"
      admet_env["benchmarks/admet/env/train.py"]:::benchmark
      admet_prepare["benchmarks/admet/scripts/prepare.py"]:::benchmark
      admet_eval["benchmarks/admet/scripts/eval.py"]:::benchmark
    end
    subgraph "DTI"
      dti_env["benchmarks/dti/env/train.py"]:::benchmark
      dti_prepare["benchmarks/dti/scripts/prepare.py"]:::benchmark
      dti_eval["benchmarks/dti/scripts/eval.py"]:::benchmark
    end
    subgraph "HTS"
      hts_env["benchmarks/hts/env/train.py"]:::benchmark
      hts_prepare["benchmarks/hts/scripts/prepare.py"]:::benchmark
      hts_eval["benchmarks/hts/scripts/eval.py"]:::benchmark
    end
    tasks["benchmarks/tasks.json"]:::benchmark
  end

  %% Evaluation & Logging
  subgraph "Evaluation & Logging"
    eval_local["eval.py"]:::logging
    mlagentbench_eval["MLAgentBench.eval"]:::logging
    workspace["workspace/"]:::logging
    agent_log["log-dir/agent_log/"]:::logging
    env_log["log-dir/env_log/"]:::logging
    traces["log-dir/traces/"]:::logging
  end

  %% External LLM API
  llm_api("LLM API"):::external

  %% Data Flow & Relationships
  runner -->|"prepare task"| prepare_task
  prepare_task -->|"load env"| admet_env & dti_env & hts_env
  runner <-->|"plan"| planner_logic
  planner_logic -->|"uses"| planner_actions
  planner_logic -->|"refined tasks"| instructor_logic
  instructor_logic -->|"uses"| instructor_actions
  instructor_logic -->|"invoke tools"| drug_utils & protein_utils & featurizer & pybiomed_helper & embeddings
  instructor_logic -->|"synthesize"| llm_api
  instructor_logic -->|"execute code"| runner
  runner -->|"execute"| admet_env & dti_env & hts_env
  runner -->|"log to"| agent_log & env_log & traces & workspace
  eval_local -->|"read logs"| agent_log & env_log & traces
  mlagentbench_eval -->|"read logs"| agent_log & env_log & traces

  %% Click Events
  click runner "https://github.com/fermiq/drugagent/blob/main/runner.py"
  click prepare_task "https://github.com/fermiq/drugagent/blob/main/prepare_task.py"
  click schema "https://github.com/fermiq/drugagent/blob/main/schema.py"
  click environment "https://github.com/fermiq/drugagent/blob/main/environment.py"
  click retriever "https://github.com/fermiq/drugagent/blob/main/retriever.py"
  click agent_base "https://github.com/fermiq/drugagent/blob/main/agents/agent.py"
  click planner_logic "https://github.com/fermiq/drugagent/blob/main/agents/agent_planner.py"
  click planner_actions "https://github.com/fermiq/drugagent/blob/main/agents/actions_planner.py"
  click instructor_logic "https://github.com/fermiq/drugagent/blob/main/agents/agent_instructor.py"
  click instructor_actions "https://github.com/fermiq/drugagent/blob/main/agents/actions_instructor.py"
  click drug_utils "https://github.com/fermiq/drugagent/blob/main/agent_tools/drug_utils.py"
  click protein_utils "https://github.com/fermiq/drugagent/blob/main/agent_tools/protein_utils.py"
  click featurizer "https://github.com/fermiq/drugagent/blob/main/agent_tools/featurizer.py"
  click pybiomed_helper "https://github.com/fermiq/drugagent/blob/main/agent_tools/pybiomed_helper.py"
  click embeddings "https://github.com/fermiq/drugagent/blob/main/agent_tools/protein_to_esm_embedding.pkl"
  click admet_env "https://github.com/fermiq/drugagent/blob/main/benchmarks/admet/env/train.py"
  click admet_prepare "https://github.com/fermiq/drugagent/blob/main/benchmarks/admet/scripts/prepare.py"
  click admet_eval "https://github.com/fermiq/drugagent/blob/main/benchmarks/admet/scripts/eval.py"
  click dti_env "https://github.com/fermiq/drugagent/blob/main/benchmarks/dti/env/train.py"
  click dti_prepare "https://github.com/fermiq/drugagent/blob/main/benchmarks/dti/scripts/prepare.py"
  click dti_eval "https://github.com/fermiq/drugagent/blob/main/benchmarks/dti/scripts/eval.py"
  click hts_env "https://github.com/fermiq/drugagent/blob/main/benchmarks/hts/env/train.py"
  click hts_prepare "https://github.com/fermiq/drugagent/blob/main/benchmarks/hts/scripts/prepare.py"
  click hts_eval "https://github.com/fermiq/drugagent/blob/main/benchmarks/hts/scripts/eval.py"
  click tasks "https://github.com/fermiq/drugagent/blob/main/benchmarks/tasks.json"
  click eval_local "https://github.com/fermiq/drugagent/blob/main/eval.py"

  %% Styles
  classDef orchestration fill:#add8e6,stroke:#000,stroke-width:1px
  classDef agents fill:#90ee90,stroke:#000,stroke-width:1px
  classDef domain fill:#ffff66,stroke:#000,stroke-width:1px
  classDef benchmark fill:#ffcc99,stroke:#000,stroke-width:1px
  classDef logging fill:#d3d3d3,stroke:#000,stroke-width:1px
  classDef external fill:#ffc0cb,stroke:#000,stroke-width:1px
```
