josh-huang/ml-research-agent

How josh-huang/ml-research-agent works

This repository is an autonomous recommender-model research agent: it loads KuaiRand data, establishes an FM baseline, iterates through evidence-based experiments, and produces a ranked test submission. The central loop is documented in the README; sampled source confirms the training, extended data loading, research retrieval, and submission paths. Some agent-tool wiring and evaluation details are documented but their implementation was not sampled, so uncertain internal links are omitted.

Main entry points: train.py Training loop · main.py Loop orchestrator · react.py ReAct researcher · tools.py Experiment tools

Components 25

Research agent

Loop orchestrator agent/main.py
ReAct researcher agent/react.py
LLM client agent/llm.py
Experiment tools agent/tools.py
Literature retrieval agent/research.py
EDA summary agent/eda.py
Config search agent/search.py
Run state agent/state.py
Run logger agent/logger.py

Modeling pipeline

Extended loader models/data_loader.py
Training loop models/train.py
FM model models/fm_torch.py
DeepFM model models/deepfm.py
DIN model models/din.py
Ranking losses models/losses.py
Official evaluator kuairand-starter-kit/kuairand-starter-kit/evaluate.py

Results and delivery

Submission generator submission/make_submission.py
Submission writer kuairand-starter-kit/kuairand-starter-kit/submit.py
Ranked CSV submission/final.csv
Run records run_logs/run_log.jsonl
Run dashboard dashboard/app.py

Other components

Operator
Anthropic API
arXiv API
KuaiRand data

Connections 27

Operator → Loop orchestrator: starts run
Loop orchestrator → Extended loader: loads data
KuaiRand data → Extended loader: provides rows
Loop orchestrator → EDA summary: builds summary
Loop orchestrator → ReAct researcher: starts episode
ReAct researcher → LLM client: requests reasoning
LLM client → Anthropic API: sends prompts
ReAct researcher → Experiment tools: dispatches tools
ReAct researcher → Literature retrieval: requests papers
Literature retrieval → arXiv API: queries
ReAct researcher → Config search: normalizes config
Loop orchestrator → Experiment tools: runs baseline
Experiment tools → Training loop: runs experiment
Training loop → FM model: builds model
Training loop → DeepFM model: builds model
Training loop → DIN model: builds model
Training loop → Ranking losses: computes objective
Training loop → Official evaluator: scores predictions
Experiment tools → Run state: updates state
Experiment tools → Run logger: records run
Run logger → Run records: appends records
Submission generator → Extended loader: loads features
Submission generator → Training loop: trains best config
Submission generator → Submission writer: writes scores
Submission writer → Ranked CSV: creates file
Run dashboard → Run records: reads trail
Run dashboard → Run state: reads state

More Python diagrams: earthtojake/text-to-cad · huggingface/open-r1 · ranaroussi/yfinance · ycm-core/youcompleteme · cinnamon/kotaemon

Drawn by GitDiagram on September 28, 2026 from the repository's file tree, README and source files. Read as Markdown ·