Primeiros passos

Lutz é uma ferramenta de linha de comando e interface web para triagem e análise de artigos acadêmicos em PDF usando IA. Este guia cobre a instalação e os primeiros comandos para colocar o projeto em funcionamento.

Pré-requisitos

• Python 3.10 ou superior
• Terminal (PowerShell no Windows, Terminal no macOS/Linux)
• Uma pasta com PDFs de artigos científicos
• Um modelo de IA: Docker Model Runner, Ollama, OpenAI, OpenRouter ou Anthropic

Instalação

Via PyPI (recomendado)

Linux / macOS

python -m venv .venv
source .venv/bin/activate
pip install lutz-research

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install lutz-research

Para instalar com a interface web:

pip install "lutz-research[ui]"

Verifique a instalação:

lutz --version
lutz --help

A partir do código-fonte

git clone https://github.com/jooguilhermesc/lutz.git
cd lutz
pip install -e .

---

Criando um projeto

mkdir minha-revisao
cd minha-revisao
lutz init

O comando lutz init cria a estrutura de diretórios e arquivos de configuração:

minha-revisao/
├── articles/                   → PDFs dos artigos
├── prompts/                    → templates de prompt prontos para editar
│   ├── systematic_review.md
│   ├── methodology_analysis.md
│   ├── evidence_quality.md
│   └── thematic_synthesis.md
├── analysis/
│   └── execution_reports/      → relatórios gerados pelas análises
├── .env.example                → exemplo de configuração de modelos
├── .gitignore
└── README.md

TIP

Você pode passar um nome de projeto: lutz init minha-revisao. Se omitido, o nome da pasta atual é usado.

---

Adicionando PDFs

Copie os arquivos manualmente para articles/ ou use o comando load:

Linux

lutz load --f ~/Downloads/artigos --so linux

macOS

lutz load --f ~/Desktop/artigos --so mac

Windows

lutz load --f "C:\Users\Ana\Downloads\artigos" --so windows

Você também pode usar a aba Biblioteca → + Adicionar PDFs na interface web para fazer upload diretamente pelo navegador.

Exemplo com artigos reais

lutz load --f ~/Downloads/AI-cyber --so linux
# Found 18 PDF candidate(s)...
# Copying articles... ████████████████████ 100%
# Done. Copied: 18 | Skipped: 0 | Invalid: 0

---

Vetorizando os artigos

lutz vectorize

Este comando executa três fases:

1. Verificação de segurança — analisa cada PDF em busca de JavaScript embutido, XFA, ações automáticas e padrões de prompt injection.
2. Extração de texto — usa pdfplumber (com fallback para pypdf) e divide o conteúdo em chunks de palavras.
3. Embedding e indexação — gera vetores de embedding e armazena no banco LanceDB em .lutz/vector_store/.

Para vetorização com detecção de seções (abstract, metodologia, resultados…):

lutz vectorize --section-parse

---

Rodando uma análise

lutz analysis --p prompts/systematic_review.md

Modo RAG (padrão): embeds do prompt recuperam os chunks mais relevantes do corpus inteiro e fazem uma única chamada ao LLM.

Modo por artigo: cada artigo recebe uma chamada separada, útil para triagem com veredicto INCLUDE/EXCLUDE:

lutz analysis --p prompts/screening.md --per-article --workers 4

---

Abrindo a interface web

lutz web

Isso inicia o servidor FastAPI + React em http://localhost:8765 e abre o navegador automaticamente.

Para escolher outra porta:

lutz web --port 8080

Veja a seção Interface Web para uma descrição completa de cada página.

---

Fluxo completo de revisão sistemática

# 1. Criar projeto
lutz init minha-revisao && cd minha-revisao

# 2. Adicionar PDFs
lutz load --f ~/Downloads/artigos --so linux

# 3. Vetorizar com detecção de seções
lutz vectorize --section-parse

# 4. Conferir seções detectadas
lutz vector-store --sections

# 5. Remover duplicatas entre bases (PubMed, Scopus, WoS)
lutz dedup --threshold 0.05

# 6. Priorizar triagem por relevância semântica
lutz rank --question "sua pergunta PICO aqui" --filter-sections abstract

# 7. Triagem por abstract (rápido e econômico)
lutz analysis --p prompts/screening.md --per-article --workers 4 \
  --filter-sections abstract

# 8. Análise de metodologia e resultados
lutz analysis --p prompts/methodology_analysis.md \
  --filter-sections methodology,results

# 9. Extrair citações dos artigos relevantes
lutz citations \
  --analysis analysis/execution_reports/screening_<timestamp>.json \
  --workers 4 --only-relevant

# 10. Síntese temática por clustering
lutz model explore kmeans --k-range 2..12   # escolhe k
lutz model fit kmeans --k 5                 # treina uma vez
lutz model cluster-report --model kmeans_5  # síntese por cluster

Veja a seção Análise Semântica para detalhes sobre deduplicação, ranking, clustering e detecção de outliers.