### Install Dependencies and Setup

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Navigate to the package directory and install dependencies using uv. Set up pre-commit hooks for code quality checks.

```bash
cd libs/gigachat
uv sync
```

```bash
make dev
```

--------------------------------

### Install langchain-gigachat

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/README.md

Install the library using pip. Use the -U flag to ensure you get the latest version.

```bash
pip install -U langchain-gigachat
```

--------------------------------

### Example: Format LangChain tool to GigaChat function

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/03-function-calling.md

Demonstrates formatting a LangChain tool, including extraction of extras like few-shot examples.

```python
from langchain_core.tools import tool
from langchain_gigachat.utils.function_calling import format_tool_to_gigachat_function

@tool(
    extras={
        "few_shot_examples": [
            {"city": "Paris", "unit": "celsius"}
        ],
        "return_schema": {"type": "string"}
    }
)
def get_weather(city: str, unit: str = "celsius") -> str:
    """Get current weather for a city."""
    return f"{city}: 22°C"

func_desc = format_tool_to_gigachat_function(get_weather)
print(func_desc.few_shot_examples)  # [{'city': 'Paris', 'unit': 'celsius'}]
```

--------------------------------

### Install GigaChat library

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/README.md

Install the package via pip.

```bash
pip install -U langchain-gigachat
```

--------------------------------

### Quick Start with GigaChat LLM

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/README.md

Initialize the GigaChat LLM with your authorization key and invoke it with a prompt. The response content is then printed.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-authorization-key")
msg = llm.invoke("Hello, GigaChat!")
print(msg.content)
```

--------------------------------

### Use LangChain tools with extras

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/03-function-calling.md

Configures tools with additional metadata like few-shot examples and custom return schemas.

```python
from langchain_core.tools import tool
from pydantic import BaseModel
from langchain_gigachat import GigaChat

class WeatherOutput(BaseModel):
    temperature: float
    condition: str

@tool(
    extras={
        "few_shot_examples": [
            {"city": "Paris", "unit": "celsius"}
        ],
        "return_schema": WeatherOutput
    }
)
def get_weather(city: str, unit: str = "celsius") -> str:
    """Get current weather."""
    return f"{city}: 22°C, sunny"

llm = GigaChat(credentials="your-auth-key")
llm_with_tools = llm.bind_tools([get_weather], tool_choice="auto")

response = llm_with_tools.invoke("What's the weather in Tokyo?")
print(response.tool_calls)
```

--------------------------------

### Convert tool to GigaChat tool format

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/03-function-calling.md

Example demonstrating the conversion of a decorated tool into a GigaChat-compatible tool dictionary.

```python
from langchain_core.tools import tool
from langchain_gigachat.utils.function_calling import convert_to_gigachat_tool

@tool
def calculate(expression: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expression))

tool_dict = convert_to_gigachat_tool(calculate)
print(tool_dict)
# Output: {
#     'type': 'function',
#     'function': {
#         'name': 'calculate',
#         'description': 'Evaluate a math expression.',
#         'parameters': {...}
#     }
# }
```

--------------------------------

### Advanced GigaChat Configuration

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Demonstrates mTLS setup using a custom SSL context and advanced model parameters.

```python
import ssl
from langchain_gigachat import GigaChat

# Custom SSL context for mTLS
ssl_context = ssl.create_default_context()
ssl_context.load_cert_chain(
    certfile="/path/to/cert.pem",
    keyfile="/path/to/key.pem",
    password=b"key-password"
)

llm = GigaChat(
    credentials="your-auth-key",
    model="GigaChat-2-Max",
    temperature=0.8,
    max_tokens=2048,
    ssl_context=ssl_context,
    timeout=30,
    max_retries=3,
    retry_backoff_factor=0.5,
    reasoning_effort="high",
    profanity_check=True,
    function_ranker={"enabled": False}
)
```

--------------------------------

### Example: Convert Python function to GigaChat function

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/03-function-calling.md

Demonstrates converting a standard Python function with type hints and docstrings.

```python
from langchain_gigachat.utils.function_calling import convert_python_function_to_gigachat_function

def get_weather(city: str, unit: str = "celsius") -> str:
    """Get current weather for a city.
    
    Args:
        city: City name to get weather for
        unit: Temperature unit (celsius or fahrenheit)
    
    Returns:
        Weather description string
    """
    return f"{city}: 22°C"

func_desc = convert_python_function_to_gigachat_function(get_weather)
print(func_desc.name)  # 'get_weather'
print(func_desc.parameters)  # JSON Schema
```

--------------------------------

### Configure mTLS and SSL context

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Provides examples for configuring mutual TLS using file paths or a custom SSL context.

```python
import ssl

llm = GigaChat(
    credentials="key",
    cert_file="/path/to/client-cert.pem",
    key_file="/path/to/client-key.pem",
    key_file_password="secret"
)

# Or use SSL context:
context = ssl.create_default_context()
context.load_cert_chain(
    "/path/to/cert.pem",
    "/path/to/key.pem",
    password=b"secret"
)
llm = GigaChat(credentials="key", ssl_context=context)
```

--------------------------------

### Check GigaChat Version

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/MIGRATION.md

Verify the installed version of the langchain-gigachat package.

```python
import langchain_gigachat
print(langchain_gigachat.__version__)  # "0.5.0"
```

--------------------------------

### Configure scope

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Defines the API scope field and provides a usage example.

```python
scope: Optional[str] = None
```

```python
llm = GigaChat(credentials="key", scope="GIGACHAT_API_B2B")
```

--------------------------------

### Embed documents synchronously

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Method signature and usage example for embedding a list of strings.

```python
def embed_documents(texts: List[str]) -> List[List[float]]
```

```python
from langchain_gigachat import GigaChatEmbeddings

embeddings = GigaChatEmbeddings(credentials="your-auth-key", model="Embeddings")
docs = ["Hello world", "GigaChat API", "Machine learning"]
vectors = embeddings.embed_documents(docs)
print(f"Generated {len(vectors)} embeddings")
print(f"Vector dimension: {len(vectors[0])}")
```

--------------------------------

### Checking Langchain-GigaChat Version

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Use `pip show` to find the installed version of the langchain-gigachat package, which is often required for bug reports.

```bash
pip show langchain-gigachat
```

--------------------------------

### Convert LangChain Tool to GigaChat Function

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Example of a Python function signature and docstring for converting a LangChain tool to a GigaChat function definition. Type hints are required.

```python
def convert_to_gigachat_function(
    tool: BaseTool,
) -> Function:
    """Convert a LangChain tool to a GigaChat function definition."""
    # Implementation here
```

--------------------------------

### Configure base_url

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Defines the API endpoint URL field and provides a usage example.

```python
base_url: Optional[str] = None
```

```python
llm = GigaChat(base_url="https://api.custom.gigachat.com/v1")
```

--------------------------------

### Embed documents asynchronously

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Async method signature and usage example for embedding a list of strings.

```python
async def aembed_documents(texts: List[str]) -> List[List[float]]
```

```python
import asyncio
from langchain_gigachat import GigaChatEmbeddings

async def main():
    embeddings = GigaChatEmbeddings(credentials="your-auth-key")
    vectors = await embeddings.aembed_documents(["text1", "text2"])
    print(vectors)

asyncio.run(main())
```

--------------------------------

### Define GigaFunctionDescription class

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/05-types.md

Structure for defining tools with GigaChat-specific extensions like return parameters and few-shot examples.

```python
class GigaFunctionDescription:
    name: str
    description: str
    parameters: Dict[str, Any]  # JSON Schema
    return_parameters: Optional[Dict[str, Any]] = None  # GigaChat extension
    few_shot_examples: Optional[List[Dict]] = None  # GigaChat extension
```

--------------------------------

### Clone Repository and Navigate

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Clone the repository and navigate to the project directory to begin development.

```bash
git clone https://github.com/YOUR_USERNAME/langchain-gigachat.git
cd langchain-gigachat
```

--------------------------------

### Initialize GigaChat with constructor parameters

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/00-index.md

Configure the GigaChat client instance with specific authentication, model, and request settings.

```python
llm = GigaChat(
    credentials="key",           # OAuth auth
    access_token="token",        # Or pre-obtained token
    scope="GIGACHAT_API_B2B",    # API scope
    model="GigaChat-2-Max",      # Model name
    temperature=0.8,             # Sampling temperature
    max_tokens=2000,             # Max response length
    top_p=0.9,                   # Nucleus sampling
    streaming=False,             # Stream by default
    timeout=30,                  # Request timeout
    max_retries=3,               # Retry attempts
    ca_bundle_file="/path/cert"  # TLS certificate
)
```

--------------------------------

### Initialize GigaChat from Environment

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Instantiate the GigaChat client using pre-configured environment variables.

```python
from langchain_gigachat import GigaChat

# All settings from environment
llm = GigaChat()
response = llm.invoke("Hello!")
```

--------------------------------

### Configure access_token

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Defines the JWT token field and provides a usage example for bypassing OAuth.

```python
access_token: Optional[str] = None
```

```python
# Use with pre-obtained token instead of credentials
llm = GigaChat(access_token="eyJhbGc...")
```

--------------------------------

### Initialize and Test GigaChat Package

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/README.md

Use these commands to synchronize dependencies and execute linting and testing for the package.

```bash
uv sync
make lint_package
make test
```

--------------------------------

### Embed a single query

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Method signature and usage example for embedding a single query string.

```python
def embed_query(text: str) -> List[float]
```

```python
from langchain_gigachat import GigaChatEmbeddings

embeddings = GigaChatEmbeddings(credentials="your-auth-key")
vector = embeddings.embed_query("What is AI?")
print(f"Query embedding dimension: {len(vector)}")
```

--------------------------------

### Initialize and Use Basic Embeddings

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Demonstrates creating an instance of GigaChatEmbeddings and generating vectors for a list of documents.

```python
from langchain_gigachat import GigaChatEmbeddings

# Create embeddings instance
embeddings = GigaChatEmbeddings(
    credentials="your-auth-key",
    model="Embeddings"
)

# Embed multiple documents
documents = [
    "Introduction to machine learning",
    "Deep learning techniques",
    "Natural language processing"
]
vectors = embeddings.embed_documents(documents)

# Print statistics
print(f"Embedded {len(vectors)} documents")
print(f"Vector dimension: {len(vectors[0])}")
```

--------------------------------

### Internal method _get_client_init_kwargs

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Builds the keyword arguments dictionary for initializing the GigaChat SDK client.

```python
def _get_client_init_kwargs(self) -> Dict[str, Any]
```

```python
# Internal method - not called directly
# But you can inspect what will be passed to SDK:
llm = GigaChat(credentials="key", model="GigaChat-2-Max")
kwargs = llm._get_client_init_kwargs()
print(kwargs)  # {'credentials': 'key', 'model': 'GigaChat-2-Max', ...}
```

--------------------------------

### Initialize GigaChatEmbeddings

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Constructor signature for configuring the GigaChat embedding client.

```python
GigaChatEmbeddings(
    base_url: Optional[str] = None,
    auth_url: Optional[str] = None,
    credentials: Optional[str] = None,
    scope: Optional[str] = None,
    access_token: Optional[str] = None,
    model: Optional[str] = None,
    timeout: Optional[float] = 600,
    verify_ssl_certs: Optional[bool] = None,
    ca_bundle_file: Optional[str] = None,
    cert_file: Optional[str] = None,
    key_file: Optional[str] = None,
    key_file_password: Optional[str] = None,
    ssl_context: Optional[ssl.SSLContext] = None,
    max_retries: Optional[int] = None,
    max_connections: Optional[int] = None,
    retry_backoff_factor: Optional[float] = None,
    retry_on_status_codes: Optional[Tuple[int, ...]] = None,
    prefix_query: str = "Дано предложение, необходимо найти его парафраз \nпредложение: ",
    use_prefix_query: bool = False,
) -> GigaChatEmbeddings
```

--------------------------------

### Configure Development Environment

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Sets environment variables for local development and initializes GigaChat using those defaults.

```bash
export GIGACHAT_CREDENTIALS="dev-key"
export GIGACHAT_SCOPE="GIGACHAT_API_PERS"
export GIGACHAT_BASE_URL="http://localhost:8000"
export GIGACHAT_VERIFY_SSL_CERTS="false"
export GIGACHAT_TIMEOUT="30"
```

```python
from langchain_gigachat import GigaChat

llm = GigaChat()  # All settings from env vars
response = llm.invoke("Hello!")
```

--------------------------------

### Run Quality Checks and Tests

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Execute make targets to format code, lint the package and tests, and run unit tests.

```bash
make format
```

```bash
make lint_package
```

```bash
make lint_tests
```

```bash
make test
```

--------------------------------

### Utilize Reasoning Models

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/00-index.md

Configure models with reasoning capabilities and adjust effort levels.

```python
llm = GigaChat(
    credentials="key",
    model="GigaChat-2-Reasoning",
    reasoning_effort="high"
)
response = llm.invoke("Complex question...")
print(response.additional_kwargs.get("reasoning_content"))
```

--------------------------------

### Configure Authentication and Connection

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Parameters for setting up authentication credentials and connection endpoints. These can also be configured via environment variables.

```python
GigaChat(
    credentials: Optional[str] = None,              # GIGACHAT_CREDENTIALS
    access_token: Optional[str] = None,             # GIGACHAT_ACCESS_TOKEN
    scope: Optional[str] = None,                    # GIGACHAT_SCOPE
    base_url: Optional[str] = None,                 # GIGACHAT_BASE_URL
    auth_url: Optional[str] = None,                 # GIGACHAT_AUTH_URL
    user: Optional[str] = None,                     # GIGACHAT_USER
    password: Optional[str] = None,                 # GIGACHAT_PASSWORD
)
```

--------------------------------

### Define nullable fields with constraints

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/08-pydantic-generator.md

Example of applying Pydantic Field constraints like ge and le while maintaining compatibility with GigaChatJsonSchema.

```python
from pydantic import BaseModel, Field
from langchain_gigachat.utils.pydantic_generator import GigaChatJsonSchema

class Task(BaseModel):
    name: str = Field(description="Task name")
    priority: int | None = Field(None, ge=1, le=5, description="Priority 1-5")
    tags: list[str] | None = Field(None, description="Task tags")

schema = Task.model_json_schema(schema_generator=GigaChatJsonSchema)
print(schema["properties"]["priority"])
# Output: {"type": "integer", "ge": 1, "le": 5, "description": "Priority 1-5"}
```

--------------------------------

### Initialize GigaChat Reasoning Model

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/MIGRATION.md

Configure the GigaChat model with reasoning capabilities and extract reasoning content from the response.

```python
llm = GigaChat(model="GigaChat-2-Reasoning", reasoning_effort="medium")
msg = llm.invoke([HumanMessage(content="Реши задачу...")])
reasoning = msg.additional_kwargs.get("reasoning_content")
```

--------------------------------

### GigaChatEmbeddings Constructor

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Initializes the GigaChatEmbeddings client with authentication and configuration parameters.

```APIDOC
## Constructor: GigaChatEmbeddings

### Description
Initializes the embedding model client. Requires credentials or an access token for authentication.

### Parameters
- **model** (str) - Optional - Model name (e.g., "Embeddings")
- **credentials** (str) - Optional - OAuth authorization key
- **access_token** (str) - Optional - Pre-obtained JWT token
- **scope** (str) - Optional - API scope (GIGACHAT_API_PERS, _B2B, _CORP)
- **timeout** (float) - Optional - Request timeout in seconds (default: 600)
- **prefix_query** (str) - Optional - Prefix to prepend to query strings
- **use_prefix_query** (bool) - Optional - Whether to apply prefix_query to query embeddings
```

--------------------------------

### Conventional Commit Message Example

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Follow this structure for commit messages: type: subject. The body provides context and explains the 'why'. The footer can reference issues or note breaking changes.

```git
feat: add retry mechanism for rate-limited requests

Implement exponential backoff with configurable max retries.
Handles 429 status codes and Retry-After headers.

Closes #45
```

```git
fix: handle tool_choice="any" gracefully

GigaChat API doesn't support "any". Convert to "auto"
when allow_any_tool_choice_fallback is set.
```

```git
docs: update SSL certificate setup in README

Add troubleshooting section for common certificate errors
on Windows and macOS.
```

```git
update stuff          # Too vague
Fixed a bug.          # Not imperative, no context
WIP                   # Not descriptive
```

--------------------------------

### Configure authentication environment variables

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/README.md

Set credentials and scope via environment variables for automatic SDK configuration.

```bash
export GIGACHAT_CREDENTIALS="your-authorization-key"
export GIGACHAT_SCOPE="GIGACHAT_API_PERS"  # GIGACHAT_API_B2B or GIGACHAT_API_CORP for enterprise
```

--------------------------------

### Initialize GigaChatEmbeddings

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/00-index.md

Instantiate the GigaChatEmbeddings class to generate vector representations of text.

```python
from langchain_gigachat import GigaChatEmbeddings

embeddings = GigaChatEmbeddings(credentials="your-key")
vector = embeddings.embed_query("What is AI?")
```

--------------------------------

### Initialize GigaChat Reasoning Models

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Configure the GigaChat model with reasoning capabilities by setting the model name and reasoning effort.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(
    credentials="your-key",
    model="GigaChat-2-Reasoning",
    reasoning_effort="high"
)

response = llm.invoke("How many r's in 'strawberry'?")
print("Answer:", response.content)
print("Reasoning:", response.additional_kwargs.get("reasoning_content"))
```

--------------------------------

### Configure GigaChat Credentials

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Set up environment variables for GigaChat API access by creating a .env file in the libs/gigachat directory.

```bash
GIGACHAT_CREDENTIALS=your_oauth_credentials_here
GIGACHAT_SCOPE=GIGACHAT_API_PERS
```

--------------------------------

### Initialize GigaChatEmbeddings with Prefix Query

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Enables the prefix query feature to handle query-document asymmetry. The default prefix is optimized for finding paraphrases in Russian.

```python
embeddings = GigaChatEmbeddings(
    credentials="your-auth-key",
    use_prefix_query=True
    # Default prefix: "Дано предложение, необходимо найти его парафраз \nпредложение: "
)
```

--------------------------------

### Configure Production Environment

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Sets production-specific environment variables and initializes GigaChat with explicit parameters.

```bash
export GIGACHAT_CREDENTIALS="prod-key"
export GIGACHAT_SCOPE="GIGACHAT_API_CORP"
export GIGACHAT_CA_BUNDLE_FILE="/etc/ssl/certs/ca-bundle.crt"
export GIGACHAT_MAX_RETRIES="3"
export GIGACHAT_RETRY_BACKOFF_FACTOR="1.0"
export GIGACHAT_TIMEOUT="60"
```

```python
from langchain_gigachat import GigaChat

llm = GigaChat(
    max_tokens=2000,
    temperature=0.7,
    max_connections=50
)
```

--------------------------------

### Run Unit Tests

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Command to execute all unit tests. This is the default test command and includes coverage reporting.

```bash
make test
```

--------------------------------

### Run Integration Tests

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Command to run integration tests. This requires GigaChat credentials to be set up.

```bash
make integration_test
```

--------------------------------

### Initialize and Invoke GigaChat

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/README.md

Basic usage for initializing the GigaChat client and invoking a simple prompt.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-authorization-key")

msg = llm.invoke("Hello, GigaChat!")
print(msg.content)
```

--------------------------------

### Configure GigaChat Credentials

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Set the GigaChat credentials via environment variables to initialize the client.

```python
import os
os.environ["GIGACHAT_CREDENTIALS"] = "your-actual-key"

from langchain_gigachat import GigaChat
llm = GigaChat()  # Reads from environment
```

--------------------------------

### Handle Unsupported Tool Choice

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Resolve tool choice errors by switching to 'auto' mode or enabling the fallback mechanism.

```python
from langchain_gigachat import GigaChat

# Option 1: Use 'auto' instead
llm = GigaChat(credentials="your-key")
llm_with_tools = llm.bind_tools(tools, tool_choice="auto")

# Option 2: Enable fallback
llm = GigaChat(
    credentials="your-key",
    allow_any_tool_choice_fallback=True
)
```

--------------------------------

### View Package Module Structure

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/README.md

Displays the directory layout and primary class implementations within the langchain_gigachat package.

```text
langchain_gigachat/
├── __init__.py                          [GigaChat, GigaChatEmbeddings]
├── _client.py                           [_GigaChatClientMixin]
├── chat_models/
│   ├── __init__.py                      [GigaChat]
│   ├── gigachat.py                      [GigaChat implementation]
│   └── base_gigachat.py                 [_BaseGigaChat]
├── embeddings/
│   ├── __init__.py                      [GigaChatEmbeddings]
│   └── gigachat.py                      [GigaChatEmbeddings implementation]
└── utils/
    ├── __init__.py                      [Tool conversion exports]
    ├── function_calling.py              [Tool conversion functions]
    └── pydantic_generator.py            [GigaChatJsonSchema]
```

--------------------------------

### List and Select Models

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Retrieves available models and initializes the GigaChat client with a specific model identifier.

```python
from langchain_gigachat import GigaChat

# Check available models
llm = GigaChat(credentials="your-key")
models = llm.get_models()
for m in models.data:
    print(m.id)

# Use specific model
llm = GigaChat(credentials="your-key", model="GigaChat-2-Max")
```

--------------------------------

### Configure CA Bundle File

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Specify the path to a CA certificate bundle.

```python
ca_bundle_file: Optional[str] = None
```

```python
llm = GigaChat(
    credentials="key",
    ca_bundle_file="/etc/ssl/certs/ca-bundle.crt"
)
```

--------------------------------

### Configure SSL and mTLS

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Settings for managing SSL verification and client certificates.

```python
GigaChat(
    verify_ssl_certs: Optional[bool] = None,        # GIGACHAT_VERIFY_SSL_CERTS
    ca_bundle_file: Optional[str] = None,           # GIGACHAT_CA_BUNDLE_FILE
    cert_file: Optional[str] = None,                # GIGACHAT_CERT_FILE
    key_file: Optional[str] = None,                 # GIGACHAT_KEY_FILE
    key_file_password: Optional[str] = None,        # GIGACHAT_KEY_FILE_PASSWORD
    ssl_context: Optional[ssl.SSLContext] = None,   # (no env var)
)
```

--------------------------------

### Configure SSL Certificate

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Provide a custom CA bundle file for SSL verification.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(
    credentials="your-key",
    ca_bundle_file="/etc/ssl/certs/ca-bundle.crt"
)
```

--------------------------------

### Configure GigaChat via Environment Variables

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Set credentials and model parameters using shell environment variables.

```bash
# Set environment variables
export GIGACHAT_CREDENTIALS="your-key"
export GIGACHAT_MODEL="GigaChat-2-Max"
export GIGACHAT_TEMPERATURE="0.8"
export GIGACHAT_MAX_TOKENS="2000"
```

--------------------------------

### Convert Python functions for GigaChat

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/03-function-calling.md

Shows how to bind standard Python functions as tools for the GigaChat LLM.

```python
from langchain_gigachat import GigaChat

def fetch_data(endpoint: str, limit: int = 100) -> dict:
    """Fetch data from API.
    
    Args:
        endpoint: API endpoint path
        limit: Maximum items to fetch
    
    Returns:
        JSON response from API
    """
    return {"data": []}

llm = GigaChat(credentials="your-auth-key")
llm_with_tools = llm.bind_tools([fetch_data])
```

--------------------------------

### Basic Chat with GigaChat

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/01-gigachat.md

Initialize the GigaChat client and invoke a simple text prompt.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-auth-key", model="GigaChat-2-Max")
response = llm.invoke("Hello, GigaChat!")
print(response.content)
```

--------------------------------

### Enable streaming by default

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/10-streaming.md

Configure the GigaChat instance to enable streaming behavior globally.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(
    credentials="your-key",
    streaming=True  # Stream by default
)

# invoke() now streams
for chunk in llm.stream("Hello"):
    print(chunk.content, end="", flush=True)
```

--------------------------------

### Tool Calling with LangChain

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/01-gigachat.md

Define a tool and bind it to the GigaChat instance to enable automatic tool selection.

```python
from langchain_core.tools import tool
from langchain_gigachat import GigaChat

@tool(extras={"few_shot_examples": [{"request": "weather Tokyo", "params": {"city": "Tokyo"}}]})
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"{city}: sunny, 22°C"

llm = GigaChat()
llm_with_tools = llm.bind_tools([get_weather], tool_choice="auto")
response = llm_with_tools.invoke("What's the weather in Tokyo?")
print(response.tool_calls)
```

--------------------------------

### Import GigaChat Utilities

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/MIGRATION.md

Access public utility functions for tool and function conversion.

```python
from langchain_gigachat.utils import convert_to_gigachat_function, convert_to_gigachat_tool
```

--------------------------------

### GigaChat Client Initialization

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

The GigaChat client can be initialized with various parameters for authentication, connection, and model selection. It supports direct parameter passing or automatic configuration via environment variables.

```APIDOC
## GigaChat Initialization

### Description
Initializes the GigaChat client for interacting with the GigaChat API. Configuration can be provided directly or via environment variables.

### Parameters
- **credentials** (str) - Optional - Authentication key.
- **scope** (str) - Optional - API scope (e.g., GIGACHAT_API_B2B).
- **base_url** (str) - Optional - API base URL.
- **timeout** (int) - Optional - Request timeout in seconds.
- **max_connections** (int) - Optional - Maximum number of connections.
- **verify_ssl_certs** (bool) - Optional - Whether to verify SSL certificates.
- **ca_bundle_file** (str) - Optional - Path to CA bundle file.
- **max_retries** (int) - Optional - Maximum number of retries.
- **retry_backoff_factor** (float) - Optional - Backoff factor for retries.
- **model** (str) - Optional - Model identifier (e.g., GigaChat-2-Max).
- **cert_file** (str) - Optional - Path to client certificate for mTLS.
- **key_file** (str) - Optional - Path to client key for mTLS.
- **key_file_password** (str) - Optional - Password for key file.
- **ssl_context** (ssl.SSLContext) - Optional - Custom SSL context.

### Example
```python
from langchain_gigachat import GigaChat

llm = GigaChat(
    credentials="your-auth-key",
    model="GigaChat-2-Max",
    timeout=30
)
```
```

--------------------------------

### Use Legacy bind_functions

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/README.md

Utilize bind_functions for legacy LangChain flows, though bind_tools is recommended for new implementations.

```python
from langchain_gigachat import GigaChat


def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"{city}: sunny, 22C"


llm = GigaChat()
llm_with_functions = llm.bind_functions(
    [get_weather],
    function_call="auto",
)
```

--------------------------------

### Import Function Calling Utilities

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/00-index.md

Use these utilities to convert LangChain tools or functions for use with GigaChat.

```python
from langchain_gigachat.utils import (
    convert_to_gigachat_function,
    convert_to_gigachat_tool,
)
```

--------------------------------

### GigaChat Client Configuration Fields

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Configuration parameters for initializing GigaChat and GigaChatEmbeddings clients.

```APIDOC
## GigaChat Client Configuration

### Connection Fields
- **timeout** (float) - Optional - Request timeout in seconds. Environment variable: `GIGACHAT_TIMEOUT`.
- **max_connections** (int) - Optional - Maximum simultaneous connections to GigaChat API. Environment variable: `GIGACHAT_MAX_CONNECTIONS`.

### SSL/TLS Fields
- **verify_ssl_certs** (bool) - Optional - Verify TLS certificates. Default: `True`. Environment variable: `GIGACHAT_VERIFY_SSL_CERTS`.
- **ca_bundle_file** (str) - Optional - Path to CA certificate bundle. Environment variable: `GIGACHAT_CA_BUNDLE_FILE`.
- **cert_file** (str) - Optional - Path to client certificate (for mTLS). Environment variable: `GIGACHAT_CERT_FILE`.
- **key_file** (str) - Optional - Path to client private key (for mTLS). Environment variable: `GIGACHAT_KEY_FILE`.
- **key_file_password** (str) - Optional - Password for encrypted private key. Environment variable: `GIGACHAT_KEY_FILE_PASSWORD`.
- **ssl_context** (ssl.SSLContext) - Optional - Custom SSL context object.

### Model Selection
- **model** (str) - Optional - Model name to use. Environment variable: `GIGACHAT_MODEL`.
```

--------------------------------

### Configure Private Key Password

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Provide a password for an encrypted private key.

```python
key_file_password: Optional[str] = None
```

```python
llm = GigaChat(
    credentials="key",
    key_file="/path/to/key.pem",
    key_file_password="my-key-passphrase"
)
```

--------------------------------

### Configure GigaChatEmbeddings Query Prefix

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Set a custom prefix for queries and toggle its usage.

```python
GigaChatEmbeddings(
    prefix_query: str = "Дано предложение, необходимо найти его парафраз \nпредложение: ",
    use_prefix_query: bool = False,
)
```

--------------------------------

### Import Tool Types

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/00-index.md

Classes for defining and handling tool calls.

```python
from langchain_core.messages import ToolCall, ToolCallChunk
from langchain_core.tools import BaseTool
```

--------------------------------

### Synchronous streaming usage

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/10-streaming.md

Demonstrates iterating over message chunks as they arrive from the GigaChat model.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-key")
for chunk in llm.stream("Write a haiku"):
    print(chunk.content, end="", flush=True)
print()  # Newline after streaming completes
```

--------------------------------

### Configure mTLS Client Certificates

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Set paths for client certificate and private key for mTLS authentication.

```python
cert_file: Optional[str] = None
```

```python
key_file: Optional[str] = None
```

```python
llm = GigaChat(
    credentials="key",
    cert_file="/path/to/client-cert.pem",
    key_file="/path/to/client-key.pem"
)
```

--------------------------------

### Initialize GigaChat Model

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/00-index.md

Instantiate the GigaChat class with credentials to interact with the API.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-key")
response = llm.invoke("Hello!")
```

--------------------------------

### Configure user

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Defines the username field for basic authentication.

```python
user: Optional[str] = None
```

--------------------------------

### Configure GigaChatEmbeddings Authentication

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Set authentication credentials, access tokens, and connection URLs for the GigaChat service.

```python
GigaChatEmbeddings(
    credentials: Optional[str] = None,
    access_token: Optional[str] = None,
    scope: Optional[str] = None,
    base_url: Optional[str] = None,
    auth_url: Optional[str] = None,
)
```

--------------------------------

### Configure GigaChat Embeddings

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Initializes GigaChatEmbeddings with custom timeout and query prefix settings.

```python
from langchain_gigachat import GigaChatEmbeddings

embeddings = GigaChatEmbeddings(
    model="Embeddings",
    credentials="your-auth-key",
    timeout=600,  # Longer timeout for embeddings
    use_prefix_query=True,
    prefix_query="Query: ",  # Custom prefix instead of default Russian prefix
    max_retries=2
)
```

--------------------------------

### Share configuration between Chat and Embeddings

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Demonstrates reusing a dictionary of configuration settings for both GigaChat and GigaChatEmbeddings instances.

```python
from langchain_gigachat import GigaChat, GigaChatEmbeddings

# Common settings
auth_config = {
    "credentials": "shared-auth-key",
    "scope": "GIGACHAT_API_CORP",
    "ca_bundle_file": "/etc/ssl/certs/ca-bundle.crt",
    "max_retries": 3
}

# Chat model
llm = GigaChat(**auth_config, model="GigaChat-2-Max")

# Embeddings (reuses same config)
embeddings = GigaChatEmbeddings(**auth_config, model="Embeddings")
```

--------------------------------

### Use Pydantic Model Methods

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/05-types.md

Demonstrates serialization and reconstruction of Pydantic models using model_dump.

```python
from langchain_core.messages import AIMessage

msg = AIMessage(content="Hello", tool_calls=[])
data = msg.model_dump()
restored = AIMessage(**data)
```

--------------------------------

### Upload and manage files

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/01-gigachat.md

Methods for uploading, retrieving, and listing files associated with the GigaChat instance.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-auth-key")
with open("document.pdf", "rb") as f:
    uploaded = llm.upload_file(("document.pdf", f.read()))
print(f"File ID: {uploaded.id_}")
```

```python
content = llm.get_file_content(file_id)
print(content.content[:20])  # First 20 chars of base64
```

```python
files = llm.list_files()
for f in files.data:
    print(f"{f.id_}: {f.filename}")
```

--------------------------------

### Configure GigaChatEmbeddings SSL/mTLS

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Provide SSL certificates, keys, and custom SSL contexts for secure connections.

```python
GigaChatEmbeddings(
    verify_ssl_certs: Optional[bool] = None,
    ca_bundle_file: Optional[str] = None,
    cert_file: Optional[str] = None,
    key_file: Optional[str] = None,
    key_file_password: Optional[str] = None,
    ssl_context: Optional[ssl.SSLContext] = None,
)
```

--------------------------------

### Implement Basic Try-Catch Error Handling

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/06-errors.md

Demonstrates catching specific GigaChat exceptions during synchronous invocation.

```python
from gigachat.exceptions import AuthenticationError, RateLimitError, GigaChatException
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="auth-key")

try:
    response = llm.invoke("Hello, GigaChat!")
except AuthenticationError as e:
    print(f"Authentication failed: {e}")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after}s")
except GigaChatException as e:
    print(f"GigaChat error: {e}")
```

--------------------------------

### Manage memory during streaming

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/10-streaming.md

Demonstrates memory-efficient processing by handling chunks individually versus collecting them into a list.

```python
# Good: Streaming with immediate processing
for chunk in llm.stream("Long response"):
    process(chunk)  # Handle chunk immediately
    # Chunk is garbage collected after processing

# More memory: Collecting all chunks
chunks = list(llm.stream("Long response"))  # Holds all chunks in memory
```

--------------------------------

### Implement Tool Calling

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Bind tools to the model to enable function calling capabilities.

```python
from langchain_core.tools import tool
from langchain_gigachat import GigaChat

@tool
def get_weather(city: str) -> str:
    """Get weather for a city."""
    return f"{city}: 22°C, sunny"

llm = GigaChat(credentials="your-key")
llm_with_tools = llm.bind_tools([get_weather], tool_choice="auto")

response = llm_with_tools.invoke("What's the weather in Paris?")
print(response.tool_calls)
```

--------------------------------

### Run Pre-commit Hooks Manually

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/CONTRIBUTING.md

Manually run all pre-commit hooks across all files to ensure code quality before committing.

```bash
pre-commit run --all-files
```

--------------------------------

### Authenticate with GigaChat

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Set credentials via environment variable or pass them directly to the constructor.

```bash
export GIGACHAT_CREDENTIALS="your-authorization-key"
```

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-authorization-key")
```

--------------------------------

### Perform Basic Chat

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Invoke the model to generate a response from a text prompt.

```python
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-key")
response = llm.invoke("Hello, GigaChat!")
print(response.content)
```

--------------------------------

### Handle RuntimeError for missing tool description

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/06-errors.md

Shows how to catch a RuntimeError when a tool lacks the required description.

```python
from langchain_core.tools import tool
from langchain_gigachat.utils.function_calling import format_tool_to_gigachat_function

@tool  # Missing description
def my_tool() -> str:
    return "result"

try:
    func = format_tool_to_gigachat_function(my_tool)
except RuntimeError as e:
    print(f"Error: {e}")  # "Incorrect function or tool description. Description is required."
```

--------------------------------

### Configure TLS certificate path

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/README.md

Specify a custom CA bundle file path for environments requiring specific TLS certificates.

```bash
export GIGACHAT_CA_BUNDLE_FILE="/path/to/certs.pem"
```

--------------------------------

### Update tool_choice configuration

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/libs/gigachat/MIGRATION.md

The tool_choice='any' argument now raises a ValueError. Use 'auto', a specific tool name, or enable the fallback option.

```python
# Before — silently degraded to "auto"
llm.bind_tools(tools, tool_choice="any")

# After — raises ValueError. Two options:

# Option 1: use "auto" or a specific tool name
llm.bind_tools(tools, tool_choice="auto")
llm.bind_tools(tools, tool_choice="my_tool_name")

# Option 2: opt-in to automatic fallback (with warning)
llm = GigaChat(allow_any_tool_choice_fallback=True, ...)
llm.bind_tools(tools, tool_choice="any")  # converts to "auto" with UserWarning
```

--------------------------------

### Configure Token Counting

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Toggle for using the API to perform token counting.

```python
GigaChat(
    use_api_for_tokens: bool = False,               # GIGACHAT_USE_API_FOR_TOKENS
)
```

--------------------------------

### Embed Queries and Calculate Similarity

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/02-embeddings.md

Shows how to embed documents and queries, including the use of query prefixes and manual cosine similarity calculation.

```python
from langchain_gigachat import GigaChatEmbeddings

embeddings = GigaChatEmbeddings(credentials="your-auth-key")

# Embed documents (without prefix)
docs = ["Python programming", "JavaScript web development"]
doc_vectors = embeddings.embed_documents(docs)

# Embed query (optionally with prefix)
embeddings_with_prefix = GigaChatEmbeddings(
    credentials="your-auth-key",
    use_prefix_query=True,
    prefix_query="Find similar items to: "
)
query_vector = embeddings_with_prefix.embed_query("machine learning tutorial")

# Compare similarity
import math
def cosine_similarity(a, b):
    dot_product = sum(x * y for x, y in zip(a, b))
    norm_a = math.sqrt(sum(x * x for x in a))
    norm_b = math.sqrt(sum(x * x for x in b))
    return dot_product / (norm_a * norm_b)

for i, doc_vec in enumerate(doc_vectors):
    similarity = cosine_similarity(query_vector, doc_vec)
    print(f"Doc {i+1} similarity: {similarity:.4f}")
```

--------------------------------

### Upload and Reference Files

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/09-quick-start.md

Uploads local files to GigaChat and references them within a HumanMessage using file IDs.

```python
from langchain_core.messages import HumanMessage
from langchain_gigachat import GigaChat

llm = GigaChat(credentials="your-key")

# Upload file
with open("image.png", "rb") as f:
    uploaded = llm.upload_file(("image.png", f.read()))

# Reference in message
msg = HumanMessage(
    content_blocks=[
        {"type": "text", "text": "Describe this image."},
        {"type": "image", "file_id": uploaded.id_},
    ]
)

response = llm.invoke([msg])
print(response.content)
```

--------------------------------

### Configure GigaChatEmbeddings Model Settings

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Define the model name and request timeout duration.

```python
GigaChatEmbeddings(
    model: Optional[str] = None,                    # GIGACHAT_MODEL
    timeout: Optional[float] = 600,                 # GIGACHAT_TIMEOUT (default: 600s)
)
```

--------------------------------

### Configure Custom SSL Context

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/07-client-mixin.md

Pass a custom ssl.SSLContext object to the client.

```python
ssl_context: Optional[ssl.SSLContext] = None
```

```python
import ssl

context = ssl.create_default_context()
context.load_cert_chain(
    certfile="/path/to/cert.pem",
    keyfile="/path/to/key.pem"
)

llm = GigaChat(credentials="key", ssl_context=context)
```

--------------------------------

### Configure Retry and Timeout

Source: https://github.com/ai-forever/langchain-gigachat/blob/master/_autodocs/04-configuration.md

Settings for network request timeouts and retry strategies.

```python
GigaChat(
    timeout: Optional[float] = None,                # GIGACHAT_TIMEOUT
    max_retries: Optional[int] = None,              # GIGACHAT_MAX_RETRIES
    max_connections: Optional[int] = None,          # GIGACHAT_MAX_CONNECTIONS
    retry_backoff_factor: Optional[float] = None,   # GIGACHAT_RETRY_BACKOFF_FACTOR
    retry_on_status_codes: Optional[Tuple[int, ...]] = None,  # (no env var)
)
```