synesis-coder: Codificação Qualitativa com IA

Como gerar anotações, ontologias e processar corpora inteiros com o CLI

1 synesis-coder: Codificação Qualitativa com IA

O synesis-coder automatiza a codificação qualitativa usando Claude como motor de inferência. A ferramenta lê o template do seu projeto (.synt) e gera blocos Synesis válidos — ITEM, SOURCE, ONTOLOGY — seguindo rigorosamente os campos, relações, valores permitidos e instruções metodológicas (GUIDELINES) do template.

Você deve usar este guia se:

  • Quer codificar trechos de texto selecionados em um arquivo .syn
  • Precisa processar um corpus de abstracts (.bib) em lote
  • Quer codificar um documento longo (entrevista, relatório) com chunking automático
  • Precisa gerar definições ontológicas (.syno) a partir do corpus já anotado
  • Quer integrar a codificação ao fluxo de trabalho no VS Code (Synesis Explorer)
Nada é hardcoded

synesis-coder não contém nenhum nome de campo, relação ou valor fixo no código. Tudo é derivado dinamicamente de result.template.field_specs via synesis.load(). Se você mudar o template, a IA segue as novas regras — sem modificar a ferramenta.

2 Instalação

2.1 Requisitos

  • Python 3.10+
  • synesis >= 0.6.0
  • Chave de API da Anthropic (ANTHROPIC_API_KEY)

2.2 Instalar o pacote

pip install synesis-coder

Verificar:

synesis-coder --version
# synesis-coder, version 0.7.7

2.3 Configurar a chave de API

Crie um arquivo .env na raiz do seu projeto com a chave:

ANTHROPIC_API_KEY=sk-ant-...

O .env é carregado automaticamente. Nunca inclua este arquivo no controle de versão.

Modelo alternativo

O modelo padrão é claude-opus-4-6. Para usar um modelo mais rápido (e mais barato), defina SYNESIS_CODER_MODEL=claude-sonnet-4-6 no .env ou passe --model claude-sonnet-4-6 na linha de comando.

3 Os modos de operação

synesis-coder organiza seus comandos em três grupos, cobrindo o ciclo completo da pesquisa — da extração inicial à revisão e consolidação:

3.1 Ingestão e extração

Modos de ingestão
Modo Entrada Saída Uso típico
item Texto + bibref Bloco ITEM Codificar um trecho selecionado
abstract Corpus .bib Blocos SOURCE + ITEM Processar abstracts em lote
document Documento .txt/.md Blocos SOURCE + ITEM Codificar entrevista ou relatório longo

3.2 Estruturação e LLM

Modos de estruturação
Modo Entrada Saída Uso típico
ontology Corpus anotado Arquivo .syno Gerar definições ontológicas
suggest Trecho de texto Lista de códigos Sugerir códigos relevantes para um excerto
finetune Dataset Alpaca JSONL enriquecido Preparar dados para fine-tuning de modelos

3.3 Pipeline ACT (revisão e consolidação)

Pipeline ACT
Fase Modo Entrada Saída LLM?
2 critique .syn .synr com blocos # REVISION Sim
3 normalize .synr .synr com códigos canonizados Sim
4 incorporate .synr .syn final validado Não
R refine .syn .syn refinado Sim (opt-in)

O pipeline ACT é descrito em detalhe em Seção 8.

4 Modo item: codificar um trecho de texto

O modo mais simples. Recebe um texto e uma referência bibliográfica, e retorna um bloco ITEM válido codificado de acordo com o template do projeto.

4.1 Uso básico

synesis-coder item \
  --project social_acceptance.synp \
  --bibref ashworth2019 \
  --text "Community trust and environmental concern are the most important factors determining willingness to participate in renewable energy projects."

A saída é um bloco ITEM compilável, pronto para inserir em um arquivo .syn:

ITEM @ashworth2019
    text: Community trust and environmental concern are the most
          important factors determining willingness to participate
          in renewable energy projects.

    note: Reveals dual-factor mechanism where trust and environmental
          concern independently drive participation willingness
    chain: Community_Trust -> INFLUENCES -> Participation

    note: Environmental concern acts as value-based enabler of
          engagement with renewable energy
    chain: Environmental_Concern -> ENABLES -> Participation
END ITEM

4.2 Redirecionar para arquivo

O formato plain (padrão) emite apenas o bloco Synesis, ideal para piping:

synesis-coder item \
  --project social_acceptance.synp \
  --bibref ashworth2019 \
  --text "Local ownership models significantly reduce opposition." \
  >> anotacoes/ashworth2019.syn

4.3 Saída verbose

O formato verbose inclui cabeçalho com status de validação:

synesis-coder item \
  --project social_acceptance.synp \
  --bibref ashworth2019 \
  --text "Local ownership models significantly reduce opposition." \
  --format verbose
# synesis-coder item
# bibref: @ashworth2019
# model: claude-opus-4-6
# validation: OK
# timestamp: 2026-03-23T14:32:11

ITEM @ashworth2019
    text: Local ownership models significantly reduce opposition.
    ...
END ITEM

4.4 Opções completas

Opções do modo item
Opção Obrigatória Descrição
--project sim Caminho para o arquivo .synp
--bibref sim Referência bibliográfica (sem @)
--text sim Texto a ser codificado
--format não plain (padrão) ou verbose
--model não ID do modelo LLM

5 Modo abstract: processar corpus bibliográfico

Processa um arquivo .bib completo, gerando anotações SOURCE + ITEM para cada referência que contenha abstract.

5.1 Uso

synesis-coder abstract \
  --project social_acceptance.synp \
  --input corpus/references.bib \
  --output-dir anotacoes/ \
  --concurrent 5
--output-dir, não --output

Esta flag sempre foi um diretório de saída, mas o nome anterior (--output) induzia ao erro de passar um nome de arquivo — o que criava uma pasta com esse nome e provocava um PermissionError confuso na execução seguinte. A flag foi renomeada para --output-dir; --output continua funcionando como alias retrocompatível.

Para cada referência no .bib que tenha abstract, o modo abstract:

  1. Cria um bloco SOURCE @bibref com os metadados bibliográficos
  2. Analisa o abstract e gera blocos ITEM @bibref codificando os achados relevantes
  3. Valida cada bloco via synesis.load() antes de gravar

5.2 Processamento em lote e batches

O modo abstract processa referências concorrentemente (padrão: 5 chamadas simultâneas) e organiza o trabalho em batches para evitar acúmulo de contexto:

synesis-coder abstract \
  --project social_acceptance.synp \
  --input corpus/references.bib \
  --output-dir anotacoes/ \
  --concurrent 5 \
  --batch-size 25

Entre cada batch, o projeto é recarregado via synesis.load() para incorporar as anotações já geradas — o code_index e topic_index ficam progressivamente mais ricos ao longo do processamento.

5.3 Um arquivo por referência

Por padrão, todas as anotações vão para um único arquivo .syn. Use --per-reference para gerar um arquivo .syn por referência:

synesis-coder abstract \
  --project social_acceptance.synp \
  --input corpus/references.bib \
  --output-dir anotacoes/ \
  --per-reference

Resultado: anotacoes/ashworth2019.syn, anotacoes/aly2019.syn, etc.

5.4 Opções completas

Opções do modo abstract
Opção Obrigatória Descrição
--project sim Caminho para o arquivo .synp
--input sim Arquivo .bib com abstracts
--output-dir sim Diretório de saída (alias: --output)
--concurrent não Chamadas LLM simultâneas (padrão: 5)
--batch-size não Referências por batch (padrão: 25)
--per-reference não Um arquivo .syn por referência
--format não plain (padrão) ou verbose
--model não ID do modelo LLM
--debug não Log DEBUG com resposta bruta do LLM

6 Modo document: codificar documentos longos

Processa um documento longo (entrevista transcrita, relatório, capítulo) com chunking automático — divide o texto em segmentos com overlap para garantir cobertura completa.

6.1 Uso

synesis-coder document \
  --project nave.synp \
  --bibref entrevista_01 \
  --input transcricoes/entrevista_01.txt \
  --output anotacoes/entrevista_01.syn

6.2 Controle de chunking

O chunking divide o documento em segmentos de tamanho configurável. O overlap garante que passagens na fronteira entre chunks não sejam perdidas:

synesis-coder document \
  --project nave.synp \
  --bibref entrevista_01 \
  --input transcricoes/entrevista_01.txt \
  --output anotacoes/entrevista_01.syn \
  --chunk-size 12000 \
  --overlap 2400
  • --chunk-size: tamanho máximo de cada segmento em caracteres (padrão: 12.000)
  • --overlap: sobreposição entre segmentos consecutivos em caracteres (padrão: 2.400)
Dimensionando o chunk

O tamanho do chunk ideal depende da complexidade do template. Templates com muitos campos CHAIN e GUIDELINES extensas exigem mais tokens de contexto — nesse caso, reduza o --chunk-size para 8.000–10.000 caracteres. Para templates simples, 12.000 funciona bem.

6.3 Opções completas

Opções do modo document
Opção Obrigatória Descrição
--project sim Caminho para o arquivo .synp
--bibref sim Referência bibliográfica para o documento
--input sim Documento .txt ou .md
--output sim Arquivo .syn de saída
--chunk-size não Tamanho do chunk em caracteres (padrão: 12.000)
--overlap não Overlap entre chunks (padrão: 2.400)
--concurrent não Chunks simultâneos (padrão: 3)
--format não plain (padrão) ou verbose
--model não ID do modelo LLM

7 Modo ontology: gerar definições ontológicas

O modo mais sofisticado. Analisa o corpus já anotado, coleta evidência empírica para cada código conceitual (frequência, fontes, relações, co-ocorrências, exemplos), e gera entradas ONTOLOGY fundamentadas nos dados observados — não em conhecimento genérico do LLM.

7.1 Uso básico

synesis-coder ontology \
  --project social_acceptance.synp \
  --output ontologia.syno

7.2 O que é o semantic context?

Para cada código pendente, o synesis-coder monta um contexto semântico derivado do corpus:

  • Frequência: quantas vezes o código aparece em blocos ITEM
  • Fontes: quantos SOURCEs distintos mencionam o código
  • Relações: triples do grafo de CHAIN envolvendo o código (até 15)
  • Co-ocorrências: outros códigos que aparecem nos mesmos ITEMs (até 20)
  • Exemplos: excertos concretos de campos QUOTATION/NOTE (até 3)

Esse contexto é injetado no prompt do LLM, produzindo definições ontológicas que refletem o uso real no corpus, não definições enciclopédicas genéricas.

7.3 Exemplo real: código Cost

O código Cost aparece em 96 itens de 66 fontes diferentes no projeto Social_Acceptance. O semantic context injetado no prompt inclui:

  • Relações: Cost -> CONSTRAINS -> Deployment, Cost -> INFLUENCES -> Acceptance, Policy -> ENABLES -> Cost_Reduction
  • Co-ocorrências: Deployment, Acceptance, Policy, Technology
  • Exemplos: “High initial investment costs remain the primary barrier to solar deployment in developing countries”

A entrada ONTOLOGY gerada:

ONTOLOGY Cost
    topic: Economics
    aspect: 11
    dimension: 2
    confidence: HIGH

    reasoning: Aspect 11: Core economic factor representing financial
               expenditure. Mainly constrains deployment/technology
               development while enabling market penetration when
               reduced. Co-occurs with Deployment and Acceptance,
               indicating market-consumer relevance. Dimension 2:
               Directly affects investors, consumers, and market
               competitiveness. High frequency (96) across broad
               sources (66) confirms central role.

    description: Economic factor representing financial expenditure
                 associated with energy technologies and systems.
                 Acts as primary barrier constraining technology
                 development, site selection, and deployment when
                 high, while enabling market penetration, technology
                 transition, and sustainable solutions when reduced.

    rgt_element_a: Low_Cost
    rgt_element_b: High_Cost
    theoretical_significance: 0
END ONTOLOGY

Observe como a classificação aspect: 11 (Economic), dimension: 2 (Market), confidence: HIGH — todas derivadas das evidências empíricas no corpus, não de associações genéricas.

7.4 Modo incremental (--update)

Quando a ontologia já contém definições e você quer gerar apenas os códigos novos (adicionados após novas rodadas de codificação):

synesis-coder ontology \
  --project social_acceptance.synp \
  --output ontologia.syno \
  --update

Com --update, o synesis-coder:

  1. Carrega a ontologia existente via synesis.load(load_ontology=True)
  2. Compara os códigos usados no corpus contra os já definidos em ontology_index
  3. Gera entradas apenas para códigos pendentes

7.5 Backup automático

Quando você executa sem --update e o arquivo .syno de destino já existe, o synesis-coder cria automaticamente um backup antes de sobrescrever:

ontologia.syno       →  ontologia_bkp.syno  (backup)
ontologia.syno       ←  novo conteúdo gerado

Isso protege ontologias curadas manualmente contra sobrescrita acidental.

7.6 Blocos rejeitados não contaminam o .syno

Se um bloco ONTOLOGY não passa na validação após todas as tentativas de correção, ele não é gravado no arquivo final. Blocos rejeitados vão para um arquivo separado:

ontologia.syno              ←  apenas blocos válidos
ontologia.syno.rejeitados   ←  blocos que falharam (sobrescrito a cada execução)
Por que isso importa

Antes, todos os resultados eram concatenados no .syno final — inclusive os que continham o comentário # ERRO: validação falhou seguido de texto malformado. Um único código mal-extraído corrompia o arquivo inteiro para qualquer compile ou load posterior. Agora o .syno gerado é sempre compilável, e o resumo da execução aponta o arquivo de rejeitados quando há falhas.

7.7 Geração estruturada (JSON Schema)

Quando o modelo suporta structured outputs, o synesis-coder não pede ao LLM que escreva o bloco inteiro. Em vez disso:

  1. Deriva um JSON Schema dos campos ONTOLOGY FIELDS do template
  2. Pede ao LLM apenas os valores dos campos
  3. Monta o bloco ONTOLOGY ... END ONTOLOGY deterministicamente, em código

O LLM nunca digita as palavras ONTOLOGY, END ONTOLOGY ou os nomes de campo — o que elimina por construção uma classe inteira de alucinações de sintaxe. O schema usa additionalProperties: false, então qualquer chave inventada é descartada antes da montagem. Quando há tópicos já definidos no projeto, o campo TOPIC vira um enum restrito a eles.

O caminho estruturado está disponível nos backends anthropic (via output_config) e openai (via response_format). Se o SDK instalado não suportar, a ferramenta cai automaticamente no caminho de texto livre — o comportamento anterior, sem quebrar nada. A validação com synesis.load() roda igual nos dois caminhos.

7.8 Requisito de template

O template do projeto deve definir pelo menos um campo com SCOPE ONTOLOGY. Projetos sem escopo de ontologia (como thompson_bible) recebem um erro claro:

Erro: O template do projeto 'thompson_bible' não define campos ONTOLOGY.

7.9 Opções completas

Opções do modo ontology
Opção Obrigatória Descrição
--project sim Caminho para o arquivo .synp
--output sim Arquivo .syno de saída
--update não Gera apenas códigos ainda sem definição
--concurrent não Chamadas LLM simultâneas (padrão: 5)
--format não plain (padrão) ou verbose
--model não ID do modelo LLM

8 O pipeline ACT: revisão e consolidação

A extração inicial (item, abstract, document) produz anotações que precisam ser revisadas. O pipeline ACT organiza essa revisão em fases explícitas, cada uma com um artefato próprio — nada é sobrescrito silenciosamente.

O formato intermediário é o .synr (Synesis revision): um .syn acrescido de blocos # REVISION com sugestões de correção. É um tipo de arquivo reconhecido pelo compilador e pela extensão do VS Code.

.syn  ──critique──▶  .synr  ──normalize──▶  .synr  ──incorporate──▶  .syn
       (fase 2)              (fase 3)                (fase 4)

8.1 Fase 2 — critique: revisar as anotações

Um segundo modelo relê cada ITEM contra o texto-fonte e o template, atribuindo um escore de suspeita. ITEMs acima do limiar recebem um bloco # REVISION com a correção sugerida.

synesis-coder critique anotacoes/entrevista_01.syn \
  --project nave.synp \
  --threshold 0.20

Saída: anotacoes/entrevista_01.synr.

Opções do modo critique
Opção Descrição
--project .synp do projeto (autodetectado a partir da pasta do .syn)
--output Caminho do .synr (padrão: mesmo nome, extensão .synr)
--threshold Escore mínimo para emitir # REVISION (padrão: 0.20)
--concurrent Chamadas simultâneas (padrão: 3)
--model Modelo crítico (SYNESIS_CODER_CRITIQUE_MODEL)
--debug Log com resposta bruta por ITEM
Modelo crítico separado

A crítica pode usar um modelo diferente do que gerou as anotações — configurável via SYNESIS_CODER_CRITIQUE_MODEL. Um segundo modelo, com contexto próprio, tende a encontrar problemas que o gerador original não veria por reproduzir os mesmos vieses.

8.2 Fase 3 — normalize: canonizar códigos

Corpora processados em lotes distintos acumulam variantes do mesmo conceito — Custo, custo, Custo_Alto. Esta fase analisa os códigos de todos os .synr juntos e propõe a forma canônica.

synesis-coder normalize anotacoes/*.synr \
  --project social_acceptance.synp \
  --confidence 0.65 \
  --inventory inventario_codigos.txt
Opções do modo normalize
Opção Descrição
--output-dir Diretório dos .synr normalizados (padrão: o de entrada)
--confidence Confiança mínima para aceitar a canonização (padrão: 0.65)
--inventory Salva o inventário de códigos em um arquivo TXT
--model Modelo de normalização (SYNESIS_CODER_NORMALIZATION_MODEL)

8.3 Fase 4 — incorporate: aplicar as revisões

Aplica os blocos # REVISION e emite o .syn final, validado. Esta fase não usa LLM — é determinística e reproduzível.

synesis-coder incorporate anotacoes/entrevista_01.synr \
  --output anotacoes/entrevista_01_final.syn
Opções do modo incorporate
Opção Descrição
--output Caminho do .syn final (padrão: mesmo nome, extensão .syn)
--overwrite Sobrescreve sem confirmação
--backup Cria cópia .bak antes de sobrescrever

8.4 Fase R — refine: reextrair os ITEMs problemáticos

Alternativa opcional às fases 3–4. Em vez de aplicar correções pontuais, reextrai do zero os ITEMs marcados como suspeitos, agora com o feedback da crítica no prompt. Itera até convergir.

synesis-coder refine anotacoes/entrevista_01.syn \
  --project nave.synp \
  --max-iter 2 \
  --threshold 0.20
Opções do modo refine
Opção Descrição
--max-iter Iterações máximas por ITEM (padrão: 2)
--threshold Escore abaixo do qual o ITEM é considerado convergido (padrão: 0.20)
--critique-model Modelo crítico
--refine-model Modelo gerador da reextração
--thinking-budget Tokens de extended thinking na reextração (0 = desligado)
--overwrite / --backup Controle de sobrescrita

Saída padrão: <nome>_refined.syn.

O arquivo de entrada nunca é sobrescrito por acidente

Se --output apontar para o próprio arquivo de entrada, o comando falha com mensagem explícita, a menos que você passe --overwrite --backup deliberadamente. Uma reextração que apagasse a anotação original seria irreversível.

8.5 Fluxo completo

# 1. Extrair
synesis-coder abstract --project estudo.synp \
  --input corpus.bib --output-dir anotacoes/

# 2. Criticar
synesis-coder critique anotacoes/annotations.syn --project estudo.synp

# 3. Canonizar códigos
synesis-coder normalize anotacoes/*.synr --project estudo.synp

# 4. Consolidar
synesis-coder incorporate anotacoes/annotations.synr \
  --output anotacoes/final.syn

# 5. Compilar
synesis compile estudo.synp --json resultado.json

9 Outros modos

9.1 suggest: sugerir códigos para um trecho

Retorna os códigos do projeto mais relevantes para um excerto, sem gerar um bloco ITEM completo. Útil para explorar a ontologia durante a codificação manual.

synesis-coder suggest \
  --project social_acceptance.synp \
  --text "Local ownership models significantly reduce opposition."

9.2 finetune: enriquecer dataset para fine-tuning

Gera ou enriquece um dataset Alpaca (JSONL) a partir do projeto compilado, para treinar um modelo próprio.

synesis-coder finetune \
  --project social_acceptance.synp \
  --output dataset_enriquecido.jsonl \
  --enrich vary --enrich didactic
Opções de --enrich (repetível)
Tipo de enriquecimento Efeito
vary (padrão) Variações de formulação do mesmo exemplo
didactic Versões com explicação do raciocínio
counterfactual Contraexemplos para reforçar fronteiras conceituais

A entrada pode ser um .synp (o dataset é gerado pelo compilador) ou um JSONL pré-existente via --input.

10 Integração com VS Code

O modo item está integrado à extensão Synesis Explorer (v0.5.25+), permitindo codificar texto diretamente no editor sem abrir o terminal.

10.1 Como usar

  1. Abra um arquivo .syn no VS Code com a extensão Synesis Explorer instalada
  2. Selecione o trecho de texto que deseja codificar
  3. Clique com o botão direito → Synesis: Code Selection
    • Ou use o atalho Ctrl+Shift+I / Cmd+Shift+I

A extensão:

  • Detecta o bibref automaticamente a partir do bloco SOURCE ou ITEM sob o cursor
  • Chama synesis-coder item como subprocesso
  • Substitui a seleção pelo bloco ITEM gerado

10.2 Fluxo de trabalho típico

O cenário mais comum é o pesquisador que cola trechos de sua revisão de literatura diretamente no arquivo .syn:

SOURCE @ashworth2019
    description: Comparative study of public attitudes toward CCS and
                 low-carbon energy technologies in Australia and China.
    epistemic_model: Social acceptance of energy technologies
    method: Online survey (Australia n=2383, China n=1266)
END SOURCE

However, male respondents, those who perceived themselves to
have higher knowledge of CCS, and those who valued economic
outcomes over environmental protection were more likely to
support CCS - as long as the risks were not perceived to
outweigh the benefits.

O pesquisador seleciona o texto colado (a passagem abaixo do END SOURCE), executa Synesis: Code Selection, e o texto é substituído por:

SOURCE @ashworth2019
    description: Comparative study of public attitudes toward CCS and
                 low-carbon energy technologies in Australia and China.
    epistemic_model: Social acceptance of energy technologies
    method: Online survey (Australia n=2383, China n=1266)
END SOURCE

ITEM @ashworth2019
    text: However, male respondents, those who perceived themselves to
          have higher knowledge of CCS, and those who valued economic
          outcomes over environmental protection were more likely to
          support CCS - as long as the risks were not perceived to
          outweigh the benefits.

    note: *complex* Four-factor convergence reveals multi-domain
          determinants requiring integrated communication strategies
    chain: Gender -> INFLUENCES -> CCS_Support

    note: Self-assessed knowledge increases support, revealing
          information deficit mechanism
    chain: Knowledge -> INFLUENCES -> CCS_Support

    note: Economic prioritization over environmental values predicts
          support, indicating value-based acceptance mechanism
    chain: Economic_Value -> INFLUENCES -> CCS_Support

    note: Risk-benefit assessment constrains support, revealing
          conditional acceptance mechanism
    chain: Risk_Perception -> CONSTRAINS -> CCS_Support
END ITEM

O bibref @ashworth2019 foi detectado automaticamente do bloco SOURCE acima. O pesquisador não precisou digitar nada — apenas selecionar e executar o comando.

10.3 Configuração do caminho do executável

Se o synesis-coder não está no PATH do sistema, configure o caminho na extensão:

VS Code Settings → synesisExplorer.coder.path:

{
  "synesisExplorer.coder.path": "C:/Python312/Scripts/synesis-coder.exe"
}

10.4 Cancelamento

A operação pode ser cancelada a qualquer momento clicando Cancel na notificação de progresso. O subprocesso é terminado imediatamente.

11 Como funciona internamente

O synesis-coder opera em um pipeline de cinco estágios. Entender esse pipeline ajuda a diagnosticar problemas e ajustar o fluxo de trabalho.

                    ┌─────────────────────────────┐
                    │  synesis-coder item/ontology │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │   1. project_loader          │
                    │      synesis.load()          │
                    │      → ctx (template, fields,│
                    │        code_index, relations) │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │   2. prompt_builder          │
                    │      system (cacheável):     │
                    │        regras + template     │
                    │        + indexes + GUIDELINES│
                    │      user (dinâmico):        │
                    │        bibref + texto        │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │   3. llm_client              │
                    │      Claude API (Anthropic)  │
                    │      rate limiting RPM/TPM   │
                    │      prompt caching ativo    │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │   4. validator               │
                    │      synesis.load() valida   │
                    │      ↻ até 3 tentativas      │
                    │      temperatura crescente   │
                    │      0.0 → 0.2 → 0.5        │
                    └─────────────┬───────────────┘
                                  │
                    ┌─────────────▼───────────────┐
                    │   5. stdout                  │
                    │      Bloco(s) Synesis válido │
                    └─────────────────────────────┘

11.1 1. project_loader

load_project() invoca synesis.load() — o compilador Synesis — para extrair do projeto:

  • template fields separados por escopo (SOURCE, ITEM, ONTOLOGY)
  • GUIDELINES por campo — instruções metodológicas do pesquisador
  • code_index — conceitos existentes (de campos CODE e CHAIN)
  • topic_index — tópicos existentes (de campos TOPIC)
  • ontology_index — entradas ontológicas já definidas
  • CHAIN relations — relações causais permitidas no projeto
  • project description — descrição do projeto (bloco DESCRIPTION)

Tudo é extraído dinamicamente do compilador. Se o pesquisador muda o template, o synesis-coder se adapta automaticamente.

11.2 2. prompt_builder

Constrói prompts em duas camadas:

  • System prompt (cacheável): regras absolutas do formato Synesis, descrição do projeto, instruções por campo (GUIDELINES > description > genérica por tipo), conceitos e tópicos existentes. Marcado com cache_control: ephemeral na API Anthropic — o primeiro item de um batch paga o custo total, os demais reutilizam o cache.
  • User prompt (dinâmico): bibref + texto (modo item) ou código + semantic_ctx (modo ontology).

A hierarquia de instruções por campo é: GUIDELINES (instrução metodológica do autor do template) > description (descrição do campo) > instrução genérica baseada no tipo de campo.

11.3 3. llm_client

Duas implementações:

  • LLMClient — síncrono, usado no modo item
  • AsyncLLMClient — assíncrono, usado nos modos abstract, document e ontology (processamento concorrente)

Ambas compartilham rate limiting:

  • RPM (requests per minute): semáforo com janela deslizante de 60s
  • TPM (tokens per minute): contagem de tokens de entrada e saída

11.4 4. validator

Valida a saída do LLM compilando-a com synesis.load(). Se o output contém erros:

  1. Extrai apenas blocos Synesis relevantes (_extract_item_blocks / _extract_ontology_blocks) — descarta markdown, SOURCE ou ONTOLOGY que o LLM eventualmente adicione
  2. Remove fences de código (```)
  3. Envia o output + diagnósticos do compilador de volta ao LLM para correção
  4. Temperatura escalona: 0.0 → 0.2 → 0.5 para evitar loops determinísticos
  5. Após 3 tentativas, retorna o melhor resultado com cabeçalho de erro comentado
OrphanItem é ignorado

No modo item, o validador ignora o diagnóstico OrphanItem (ITEM sem SOURCE correspondente). Isso é esperado — o SOURCE existe no .syn do projeto, mas não é carregado na validação isolada para economizar tokens de contexto.

12 Projetos de teste reais

O synesis-coder é testado contra projetos reais com templates de complexidade variada:

Projetos usados como fixtures de teste
Projeto Template Características
Social_Acceptance GUIDELINES, ORDERED, ENUMERATED, SCALE, CHAIN com 5 relações Caso completo com ontologia multidimensional
aids_corpus CHAIN com relações em português, sem GUIDELINES Template sem instruções metodológicas
nave Sem campo CHAIN Template teológico minimalista
thompson_bible Sem ONTOLOGY scope Projeto que rejeita modo ontology

12.0.1 Executar testes sem API

Testes de integração (que consomem tokens) são excluídos por padrão. Executar a suíte normalmente não gera custo de API:

cd synesis-coder
pytest

12.0.2 Executar testes de integração

Requerem ANTHROPIC_API_KEY no ambiente:

pytest tests/ -v -m integration

12.0.3 Cobertura

pytest tests/ --cov=synesis_coder --cov-report=term-missing

13 Variáveis de ambiente

Variáveis de ambiente gerais
Variável Obrigatória Padrão Descrição
ANTHROPIC_API_KEY sim — Chave da API Anthropic
SYNESIS_CODER_BACKEND não anthropic Backend LLM (anthropic ou openai)
SYNESIS_CODER_MODEL não claude-opus-4-6 Modelo LLM padrão
SYNESIS_CODER_MAX_RETRIES não 3 Tentativas de correção por item
SYNESIS_CODER_TEMPERATURE não 0.0 Temperatura de geração
SYNESIS_CODER_RPM_LIMIT não 50 Requests por minuto
SYNESIS_CODER_TPM_LIMIT não 100000 Tokens por minuto

13.1 Modelo por fase

Cada fase do pipeline pode usar um modelo diferente. A variável específica tem precedência sobre SYNESIS_CODER_MODEL:

Modelos por fase
Variável Fase
SYNESIS_CODER_CRITIQUE_MODEL critique e a crítica dentro de refine
SYNESIS_CODER_REFINE_MODEL Reextração em refine
SYNESIS_CODER_NORMALIZATION_MODEL normalize

13.2 Limiares do pipeline ACT

Limiares configuráveis
Variável Padrão Descrição
SYNESIS_CODER_SUSPICION_THRESHOLD 0.20 Escore mínimo para emitir # REVISION
SYNESIS_CODER_MERGE_CONFIDENCE_THRESHOLD 0.65 Confiança mínima para canonizar um código
SYNESIS_CODER_REFINE_MAX_ITER 2 Iterações máximas por ITEM em refine

14 Erros comuns

14.1 synesis-coder não encontrado

'synesis-coder' is not recognized as an internal or external command

O executável não está no PATH. Soluções:

  • Verifique a instalação: pip show synesis-coder
  • Use o caminho completo: python -m synesis_coder item ...
  • No VS Code: configure synesisExplorer.coder.path com o caminho absoluto

14.2 Erro de configuração (API key)

Erro de configuração: ANTHROPIC_API_KEY não encontrada

Crie um arquivo .env no diretório de onde executa o comando, ou exporte a variável:

export ANTHROPIC_API_KEY=sk-ant-...

14.3 Template sem ONTOLOGY scope

Erro: O template do projeto 'thompson_bible' não define campos ONTOLOGY.

O modo ontology requer pelo menos um campo com SCOPE ONTOLOGY no template. Os modos item, abstract e document funcionam normalmente sem ontologia.

14.4 Validação falha após 3 tentativas

O cabeçalho de erro é incluído como comentário no output:

# synesis-coder: validation failed after 3 attempts
# errors: Missing required field 'chain' in ITEM block
ITEM @smith2024
    text: ...
    note: ...
END ITEM

Revise o bloco gerado e corrija manualmente os campos faltantes. Isso é raro em templates com GUIDELINES bem escritas.

15 Próximos passos