auto-deep-researcher-24x7

Implements a persistent state machine (ResearchLoop in core/loop.py) that coordinates the THINK → EXECUTE → REFLECT lifecycle across multiple experiment cycles. The loop maintains cycle counters, manages graceful shutdowns, and orchestrates transitions between Leader and Worker agents while tracking experiment state across 30+ day runs without human intervention. Uses a cycle-persistence mechanism to resume from checkpoints and prevent context window bloat.

Replaces LLM polling with system-level monitoring (monitor.py) using os.kill checks, nvidia-smi GPU telemetry, and log tailing to track training progress without invoking the LLM. The agent 'sleeps' during GPU training and only wakes to parse structured logs and system metrics, reducing operational costs by over 90% compared to continuous LLM-based monitoring. Integrates with PyTorch training loops via log file parsing and GPU process introspection.

Provides native integration with PyTorch and TensorFlow training loops, allowing the Code Worker to generate and execute training scripts that use these frameworks. The system handles GPU allocation, device management, and training process spawning via subprocess calls. Experiment results (metrics, checkpoints) are automatically logged to structured formats (JSON, CSV) that the monitor can parse.

The Writing Worker agent has access to literature search tools (e.g., arXiv API, Google Scholar) to discover relevant papers and research directions. When generating ideas or analyzing results, the agent can query the literature to find similar work, identify gaps, or validate hypotheses against published results. Search results are summarized and fed back to the Leader for decision-making.

Integrates with Happy Coder (Claude Code's interactive development environment) to allow humans to inspect and modify agent-generated code in real-time. When the Code Worker generates changes, they can be reviewed in Happy Coder before being applied to the training codebase. This provides a safety checkpoint and allows developers to understand agent reasoning.

Organizes experiments into discrete cycles, where each cycle consists of hypothesis generation, code modification, training execution, and result analysis. The ResearchLoop (loop.py) manages cycle transitions and maintains a cycle counter for persistence. This batching approach allows the agent to group related experiments and make strategic decisions at cycle boundaries rather than continuously.

Implements a two-tier agent architecture (AgentDispatcher in agents.py) where a persistent Leader agent maintains high-level research strategy and cycle state, while stateless specialized Workers (Idea, Code, Writing) execute specific tasks with minimal, role-specific toolsets. The Leader coordinates which Worker to invoke and when, ensuring only one Worker is active at a time to minimize parallel LLM costs. Each Worker has a tailored prompt and tool registry optimized for its domain (e.g., Code Worker has PyTorch/TensorFlow tools, Writing Worker has literature search tools).

Enforces a strict memory budget (~5,000 characters total) split across two tiers: Tier 1 (PROJECT_BRIEF.md) is a frozen, immutable project reference containing the original research goal and constraints, while Tier 2 (MEMORY_LOG.md) is a rolling log of milestones, decisions, and experiment results that undergoes aggressive auto-compaction. When Tier 2 exceeds budget, the MemoryManager (memory.py) summarizes old entries into condensed milestone summaries and removes redundant logs, preventing context window bloat over weeks of operation.

Provides real-time GPU telemetry via detect.py, querying nvidia-smi to determine GPU utilization, memory availability, and process status. The system uses this data to decide whether a training run can be safely launched (e.g., waiting if GPU memory is insufficient) and to track which GPUs are available. Integrates with the research loop to prevent resource conflicts and gracefully queue experiments when GPUs are saturated.

Implements keeper.py to prevent cloud IDE environments (e.g., Aliyun PAI-DSW, Kaggle Notebooks) from reclaiming GPU resources due to inactivity timeouts. The keeper sends periodic heartbeat signals (e.g., dummy GPU operations, log writes) to signal that the session is still active, allowing long-running experiments to continue without interruption. This is essential for autonomous agents running on managed cloud platforms with strict idle-time policies.

The Idea Worker agent (specialized prompt in agents.py) generates new research hypotheses and experiment ideas based on previous cycle results. It uses a tool registry that includes literature search capabilities and prior experiment analysis to propose next steps (e.g., 'try lower learning rate', 'test batch normalization'). The Leader agent evaluates these ideas and decides which to pursue, creating a feedback loop that drives iterative research.

The Code Worker agent (specialized prompt in agents.py) modifies training code based on the Leader's directives and Idea Worker's proposals. It has access to Claude Code capabilities (file editing, code execution) and a tool registry including PyTorch/TensorFlow utilities, allowing it to implement changes like hyperparameter tuning, architecture modifications, or data augmentation. The Code Worker reads the current codebase, applies changes, and validates syntax before returning modified code to the Leader.

After each training run completes, the system parses experiment logs and metrics (via monitor.py) and feeds them to the Leader agent for reflection. The Leader analyzes whether the hypothesis was validated, identifies failure modes (e.g., 'loss diverged', 'accuracy plateaued'), and decides the next research direction. This reflection step is critical for the iterative research cycle and informs the next hypothesis generation.

Implements a directive system that allows humans to inject high-level commands into the autonomous loop without stopping it. Directives are natural language instructions (e.g., 'try learning rate 0.001', 'focus on reducing overfitting') that the Leader agent reads and incorporates into its decision-making. Directives are stored in a queue and processed at the start of each cycle, enabling real-time human guidance without interrupting the agent.