Inteligência artificial · estudo de caso
Farol
Transforma documentação técnica em pacotes de conhecimento com fonte verificável para agentes de IA — e recusa avançar quando falta evidência.
Visão geral
O projeto em poucas palavras
O Farol recebe uma fonte de documentação — uma pasta, um arquivo, uma URL, um repositório Git ou um nome de catálogo — e produz um pacote portátil que um agente de IA consegue consultar com contexto e com evidência. É uma ferramenta de linha de comando em Python, com uma API, de código aberto sob licença MIT.
Em uma linha: fonte → pacote de conhecimento → agente que responde com base no que está escrito e mostra onde leu.
Desafio
O ponto de partida
Agentes de IA erram documentação de um jeito previsível: lembram uma versão antiga, inventam um valor padrão ou citam uma função que não existe — e raramente dizem de onde tiraram a informação. Usar só busca de trechos resolve parte disso, mas entrega fragmentos sem visão de conjunto. Usar só um resumo conceitual dá visão geral, mas não permite conferir o texto literal.
Há ainda um cuidado que costuma ser esquecido: documentação de terceiros tem licença. Transformá-la em base de conhecimento sem registrar isso é um risco.
Solução
Dois caminhos, um pacote
Cada pacote gerado separa o entendimento do fato:
| Parte | Papel |
|---|---|
| Skill | Conceitos, padrões e glossário: responde “qual padrão devo usar para fazer isso?”. |
| Roteador | Decide quando usar a skill e quando buscar o trecho literal. |
| Corpus RAG | Documentos normalizados com proveniência, para perguntas como “qual é o valor padrão?”. |
| Manifesto | Identidade, licença, hashes, estado e métricas do pacote. |
Respostas factuais apontam para a origem exata, como caminho e seção ou caminho e linha. O Farol não é um chatbot, não executa modelos e não exige chave de API: o agente externo continua responsável por carregar o contexto e escrever a resposta.
Processo
Falhar de forma segura
O fluxo tem etapas explícitas: resolver a fonte, planejar (mostrando mudanças, políticas e bloqueios sem alterar nada), gerar em uma área de rascunho, validar e só então promover. Se algo falha no meio, o pacote ativo não é substituído por um incompleto.
Algumas decisões dão o tom do projeto:
Fail-closed. Ambiguidade, licença desconhecida, revogação e evidência ausente bloqueiam o avanço em vez de serem ignoradas.
Representação intermediária canônica. Extratores de PDF, documentos Office, e-books, texto, páginas web e repositórios preservam blocos, relações e localizadores antes de qualquer síntese ou indexação.
Recuperação. Checkpoints, diário de operações, backup e rollback preservam a geração ativa se uma execução for interrompida.
Aquisição web responsável. O acesso respeita robots.txt, redirecionamentos seguros e limites de páginas, profundidade, tamanho e tempo.
Integrações opcionais. O RAGFlow (serviço externo, com imagem fixada por digest e acesso por token) e o OCR são perfis opt-in; o núcleo funciona localmente, sem modelo, banco ou serviço obrigatório.
Meu papel
O que fiz
Projetei a arquitetura e escrevi o código — cerca de 32 mil linhas de Python no pacote principal —, os esquemas de contrato, a CLI e a API Python, os extratores, o roteador, o pipeline de validação e os gates de release. O núcleo não tem dependências obrigatórias; formatos de documento e integrações entram por extras opcionais.
O trabalho foi conduzido por especificação: o planejamento, o estado e as evidências de cada etapa ficam versionados no repositório, o que permite retomar o desenvolvimento sem depender de memória.
Resultados
Estado atual
A versão 2.0.0rc1 é uma candidata a lançamento, e o próprio repositório é claro: não é uma versão estável e ainda não há tag nem release publicada. O gate completo de qualidade, com 25 etapas, passou em 20 de setembro de 2026; em 27 de setembro, o perfil “core” passou 22 etapas, com 1.050 testes aprovados e 12 ignorados de forma explícita. A integração real com o RAGFlow foi validada localmente. A promoção para versão estável depende de novos gates e de autorização explícita.
Aprendizados
O que guiou as decisões
Uma base de conhecimento só é confiável se souber recusar. Fazer o sistema parar quando falta licença ou evidência, em vez de “dar um jeito”, deu mais confiança nas respostas do que qualquer ajuste de recuperação.
Separar conceito de fato também simplificou tudo: a skill cuida do raciocínio, o corpus cuida da citação, e cada um pode ser avaliado por conta própria.