[bot] Add Groq Python SDK integration for chat completions, audio, and built-in tools instrumentation

[braintrust-bot]

Summary

The Groq Python SDK (groq) is the official Python client for Groq's inference API. Its Groq and AsyncGroq clients provide execution APIs for chat completions, streaming, tool/function calling, audio transcription, and Groq Compound built-in tools (web search, code execution, browser automation). This repository has zero instrumentation for any Groq SDK surface — no integration, no wrapper, no patcher, no auto-instrumentation config. Users who call the Groq SDK directly get no Braintrust spans.

While Groq exposes an OpenAI-compatible endpoint that can be used via openai.OpenAI(base_url="https://api.groq.com/openai/v1") + wrap_openai(), the native groq.Groq() client cannot be wrapped with wrap_openai() because it is a distinct client class. Users who follow Groq's official documentation and pip install groq get zero Braintrust tracing. This is the same pattern as Mistral and OpenRouter — both have OpenAI-compatible APIs but received dedicated native integrations in this repo.

Additionally, Groq Compound's built-in tools (web_search, code_interpreter, browser_automation, wolfram_alpha, visit_website) are Groq-specific agentic execution surfaces where the model autonomously calls server-side tools and handles the agentic loop internally. These execution surfaces are not available through the OpenAI compatibility endpoint.

What needs to be instrumented

The groq package (latest: v1.2.0, released April 18, 2026) exposes these execution surfaces, none of which are instrumented:

Chat completions (highest priority)

SDK Method	Description	Streaming	Return type
client.chat.completions.create()	Chat completions with tool calling, vision, JSON mode	stream=True returns stream iterator	ChatCompletion

Response shape is OpenAI-compatible: ChatCompletion has choices, usage (prompt_tokens, completion_tokens, total_tokens), model, id — standard span metrics extraction should be straightforward, similar to the existing OpenAI integration.

Streaming: When stream=True, returns an iterator of ChatCompletionChunk objects. The integration must handle streaming span lifecycle (start span on call, accumulate chunks, finalize on stream exhaustion).

Tool/function calling: Standard OpenAI-style tool calling with tools parameter and tool_calls in responses.

Built-in tools / Groq Compound (unique to Groq)

Feature	Description
web_search	Server-side web search during generation
code_interpreter	Server-side code execution during generation
browser_automation	Server-side browser automation
wolfram_alpha	Server-side Wolfram Alpha queries
visit_website	Server-side website content retrieval

Built-in tools are passed via the tools parameter with special tool identifiers. The model autonomously calls these tools on Groq's servers and returns the complete result. This is an agentic execution surface unique to Groq that has no equivalent in the OpenAI SDK.

Audio (lower priority)

SDK Method	Description	Return type
client.audio.transcriptions.create()	Speech-to-text via Whisper models	Transcription

Both sync and async

All methods have async variants on AsyncGroq with identical signatures.

Implementation notes

Stainless-generated SDK: The groq package is generated by Stainless (same toolchain as the OpenAI SDK). The client structure (client.chat.completions.create()) mirrors the OpenAI SDK, so the patcher/wrapper pattern from the OpenAI integration can serve as a close structural reference.

chat.completions.create() parameters relevant for span metadata: model, temperature, max_tokens, max_completion_tokens, top_p, frequency_penalty, presence_penalty, seed, tools, tool_choice, response_format, stop, n.

No coverage in any instrumentation layer

• No integration directory (py/src/braintrust/integrations/groq/)
• No wrapper function (e.g. wrap_groq())
• No patcher in any existing integration
• No nox test session (test_groq)
• No version entry in py/src/braintrust/integrations/versioning.py
• No mention in py/src/braintrust/integrations/__init__.py

A grep for groq (case-insensitive) across py/src/braintrust/integrations/ returns zero matches in integration code (only incidental mentions in cassette YAML files and pydantic_ai model name strings).

Braintrust docs status

not_found — Groq is not listed on the Braintrust integrations directory or the tracing guide.

Upstream references

• Groq Python SDK on PyPI: https://pypi.org/project/groq/
• Groq Python SDK on GitHub: https://github.com/groq/groq-python
• Groq API reference: https://console.groq.com/docs/api-reference
• Groq Chat Completions docs: https://console.groq.com/docs/text-chat
• Groq Built-in Tools docs: https://console.groq.com/docs/tool-use/built-in-tools
• Groq Client Libraries: https://console.groq.com/docs/libraries

Local repo files inspected

• py/src/braintrust/integrations/ — no groq/ directory exists on main
• py/src/braintrust/wrappers/ — no Groq wrapper
• py/noxfile.py — no test_groq session
• py/src/braintrust/integrations/__init__.py — Groq not listed in integration registry
• py/src/braintrust/integrations/versioning.py — no Groq version matrix
• py/pyproject.toml — no Groq entries in [tool.braintrust.matrix]