floopy-sdk (Python)

Official Floopy AI Gateway SDK for Python. Drop-in replacement for the openai SDK with Floopy's cache, audit, experiments, routing, and security on top.

Why

floopy-sdk wraps the official openai package and points it at the Floopy gateway, so:

• Zero migration cost for chat.completions and embeddings — same types, same methods.
• Security updates to the OpenAI SDK reach you on pip install -U without forks or parity drift.
• Floopy-only features (audit, experiments, constraints, decision export, feedback, routing dry-run, sessions) get first-class typed methods instead of raw requests/httpx calls.

Install

pip install floopy-sdk          # or: uv add floopy-sdk

Requires Python >= 3.10.

Quick start

from floopy import Floopy

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

Async is symmetric:

import asyncio
from floopy import AsyncFloopy


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


asyncio.run(main())

Migrating from 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, and client.models return the underlying openai resources, so types and runtime behaviour are identical. Full guide: https://floopy.ai/docs/guides/sdks/floopy-sdk-python#migrating-from-openai.

Floopy options (cache, prompt versioning, security firewall)

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,
    ),
)

These map to Floopy-* headers forwarded to every request (both OpenAI-compat calls and Floopy-only ones). Per-call overrides are available via request_options=RequestOptions(...) on every resource.

Floopy-only resources

Each resource maps to a public /v1/* gateway endpoint and is typed end-to-end. Errors are FloopyError subclasses (see below). Every method exists on both Floopy (sync) and AsyncFloopy (await it).

feedback

r = floopy.chat.completions.create(...)
floopy.feedback.submit(score=9, useful=True, session_id=r.id)

decisions

decision = floopy.decisions.get(request_id)
page = floopy.decisions.list(from_=since, limit=50)

for d in floopy.decisions.iterate(from_=since):  # one at a time
    ...
for p in floopy.decisions.pages(from_=since):  # page at a time
    ...

experiments

exp = floopy.experiments.create(
    name="cost-vs-quality",
    variant_a_routing_rule_id=rule_a,
    variant_b_routing_rule_id=rule_b,
)
results = floopy.experiments.results(exp.id)
floopy.experiments.rollback(exp.id)

create and rollback automatically include the X-Floopy-Confirm: experiments header the gateway requires (SEC-009).

constraints

from floopy import OrgConstraints

current = floopy.constraints.get()
floopy.constraints.put(OrgConstraints(cost_limit_monthly_usd=100))

put is full-replace: fields left as None are reset.

export

for row in floopy.export.decisions(from_=start, to=end):
    ...  # streamed JSONL, parsed and typed

# to also read the trailer (truncation reasons, totals):
stream = floopy.export.decisions_with_trailer(from_=start, to=end)
for row in stream:
    ...
print(stream.trailer)  # populated after iteration completes

evaluations

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

routing.explain

explain = floopy.routing.explain(model="gpt-4o", messages=messages)
print(explain.would_select, explain.firewall_decision)

Pro plan only. would_select is None if the firewall blocks the request.

sessions

session = floopy.sessions.get(session_id)
# session.messages is a drop-in for a follow-up chat completion
floopy.chat.completions.create(model="gpt-4o", messages=session.messages)

files and batches

OpenAI-shaped Batch + Files passthrough. A batch carries no model up front, so select the upstream with provider= (sent as the floopy-provider header) — optional when the key has one provider. AsyncFloopy exposes the same files/batches API.

file = floopy.files.upload(
    file=open("requests.jsonl", "rb").read(),
    filename="requests.jsonl",
    purpose="batch",
    provider="openai",
)
batch = floopy.batches.create(
    input_file_id=file.id,
    endpoint="/v1/chat/completions",
    completion_window="24h",
    provider="openai",
)
done = floopy.batches.retrieve(batch.id, provider="openai")
if done.status == "completed" and done.output_file_id:
    out = floopy.files.content(done.output_file_id, provider="openai")  # bytes
floopy.batches.cancel(batch.id, provider="openai")
floopy.files.delete(file.id, provider="openai")

files.list, files.retrieve, and batches.list are also available.

Streaming

chat.completions streaming is delegated to openai and yields chunks exactly as the upstream SDK does. export.decisions yields typed ExportedDecisionRow objects over the gateway's JSONL stream.

Error handling

Every Floopy-only call raises a FloopyError subclass:

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"Upgrade plan: feature {err.feature} not in current plan")

Errors from chat.completions / embeddings are emitted by the OpenAI SDK (openai.APIError and friends).

Security

• The API key is only ever sent in the Authorization header and is masked in repr() of internal objects; the SDK never logs request or response bodies.
• TLS certificate verification is on by default (httpx).
• Releases are published to PyPI via Trusted Publishing (OIDC) with PEP 740 attestations — no long-lived tokens, and consumers can verify the artifact was built by this repo's release workflow.

Self-hosting / custom base URL

floopy = Floopy(api_key="fl_...", base_url="https://gateway.internal.acme.com/v1")

Links

• Full SDK guide: https://floopy.ai/docs/guides/sdks/floopy-sdk-python (Português)
• API reference: https://floopy.ai/docs/guides/api-reference
• Changelog: CHANGELOG.md

License

Apache-2.0 © Floopy

Responses API

Use client.responses.create(...) / await client.responses.create(...) for native POST /v1/responses, including reasoning with function tools and typed streaming events. The delegate uses your Floopy base URL, API key and default gateway headers.

This release uses OpenAI Python >=3.25.0,<4. Responses currently routes to compatible OpenAI targets through the existing gateway orchestration. Stateless text caching requires store: false; calls with tools or provider-managed history bypass cache. Background jobs and public response-management methods are not exposed by the gateway yet. See Responses API documentation.