GigaChat Python SDK

The SDK supports several ways to interact with chat models:

• Synchronous Chat: Use client.chat.create(...) for standard completions and client.chat.stream(...) for streaming responses.
• Asynchronous Chat: Use GigaChatAsyncClient with client.achat.create(...) for async completions and client.achat.stream(...) for async SSE (Server-Sent Events) streaming.
• Model Tuning: You can configure temperature, top_p, and token limits. For v2 chat requests, you can use reasoning.effort to control reasoning capabilities.
• Thread Management: Reuse storage.thread_id between requests to maintain conversation context.

The SDK supports tool use and function calling:

• Function Calling: Provide client functions that the model can call, and handle the follow-up response.
• Forced Function Call: Use tool_config.mode="forced" to ensure the model calls a specific function.
• Built-in Tools:
  • web_search: Perform web searches (can be configured via search options or forced via tool_config.tool_name).
  • code_interpreter: Execute code within the model environment.
  • url_content_extraction: Extract content from provided URLs.
  • image_generate: Generate images (returns generated file IDs).

For complex workflows, use the Files and Assistants features:

• File Input: Upload a file and reference it within your message content to provide context to the model.
• Assistants: Manage the lifecycle of an assistant (create, use, and delete) to maintain stateful interactions.

The v2 contract is the recommended target for integrations requiring advanced features. These features are modeled natively in the primary request/response structure.

Supported v2 features include:

• Function calling
• Built-in tools (e.g., web search)
• Assistant-based stateful conversations
• Thread storage
• Richer response metadata

New explicit request fields in v2:

• tools
• tool_config
• assistant_id
• storage
• ranker_options
• user_info

You can constrain the model's output to specific formats using the response_format parameter:

• Pydantic Parsing: Use client.chat.parse(...) with a Pydantic model to automatically parse the response into a structured object.
• JSON Schema: Set response_format.type="json_schema" to enforce a specific JSON structure.
• Regex Format: Set response_format.type="regex" to constrain the output to a specific regular expression pattern.

If you are not ready to migrate your request/response handling, you can continue using the root compatibility methods. This is useful if your code relies heavily on the choices[0].message.content structure or if you have many downstream consumers expecting the old chunk shapes.

Compatibility methods:

• Sync: client.chat(payload), client.stream(payload), client.chat_parse(payload, ...)
• Async: client.achat(payload), client.astream(payload), client.achat_parse(payload, ...)

# Staying on the previous contract
response = client.chat(payload)

for chunk in client.stream(payload):
    ...

completion, parsed = client.chat_parse(
    payload,
    response_format=MathAnswer,
)

To run the provided Python examples, execute them as modules from the repository root using uv run.

uv run python -m examples.chat_completions.sync_chat

The GigaChat SDK uses load_dotenv() to load configuration. You can provide settings via environment variables or an .env file. Two settings are required for the examples to run:

1. Credentials: Use either GIGACHAT_CREDENTIALS or GIGACHAT_ACCESS_TOKEN.
2. Model: Set GIGACHAT_MODEL. The SDK does not have a default model; if you do not specify a model in your code and this variable is missing, the SDK will raise a ModelNotSpecifiedError. You can use client.get_models() to list available models.

# Example .env content
GIGACHAT_CREDENTIALS="your_credentials"
GIGACHAT_MODEL="your_model_name"

Install the gigachat package using pip. The SDK requires Python 3.8 through 3.13.

Note: In production, keep TLS verification enabled (the default).

pip install gigachat