release: 0.35.0 (#257)

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>
Co-authored-by: Graden Rea <grea@groq.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.34.1"
+  ".": "0.35.0"
 }

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 17
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/groqcloud%2Fgroqcloud-5d2697ad30ccbbd1502ade612deb9221a1e05e70d09a156da743d0ca120942f9.yml
-openapi_spec_hash: 0bde05b560fbd40711e91e6b562c3b0f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/groqcloud%2Fgroqcloud-b059caa2a4d4cc23663f61d2ec0f83a4b0e4eda7ed1f2dbbb129c5d320811200.yml
+openapi_spec_hash: 87ccaae4d281259575c961b9cd52766e
 config_hash: a4a6c3089a2e53425351cc9f42b4b5aa

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.35.0 (2025-11-18)
+
+Full Changelog: [v0.34.1...v0.35.0](https://github.com/groq/groq-python/compare/v0.34.1...v0.35.0)
+
+### Features
+
+* **api:** api update ([d6ec93d](https://github.com/groq/groq-python/commit/d6ec93d000702baf001b1a5739489d8d5fd7b7da))
+* **api:** api update ([48c8f11](https://github.com/groq/groq-python/commit/48c8f11f014207d9665b1eacce3f97461265b12d))
+
+
+### Bug Fixes
+
+* update chat completion streaming types ([833cf83](https://github.com/groq/groq-python/commit/833cf83b5f2f59eaa17507c330be90a722a871e8))
+
+
+### Chores
+
+* GitHub Terraform: Create/Update .github/workflows/code-freeze-bypass.yaml [skip ci] ([63d11e3](https://github.com/groq/groq-python/commit/63d11e39fec78e040a95e6e3fe398fe6ca9e1fc2))
+
 ## 0.34.1 (2025-11-14)
 
 Full Changelog: [v0.34.0...v0.34.1](https://github.com/groq/groq-python/compare/v0.34.0...v0.34.1)

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "groq"
-version = "0.34.1"
+version = "0.35.0"
 description = "The official Python library for the groq API"
 dynamic = ["readme"]
 license = "Apache-2.0"

src/groq/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "groq"
-__version__ = "0.34.1"  # x-release-please-version
+__version__ = "0.35.0"  # x-release-please-version

src/groq/types/chat/chat_completion.py

@@ -1,14 +1,25 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-from typing import List, Optional
+from typing import Dict, List, Optional
 from typing_extensions import Literal
 
 from ..._models import BaseModel
 from ..completion_usage import CompletionUsage
 from .chat_completion_message import ChatCompletionMessage
 from .chat_completion_token_logprob import ChatCompletionTokenLogprob
 
-__all__ = ["ChatCompletion", "Choice", "ChoiceLogprobs", "UsageBreakdown", "UsageBreakdownModel"]
+__all__ = [
+    "ChatCompletion",
+    "Choice",
+    "ChoiceLogprobs",
+    "McpListTool",
+    "McpListToolTool",
+    "UsageBreakdown",
+    "UsageBreakdownModel",
+    "XGroq",
+    "XGroqDebug",
+    "XGroqUsage",
+]
 
 
 class ChoiceLogprobs(BaseModel):
@@ -36,6 +47,34 @@ class Choice(BaseModel):
     """A chat completion message generated by the model."""
 
 
+class McpListToolTool(BaseModel):
+    annotations: Optional[object] = None
+    """Additional metadata for the tool."""
+
+    description: Optional[str] = None
+    """Description of what the tool does."""
+
+    input_schema: Optional[Dict[str, object]] = None
+    """JSON Schema describing the tool's input parameters."""
+
+    name: Optional[str] = None
+    """The name of the tool."""
+
+
+class McpListTool(BaseModel):
+    id: Optional[str] = None
+    """Unique identifier for this tool list response."""
+
+    server_label: Optional[str] = None
+    """Human-readable label for the MCP server."""
+
+    tools: Optional[List[McpListToolTool]] = None
+    """Array of discovered tools from the server."""
+
+    type: Optional[str] = None
+    """The type identifier."""
+
+
 class UsageBreakdownModel(BaseModel):
     model: str
     """The name/identifier of the model used"""
@@ -49,6 +88,51 @@ class UsageBreakdown(BaseModel):
     """List of models used in the request and their individual usage statistics"""
 
 
+class XGroqDebug(BaseModel):
+    input_token_ids: Optional[List[int]] = None
+    """Token IDs for the input."""
+
+    input_tokens: Optional[List[str]] = None
+    """Token strings for the input."""
+
+    output_token_ids: Optional[List[int]] = None
+    """Token IDs for the output."""
+
+    output_tokens: Optional[List[str]] = None
+    """Token strings for the output."""
+
+
+class XGroqUsage(BaseModel):
+    dram_cached_tokens: Optional[int] = None
+    """Number of tokens served from DRAM cache."""
+
+    sram_cached_tokens: Optional[int] = None
+    """Number of tokens served from SRAM cache."""
+
+
+class XGroq(BaseModel):
+    id: str
+    """
+    A groq request ID which can be used to refer to a specific request to groq
+    support.
+    """
+
+    debug: Optional[XGroqDebug] = None
+    """Debug information including input and output token IDs and strings.
+
+    Only present when debug=true in the request.
+    """
+
+    seed: Optional[int] = None
+    """The seed used for the request.
+
+    See the seed property on CreateChatCompletionRequest for more details.
+    """
+
+    usage: Optional[XGroqUsage] = None
+    """Additional Groq-specific usage metrics (hardware cache statistics)."""
+
+
 class ChatCompletion(BaseModel):
     id: str
     """A unique identifier for the chat completion."""
@@ -68,6 +152,12 @@ class ChatCompletion(BaseModel):
     object: Literal["chat.completion"]
     """The object type, which is always `chat.completion`."""
 
+    mcp_list_tools: Optional[List[McpListTool]] = None
+    """List of discovered MCP tools from connected servers."""
+
+    service_tier: Optional[Literal["auto", "on_demand", "flex", "performance"]] = None
+    """The service tier used for the request."""
+
     system_fingerprint: Optional[str] = None
     """This fingerprint represents the backend configuration that the model runs with.
 
@@ -83,3 +173,6 @@ class ChatCompletion(BaseModel):
     Detailed usage breakdown by model when multiple models are used in the request
     for compound AI systems.
     """
+
+    x_groq: Optional[XGroq] = None
+    """Groq-specific metadata for non-streaming chat completion responses."""

src/groq/types/chat/chat_completion_chunk.py

@@ -17,6 +17,10 @@
     "ChoiceDeltaToolCall",
     "ChoiceDeltaToolCallFunction",
     "ChoiceLogprobs",
+    "XGroq",
+    "XGroqDebug",
+    "UsageBreakdown",
+    "UsageBreakdownModel",
 ]
 
 
@@ -98,6 +102,33 @@ class ChoiceLogprobs(BaseModel):
     """A list of message content tokens with log probability information."""
 
 
+class UsageBreakdownModel(BaseModel):
+    model: str
+    """The name/identifier of the model used"""
+
+    usage: CompletionUsage
+    """Usage statistics for the completion request."""
+
+
+class UsageBreakdown(BaseModel):
+    models: List[UsageBreakdownModel]
+    """List of models used in the request and their individual usage statistics"""
+
+
+class XGroqDebug(BaseModel):
+    input_token_ids: Optional[List[int]] = None
+    """Token IDs for the input."""
+
+    input_tokens: Optional[List[str]] = None
+    """Token strings for the input."""
+
+    output_token_ids: Optional[List[int]] = None
+    """Token IDs for the output."""
+
+    output_tokens: Optional[List[str]] = None
+    """Token strings for the output."""
+
+
 class Choice(BaseModel):
     delta: ChoiceDelta
     """A chat completion delta generated by streamed model responses."""
@@ -120,17 +151,32 @@ class Choice(BaseModel):
 
 
 class XGroq(BaseModel):
-    id: Optional[str]
+    id: Optional[str] = None
+    """
+    A groq request ID which can be used to refer to a specific request to groq support.
+    Sent only in the first and final chunk.
     """
-    A groq request ID which can be used by to refer to a specific request to groq support 
-    Only sent with the first chunk
+
+    debug: Optional[XGroqDebug] = None
+    """Debug information including input and output token IDs and strings.
+
+    Only present when debug=true in the request.
     """
 
-    usage: Optional[CompletionUsage]
-    """Usage information for the stream. Only sent in the final chunk"""
+    seed: Optional[int] = None
+    """The seed used for the request. Sent in the final chunk."""
+
+    usage: Optional[CompletionUsage] = None
+    """Usage information for the stream. Only sent in the final chunk."""
+
+    usage_breakdown: Optional[UsageBreakdown] = None
+    """
+    Detailed usage breakdown by model when multiple models are used in the request
+    for compound AI systems. Only sent in the final chunk.
+    """
 
-    error: Optional[str]
-    """ An error string indicating why a stream was stopped early"""
+    error: Optional[str] = None
+    """An error string indicating why a stream was stopped early."""
 
 
 class ChatCompletionChunk(BaseModel):
@@ -171,7 +217,7 @@ class ChatCompletionChunk(BaseModel):
     statistics for the entire request.
     """
 
-    x_groq: Optional[XGroq]
+    x_groq: Optional[XGroq] = None
     """
     Additional metadata provided by groq.
     """

src/groq/types/completion_usage.py

@@ -4,7 +4,17 @@
 
 from .._models import BaseModel
 
-__all__ = ["CompletionUsage"]
+__all__ = ["CompletionUsage", "CompletionTokensDetails", "PromptTokensDetails"]
+
+
+class CompletionTokensDetails(BaseModel):
+    reasoning_tokens: int
+    """Number of tokens used for reasoning (for reasoning models)."""
+
+
+class PromptTokensDetails(BaseModel):
+    cached_tokens: int
+    """Number of tokens that were cached and reused."""
 
 
 class CompletionUsage(BaseModel):
@@ -20,9 +30,15 @@ class CompletionUsage(BaseModel):
     completion_time: Optional[float] = None
     """Time spent generating tokens"""
 
+    completion_tokens_details: Optional[CompletionTokensDetails] = None
+    """Breakdown of tokens in the completion."""
+
     prompt_time: Optional[float] = None
     """Time spent processing input tokens"""
 
+    prompt_tokens_details: Optional[PromptTokensDetails] = None
+    """Breakdown of tokens in the prompt."""
+
     queue_time: Optional[float] = None
     """Time the requests was spent queued"""