opendraft

O que opendraft faz?

Transforma uma linha de tópico em um artigo acadêmico completo com base bibliográfica real.

Portado do OpenDraft (github.com/federicodeponte/opendraft, MIT), que executa isso como um motor hospedado. Aqui o motor é você: dezoito estágios, cada um com um prompt em agents/, mais cinco scripts que fazem as partes que um modelo de linguagem não deve fazer manualmente.

Você é o modelo. Sem chave, sem serviço, sem conta. As únicas chamadas de rede são Crossref, OpenAlex e DataCite, todos endpoints abertos.

O comando único

Escreva um artigo sobre <tópico>

Tudo abaixo segue disso. Não peça ao usuário para executar os estágios; execute-os.

Pergunte quatro coisas primeiro

Antes do estágio 5, se o usuário ainda não disse, pergunte por:

1. Veículo de publicação alvo, ou "nenhum, acadêmico geral".
2. Limite total de palavras.
3. Estilo de citação, um dos seis em references/citation-styles.md.
4. Tipo de documento, um dos tipos em references/paper-types.md.

Estas são quatro perguntas em uma mensagem, não uma entrevista, e são as únicas perguntas que o pipeline faz. Todo o resto ele decide.

Pergunte porque o custo de adivinhar recai no final e não pode ser pago lá. Um veículo com um limite rígido de 150 palavras para o resumo é imposto no estágio 6 ou em nenhum lugar: quando o estágio 17 escreve o resumo, o orçamento de palavras contra o qual cada seção foi rascunhada já está errado. Um estilo de citação escolhido no portão em vez de no estágio 6 significa que todo o rascunho foi escrito contra a densidade de marcadores errada.

Se o usuário se recusar a responder, ou disser "você escolhe", prossiga com os padrões em references/paper-types.md, escreva-os no bloco de formato do veículo no estágio 6, e diga em uma linha quais padrões você usou. Nunca prossiga com uma suposição não declarada que você não mostrou a eles.

Quatro coisas que os scripts possuem, e você não

Um modelo de linguagem é bom em julgamento e ruim em contabilidade. A divisão é deliberada, e cruzá-la é como esta saída quebra. Cada uma é imposta por um script que sai com código diferente de zero, então nenhuma delas é uma questão de opinião no portão.

Nunca escreva um marcador de citação renderizado manualmente. Nem [3], nem (Smith, 2020). Ao rascunhar, você escreve {cite_<doi>} inline no ponto exato da afirmação. scripts/citations.py compile transforma esses marcadores em marcadores renderizados e constrói a bibliografia por consulta a um dicionário. É determinístico, então o mapeamento entre prosa e bibliografia é mecânico, não lembrado.

Nunca invente uma fonte para uma afirmação que você não pode sustentar. Se uma afirmação é real e você não consegue encontrar uma fonte para ela, escreva {cite_MISSING: descrição curta da afirmação} e continue. compile se recusa a renderizá-la, nomeia-a e sai com código diferente de zero, e integrity.py conta como crítica, então não pode sobreviver até um artigo finalizado. Esse é o ponto: não é uma maneira de enviar uma afirmação sem fonte, é uma maneira de ser honesto durante o rascunho, em vez de deletar silenciosamente a afirmação ou anexá-la a um DOI que você inventou. Elimine cada uma antes do portão encontrando uma fonte real com sources.py find, ou cortando a afirmação propositalmente.

Nunca mescle as seções no rascunho manualmente. scripts/assemble.py faz isso, em ordem numérica, e se recusa a emendar qualquer coisa que não seja uma seção numerada no artigo. Uma mesclagem manual que deixa cair uma seção é a falha que ninguém percebe até um leitor notar.

Nunca decida a olho se o artigo é internamente consistente. scripts/integrity.py verifica e sai com código diferente de zero. Execute-o e leia o código de saída.

Configuração

mkdir -p research sections review

Sem chave de API, sem conta, sem etapa de instalação: os scripts são apenas biblioteca padrão do Python. Existe uma variável de ambiente opcional, e é a única que algo aqui lê. Defina OPENDRAFT_CONTACT_EMAIL com seu próprio endereço e sources.py o anexa ao seu User-Agent, o que move as requisições ao Crossref para o pool educado e seus melhores limites de taxa. Deixe-a desdefinida e todos os estágios ainda funcionam; nenhum endereço é embutido, porque um padrão enviado agregaria todos os instaladores em uma identidade e rotearia seus problemas de limite de taxa para a caixa de entrada de um estranho.

O pipeline escreve em caminhos fixos, e cada estágio lê o que os estágios anteriores escreveram. Os caminhos são o contrato entre os estágios:

research/sources.md        research/sources.json     research/summaries.md
research/gaps.md           research/citations.json   research/citation-notes.md
outline.md                 outline_formatted.md
sections/*.md              full_draft.md             final.md
review/thread.md           review/narrator.md        review/skeptic.md
review/verifier.md         review/referee.md         review/voice.md
review/entropy.md          review/polish.md

Quatro regras sobre esses caminhos, e cada uma já foi quebrada antes:

• sections/ contém seções do artigo e nada mais. Cada arquivo nele é emendado no artigo finalizado por scripts/assemble.py. Um relatório de estágio ali estacionado acaba dentro da tese de alguém. Relatórios vão em review/.
• research/sources.json é entrada de máquina, research/sources.md é leitura humana. O estágio 1 escreve ambos. citations.py build lê o JSON.
• Nada escrito à mão vai para research/citations.json. Ele é construído por citations.py build e só muda executando build novamente. Os julgamentos que nenhum script pode fazer, fontes sem DOI, entradas que precisam de revisão, menções que não puderam ser transformadas em um placeholder, vão para research/citation-notes.md, que é prosa e nunca é lido por um script. Um banco de dados editado à mão é como um flag verified é virado para passar pelo portão, que é como um DOI não resolvido alcança a bibliografia parecendo verificado.
• Após o estágio 9.5, full_draft.md é o único rascunho. Nada a jusante lê sections/*.md novamente, então editar um arquivo de seção após a montagem não muda nada e silenciosamente perde a edição.

O pipeline

Execute em ordem. Todo estágio, exceto um, é um arquivo em agents/: leia esse arquivo, faça o que ele diz, escreva a saída que ele nomeia e prossiga. A exceção é o estágio 9.5, que é um script que você executa. Não pule um estágio porque o tópico parece fácil.

#	Estágio	Arquivo do agente ou script	Escreve
1	Encontrar fontes	agents/01-scout.md	research/sources.md, research/sources.json
2	Ler e resumir	agents/02-scribe.md	research/summaries.md
3	Encontrar a lacuna que vale a pena escrever	agents/03-signal.md	research/gaps.md
4	Construir o banco de citações	agents/04-citation-manager.md	research/citations.json, research/citation-notes.md
5	Esboçar o argumento	agents/05-architect.md	outline.md
6	Aplicar formato do veículo e orçamentos de palavras	agents/06-formatter.md	outline_formatted.md
7	Escrever cada seção	agents/07-crafter.md	sections/*.md, anexa a research/gaps.md
8	Verificar consistência entre seções	agents/08-thread.md	correções em sections/*.md, review/thread.md
9	Unificar voz	agents/09-narrator.md	correções em sections/*.md, review/narrator.md
9.5	Montar as seções em um rascunho	scripts/assemble.py	full_draft.md
10	Atacar o argumento	agents/10-skeptic.md	review/skeptic.md, depois correções
11	Verificar afirmações contra fontes	agents/11-verifier.md	review/verifier.md, depois correções
12	Simular revisão por pares	agents/12-referee.md	review/referee.md, depois correções
13	Combinar a voz do autor (opcional)	agents/13-voice.md	correções em full_draft.md, review/voice.md
14	Variar o ritmo da prosa	agents/14-entropy.md	correções em full_draft.md, review/entropy.md
15	Gramática e polimento final	agents/15-polish.md	full_draft.md, review/polish.md
16	Adicionar aparato (opcional)	agents/16-enhancer.md	full_draft.md
17	Escrever o resumo	agents/17-abstract.md	anexado ao início de full_draft.md
18	Escrever o título	agents/18-titlemaker.md	anexado ao início de full_draft.md

O estágio 7 é executado uma vez por seção, não uma vez por artigo. Os estágios 10 a 12 produzem listas de problemas; uma lista de problemas que ninguém aplica não faz nada, então aplique as correções e execute o estágio novamente até que nenhum problema crítico permaneça.

O estágio 12 tem um número, não um sentimento. Pare quando uma execução nova relatar zero problemas críticos e uma média geral de pelo menos 3,0 de 5, com nenhuma dimensão única abaixo de 3, a menos que você registre o motivo em review/referee.md. "Bom o suficiente para enviar" não é uma condição de parada, porque um modelo solicitado a julgar seu próprio rascunho sempre o considerará bom o suficiente na terceira passagem.

O estágio 13 é o único estágio com uma entrada que o pipeline nunca produz. Ele combina o rascunho com a própria prosa do autor, e lê essa prosa de um diretório samples/ no diretório de trabalho: dois ou três artigos anteriores, capítulos ou posts longos, como .md ou .txt. Nada cria esse diretório e nada pergunta por ele, então uma execução que nunca o cria pula o estágio 13 limpidamente, que é o resultado normal, não uma falha. Coloque sua própria escrita lá antes da execução se quiser que o artigo soe como se você o tivesse escrito.

O estágio 9.5 é numerado como um meio passo porque é um script em vez de um prompt de agente, e porque os dezoito estágios de agente mantêm os números que já tinham. Não é opcional. Os estágios 1 a 9 trabalham em sections/*.md; os estágios 10 a 18 trabalham em full_draft.md; nada produz esse arquivo exceto este comando:

python3 scripts/assemble.py sections -o full_draft.md

Ele mescla os arquivos de seção em ordem numérica, se recusa a incluir qualquer arquivo que não seja uma seção numerada e sai com código diferente de zero em caso de lacuna de numeração, número duplicado ou diretório vazio. --check relata o que faria sem escrever.

Ele também pula qualquer arquivo numerado cujo nome contenha report, review, notes, checklist ou log, que é o mecanismo que impede que um relatório de estágio obsoleto acabe dentro de uma tese. Isso é uma heurística de nome de arquivo, então tem uma borda afiada: uma seção real chamada "Revisão da literatura" seria pulada, e você a veria apenas como uma linha "Pulado" no stdout, não como um erro. Nomeie essa seção como trabalhos-relacionados ou literatura. Leia as linhas de salto; uma seção que desaparece aqui desaparece silenciosamente.

Reexecutá-lo após full_draft.md existir precisa de --force, e --force descarta todas as edições que os estágios 10 em diante fizeram no rascunho, então remonte apenas quando você pretende recomeçar das seções.

Escala

Combine o pipeline com o que foi solicitado. Os estágios são os mesmos; a profundidade não é.

• Uma peça curta, 1.500 a 3.000 palavras. Estágios 1 a 7, depois 9.5, 10, 11, 15. Dez a quinze fontes.
• Um artigo completo, o padrão. Todos os dezoito, mais 9.5. Vinte e cinco a cinquenta fontes, ou cinquenta ou mais quando o artigo é uma revisão de literatura, cujo próprio piso governa sempre que é maior (references/paper-types.md).
• Um capítulo de tese ou revisão longa. Todos os dezoito, mais 9.5, fontes na casa das dezenas ou mais, e estágio 7 uma vez por subseção em vez de por seção.

O estágio 9.5 está em cada uma dessas listas. Não há escala na qual um artigo se monte sozinho.

Os dois arquivos de referência

• references/paper-types.md contém o esqueleto da seção, orçamento de palavras e contagem de fontes para cada tipo de documento. Leia-o no estágio 5.
• references/citation-styles.md mostra a saída compilada real de todos os seis estilos, marcador no texto e entrada de referência, para que você possa escolher um para o veículo e saber como será. Leia-o no estágio 6, e novamente antes do portão se uma citação for renderizada de uma forma que você não esperava. Ele também afirma o que o compilador não carrega: sem volume, número ou páginas, sem abreviatura de periódico. Se um supervisor exigir esses, este é o lugar que diz isso honestamente, em vez do lugar onde você descobre depois.

Nenhum dos arquivos é leitura opcional vestida de referência. Um estilo escolhido sem ler o segundo é um estilo escolhido de memória, e o compilador não implementa sua memória da APA.

Os scripts

python3 scripts/sources.py find "<consulta>" --n 15        # Crossref mais OpenAlex
python3 scripts/sources.py find "<consulta>" --json        # legível por máquina
python3 scripts/sources.py verify <doi> <doi> ...       # Crossref mais DataCite

python3 scripts/citations.py build research/sources.json -o research/citations.json
python3 scripts/citations.py verify -d research/citations.json
python3 scripts/citations.py compile full_draft.md -d research/citations.json --style apa -o final.md
python3 scripts/citations.py bibtex -d research/citations.json -o refs.bib

python3 scripts/assemble.py sections -o full_draft.md
python3 scripts/assemble.py sections -o full_draft.md --check

python3 scripts/integrity.py final.md -d research/citations.json --target 8000
python3 scripts/integrity.py final.md -c research/summaries.md   # verificação de número consultiva
python3 scripts/export.py final.md --format docx -o final.docx

Todos eles saem com código diferente de zero em caso de falha. Esse código de saída é o sinal; leia-o em vez de examinar a saída.

sources.py find sai com 1 quando nenhuma API pôde ser alcançada, o que é diferente de alcançá-las e não obter resultados. agents/01-scout.md é a autoridade sobre como ler esse código de saída e sobre o piso de fontes abaixo do qual o estágio 1 para em vez de prosseguir; leia-o lá, em vez de confiar em um resultado vazio.

citations.py build recebe o array JSON que o estágio 1 escreveu em research/sources.json, não o markdown em research/sources.md. Alimentá-lo com o arquivo markdown é um erro, e ele dirá isso.

Pesquise também duas ou três subconsultas mais restritas se a primeira passagem for fina. Um artigo com cinco fontes parece um com cinco fontes.

Verificação, e o que ela prova e não prova

citations.py verify coloca cada DOI em um de quatro estados, e unknown nunca é silenciosamente transformado em absent:

• resolved. Crossref ou DataCite retornaram o registro. Cite-o.
• absent. Ambos retornaram 404. Descarte-o. Não o repare, não adivinhe um DOI de substituição, vá para trás