autoresearch — Estrutura de Pesquisa Autônoma de LLM por IA

---

Visão Geral

autoresearch é uma estrutura experimental de Andrej Karpathy que automatiza o processo de iteração de pesquisa em IA/ML. A ideia central é elegantemente simples: dar a um agente de IA (como Claude ou Codex) um código de treinamento de LLM real e funcional, e deixá-lo propor autonomamente alterações, executar experimentos de treinamento de 5 minutos, avaliar resultados e iterar — tudo sem intervenção humana.

Pense nisso como um laboratório de pesquisa de IA mínimo e autônomo que roda durante a noite em uma única GPU, produzindo um registro de ~100 experimentos e (esperançosamente) um modelo de linguagem progressivamente melhor pela manhã.

---

Contexto e Motivação

Karpathy abre o README com uma visão sarcástica do futuro — um mundo onde a pesquisa de IA não é mais feita por humanos, mas por "enxames autônomos de agentes de IA rodando em megaestruturas de clusters de computação". O repositório, ele escreve, é "a história de como tudo começou".

A motivação prática é mais fundamentada: a iteração de pesquisa é lenta porque os humanos precisam comer, dormir e participar de reuniões. Este projeto substitui o humano no loop por um agente de IA que pode executar experimentos 24 horas por dia, 7 dias por semana, tornando a pesquisa de ML dramaticamente mais rápida e automatizada.

---

Como Funciona

O fluxo de trabalho é um loop apertado de editar → treinar → avaliar → manter/descartar:

1. O agente lê program.md — um arquivo Markdown contendo instruções de pesquisa e contexto, escrito e mantido pelo pesquisador humano.
2. O agente modifica train.py — o único arquivo Python contendo a arquitetura do modelo GPT, o otimizador (Muon + AdamW) e o loop de treinamento. O agente pode mudar qualquer coisa: arquitetura, hiperparâmetros, configurações do otimizador, tamanho do lote, etc.
3. O treinamento roda por exatamente 5 minutos (tempo de relógio, excluindo inicialização/compilação).
4. A métrica val_bpb (bits de validação por byte) é calculada — quanto menor, melhor. É independente do tamanho do vocabulário, portanto, as mudanças arquitetônicas podem ser comparadas de forma justa.
5. O agente decide se mantém a alteração ou a descarta, e então repete.

Isso resulta em aproximadamente 12 experimentos/hora e ~100 experimentos durante a noite.

---

Estrutura do Repositório

autoresearch/
├── prepare.py       # Fixo: preparação de dados única, treinamento de tokenizador BPE, dataloader, utilitários de avaliação
├── train.py         # Editável pelo agente: modelo GPT, otimizador, loop de treinamento
├── program.md       # Editável pelo humano: instruções do agente e contexto de pesquisa
├── analysis.ipynb   # Notebook para análise de resultados de experimentos
├── pyproject.toml   # Dependências (gerenciadas via uv)
└── progress.png     # Imagem teaser mostrando o progresso do treinamento

Arquivos Chave Explicados

Arquivo	Proprietário	Propósito
prepare.py	Humano (fixo)	Baixa fragmentos de dados, treina tokenizador BPE, fornece dataloader e utilitários de avaliação
train.py	Agente de IA	Implementação completa do GPT + loop de treinamento — o sandbox do agente
program.md	Humano (iterável)	"Habilidade" de pesquisa / instruções para o agente

---

Filosofia de Design

1. Arquivo Único para Modificar

O agente só mexe em train.py. Isso mantém o escopo gerenciável e as diferenças fáceis de revisar. Também restringe o espaço de ação do agente a mudanças significativas de ML em vez de mudanças de infraestrutura/ferramentas.

2. Orçamento de Tempo Fixo

Cada experimento roda por exatamente 5 minutos de tempo de treinamento de relógio (excluindo inicialização). Isso garante:

• Todos os experimentos são diretamente comparáveis independentemente das mudanças arquitetônicas (tamanho do modelo, tamanho do lote, etc.)
• O agente encontra a melhor configuração de modelo para seu hardware específico
• Taxa de transferência previsível: ~12 experimentos/hora

A troca: os resultados não são portáteis entre diferentes plataformas de computação (uma execução em H100 não pode ser comparada a uma execução em A100).

3. Autocontido

Sem treinamento distribuído, sem arquivos de configuração complexos, sem infraestrutura de pesquisa externa. Apenas PyTorch + um punhado de pequenos pacotes, uma GPU, um arquivo, uma métrica. Isso torna o projeto fácil de entender, copiar e construir.

4. program.md como a Interface Humana

Em vez de codificar um agente de pesquisa do zero, Karpathy usa program.md como uma "habilidade" leve — um arquivo Markdown que fornece ao agente de IA contexto, objetivos e restrições. O humano itera em program.md ao longo do tempo para melhorar o "código da organização de pesquisa".

---

Detalhes Técnicos

Modelo e Treinamento

• Baseado em uma versão simplificada de GPU única do nanochat
• Usa o otimizador Muon + AdamW por padrão (embora o agente possa mudar isso)
• Treina um modelo estilo GPT do zero em fragmentos de dados de texto baixados
• Tokenizador BPE treinado nos próprios dados via prepare.py
• Métrica de avaliação: val_bpb (bits de validação por byte)

Requisitos

• GPU: GPU NVIDIA única (testado em H100)
• Python: 3.10+
• Gerenciador de pacotes: uv

Início Rápido

# 1. Instale o uv (se ainda não estiver instalado)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. Instale as dependências
uv sync

# 3. Preparação de dados única (~2 min)
uv run prepare.py

# 4. Execute um único experimento de treinamento (~5 min)
uv run train.py

Executando o Agente

Inicie Claude, Codex ou qualquer agente de codificação capaz no diretório do repositório (com permissões de escrita de arquivos) e, em seguida, solicite:

Dê uma olhada em program.md e vamos iniciar um novo experimento! Vamos fazer a configuração primeiro.

O agente lerá program.md, proporá uma alteração em train.py, executará o treinamento, avaliará o resultado e iterará.

---

Significado e Impacto

autoresearch é uma prova de conceito para pesquisa automatizada de aprendizado de máquina em microescala. Embora existam sistemas AutoML em larga escala, este projeto é notável por:

• Simplicidade: Todo o código significativo tem ~3 arquivos
• Transparência: Cada decisão do agente é registrada e pode ser revisada
• Acessibilidade: Roda em uma única GPU de consumidor/pesquisa
• Visão: Demonstra a viabilidade de agentes de IA conduzirem pesquisa genuína de ML autonomamente

Ele também serve como um modelo para "programar sua organização de pesquisa de IA via Markdown" — um paradigma que pode se tornar padrão à medida que os agentes de codificação de IA se tornam mais capazes.

---

Forks Notáveis

• miolini/autoresearch-macos — Suporte macOS/MPS

---

Resumo

Propriedade	Valor
Tipo	Estrutura de Agente de Pesquisa Autônoma de IA
Uso Primário	Experimentação de treinamento de LLM automatizada durante a noite
Interface do Agente	program.md (instruções Markdown)
Espaço de Ação do Agente	train.py (modelo GPT + loop de treinamento)
Duração do Experimento	5 minutos (fixo)
Taxa de Transferência	~12 experimentos/hora, ~100 durante a noite
Métrica	val_bpb (bits de validação por byte)
Hardware	GPU NVIDIA única (H100 testado)
Licença	MIT