freephdlabor - Moses Yebei

The Problem

Scientific research automation is typically either rigid pipeline orchestration or single-agent assistants that cannot sustain multi-step investigation. Researchers need a system that can generate hypotheses, run experiments, analyze results, and produce a manuscript without constant human intervention—while remaining adaptable to their specific domain.

What This Does

freephdlabor is a multiagent framework that automates the research lifecycle end-to-end. The core package (freephdlabor/) implements specialized agents—manager_agent, ideation_agent, experimentation_agent, writeup_agent, and others—that coordinate through a supervision layer. The external_tools/run_experiment_tool/ directory contains a separate, more experimental tree-search-based scientist that performs experiments and produces LaTeX papers directly.

The system ships with toolkits for web browsing, arXiv fetching, file editing, knowledge-base management, and LaTeX compilation. It supports two usage modes: out-of-the-box operation with a single task prompt, or domain customization by defining domain-specific tools.

How It Is Wired

Execution starts at launch_multiagent.py, which routes through freephdlabor/agents/manager_agent.py. That agent coordinates specialized agents via freephdlabor/supervision/supervision_manager.py. The most-connected module is freephdlabor/toolkits/model_utils.py (23 modules import it), making it the highest-blast-radius file for changes. The agent layer has an import cycle involving manager_agent, ideation_agent, and utils.py—changing any of these risks breaking the others.

The writeup pipeline routes through writeup_agent.py, which calls compile_latex and search heavily (8 call sites each). The external_tools/run_experiment_tool/ai_scientist/treesearch/agent_manager.py entry point (run) reaches 85 functions and performs filesystem writes via notes_dir.mkdir. The system makes outbound network calls (14 functions), reads/writes files (46 functions), calls models for inference (22 functions), and runs external commands (12 functions).

The mdconvert.py file in text_web_browser is the most heavily routed file (38 functions, 19 classes, called from 6 files), handling HTML-to-markdown conversion for web research.

How To Use It

git clone https://github.com/moses-y/freephdlabor
cd freephdlabor
conda env create -f environment.yml
conda activate freephdlabor
# Edit .env with your API keys (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)
python launch_multiagent.py --task "Your research idea here"

Configuration lives in .llm_config.yaml for model selection and .env for API keys. The external_tools/run_experiment_tool/ has its own config (bfts_config.yaml) and requirements.

Real-World Use

A materials science lab could define custom tools for crystallographic data analysis, then run:

python launch_multiagent.py --task "Investigate the effect of annealing temperature on grain boundary migration in nickel superalloys"

The system would search literature, design experiments, execute simulations, and draft a paper—with the lab reviewing outputs at each stage.

Code Health & Issues

Static analysis found 125 issues (38 high, 86 medium, 1 low) across 8 categories. The high-severity findings are:

Import cycle (5 files): utils.py, ideation_agent.py, manager_agent.py participate in circular dependencies.
Deep nesting (34 instances): base_research_agent.py has indentation depth of 8.
Oversized files (3): vlm_document_analysis_tool.py (798 lines), latex_compiler_tool.py, parallel_agent.py.
Duplicated code: 46 files share 1004 repeated 6-line blocks.

Medium findings include broad exception handling (12 instances), a hub module (model_utils.py), and high branching density in file_editing_tools.py.

The code health audit confirms: a .env file is committed despite being gitignored (rotate credentials), no test suite exists, no CI workflow, and assets/preview.mp4 (6.1MB) exceeds the 5MB threshold. Dependencies are declared without a lockfile.

The Bottom Line

This is a serious research-automation framework with real breadth, but it's early-stage code: no tests, no CI, and a committed .env that needs immediate attention. Researchers wanting to automate their lab's workflow will find value, but should budget time for hardening before production use.

What the analyser found

Deployment readiness

3/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

199 files

Python145
JSON5
Markdown4
YAML3
HTML1
JavaScript1

Module dependencies

The 10 most depended-upon modules of 146, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_hdlabor_toolkits_model_utils["model_utils"] n1_r_agents_base_research_agent["base_research_agent"] n2_prompts_workspace_management["workspace_management"] n3_e_editing_file_editing_tools["file_editing_tools"] n4_scientist_treesearch_journal["journal"] n5_p_vlm_document_analysis_tool["vlm_document_analysis_to"] n6_ompts_system_prompt_template["system_prompt_template"] n7_freephdlabor_utils["utils"] n8__writeup_latex_compiler_tool["latex_compiler_tool"] n9__treesearch_backend___init__["__init__"] n4_scientist_treesearch_journal --> n9__treesearch_backend___init__ n8__writeup_latex_compiler_tool --> n0_hdlabor_toolkits_model_utils classDef cyc stroke:#ef4444,stroke-width:2px; class n7_freephdlabor_utils cyc;

Dependencies

26 declared dependencies, none a major version behind. Resolved 26 of 26 against the registry.

Findings

MediumNo CI/CD pipeline detected - no automated build/test gate .github/ or CI config
LowDependencies declared without a lockfile - non-reproducible builds external_tools/run_experiment_tool/requirements.txt
LowSecret-shaped paths present; the code-health audit confirms or clears them .env

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high4

medium3

Untrack the file your own .gitignore says to ignorehigh

.env

tracked although .gitignore excludes it

The author already decided this file must never be committed, so its presence is an accident nobody noticed, which means the credentials in it are the ones actually in use.

Fix: git rm --cached the path and rotate; the ignore rule is already correct.

Add a test suite; this repository has nonehigh146 occurrences

146 source files, no test files

Any change ships with no signal that existing behaviour still holds, so a regression reaches production undetected.

Fix: Add one test per public entry point, then a CI step that runs them.

Add a workflow that builds and tests this repositoryhigh

146 source files, no CI configuration

Every change merges with nobody having run the build once, which across this estate is 499 repositories.

Fix: Add a workflow running the project build and test command on push and pull_request.

Remove the committed .env and rotate what it holdshigh

.env

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Add a pre-commit secret gatemedium

a secret-shaped file is tracked and no repo-level gate is visible

Without a gate the same class of leak recurs on the next commit, so a leak finding is the symptom and this is the cause.

Fix: Add a pre-commit hook scanning staged content, and enable push protection.

Move large binaries to Git LFS or out of the repositorymedium

assets/preview.mp4

1 blobs over 5MB: preview.mp4 6.1MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.