Valter is written in Python >=3.12 (production uses the 3.12-slim Docker image). Python was chosen for three reasons:
ML ecosystem — sentence-transformers, cross-encoders, and NLP libraries for legal text processing are Python-native. There is no viable alternative in other languages for Legal-BERTimbau embeddings.
Async performance — Python 3.12 with asyncio, asyncpg, and uvicorn delivers throughput sufficient for the expected load (single-digit concurrent users during early adoption).
Rich typing — type hints with mypy --strict and Pydantic v2 validation catch errors at development time that would otherwise surface as runtime bugs in legal data processing, where correctness is paramount.
All public functions require type hints. This is enforced by mypy in CI and by convention in CLAUDE.md.
FastAPI >=0.115.0 with Uvicorn >=0.34.0 serves as the HTTP layer.
FastAPI was chosen because it aligns with every architectural constraint in the project:
Async-first — every I/O operation in Valter (database queries, vector search, graph traversal, LLM calls) is async/await. FastAPI is built on Starlette’s async foundation.
Pydantic v2 integration — request and response validation uses the same Pydantic models that define domain entities, eliminating translation layers.
OpenAPI auto-generation — the REST API produces a complete OpenAPI spec from type annotations, which is consumed by external integrators.
Depends() DI — FastAPI’s dependency injection system powers the protocol-based architecture. Stores are wired in api/deps.py and injected into route handlers without the core layer knowing about concrete implementations.
~23,441 docs, 2,119 features, 810,225 metadata records
Relational integrity for legal documents, JSONB for flexible metadata, mature async support via asyncpg, Alembic migrations
Qdrant
latest
Semantic vector search
~3,673 vectors (768-dim, cosine similarity)
Purpose-built vector database with payload filtering, native cosine similarity, and sub-second query latency for legal embeddings
Neo4j
5.x / Aura
Knowledge graph (FRBR ontology)
~28,482 nodes, ~207,163 edges
Native graph traversal for multi-hop queries (citation chains, divergence detection, community discovery), Cypher query language, managed Aura option for production
Redis
7 (Alpine)
Cache, rate limiting, job queue
Ephemeral
Sub-millisecond latency for query cache (180s TTL), native TTL for rate limiting sliding windows, ARQ integration for background job queues
