Plataforma de Consulta Geoespacial em Linguagem Natural

Arquitetura

1. Pergunta

   linguagem natural, via app web ou SDK
2. LLM

   geração de SQL ciente do esquema
3. Validação

   esquemas permitidos · consulta restrita
4. PostGIS

   execução espacial
5. Resposta

   texto · gráfico · mapa · análise

O motor de consulta

O motor é um serviço FastAPI sobre PostgreSQL/PostGIS com datasets públicos em nível federal, estadual e municipal: financiamento de campanha, demografia censitária, registros e licenças de empresas, alvarás, criminalidade, tributos. A parte difícil de texto-para-SQL sobre dados assim não é o modelo; é dar ao modelo um esquema sobre o qual ele consiga raciocinar. Projetei a camada de dados: como jurisdições de níveis diferentes se relacionam, como geometrias são expostas e simplificadas, quais colunas carregam significado e como tudo isso é descrito para que o SQL gerado esteja correto de primeira com mais frequência. A correspondência aproximada de nomes usa similaridade por trigramas no banco, então lugares e candidatos com grafia errada ainda resolvem.

Uma pergunta vira um candidato a SQL, é validada e restringida (esquemas são permitidos por conversa, esquemas internos nunca podem ser consultados), executada e resumida de volta em linguagem. O backend de LLM é plugável: uma implementação com modelos da OpenAI via LangChain, outra com o framework de agentes do Google e Gemini, ambas atrás do mesmo contrato REST com histórico de conversa, de modo que comparar provedores foi configuração e não reescrita. Um modo analítico acrescenta um loop de agente limitado sobre dados recém-buscados, com timeouts por consulta, tetos de retentativa e um prazo de ponta a ponta, produzindo percentuais, rankings, gráficos e mapas.

O produto ao redor

Um motor de consulta não é um produto. Também liderei a plataforma que o transforma em um: uma API Express com PostgreSQL/PostGIS em camadas de controllers, services e repositories, uma aplicação web React para chat e gestão de conversas, SDKs em TypeScript e Python para acesso programático, organizações e equipes, chaves de API, medição de uso e rate limiting, um sistema de webhooks para notificações de eventos, cobrança por assinatura via Stripe e um site de documentação.

Infraestrutura

Tudo roda como stacks Docker Compose atrás do Traefik, com ambientes separados de desenvolvimento, beta e produção, atualização automática de imagens, uma camada de métricas e BI e o Sentinel vigiando o conjunto. Secrets são escopados por serviço e carregados de um único arquivo de ambiente para que a configuração continue legível conforme a stack cresce. Chamadas que levam dados de clientes a endpoints externos de modelos resolvem seus destinos em modo fail-closed: produção se recusa a rodar sem um endpoint explícito e nunca recorre a um público.