gigachat 0.2.0

GigaChat. Python-library for GigaChat API

GigaChat Python SDK

Python SDK for the GigaChat REST API — a large language model.

This library is part of GigaChain and powers langchain-gigachat, the official LangChain integration for GigaChat.

Table of Contents

• Features
• Installation
• Quick Start
• Usage Examples
  • Basic Chat
  • Streaming
  • Async
  • Embeddings
  • Function Calling
  • More Examples
• Configuration
  • Constructor Parameters
  • Environment Variables
• Authentication
• SSL Certificates
• Error Handling
• Advanced Features
• API Reference
• Related Projects
• Contributing
• License

Features

• ✅ Chat completions — synchronous and asynchronous
• ✅ Streaming responses — real-time token generation
• ✅ Embeddings — text vectorization
• ✅ Function calling — tool use for building agents
• ✅ Vision — image understanding (multimodal)
• ✅ File operations — upload, retrieve, and delete files
• ✅ Token counting — estimate token usage before requests
• ✅ Multiple auth methods — OAuth credentials, password, TLS certificates, access tokens
• ✅ Automatic retry — configurable exponential backoff for transient errors
• ✅ Fully typed — Pydantic V2 models with py.typed marker for IDE support

Installation

pip install gigachat

Requirements: Python 3.8 — 3.13

Note: In production, keep TLS verification enabled (default). See SSL Certificates for setup instructions.

Quick Start

Get your GigaChat authorization key

For detailed instructions, see the official documentation.

Configure gigachat package to use TLS certificate

TLS certificate: follow the OS-specific installation steps on Gosuslugi (see SSL Certificates for how to configure GIGACHAT_CA_BUNDLE_FILE / ca_bundle_file if needed).

Development-only (not recommended):

set GIGACHAT_VERIFY_SSL_CERTS=false or pass verify_ssl_certs=False to GigaChat(...).

Usage Examples

The examples below assume authentication is configured via environment variables (for example, GIGACHAT_CREDENTIALS). See Authentication.

Basic Chat

from gigachat import GigaChat

with GigaChat(credentials="<your_authorization_key>") as client:
    response = client.chat("Hello, GigaChat!")
    print(response.choices[0].message.content)

Streaming

Receive tokens as they are generated:

from gigachat import GigaChat

with GigaChat() as client:
    for chunk in client.stream("Write a short poem about programming"):
        print(chunk.choices[0].delta.content, end="", flush=True)
    print()  # Newline at the end

Async

Use async/await for non-blocking operations:

import asyncio
from gigachat import GigaChat

async def main():
    async with GigaChat() as client:
        # Async chat
        response = await client.achat("Explain quantum computing in simple terms")
        print(response.choices[0].message.content)

        # Async streaming
        print("Streaming response:")
        async for chunk in client.astream("Tell me a joke"):
            print(chunk.choices[0].delta.content, end="", flush=True)
        print()

asyncio.run(main())

Embeddings

Generate vector representations of text:

from gigachat import GigaChat

with GigaChat() as client:
    result = client.embeddings(["Hello, world!", "Machine learning is fascinating"])

    for i, item in enumerate(result.data):
        print(f"Text {i + 1}: {len(item.embedding)} dimensions")

Function Calling

Enable the model to call functions (tools):

from gigachat import GigaChat
from gigachat.models import Chat, Messages, MessagesRole, Function, FunctionParameters

weather_function = Function(
    name="get_weather",
    description="Get current weather for a location",
    parameters=FunctionParameters(
        type="object",
        properties={
            "location": {
                "type": "string",
                "description": "City name, e.g., Moscow"
            },
            "unit": {
                "type": "string",
                "enum": ["celsius", "fahrenheit"],
                "description": "Temperature unit"
            }
        },
        required=["location"],
    ),
)

chat = Chat(
    messages=[Messages(role=MessagesRole.USER, content="What's the weather in Tokyo?")],
    functions=[weather_function],
)

with GigaChat() as client:
    response = client.chat(chat)
    message = response.choices[0].message

    if response.choices[0].finish_reason == "function_call":
        print(f"Function: {message.function_call.name}")
        print(f"Arguments: {message.function_call.arguments}")

More examples

See the examples/ folder for complete working examples including chat, functions, context variables, AI detection, and vision.

Configuration

Constructor Parameters

Parameter	Type	Default	Description
credentials	str	None	Authorization key from GigaChat API
scope	str	GIGACHAT_API_PERS	API scope (see below)
model	str	GigaChat	Default model for requests
base_url	str	https://gigachat.devices.sberbank.ru/api/v1	API base URL
auth_url	str	https://ngw.devices.sberbank.ru:9443/api/v2/oauth	OAuth token endpoint
access_token	str	None	Pre-obtained access token (bypasses OAuth)
user	str	None	Username for password authentication
password	str	None	Password for password authentication
verify_ssl_certs	bool	True	Verify SSL certificates
ca_bundle_file	str	None	Path to CA certificate bundle
cert_file	str	None	Path to client certificate (for mTLS)
key_file	str	None	Path to client private key (for mTLS)
key_file_password	str	None	Password for encrypted private key
timeout	float	30.0	Request timeout in seconds
max_connections	int	None	Maximum concurrent connections
max_retries	int	0	Maximum retry attempts for transient errors
retry_backoff_factor	float	0.5	Exponential backoff multiplier
retry_on_status_codes	tuple	(429, 500, 502, 503, 504)	HTTP status codes that trigger retry
profanity_check	bool	None	Enable profanity filtering
flags	list	None	Additional API flags

API Scopes:

Scope	Description
GIGACHAT_API_PERS	API for individuals (default)
GIGACHAT_API_B2B	API for businesses (prepaid)
GIGACHAT_API_CORP	API for businesses (postpaid)

Environment Variables

All parameters can be configured via environment variables with the GIGACHAT_ prefix:

# Authentication
export GIGACHAT_CREDENTIALS="<your_authorization_key>"
export GIGACHAT_SCOPE="GIGACHAT_API_PERS"

# Connection
export GIGACHAT_BASE_URL="https://gigachat.devices.sberbank.ru/api/v1"
export GIGACHAT_TIMEOUT="60.0"
export GIGACHAT_VERIFY_SSL_CERTS="true"
# TLS: path to a CA bundle file (typically required - Python HTTP clients often don't use OS trust store by default)
export GIGACHAT_CA_BUNDLE_FILE="<your_ca_bundle_file>"

# Model
export GIGACHAT_MODEL="GigaChat"

# Retry
export GIGACHAT_MAX_RETRIES="3"
export GIGACHAT_RETRY_BACKOFF_FACTOR="0.5"

Then create a client without any parameters:

from gigachat import GigaChat

# Configuration loaded from environment variables
with GigaChat() as client:
    response = client.chat("Hello!")

Authentication

The library supports four authentication methods:

Authentication priority (when multiple are configured)

If multiple auth inputs are provided at the same time, the SDK applies this priority:

1. custom_headers_cvar["Authorization"] (if set) — overrides any other auth source.
2. authorization_cvar (if set) — overrides any other auth source and disables automatic token fetching/refresh (you manage the header value and its lifecycle).
3. Explicit access_token (constructor parameter / GIGACHAT_ACCESS_TOKEN) — used as-is. If it fails with 401 and OAuth credentials or user/password are also configured, the SDK will fall back to fetching a new token.
4. OAuth credentials (constructor parameter / GIGACHAT_CREDENTIALS) — used to obtain/refresh a token.
5. Username/password (user + password) — used to obtain/refresh a token from the /token endpoint.

When both OAuth credentials and username/password are provided, OAuth credentials take precedence for token refresh.

1. Authorization Key (Recommended)

For detailed instructions, see the official documentation.

from gigachat import GigaChat

client = GigaChat(credentials="<your_authorization_key>")

The authorization key encodes your API scope. If using the B2B or CORP API, specify the scope explicitly:

client = GigaChat(
    credentials="<your_authorization_key>",
    scope="GIGACHAT_API_B2B",  # or GIGACHAT_API_CORP
)

2. Username and Password

Authenticate with a username and password:

from gigachat import GigaChat

client = GigaChat(
    base_url="https://gigachat.devices.sberbank.ru/api/v1",
    user="<username>",
    password="<password>",
)

3. TLS Certificates (mTLS)

Authenticate using client certificates for mutual TLS:

from gigachat import GigaChat

client = GigaChat(
    base_url="https://gigachat.devices.sberbank.ru/api/v1",
    cert_file="certs/client.pem",         # Client certificate
    key_file="certs/client.key",          # Client private key
    key_file_password="<key_password>",   # Optional: password for encrypted key
)

4. Access Token

Use a pre-obtained access token (JWT):

from gigachat import GigaChat

client = GigaChat(access_token="<your_access_token>")

Note: Access tokens expire after 30 minutes. Use this method when you manage token lifecycle externally.

Pre-authentication

By default, the library obtains an access token on the first API request. To authenticate immediately:

from gigachat import GigaChat

client = GigaChat(credentials="<your_authorization_key>")
token = client.get_token()  # Authenticate now
print(f"Token expires at: {token.expires_at}")

SSL Certificates

GigaChat endpoints use a certificate chain issued by the Russian Ministry of Digital Development. This section explains how to configure the GigaChat SDK to use the required certificates.

Quick Reference

• What you need: The "Russian Trusted Root CA" certificate file from Gosuslugi
• How to configure: Set GIGACHAT_CA_BUNDLE_FILE environment variable or pass ca_bundle_file argument to GigaChat()
• Why: Python HTTP clients typically use their own CA bundle (e.g., certifi) instead of the OS trust store

Configuration

Environment variable (recommended):

export GIGACHAT_CA_BUNDLE_FILE="<path_to_root_ca_file>"

Or as argument:

from gigachat import GigaChat

with GigaChat(ca_bundle_file="<path_to_root_ca_file>") as client:
    response = client.chat("Hello!")
    print(response.choices[0].message.content)

OS-Specific Notes

Download the "Russian Trusted Root CA" certificate from Gosuslugi and configure GIGACHAT_CA_BUNDLE_FILE to point to the downloaded file:

• Windows: Downloaded as .cer file (e.g., Russian Trusted Root CA.cer)
• macOS/Linux: Downloaded as .crt file (e.g., Russian_Trusted_Root_CA.crt)

Example paths:

# Windows
set GIGACHAT_CA_BUNDLE_FILE=C:\path\to\Russian_Trusted_Root_CA.cer

# macOS/Linux
export GIGACHAT_CA_BUNDLE_FILE="/path/to/Russian_Trusted_Root_CA.crt"

Development-only: Disable TLS verification (not recommended)

• Environment variable: GIGACHAT_VERIFY_SSL_CERTS=false
• Or pass verify_ssl_certs=False to GigaChat(...)

from gigachat import GigaChat

client = GigaChat(verify_ssl_certs=False)

⚠️ Warning: Disabling certificate verification reduces security and is not recommended for production environments.

Error Handling

The library raises specific exceptions for different error conditions:

from gigachat import GigaChat
from gigachat.exceptions import (
    GigaChatException,
    AuthenticationError,
    RateLimitError,
    BadRequestError,
    ForbiddenError,
    NotFoundError,
    RequestEntityTooLargeError,
    ServerError,
)

try:
    with GigaChat() as client:
        response = client.chat("Hello!")
        print(response.choices[0].message.content)
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except BadRequestError as e:
    print(f"Invalid request: {e}")
except ForbiddenError as e:
    print(f"Access denied: {e}")
except NotFoundError as e:
    print(f"Resource not found: {e}")
except RequestEntityTooLargeError as e:
    print(f"Request payload too large: {e}")
except ServerError as e:
    print(f"Server error: {e}")
except GigaChatException as e:
    print(f"GigaChat error: {e}")

Exception Reference

Exception	HTTP Status	Description
GigaChatException	—	Base exception for all library errors
ResponseError	—	Base exception for HTTP response errors
AuthenticationError	401	Invalid or expired credentials
BadRequestError	400	Malformed request or invalid parameters
ForbiddenError	403	Access denied (insufficient permissions)
NotFoundError	404	Requested resource not found
RequestEntityTooLargeError	413	Request payload too large
RateLimitError	429	Too many requests (use e.retry_after)
ServerError	5xx	Server-side error

Advanced Features

Context Variables

Track requests with custom headers for logging and debugging:

from gigachat import GigaChat, session_id_cvar, request_id_cvar, custom_headers_cvar
import uuid

# Set session and request identifiers
session_id_cvar.set("user-session-12345")
request_id_cvar.set(str(uuid.uuid4()))

# Or add custom headers
custom_headers_cvar.set({"X-Custom-Header": "custom-value"})

with GigaChat() as client:
    response = client.chat("Hello!")

Available context variables:

Variable	Header	Description
session_id_cvar	X-Session-ID	Session identifier for grouping requests
request_id_cvar	X-Request-ID	Unique request identifier
client_id_cvar	X-Client-ID	Client identifier
custom_headers_cvar	(various)	Dictionary of additional headers

Header precedence (when multiple sources set the same header):

• Explicit access_token passed by the SDK (or your code) sets Authorization: Bearer ... first.
• authorization_cvar overrides that Authorization header if it is set.
• custom_headers_cvar is applied last and overrides both (including Authorization), as well as any other header.

Retry Configuration

Configure automatic retry with exponential backoff for transient errors:

from gigachat import GigaChat

client = GigaChat(
    max_retries=3,                          # Retry up to 3 times
    retry_backoff_factor=0.5,               # Delays: 0.5s, 1s, 2s
    retry_on_status_codes=(429, 500, 502, 503, 504),
)

Avoid “double retry” (important): If you use gigachat through a higher-level library that also retries (for example, langchain-gigachat / LangChain), enable retries in only one layer. Otherwise, the effective number of attempts multiplies (e.g., 3 SDK retries × 3 framework retries).

Recommended defaults:

• Keep gigachat retries disabled (default max_retries=0) when the outer framework retries.
• Or disable retries in the outer framework and configure retries here (recommended if you want one consistent retry policy).

Deprecations

• Messages.data_for_context: deprecated by the upstream API. Do not use it in new code.
  • Use instead: include the relevant information directly in the message content, or attach files via attachments (file IDs) when you need to provide additional context.
  • Timeline: the SDK will keep accepting data_for_context through the 0.x line, but it may be removed in 1.0.0 (or earlier if the upstream API removes it).

Token Counting

Estimate token usage before sending requests:

from gigachat import GigaChat

with GigaChat() as client:
    counts = client.tokens_count(["Hello, world!", "How are you today?"])
    for count in counts:
        print(f"Tokens: {count.tokens}, Characters: {count.characters}")

Available Models

List available models and their capabilities:

from gigachat import GigaChat

with GigaChat() as client:
    models = client.get_models()
    for model in models.data:
        print(f"{model.id_} (owned_by={model.owned_by})")

File Operations

Upload and manage files:

from gigachat import GigaChat

with GigaChat() as client:
    # Upload a file
    with open("document.pdf", "rb") as f:
        uploaded = client.upload_file(f, purpose="general")
    print(f"Uploaded: {uploaded.id}")

    # List files
    files = client.get_files()
    for file in files.data:
        print(f"{file.id}: {file.filename}")

    # Delete a file
    client.delete_file(uploaded.id)

Balance Check

Check your remaining token balance (prepaid accounts only):

from gigachat import GigaChat

with GigaChat(scope="GIGACHAT_API_B2B") as client:
    balance = client.get_balance()
    for entry in balance.balance:
        print(f"{entry.usage}: {entry.value}")

API Reference

• GigaChat API Documentation
• Available Models
• Early Access Models
• Pricing

Related Projects

• GigaChain — A set of solutions for developing Russian-language LLM applications and multi-agent systems, with support for LangChain, LangGraph, LangChain4j, as well as GigaChat and other available LLMs. GigaChain covers the full development lifecycle: from prototyping and research to production deployment and ongoing support.
• langchain-gigachat — Official LangChain integration package for GigaChat

Versioning and stability

This project follows SemVer with additional clarity for pre-1.0.0 releases:

• Patch releases (0.x.Y): Backwards compatible bug fixes and internal changes.
• Minor releases (0.X.0): May include backwards-incompatible changes. Any breaking changes must be called out in the GitHub Release notes.

Stable release gate

To ship a release marked Production/Stable, the following must be true:

• CI is green on main (lint, mypy, unit tests, integration replay).
• Local checks are green (make all).
• Packaging is sane: sdist+wheel build and install from artifacts works (no missing files).
• Integration cassettes are current: re-recorded with real credentials and reviewed for scrubbing.

Contributing

We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, and code contributions!

Quick Start:

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/gigachat.git
cd gigachat

# Install dependencies and pre-commit hooks
make install

# Run all checks
make all

For detailed contributing guidelines, please see CONTRIBUTING.md.

This guide covers:

• Development setup and workflow
• Code quality standards and testing
• Commit message guidelines
• Pull request process
• Issue reporting guidelines
• Project architecture

All contributions are licensed under the MIT License.

License

This project is licensed under the MIT License.

Copyright © 2026 GigaChain