nexus-rag

Motor de ingestão de documentos normativos em Python. Recebe um PDF e devolve entidades estruturadas e tipadas — prontas para alimentar um banco vetorial, um grafo de conhecimento, ou qualquer pipeline RAG que você estiver construindo.

Sem banco de dados embutido. Sem servidor. Sem opiniões sobre onde você vai guardar os dados.

O problema que isso resolve

PDFs de resoluções, portarias, leis e normas técnicas são documentos densos e mal estruturados. Converter esse tipo de conteúdo em dados utilizáveis manualmente é lento e frágil. Fazer isso com um text.split("\n\n") genérico gera lixo — chunks que cortam no meio de um artigo, perdem o contexto da seção, e não capturam nenhuma das relações entre documentos.

O nexus-rag foi construído para esse problema específico. Ele divide o documento respeitando a hierarquia normativa real (títulos, capítulos, artigos, parágrafos, incisos), e usa uma LLM com saída estruturada para extrair relações explícitas entre documentos — do tipo "a Resolução 361/2026 revoga a Resolução 221/2018".

Como funciona

O pipeline tem três fases em sequência, todas em memória:

PDF
 │
 ▼
DoclingParser          → converte para Markdown com layout preservado
 │
 ▼
ConfigurableMarkdownChunker  → divide em fragmentos semânticos (Atoms)
 │                             respeitando a hierarquia do documento
 ▼
StructuredBondExtractor      → varre os Atoms por frases-gatilho,
 │                             despacha candidatos para a LLM em paralelo,
 ▼                             e extrai relações como objetos Pydantic (Bonds)

(Molecule, [Atom, ...], [Bond, ...])

O que você recebe de volta são três objetos Python tipados. O que fazer com eles é por sua conta.

Modelo de domínio

Molecule — o documento inteiro. Metadados, aliases e o Markdown bruto produzido pelo parser.

Atom — um fragmento semântico. Carrega o trecho de texto e o caminho hierárquico de onde ele veio: ["Capítulo II", "Artigo 5", "Parágrafo 1"].

Bond — uma relação entre documentos, no formato Sujeito → Relação → Alvo. A relação é validada contra um Enum gerado a partir dos tipos que você configurou — a LLM não consegue inventar um valor fora da lista.

Resolução 361/2026  ──[ REVOGA ]──►  Resolução 221/2018
Resolução 361/2026  ──[ ALTERA ]──►  Portaria 88/2020

Instalação

pip install -e .

Para usar com Ollama local:

pip install langchain-ollama

A biblioteca aceita qualquer modelo compatível com LangChain Structured Output — Ollama, OpenAI, Anthropic, Groq, o que você preferir.

Uso básico

import asyncio
from langchain_ollama import ChatOllama
from nexus_rag import NexusPipelineRunner

async def main():
    pipeline = NexusPipelineRunner(
        llm=ChatOllama(model="qwen2.5:7b", temperature=0),
        relation_types=["REVOGA", "ALTERA", "ADICIONA", "REGULAMENTA"],
        id_format_hint="NÚMERO/ANO (ex: 361/2026)",
        chunking_rules=[
            r"(?i)^#{1,3}\s+(?:título|capítulo|seção|anexo|resolve).*",
            r"(?i)^(?:#{1,3}\s*)?(?:Art|Artigo)[\.\s]+\d+(?:º|o|°)?\b.*",
            r"(?i)^(?:-\s*)?(?:§|Parágrafo)[\.\s]*(?:\d+|único).*",
        ],
        candidate_trigger_pattern=(
            r"(?i)(ficam?\s+revogad[ao]s?|redação\s+dada\s+(?:pela|pelo)|"
            r"nos\s+termos\s+d[ao]|passa[m]?\s+a\s+vigorar)"
            r".*?(Resolução|Portaria|Decreto|Lei|Deliberação)"
        ),
    )

    molecule, atoms, bonds = await pipeline.process_from_pdf_async(
        pdf_path="./resolucao-361-2026.pdf",
        molecule_id="361/2026",
        title="Resolução 361/2026",
        aliases=["361/2026"],
    )

    print(f"{len(atoms)} átomos extraídos")
    print(f"{len(bonds)} ligações encontradas")
    for bond in bonds:
        print(f"  {bond.source_id} [{bond.relation}] {bond.target_id}")

asyncio.run(main())

Documentação

• Primeiros passos — instalação, configuração do Ollama, diretórios e execução do exemplo
• Arquitetura — estrutura de pastas, entidades do domínio e decisões de design
• exemplo_uso_llm_local.py — exemplo de uso com Ollama local
• exemplo_uso_openai.py — exemplo de uso com OpenAI
• exemplo_uso_gemini.py — exemplo de uso com Google Gemini

Requisitos

• Python 3.10+
• Uma LLM compatível com LangChain Structured Output