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).
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues