Skip to main content
Glama
RAG Jurídico — Registro de Imóveis & Especialidades Extrajudiciais Conexas

RAG Jurídico — Registro de Imóveis & Especialidades Extrajudiciais Conexas

README.md
# ⚖️ RAG Jurídico — Registro de Imóveis & Especialidades Extrajudiciais Conexas

> **Plataforma Aberta de Engenharia de Conhecimento, Qualificação Registral e Pesquisa Normativa Rastreável com Foco Prioritário no Registro de Imóveis (RI)**  
> *Núcleo Central: Registro de Imóveis (RI) • Afluentes e Interfaces: Tabelionato de Notas • RCPN • RTD & RCPJ • Tabelionato de Protesto*  
> **Versão Normativa Atual:** `2026.12.07` • **103 Diplomas Oficiais Vigentes (Federal + CNJ + ANPD + Estadual Ceará + Fortaleza)** • **9.986 Dispositivos / URNs Canônicos (Prata)** • **396 Documentos / 1.318 Seções Granulares (Ouro — 100,00% dos 3.328 URNs elegíveis)** • **Grafo de Remissões (4.166 arestas)** • **Servidor MCP Local (10 Tools / 4 Resources / 1 Prompt)** • **146/146 casos do Golden Dataset**

---

## 🎯 Visão Geral do Projeto: Arquitetura Concéntrica Imobiliária

O **RAG Jurídico — Registro de Imóveis** é uma arquitetura local e determinística de Engenharia de Conhecimento, Pesquisa Normativa e Suporte à Qualificação Registral projetada especificamente com **foco prioritário no Registro de Imóveis (RI)** (Art. 236 da Constituição Federal, Lei nº 6.015/1973 e Art. 5º da Lei nº 8.935/1994).

Em vez de dispersar o conhecimento em especialidades isoladas, o projeto adota uma **Arquitetura Concéntrica Gravitacional**:
- **Núcleo Central Prioritário (Registro de Imóveis):** Matrícula, prenotação, qualificação registral de títulos, emissão fundamentada de notas devolutivas, procedimento de dúvida (Art. 198 da LRP), alienação fiduciária e garantias reais (Leis nº 9.514/1997 e 14.711/2023), condomínio e incorporação imobiliária (Lei nº 4.591/1964), parcelamento do solo urbano (Lei nº 6.766/1979), regularização fundiária (REURB — Lei nº 13.465/2017), georreferenciamento e retificação de área (Leis nº 6.015/1973 e 10.267/2001), usucapião e adjudicação compulsória extrajudicial (Arts. 216-A e 216-B da LRP), bens públicos e terrenos de marinha (SPU/Laudêmio) e ecossistema ONR / SREI / SERP / SAEC.
- **Afluentes Notariais e Registrais Conexos (Interfaces que deságuam no RI):**
  - **Tabelionato de Notas (TN):** Escrituras públicas, doações, permutas, partilhas e pactos antenupciais examinados sob o crivo de títulos causadores submetidos à qualificação no RI;
  - **Registro Civil das Pessoas Naturais (RCPN):** Estado civil, regime de bens, eficácia de pactos, averbações de separação/divórcio e óbito de titulares de direitos reais;
  - **RTD e RCPJ:** Notificações extrajudiciais de constituição em mora para consolidação de propriedade fiduciária e qualificação de pessoas jurídicas adquirentes ou devedoras;
  - **Tabelionato de Protesto (TP):** Certidões de protesto e cancelamentos vinculados à análise de solvência e regularidade negocial imobiliária;
  - **Direito Tributário e Urbanístico:** ITBI (Fortaleza), ITCD (Ceará), ITR, laudêmio SPU e CNDs fiscais como condições legais para a prática de atos registrais imobiliários.

Diferentemente de sistemas RAG convencionais que fatiavam PDFs jurídicos em blocos arbitrários de caracteres (*naive chunking*) — destruindo a relação entre *caput*, parágrafos, incisos e alíneas, misturando artigos revogados com vigentes e confundindo resumos com texto de lei —, este projeto implementa uma **Arquitetura Medalhão Jurídica Determinística** com **Separação Epistêmica Estrita**:

1. **🥉 Camada Bronze (`data/01_bronze/`):** **103 fontes normativas oficiais primárias vigentes** (Constituição Federal de 1988, Portal da Legislação do Planalto, CNJ, ANPD, ONR/ITNs, CGJ/CE, TJCE, ALCE e Município de Fortaleza) + **16 precedentes vinculantes oficiais do STF e STJ**, catalogados sob domínio público (**Art. 8º, IV, da Lei nº 9.610/1998**) com integridade criptográfica `SHA-256`, URL oficial e manifestos auditáveis.
2. **🥈 Camada Prata (`data/02_prata/`):** Decomposição estrutural integralmente literal e determinística (gerada via parser Python, zero reescrita por LLM) em `dispositivos_canonicos.jsonl` (**9.986 registros / 9.986 URNs canônicos únicos**, incluindo **49 anexos canônicos**) e Markdown estruturado por diploma, atribuindo `URN` canônico estável sem colisão federativa, árvore hierárquica (`Parte > Livro > Título > Capítulo > Seção > Artigo`), status de vigência (`VIGENTE`, `ALTERADO_COMPILADO`, `REVOGADO`) e mapeamento das revogações expressas pelo Art. 556 do Provimento CNJ nº 149/2023 (**42 incisos mapeados / 34 redirecionamentos**) e revogações supervenientes CNJ/CE.
3. **🥇 Camada Ouro (`data/03_ouro/`):** **396 documentos estruturados (1.318 seções granulares)** — **321 fichas analíticas/índices**, **16 fichas de Jurisprudência Oficial Vinculada (STF e STJ)**, **54 protocolos operacionais de qualificação** e **5 tabelas operacionais canônicas**, cobrindo **100,00% dos 3.328 URNs elegíveis** (`config/matriz_elegibilidade_ouro.yaml`), com citações literais validadas matematicamente contra a Camada Prata (`verify_literal_quote()`).
4. **⚡ Camada de Índices e Grafo (`data/04_indices/`):** Catálogo relacional, busca híbrida real 100% offline em **SQLite + FTS5 (`unicode61 remove_diacritics 2`, `bm25()`) + Índice Vetorial ONNX INT8 CPU (`Xenova/multilingual-e5-small`, 384d) + Reciprocal Rank Fusion (RRF)** com vocabulário controlado de sinônimos de balcão (`config/sinonimos_extrajudicial.yaml`), filtro canônico `--especialidade` e **Grafo Determinístico de Remissões Cruzadas** (**3.424 nós conectados** e **4.166 arestas verificadas** com enriquecimento automático 1-hop).

> 📖 **Documentação Completa da v1.0:** consulte o **[Manual do Usuário](docs/MANUAL_USUARIO.md)** (instalação plug-and-play via ZIP, verificação SHA-256 e uso cotidiano) e o **[Manual Técnico de Integração MCP](docs/MANUAL_INTEGRACAO_MCP.md)** (protocolo STDIO, variáveis de ambiente, contrato das 10 tools / 4 resources / 1 prompt e segurança).

---

## 🛡️ Arquitetura de Prevenção de Alucinações Jurídicas

```mermaid
flowchart LR
    subgraph INGEST ["1. Engenharia Documental Determinística"]
        B["🥉 Bronze (103 Diplomas + 16 STF/STJ)\nFonte Oficial + SHA-256"] --> P["🥈 Prata (9.986 URNs Únicos)\nTexto Literal + Hierarquia\n+ Vigência Verificada"]
        P --> O["🥇 Ouro (396 Documentos / 1.318 Seções)\n321 Fichas + 16 Jurisprudência\n+ 54 Protocolos + 5 Tabelas"]
    end

    subgraph RETRIEVAL ["2. Recuperação Híbrida Offline, Grafo e Guardrails"]
        P & O --> IDX["⚡ SQLite FTS5 + ONNX INT8 RRF + Grafo\nLookup Exato + Seções + Sinônimos\n+ 4.166 Remissões Verificadas"]
        IDX --> GUARD["🛡️ Guardrails Anti-Alucinação\n• Bloco A (Literal) ≠ Bloco B (Análise/Juris)\n• Alerta de Revogação (Art. 556 + CNJ/CE)\n• Safe Abstention & DLP Guard"]
    end
```

### Travas Técnicas Implementadas
- **Separação Ontológica Estrita (`[BLOCO A — TEXTO LEGAL LITERAL]` vs. `[BLOCO B — ANÁLISE JURÍDICA E PROTOCOLOS]`):** Resumos, teses jurisprudenciais e comentários jamais são apresentados como redação de lei.
- **Validador Matemático de Sequência (`validate_article_sequence`):** Sequência numérica verificada nos diplomas indexados.
- **Verificador de Fidelidade Literal (`verify_literal_quote`):** Confere deterministicamente se as citações entre aspas na Camada Ouro correspondem a *substrings* exatas da Camada Prata oficial.
- **Controle Temporal (*Tempus Regit Actum*):** Intercepta automaticamente consultas a provimentos revogados pelo Art. 556 do Provimento CNJ nº 149/2023 (**42 incisos mapeados / 34 redirecionamentos**) e revogações supervenientes CNJ/CE (incluindo `Prov. 74/2018 → Prov. 213/2026` e `Prov. 39/2014 → CNIB 2.0`).
- **Abstenção Segura (`SAFE_ABSTENTION`):** Declara explicitamente a ausência de lastro normativo quando a consulta recai fora do escopo jurídico extrajudicial indexado ou menciona normas privadas licenciadas.

---

## 🏛️ Acervo Indexado (103 Diplomas Oficiais Vigentes & 396 Documentos Ouro — 100,00% dos 3.328 URNs Elegíveis)

O inventário completo e sempre atualizado dos **103 diplomas** (núcleo federal/CNJ, ANPD, ONR/ITNs, Estadual Ceará e ITBI Fortaleza), seus respectivos `source_id`, Tiers e percentuais de cobertura pode ser consultado diretamente via:
- Tool MCP `listar_diplomas_e_estatisticas` ou resource `rag-extrajudicial://catalogo/cobertura-ouro`;
- Metadados de release em [data/version.json](data/version.json) e relatório [data/04_indices/ouro_coverage_report.json](data/04_indices/ouro_coverage_report.json);
- Índice mestre da Camada Ouro em [data/03_ouro/00_Mapa_Juridico_Extrajudicial.md](data/03_ouro/00_Mapa_Juridico_Extrajudicial.md).

| Esfera / Bloco Normativo | Principais Diplomas e Conteúdos Indexados |
| :--- | :--- |
| **Núcleo Constitucional, Federal & CNJ** | CF/88, LRP (Lei 6.015/1973), LNR (Lei 8.935/1994), CC/2002, CPC/2015, CTN, LGPD, SERP (Lei 14.382/2022), Alienação Fiduciária & Marco Legal das Garantias (Leis 9.514/1997 e 14.711/2023), Concentração (Lei 13.097/2015), REURB (Lei 13.465/2017), Incorporação (Lei 4.591/1964), Parcelamento (Lei 6.766/1979), Protesto (Lei 9.492/1997), Emolumentos (Lei 10.169/2000), Terrenos de Marinha/SPU (DL 9.760/1946, Lei 9.636/1998, DL 2.398/1987), Georreferenciamento/INCRA/Faixa de Fronteira (Leis 5.868/1972, 6.634/1979, 10.267/2001, Dec. 4.449/2002), Provimento CNJ nº 149/2023 (CNN/CNJ-Extra), Prov. CNJ 213/2026, Res. CNJ 35/2007–571/2024 e demais atos CNJ vigentes. |
| **Proteção de Dados (ANPD)** | Resoluções CD/ANPD nº 01/2021, 02/2022, 04/2023, 15/2024, 18/2024, 19/2024 e 32/2026. |
| **Ecossistema Digital ONR / SREI** | Provimento CNJ nº 124/2021 e Instruções Técnicas de Normalização ONR (ITNs 002/2024, 003/2025 e 004/2026). |
| **Módulo Estadual Ceará & Fortaleza** | CNNR/CE (Prov. CGJ/CE 04/2023), Portaria TJCE 2.982/2025 (Emolumentos), Provs. CGJ/CE 24/2024 e 04/2026 (Selo Tipo 14), Leis CE (Emolumentos, FERMOJU, FAADEP, FRMMP, ITCD Lei 15.812/2015) e LC Fortaleza 159/2013 (ITBI). |
| **Camada Ouro (396 docs / 1.318 seções)** | 321 fichas analíticas e índices, 54 protocolos operacionais de qualificação (`PROTO_*` e `OURO_QUALIF_*`), 16 precedentes vinculantes STF/STJ (`JURIS_01..16`) e 5 tabelas operacionais canônicas (`TAB_01..05`). |

---

## 🚀 Como Usar Localmente (CLI de Pesquisa Normativa)

### Requisitos de Execução
- Python 3.11+ (biblioteca padrão `sqlite3` com FTS5 habilitado; sem necessidade de API paga ou LLM externo para pesquisa local).

### Exemplos de Execução no Terminal
```bash
# 1. Consulta constitucional exata (CF/88)
python cli_pesquisa.py --query "Art. 236 CF"

# 2. Consulta a jurisprudência vinculante (STF/STJ) com lastro legal vinculado
python cli_pesquisa.py --query "STF Tema 777 responsabilidade civil tabeliães registradores"

# 3. Consulta exata por artigo e diploma infraconstitucional
python cli_pesquisa.py --query "Art. 216-A LRP"

# 4. Consulta por tema em linguagem natural / coloquial de balcão (BM25 FTS5 + Sinônimos Controlados)
python cli_pesquisa.py --query "como tirar o nome do protesto depois de pagar a divida"

# 4b. Consulta filtrada por especialidade canônica (RI, TN, TP, RTD_RCPJ, RCPN, NC)
python cli_pesquisa.py --query "ficha de firma autocuratela PEP" --especialidade TN

# 5. Teste de controle temporal / alerta de revogação (Art. 556 do Provimento 149/2023)
python cli_pesquisa.py --query "Provimento 65/2017"

# 6. Teste de Abstenção Segura (matéria fora do escopo extrajudicial)
python cli_pesquisa.py --query "procedimento de direito penal militar crime de desercao"

# 7. Consulta ao Grafo Determinístico de Remissões Cruzadas de um URN
python cli_pesquisa.py --graph-urn "BR:FED:PRES:LEI:6015:1973:ART-216-A"

# 8. Saída estruturada em JSON (para integração com pipelines e agentes)
python cli_pesquisa.py --json --query "Art. 123 Provimento 149"

# 9. Modo interativo
python cli_pesquisa.py --interactive
```

---

## 🔌 Servidor MCP Local (Plug-and-Play v1.0 para Agentes de IA e IDEs)

O projeto inclui um **Servidor MCP (Model Context Protocol) nativo sobre `stdio` JSON-RPC 2.0** (`src/mcp/server.py`), instalável via `pyproject.toml` (`rag-juridico-mcp`) e independente de `cwd`, pronto para conexão em clientes MCP (Claude Desktop, Cursor, VS Code, Gemini CLI / Antigravity e agentes customizados):

```bash
# Instalação plug-and-play (modo híbrido offline com ONNX INT8 CPU)
pip install -e ".[hybrid]"

# Ou instalação enxuta (somente modo léxico SQLite FTS5)
pip install -e .

# Verificar prontidão do banco SQLite, índice vetorial, estatísticas e tools registradas
rag-juridico-mcp --check

# Listar tools disponíveis
rag-juridico-mcp --list-tools

# Executar o servidor MCP sobre stdio (JSON-RPC 2.0) a partir de qualquer diretório
rag-juridico-mcp
```

Variáveis de ambiente suportadas (opcionais, com fallback automático para a raiz do pacote): `RAG_DATA_DIR`, `RAG_CONFIG_DIR`, `RAG_DB_PATH`, `RAG_VECTOR_STORE_DIR`, `RAG_SYNONYMS_PATH`, `RAG_TELEMETRY_DIR` e `RAG_ENABLE_TELEMETRY=1`.

Exemplo de configuração em cliente MCP ([config/mcp_client_example.json](config/mcp_client_example.json)):

```json
{
  "mcpServers": {
    "rag-juridico-extrajudicial": {
      "command": "rag-juridico-mcp",
      "args": [],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "RAG_DATA_DIR": "/CAMINHO/PARA/RAG_JURIDICO_EXTRAJUDICIAL/data",
        "RAG_CONFIG_DIR": "/CAMINHO/PARA/RAG_JURIDICO_EXTRAJUDICIAL/config"
      }
    }
  }
}
```

### Ferramentas (`tools`), Recursos (`resources`) e Prompts Expostos via MCP
- **Tools (10):** `pesquisar_normativa`, `obter_artigo_exato`, `ler_documento_ouro`, `explorar_grafo_remissoes`, `listar_protocolos_e_tabelas`, `verificar_provimento_revogado`, `listar_diplomas_e_estatisticas`, `auditar_citacao_parecer`, `comparar_federal_cnj_vs_ceara` e `gerar_checklist_qualificacao`.
- **Resources (4):** `rag-extrajudicial://catalogo/versao`, `rag-extrajudicial://catalogo/mapa-ouro`, `rag-extrajudicial://catalogo/cobertura-ouro` e `rag-extrajudicial://catalogo/sinonimos`.
- **Prompt (1):** `qualificacao_registral_notarial` (roteiro guiado com separação estrita entre Texto Literal e Análise/Protocolos).

### Empacotamento de Distribuição v1.0 (GitHub Releases)
Como os índices binários (`normative_catalog.sqlite` e `vector_store/`) são ignorados no Git, o empacotador `scripts/build_release_bundle.py` gera bundles prontos para consulta com checksum `.sha256`:
```bash
# Bundle completo v1.0 plug-and-play (código runtime + SQLite + Ouro + vector_store ONNX/NPZ)
python scripts/build_release_bundle.py --profile hybrid

# Bundle leve v1.0 (código runtime + SQLite + Ouro, modo lexical_only sem ONNX)
python scripts/build_release_bundle.py --profile lexical
```

---

## 🔧 Reconstrução Determinística do Pipeline, Testes e Empacotamento de Release

Para contribuidores e auditores que desejarem reconstruir os índices a partir do código-fonte (usuários finais dos pacotes de release v1.0 **não** precisam executar esta etapa):

```bash
# 1. Reconstruir índices derivados (SQLite/FTS5, Grafo de Remissões e Cobertura Ouro 100%)
python -m src.cli.rebuild_all --only-indices

# 2. (Opcional) Reconstruir índice vetorial ONNX offline
python src/indexing/build_vector_index.py

# 3. Avaliar Golden Dataset (146 casos) e rodar suíte completa pytest (137 testes)
python src/evaluation/evaluate_golden_dataset.py
python -m pytest -q

# 4. Empacotar bundles plug-and-play v1.0 (.zip + .sha256) em dist/
python scripts/build_release_bundle.py --profile hybrid
python scripts/build_release_bundle.py --profile lexical
```

---

## 📂 Estrutura de Diretórios

```text
RAG_JURIDICO_EXTRAJUDICIAL/
├── LICENSE                               # Licença MIT (engenharia) + Domínio Público (Lei 9.610/98)
├── pyproject.toml                        # Empacotamento v1.0 (entry points rag-juridico-mcp e rag-juridico-cli)
├── requirements-runtime.txt              # Dependências mínimas de consulta (léxico + híbrido ONNX)
├── cli_pesquisa.py                       # CLI de pesquisa normativa local
├── CHANGELOG_NORMATIVO.md                # Histórico auditável de versões normativas
├── docs/
│   ├── MANUAL_USUARIO.md                 # Manual operacional v1.0 (instalação, consulta e interpretação)
│   └── MANUAL_INTEGRACAO_MCP.md          # Manual técnico MCP v1.0 (STDIO, env vars, 10 tools / 4 resources / 1 prompt)
├── config/
│   ├── mcp_client_example.json           # Bloco JSON plug-and-play para clientes MCP
│   ├── sinonimos_extrajudicial.yaml      # Vocabulário controlado de sinônimos de balcão
│   ├── settings.yaml                     # Configurações de isolamento, domínios oficiais e separação epistêmica
│   ├── taxonomy_especialidades.yaml      # Taxonomia das 5 especialidades + Núcleo Comum
│   └── matriz_elegibilidade_ouro.yaml    # Matriz de Elegibilidade por Tier (3.328 URNs elegíveis)
├── scripts/
│   └── build_release_bundle.py           # Empacotador de Release GitHub (perfis hybrid / lexical / knowledge-pack)
├── data/
│   ├── version.json                      # Metadados e estatísticas da release (2026.12.07)
│   ├── 01_bronze/                        # 103 fontes oficiais + manifestos com SHA-256
│   ├── 02_prata/                         # 9.986 URNs literais (dispositivos_canonicos.jsonl + remissoes_revogacoes.json)
│   ├── 03_ouro/                          # 396 documentos Ouro (1.318 seções) + 00_Mapa_Juridico_Extrajudicial.md
│   └── 04_indices/                       # normative_catalog.sqlite, grafo_remissoes.json, vector_store/ (ONNX INT8 + NPZ)
├── src/
│   ├── mcp/                              # Servidor MCP STDIO JSON-RPC 2.0 (10 tools, 4 resources, 1 prompt)
│   ├── retrieval/                        # Motor híbrido local (FTS5 + ONNX RRF), runtime_config (mode=ro) e telemetria
│   ├── validators/                       # Guardrail DLP, Literal Quote Verifier e Sequence Validator
│   ├── ingestion/                        # Captura oficial (Planalto / CF/88 / CNJ / ANPD / CE / ONR)
│   ├── parsers/                          # Decomposição Prata e construtores Ouro
│   ├── indexing/                         # Construtor SQLite/FTS5, Grafo de Remissões e Índice Vetorial ONNX
│   └── evaluation/                       # Avaliador do Golden Dataset (146 casos) e Auditor de Cobertura por Tier
└── tests/                                # Suíte automatizada (137 testes) + golden_datasets/ (146 casos)
```

---

## 📄 Licença e Regime Jurídico do Acervo

Consulte o arquivo [LICENSE](LICENSE): o código-fonte de engenharia, scripts, testes e documentação analítica são disponibilizados sob **Licença MIT**, enquanto todos os textos legais, constitucionais, regulamentares e decisões judiciais oficiais integram o **Domínio Público** brasileiro conforme o **Art. 8º, inciso IV, da Lei nº 9.610/1998**.

## ⚠️ Aviso Técnico-Jurídico (Disclaimer)

> Esta ferramenta realiza pesquisa estruturada e correlação automatizada sobre textos normativos públicos oficiais (**Art. 8º, IV, da Lei nº 9.610/1998**). Os resultados possuem caráter estritamente informativo e de apoio à pesquisa jurídica, não substituindo a conferência direta na publicação oficial nem o juízo prudencial de qualificação jurídica privativo do(a) Oficial de Registro, Tabelião(ã) ou profissional do Direito (Lei nº 8.935/1994 e Lei nº 6.015/1973).