Pular para o conteúdo
Floopy Docs

Como Funciona

Visao Geral da Arquitetura

O Floopy e uma AI Agent Optimization Platform. Sua superficie de roteamento — o componente gateway — e um proxy Rust de alta performance construido com Axum e Tokio. Ele fica entre sua aplicacao e os provedores de LLM, adicionando roteamento guiado por feedback, caching, rate limiting, seguranca, observabilidade e failover automatico — sem exigir nenhuma alteracao no codigo da sua aplicacao.

Voce aponta o baseURL do seu OpenAI SDK para https://api.floopy.ai/v1, e o gateway traduz as requisicoes para o formato correto do provedor, roteia de acordo com sua estrategia e registra tudo de forma assincrona.

graph LR
    App[Your Application] -->|OpenAI SDK| Gateway[Floopy Gateway]
    Gateway -->|Translated| OpenAI[OpenAI]
    Gateway -->|Translated| Anthropic[Anthropic]
    Gateway -->|Translated| Gemini[Google Gemini]
    Gateway -->|Translated| Groq[Groq]
    Gateway -->|Translated| Mistral[Mistral]
    Gateway -->|Translated| DeepSeek[DeepSeek]
    Gateway -.->|Async Logs| ClickHouse[(ClickHouse)]
    Gateway -.->|Cache| Redis[(Redis)]
    Gateway -.->|Vectors| Qdrant[(Qdrant)]

O gateway e stateless — todo estado compartilhado reside no Redis, ClickHouse e Qdrant. Isso significa que voce pode escalar horizontalmente executando multiplas instancias do gateway atras de um load balancer.

Pipeline de Requisicoes

Toda requisicao que entra no gateway Floopy passa por uma serie de estagios. Cada estagio pode interromper o pipeline e retornar uma resposta antecipadamente (cache hit, rate limit excedido, bloqueio do firewall), ou passar a requisicao para o proximo estagio.

graph TD
    A[Request Arrives] --> B[API Key Validation]
    B -->|Invalid| B1[401 Unauthorized]
    B -->|Valid| C[Rate Limit Check]
    C -->|Exceeded| C1[429 Too Many Requests]
    C -->|OK| D[Prompt Resolution]
    D --> E{Cache Enabled?}
    E -->|Yes| F[Exact Cache Check]
    F -->|Hit| F1[Return Cached Response]
    F -->|Miss| G[Semantic Cache Check]
    G -->|Hit| G1[Return Cached Response]
    G -->|Miss| H{Advanced Cache?}
    H -->|Yes| I[Advanced Cache Check]
    I -->|Hit| I1[Return Cached Response]
    I -->|Miss| J[LLM Firewall]
    H -->|No| J
    E -->|No| J
    J -->|Threat Detected| J1[400 Blocked]
    J -->|Safe| K[Routing Strategy]
    K --> L[Provider Dispatch]
    L -->|Success| M[Return Response]
    L -->|Failure| N{Fallback Available?}
    N -->|Yes| K
    N -->|No| N1[502 Bad Gateway]
    M --> O[Async: Log to ClickHouse]
    M --> P[Async: Store in Cache]

Validacao da API Key

O gateway extrai a API key do header Authorization: Bearer e a valida contra o Supabase (PostgreSQL). Para evitar uma ida ao banco de dados em cada requisicao, as chaves validadas e suas configuracoes associadas (organizacao, rate limits, regra de roteamento, feature flags) sao armazenadas em cache no Redis com invalidacao automatica quando as configuracoes mudam no dashboard.

Verificacao de Rate Limit

O rate limiting utiliza um algoritmo de janela deslizante implementado com operacoes atomicas no Redis (scripts Lua) para garantir consistencia mesmo ao executar multiplas instancias do gateway. Os limites sao configuraveis por API key e por organizacao. Quando o limite e excedido, o gateway retorna 429 Too Many Requests com um header Retry-After.

Resolucao de Prompt

Se a requisicao incluir um header floopy-prompt-id, o gateway resolve o prompt da sua biblioteca de prompts. Variaveis de template no prompt (usando a sintaxe {{variable}}) sao substituidas por valores do campo inputs no corpo da requisicao. Isso permite versionar e gerenciar prompts centralmente sem precisar reimplantar sua aplicacao.

Busca no Cache

Quando o caching esta habilitado, tres niveis sao verificados em sequencia: correspondencia exata no Redis, similaridade semantica no Qdrant e busca avancada por buckets. Cada nivel troca uma pequena quantidade de latencia adicional por uma cobertura de correspondencia mais ampla. Um hit em qualquer nivel retorna a resposta armazenada imediatamente — nenhum token e consumido e nenhuma chamada ao provedor e feita.

LLM Firewall

O firewall envia cada prompt a um LLM ajustado para seguranca (configurado por FIREWALL_MODEL) que devolve um veredito safe ou unsafe. Um cache de vereditos no Qdrant evita chamadas repetidas: quando o embedding bate com um veredito unsafe recente acima do limite configurado, o resultado em cache pula a chamada ao LLM. Se o veredito for unsafe, a requisicao e bloqueada com uma resposta 400.

Estrategia de Roteamento

O gateway seleciona um provedor com base na estrategia de roteamento configurada para a API key — fallback, round-robin, ponderada ou baseada em latencia. A estrategia determina qual provedor recebe a requisicao e o que acontece se esse provedor falhar. Consulte o guia de Roteamento para detalhes sobre cada estrategia.

Despacho para o Provedor

A requisicao e traduzida para o formato do provedor de destino e enviada. Cada conexao com provedor e protegida por um circuit breaker que rastreia taxas de falha. Se um provedor estiver falhando consistentemente, o circuit breaker abre e o gateway o ignora automaticamente, tentando o proximo provedor disponivel de acordo com a estrategia de roteamento.

Logging Assincrono

Apos a resposta ser enviada ao cliente, o gateway registra o par completo requisicao-resposta no ClickHouse de forma assincrona. O logging usa canais mpsc do Tokio para passar entradas de log para um worker em background que realiza insercoes em lote. Este design garante que o logging nunca bloqueia ou desacelera a resposta, e que a indisponibilidade do ClickHouse nao afeta a operacao do gateway.

O Que o Torna Rapido

O Floopy e projetado para overhead minimo de latencia. O gateway tipicamente adiciona menos de 5ms aos tempos de resposta dos provedores (excluindo cache hits, que ficam abaixo de 10ms no total).

  • Rust com Tokio — O gateway e totalmente assincrono. Toda operacao de I/O (consultas ao Redis, chamadas a provedores, logging) e nao-bloqueante, permitindo que uma unica instancia lide com milhares de requisicoes concorrentes.
  • Parsing zero-copy — Corpos de requisicao e resposta sao parseados com alocacao minima de memoria. Respostas grandes em streaming sao encaminhadas chunk por chunk sem armazenar o corpo completo em buffer.
  • Workers em background — Logging e armazenamento em cache acontecem de forma assincrona via canais tokio::sync::mpsc. Uma tarefa dedicada em background agrupa entradas de log e as insere no ClickHouse em lote, reduzindo o overhead de escrita.
  • Connection pooling — Conexoes Redis e conexoes HTTP com provedores sao mantidas em pool e reutilizadas entre requisicoes, evitando o overhead de estabelecer novas conexoes.
  • Reuso de embedding — O mesmo embedding calculado pela cache semantica de respostas e reutilizado pelo cache de vereditos do firewall, entao a requisicao nunca paga por dois embed calls.