NanoJud

Dados judiciais públicos, estruturados e rastreáveis.

Consulte e organize informações públicas do eSAJ/TJSP, DataJud/CNJ e DJEN usando Python, linha de comando ou agentes de IA compatíveis com MCP.

Comece aqui · Documentação · Uso com IA · Uso responsável · Releases

---

[!IMPORTANT] Status: beta público.

O projeto já oferece API Python, CLI, cliente configurável e servidor MCP local, mas continua em evolução. As fontes judiciais consultadas são externas e podem alterar páginas, contratos, disponibilidade ou limites sem aviso.

Confirme informações relevantes nos sistemas oficiais antes de utilizá-las em atividades profissionais.

[!NOTE] Este é um projeto independente. Não é um produto oficial do TJSP, CNJ, eSAJ ou DataJud.

A biblioteca não contorna autenticação, senha, captcha, segredo de justiça ou restrições técnicas das fontes consultadas.

Visão geral

O nanojud é uma camada local e auditável para consultar, estruturar e organizar dados judiciais públicos.

O projeto transforma informações dispersas em resultados adequados para:

• consultas jurídicas assistidas;
• linhas do tempo processuais;
• relatórios internos;
• automações locais;
• scripts e notebooks;
• integrações com sistemas;
• agentes de IA compatíveis com MCP;
• exportações estruturadas para análise.

A proposta é permitir que profissionais do Direito e equipes técnicas utilizem fontes públicas judiciais sem perder a origem, o contexto e os limites de cada informação.

Fontes integradas

Fonte	Conteúdo consultado
eSAJ/TJSP	Dados básicos, partes, movimentações, audiências, petições, incidentes, apensos e documentos públicos candidatos
DataJud/CNJ	Dados processuais estruturados e normalizados
DJEN	Comunicações e publicações judiciais

A disponibilidade e a cobertura dependem das informações publicadas por cada fonte.

Principais recursos

Para profissionais do Direito

• Consulta de processos públicos por número CNJ.
• Organização de dados básicos e movimentações.
• Construção de timelines cronológicas.
• Consolidação de informações provenientes de fontes diferentes.
• Identificação da origem de cada conjunto de dados.
• Exportação de resultados para arquivos estruturados.
• Uso por meio de agentes de IA locais.

Para integrações e automações

• API Python de alto nível.
• Cliente configurável para rotinas profissionais.
• Interface de linha de comando.
• Servidor MCP local por stdio.
• Exportação para JSON, JSONL, CSV e SQLite.
• Timeout, retry, backoff e rate limit.
• Cache local opcional.
• Logging e sessões HTTP injetáveis.
• Contratos tipados e exceções públicas.

Para segurança e qualidade

• Testes automatizados sem rede com fixtures sanitizadas.
• Testes opcionais contra fontes reais.
• Compatibilidade com Python 3.10, 3.11, 3.12 e 3.13.
• Cobertura mínima de testes exigida pelo CI.
• CodeQL, pip-audit, lint, type check e validação de pacote.
• Pacote marcado como tipado com py.typed.
• Documentação de LGPD, governança, ameaças e uso responsável.

---

Comece aqui

Escolha o caminho mais adequado ao seu perfil.

Perfil	Caminho recomendado
Advogado usando Claude Code ou outro agente local	Uso com agentes de IA
Usuário sem Git	Baixar o projeto como ZIP
Desenvolvedor Python	Instalação técnica
Usuário de terminal	Uso pela CLI
Usuário de MCP	Servidor MCP local
Contribuidor	Desenvolvimento

---

Uso com agentes de IA

O projeto pode ser preparado e utilizado por agentes que tenham acesso à pasta local e ao terminal do computador, como Claude Code e outros agentes de desenvolvimento.

Você não precisa conhecer Git, Python ou os comandos internos do projeto para seguir esse caminho.

[!WARNING] Uma IA utilizada apenas pelo navegador, sem acesso aos arquivos e ao terminal do seu computador, não conseguirá instalar ou executar o projeto localmente.

Baixar sem usar Git

1. Abra a página do repositório no GitHub.
2. Clique em Code.
3. Clique em Download ZIP.
4. Extraia o arquivo para uma pasta do computador.
5. Abra essa pasta no Claude Code ou em outro agente local.
6. Envie ao agente a instrução abaixo.

Instrução para preparar o projeto

Copie e cole esta mensagem no agente:

Prepare este projeto para uso jurídico local.

Leia primeiro o README.md e entenda a estrutura do projeto.

Identifique meu sistema operacional e prepare o ambiente automaticamente.

Crie um ambiente virtual isolado, atualize o pip, instale o projeto com os recursos de CLI e MCP e valide se a instalação está funcionando.

Use o Python do ambiente virtual e não instale dependências globalmente quando isso puder ser evitado.

Não altere o código-fonte durante a instalação.

Se este agente aceitar servidores MCP, configure o servidor MCP local usando o ambiente virtual do projeto. Se não aceitar, mantenha a CLI disponível e explique de forma simples como utilizá-la.

Não tente acessar processos sigilosos, contornar autenticação, senha, captcha ou qualquer restrição técnica. Não solicite credenciais judiciais.

Ao terminar, informe:

1. se a instalação foi concluída;
2. se a biblioteca foi importada corretamente;
3. se a CLI está funcionando;
4. se o MCP foi configurado;
5. quais fontes estão disponíveis;
6. como abrir e usar o projeto novamente;
7. e qual é o próximo passo para consultar um processo público.

O agente deverá executar as etapas necessárias e apresentar apenas as decisões que realmente dependam de você.

Resultado esperado

Ao final da preparação, o agente deverá apresentar um resumo semelhante a este:

Preparação concluída.

- Biblioteca instalada: sim
- CLI disponível: sim
- MCP configurado: sim ou não
- Ambiente utilizado: .venv
- Código-fonte alterado: não

Agora envie o número CNJ público do processo que deseja consultar.

Consultar um processo com o agente

Depois da instalação, envie uma instrução como:

Consulte o processo público de número:

0015020-23.2010.8.26.0053

Apresente:

- os dados básicos;
- a última movimentação;
- uma linha do tempo em ordem cronológica;
- as informações encontradas no eSAJ, DataJud e DJEN;
- eventuais diferenças entre as fontes;
- a data e a origem de cada informação relevante.

Separe claramente:

1. dados obtidos diretamente das fontes;
2. dados normalizados pelo projeto;
3. explicações ou inferências produzidas pela IA.

Não trate análises produzidas pela IA como informações oficiais do tribunal.

Substitua o número utilizado no exemplo pelo número CNJ público que deseja consultar.

Outros pedidos úteis

Resuma as movimentações mais importantes deste processo.

Mostre apenas as movimentações dos últimos 90 dias.

Compare os dados encontrados no eSAJ, DataJud e DJEN.

Gere uma linha do tempo objetiva com data, evento e fonte.

Exporte os dados públicos deste processo para JSON.

Identifique divergências ou informações ausentes entre as fontes.

---

Demonstração pública

Para demonstrações, tutoriais e testes manuais, o projeto utiliza o seguinte processo público:

0015020-23.2010.8.26.0053

Trata-se de um Mandado de Segurança Cível envolvendo sindicato e Administração Pública estadual.

Em uma validação manual realizada em 31 de julho de 2026, o projeto obteve dados do eSAJ/TJSP, DataJud/CNJ e DJEN e gerou uma timeline agregada sem falhas registradas naquela execução.

Os resultados podem mudar, pois dependem de fontes externas atualizadas continuamente.

Consulte a demonstração completa em:

• Demonstração pública
• Exemplos seguros

---

Instalação

Requisitos

• Python 3.10 ou superior.
• Acesso à internet para instalação e consultas.
• Terminal ou agente local com acesso ao terminal.

Instalar pelo PyPI

Para usar a biblioteca, CLI e consultas principais:

python -m pip install nanojud

Para instalar tambem o servidor MCP local e leitura de PDFs publicos em memoria:

python -m pip install "nanojud[mcp]"

Depois valide:

python -c "import nanojud; print(nanojud.__version__)"
nanojud --help

MCP direto com uvx

Para clientes MCP que aceitam comando externo, a forma mais simples e nao manter projeto clonado:

uvx --from "nanojud[mcp]" nanojud-mcp

Exemplo de configuracao MCP:

{
  "mcpServers": {
    "nanojud": {
      "command": "uvx",
      "args": ["--from", "nanojud[mcp]", "nanojud-mcp"]
    }
  }
}

Desenvolvimento local

Use este caminho apenas se voce quer contribuir, rodar testes ou alterar o codigo.

git clone https://github.com/lucmolero/nanojud.git
cd nanojud

Tambem e possivel baixar o projeto por Code -> Download ZIP.

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev,mcp]"

Linux ou macOS

python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev,mcp]"

Validar a instalação

python -c "import nanojud; print('nanojud instalado com sucesso')"

nanojud --help

Também é possível executar a CLI pelo módulo:

python -m nanojud.cli --help

---

Uso pela CLI

Consultar um processo

nanojud search 0015020-23.2010.8.26.0053

Gerar um extrato em JSON

nanojud extrato 0015020-23.2010.8.26.0053 --out extrato.json

Consultar partes

nanojud partes 0015020-23.2010.8.26.0053

Consultar o DJEN

nanojud djen 0015020-23.2010.8.26.0053 --out djen.json

Consultar o DataJud

nanojud datajud 0015020-23.2010.8.26.0053 --out datajud.json

Gerar uma timeline consolidada

nanojud timeline 0015020-23.2010.8.26.0053 \
  --source esaj \
  --source djen \
  --source datajud \
  --recent-first \
  --limit 20 \
  --out timeline.json

Executar pela instalação Python

python -m nanojud.cli search 0015020-23.2010.8.26.0053

Consulte o guia completo:

• Guia da CLI

---

Uso rápido em Python

from nanojud import api

numero = "0015020-23.2010.8.26.0053"

resumo = api.search_processo(numero)
print(resumo["classe"])

extrato = api.get_extrato(numero)
print(extrato["dados_basicos"])

comunicacoes = api.consultar_djen(numero)
print(len(comunicacoes))

datajud = api.consultar_datajud(numero)
print(datajud["classe"])

A API pública do DataJud/CNJ utiliza uma chave pública documentada pelo próprio CNJ.

A biblioteca inclui a chave vigente como fallback. Caso o CNJ altere essa chave, defina NANOJUD_DATAJUD_API_KEY ou informe api_key explicitamente. Também há compatibilidade com DATAJUD_API_KEY e CNJ_DATAJUD_API_KEY.

---

Cliente configurável

Para automações, jobs e integrações profissionais, use o cliente configurável:

from nanojud import NanoJudClient, NanoJudConfig

client = NanoJudClient(
    NanoJudConfig(
        timeout=20,
        rate_limit_interval=1.0,
        cache_enabled=True,
        cache_ttl_seconds=6 * 60 * 60,
    )
)

resumo = client.search_processo(
    "0015020-23.2010.8.26.0053"
)

print(resumo["classe"])

Consulte:

• Cliente configurável
• API Reference
• Contratos de dados
• Tratamento de erros

---

Servidor MCP local

O projeto inclui um servidor MCP local opcional por stdio.

Ele permite que agentes e clientes compatíveis consultem e estruturem dados judiciais sem a necessidade de expor um endpoint público.

Instalação

python -m pip install "nanojud[mcp]"

Execução direta

nanojud-mcp

Ou:

python -m nanojud.mcp_server

[!NOTE] Executar o servidor e configurá-lo em um cliente MCP são etapas diferentes.

O cliente deve registrar o comando do servidor e, preferencialmente, utilizar o executável Python localizado dentro do ambiente virtual .venv.

As ferramentas MCP disponíveis incluem:

• validação de números CNJ;
• extração de números CNJ contidos em textos;
• consulta ao eSAJ/TJSP;
• consulta ao DataJud/CNJ;
• consulta ao DJEN;
• geração de envelopes versionados;
• criação de timelines cronológicas;
• leitura em memória de documentos públicos candidatos, quando tecnicamente possível.

Documentos públicos

A ferramenta de leitura de documentos não salva PDFs em disco.

Quando a fonte fornece um PDF público, os bytes podem ser processados em memória e o texto extraído com pypdf.

Continuam fora do escopo:

• documentos protegidos por senha;
• documentos dependentes de captcha;
• processos sigilosos;
• conteúdo sujeito a autenticação;
• materiais com restrição de acesso.

Consulte:

• MCP local
• Aprendizados MCP

---

Exemplo de saída

{
  "numero": "0015020-23.2010.8.26.0053",
  "classe": "Mandado de Segurança Cível",
  "assunto": "Organização Político-administrativa / Administração Pública",
  "foro": "Foro Central - Fazenda Pública/Acidentes",
  "vara": "7ª Vara de Fazenda Pública",
  "ultima_movimentacao": "Extinta a Execução/Cumprimento da Sentença pela Satisfação da Obrigação",
  "ultima_data": "2026-07-19",
  "url": "https://esaj.tjsp.jus.br/cpopg/...",
  "status": "ok",
  "mensagem": "Processo consultado com sucesso"
}

[!CAUTION] Em demonstrações públicas, reduza os resultados e sanitize nomes, documentos, dados pessoais e trechos extensos.

Para trabalhos profissionais, consulte apenas processos escolhidos legitimamente pelo próprio usuário e confirme informações relevantes nas fontes oficiais.

---

Arquitetura

O fluxo principal do projeto é:

eSAJ/TJSP ─┐
DataJud/CNJ ├──> clientes e parsers ──> normalização ──> API / CLI / MCP
DJEN ──────┘                                  │
                                              └──> JSON / JSONL / CSV / SQLite

Principais módulos:

Módulo	Responsabilidade
nanojud.api	API pública de alto nível
nanojud.client	Cliente configurável
nanojud.config	Timeout, cache, rate limit e User-Agent
nanojud.cache	Cache local JSON opcional
nanojud.esaj	Consulta e parsing do eSAJ/TJSP
nanojud.datajud	Cliente DataJud/CNJ
nanojud.djen	Cliente de comunicações do DJEN
nanojud.extraction	Envelopes versionados de extração
nanojud.timeline	Timeline cronológica
nanojud.exports	Exportadores estruturados
nanojud.mcp_server	Servidor MCP local
nanojud.cli	Interface de linha de comando
nanojud.utils	Normalização e funções auxiliares

Consulte a documentação completa:

• Arquitetura
• Metodologia
• Reprodutibilidade

---

Qualidade e confiabilidade

O projeto utiliza práticas de engenharia voltadas a previsibilidade, manutenção e auditoria.

Controles automatizados

• CI em Python 3.10, 3.11, 3.12 e 3.13.
• Gate mínimo de cobertura de testes de 90%.
• CodeQL.
• Auditoria de dependências.
• Lint e formatação.
• Checagem de tipos com mypy.
• Build e validação de pacote.
• Testes sem rede com fixtures sanitizadas.
• Testes ao vivo opcionais, separados do CI.
• Releases versionadas com wheel, sdist e notas públicas.

Validação com cenários reais

O projeto também é validado em um corpus interno não publicado, utilizado para ampliar a cobertura de layouts e cenários reais sem expor HTMLs, PDFs, peças processuais ou estudos empresariais identificáveis.

Na validação mais recente, esse corpus continha:

• 17 processos públicos;
• 32 HTMLs reais;
• 10.310 movimentações parseadas;
• 42 partes principais;
• 2.451 partes em tabelas completas;
• 204 documentos públicos candidatos;
• 816 documentos identificados como restritos por senha.

Os documentos restritos foram identificados como indisponíveis. Seu conteúdo não integra o escopo público da biblioteca.

Consulte:

• Validação real
• Fixtures
• Modelo de ameaças
• Segurança

---

Limitações conhecidas

O projeto depende de fontes externas e, por isso, não pode garantir:

• disponibilidade contínua dos portais;
• estabilidade permanente do HTML;
• presença das mesmas informações em todas as fontes;
• cobertura idêntica entre tribunais;
• atualização simultânea dos dados;
• acesso a documentos protegidos ou sigilosos;
• validade jurídica de análises produzidas por agentes de IA.

Resultados incompletos ou divergentes devem ser apresentados de forma explícita, sem preenchimento inventado.

A ausência de uma informação em uma consulta não significa necessariamente que ela não exista na fonte oficial.

---

Uso responsável

Esta biblioteca deve ser utilizada apenas para consulta e organização de informações públicas ou legitimamente acessíveis pelo usuário.

O projeto não tem como objetivo:

• burlar autenticação;
• contornar captcha;
• acessar processos sigilosos;
• superar restrições técnicas;
• contornar limites definidos pelos tribunais;
• coletar dados pessoais sem finalidade legítima;
• substituir a conferência nas fontes oficiais;
• substituir orientação jurídica profissional.

Ao utilizar agentes de IA:

• diferencie dados obtidos das fontes e análises geradas pelo modelo;
• não trate inferências como fatos oficiais;
• não envie credenciais judiciais sem necessidade e autorização;
• evite expor dados pessoais em logs ou demonstrações;
• mantenha rastreabilidade da origem das informações;
• revise resultados antes de utilizá-los profissionalmente.

Leia antes de usar o projeto em rotinas recorrentes:

• Uso responsável
• LGPD
• Modelo de ameaças
• Governança

---

Status e roadmap

O projeto está em fase beta.

Já estão disponíveis:

• validação de número CNJ;
• API pública;
• CLI;
• cliente configurável;
• eSAJ/TJSP;
• DataJud/CNJ;
• DJEN;
• cache opcional;
• rate limit;
• contratos tipados;
• servidor MCP local;
• testes automatizados;
• build e releases.

Continuam em evolução:

• cobertura de cenários reais do eSAJ;
• exportadores analíticos;
• documentação publicada;
• estabilidade dos contratos durante o beta;
• ampliação dos exemplos profissionais.

Acompanhe:

• SPECS.md
• CHANGELOG.md
• Roadmap
• Releases

---

Desenvolvimento

Instalar dependências

python -m pip install -e ".[dev]"

Executar os testes

python -m pytest --cov

Executar verificações de qualidade

python -m ruff check src tests
python -m ruff format --check src tests
python -m mypy src

Testes ao vivo

Os testes ao vivo ficam desativados por padrão.

No Windows PowerShell:

$env:NANOJUD_RUN_LIVE = "1"
python -m pytest -m live

No Linux ou macOS:

export NANOJUD_RUN_LIVE=1
python -m pytest -m live

Antes de abrir um pull request

python -m pytest --cov
python -m ruff check src tests
python -m ruff format --check src tests
python -m mypy src
python -m build
python -m twine check dist/*

Consulte:

• Contribuindo
• Governança
• Segurança

---

Documentação

Para começar

• Quickstart
• Instalação com IA
• Para advogados
• Demonstração pública
• Exemplos seguros

Para utilizar e integrar

• MCP local
• Aprendizados MCP
• Cliente configurável
• API Reference
• Guia da CLI
• Contratos de dados
• Erros

Para entender o projeto

• Arquitetura
• Metodologia
• Reprodutibilidade
• Fixtures
• Validação real

Segurança, governança e responsabilidade

• Uso responsável
• LGPD
• Modelo de ameaças
• Governança
• Segurança

Evolução e contribuição

• Roadmap
• Contribuindo
• Changelog

---

Citação

Para uso acadêmico, técnico ou institucional, utilize o arquivo:

• CITATION.cff

---

Licença

Distribuído sob a licença MIT.

Consulte:

• LICENSE

---

Autor

Luciano Molero · lucmolero

Atuação na intersecção entre Direito, engenharia de software e automação jurídica.

• LinkedIn

---

Infraestrutura aberta para dados judiciais públicos, com rastreabilidade, responsabilidade e integração local.