SDK Python (floopy-sdk)

Visao Geral

O floopy-sdk e o SDK Python oficial do Floopy. Ele encapsula o pacote oficial openai e o aponta para o gateway do Floopy, entao chat.completions e embeddings continuam sendo um substituto direto 1:1, enquanto os recursos exclusivos do Floopy (auditoria, experimentos, constraints, exportacao de decisoes, feedback, roteamento em modo dry-run, sessoes) ganham metodos tipados de primeira classe.

Prefere a abordagem sem SDK? A pagina Python mostra como usar o SDK OpenAI puro com os headers do Floopy. Use o floopy-sdk quando voce tambem quiser os recursos tipados do Floopy e um unico cliente para ambos.

Sao fornecidos um cliente sincrono Floopy e um assincrono AsyncFloopy. Requer Python >= 3.10.

Instalacao

pip install floopy-sdk

uv add floopy-sdk

poetry add floopy-sdk

import os
from floopy import Floopy

with Floopy(api_key=os.environ["FLOOPY_API_KEY"]) as floopy:
    response = floopy.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Ola do Floopy!"}],
    )
    print(response.choices[0].message.content)

import asyncio, os
from floopy import AsyncFloopy

async def main() -> None:
    async with AsyncFloopy(api_key=os.environ["FLOOPY_API_KEY"]) as floopy:
        r = await floopy.chat.completions.create(
            model="gpt-4o",
            messages=[{"role": "user", "content": "Ola!"}],
        )
        print(r.choices[0].message.content)

asyncio.run(main())

Defina FLOOPY_API_KEY no seu ambiente. Voce pode criar uma no dashboard.

Migrando do `openai`

from openai import OpenAI
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
from floopy import Floopy
client = Floopy(api_key=os.environ["FLOOPY_API_KEY"])

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

client.chat, client.embeddings e client.models retornam os recursos do openai por baixo, entao os tipos e o comportamento em runtime sao identicos. Atualizacoes de seguranca do SDK OpenAI chegam ate voce com pip install -U, sem forks ou divergencia de versao.

Opcoes do Floopy

As FloopyOptions mapeiam para headers Floopy-* e sao enviadas em todas as requisicoes (chamadas compativeis com OpenAI e tambem as exclusivas do Floopy). Sobrescritas por chamada estao disponiveis via request_options=RequestOptions(...) em todo recurso.

from floopy import Floopy, FloopyOptions, CacheOptions

floopy = Floopy(
    api_key="fl_...",
    options=FloopyOptions(
        cache=CacheOptions(enabled=True, bucket_max_size=3),
        prompt_id="cd4249d5-44d5-46c8-8961-9eb3861e1f7e",
        prompt_version="1",
        llm_security_enabled=True,
    ),
)

Opcao	Header	Proposito
`cache.enabled`	`Floopy-Cache-Enabled`	Liga cache exato + semantico
`cache.bucket_max_size`	`Floopy-Cache-Bucket-Max-Size`	Max. de entradas por bucket semantico
`prompt_id`	`Floopy-Prompt-Id`	Prompt armazenado a resolver
`prompt_version`	`Floopy-Prompt-Version`	Versao fixada para `prompt_id`
`llm_security_enabled`	`floopy-llm-security-enabled`	Pre-checagem do firewall LLM

Veja a Referencia de Headers para a lista completa.

Recursos exclusivos do Floopy

Cada recurso mapeia para um endpoint publico /v1/* do gateway e e tipado de ponta a ponta. Todo metodo existe tanto em Floopy (sincrono) quanto em AsyncFloopy (use await).

# Feedback
floopy.feedback.submit(score=9, useful=True, session_id=r.id)

# Decisoes (iteradores paginados)
decision = floopy.decisions.get(request_id)
for d in floopy.decisions.iterate(from_=since, limit=50):
    ...

# Experimentos (header X-Floopy-Confirm: experiments automatico)
exp = floopy.experiments.create(
    name="cost-vs-quality",
    variant_a_routing_rule_id=rule_a,
    variant_b_routing_rule_id=rule_b,
)
floopy.experiments.rollback(exp.id)

# Constraints (PUT full-replace)
from floopy import OrgConstraints
floopy.constraints.put(OrgConstraints(cost_limit_monthly_usd=100))

# Exportacao (JSONL em streaming + trailer)
stream = floopy.export.decisions_with_trailer(from_=start, to=end)
for row in stream:
    ...
print(stream.trailer)

# Avaliacoes
run = floopy.evaluations.create(dataset_id=ds_id, model="gpt-4o")
results = floopy.evaluations.results(run.id, limit=100)

# Roteamento em dry-run (plano Pro)
explain = floopy.routing.explain(model="gpt-4o", messages=messages)

# Sessoes — restaura uma conversa armazenada
session = floopy.sessions.get(session_id)
floopy.chat.completions.create(model="gpt-4o", messages=session.messages)

Tratamento de Erros

Toda chamada exclusiva do Floopy lanca uma subclasse de FloopyError:

from floopy import FloopyRateLimitError, FloopyPlanError

try:
    for row in floopy.export.decisions(from_=start, to=end):
        ...
except FloopyRateLimitError as err:
    time.sleep(err.retry_after_seconds or 1)
except FloopyPlanError as err:
    print(f"Faca upgrade: recurso {err.feature} fora do plano atual")

Erros de chat.completions / embeddings sao emitidos pelo SDK OpenAI (openai.APIError e afins).

Seguranca

A chave de API so e enviada no header Authorization e e mascarada em repr(); o SDK nunca registra corpos de requisicao ou resposta.
A verificacao de certificado TLS fica ativa por padrao.
As releases sao publicadas no PyPI via Trusted Publishing (OIDC) com atestados PEP 740 — sem tokens de longa duracao, e os consumidores podem verificar que o artefato foi gerado pelo workflow de release.

Veja o guia de Seguranca para controles do lado do gateway.