### Providing Few-Shot Examples for Tool Usage

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Illustrates how to provide few-shot examples to guide the model on how to use a tool, including sample requests and parameters.

```java
fewShotExamples = {
    @FewShotExample(
        request = "What's the weather like in Paris?",
        params = "{\"city\": \"Paris\"}"
    )
}
```

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

### Complete Example Configuration

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

A comprehensive configuration example for Spring AI GigaChat, including chat, embedding, image generation, authentication, internal settings, and observability.

```yaml
spring:
  application:
    name: gigachat-app
  ai:
    gigachat:
      # Chat model defaults
      chat:
        options:
          model: GigaChat-2
          temperature: 0.7
          top-p: 0.95
          max-tokens: 2000
          repetition-penalty: 1.1
          profanity-check: false
      
      # Embedding model defaults
      embedding:
        options:
          model: Embeddings-2
          dimensions: 1024
      
      # Image generation defaults
      image:
        options:
          model: GigaChat-2
          style: realistic
          response-format: url
      
      # Authentication
      auth:
        bearer:
          api-key: ${GIGACHAT_API_KEY}
        scope: GIGACHAT_API_PERS
        unsafe-ssl: false
        certs:
          ca-certs: file:/path/to/russian_trusted_root_ca.cer
      
      # Internal settings
      internal:
        connect-timeout: 20s
        read-timeout: 60s
        make-system-prompt-first-message-in-memory: true

# Actuator for observability
management:
  endpoints:
    web:
      exposure:
        include: health,metrics
  metrics:
    export:
      simple:
        enabled: true
```

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

### Hello World Chat Client Example

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

A basic Spring Boot application demonstrating how to use `ChatClient` to interact with GigaChat. This example sends a prompt and prints the response.

```java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.ai.chat.client.ChatClient;

@SpringBootApplication
public class Main {
    
    public static void main(String[] args) {
        SpringApplication.run(Main.class, args);
    }
    
    @Bean
    public CommandLineRunner runner(ChatClient.Builder builder) {
        return args -> {
            ChatClient chatClient = builder.build();
            String response = chatClient.prompt("Hello GigaChat!").call().content();
            System.out.println(response);
        };
    }
}
```

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

### Tool with Few-Shot Examples

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Defines a calculator tool that includes few-shot examples to guide the model. These examples provide specific request-parameter pairs for arithmetic expressions.

```java
@Component
public class CalculatorService {
    
    @GigaTool(
        name = "calculate",
        description = "Perform arithmetic calculations",
        fewShotExamples = {
            @FewShotExample(
                request = "What is 5 plus 3?",
                params = "{\"expression\": \"5+3\"}"
            ),
            @FewShotExample(
                request = "Calculate 10 times 4",
                params = "{\"expression\": \"10*4\"}"
            )
        }
    )
    public String calculate(
        @ToolParam(description = "Mathematical expression") String expression
    ) {
        // Evaluate expression
        return String.valueOf(eval(expression));
    }
}

```

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

### Download with Session ID Example (Java)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/file-operations.md

This example shows how to attach a custom session ID to the HTTP headers when downloading a file. This can be useful for tracking requests or maintaining session state.

```java
HttpHeaders headers = new HttpHeaders();
headers.add("X-Session-Id", "session-123");

byte[] content = gigaChatApi.downloadFile(fileId, headers);
```

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

### Building GigaChatImageOptions

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-image-model.md

Example of programmatically building GigaChatImageOptions with specific model, style, and response format.

```java
GigaChatImageOptions options = GigaChatImageOptions.builder()
    .model("GigaChat-2")
    .style("oil_painting")
    .responseFormat(GigaChatImageOptions.RESPONSE_FORMAT_URL)
    .build();
```

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

### Java Example for Blocking Chat Completion

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-model.md

Demonstrates how to use the call() method to get a single chat response. Ensure you have initialized the GigaChat model and ChatClient.

```java
ChatClient chatClient = ChatClient.builder(gigaChatModel).build();
String response = chatClient.prompt("Tell me a joke").call().content();
System.out.println(response);
```

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

### Java Example for Fetching Available Models

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-model.md

Demonstrates how to retrieve and iterate through the list of available GigaChat models. Each model's name is printed to the console.

```java
List<ModelDescription> availableModels = gigaChatModel.models();
availableModels.forEach(m -> System.out.println(m.getName()));
```

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

### FewShotExample Record

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/types.md

Represents an example for few-shot learning within a function description. It includes the request and its corresponding parameters.

```java
public record FewShotExample(
    @JsonProperty("request") String request,
    @JsonProperty("params") @JsonRawValue String params) {}

```

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

### Example of Building GigaChat Options

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Demonstrates how to use the GigaChatOptions builder to configure model, generation parameters, tool names, internal tool execution, and custom HTTP headers.

```java
GigaChatOptions options = GigaChatOptions.builder()
    .model("GigaChat-2")
    .temperature(0.5)
    .topP(0.95)
    .maxTokens(500)
    .toolNames("weather", "calculator")
    .internalToolExecutionEnabled(true)
    .httpHeaders(Map.of("X-Custom-Header", "value"))
    .build();
```

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

### Example: Upload Image Service

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/file-operations.md

A service class demonstrating how to read image bytes from a file and upload it using GigaChatApi. Requires an instance of GigaChatApi.

```java
@Service
public class ImageUploadService {
    
    private final GigaChatApi gigaChatApi;
    
    public UUID uploadImage(File imageFile) throws IOException {
        byte[] imageBytes = Files.readAllBytes(imageFile.toPath());
        
        Media media = Media.builder()
            .name(imageFile.getName())
            .data(new ByteArrayResource(imageBytes))
            .mimeType(MimeTypeUtils.IMAGE_JPEG)
            .build();
        
        ResponseEntity<UploadFileResponse> response = gigaChatApi.uploadFile(media);
        return response.getBody().id();
    }
}
```

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

### FewShotExample Annotation Definition

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Defines the structure for few-shot examples used in tool definitions. It includes user request examples and corresponding tool parameters in JSON format.

```java
@Target({ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface FewShotExample {
    String request();      // User request example
    String params();       // Tool parameters as JSON
}
```

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

### FewShotExample Record Definition

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

A record representing a few-shot example, containing a user prompt example and its associated JSON parameters.

```java
public record FewShotExample(
    String request,        // User prompt example
    String params          // JSON parameters
) {}

```

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

### Java Example for Streaming Chat Completion

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-model.md

Shows how to use the stream() method to process chat responses chunk by chunk. The output will be printed as each chunk is received.

```java
chatClient.prompt("Write a poem about spring")
    .stream()
    .content()
    .subscribe(chunk -> System.out.print(chunk));
```

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

### Image Generation Example with GigaChatImageModel

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-image-model.md

Demonstrates how to use GigaChatImageModel to generate an image from a text prompt, specifying response format and style. It handles both base64 and URL image outputs.

```java
ImagePrompt prompt = new ImagePrompt(
    "A serene landscape with mountains and a lake",
    GigaChatImageOptions.builder()
        .responseFormat(GigaChatImageOptions.RESPONSE_FORMAT_BASE64)
        .style("realistic")
        .build()
);

ImageResponse response = imageModel.call(prompt);
response.getResults().forEach(generation -> {
    Image image = generation.getImage();
    if (image.getB64Json() != null) {
        // Use base64-encoded image
        System.out.println("Generated image (base64): " + image.getB64Json());
    } else if (image.getUrl() != null) {
        // Use image URL
        System.out.println("Generated image URL: " + image.getUrl());
    }
});
```

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

### Multimodal Chat Service with Image Analysis and Cleanup

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/response-metadata.md

An example service demonstrating how to send an image with a question, process the response, and clean up uploaded media files. It handles potential exceptions during file deletion.

```java
@Service
public class MultimodalChatService {
    
    private final ChatClient chatClient;
    private final GigaChatApi gigaChatApi;
    
    public String analyzeImageAndCleanup(byte[] imageData, String question) {
        // Create multimodal message
        Media image = Media.builder()
            .name("image.jpg")
            .data(new ByteArrayResource(imageData))
            .mimeType(MimeTypeUtils.IMAGE_JPEG)
            .build();
        
        UserMessage message = new UserMessage(question, List.of(image));
        
        // Get response
        ChatResponse response = chatClient.prompt(message).call();
        String answer = response.getContent();
        
        // Clean up uploaded files
        @SuppressWarnings("unchecked")
        List<String> uploadedIds = (List<String>) 
            response.getMetadata().get(GigaChatModel.UPLOADED_MEDIA_IDS);
        
        if (uploadedIds != null) {
            uploadedIds.forEach(id -> {
                try {
                    gigaChatApi.deleteFile(id);
                } catch (Exception e) {
                    logger.warn("Failed to cleanup file {}", id);
                }
            });
        }
        
        return answer;
    }
}
```

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

### Download Generated Image (Java)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/file-operations.md

Example demonstrating how to generate an image, extract its file ID from the response metadata, and then download the image bytes using the `downloadFile` method. The downloaded bytes are then written to a file.

```java
// Generate image
ImagePrompt prompt = new ImagePrompt("A sunset landscape",
    GigaChatImageOptions.builder()
        .responseFormat(GigaChatImageOptions.RESPONSE_FORMAT_B64_JSON)
        .build());

ImageResponse response = imageModel.call(prompt);

// Get file ID from metadata
ImageGenerationMetadata metadata = 
    (ImageGenerationMetadata) response.getResult().getMetadata();
String fileId = metadata.toString(); // Contains file ID

// Download image
byte[] imageBytes = gigaChatApi.downloadFile(fileId);
Files.write(Paths.get("generated.jpg"), imageBytes);
```

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

### Streaming Chat API Endpoint

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

This example demonstrates how to implement a streaming chat endpoint. It returns a Flux of strings, allowing for real-time responses from the chat model.

```java
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.ai.chat.client.ChatClient;
import reactor.core.publisher.Flux;

@GetMapping("/stream")
public Flux<String> stream(@RequestParam String prompt) {
    return chatClient.prompt(prompt)
        .stream()
        .content();
}
```

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

### CustomGigaAuthToken Implementation

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/authentication.md

An example of a custom GigaAuthToken implementation that uses a TokenProvider to fetch the latest token. Useful for dynamic token retrieval.

```java
public class CustomGigaAuthToken implements GigaAuthToken {
    
    private final TokenProvider tokenProvider;
    
    public CustomGigaAuthToken(TokenProvider tokenProvider) {
        this.tokenProvider = tokenProvider;
    }
    
    @Override
    public String getAuthorizationToken() {
        return tokenProvider.getLatestToken();
    }
}
```

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

### Graceful Error Handling within Tool Logic

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Provides an example of a try-catch block within tool logic to handle potential exceptions gracefully and return an error message.

```java
try {
    // tool logic
} catch (Exception e) {
    return "Error: " + e.getMessage();
}
```

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

### Get File Download URL

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-api.md

Constructs a full, downloadable URL for a given file ID. This URL can be used to access the file directly from GigaChat's servers.

```java
String url = gigaChatApi.getFileUrl("550e8400-e29b-41d4-a716-446655440000");
// Returns: "https://gigachat.devices.sberbank.ru/api/v1/files/550e8400-e29b-41d4-a716-446655440000/content"
```

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

### GigaChatOptions Tool Calling Methods

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Methods for configuring and managing tool callbacks and execution within GigaChat options. These include setting and getting tool callbacks, tool names, internal tool execution status, and tool context.

```APIDOC
## Tool Calling Methods

```java
@Override
@JsonIgnore
public List<ToolCallback> getToolCallbacks()

@Override
@JsonIgnore
public void setToolCallbacks(List<ToolCallback> toolCallbacks)

@Override
@JsonIgnore
public Set<String> getToolNames()

@Override
@JsonIgnore
public void setToolNames(Set<String> toolNames)

@Override
@Nullable
@JsonIgnore
public Boolean getInternalToolExecutionEnabled()

@Override
@JsonIgnore
public void setInternalToolExecutionEnabled(@Nullable Boolean internalToolExecutionEnabled)

@Override
public Map<String, Object> getToolContext()

@Override
public void setToolContext(Map<String, Object> toolContext)
```
```

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

### Get GigaChat Model Name

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-api.md

Retrieves the API-ready name for a GigaChat model. This example shows how to get the name for GigaChat-2.

```java
String modelName = ChatModel.GIGA_CHAT_2.getName(); // "GigaChat-2"
```

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

### Defining a Tool with Name and Description

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Shows how to define a tool with a specific name and a descriptive explanation for its functionality.

```java
@GigaTool(
    name = "getWeatherForecast",
    description = "Get weather forecast for next 7 days in a city"
)
```

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

### Create and Use Vector Store with GigaChat Embeddings

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-embedding-model.md

Demonstrates how to initialize a VectorStore using GigaChat embeddings, add documents, and perform a similarity search. Ensure the embeddingModel is properly configured before use.

```java
VectorStore vectorStore = new SimpleVectorStore(embeddingModel);

List<Document> documents = List.of(
    new Document("Spring AI provides unified abstractions for AI models"),
    new Document("RAG retrieves relevant documents for LLM context")
);
vectorStore.add(documents);

List<Document> results = vectorStore.similaritySearch("How does Spring AI work?");
```

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

### Get Model Name

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Retrieves the name of the GigaChat model being used.

```java
@Override
public String getModel()
```

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

### Configuring GigaChat Image Options via application.yml

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-image-model.md

Demonstrates how to configure GigaChat image generation settings using the application.yml configuration file.

```yaml
spring:
  ai:
    gigachat:
      image:
        options:
          model: GigaChat-2
          style: realistic
          response-format: url
```

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

### Get Temperature

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Retrieves the current temperature setting for the model. Returns null if not set.

```java
@Override
public Double getTemperature()
```

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

### Get Top-P Value

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Retrieves the Top-P sampling value for the model. Returns null if not set.

```java
@Override
public Double getTopP()
```

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

### Get Stop Sequences (Unsupported)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

GigaChat does not support stop sequences. This method will always return null.

```java
@Override
@JsonIgnore
public List<String> getStopSequences()
```

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

### Configure TLS Certificate Authentication

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Set up authentication using TLS certificates. Provide the paths to your certificate and private key files.

```yaml
spring:
  ai:
    gigachat:
      auth:
        certs:
          certificate: file:/path/to/cert.pem
          private-key: file:/path/to/key.pem
```

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

### Get Presence Penalty (Unsupported)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

GigaChat does not support presence penalty. This method will always return null.

```java
@Override
@JsonIgnore
public Double getPresencePenalty()
```

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

### Get Frequency Penalty (Unsupported)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

GigaChat does not support frequency penalty. This method will always return null.

```java
@Override
@JsonIgnore
public Double getFrequencyPenalty()
```

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

### Get Top-K Value (Unsupported)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

GigaChat does not support top-k sampling. This method will always return null.

```java
@Override
@JsonIgnore
public Integer getTopK()
```

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

### Run Spring Boot Application

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Execute this Maven command to run your Spring Boot application and test the GigaChat integration.

```bash
mvn spring-boot:run
```

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

### Generating Embeddings with GigaChat

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/INDEX.md

Create an EmbeddingRequest with text and GigaChatEmbeddingOptions, then call the embeddingModel to get the vector representation. The output is a float array.

```java
EmbeddingRequest request = new EmbeddingRequest(
    List.of("text to embed"),
    new GigaChatEmbeddingOptions()
);
EmbeddingResponse response = embeddingModel.call(request);
float[] vector = response.getResult().getOutput();
```

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

### Configure Client Credentials Authentication

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Configure authentication using client ID and client secret. Set GIGACHAT_CLIENT_ID and GIGACHAT_CLIENT_SECRET environment variables.

```yaml
spring:
  ai:
    gigachat:
      auth:
        bearer:
          client-id: ${GIGACHAT_CLIENT_ID}
          client-secret: ${GIGACHAT_CLIENT_SECRET}
```

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

### FunctionDescription Record

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/types.md

Defines a function available for tool calling. It includes the function's name, description, parameters schema, and optional few-shot examples.

```java
public record FunctionDescription(
    @JsonProperty("name") String name,
    @JsonProperty("description") String description,
    @JsonProperty("parameters") @JsonRawValue String parameters,
    @JsonProperty("few_shot_examples") List<FewShotExample> fewShotExamples,
    @JsonProperty("return_parameters") @JsonRawValue String returnParameters) {}

```

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

### Configure ChatClient with Default GigaChat Options

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Initialize a ChatClient with default GigaChat options for consistent model behavior. Options can be overridden at runtime for specific prompts.

```java
ChatClient chatClient = ChatClient.builder(gigaChatModel)
    .defaultOptions(GigaChatOptions.builder()
        .model("GigaChat-2")
        .temperature(0.7)
        .build())
    .build();

// Override options at runtime
String response = chatClient.prompt("Your question")
    .options(GigaChatOptions.builder()
        .temperature(0.3)  // More deterministic
        .build())
    .call()
    .content();
```

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

### GigaChatModel Constructor

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-model.md

Illustrates the constructor for GigaChatModel, detailing its dependencies for API interaction, options, tool management, retries, observability, and configuration.

```java
public GigaChatModel(
    GigaChatApi gigaChatApi,
    GigaChatOptions defaultOptions,
    ToolCallingManager toolCallingManager,
    RetryTemplate retryTemplate,
    ObservationRegistry observationRegistry,
    GigaChatInternalProperties internalProperties,
    ToolExecutionEligibilityPredicate toolExecutionEligibilityPredicate)
```

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

### Using Specific Parameter Descriptions for Tools

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Demonstrates how to use the @ToolParam annotation to provide detailed descriptions for tool parameters, aiding model understanding.

```java
public String search(
    @ToolParam(description = "Search query (e.g., 'Python tutorial')") 
    String query
)
```

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

### Get Request ID from Chat Response

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/response-metadata.md

Retrieve the unique request identifier from the chat response metadata. This is useful for tracing requests in logs and debugging.

```java
ChatResponse response = chatClient.prompt(prompt).call();
String requestId = response.getMetadata().getId();

logger.info("Request ID: {}", requestId);
// Use for tracing in logs and debugging
```

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

### GigaChat Spring AI Package Structure

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/INDEX.md

Provides an overview of the directory structure for the GigaChat Spring AI integration.

```text
chat.giga.springai/
├── GigaChatModel.java              - Main chat model
├── GigaChatOptions.java            - Chat options
├── GigaChatEmbeddingModel.java     - Embeddings
├── GigaChatEmbeddingOptions.java   - Embedding options
├── api/
│   ├── GigaChatApi.java            - HTTP client
│   ├── GigaChatApiProperties.java  - API properties
│   ├── auth/
│   │   ├── GigaChatAuthProperties.java
│   │   ├── GigaChatApiScope.java
│   │   └── bearer/
│   │       ├── GigaChatBearerAuthApi.java
│   │       ├── GigaChatOAuthClient.java
│   │       └── interceptors/
│   ├── chat/
│   │   ├── completion/
│   │   │   ├── CompletionRequest.java
│   │   │   └── CompletionResponse.java
│   │   ├── embedding/
│   │   │   ├── EmbeddingsRequest.java
│   │   │   ├── EmbeddingsResponse.java
│   │   │   └── EmbeddingsModel.java
│   │   └── models/
│   │       └── ModelsResponse.java
├── image/
│   ├── GigaChatImageModel.java     - Image generation
│   └── GigaChatImageOptions.java   - Image options
├── tool/
│   ├── annotation/
│   │   └── GigaTool.java           - Tool annotation
│   └── definition/
│       └── GigaToolDefinition.java
└── advisor/
    ├── GigaChatHttpHeadersAdvisor.java
    └── GigaChatCachingAdvisor.java
```

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

### Configure Advanced GigaChat Client Options

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Set up a custom ChatClient bean with advanced GigaChat model options. This allows fine-tuning parameters like model name, temperature, token limits, and enabling tool execution.

```java
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.prompt.Prompt;
import org.springframework.ai.chat.prompt.UserMessage;
import org.springframework.ai.model.Media;
import org.springframework.ai.gigachat.GigaChatModel;
import org.springframework.ai.gigachat.GigaChatOptions;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.core.io.ByteArrayResource;
import org.springframework.util.MimeTypeUtils;

import java.io.IOException;
import java.util.List;

@Configuration
public class GigaChatConfig {
    
    @Bean
    public ChatClient advancedChatClient(
            ChatClient.Builder builder,
            GigaChatModel model) {
        
        return builder
            .defaultOptions(GigaChatOptions.builder()
                .model("GigaChat-2")
                .temperature(0.3)           // More deterministic
                .topP(0.9)
                .maxTokens(2000)
                .repetitionPenalty(1.1)
                .profanityCheck(false)
                .internalToolExecutionEnabled(true)
                .toolNames("getWeather", "calculatePrice")
                .build())
            .build();
    }
}
```

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

### Basic SSL Configuration with Trusted CA

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

Configure basic SSL settings for GigaChat, including specifying a CA certificate for server verification. The `unsafe-ssl` property can disable verification but is not recommended for production.

```yaml
spring:
  ai:
    gigachat:
      auth:
        unsafe-ssl: false
        certs:
          ca-certs: file:/path/to/russian_trusted_root_ca.cer
```

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

### Configure Chat Client with Tools

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Configure a `ChatClient` bean to enable tool calling with GigaChat. This involves specifying the model, tool names, and enabling internal tool execution.

```java
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.gigachat.GigaChatModel;
import org.springframework.ai.gigachat.GigaChatOptions;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ToolConfig {
    
    @Bean
    public ChatClient chatClientWithTools(
            ChatClient.Builder builder,
            GigaChatModel gigaChatModel) {
        
        return builder
            .defaultOptions(GigaChatOptions.builder()
                .model("GigaChat-2")
                .toolNames("getWeather", "getTemperature")
                .internalToolExecutionEnabled(true)
                .build())
            .build();
    }
}
```

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

### Integrate Image Generation with ChatClient

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-image-model.md

Demonstrates how to generate an image using the image model and then use its URL in a subsequent chat prompt for analysis. This is useful for multimodal chat applications.

```java
// Generate image
ImageResponse imageResponse = imageModel.call(
    new ImagePrompt("A scenic landscape"));

// Use image in follow-up chat
String imageUrl = imageResponse.getResult().getImage().getUrl();
String analysis = chatClient.prompt(
    "Describe this image: " + imageUrl
).call().content();
```

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

### Configure ChatClient with Custom Tools

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

Configure a ChatClient to use custom tools with GigaChat, enabling internal tool execution and specifying tool names.

```java
@Configuration
public class ToolsConfig {
    
    @Bean
    public ChatClient chatClientWithTools(GigaChatModel gigaChatModel, 
                                         WeatherService weatherService) {
        return ChatClient.builder(gigaChatModel)
            .defaultOptions(GigaChatOptions.builder()
                .model("GigaChat-2")
                .toolNames("getWeather", "getLocation")
                .internalToolExecutionEnabled(true)
                .build())
            .build();
    }
}
```

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

### Configure Tool for Direct Return

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Configure a tool to return its result directly to the user without sending it back to the model. This is useful for tools that provide immediate, self-contained information.

```java
@GigaTool(returnDirect = true)
public String myTool() { ... }
```

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

### Get Uploaded Media IDs from Chat Response

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/response-metadata.md

Extract file IDs for media uploaded during multimodal conversations. These IDs can be used for subsequent operations like deleting the files.

```java
ChatResponse response = chatClient.prompt(userMessageWithImage).call();

// Get uploaded file IDs
@SuppressWarnings("unchecked")
List<String> uploadedIds = (List<String>) 
    response.getMetadata().get(GigaChatModel.UPLOADED_MEDIA_IDS);

if (uploadedIds != null && !uploadedIds.isEmpty()) {
    uploadedIds.forEach(id -> 
        logger.info("Uploaded file: {}", id)
    );
    
    // Can delete files later
    uploadedIds.forEach(id -> gigaChatApi.deleteFile(id));
}
```

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

### GigaChat Options Builder Methods

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Provides methods for constructing GigaChatOptions. Use the builder pattern to set various parameters like model, temperature, top-P, max tokens, and tool configurations.

```java
public static Builder builder()
public Builder toBuilder()
```

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

### GigaChatApi Constructor with Properties

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-api.md

Creates an API client using default REST/WebClient builders and error handlers. Requires GigaChatApiProperties for configuration.

```java
public GigaChatApi(GigaChatApiProperties properties)
```

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

### Tool Calling Methods

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Methods for configuring and retrieving tool callbacks, tool names, internal tool execution, and tool context for GigaChat.

```java
@Override
@JsonIgnore
public List<ToolCallback> getToolCallbacks()

@Override
@JsonIgnore
public void setToolCallbacks(List<ToolCallback> toolCallbacks)

@Override
@JsonIgnore
public Set<String> getToolNames()

@Override
@JsonIgnore
public void setToolNames(Set<String> toolNames)

@Override
@Nullable
@JsonIgnore
public Boolean getInternalToolExecutionEnabled()

@Override
@JsonIgnore
public void setInternalToolExecutionEnabled(@Nullable Boolean internalToolExecutionEnabled)

@Override
public Map<String, Object> getToolContext()

@Override
public void setToolContext(Map<String, Object> toolContext)
```

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

### GigaChatApi Configuration with Custom Token

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/authentication.md

Demonstrates how to configure the GigaChatApi bean using a custom GigaAuthToken implementation within a Spring @Configuration class. Requires GigaChatApiProperties and a TokenProvider.

```java
@Configuration
public class AuthConfig {
    
    @Bean
    public GigaChatApi gigaChatApi(
            GigaChatApiProperties properties,
            TokenProvider tokenProvider) {
        
        GigaAuthToken authToken = new CustomGigaAuthToken(tokenProvider);
        return new GigaChatApi(
            properties,
            authToken,
            RestClient.builder(),
            WebClient.builder(),
            RetryUtils.DEFAULT_RESPONSE_ERROR_HANDLER,
            null,
            null
        );
    }
}
```

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

### GigaTool Annotation Definition

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Defines the GigaTool annotation used for marking Java methods as callable tools in GigaChat. It includes attributes for tool name, description, return behavior, result conversion, few-shot examples, and output schema generation.

```java
import java.lang.annotation.*;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import org.springframework.core.annotation.AliasFor;

import chat.giga.springai.tool.annotation.Tool;
import chat.giga.springai.tool.converter.GigaToolCallResultConverter;
import chat.giga.springai.tool.converter.ToolCallResultConverter;
import chat.giga.springai.tool.model.FewShotExample;

@Target({ElementType.METHOD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Tool
@Inherited
public @interface GigaTool {
    
    @AliasFor(annotation = Tool.class, attribute = "name")
    String name() default "";
    
    @AliasFor(annotation = Tool.class, attribute = "description")
    String description() default "";
    
    @AliasFor(annotation = Tool.class, attribute = "returnDirect")
    boolean returnDirect() default false;
    
    @AliasFor(annotation = Tool.class, attribute = "resultConverter")
    Class<? extends ToolCallResultConverter> resultConverter() 
        default GigaToolCallResultConverter.class;
    
    FewShotExample[] fewShotExamples() default {};
    
    boolean generateOutputSchema() default true;
}
```

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

### GigaChatImageModel Constructor

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-image-model.md

Illustrates the constructor for GigaChatImageModel, detailing its dependencies for API interaction, default options, and error handling.

```java
public GigaChatImageModel(
    GigaChatApi gigaChatApi,
    GigaChatImageOptions defaultOptions,
    ObservationRegistry observationRegistry,
    RetryTemplate retryTemplate)
```

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

### Configure ChatClient with GigaChat

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

Programmatically configure a ChatClient with GigaChat, specifying the model and default options like temperature and max tokens.

```java
@Configuration
public class GigaChatConfig {
    
    @Bean
    public ChatClient chatClient(GigaChatModel gigaChatModel) {
        return ChatClient.builder(gigaChatModel)
            .defaultOptions(GigaChatOptions.builder()
                .model("GigaChat-2")
                .temperature(0.7)
                .topP(0.95)
                .maxTokens(2000)
                .build())
            .build();
    }
}
```

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

### GigaChatApi Constructor with Builders and TLS

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-api.md

Creates an API client with custom builders for synchronous and asynchronous HTTP clients, error handling, and optional TLS configurations. Use this for advanced customization of the HTTP client and SSL/TLS settings.

```java
public GigaChatApi(
    GigaChatApiProperties properties,
    RestClient.Builder restClientBuilder,
    WebClient.Builder webClientBuilder,
    ResponseErrorHandler responseErrorHandler,
    @Nullable KeyManagerFactory kmf,
    @Nullable TrustManagerFactory tmf)
```

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

### Manually Construct GigaChatApi with Properties

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-api.md

Instantiate GigaChatApi programmatically by building a GigaChatApiProperties object. Configure base URL, authentication details (API key, scope), and internal properties like connection timeouts.

```java
GigaChatApiProperties properties = GigaChatApiProperties.builder()
    .baseUrl(GigaChatApi.DEFAULT_BASE_URL)
    .auth(GigaChatAuthProperties.builder()
        .bearer(GigaChatAuthProperties.Bearer.builder()
            .apiKey("your-api-key")
            .build())
        .scope(GigaChatApiScope.GIGACHAT_API_PERS)
        .build())
    .internal(GigaChatInternalProperties.builder()
        .connectTimeout(Duration.ofSeconds(15))
        .build())
    .build();

GigaChatApi api = new GigaChatApi(properties);
```

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

### Image Generation with GigaChat

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/INDEX.md

Use ImagePrompt and GigaChatImageOptions to generate images. Specify response format, such as URL, and retrieve the image URL from the response.

```java
ImagePrompt prompt = new ImagePrompt(
    "A sunset landscape",
    GigaChatImageOptions.builder()
        .responseFormat(GigaChatImageOptions.RESPONSE_FORMAT_URL)
        .build()
);
String imageUrl = imageModel.call(prompt).getResult().getImage().getUrl();
```

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

### GigaChat Tool Execution Flow

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/INDEX.md

Details the process of executing tools with GigaChat, including function calls and tool execution.

```text
User Prompt
  ↓
GigaChatModel.call()
  ↓
API Call (function_call enabled)
  ↓
Model responds with function_call
  ↓
ToolCallingManager executes tool
  ↓
Result sent back to model
  ↓
Final response generated
  ↓
ChatResponse returned
```

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

### GigaChatEmbeddingModel Constructor

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-embedding-model.md

Initializes the GigaChatEmbeddingModel with necessary dependencies for interacting with the GigaChat API.

```APIDOC
## GigaChatEmbeddingModel Constructor

### Description
Initializes the GigaChatEmbeddingModel with necessary dependencies for interacting with the GigaChat API.

### Parameters
#### Constructor Parameters
- **gigaChatApi** (`GigaChatApi`) - Yes - Low-level API client
- **defaultOptions** (`GigaChatEmbeddingOptions`) - Yes - Default embedding model and dimensions
- **retryTemplate** (`RetryTemplate`) - Yes - Retry strategy for API calls
- **observationRegistry** (`ObservationRegistry`) - Yes - Metrics and traces registry
```

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

### Enable Tools in ChatClient

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Configure a ChatClient bean to enable tool usage with GigaChat. Specify model, tool names, and enable internal tool execution.

```java
@Configuration
public class ToolConfig {
    
    @Bean
    public ChatClient chatClientWithTools(
            GigaChatModel gigaChatModel,
            WeatherService weatherService) {
        
        return ChatClient.builder(gigaChatModel)
            .defaultOptions(GigaChatOptions.builder()
                .model("GigaChat-2")
                .toolNames("getWeather")
                .internalToolExecutionEnabled(true)
                .build())
            .build();
    }
}
```

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

### Expose Tool Calling via REST Endpoint

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Create a REST controller to expose a chat endpoint that utilizes the configured `ChatClient` for tool-based queries. This allows users to ask questions that can be answered by the defined tools.

```java
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class ToolController {
    
    private final ChatClient chatClient;
    
    public ToolController(ChatClient chatClient) {
        this.chatClient = chatClient;
    }
    
    @GetMapping("/weather-query")
    public String weatherQuery(@RequestParam String question) {
        return chatClient.prompt(question).call().content();
    }
}
```

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

### Handling Risky Tool Execution Errors

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Demonstrates how a tool can throw an exception, which will be caught and included in the tool response sent back to the model.

```java
@GigaTool(description = "May throw exception")
public String riskyTool() throws Exception {
    if (badCondition) {
        throw new IllegalArgumentException("Invalid input");
    }
    return "success";
}
```

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

### SSL Bundle Configuration for GigaChat

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

Configure a custom SSL bundle for GigaChat authentication, specifying the keystore and truststore details. This is an alternative to direct certificate and CA certificate configuration.

```yaml
spring:
  ai:
    gigachat:
      auth:
        certs:
          ssl-bundle: gigachat-ssl-bundle
        scope: GIGACHAT_API_PERS
  ssl:
    bundle:
      pem:
        gigachat-ssl-bundle:
          keystore:
            private-key: file:/path/to/tls.key
            certificate: file:/path/to/tls.crt
          truststore:
            certificates: file:/path/to/ca.crt
```

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

### Tool Eligibility Predicate Configuration

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Configure a bean to define custom logic for determining when a tool should execute based on response content.

```java
import org.springframework.ai.tool.ToolExecutionEligibilityPredicate;
import org.springframework.ai.tool.ToolOptions;
import org.springframework.ai.tool.ToolResponse;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class ToolConfig {
    
    @Bean
    public ToolExecutionEligibilityPredicate toolEligibility() {
        return (options, response) -> {
            // Custom logic to determine if tool should execute
            return !response.getResult().getOutput().contains("error");
        };
    }
}
```

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

### TLS Certificate Authentication

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

Set up TLS certificate authentication by providing paths to the client certificate, private key, and CA certificates. This method enhances security for sensitive communications.

```yaml
spring:
  ai:
    gigachat:
      auth:
        certs:
          certificate: file:/path/to/tls.crt
          private-key: file:/path/to/tls.key
          ca-certs: file:/path/to/ca.crt
        scope: GIGACHAT_API_PERS
```

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

### RAG Service for Question Answering

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

This service implements a RAG pattern to answer questions by first retrieving relevant documents from a VectorStore and then using them as context for the ChatClient.

```java
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.document.Document;
import org.springframework.ai.vectorstore.VectorStore;
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.stream.Collectors;

@Service
public class RagService {
    
    private final VectorStore vectorStore;
    private final ChatClient chatClient;
    
    // Constructor would typically inject VectorStore and ChatClient
    // public RagService(VectorStore vectorStore, ChatClient chatClient) {
    //     this.vectorStore = vectorStore;
    //     this.chatClient = chatClient;
    // }
    
    public String ask(String question) {
        // Retrieve relevant documents
        List<Document> documents = vectorStore.similaritySearch(question);
        
        // Build context
        String context = documents.stream()
            .map(Document::getContent)
            .collect(Collectors.joining("\n\n"));
        
        // Ask model with context
        String prompt = "Context:\n" + context + "\n\nQuestion: " + question;
        return chatClient.prompt(prompt).call().content();
    }
}
```

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

### call(ImagePrompt)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-image-model.md

Generates images based on the input prompt using the GigaChatImageModel. This method supports various generation options and returns a response containing the generated images.

```APIDOC
## call(ImagePrompt)

### Description
Generates images based on the input prompt. This method converts text prompts into generated images, supporting both base64-encoded and URL response formats.

### Method
```java
@Override
public ImageResponse call(ImagePrompt prompt)
```

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **prompt** (`ImagePrompt`) - Required - Text prompt(s) and options for generation

### Request Example
```java
ImagePrompt prompt = new ImagePrompt(
    "A serene landscape with mountains and a lake",
    GigaChatImageOptions.builder()
        .responseFormat(GigaChatImageOptions.RESPONSE_FORMAT_BASE64)
        .style("realistic")
        .build()
);

ImageResponse response = imageModel.call(prompt);
response.getResults().forEach(generation -> {
    Image image = generation.getImage();
    if (image.getB64Json() != null) {
        // Use base64-encoded image
        System.out.println("Generated image (base64): " + image.getB64Json());
    } else if (image.getUrl() != null) {
        // Use image URL
        System.out.println("Generated image URL: " + image.getUrl());
    }
});
```

### Response
#### Success Response (200)
- **results** (`List<ImageGeneration>`) - A list of image generation results.
  - **image** (`Image`) - The generated image object.
    - **b64Json** (`String`) - Base64 encoded image data (if requested).
    - **url** (`String`) - URL of the generated image (if requested).
  - **revisedPrompt** (`String`) - The revised prompt based on generation (if applicable).

#### Response Example
(Response structure depends on `responseFormat` option. Example for base64):
```json
{
  "results": [
    {
      "image": {
        "b64Json": "/9j/4AAQSkZJRgABAQEAS...",
        "url": null
      },
      "revisedPrompt": null
    }
  ]
}
```

### Error Handling
- API errors on request failure (retried per `RetryTemplate`)
- `IllegalStateException` — if image download fails
```

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

### Generate Image with GigaChat

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Use the `ImageService` to generate an image based on a text description. This snippet requires an `ImageModel` to be configured.

```java
import org.springframework.ai.image.ImagePrompt;
import org.springframework.ai.image.ImageModel;
import org.springframework.ai.gigachat.GigaChatImageOptions;
import org.springframework.stereotype.Service;

@Service
public class ImageService {
    
    private final ImageModel imageModel;
    
    public ImageService(ImageModel imageModel) {
        this.imageModel = imageModel;
    }
    
    public String generateImage(String description) {
        ImagePrompt prompt = new ImagePrompt(description,
            GigaChatImageOptions.builder()
                .responseFormat(GigaChatImageOptions.RESPONSE_FORMAT_URL)
                .build());
        
        return imageModel.call(prompt)
            .getResult()
            .getImage()
            .getUrl();
    }
}
```

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

### models

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-api.md

Retrieves a list of all available models supported by GigaChat.

```APIDOC
## models()

### Description
Fetches a list of available models that can be used with the GigaChat API.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **data** (List<ModelDescription>) - A list containing descriptions of each available model.

### Response Example
```java
ResponseEntity<ModelsResponse> response = gigaChatApi.models();
List<ModelDescription> models = response.getBody().getData();
models.forEach(m -> System.out.println(m.getName()));
```
```

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

### Configure Vector Store for RAG

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

Configure a VectorStore for Retrieval-Augmented Generation (RAG) using a GigaChat embedding model.

```java
@Configuration
public class RagConfig {
    
    @Bean
    public VectorStore vectorStore(GigaChatEmbeddingModel embeddingModel) {
        return new SimpleVectorStore(embeddingModel);
    }
}
```

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

### Set OAuth Client Credentials Environment Variables

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/authentication.md

Export the GigaChat client ID and client secret as environment variables. These credentials are used to obtain an access token from the OAuth server.

```bash
export GIGACHAT_CLIENT_ID=your-client-id
export GIGACHAT_CLIENT_SECRET=your-client-secret
```

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

### Java Method Signature for getDefaultOptions()

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-model.md

This method signature retrieves the default chat options specific to the GigaChat model instance.

```java
public ChatOptions getDefaultOptions()
```

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

### Simple Text to Image Generation

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-image-model.md

Generates a single image from a text prompt and retrieves its URL. Ensure the imageModel is properly configured.

```java
ImagePrompt prompt = new ImagePrompt("A cat wearing sunglasses");
ImageResponse response = imageModel.call(prompt);

String imageUrl = response.getResult().getImage().getUrl();
System.out.println("Image: " + imageUrl);
```

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

### Set GigaChat API Key Environment Variable

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/authentication.md

Use environment variables to manage your GigaChat API key securely. Avoid committing credentials directly to version control.

```bash
# Use environment variables
export GIGACHAT_API_KEY=xxx
```

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

### Configure GigaChat Options via application.yml

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/gigachat-options.md

Set GigaChat model parameters such as model name, temperature, top-p, max tokens, repetition penalty, and profanity check through application configuration properties.

```yaml
spring:
  ai:
    gigachat:
      chat:
        options:
          model: GigaChat-2
          temperature: 0.5
          top-p: 0.95
          max-tokens: 1000
          repetition-penalty: 1.0
          profanity-check: false
```

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

### Download File by ID (Java)

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/file-operations.md

Use this method to download raw file content when custom headers are not required. It takes a file ID as input and returns the file as a byte array.

```java
public byte[] downloadFile(String fileId)
```

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

### Enable Internal Tool Execution

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/tool-calling.md

Enable internal tool execution for the GigaChat client. This allows the framework to manage tool calls and responses.

```java
.internalToolExecutionEnabled(true)
```

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

### GigaChat Environment Variables

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/configuration.md

Set these environment variables for authentication and API configuration. Ensure sensitive keys are kept secure.

```bash
# Authentication
GIGACHAT_API_KEY=your-authorization-key
GIGACHAT_CLIENT_ID=your-client-id
GIGACHAT_CLIENT_SECRET=your-client-secret

# API Configuration
GIGACHAT_BASE_URL=https://gigachat.devices.sberbank.ru/api/v1/

# Certificates
GIGACHAT_CA_CERTS=/path/to/ca.crt
GIGACHAT_TLS_CERT=/path/to/tls.crt
GIGACHAT_TLS_KEY=/path/to/tls.key
```

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

### Implementing Tool Calling with GigaChat

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/INDEX.md

Define methods annotated with @GigaTool to enable GigaChat to call your custom tools. Use @ToolParam to specify parameters for your tools.

```java
@GigaTool(description = "Get weather for a city")
public String getWeather(
    @ToolParam(description = "City name") String city
) {
    return "Weather data for " + city;
}
```

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

### Analyze Image with Multimodal Chat

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/quick-start.md

Use this service to send image data and a question to the GigaChat model for analysis. Ensure you have the necessary dependencies for handling image data and making client calls.

```java
import org.springframework.ai.chat.client.ChatClient;
import org.springframework.ai.chat.model.ChatModel;
import org.springframework.ai.chat.prompt.UserMessage;
import org.springframework.ai.model.Media;
import org.springframework.core.io.ByteArrayResource;
import org.springframework.stereotype.Service;
import org.springframework.util.MimeTypeUtils;

import java.io.IOException;
import java.util.List;

@Service
public class MultimodalService {
    
    private final ChatClient chatClient;
    
    public MultimodalService(ChatClient chatClient) {
        this.chatClient = chatClient;
    }

    public String analyzeImage(byte[] imageData, String question) 
            throws IOException {
        
        // Create media from image bytes
        Media image = Media.builder()
            .name("image.jpg")
            .data(new ByteArrayResource(imageData))
            .mimeType(MimeTypeUtils.IMAGE_JPEG)
            .build();
        
        // Create message with image
        UserMessage message = new UserMessage(question, List.of(image));
        
        // Send to model
        return chatClient.prompt(message).call().content();
    }
}
```

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

### SimpleGigaAuthToken Implementation

Source: https://github.com/ai-forever/spring-ai-gigachat/blob/main/_autodocs/authentication.md

A built-in implementation of GigaAuthToken for API key-based authentication. Instantiate with your API key.

```java
public class SimpleGigaAuthToken implements GigaAuthToken {
    public SimpleGigaAuthToken(String apiKey) { ... }
    
    @Override
    public String getAuthorizationToken() {
        return apiKey;
    }
}
```