Recebi sua solicitação e estou começando a trabalhar nela.

Vou ajustar o documento arquitetural para refletir a nova restrição de tribunais e a integração com LLMs gratuitos. Primeiro, deixe-me pesquisar informações atualizadas sobre as APIs gratuitas disponíveis.

PROJETO LEXNOVA: DOCUMENTO DE ARQUITETURA DE SISTEMA

1. ESCOPO FUNCIONAL EXTRAÍDO (Feature Mapping)

1.1 Funcionalidades Primárias Identificadas

O sistema LexNova deve prover as seguintes capacidades fundamentais para pesquisa jurisprudencial assistida por inteligência artificial, com foco nos quatro tribunais especificados:

Busca Inteligente em Linguagem Natural: Capacidade de receber consultas em linguagem natural (descrições coloquiais de casos jurídicos) e converter automaticamente em parâmetros de busca otimizados para cada tribunal. O sistema deve identificar sinônimos jurídicos, termos técnicos equivalentes e adaptar a consulta aos padrões de indexação específicos de cada base de dados. A descrição "responsabilidade do Estado por ato administrativo lesivo" deve automaticamente buscar decisões relacionadas a "responsabilidade civil do Estado", "indenização por dano", "ato omissivo do poder público" e variações equivalentes. Esta funcionalidade é essencial para eliminar a barreira de conhecimento terminológico que impede advogados e operadores jurídicos de encontrarem precedentes relevantes.

Upload de Petição para Análise Contextual: Funcionalidade para receber documentos em formato PDF, DOCX ou texto e extrair automaticamente os temas jurídicos relevantes. O sistema deve identificar os argumentos centrais, normas aplicáveis e questões jurídicas discutidas, utilizando-os como base para busca de precedentes aplicáveis. Esta funcionalidade otimiza o workflow do operador jurídico, que não precisa reformular manualmente seu caso em termos de busca.

Cobertura Multi-Tribunal Restrita: Capacidade de realizar buscas simultâneas em múltiplas cortes, permitindo comparação de entendimentos jurisprudenciais. Cobertura obrigatória dos tribunais de maior relevância para o contexto nordestino e federal: Supremo Tribunal Federal (STF), Superior Tribunal de Justiça (STJ), Tribunal Regional Federal da 5ª Região (TRF-5) e Tribunal de Justiça do Estado do Ceará (TJ-CE). Suporte para seleção simultânea de até três tribunais na mesma pesquisa, permitindo comparações estratégicas entre tribunais superiores e instâncias regionais.

Classificação de Relevância: Sistema de etiquetagem de resultados em categorias de relevância (muito relevante, relevante, pouco relevante, irrelevante) para priorização do trabalho de análise pelo operador jurídico. A classificação deve ser determinística, baseada em métricas objetivas de similaridade semântica e correspondência temática. Esta funcionalidade é crítica para reduzir o tempo de triagem manual de resultados.

Interface de Busca (/search): Interface web dedicada para pesquisa por termos jurídicos, retornando jurisprudências reais filtradas de acordo com os tribunais selecionados. Permite navegação por páginas de resultados e refinamento de filtros por data, tipo de decisão e órgão julgador.

Busca por Temas (/search/results/:job_id): Após envio de petição, o sistema deve extrair temas automaticamente e apresentar resultados segmentados por tema, com opção de visualização de todos os resultados ou filtro por tema específico. Em desktop, temas exibidos em coluna lateral; em dispositivos móveis (abaixo de 1024px), seleção por menu dropdown.

1.2 Funcionalidades de Integração e API

API REST Pública: Endpoint base para acesso programático a jurisprudências dos tribunais brasileiros. Autenticação por Bearer token com prefixo identificador. Planos gratuitos com limites diários generosos e planos subscriber com limites expandidos. A API deve ser documentada com especificação OpenAPI 3.1 para facilitar integração por ferramentas de IA e sistemas terceiros.

Endpoints de API:

• GET /api/v1/courts — Listagem de tribunais disponíveis com contagem de decisões indexadas
• GET /api/v1/courts/:court/decisions — Busca por texto com suporte a filtros de data (publicação e julgamento), paginação e operadores de busca avançados
• GET /api/v1/courts/:court/decisions/lookup — Consulta por número de processo com retorno de decisão completa
• POST /api/v1/documents/analyze — Upload de petição para análise automática de temas
• GET /api/v1/documents/analyze/:job_id — Verificação de status e recuperação de resultados de análise
• POST /api/v1/search/semantic — Busca semântica avançada utilizando vetorização
• POST /api/v1/search/rag-context — Obtenção de contexto formatado para sistemas RAG
• Sistema de rate limiting com headers X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset

Integração com Agentes de IA: Capacidade de integração nativa comLLMs através de múltiplos mecanismos: servidor MCP (Model Context Protocol) para Claude e clientes compatíveis, especificação OpenAPI 3.1 para Custom GPTs, e skill específica para Claude Code com ferramentas de list_courts, search_decisions e lookup_decision.

Suporte a LLMs Gratuitos: Arquitetura diseñada para integração com múltiplos provedores de APIs gratuitas de LLMs, incluindo Google Gemini, Groq, Mistral AI, Cerebras, NVIDIA NeMo, OpenRouter e provedores asiáticos como Zhipu AI (GLM). O sistema deve implementar um gateway de roteamento inteligente que permita failover automático entre provedores quando um atingir limites de uso.

1.3 Funcionalidades de Apresentação e UX

Landing Page (/): Interface inicial minimalista com slogan, campo de busca em destaque e opção de upload de petição. Design focado em simplicidade e eficiência operacional, com chamada clara para as principais ações do sistema.

Responsividade: Interface adaptativa que modifica layout de apresentação de temas baseado em breakpoint de 1024px, utilizando coluna lateral em desktop e menu dropdown em mobile. A experiência mobile é prioritária para advogados em deslocamento.

Preservação de Autenticidade: Sistema projetado para exibir únicamente jurisprudências autênticas obtidas de fontes oficiais, sem geração de texto intermediário por IA. Cada resultado deve exibir tribunal, número do processo, data de julgamento, ementa completa e link direto para o portal oficial do tribunal. O operador jurídico pode verificar a fonte original antes de qualquer citação.

---

2. ENGENHARIA REVERSA LÓGICA (System Internals)

2.1 Pipeline de Ingestão de Jurisprudências

Arquitetura de Coleta de Dados:

O sistema implementa uma arquitetura de crawler distribuído para extração de dados dos repositórios oficiais dos tribunais. O pipeline de ingestão foi projetado considerando as especificidades estruturais de cada tribunal brasileiro, que mantêm portais de jurisprudência com tecnologias e formatos distintos.

Fontes de Dados Oficiais e suas Características:

Supremo Tribunal Federal (STF): O STF mantém o portal stf.jus.br com sistema de busca jurisprudencial que expõe resultados em formato HTML dinâmico. A estrutura utiliza JavaScript para renderização, exigindo abordagem de crawling com renderização browser-side ou parseamento de APIs internas não documentadas. O tribunal publica em média 150 a 200 decisões por dia útil, com concentração em questões constitucionais de alta relevância.

Superior Tribunal de Justiça (STJ): O STJ disponibilza o portal stj.jus.br com sistema de busca mais estruturado, incluindo índice por assunto (CDU jurídico) e possibilidade de filtros avançados. A página de resultados apresenta formato mais estável, facilitando a extração automatizada. O STJ é o tribunal de maior volume, com aproximadamente 500 a 800 decisões publicadas diariamente.

Tribunal Regional Federal da 5ª Região (TRF-5): Com jurisdição sobre os estados do Nordeste (incluindo Ceará), o TRF-5 mantém portal próprio com estrutura similar aos tribunais estaduais. O volume de decisões é moderado, aproximadamente 100 a 200 diárias, concentradas em questões federais como direito previdenciário, tributário e administrativo.

Tribunal de Justiça do Estado do Ceará (TJ-CE): O TJ-CE disponibilza seu portal de jurisprudência com indexação por classe processual e assunto. A estrutura HTML apresenta variações frequentes que exigem manutenção ativa dos crawlers. O volume é aproximadamente 200 a 400 decisões por dia útil.

Crawlers Específicos por Tribunal: Implementação de agentes de extração dedicados para cada tribunal, encapsulando a lógica de navegação, autenticação (quando necessária) e parsing de HTML. Cada crawler é versionado conforme as alterações nos portais de origem, permitindo rollbacks quando alterações estruturais quebrarem a extração. A arquitetura permite adição de novos tribunais sem modificar o core do sistema.

Estrutura de Dados Extraída: Para cada decisão jurisprudencial, o sistema extrai e normaliza os seguintes campos: número do processo (formato CNJ com e sem pontuação), tipo de documento (acórdão, decisão monocrática, decisão interlocutória), relator (nome completo e cargo), órgão julgador (câmara, turma ou seção), data de publicação no DJ (Diário da Justiça), data de julgamento, ementa completa (texto resumido redigido pelo redator), texto integral quando disponível, link para inteiro teor no portal oficial, e identificadores internos do tribunal.

Estratégia de Atualização: O pipeline opera em três modos complementares: full scan para sincronização completa executado semanalmente para garantir integridade, incremental para captura de novas decisões baseado em datas de publicação, e sob demanda para tribunais específicos com alto volume de novidade. A frequência de atualização é calibrada por tribunal considerando o volume de novas decisões publicadas diariamente, sendo mais frequente para STJ (a cada 2 horas) e menos frequente para tribunais estaduais (a cada 6 horas).

Resiliência e Monitoramento: Implementação de mecanismos de retry exponencial para falhas transitórias, detecção de CAPTCHAs e bloqueios de IP com escalonamento para tor network ou residential proxies, alertas para alterações estruturais nos portais de origem através de testes de regressão automatizados, e dashboards de monitoramento de saúde do pipeline de ingestão com métricas de latência, taxa de sucesso e volume processado.

2.2 Motor de Busca Semântica e NLP

Arquitetura de Indexação Vetorial:

O sistema combina buscas em texto completo com indexação semântica baseada em vetores densos para garantir tanto precisão quanto recall nas pesquisas. A arquitetura foi projetada paraoperar com custos mínimos, aproveitando provedores de APIs gratuitas e modelos open-source.

Pipeline de Vetorização: Cada ementa e trecho relevante de decisão passa por um processo de vetorização utilizando modelos de embedding otimizados para português brasileiro. A escolha primária recai sobre modelos da família BERTimbau (portuguese-bert) ou sentence-transformers multilingual, que oferecem bom desempenho em textos jurídicos sem necessitar de fine-tuning específico. O processo de vetorização é executado em batch para otimizar custos, processando documentos em grupos de 100 durante janelas de menor utilização.

Banco de Dados Vetorial: Seleção de solução open-source para economia de custos, com preferência por Milvus ou Qdrant rodando em infraestrutura própria. Alternativamente, pode-se utilizar ChromaDB para ambientes de desenvolvimento e Scale-out para produção. A seleção considera escalabilidade horizontal, suporte a filtros híbridos (vetor mais metadados), latência de consulta inferior a 100ms para 95% das requisições, e custo operacional reduzido.

Busca Híbrida: Combinação de busca semântica (vector similarity search) com busca por palavra-chave utilizando BM25 ou FTS5. A consulta do usuário passa por um processo de expansão semântica que gera múltiplas representações da mesma intenção, buscando tanto correspondências exatas quanto semânticamente similares. O sistema gera de 3 a 5 variações da query original utilizando o LLM configurado, enriquecendo os resultados.

Mapeamento de Sinônimos Jurídicos: Construção de um léxico especializado que mapeia termos coloquiais para terminologia jurídica oficial. Este léxico inclui variações regionais nordestinas, gírias jurídicas, abreviações comuns, correspondências entre português arcaico e contemporâneo utilizado nas decisões, e mapeamento de princípios constitucionais para seus desdobramentos jurisprudenciais.

Filtros e Refinamento: Suporte a filtros por tribunal, intervalo de datas (publicação e julgamento), tipo de decisão, órgão julgador específico, e relatoria. A arquitetura permite que filtros sejam aplicados como pré-filtros no banco vetorial para garantir eficiência computacional, reduzindo o espaço de busca antes da comparação de similaridade.

Classificação de Relevância: Implementação de um sistema de scoring que combina múltiplos sinais: similaridade vetorial (40% do peso), correspondência de termos exatos (30% do peso), recência da decisão (20% do peso), e frequência de citação quando disponível (10% do peso). O score final é discretizado em categorias através de thresholds calibrados: muito relevante (score superior a 0.85), relevante (0.65 a 0.85), pouco relevante (0.40 a 0.65), e irrelevante (inferior a 0.40).

2.3 Integração com LLMs

Arquitetura de Gateway para LLMs Gratuitos:

O sistema implementa uma arquitetura de gateway inteligente que abstrai a complexidade de múltiplos provedores de LLM, permitindo failover automático e otimização de custos. O gateway é baseado no padrão RelayFreeLLM, adaptado para as necessidades específicas de processamento de linguagem natural jurídica.

Provedores Suportados e suas Características:

Estratégia de Roteamento: O gateway implementa roteamento baseado em intent, selecionando automaticamente o provedor mais adequado para cada tipo de tarefa. Consultas simples de classificação usam modelos menores (Groq llama-3.1-8b), enquanto análises complexas de similaridade usam modelos maiores (Cerebras qwen-3-235b). O sistema mantém sessão affinity para requests consecutivos, melhorando performance através de context caching.

Fallback e Failover: Quando um provedor atinge limites de rate limiting, o gateway automaticamente roteia para o próximo provedor disponível na lista de preferência. Cada requisição inclui retry logic com backoff exponencial, tentando até 3 provedores antes de retornar erro. Métricas de disponibilidade são coletadas em tempo real para ajustar dinamicamente a lista de preferência.

Integração como Camada de RAG: O sistema funciona como fonte de contexto verificável para LLMs, evitando alucinações em respostas jurídicas. Quando um agente de IA consulta o LexNova, recebe trechos verbatim de decisões reais com citeção completa, impossibilitando a geração de precedentes fictícios.

API de Contexto para RAG: Endpoint especializado que formata jurisprudências como contexto estruturado para prompts de LLMs. A resposta inclui texto original extraído verbatim das decisões, metadados de origem (tribunal, número, data), e URL oficial para verificação. O formato é otimizado para incluir o máximo de informação relevante dentro do limite de context window do modelo destino.

---

3. ARQUITETURA TÉCNICA PROPOSTA (Tech Stack & Blueprint)

3.1 Visão Arquitetural de Alto Nível

A arquitetura do sistema LexNova segue um padrão de microsserviços com processamento assíncrono, dividido em camadas distintas de responsabilidade. O design prioriza custo-benefício, utilizando tecnologias open-source e provedores de APIs gratuitas sempre que possível.

┌─────────────────────────────────────────────────────────────────────────┐
│                           CAMADA DE APRESENTAÇÃO                          │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │   Frontend Web  │  │    API Gateway   │  │   Integrações Externas  │  │
│  │  (Next.js 14)   │  │    (Kong/Traefik)│  │   (MCP, OpenAI, Claude)│  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           CAMADA DE SERVIÇOS                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │  Search Service │  │  Document Service│  │   LLM Gateway Service  │  │
│  │  - Busca FTS     │  │  - Upload/Parse │  │   - Multi-provider     │  │
│  │  - Reranking     │  │  - OCR           │  │   - Failover           │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │  Auth Service   │  │  Queue Service  │  │   Crawler Service      │  │
│  │  - JWT/OAuth     │  │  - Task Queue   │  │   - Schedulers          │  │
│  │  - Rate Limit   │  │  - Celery       │  │   - Extractors          │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │  Embedding Svc  │  │  NLP Service    │  │   Notification Service  │  │
│  │  - Vectorization │  │  - NER           │  │   - Alerts              │  │
│  │  - Batch Process │  │  - Classification│  │   - Webhooks           │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           CAMADA DE DADOS                                │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │  PostgreSQL     │  │  Vector Store   │  │   Object Storage       │  │
│  │  - Metadados    │  │  (Milvus/Qdrant)│  │   (MinIO/S3)           │  │
│  │  - Usuários     │  │  - Embeddings    │  │   - PDFs Originais     │  │
│  │  - Cache         │  │  - Busca Semântica│ │   - Documentos Upl.  │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │  Redis          │  │  SQLite FTS5    │  │   Elasticsearch        │  │
│  │  - Cache        │  │  - Busca Texto  │  │   - Logs              │  │
│  │  - Sessions      │  │  - Fallback     │  │   - Analytics         │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                           CAMADA DE INFRAESTRUTURA                       │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────────────┐  │
│  │  Docker/K8s     │  │  CI/CD (GitHub)  │  │   Monitoring           │  │
│  │  - Containers    │  │  - Automated     │  │   (Prometheus/Grafana) │  │
│  │  - Orchestration │  │    Deployments  │  │   - Alerts             │  │
│  └─────────────────┘  └─────────────────┘  └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

3.2 Stack Tecnológica Detalhada

Frontend:

• Framework: Next.js 14 com App Router para SSR/SSG otimizado
• Linguagem: TypeScript para type safety completo
• UI Components: Shadcn/ui como base acessível e customizável
• Estado: TanStack Query para server-state e cache automático
• Estilização: Tailwind CSS com design system customizado em português
• PDF Viewer: react-pdf ou pdf.js para visualização de decisões
• Testes: Playwright para E2E, Jest para unit tests

Backend API:

• Framework: FastAPI (Python 3.11+) para alta performance async e documentação automática OpenAPI
• API Gateway: Kong ou Traefik para rate limiting, autenticação centralizada, e routing
• Validação: Pydantic v2 para schemas de request/response com validação rigorosa
• ORM: SQLAlchemy 2.0 com async support para PostgreSQL
• Autenticação: JWT com refresh tokens, suporte a API keys para integração
• Documentação: OpenAPI 3.1 com ReDoc e Swagger UI

Processamento Assíncrono:

• Message Broker: RabbitMQ ou Redis Streams para filas de processamento
• Workers: Celery com Redis como broker para tasks assíncronas (crawlers, embeddings)
• Schedule: Celery Beat para jobs recorrentes (crawlers noturnos, updates incrementais)
• Background Tasks: FastAPI BackgroundTasks para operações curtas assíncronas

Bancos de Dados:

• Relacional: PostgreSQL 15+ para dados transacionais, metadados de usuários e decisões
• Vetorial: Qdrant (preferido por ser Rust-based com excelente performance) ou Milvus
• Cache: Redis 7+ para sessões, cache de consultas frequentes, rate limiting counters
• Busca Texto: SQLite FTS5 para fallback e ambientes lean, Elasticsearch opcional para scale
• Object Storage: MinIO (S3-compatible, self-hosted) para storage de PDFs e documentos

Machine Learning / NLP:

• Embedding Model: paraphrase-multilingual-MiniLM-L12-v2 (sentence-transformers) para embeddings densos
• NER e Classificação: spaCy com modelo pt_core_news_lg para reconhecimento de entidades jurídicas
• OCR: Tesseract 5 com treinamento adicional para manuscrito jurídico ou PaddleOCR
• PDF Parsing: pdfplumber para extração de texto estruturado, PyMuPDF para manipulação
• LLM Gateway: Integração com múltiplos provedores via SDKs oficiais (Groq, Cerebras, Mistral)

Infraestrutura:

• Containerização: Docker com Docker Compose para desenvolvimento, imagens multi-stage para produção
• Orquestração: Kubernetes via EKS/GKE ou Docker Swarm para produção simplificada
• IaC: Terraform ou Pulumi para provisionamento de infraestrutura cloud
• CI/CD: GitHub Actions com stages de test, build, deploy automatizados
• Monitoring: Prometheus + Grafana para métricas, Loki para logs, alerting via Alertmanager
• Observabilidade: OpenTelemetry para tracing distribuído,Jaeger ou Tempo para visualização

3.3 Fluxo de Dados Entre Componentes

Fluxo de Busca por Linguagem Natural:

1. Usuário submete consulta em linguagem natural via interface web ou API
2. API Gateway autentica requisição via JWT ou API key e aplica rate limiting
3. Search Service recebe consulta e inicia pipeline assíncrono
4. NLP Service processa texto: tokenização, detecção de idioma, extração de entidades jurídicas
5. LLM Gateway expande a consulta gerando 3-5 variações semânticas usando modelo gratuito configurado
6. Query Expansion Service mapeia sinônimos jurídicos do léxico interno
7. Vector Store recebe query vectorizada (usando sentence-transformers) e busca top-100 por similaridade
8. PostgreSQL busca metadados complementares (datas, tribunal, tipo de decisão, relatoria)
9. Reranking Service aplica modelo de reordenação combinando scores de similaridade, BM25, e recência
10. Resultados são classificados em categorias de relevância (muito relevante, relevante, pouco relevante)
11. Resposta formatada é retornada ao cliente com links para fontes oficiais e snippets destacados

Fluxo de Upload de Petição:

1. Usuário faz upload de documento (PDF, DOCX, TXT) através de interface drag-and-drop
2. Document Service recebe arquivo, persiste em Object Storage, e inicia processamento assíncrono
3. OCR Service extrai texto se necessário (PDFs scaneados) usando Tesseract ou PaddleOCR
4. NLP Service identifica temas jurídicos usando spaCy NER e classificador treinado para topik jurídicos
5. Para cada tema identificado (máximo 10), Search Service executa busca independente
6. Job Service cria identificador único (UUID) e retorna job_id para tracking
7. Resultados agregados são armazenados no PostgreSQL e associados ao job
8. Interface exibe temas extraídos com ícones representativos e resultados segmentados por tema
9. Cliente pode visualizar todos os resultados ou filtrar por tema específico

Fluxo de Ingestão de Jurisprudência (Crawler):

1. Scheduler inicia job de crawling baseado em configuração temporal (STF/STJ: 2h, TJ-CE/TRF-5: 6h)
2. Crawler Service identifica tribunais a processar e janelas temporais a buscar
3. Para cada decisão encontrada, Extractor parseia HTML e normaliza数据结构
4. Decisões validadas são inseridas em PostgreSQL (metadados) e Object Storage (PDF/HTML)
5. Embedding Service gera vetores de 384 dimensões para cada ementa em batch
6. Vector Store é atualizado com novos embeddings e filtros de tribunal/data
7. FTS Index é atualizado para busca keyword-based
8. Métricas de crawling (volume, latência, erros) são registradas para monitoramento
9. Alertas são disparados se taxa de erro exceder threshold de 5%

---

4. ESPECIFICAÇÃO DE API PARA INTEGRAÇÃO

4.1 Endpoints Principais

A API do sistema LexNova segue convenções RESTful com versionamento semântico (v1) e resposta em JSON. Todos os endpoints requerem autenticação via Bearer token. A especificação completa está disponível em OpenAPI 3.1.

Base URL: https://api.lexnova.com.br/v1

Autenticação: Bearer token no header Authorization com prefixo lex_

Endpoints Disponíveis:

Listar Tribunais Disponíveis

GET /courts

Retorna lista dos tribunais atualmente indexados com estatísticas de decisões.

Response Schema:

{
  "data": [
    {
      "id": "stf",
      "name": "Supremo Tribunal Federal",
      "abbreviation": "STF",
      "jurisdiction": "Nacional - Constitucional",
      "decisions_count": 156842,
      "last_updated": "2026-04-14T02:30:00Z"
    },
    {
      "id": "stj",
      "name": "Superior Tribunal de Justiça",
      "abbreviation": "STJ",
      "jurisdiction": "Nacional - Infraconstitucional",
      "decisions_count": 892547,
      "last_updated": "2026-04-14T04:15:00Z"
    },
    {
      "id": "trf5",
      "name": "Tribunal Regional Federal da 5ª Região",
      "abbreviation": "TRF-5",
      "jurisdiction": "Nordeste - Federal",
      "decisions_count": 324891,
      "last_updated": "2026-04-13T22:00:00Z"
    },
    {
      "id": "tjce",
      "name": "Tribunal de Justiça do Estado do Ceará",
      "abbreviation": "TJ-CE",
      "jurisdiction": "Ceará - Estadual",
      "decisions_count": 567234,
      "last_updated": "2026-04-13T20:45:00Z"
    }
  ],
  "meta": {
    "total": 4,
    "api_version": "1.0.0"
  }
}

Buscar Decisões por Texto

GET /courts/{court_id}/decisions

Parâmetros de Query:

Response Schema:

{
  "data": [
    {
      "process_number": "REsp 1.847.234-CE",
      "process_type": "Acórdão",
      "rapporteur": "Min. Herman Benjamin",
      "adjudicating_body": "2ª Turma",
      "publication_date": "2024-08-22",
      "trial_date": "2024-08-20",
      "excerpt": "RESPONSABILIDADE CIVIL. Contrato bancário. Animais de estimação...",
      "full_text_available": true,
      "url": "https://www.stj.jus.br/processo/...,
      "relevance_score": "high",
      "themes": ["responsabilidade civil", "contrato bancário"],
      "cited_by_count": 45
    }
  ],
  "meta": {
    "total": 2847,
    "page": 0,
    "per_page": 20,
    "total_pages": 143
  },
  "links": {
    "self": "/courts/stj/decisions?q=responsabilidade+civil&page=0",
    "next": "/courts/stj/decisions?q=responsabilidade+civil&page=1",
    "last": "/courts/stj/decisions?q=responsabilidade+civil&page=142"
  }
}

Consultar Decisão por Número

GET /courts/{court_id}/decisions/lookup

Parâmetros de Query:

Response Schema:

{
  "data": {
    "process_number": "REsp 1.847.234-CE",
    "process_type": "Acórdão",
    "rapporteur": "Min. Herman Benjamin",
    "adjudicating_body": "2ª Turma",
    "publication_date": "2024-08-22",
    "trial_date": "2024-08-20",
    "summary": "RECURSO ESPECIAL. Responsabilidade civil. Contrato bancário...",
    "full_text": "...",
    "full_text_available": true,
    "url": "https://www.stj.jus.br/processo/...,
    "court": "stj",
    "embedding_id": "emb_abc123xyz",
    "cited_by_count": 45,
    "keywords": ["responsabilidade civil", "contrato", "bancário"]
  }
}

Upload de Petição para Análise

POST /documents/analyze

Body (multipart/form-data):

Response Schema:

{
  "data": {
    "job_id": "job_xyz789abc",
    "status": "processing",
    "document_id": "doc_abc123",
    "document_name": "peticao_inicial.pdf",
    "estimated_completion": "2026-04-14T05:15:00Z",
    "created_at": "2026-04-14T05:10:00Z"
  },
  "links": {
    "status": "/documents/analyze/job_xyz789abc",
    "cancel": "/documents/analyze/job_xyz789abc/cancel"
  }
}

Verificar Status e Resultados de Análise

GET /documents/analyze/{job_id}

Response Schema (completo):

{
  "data": {
    "job_id": "job_xyz789abc",
    "status": "completed",
    "document_id": "doc_abc123",
    "document_name": "peticao_inicial.pdf",
    "created_at": "2026-04-14T05:10:00Z",
    "started_at": "2026-04-14T05:10:05Z",
    "completed_at": "2026-04-14T05:12:30Z",
    "processing_time_seconds": 145,
    "llm_provider_used": "groq",
    "themes": [
      {
        "id": "theme_001",
        "name": "Responsabilidade Civil do Estado",
        "confidence": 0.94,
        "results_count": 15,
        "results": [...]
      },
      {
        "id": "theme_002",
        "name": "Ato Administrativo",
        "confidence": 0.87,
        "results_count": 12,
        "results": [...]
      },
      {
        "id": "theme_003",
        "name": "Danos Morais",
        "confidence": 0.82,
        "results_count": 8,
        "results": [...]
      }
    ],
    "all_results": {
      "data": [...],
      "meta": {...}
    },
    "statistics": {
      "total_results": 35,
      "by_court": {
        "stf": 5,
        "stj": 18,
        "trf5": 7,
        "tjce": 5
      },
      "by_relevance": {
        "high": 12,
        "medium": 15,
        "low": 8
      }
    }
  }
}

Busca Semântica Avançada (com Expansão de Query)

POST /search/semantic

Body:

{
  "query": "responsabilidade do estado por falha na prestação de serviço público de saúde",
  "courts": ["stf", "stj", "trf5", "tjce"],
  "max_results": 20,
  "expand_query": true,
  "llm_provider": "auto",
  "include_summary": true,
  "date_range": {
    "from": "2019-01-01",
    "to": "2026-04-14"
  },
  "filters": {
    "process_type": "Acórdão",
    "min_cited_by": 5
  }
}

Obter Contexto para RAG (Retrieval-Augmented Generation)

POST /search/rag-context

Body:

{
  "query": "Responsabilidade civil de hospital público por erro médico",
  "max_context_length": 6000,
  "courts": ["stf", "stj", "trf5"],
  "include_citations": true,
  "format": "markdown"
}

Response Schema:

{
  "data": {
    "context": "# Contexto Jurisprudencial\n\nCom base nas jurisprudências consultadas em 14 de abril de 2026:\n\n## STF - Precedente Relevante\n\n**REsp 1.234.567** - 2ª Turma - Publ. 15/03/2024\n\n> \"A responsabilidade civil do Estado por ato médico hospitalpúblico segue a teoria da responsabilidade objetiva..."\n\nFonte: https://stf.jus.br/processo/...\n\n## STJ - Tese Consolidada\n\n**REsp 1.847.234-CE** - 2ª Turma - Publ. 22/08/2024\n\n> \"É objetiva a responsabilidade civil do hospital público..."\n\nFonte: https://www.stj.jus.br/processo/...",
    "sources": [
      {
        "process_number": "REsp 1.234.567",
        "court": "stf",
        "rapporteur": "Min. Rosa Weber",
        "publication_date": "2024-03-15",
        "url": "https://stf.jus.br/processo/...",
        "relevant_excerpt": "A responsabilidade civil do Estado..."
      }
    ],
    "metadata": {
      "total_sources": 5,
      "query_expansion_used": true,
      "llm_provider": "groq",
      "generated_at": "2026-04-14T05:30:00Z"
    }
  }
}

4.2 Códigos de Erro e Rate Limiting

Códigos de Status HTTP:

Formato de Erro:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Limite diário de requisições atingido para o plano Free.",
    "status": 429,
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset_at": "2026-04-15T00:00:00Z",
      "upgrade_url": "/pricing"
    }
  }
}

Rate Limits por Plano:

Headers de Rate Limiting:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1744652400
X-RateLimit-Policy: 100;w=86400

4.3 SDKs e Integração com Agentes de IA

SDKs Oficiais:

• Python: pip install lexnova-sdk — Suporte completo com async/await
• JavaScript/TypeScript: npm install @lexnova/sdk — Compatível com Node.js e browsers
• Go: go get github.com/lexnova/sdk-go — Gopher-friendly com context support

Exemplo de Uso (Python):

import asyncio
from lexnova import AsyncLexNovaClient

async def main():
    client = AsyncLexNovaClient(api_key="lex_sua_chave")
    
    # Listar tribunais
    courts = await client.courts.list()
    print(f"Tribunais disponíveis: {len(courts.data)}")
    
    # Busca semântica
    results = await client.search.semantic(
        query="responsabilidade civil de hospital público",
        courts=["stf", "stj", "trf5"],
        max_results=10
    )
    
    for decision in results.data:
        print(f"[{decision.relevance_score}] {decision.process_number}")
        print(f"  Ementa: {decision.excerpt[:100]}...")
        print(f"  Fonte: {decision.url}")
    
    # Upload e análise de petição
    job = await client.documents.analyze(
        file_path="peticao.pdf",
        courts=["stj", "trf5"],
        llm_provider="groq"
    )
    
    # Aguardar conclusão
    result = await client.documents.wait_for_completion(job.job_id)
    print(f"Análise completa! {len(result.themes)} temas identificados.")
    
    await client.close()

asyncio.run(main())

Integração com Claude Code (MCP):

O servidor MCP permite que o Claude Code busque jurisprudências diretamente durante sessões de trabalho. Configuração em .claude/mcp.json:

{
  "mcpServers": {
    "lexnova": {
      "command": "npx",
      "args": ["-y", "@lexnova/mcp-server"],
      "env": {
        "LEXNOVA_API_KEY": "lex_sua_chave"
      }
    }
  }
}

Ferramentas Disponíveis no MCP:

• list_courts — Lista tribunais disponíveis com contagens
• search_decisions — Busca decisões por texto com filtros
• lookup_decision — Consulta decisão específica por número
• analyze_document — Analisa petição e retorna temas
• get_rag_context — Gera contexto formatado para RAG

---

5. PLANO DE IMPLEMENTAÇÃO E ROADMAP

5.1 Fases de Desenvolvimento

Fase 1 — Foundation (Meses 1-2):

• Configuração de infraestrutura cloud (VPS ou cloud provider escolhido)
• Implementação do pipeline de crawler para STF e STJ (tribunais com APIs mais estruturadas)
• Setup de PostgreSQL, Redis, MinIO e Qdrant
• Desenvolvimento da API REST core (autenticação JWT, CRUD básico, rate limiting)
• Interface web MVP com busca por termo simples
• Testes de integração com provedores LLM gratuitos (Groq, Cerebras)

Fase 2 — Search Intelligence (Meses 3-4):

• Implementação de busca semântica com Vector Store (Qdrant)
• Desenvolvimento do módulo de expansão de consultas via LLM
• Sistema de classificação de relevância multi-sinal
• Integração de NLP (spaCy) para extração de entidades jurídicas
• Upload de documentos com extração automática de temas
• Interface de resultados com filtros e paginação

Fase 3 — Expansão de Tribunais (Meses 5-6):

• Crawler para TRF-5 e TJ-CE com adaptadores específicos
• Sincronização inicial de histórico de decisões (últimos 5 anos)
• Testes de carga e otimização de performance
• Dashboard administrativo para monitoramento de crawlers

Fase 4 — Integrações e Production Hardening (Meses 7-8):

• Servidor MCP para Claude Code e clientes compatíveis
• SDKs oficiais para Python e JavaScript
• Especificação OpenAPI 3.1 completa
• Failover automático entre provedores LLM
• Documentação para desenvolvedores
• Testes E2E com Playwright -部署 e monitoramento de produção

5.2 Estimativa de Custos Operacionais (Infraestrutura Própria)

5.3 Métricas de Qualidade

• CQ1: Mapeamento funcional completo para os 4 tribunais especificados (STF, STJ, TRF-5, TJ-CE)
• CQ2: Arquitetura de backend plausible utilizando tecnologias open-source e provedores gratuitos
• CQ3: Sistema LexNova projetado como entidade independente com identidade e roadmap próprios
• CQ4: Nível de detalhe técnico adequado para equipe de engenharia iniciar desenvolvimento