CausaGanha

CausaGanha é uma camada pública e verificável para acompanhar o rastro de processos judiciais brasileiros. O projeto preserva o que foi publicado, reconcilia fontes oficiais e mantém explícito de onde veio cada fato — inclusive quando uma fonte não tem aquele processo, está indisponível ou representa apenas um snapshot no tempo.

O site permite consultar um processo por número CNJ, pesquisar publicações por texto/OAB/parte e explorar a cobertura do arquivo. Os mesmos dados também podem ser reutilizados diretamente via Internet Archive + DuckDB ou consultados por assistentes através do servidor MCP read-only.

Site público: franklinbaldo.github.io/causaganha

Estratégia do acervo

Antes das interfaces, a regra do acervo: inventariar o que existe no Internet Archive e disponibilizar os dados preservados sem esperar completude nacional. ZIPs disponíveis devem avançar para Parquet, catálogo e busca por tribunal/partição. A falta de um ZIP indica uma lacuna a investigar; não prova ausência de publicação. Registros de verificação preservados explicam ausências e falhas, sem bloquear o acervo existente.

Essa estratégia está integrada ao pipeline por tribunal/ano. A ADR 0012 define fontes de verdade e critérios de entrega; o guia operacional registra a ativação, validações e limites. Integração do código não implica que todo o backlog já esteja pesquisável.

O produto em três perguntas

Um processo deixa rastros diferentes em fontes diferentes. O CausaGanha evita fundi-los numa resposta opaca:

Pergunta	Evidência	Papel no CausaGanha
O que foi publicado e preservado?	arquivo	DJEN preservado no Internet Archive, Parquets e catálogo reproduzível
Onde o processo está / o que aconteceu na linha processual?	estado	metadata e movimentação processual, especialmente DataJud
O que a decisão ou documento efetivamente diz?	teor	documentos de jurisprudência e acórdãos quando a fonte correspondente está disponível

Arquivo, estado e teor podem divergir no tempo. Um documento local antigo não prova que o processo parou; um movimento chamado “Sentença” não prova qual foi o fundamento da sentença. A proveniência continua visível para que o consumidor saiba exatamente o que cada fonte sustenta.

Quatro fontes, quatro papéis

O knowledge corpus do projeto modela quatro fontes oficiais e os pipelines que as consomem:

Fonte	O que ela traz	Papel principal
DJEN (CNJ)	comunicações judiciais diárias	preservação, busca de publicações, cobertura histórica
TJRO JURIS	decisões e documentos de jurisprudência do TJRO	teor estruturado e corpus de decisões
STJ Acórdãos	acórdãos do Superior Tribunal de Justiça	teor/metadata de decisões do STJ e reconciliação processual
DataJud (CNJ)	capa, classe, assuntos, órgão, grau, datas e movimentos	estado processual, enriquecimento e facetas

A existência de um pipeline não implica cobertura completa nem maturidade operacional idêntica. Cada superfície deve expor freshness, cobertura e limitações de sua própria fonte em vez de transformar integração em promessa de completude.

Três interfaces do mesmo sistema

1. Site

A home aceita dois jobs principais:

• um CNJ leva ao dossiê reconciliado em /processo;
• texto livre, OAB ou parte leva à busca de publicações do DJEN.

O dossiê por CNJ usa indice_processual.parquet como índice fino: ele descobre quais fontes têm registro para o processo e consulta os Parquets de origem sem copiar todo o conteúdo para uma tabela monolítica.

2. Dados públicos

O produto suportado continua tendo como fundação o arquivo público. ZIPs originais, manifestos e derivados ficam no Internet Archive. O catálogo público é distribuído como SQL auditável, não como um banco DuckDB opaco:

curl -L https://archive.org/download/causaganha-catalog/catalog.sql -o catalog.sql
duckdb causaganha.duckdb < catalog.sql
duckdb causaganha.duckdb "SELECT * FROM comunicacoes LIMIT 100;"

Artefatos centrais:

• sync-manifest.parquet — fonte de verdade da sincronização DJEN;
• catalog.sql — contrato reconstruível das views públicas;
• indice_processual.parquet — índice fino que liga CNJs às fontes/arquivos de origem;
• Parquets específicos de DJEN, JURIS, STJ e DataJud conforme disponibilidade de cada pipeline.

3. Agentes / MCP

causaganha-mcp expõe uma superfície read-only para assistentes. Hoje são dez tools:

Tools de produto (respondem ARQUIVO/ESTADO/TEOR sem exigir conhecimento de schemas ou pipelines):

• processo_consultar — ARQUIVO: publicações preservadas, decisões/documentos e metadados do snapshot para um CNJ;
• publicacoes_buscar — ARQUIVO: pesquisa publicações preservadas por processo, OAB, parte, advogado, texto, tribunal ou período;
• processo_estado — ESTADO: movimentos, graus e último marco de um CNJ no DataJud oficial;
• decisoes_buscar — TEOR: busca temática por decisão, acórdão, ementa ou tese.

Tools operacionais/diagnóstico (saúde e freshness dos coletores, nunca pré-requisito para uma consulta de produto):

• causaganha_status
• djen_backup_status
• tjro_juris_status
• stj_acordaos_status
• datajud_status
• datajud_facetas

As seis tools operacionais leem estado local dos pipelines ou, no caso de datajud_facetas, agregados da API pública do DataJud. Nenhuma tool dispara ingestão, upload ou backfill.

Hosts que suportam MCP local por stdio podem iniciar o servidor com:

{
  "mcpServers": {
    "causaganha": {
      "command": "uv",
      "args": ["run", "--directory", "/caminho/para/causaganha", "causaganha-mcp"]
    }
  }
}

Estado do transporte HTTP, em três partes:

• stdio local: suportado hoje via causaganha-mcp (acima);
• artefato HTTP/deploy: já existe no repositório em deployment/mcp/ (causaganha-mcp-http, Dockerfile e cloudbuild.yaml), com limites de timeout e concorrência documentados ali;
• URL pública estável: ainda bloqueada — o rollout e a divulgação de uma URL dependem da prova de smoke descrita em #950.

Fundação: o arquivo DJEN

O DJEN (Diário de Justiça Eletrônico Nacional) publica comunicações judiciais com efeitos jurídicos e existência frequentemente efêmera na superfície de origem. O CausaGanha preserva os ZIPs no Internet Archive e mantém um manifesto auditável por par (tribunal, data).

O motor canônico fica em src/djen_backup/ e opera com pools independentes de check, download e upload. O estado é um log append-only de segmentos compactados em sync-manifest.parquet; o projeto não trata um código HTTP isolado como veredito de disponibilidade.

Invariantes importantes

• 403 do DJEN não significa ausência; pode ser bloqueio/rate-limit e deve continuar desconhecido/retriável.
• 200 também não basta para dizer disponível: o DJEN pode responder {"status": "Sem comunicações"} sem URL de download.
• o arquivo distingue ausência confirmada de erro transitório, nunca verificado e pendência real.
• uploads do Internet Archive usam httpx e headers x-archive-meta-*; não boto3.

Workflows principais

Workflow	Trigger	Papel
collect-zips.yml	a cada 20 min	consultar DJEN, baixar e arquivar ZIPs
upload-backlog.yml	a cada 15 min	drenar ZIPs já confirmados
render-manifest-parquet.yml	a cada 30 min	compactar o event log no manifesto base
consolidate-parquet.yml	diário	ZIPs → Parquet
update-catalog.yml	após consolidação	atualizar catálogo/índice e contratos derivados
deploy-web.yml	push / catálogo	renderizar dados e publicar o site
canary.yml	diário	provar o caminho DJEN/deploy contra o sistema real

Arquitetura

flowchart LR
    DJEN[DJEN] --> ARCHIVE[Arquivo DJEN / IA]
    JURIS[TJRO JURIS] --> SOURCES[Parquets por fonte]
    STJ[STJ Acórdãos] --> SOURCES
    DATAJUD[DataJud] --> SOURCES
    ARCHIVE --> SOURCES
    SOURCES --> INDEX[indice_processual.parquet]
    INDEX --> DOSSIER[Dossiê por CNJ]
    SOURCES --> CATALOG[catalog.sql / DuckDB]
    ARCHIVE --> STATUS[coverage / freshness]
    DOSSIER --> WEB[Site]
    CATALOG --> WEB
    STATUS --> WEB
    INDEX --> MCP[causaganha-mcp]
    SOURCES --> MCP

Há duas superfícies de runtime principais:

• backend Python/CLIs em src/;
• frontend Astro + Svelte em web/.

Metadados estáveis de produto (fontes e pipelines) vivem no bundle OKF de knowledge/; contratos físicos continuam no código, Parquet e Zod. O OKF participa do causaganha_status, mas não substitui schema registry nem contratos de dados.

CLIs

Entry points registrados em pyproject.toml:

Comando	Papel
djen-backup	sincronização/arquivo DJEN
tjro-juris	coleta de jurisprudência TJRO
stj-acordaos	coleta de acórdãos STJ
datajud	enriquecimento processual DataJud
causaganha-mcp	servidor MCP read-only

Exemplos:

uv run djen-backup --workers 8
uv run djen-backup check --workers 8
uv run djen-backup upload --workers 4
uv run --env-file .env datajud enrich --tribunal tjro --skip-upload

A consolidação Parquet é um module CLI: python -m causaganha.consolidate.

Frontend e contratos de consulta

O frontend usa Astro 7, Svelte 5, DuckDB WASM, Vitest e Zod.

As necessidades de dados do site são declaradas em web/src/queries/*.qmd. Cada contrato define output/formato e uma consulta SQL. scripts/render_queries.py materializa JSON em web/public/data/, e os payloads renderizados são validados contra o registry Zod do frontend em CI.

Para adicionar uma view:

1. criar web/src/queries/minha_view.qmd;
2. adicionar o schema/registry em web/src/lib/data/contracts.ts;
3. executar uv run python scripts/render_queries.py.

Veja web/src/queries/README.md para o contrato completo.

Lab experimental

Classificação de resultados, embeddings, segmentação de decisões, treinamento de modelos e outros experimentos ficam sob a fronteira Lab. Eles podem usar o arquivo público como matéria-prima, mas não definem a confiabilidade do produto suportado e não devem ser apresentados como fatos equivalentes aos registros oficiais.

Notebooks são autorados em marimo (notebooks/*.py) e exportados para .ipynb em CI. A governança da camada analítica está em docs/GOVERNANCE.md.

Desenvolvimento

Pré-requisitos: Python 3.12+, uv e Node.js 22+.

uv sync --dev
cp .env.example .env
uv run pre-commit install
uv run pytest -q

Gates usuais:

uv run ruff format --check
uv run ruff check
uvx vulture src/ scripts/ vulture_whitelist.py --min-confidence 100
cd web && npm ci && npm run lint && npm test && npm run build

Estrutura do repositório

knowledge/               fatos estáveis de fontes/pipelines (OKF)
src/causaganha/          domínio, consolidação e processo como recurso
src/causaganha_mcp/      superfície MCP
src/djen_backup/         motor de sincronização DJEN
src/datajud/              client/service/archive DataJud
src/tjro_juris/           pipeline JURIS
src/stj_acordaos/         pipeline STJ
web/                     site Astro + Svelte
scripts/                 pipelines e operações auxiliares
notebooks/               Lab / marimo + exports
.github/workflows/       CI/CD e jobs de dados

Documentação

• docs/PRODUCT.md — modelo de produto, proveniência e fronteiras
• CONTRIBUTING.md — setup e regras de contribuição
• FRONTEND.md — arquitetura/design do frontend
• web/src/queries/README.md — contratos .qmd
• docs/GOVERNANCE.md — preservação, correção/restrição e licenciamento
• docs/SERVICE_OBJECTIVES.md — objetivos operacionais e canário

Se documentação e código divergirem, o código/workflow é a evidência operacional e a documentação deve ser corrigida na mesma mudança.

Licença

• Código: MIT.
• Dados derivados pelo projeto: direitos que pertençam ao CausaGanha são disponibilizados sob CC0 1.0.

Textos de atos oficiais têm regime próprio (Lei 9.610/98, art. 8º, IV), sem prejuízo de direitos de terceiros eventualmente reproduzidos, privacidade ou proteção de dados. A política completa de preservação, correção e restrição está em docs/GOVERNANCE.md.