[bot] Instrument fal-client (832,150 weekly downloads)

[braintrust-bot]

Summary

fal-client is fal.ai's official Python client for calling generative model APIs hosted on the fal platform (image, video, and audio generation models such as fal-ai/flux/dev). Its primary execution entrypoint is fal_client.subscribe(), which submits a generation request and blocks (with live queue-status callbacks) until the result is ready:

import fal_client
result = fal_client.subscribe(
    "fal-ai/flux/dev",
    arguments={"prompt": "a cat wearing a hat", "image_size": "landscape_4_3"},
    with_logs=True,
    on_queue_update=lambda status: print(f"Status: {status}"),
)
print(result["images"][0]["url"])

The package also exposes a submit/status/result queue-based API and an async client per fal's docs. This is a real generation execution surface (prompt → generated media) analogous to other model-execution surfaces this repo instruments, but for image/video/audio generation via a gateway not covered at all today.

This repository has zero instrumentation for it — no py/src/braintrust/integrations/fal* directory, no wrapper, no nox session, no cassette directory, and no entry in py/pyproject.toml's [tool.braintrust.matrix].

Weekly downloads

Weekly downloads: 832,150 (as of 2026-07-23; https://pypistats.org/packages/fal-client). Cross-checked against https://pepy.tech/projects/fal-client, which shows 2,993,462 downloads over the trailing 30 days (~700K/week), broadly consistent with the pypistats figure.

Braintrust docs status

not_found. Checked https://www.braintrust.dev/docs/guides/tracing and https://www.braintrust.dev/docs/guides/tracing/integrations — fal.ai / fal-client is not mentioned in either the provider list or the tracing-integrations directory (OpenTelemetry, Temporal, Vercel AI SDK, OpenRouter SDK, LangChain, LangSmith, LlamaIndex, Agno, Apollo GraphQL, Cloudflare Workers AI, DSPy, Instructor, LiteLLM, Ruby LLM, Traceloop, TrueFoundry).

What needs to be instrumented

• fal_client.subscribe() (sync, primary entrypoint) — should log the model endpoint id, input arguments (prompt/params), and output (generated media URLs/metadata).
• Queue-based submit() / status() / result() calls, if used independently of subscribe().
• Async client equivalents.

Upstream sources

• PyPI: https://pypi.org/project/fal-client/
• GitHub (fal.ai org): https://github.com/fal-ai/fal
• Docs: https://fal.ai/docs/api-reference/client-libraries/python

Local repo files inspected

• py/src/braintrust/integrations/ — no fal directory
• py/src/braintrust/wrappers/ — no fal-client wrapper
• py/pyproject.toml [tool.braintrust.matrix] — no fal-client entry
• py/noxfile.py — no test_fal session
• Repo-wide case-insensitive grep for fal[-_]client under py/ — zero matches