{
"markdown": "\n\n# Autonomous ML Research Engineer\n\n**A codex-style CLI for autonomous ML research.** Reads papers, understands\ncodebases, plans experiments, writes patches, runs training, evaluates\nresults, and conducts end-to-end research workflows — entirely in your\nterminal, orchestrated by LangGraph.\n\n[](https://www.python.org/)\n[](https://www.langchain.com/langgraph)\n[](https://docs.pydantic.dev/)\n[](LICENSE)\n\n
\n\n---\n\n## Why\n\nExisting ML-research tooling is either notebooks (not reproducible), SaaS\n(your data leaves), or scaffolding (you still write the loop).\n`research-engineer` is a single binary that closes the loop: it is an\nagent you talk to like codex — one prompt becomes literature review,\nhypotheses, an experiment plan, patches, runs, evaluation, and a report —\nwith every stage typed, checkpointed, and approval-gated.\n\n**Stack:** Python 3.12 · typer CLI · **LangGraph** (the only research\nengine) · LangChain providers · pydantic v2 · rich + prompt_toolkit\nterminal UX. No server, no frontend, no Docker — a pure CLI product.\n\n## Install\n\n```bash\ngit clone && cd AutonomousMLResearchEngineer\nuv sync\nuv run research-engineer --help\n```\n\n## Quick start\n\n```bash\n# 1. The interactive session (codex-style REPL)\nuv run research-engineer chat --repo ./my-repo\n# Later: uv run research-engineer chat --resume session_ab12cd34ef56\n\n# research-engineer> /research \"Design a more efficient diffusion transformer\"\n# research-engineer> /analyze 2503.12345\n# research-engineer> What loss schedules work best for MoE routing?\n# research-engineer> /exit\n\n# 2. One-shot paper analysis (rule-based, no LLM cost)\nuv run research-engineer analyze 2503.12345\n\n# 3. End-to-end research workflow (LangGraph engine)\nexport OLLAMA_API_KEY=\"...\"\nuv run research-engineer research \"Improve attention efficiency\" \\\n --max-papers 30 --dry-run\n# -> output/research//research_report.md\n\n# 4. Autonomous loop with approval gates\nuv run research-engineer loop run \"Reduce val loss below 0.1\" \\\n --repo ./my-repo --max-iterations 5 --approval\n```\n\n## The chat session\n\n`research-engineer chat` opens a terminal REPL over the same agents the\none-shot commands use:\n\n| Command | What it does |\n|---------|--------------|\n| `/task [--apply] [--tests] [--delegate] ` | Run the terminal-first coding agent in the active repository; dry-run by default |\n| `/repo [path]` | Show or change the active repository workspace |\n| `/research ` | Full autonomous workflow: literature → synthesis → hypotheses → planning → execution → analysis → report |\n| `/analyze ` | Analyze an arXiv ID, arXiv URL, or local PDF |\n| `/llm ` | Ask the configured LLM directly |\n| `/clear` | Clear the bounded LLM conversation context and turn history |\n| `/status` | Session + provider status |\n| `/help`, `/exit` | The usual |\n\nFree-form lines continue a bounded LLM conversation. Coding turns reuse the\nsame `TaskAgent` as the one-shot `task` command, including repository memory,\ndelegation, review/repair, and patch-first safety. Output renders as rich\npanels/tables; input history uses prompt_toolkit. Workspace, turn history, and\nconversation context are saved atomically under `output/sessions/`; the banner\nshows the session ID accepted by `chat --resume`.\n\n## What's inside\n\n**15 phases, one CLI.** Paper analysis (1), repository analysis (2),\nexperiment planning (3), patch-first implementation (4), research memory\n(5), literature intelligence (6), experiment execution (7), evaluation\n(8), the autonomous loop (9), a provider-agnostic LLM layer (10),\nterminal-first coding (11), repository memory with hybrid retrieval (12),\nmulti-agent delegation (13), self-repair (14), and the end-to-end\nresearch workflow (15) — 20 agents, 61 typed tools, 250+ pydantic models.\n\n**LangGraph is the research engine.** The seven research stages run as a\nLangGraph `StateGraph` (`graphs/research.py`) with checkpointed,\nresumable threads (`--thread-id`; PostgreSQL snapshots via\n`RE_LANGGRAPH_CHECKPOINT_DSN` + the `postgres` extra). The workflow\nframework remains the stage-executor authority — the graph owns\nordering, state, and persistence.\n\n**Benchmarks over the production path.** The P1/P2 benchmark suites\n(`research-engineer benchmark`) execute every case directly through the\nsame `AgentRuntime → ToolGateway → SafetyController → checkpointing`\nstack an autonomous run uses, then grade the persisted payloads — no\nseparate serving tier, no difference between what is measured and what\nis shipped.\n\n## Configuration\n\n**LLM routing** — `llm_config.yaml` maps agents to models\n(`RE_LLM_CONFIG` overrides the path):\n\n```yaml\nrouting:\n ResearchAgent: glm-5.3-flash\n CodingAgent: kimi-k2.7-code\ndefault_model: glm-5.3-flash\n```\n\nProviders: Ollama Cloud (default), OpenAI, Anthropic, local Ollama, and\nany LangChain chat model — all behind one `LLMProvider` ABC with health\nchecks, failover, cost tracking, and streaming. Phases 1–3 stay\nrule-based (zero API cost); LLM is spent where it adds value.\n\n**Key env vars:** `OLLAMA_API_KEY`, `OLLAMA_BASE_URL`, `OLLAMA_TIMEOUT`,\n`OPENAI_API_KEY`, `RE_LLM_CONFIG`, `RE_LANGGRAPH_CHECKPOINT_DSN`.\n\n## Development\n\n```bash\nuv run python -m pytest -q # full suite (offline-safe; network tests skip)\nuv run ruff check . # lint\nscripts/ci_mypy.sh # mypy — fails only on NEW errors vs baseline\n```\n\n## Docs\n\nSee [`docs/`](docs/) — architecture, CLI reference, LLM integration,\nbenchmark methodology, and the LangGraph framework-stack notes.\n\n## License\n\nMIT\n",
"bytes": 5875,
"sha": "c2515b26dbc11397f26dcf755f4c777810fa154b9f19a66f5afc3608756362ba",
"repo_slug": "atandra2000/autonomousresearcher",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/okf_atandra2000_autonomousresearcher_openwik_54bb038f/readme"
}