O Valter e escrito em Python >=3.12 (producao usa a imagem Docker 3.12-slim). Python foi escolhido por tres razoes:
Ecossistema de ML — sentence-transformers, cross-encoders e bibliotecas de NLP para processamento de texto juridico sao nativos de Python. Nao existe alternativa viavel em outras linguagens para embeddings com Legal-BERTimbau.
Performance assincrona — Python 3.12 com asyncio, asyncpg e uvicorn entrega throughput suficiente para a carga esperada (usuarios concorrentes em digito unico durante a adocao inicial).
Tipagem rica — type hints com mypy --strict e validacao via Pydantic v2 capturam erros em tempo de desenvolvimento que, de outra forma, surgiriam como bugs em runtime no processamento de dados juridicos, onde corretude e primordial.
Todas as funcoes publicas exigem type hints. Isso e aplicado pelo mypy no CI e por convencao no CLAUDE.md.
FastAPI >=0.115.0 com Uvicorn >=0.34.0 serve como camada HTTP.
O FastAPI foi escolhido porque se alinha com todas as restricoes arquiteturais do projeto:
Async-first — toda operacao de I/O no Valter (queries de banco, busca vetorial, travessia de grafo, chamadas LLM) e async/await. O FastAPI e construido sobre a fundacao assincrona do Starlette.
Integracao com Pydantic v2 — validacao de request e response usa os mesmos modelos Pydantic que definem entidades de dominio, eliminando camadas de traducao.
Geracao automatica de OpenAPI — a REST API produz uma spec OpenAPI completa a partir das anotacoes de tipo, consumida por integradores externos.
DI via Depends() — o sistema de injecao de dependencia do FastAPI alimenta a arquitetura baseada em protocols. Stores sao conectados em api/deps.py e injetados nos route handlers sem que a camada core conheca implementacoes concretas.
O Valter usa quatro bancos de dados especializados, cada um escolhido para uma carga de trabalho especifica:
Store
Versao
Papel
Volume de Dados
Por Que Este Store
PostgreSQL
16 (Alpine)
Documentos, features, metadados do STJ, jobs de ingestao, estado de workflow, memoria de sessao, API keys, audit logs
~23.441 docs, 2.119 features, 810.225 registros de metadados
Integridade relacional para documentos juridicos, JSONB para metadados flexiveis, suporte async maduro via asyncpg, migracoes com Alembic
Qdrant
latest
Busca semantica vetorial
~3.673 vetores (768-dim, similaridade por cosseno)
Banco vetorial construido para esse fim, com filtragem por payload, similaridade por cosseno nativa e latencia sub-segundo para embeddings juridicos
Neo4j
5.x / Aura
Knowledge graph (ontologia FRBR)
~28.482 nos, ~207.163 arestas
Travessia nativa de grafo para queries multi-hop (cadeias de citacao, deteccao de divergencia, descoberta de comunidades), linguagem de query Cypher, opcao gerenciada Aura para producao
Redis
7 (Alpine)
Cache, rate limiting, fila de jobs
Efemero
Latencia sub-milissegundo para cache de queries (TTL 180s), TTL nativo para sliding windows de rate limiting, integracao ARQ para filas de jobs em background
