quota-sdk (Python)

SDK oficial em Python para telemetria, monitoramento de latência e consumo de tokens de modelos de IA (OpenAI, Anthropic, Gemini, Groq, etc.) para a plataforma Quota.

📦 Instalação

pip install quota-sdk

🚀 Uso Rápido (1 Linha de Configuração)

Basta chamar Quota.init() no início da sua aplicação (ex: main.py ou app.py).

from quota import Quota
from openai import OpenAI

# 1. Inicializa o monitoramento do Quota (uma única vez na inicialização)
Quota.init(api_key="qta_live_sua_chave_de_api")

# 2. Use qualquer SDK oficial de IA normalmente!
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Olá!"}]
)

print(response.choices[0].message.content)

🤖 Exemplos de Uso por Provedor em Python

Como o Quota.init() intercepta automaticamente chamadas via httpx e requests, você pode usar os SDKs oficiais das IAs diretamente:

1. OpenAI SDK (openai)

from quota import Quota
from openai import OpenAI

Quota.init(api_key="qta_live_sua_chave")

client = OpenAI()
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Resuma este artigo."}]
)

2. Anthropic SDK (anthropic)

from quota import Quota
import anthropic

Quota.init(api_key="qta_live_sua_chave")

client = anthropic.Anthropic()
message = client.messages.create(
    model="claude-3-5-sonnet-20241022",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Explique astrofísica."}]
)

3. Groq SDK (groq)

from quota import Quota
from groq import Groq

Quota.init(api_key="qta_live_sua_chave")

client = Groq()
response = client.chat.completions.create(
    model="llama-3.3-70b-versatile",
    messages=[{"role": "user", "content": "Olá Groq!"}]
)

4. Google Gemini (google-generativeai)

from quota import Quota
import google.generativeai as genai

Quota.init(api_key="qta_live_sua_chave")

genai.configure(api_key="SUA_CHAVE_GEMINI")
model = genai.GenerativeModel("gemini-1.5-pro")
response = model.generate_content("Escreva uma história curta.")

5. Mistral AI SDK (mistralai)

from quota import Quota
from mistralai import Mistral

Quota.init(api_key="qta_live_sua_chave")

client = Mistral(api_key="SUA_CHAVE_MISTRAL")
response = client.chat.complete(
    model="mistral-large-latest",
    messages=[{"role": "user", "content": "Olá Mistral!"}]
)

[!IMPORTANT] API Key do Quota (qta_live_...) é a única chave aceita para autenticação! Certifique-se de passar uma Quota API Key válida criada no painel da plataforma. Caso seja informada uma chave inexistente ou não cadastrada no ambiente, os dados de consumo e telemetria não poderão ser gravados (HTTP 401).

Os parâmetros de categorização (Projeto, Agente, Ambiente, Usuário Final, Tags e Grupo de Faturamento) são 100% opcionais.

🏷️ Passando Metadados de Observabilidade (Opcional)

Se você desejar categorizar e filtrar suas métricas no painel do Quota por Agente, Projeto, Equipe/Grupo, Usuário Final ou Tags, existem duas formas de enviar esses dados:

Opção A: Metadados Globais na Inicialização (Recomendado)

Defina os parâmetros diretamente no Quota.init(). Todas as chamadas de IA da sua aplicação herdarão essas informações automaticamente:

from quota import Quota

Quota.init(
    api_key="qta_live_sua_chave",
    project="portal-cliente",     # Projeto / Setor
    agent="bot-suporte",          # Agente / Assistente
    environment="production"      # Ambiente (production, staging, etc)
)

Opção B: Metadados Dinâmicos por Requisição (via Cabeçalhos)

Para informações dinâmicas que mudam a cada requisição (como o ID do usuário logado ou tags específicas), passe os cabeçalhos x-quota-* ou extra_headers:

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Qual o meu saldo?"}],
    extra_headers={
        "x-quota-user-id": "usr_991823",        # ID do usuário final
        "x-quota-tags": "vip,financeiro",        # Tags separadas por vírgula
        "x-quota-billing-group": "equipe-vendas" # Grupo de faturamento/equipe
    }
)

📋 Parâmetros e Cabeçalhos Suportados:

🛠️ Ambiente Local (Desenvolvimento)

Por padrão, a telemetria é enviada para a API em produção (https://quota-api.up.railway.app/collector). Para testar localmente contra o seu servidor de desenvolvimento:

Quota.init(
    api_key="qta_live_sua_chave_de_api",
    endpoint="http://localhost:3000/collector"  # Sobrescreve para ambiente local
)

Ou definindo a variável de ambiente no .env:

QUOTA_ENDPOINT=http://localhost:3000/collector

🔧 Configurando o Ambiente de Desenvolvimento Local (.venv)

Para rodar os exemplos locais e desenvolver a SDK Python:

1. Crie e ative um ambiente virtual (.venv):

   # Windows (PowerShell)
   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   
   # Linux / macOS
   python3 -m venv .venv
   source .venv/bin/activate
   

2. Instale as dependências em modo editável:

   pip install -e .
   

3. Resolução de Avisos do IDE / Type Checker (Pyright / Pylance): Se o seu editor (VS Code, Cursor, PyCharm) exibir avisos como Cannot find module httpx ou Cannot find module requests:

   • Selecione o interpretador Python do projeto apontando para .venv/Scripts/python.exe (Ctrl + Shift + P -> Python: Select Interpreter).
   • O projeto já inclui suporte a pyrightconfig.json e [tool.pyright] no pyproject.toml vinculados à pasta .venv.

📊 Rastreamento Manual (Quota.track_usage)

Para enviar eventos de uso customizados:

from quota import Quota

# 1. Inicializa com a sua Quota API Key
Quota.init(api_key="quota_live_sua_chave")

# 2. Envia o evento de telemetria manual
Quota.track_usage({
    "provider": "openai",
    "model": "gpt-4o",
    "promptTokens": 150,
    "completionTokens": 50,
    "latencyMs": 380,
    "metadata": {
        "project": "meu-projeto",
        "agent": "bot-atendimento",
        "externalUserId": "user_123"
    }
})

🛡️ Segurança & Performance

• Zero Latência (Thread Daemon Assíncrona): O envio de dados é processado em background sem travar o loop de execução principal.
• Fail-Safe: Falhas na rede de telemetria nunca afetam ou interrompem o funcionamento da sua chamada de IA.