Metadata-Version: 2.5
Name: smart-router-llm
Version: 1.0.2
Summary: Proxy inteligente entre APIs compatíveis com OpenAI e múltiplos provedores de LLM, com roteamento por complexidade e compressão de contexto.
License: Proprietary
Requires-Python: >=3.11
Requires-Dist: accelerate==1.14.0
Requires-Dist: aiohappyeyeballs==2.7.1
Requires-Dist: aiohttp==3.14.3
Requires-Dist: aiosignal==1.4.0
Requires-Dist: annotated-doc==0.0.5
Requires-Dist: annotated-types==0.8.0
Requires-Dist: anyio==4.14.2
Requires-Dist: apscheduler==3.11.3
Requires-Dist: attrs==26.1.0
Requires-Dist: backoff==2.2.1
Requires-Dist: certifi==2026.7.22
Requires-Dist: cffi==2.1.1
Requires-Dist: charset-normalizer==3.4.9
Requires-Dist: click==8.4.2
Requires-Dist: croniter==6.2.4
Requires-Dist: cryptography==43.0.3
Requires-Dist: defusedxml==0.7.1
Requires-Dist: dicttoxml==1.7.16
Requires-Dist: distro==1.9.0
Requires-Dist: dnspython==2.8.0
Requires-Dist: email-validator==2.3.0
Requires-Dist: faiss-cpu==1.15.0
Requires-Dist: fastapi-sso==0.16.0
Requires-Dist: fastapi==0.115.6
Requires-Dist: filelock==3.32.2
Requires-Dist: frozenlist==1.8.0
Requires-Dist: fsspec==2026.7.0
Requires-Dist: gunicorn==22.0.0
Requires-Dist: h11==0.16.0
Requires-Dist: hf-xet==1.6.0
Requires-Dist: httpcore==1.0.9
Requires-Dist: httpx==0.28.1
Requires-Dist: huggingface-hub==1.26.0
Requires-Dist: idna==3.18
Requires-Dist: importlib-metadata==9.0.0
Requires-Dist: jinja2==3.1.6
Requires-Dist: jiter==0.16.0
Requires-Dist: joblib==1.5.3
Requires-Dist: jsonschema-specifications==2025.9.1
Requires-Dist: jsonschema==4.26.0
Requires-Dist: litellm==1.61.20
Requires-Dist: llmlingua==0.2.2
Requires-Dist: markdown-it-py==4.2.0
Requires-Dist: markupsafe==3.0.3
Requires-Dist: mdurl==0.1.2
Requires-Dist: mpmath==1.3.0
Requires-Dist: multidict==6.7.1
Requires-Dist: narwhals==2.24.0
Requires-Dist: networkx==3.6.1
Requires-Dist: nltk==3.10.2
Requires-Dist: numpy==2.5.1
Requires-Dist: oauthlib==3.3.1
Requires-Dist: ollama==0.6.2
Requires-Dist: openai==2.53.0
Requires-Dist: orjson==3.11.9
Requires-Dist: packaging==26.3
Requires-Dist: propcache==0.5.2
Requires-Dist: psutil==7.2.2
Requires-Dist: pycparser==3.0
Requires-Dist: pydantic-core==2.33.0
Requires-Dist: pydantic==2.11.0
Requires-Dist: pygments==2.20.0
Requires-Dist: pyjwt==2.13.0
Requires-Dist: pynacl==1.6.2
Requires-Dist: python-dateutil==2.9.0.post0
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: python-multipart==0.0.18
Requires-Dist: pyyaml==6.0.3
Requires-Dist: redis==8.1.0
Requires-Dist: referencing==0.37.0
Requires-Dist: regex==2026.7.19
Requires-Dist: requests==2.34.2
Requires-Dist: rich==15.0.0
Requires-Dist: rpds-py==2026.6.3
Requires-Dist: rq==2.10.0
Requires-Dist: safetensors==0.8.0
Requires-Dist: scikit-learn==1.9.0
Requires-Dist: scipy==1.18.0
Requires-Dist: sentence-transformers==5.7.0
Requires-Dist: setuptools==83.0.0
Requires-Dist: shellingham==1.5.4
Requires-Dist: six==1.17.0
Requires-Dist: sniffio==1.3.1
Requires-Dist: starlette==0.41.3
Requires-Dist: sympy==1.14.0
Requires-Dist: threadpoolctl==3.6.0
Requires-Dist: tiktoken==0.13.0
Requires-Dist: tokenizers==0.22.2
Requires-Dist: torch==2.13.0
Requires-Dist: tqdm==4.70.0
Requires-Dist: transformers==5.14.1
Requires-Dist: truststore==0.10.4
Requires-Dist: typer==0.27.1
Requires-Dist: typing-extensions==4.16.0
Requires-Dist: typing-inspection==0.4.2
Requires-Dist: tzlocal==5.4.4
Requires-Dist: urllib3==2.7.0
Requires-Dist: uvicorn==0.29.0
Requires-Dist: uvloop==0.21.0
Requires-Dist: xmltodict==1.0.4
Requires-Dist: yarl==1.24.5
Requires-Dist: zipp==4.1.0
Description-Content-Type: text/markdown

# SMART ROUTER LLM GATEWAY

---

## 1. Descrição do Projeto

O **Smart Router LLM Gateway** é uma solução avançada de infraestrutura para IA Generativa que atua como um proxy inteligente entre aplicações e múltiplos provedores de LLM. Construído sobre o **LiteLLM**, o sistema intercepta requisições compatíveis com a API da OpenAI e utiliza um pipeline de decisão em 4 camadas para rotear a consulta ao modelo mais eficiente em termos de custo-performance.

O diferencial deste gateway reside na sua capacidade de classificar a complexidade da consulta em tempo real, aplicando técnicas de compressão de prompt (**LLMLingua**) e truncamento inteligente de contexto (**Tiktoken**) antes de despachar a chamada para o provedor final através do gateway corporativo.

---

## 2. Arquitetura do Sistema

A arquitetura é baseada em microserviços orquestrados via Docker, garantindo isolamento e escalabilidade dos componentes de cache, classificação local e proxy.

### 2.1. Visão Geral dos Componentes

```mermaid
graph TD
    subgraph "Client Layer"
        App[Aplicação Cliente]
    end

    subgraph "Smart Router Gateway (Docker)"
        Proxy[LiteLLM Proxy :4000]
        Router[SmartRouterV2 Callback]

        subgraph "Optimization Engine"
            Lingua[LLMLingua - Compression]
            Tik[Tiktoken - Truncation]
        end

        subgraph "Local Intelligence"
            Ollama[Ollama :11434 - Qwen2.5]
            FAISS[FAISS Vector DB - Semantic]
        end

        subgraph "Persistence"
            Redis[(Redis :6379)]
        end
    end

    subgraph "External Providers"
        Flow[LLM Gateway Corporativo]
        Models[Mistral / Gemini / Claude]
    end

    App -->|OpenAI SDK| Proxy
    Proxy <--> Router
    Router <--> Redis
    Router <--> FAISS
    Router <--> Ollama
    Router --> Lingua
    Lingua --> Tik
    Tik --> Flow
    Flow --> Models
```

---

## 3. Pipeline de Roteamento (4 Camadas)

O sistema utiliza uma estratégia de "fail-fast" e "cache-first" para determinar o destino de cada prompt.

### 3.1. Fluxo de Decisão

```mermaid
flowchart TD
    Start([Recebe Requisição]) --> L1{L1: Redis Cache}
    L1 -- "Hit (Hash Match)" --> Return[Retorna Resposta Cacheada]
    L1 -- "Miss" --> L2{L2: Semantic Router}

    L2 -- "Score > 0.75" --> SetTier[Define Tier: Simple/Std/Complex]
    L2 -- "Score < 0.75" --> L3{L3: LLM Router}

    L3 -- "Ollama Classification" --> SetTier
    L3 -- "Fail/Timeout" --> L4{L4: Regex & Heuristics}

    L4 -- "Pattern Match" --> SetTier
    L4 -- "Default" --> Default[Tier: Standard]

    SetTier --> Optimize[Otimização de Tokens]
    Optimize --> Dispatch[Executa Chamada LiteLLM]
    Dispatch --> CacheResult[Salva no Redis]
    CacheResult --> End([Resposta ao Cliente])
```

### 3.2. Detalhamento das Camadas

1.  **Camada 1 - Redis Cache:** Normaliza o prompt (lowercase, strip) e gera um hash SHA-256. Verifica se existe uma decisão de rota (`route:{hash}`) válida por 24h ou uma resposta completa (`resp:{hash}`) válida por 1h.
2.  **Camada 2 - Semantic Router:** Utiliza `all-MiniLM-L6-v2` para gerar embeddings e compara via similaridade de cosseno (FAISS) contra 30 prompts de referência (10 por tier) em PT-BR e EN.
3.  **Camada 3 - LLM Router:** Consulta um modelo local `qwen2.5:1.5b` via Ollama para análise lógica da complexidade, esperando um JSON com `tier` e `confidence`.
4.  **Camada 4 - Regex Fallback:** Analisa palavras-chave técnicas (ex: "deadlock", "architecture" para complexo; "crud", "getter" para simples) e heurística de contagem de palavras (<15 simples, >80 complexo).

---

## 4. Modelos e Fallbacks

O mapeamento de tiers garante que tarefas simples não consumam créditos de modelos de alta performance.

| Tier | Modelo Principal | Fallback 1 | Fallback 2 |
| :--- | :--- | :--- | :--- |
| **Simple** | `mistral-small-2503` | `claude-4-5-haiku` | `gemini-2.5-flash` |
| **Standard** | `gemini-2.5-flash` | `gemini-3.1-pro` | `claude-4-5-haiku` |
| **Complex** | `gemini-3.1-pro` | `gemini-2.5-flash` | `claude-4-5-haiku` |

---

## 5. Otimização de Tokens

Para reduzir custos e latência, o gateway aplica duas técnicas antes do roteamento final:

*   **LLMLingua-2:** Prompts de sistema com mais de 500 caracteres são comprimidos usando o modelo `microsoft/llmlingua-2-bert-base-multilingual-cased-meetingbank` com uma taxa de 0.5.
*   **Tiktoken Truncation:** Garante que o contexto enviado não ultrapasse 4.000 tokens, mantendo as mensagens mais recentes e preservando a mensagem de sistema original.

---

## 6. Configuração e Instalação

### 6.0. Instalação via pip (alternativa ao Docker)

```bash
pip install smart-router-llm
```

Redis e Ollama continuam sendo responsabilidade sua instalar e rodar — o pacote só se conecta a eles, não os empacota nem gerencia.

```bash
# 1. Configure as variáveis de ambiente (mesmas da seção 6.2)
export LLM_GATEWAY_API_KEY=seu_token_aqui
export LLM_GATEWAY_BASE_URL=sua_url_aqui

# 2. Verifica se Redis e Ollama estão acessíveis
smart-router check

# 3. Baixa os modelos Ollama necessários e cria o modelo classificador
smart-router pull-models

# 4. Valida conectividade com o gateway corporativo
smart-router validate

# 5. Sobe o proxy (porta 4000)
smart-router serve
```

### 6.1. Pré-requisitos

*   Docker & Docker Compose
*   Python 3.12+ (para execução local)
*   Chave de API do gateway LLM corporativo

### 6.2. Variáveis de Ambiente (.env)

Crie um arquivo `.env` na raiz do projeto:

```bash
LLM_GATEWAY_API_KEY=seu_token_aqui
LLM_GATEWAY_BASE_URL=sua_url_aqui
REDIS_HOST=redis
REDIS_PORT=6379
OLLAMA_HOST=http://ollama:11434
OLLAMA_MODEL=qwen2.5:1.5b
LITELLM_MASTER_KEY=sk-litellm-local
```

### 6.3. Comandos do Makefile

O projeto utiliza um `Makefile` para simplificar a gestão:

*   `make .venv`: Cria o ambiente virtual com Python 3.12.
*   `make install`: Instala as dependências no ambiente virtual.
*   `make up`: Sobe toda a infraestrutura (Redis, Ollama, LiteLLM).
*   `make down`: Encerra todos os serviços.
*   `make logs`: Acompanha os logs do proxy em tempo real.
*   `make validate`: Valida a conectividade com os modelos do gateway.
*   `make clean`: Limpa caches, logs e arquivos temporários.

---

## 7. Estrutura do Projeto

```text
.
├── app/
│   ├── cache/          # Singleton Redis e lógica de hashing
│   ├── optimization/   # Implementação LLMLingua e Tiktoken
│   ├── router/         # Lógica das 4 camadas de roteamento
│   ├── utils/          # Sanitização e extração de prompts
│   └── main.py         # Ponto de entrada LiteLLM Proxy
├── ollama/
│   └── Modelfile       # Configuração do modelo de classificação
├── scripts/            # Scripts de inicialização e validação
├── config.yaml         # Definição de modelos e fallbacks LiteLLM
├── docker-compose.yml  # Orquestração de serviços
├── Makefile            # Atalhos de automação
└── venv/               # Ambiente virtual
```

---

## 8. Utilização da API

O gateway expõe um endpoint compatível com OpenAI na porta `4000`.

**Exemplo de requisição via cURL:**

```bash
curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-litellm-local" \
  -d '{
    "model": "smart-router",
    "messages": [
      {"role": "system", "content": "Você é um arquiteto de software."},
      {"role": "user", "content": "Explique a diferença entre consistência eventual e forte em sistemas distribuídos."}
    ]
  }'
```

Nota: Ao enviar para o modelo "smart-router", o sistema automaticamente reescreverá o campo "model" para o tier adequado (ex: gemini-3.1-pro) antes de processar.

---

## 9. Monitoramento e Estatísticas

O sistema mantém métricas de performance no Redis sob a hash `router:stats`. É possível monitorar:

*   `total_requests`: Total de chamadas processadas.
*   `cache_hits`: Quantidade de respostas servidas pelo cache.
*   `routing_decisions`: Distribuição de roteamento por tier (simple/standard/complex).

*Documento elaborado em 06 de agosto de 2026. As informações contidas são de responsabilidade do solicitante.*