Getting Started with Synesis

Seu primeiro projeto em 30 minutos

1 Bem-vindo ao Tutorial Getting Started

Neste tutorial, nós vamos construir juntos seu primeiro projeto Synesis completo. Ao final, você terá criado um sistema de anotações estruturadas, validado sua consistência e exportado os resultados para análise.

O que você vai construir:

Um projeto de análise de entrevistas sobre adoção de tecnologia
Um template personalizado definindo campos e regras
Anotações interpretativas estruturadas
Uma ontologia com códigos conceituais
Exportações em JSON, CSV e Excel

Pré-requisitos:

Python 3.10 ou superior instalado
VSCode (recomendado, mas opcional)
30 minutos de tempo dedicado

Primeira vez com linha de comando?

Não se preocupe! Vamos explicar cada comando claramente. Se você ficar travado, veja nossa seção de Troubleshooting no final.

1.1 Passo 1: Instalação do Compilador e ambiente de trabalho

Primeiro, vamos instalar o compilador Synesis. Abra seu terminal e execute:

pip install synesis

Agora, vamos verificar se a instalação funcionou:

synesis --version

O output deve ser algo como:

synesis, version 0.2.6

Checkpoint ✓

Se você vê o número da versão, parabéns! O compilador está instalado corretamente. Se não, veja Troubleshooting.

Agora, vamos instalar o Language Server Protocol (LSP). Com ele é possível editar códigos em linguagem Synesis com verificação automática em tempo real.

Para instalar, digite em seu terminal e execute:

pip install synesis-lsp

Por fim, instale o editor de código VSCode e a extensão Synesis. Veja instruções aqui:

Tutorial Synesis Explorer — Configurar o ambiente VSCode

1.2 Passo 2: Criar a Estrutura do Projeto

Vamos criar uma pasta para nosso projeto. No terminal, execute:

mkdir meu-primeiro-projeto
cd meu-primeiro-projeto

Agora vamos usar o comando synesis init para criar a estrutura inicial:

synesis init --name "Análise de Adoção Tecnológica"

O que aconteceu? O Synesis criou os seguintes arquivos:

meu-primeiro-projeto/
├── analysis.synp          # Arquivo de projeto (orquestrador)
├── template.synt          # Template (define campos)
├── references.bib         # Bibliografia (vazia por enquanto)
├── annotations/           # Pasta para anotações
│   └── example.syn       # Exemplo de anotação
└── ontology/             # Pasta para ontologias
    └── codes.syno        # Ontologia de códigos

Checkpoint ✓

Liste os arquivos com ls (Linux/Mac) ou dir (Windows). Você deve ver os arquivos acima.

1.3 Passo 3: Entender o Template

O template é o contrato entre você e o compilador. Vamos abrir o arquivo template.synt em um editor de texto:

# Windows
notepad template.synt

# Linux/Mac
nano template.synt
# ou
code template.synt  # se você tem VSCode

Você verá algo assim:

TEMPLATE analysis
version: "1.0"

ITEM FIELDS
    REQUIRED quote
    OPTIONAL memo
    OPTIONAL code
    OPTIONAL chain
END ITEM FIELDS

FIELD quote TYPE QUOTATION
    SCOPE ITEM
    DESCRIPTION Citação literal extraída da fonte
END FIELD

FIELD memo TYPE MEMO
    SCOPE ITEM
    DESCRIPTION Sua interpretação e análise do trecho
END FIELD

FIELD code TYPE CODE
    SCOPE ITEM
    DESCRIPTION Código conceitual da ontologia
END FIELD

FIELD chain TYPE CHAIN
    SCOPE ITEM
    DESCRIPTION Relação causal entre conceitos
    RELATIONS
        INIBE: Um fator reduz ou impede outro
        FAVORECE: Um fator promove ou facilita outro
    END RELATIONS
END FIELD

O que isso significa?

ITEM FIELDS: Declara quais campos o bloco ITEM aceita e se são obrigatórios ou opcionais
FIELD quote TYPE QUOTATION: Campo obrigatório para citações literais
FIELD memo TYPE MEMO: Campo para sua interpretação analítica
FIELD code TYPE CODE: Campo para códigos conceituais (pode aparecer várias vezes no mesmo ITEM)
FIELD chain TYPE CHAIN: Campo para relações causais, com as relações válidas declaradas

Regra de Ouro

O template é a única fonte da verdade. Se você adicionar campos aqui, o compilador vai validá-los. Se você usá-los sem definir, o compilador vai reclamar.

1.4 Passo 4: Definir Nossa Ontologia

Agora vamos definir os códigos conceituais que vamos usar. Abra ontology/codes.syno:

code ontology/codes.syno  # ou seu editor preferido

Substitua o conteúdo por:

ONTOLOGY custo
    descricao: "Fatores econômicos relacionados ao preço e investimento necessário"
    grupo: fatores_de_adocao
END ONTOLOGY

ONTOLOGY facilidade_de_uso
    descricao: "Percepção de complexidade ou simplicidade da tecnologia"
    grupo: fatores_de_adocao
END ONTOLOGY

ONTOLOGY utilidade_percebida
    descricao: "Crença de que a tecnologia trará benefícios práticos"
    grupo: fatores_de_adocao
END ONTOLOGY

ONTOLOGY adocao_de_ia
    descricao: "Decisão de incorporar inteligência artificial nos processos da organização"
    grupo: desfechos
END ONTOLOGY

Salve o arquivo.

Checkpoint ✓

Vamos validar a ontologia. No terminal, execute:

synesis check ontology/codes.syno

Se não houver erros, você verá: ✓ Ontology is valid

1.5 Passo 5: Criar Nossa Primeira Fonte Bibliográfica

Vamos adicionar uma referência fictícia à nossa bibliografia. Abra references.bib:

code references.bib

Adicione:

@interview{entrevista_joao2026,
  author = {João Silva},
  title = {Entrevista sobre adoção de IA},
  year = {2026},
  type = {Entrevista semiestruturada},
  note = {Gerente de TI, empresa de médio porte}
}

@interview{entrevista_maria2026,
  author = {Maria Santos},
  title = {Entrevista sobre resistência tecnológica},
  year = {2026},
  type = {Entrevista em profundidade},
  note = {Analista de sistemas, startup}
}

Salve o arquivo.

1.6 Passo 6: Criar Nossas Anotações

Agora vem a parte emocionante! Vamos criar anotações interpretativas. Crie um novo arquivo annotations/entrevistas.syn:

code annotations/entrevistas.syn

Digite o seguinte:

SOURCE @entrevista_joao2026
END SOURCE

ITEM @entrevista_joao2026
    quote: "O custo inicial é proibitivo para nossa escala de operação"
    memo: Entrevistado expressa barreira econômica clara à adoção de IA
    code: custo
    chain: custo -> INIBE -> adocao_de_ia
END ITEM

ITEM @entrevista_joao2026
    quote: "Parece muito complexo, não temos expertise interna"
    memo: Falta de capacitação técnica percebida como obstáculo
    code: facilidade_de_uso
    chain: facilidade_de_uso -> INIBE -> adocao_de_ia
END ITEM

SOURCE @entrevista_maria2026
END SOURCE

ITEM @entrevista_maria2026
    quote: "Se fosse mais barato, a gente testaria. A tecnologia parece boa"
    memo: Reconhecimento de utilidade, mas custo como fator limitante
    code: custo
    code: utilidade_percebida
    chain: utilidade_percebida -> FAVORECE -> adocao_de_ia
    chain: custo -> INIBE -> adocao_de_ia
END ITEM

Salve o arquivo.

Observe o padrão

Cada ITEM conecta: 1. Uma citação literal (quote) 2. Sua interpretação (memo) 3. Códigos conceituais (code) 4. Relações causais (chain)

Isso é rastreabilidade bidirecional: da evidência à interpretação e vice-versa.

1.7 Passo 7: Validar Tudo

Antes de compilar, vamos validar que tudo está consistente. Execute:

synesis check analysis.synp

O output deve mostrar:

✓ Template is valid
✓ Bibliography loaded: 2 entries
✓ Ontology is valid
✓ All annotations are valid
✓ All codes are defined in ontology
✓ All bibrefs exist in bibliography
✓ No validation errors found

Checkpoint ✓

Se você vê todas as marcas de verificação (✓), excelente! Se houver erros, leia as mensagens cuidadosamente — o compilador indica exatamente o que precisa ser corrigido.

1.8 Passo 8: Compilar o Projeto

Agora vem o momento mágico. Vamos compilar nosso projeto e gerar as saídas estruturadas:

synesis compile analysis.synp --output output/

O que aconteceu? O compilador gerou vários arquivos:

output/
├── analysis.json          # Estrutura hierárquica completa
├── sources.csv           # Tabela de fontes
├── items.csv             # Tabela de anotações
├── codes.csv             # Tabela de códigos
├── chains.csv            # Tabela de relações
└── analysis.xlsx         # Excel com múltiplas abas

Explore os resultados

Abra o arquivo analysis.xlsx no Excel ou LibreOffice. Você verá:

Aba “Sources”: Lista de fontes bibliográficas
Aba “Items”: Todas as anotações com seus campos
Aba “Codes”: Frequência de códigos
Aba “Chains”: Mapa de relações causais

Agora você pode fazer análises quantitativas sobre dados qualitativos!

1.9 Passo 9: Adicionar Mais Uma Anotação

Vamos praticar! Abra novamente annotations/entrevistas.syn e adicione:

ITEM @entrevista_maria2026
    quote: "A interface é intuitiva, mas precisaríamos de treinamento"
    memo: Reconhece facilidade de uso, mas identifica necessidade de capacitação
    code: facilidade_de_uso
END ITEM

Salve, valide e compile novamente:

synesis check analysis.synp
synesis compile analysis.synp --output output/

Observe: O arquivo output/analysis.xlsx agora tem 4 anotações em vez de 3!

Checkpoint ✓

Você acaba de fazer o ciclo completo: anotar → validar → compilar → analisar. Este é o workflow Synesis.

1.10 Passo 10 (Opcional): Instalar a Extensão VSCode

Se você usa VSCode, instale a extensão Synesis Explorer para ter:

Syntax highlighting automático
Validação em tempo real
Autocomplete de códigos
Tree views de fontes, códigos e relações

Instalação:

Abra VSCode
Pressione Ctrl+Shift+X (abre Extensions)
Busque por “Synesis Explorer”
Clique em “Install”

Agora, abra sua pasta do projeto no VSCode:

code .

Abra o arquivo annotations/entrevistas.syn. Você verá syntax highlighting colorido e, se houver erros, linhas onduladas vermelhas com mensagens de diagnóstico.

1.11 🎉 Parabéns!

Você acabou de criar seu primeiro projeto Synesis completo! Você aprendeu a:

✅ Instalar o compilador Synesis
✅ Criar a estrutura de um projeto
✅ Definir um template personalizado
✅ Criar uma ontologia de códigos
✅ Adicionar referências bibliográficas
✅ Escrever anotações interpretativas estruturadas
✅ Validar consistência semântica
✅ Compilar para formatos universais (JSON/CSV/Excel)
✅ Configurar o ambiente VSCode (opcional)

1.12 Próximos Passos

Agora que você domina o básico, explore:

1.12.1 Aprofundar Conhecimento

Guia para Pesquisadores — Aplicar Synesis em pesquisa qualitativa
Referência da Linguagem — Sintaxe completa

1.12.2 Resolver Problemas Específicos

1.12.3 Entender Conceitos

1.13 Troubleshooting

1.13.1 Erro: `command not found: synesis`

Causa: Python não está no PATH ou pip instalou em local não reconhecido.

Solução:

python -m pip install --user synesis
python -m synesis --version

1.13.2 Erro: `Template file not found`

Causa: Você está rodando comandos no diretório errado.

Solução:

# Certifique-se de estar na pasta do projeto
cd meu-primeiro-projeto
pwd  # Deve mostrar o caminho do projeto

1.13.3 Erro: `Code 'XYZ' not defined in ontology`

Causa: Você usou um código em annotations/entrevistas.syn que não existe em ontology/codes.syno.

Solução: 1. Abra ontology/codes.syno 2. Adicione um bloco ONTOLOGY conceito_novo ... END ONTOLOGY com descricao: e grupo: 3. Salve e valide novamente

1.13.4 Erro: `Bibref '@abc' not found in bibliography`

Causa: Você referenciou uma fonte que não existe em references.bib.

Solução: 1. Abra references.bib 2. Adicione a entrada BibTeX com a chave abc 3. Salve e valide novamente

Ficou com dúvidas? Abra uma discussão em GitHub Discussions ou consulte a documentação completa.

1 Bem-vindo ao Tutorial Getting Started

1.1 Passo 1: Instalação do Compilador e ambiente de trabalho

1.2 Passo 2: Criar a Estrutura do Projeto

1.3 Passo 3: Entender o Template

1.4 Passo 4: Definir Nossa Ontologia

1.5 Passo 5: Criar Nossa Primeira Fonte Bibliográfica

1.6 Passo 6: Criar Nossas Anotações

1.7 Passo 7: Validar Tudo

1.8 Passo 8: Compilar o Projeto

1.9 Passo 9: Adicionar Mais Uma Anotação

1.10 Passo 10 (Opcional): Instalar a Extensão VSCode

1.11 🎉 Parabéns!

1.12 Próximos Passos

1.12.1 Aprofundar Conhecimento

1.12.2 Resolver Problemas Específicos

1.12.3 Entender Conceitos

1.13 Troubleshooting

1.13.1 Erro: command not found: synesis

1.13.2 Erro: Template file not found

1.13.3 Erro: Code 'XYZ' not defined in ontology

1.13.4 Erro: Bibref '@abc' not found in bibliography

1.13.1 Erro: `command not found: synesis`

1.13.2 Erro: `Template file not found`

1.13.3 Erro: `Code 'XYZ' not defined in ontology`

1.13.4 Erro: `Bibref '@abc' not found in bibliography`