LangChain4j

https://docs.langchain4j.dev/
Admin
LangChain4j is a framework designed to supercharge Java applications with the power of LLMs,...
Tokens:1,516,669
Snippets:11,388
Trust Score:5.3
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Google Cloud SDK

Source: https://docs.langchain4j.dev/integrations/language-models/google-vertex-ai-anthropic

Navigate to the SDK directory and execute the installation script.

```bash
cd google-cloud-sdk/

./install.sh
```

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

### start

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/mcp/client/transport/http/StreamableHttpMcpTransport.html

Starts the MCP server connection.

```APIDOC
## start(McpOperationHandler operationHandler)

### Description
Creates a connection to the MCP server. If necessary, this method will also run the server as a subprocess. It requires an `McpOperationHandler` to process incoming operations.

### Method
`void start(McpOperationHandler operationHandler)`

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **operationHandler** (McpOperationHandler) - Required - The handler for processing MCP operations.
```

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

### Configure Tool Use Examples with Metadata

Source: https://docs.langchain4j.dev/integrations/language-models/anthropic

Shows how to provide input examples for tools via metadata, which helps the model understand expected input formats.

```java
enum Unit {  

    CELSIUS, FAHRENHEIT  

}  

  

class Tools {  

  

    // NOTE: if javac "-parameters" option is not enabled, you need to change "location" to "arg0"  

    // and "unit" to "arg1" inside the TOOL_METADATA to make it work.  

    public static final String TOOL_METADATA = """  

            {  

                \"input_examples\": [  

                    {  

                        \"location\": \"San Francisco, CA\",  

                        \"unit\": \"FAHRENHEIT\"  

                    },  

                    {  

                        \"location\": \"Tokyo, Japan\",  

                        \"unit\": \"CELSIUS\"  

                    },  

                    {  

                        \"location\": \"New York, NY\"  

                    }  

                ]  

            }  

            """;  

  

    @Tool(metadata = TOOL_METADATA)  

    String getWeather(String location, @P(description = "temperature unit", required = false) Unit unit) {  

        return "sunny";  

    }  

}  

  

ChatModel chatModel = AnthropicChatModel.builder()  

        .apiKey(System.getenv("ANTHROPIC_API_KEY"))  

        .modelName(CLAUDE_SONNET_4_5_20250929)  

        .beta("advanced-tool-use-2025-11-20")  

        .toolMetadataKeysToSend("input_examples") // need to specify it explicitly  

        .logRequests(true)  

        .logResponses(true)  

        .build();  

  

interface Assistant {  

  

    String chat(String userMessage);  

}  

  

Assistant assistant = AiServices.builder(Assistant.class)  

        .chatModel(chatModel)  

        .tools(new Tools())  

        .build();  

  

assistant.chat("What is the weather in Munich in Fahrenheit?");
```

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

### Initialize and Start WebSocketMcpTransport

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/mcp/client/transport/websocket/WebSocketMcpTransport.html

Demonstrates how to instantiate, start, and initialize a WebSocketMcpTransport connection. The start method establishes the connection, while initialize negotiates capabilities with the server.

```java
WebSocketMcpTransport transport = WebSocketMcpTransport.builder()
    .uri("ws://localhost:8080")
    .build();

transport.start(operationHandler);
transport.initialize(initializeRequest).get();
```

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

### Run Ollama with Testcontainers

Source: https://docs.langchain4j.dev/integrations/language-models/ollama

Example demonstrating how to programmatically start an Ollama container, pull a model, and execute a chat request.

```java
import com.github.dockerjava.api.DockerClient;  

import com.github.dockerjava.api.model.Image;  

import dev.langchain4j.model.chat.ChatModel;  

import dev.langchain4j.model.ollama.OllamaChatModel;  

import org.slf4j.Logger;  

import org.slf4j.LoggerFactory;  

import org.testcontainers.DockerClientFactory;  

import org.testcontainers.containers.Container;  

import org.testcontainers.ollama.OllamaContainer;  

import org.testcontainers.utility.DockerImageName;  

  

import java.io.IOException;  

import java.util.List;  

  

public class OllamaChatExample {  

  

  private static final Logger log = LoggerFactory.getLogger(OllamaChatExample.class);  

  

  static final String OLLAMA_IMAGE = "ollama/ollama:latest";  

  static final String TINY_DOLPHIN_MODEL = "tinydolphin";  

  static final String DOCKER_IMAGE_NAME = "tc-ollama/ollama:latest-tinydolphin";  

  

  public static void main(String[] args) {  

    // Create and start the Ollama container  

    DockerImageName dockerImageName = DockerImageName.parse(OLLAMA_IMAGE);  

    DockerClient dockerClient = DockerClientFactory.instance().client();  

    List<Image> images = dockerClient.listImagesCmd().withReferenceFilter(DOCKER_IMAGE_NAME).exec();  

    OllamaContainer ollama;  

    if (images.isEmpty()) {  

        ollama = new OllamaContainer(dockerImageName);  

    } else {  

        ollama = new OllamaContainer(DockerImageName.parse(DOCKER_IMAGE_NAME).asCompatibleSubstituteFor(OLLAMA_IMAGE));  

    }  

    ollama.start();  

  

    // Pull the model and create an image based on the selected model.  

    try {  

        log.info("Start pulling the '{}' model ... would take several minutes ...", TINY_DOLPHIN_MODEL);  

        Container.ExecResult r = ollama.execInContainer("ollama", "pull", TINY_DOLPHIN_MODEL);  

        log.info("Model pulling competed! {}", r);  

    } catch (IOException | InterruptedException e) {  

        throw new RuntimeException("Error pulling model", e);  

    }  

    ollama.commitToImage(DOCKER_IMAGE_NAME);  

  

    // Build the ChatModel  

    ChatModel model = OllamaChatModel.builder()  

            .baseUrl(ollama.getEndpoint())  

            .temperature(0.0)  

            .logRequests(true)  

            .logResponses(true)  

            .modelName(TINY_DOLPHIN_MODEL)  

            .build();  

  

    // Example usage  

    String answer = model.chat("Provide 3 short bullet points explaining why Java is awesome");  

    System.out.println(answer);  

  

    // Stop the Ollama container  

    ollama.stop();  

  }  

}
```

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

### Example output

Source: https://docs.langchain4j.dev/integrations/language-models/mistral-ai

The expected output format from the assistant.

```text
The status of transaction T1005 is Pending. The payment date is October 8, 2021.  
```

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

### start

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/service/TokenStream.html

Initiates the streaming process.

```APIDOC
## void start()

### Description
Completes the current token stream building and starts processing by sending a request to the LLM and beginning response streaming.
```

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

### Configure Neo4jEmbeddingStore Instances

Source: https://docs.langchain4j.dev/integrations/embedding-stores/neo4j

Examples of minimal and custom configurations for the Neo4jEmbeddingStore.

```java
// ---> MINIMAL EMBEDDING <---  

Neo4jEmbeddingStore minimalEmbedding = Neo4jEmbeddingStore.builder()  

    .withBasicAuth(NEO4J_CONNECTION_STRING, USERNAME, ADMIN_PASSWORD)  

    .dimension(384)  

    .build();  

  

// ---> CUSTOM EMBEDDING <---  

Neo4jEmbeddingStore customEmbeddingStore = Neo4jEmbeddingStore.builder()  

        .withBasicAuth(NEO4J_CONNECTION_STRING, USERNAME, ADMIN_PASSWORD)  

        .dimension(384)  

        .indexName(CUSTOM_INDEX)  

        .metadataPrefix(CUSTOM_METADATA_PREF)  

        .label(CUSTOM_LABEL)  

        .embeddingProperty(CUSTOM_PROP)  

        .idProperty(CUSTOM_ID)  

        .textProperty(CUSTOM_TEXT)  

        .build();  
```

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

### WatsonxStreamingChatModel Builder Example (Alternative Model)

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/model/watsonx/WatsonxStreamingChatModel.html

An alternative example showing the construction of a WatsonxStreamingChatModel, specifying a different model name. This highlights the flexibility in choosing different watsonx.ai models.

```java
StreamingChatModel chatModel = WatsonxStreamingChatModel.builder()
    .baseUrl("https://...") // or use CloudRegion
    .apiKey("...")
    .projectId("...")
    .modelName("ibm/granite-3-8b-instruct")
    .maxOutputTokens(0)
    .temperature(0.7)
    .build();
```

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

### Initialize and Start StdioMcpTransport

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/mcp/client/transport/stdio/StdioMcpTransport.html

Demonstrates how to instantiate the transport using its builder and initiate the connection to the MCP server. The start method launches the subprocess, while initialize negotiates protocol capabilities.

```java
StdioMcpTransport transport = StdioMcpTransport.builder()
    .build();
transport.start(messageHandler);
transport.initialize(initializeRequest).join();
```

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

### Example Usage of fromLLM

Source: https://docs.langchain4j.dev/integrations/embedding-stores/neo4j

Example of using Neo4jText2CypherRetriever's fromLLM method to get a natural language response to a query about a book author.

```java
Neo4jText2CypherRetriever neo4jContentRetriever = Neo4jText2CypherRetriever.builder() 
        .graph(graph) 
        .chatModel(OPEN_AI_CHAT_MODEL) 
        .build();

Query query = new Query("Who is the author of the book 'Dune'?");

String response = neo4jContentRetriever.fromLLM(query);
// example output: the author of the book 'Dune' is Frank Herbert
```

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

### Implement JlamaChatModelBuilderFactory

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/model/jlama/spi/JlamaChatModelBuilderFactory.html

An example of how to implement the JlamaChatModelBuilderFactory interface to provide a custom builder instance. The implementation must override the get method to return a JlamaChatModel.JlamaChatModelBuilder.

```java
import dev.langchain4j.model.jlama.JlamaChatModel;
import java.util.function.Supplier;

public class MyJlamaFactory implements JlamaChatModelBuilderFactory {
    @Override
    public JlamaChatModel.JlamaChatModelBuilder get() {
        return JlamaChatModel.builder()
            .modelName("llama-3");
    }
}
```

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

### PostgresEmbeddingStore Usage Example

Source: https://docs.langchain4j.dev/integrations/embedding-stores/cloud-sql

Demonstrates how to initialize PostgresEngine, create a PostgresEmbeddingStore, add embeddings, perform a search, and remove embeddings.

```java
import dev.langchain4j.data.document.Metadata;
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.embedding.onnx.allminilml6v2.AllMiniLmL6V2EmbeddingModel;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingMatch;
import dev.langchain4j.store.embedding.EmbeddingSearchRequest;
import dev.langchain4j.store.embedding.EmbeddingSearchResult;
import dev.langchain4j.engine.EmbeddingStoreConfig;
import dev.langchain4j.engine.PostgresEngine;
import dev.langchain4j.engine.MetadataColumn;
import dev.langchain4j.store.embedding.cloudsql.PostgresEmbeddingStore;

import java.util.ArrayList;
import java.util.List;
import java.util.UUID;
import java.util.stream.Collectors;

PostgresEngine engine = new PostgresEngine.Builder()
    .projectId("")
    .region("")
    .instance("")
    .database("")
    .build();

PostgresEmbeddingStore store = new PostgresEmbeddingStore.Builder(engine, TABLE_NAME)
    .build();

List<String> testTexts = Arrays.asList("cat", "dog", "car", "truck");
List<Embedding> embeddings = new ArrayList<>();
List<TextSegment> textSegments = new ArrayList<>();
EmbeddingModel embeddingModel = new AllMiniLmL6V2EmbeddingModel();

for (String text : testTexts) {
    Map<String, Object> metaMap = new HashMap<>();
    metaMap.put("my_metadata", "string");
    Metadata metadata = new Metadata(metaMap);
    textSegments.add(new TextSegment(text, metadata));
    embeddings.add(MyEmbeddingModel.embed(text).content());
}
List<String> ids = store.addAll(embeddings, textSegments);
// search for "cat"
EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()
        .queryEmbedding(embeddings.get(0))
        .maxResults(10)
        .minScore(0.9)
        .build();
List<EmbeddingMatch<TextSegment>> result = store.search(request).matches();
// remove "cat"
store.removeAll(singletonList(result.get(0).embeddingId()));

```

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

### DefaultMcpClient.instructions()

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/mcp/client/DefaultMcpClient.html

Returns the server instructions from the initialize result, or null if the server did not provide any.

```APIDOC
## DefaultMcpClient.instructions()

### Description
Retrieves the server instructions that were provided during the initialization phase. Returns null if no instructions were supplied by the server.

### Method
Instance Method

### Returns
`@Nullable String` - The server instructions, or null.
```

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

### Getting ToolMessage Details (Java)

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/model/openai/internal/chat/ToolMessage.html

This example shows how to retrieve specific details from a ToolMessage object. It demonstrates accessing the message's role, the ID of the tool call it corresponds to, and its textual content.

```java
Role role = toolMessage.role();
String toolCallId = toolMessage.toolCallId();
String content = toolMessage.content();
```

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

### Recursive Document Splitting Example (Java)

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/data/document/DocumentSplitter.html

Demonstrates how to obtain a default DocumentSplitter instance using the recursive strategy. This is a common starting point for document splitting in Langchain4j, provided by the `DocumentSplitters.recursive()` method from the `langchain4j` module.

```java
DocumentSplitter splitter = DocumentSplitters.recursive();
```

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

### Configure OpenTelemetry starter in application.yaml

Source: https://docs.langchain4j.dev/tutorials/observability

Enable the starter and configure telemetry settings, including optional cost tracking, via the application.yaml file.

```yaml
otel:  

  langchain4j:  

    enabled: true  

    system: openai  

    default-model: gpt-4o  

    capture-prompts: true  

    capture-completions: true  

    cost:  

      enabled: true  

      input-per-thousand: 0.0005  

      output-per-thousand: 0.0015
```

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

### instructions

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/mcp/client/McpClient.html

Retrieves the server instructions from the initialize result.

```APIDOC
## instructions

### Description
Returns the server instructions from the initialize result, or null if the server did not provide any.

### Method
default @Nullable String

### Endpoint
N/A (SDK method)

### Parameters
None

### Response
#### Success Response
- **String** - The server instructions, or null.

### Response Example
"Please provide valid input."
```

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

### GET /getAllVersionsOfServer

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/mcp/registryclient/DefaultMcpRegistryClient.html

Get all available versions for a specific MCP server.

```APIDOC
## GET /getAllVersionsOfServer

### Description
Get all available versions for a specific MCP server.

### Method
GET

### Parameters
#### Query Parameters
- **serverName** (String) - Required - The name of the MCP server.

### Response
#### Success Response (200)
- **McpServerList** (Object) - A list containing all available versions for the server.
```

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

### init(InitPlanningContext)

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/agentic/patterns/goap/GoalOrientedPlanner.html

Initializes the planner with the provided planning context.

```APIDOC
### Method
`void init(InitPlanningContext initPlanningContext)`

Initializes the planner using the specified context.
```

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

### GET /getSpecificServerVersion

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/mcp/registryclient/DefaultMcpRegistryClient.html

Get detailed information about a specific version of an MCP server.

```APIDOC
## GET /getSpecificServerVersion

### Description
Get detailed information about a specific version of an MCP server. Use the special version 'latest' to get the latest version.

### Method
GET

### Parameters
#### Query Parameters
- **serverName** (String) - Required - The name of the MCP server.
- **version** (String) - Required - The specific version string or 'latest'.

### Response
#### Success Response (200)
- **McpGetServerResponse** (Object) - Detailed information about the specific version of the server.
```

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

### Initialize and use Neo4jEmbeddingStore

Source: https://docs.langchain4j.dev/integrations/embedding-stores/neo4j

Demonstrates creating a minimal embedding store, adding segments, and performing a similarity search.

```java
private static final EmbeddingModel embeddingModel = new AllMiniLmL6V2EmbeddingModel();  

  

public static void minimalEmbedding() {  

    try (Neo4jContainer<?> neo4j = new Neo4jContainer<>("neo4j:5.26")) {  

        neo4j.start();  

  

        EmbeddingStore<TextSegment> minimalEmbedding = Neo4jEmbeddingStore.builder()  

                .withBasicAuth(neo4j.getBoltUrl(), "neo4j", neo4j.getAdminPassword())  

                .dimension(384)  

                .build();  

  

  

        TextSegment segment1 = TextSegment.from("I like football.", Metadata.from("test-key-1", "test-value-1"));  

        Embedding embedding1 = embeddingModel.embed(segment1).content();  

  

        TextSegment segment2 = TextSegment.from("The weather is good today.", Metadata.from("test-key-2", "test-value-2"));  

        Embedding embedding2 = embeddingModel.embed(segment2).content();  

  

        TextSegment segment3 = TextSegment.from("I like basketball.", Metadata.from("test-key-3", "test-value-3"));  

        Embedding embedding3 = embeddingModel.embed(segment3).content();  

        minimalEmbedding.addAll(  

                List.of(embedding1, embedding2, embedding3),  

                List.of(segment1, segment2, segment3)  

        );  

  

        Embedding queryEmbedding = embeddingModel.embed("What are your favourite sports?").content();  

        final EmbeddingSearchRequest request = EmbeddingSearchRequest.builder()  

                .queryEmbedding(queryEmbedding)  

                .maxResults(2)  

                .minScore(0.15)  

                .build();  

        List<EmbeddingMatch<TextSegment>> relevant = minimalEmbedding.search(request).matches();  

        relevant.forEach(match -> {  

            System.out.println(match.score()); // 0.8144289255142212  

            System.out.println(match.embedded().text()); // I like football. || I like basketball.  

        });  

    }  

}  
```

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

### Start the stdio server

Source: https://docs.langchain4j.dev/tutorials/mcp-stdio-server

Initialize the McpServer and transport it over stdio. Ensure logging is directed to System.err to avoid corrupting the JSON-RPC stream.

```java
import dev.langchain4j.community.mcp.server.McpServer;  

import dev.langchain4j.community.mcp.server.transport.StdioMcpServerTransport;  

import dev.langchain4j.mcp.protocol.McpImplementation;  

import java.util.List;  

  

public class McpServerMain {  

  

    public static void main(String[] args) throws Exception {  

        McpImplementation serverInfo = new McpImplementation();  

        serverInfo.setName("my-java-mcp-server");  

        serverInfo.setVersion("1.0.0");  

  

        McpServer server = new McpServer(List.of(new Calculator()), serverInfo);  

        new StdioMcpServerTransport(System.in, System.out, server);  

  

        // Keep the process alive while stdio is open  

        Thread.currentThread().join();  

    }  

}
```

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

### Example Exception

Source: https://docs.langchain4j.dev/integrations/language-models/google-vertex-ai-gemini

Example of an exception that may occur when accessing restricted models.

```text
Caused by: io.grpc.StatusRuntimeException:  

 FAILED_PRECONDITION: Project `1234567890` is not allowed to use Publisher Model  

  `projects/{YOUR_PROJECT_ID}/locations/us-central1/publishers/google/models/gemini-ultra`  
```

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

### Initialize and Use GPULlama3ChatModel

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/model/gpullama3/GPULlama3ChatModel.html

Demonstrates how to build and use the GPULlama3ChatModel. Configure model path, temperature, max tokens, and GPU usage. This model automatically separates thinking content from actual responses.

```java
GPULlama3ChatModel model = GPULlama3ChatModel.builder()
    .modelPath(Paths.get("path/to/model.gguf"))
    .temperature(0.7)
    .maxTokens(2048)
    .onGPU(true)
    .build();

ChatResponse response = model.chat(chatRequest);
```

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

### AgentInvocation Class Methods - Java

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/agentic/observability/AgentInvocation.html

This snippet details the methods available in the AgentInvocation Java class. These methods allow retrieval of agent invocation details such as start time, finish time, duration, inputs, outputs, token usage, iteration index, nested invocations, and tool executions. It also includes the `done()` method to check completion status and `agent()` to get the agent instance.

```java
public class AgentInvocation extends Object
  * ## Method Summary 
All MethodsInstance MethodsConcrete Methods
Modifier and Type
Method
Description
`AgentInstance`
`agent()`
`AgenticScope`
`agenticScope()`
`boolean`
`done()`
`Duration`
`duration()`
`LocalDateTime`
`finishTime()`
`Map<String,Object>`
`inputs()`
`int`
`iterationIndex()`
Returns the zero-based iteration index when this invocation is part of a loop, or -1 otherwise.
`List<AgentInvocation>`
`nestedInvocations()`
`Object`
`output()`
`LocalDateTime`
`startTime()`
`Optional<TokenUsage>`
`tokenUsage()`
`List<ToolExecution>`
`toolExecutions()`
`String`
`toString()`
`int`
`totalTokenCount()`
### Methods inherited from class Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  * ## Method Details 
    * ### done 
public boolean done()
    * ### startTime 
public LocalDateTime startTime()
    * ### finishTime 
public LocalDateTime finishTime()
    * ### duration 
public Duration duration()
    * ### agent 
public AgentInstance agent()
    * ### agenticScope 
public AgenticScope agenticScope()
    * ### inputs 
public Map<String,Object> inputs()
    * ### output 
public Object output()
    * ### totalTokenCount 
public int totalTokenCount()
    * ### tokenUsage 
public Optional<TokenUsage> tokenUsage()
    * ### iterationIndex 
public int iterationIndex()
Returns the zero-based iteration index when this invocation is part of a loop, or -1 otherwise.
    * ### nestedInvocations 
public List<AgentInvocation> nestedInvocations()
    * ### toolExecutions 
public List<ToolExecution> toolExecutions()
    * ### toString 
public String toString()

Overrides:
    `toString` in class `Object`
```

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

### Micrometer Metrics Output Example

Source: https://docs.langchain4j.dev/tutorials/observability

Example output showing generated metrics for operation duration and token usage in Prometheus format.

```text
# HELP gen_ai_client_operation_duration_active_seconds    

# TYPE gen_ai_client_operation_duration_active_seconds summary  

gen_ai_client_operation_duration_active_seconds_count{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="unknown",outcome="SUCCESS"} 0  

gen_ai_client_operation_duration_active_seconds_sum{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="unknown",outcome="SUCCESS"} 0.0  

# HELP gen_ai_client_operation_duration_active_seconds_max    

# TYPE gen_ai_client_operation_duration_active_seconds_max gauge  

gen_ai_client_operation_duration_active_seconds_max{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="unknown",outcome="SUCCESS"} 0.0  

# HELP gen_ai_client_operation_duration_seconds    

# TYPE gen_ai_client_operation_duration_seconds summary  

gen_ai_client_operation_duration_seconds_count{error="none",gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",outcome="SUCCESS"} 2  

gen_ai_client_operation_duration_seconds_sum{error="none",gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",outcome="SUCCESS"} 3.384050045  

# HELP gen_ai_client_operation_duration_seconds_max    

# TYPE gen_ai_client_operation_duration_seconds_max gauge  

gen_ai_client_operation_duration_seconds_max{error="none",gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",outcome="SUCCESS"} 2.115592691  

# HELP gen_ai_client_token_usage_tokens Measures the quantity of used tokens  

# TYPE gen_ai_client_token_usage_tokens summary  

gen_ai_client_token_usage_tokens_count{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="input"} 2  

gen_ai_client_token_usage_tokens_sum{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="input"} 508.0  

gen_ai_client_token_usage_tokens_count{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="output"} 2  

gen_ai_client_token_usage_tokens_sum{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="output"} 53.0  

# HELP gen_ai_client_token_usage_tokens_max Measures the quantity of used tokens  

# TYPE gen_ai_client_token_usage_tokens_max gauge  

gen_ai_client_token_usage_tokens_max{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="input"} 273.0  

gen_ai_client_token_usage_tokens_max{gen_ai_operation_name="chat",gen_ai_provider_name="OPEN_AI",gen_ai_request_model="gpt-4o-mini",gen_ai_response_model="gpt-4o-mini-2024-07-18",gen_ai_token_type="output"} 27.0
```

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

### Implement SearchApi Tool in Java

Source: https://docs.langchain4j.dev/integrations/web-search-engines/searchapi

Example demonstrating how to configure the SearchApiWebSearchEngine and integrate it into an AI service using LangChain4j.

```java
import dev.langchain4j.memory.chat.MessageWindowChatMemory;  

import dev.langchain4j.model.chat.ChatModel;  

import dev.langchain4j.model.openai.OpenAiChatModel;  

import dev.langchain4j.model.openai.OpenAiChatModelName;  

import dev.langchain4j.service.AiServices;  

import dev.langchain4j.web.search.WebSearchTool;  

import dev.langchain4j.web.search.searchapi.SearchApiEngine;  

import dev.langchain4j.web.search.searchapi.SearchApiWebSearchEngine;  

  

public class SearchApiTool {  

  

    interface Assistant {  

        @SystemMessage({  

                "You are a web search support agent.",  

                "If there is any event that has not happened yet",  

                "You MUST create a web search request with user query and",  

                "use the web search tool to search the web for organic web results.",  

                "Include the source link in your final response."  

        })  

        String answer(String userMessage);  

    }  

  

    private static final String SEARCHAPI_API_KEY = "YOUR_SEARCHAPI_KEY";  

    private static final String OPENAI_API_KEY = "YOUR_OPENAI_KEY";  

  

    public static void main(String[] args) {  

        Map<String, Object> optionalParameters = new HashMap<>();  

        optionalParameters.put("gl", "us");  

        optionalParameters.put("hl", "en");  

        optionalParameters.put("google_domain", "google.com");  

          

        SearchApiWebSearchEngine searchEngine = SearchApiWebSearchEngine.builder()  

                .apiKey(SEARCHAPI_API_KEY)  

                .engine("google")  

                .optionalParameters(optionalParameters)  

                .build();  

        ChatModel chatModel = OpenAiChatModel.builder()  

                .apiKey(OPENAI_API_KEY)  

                .modelName(OpenAiChatModelName.GPT_3_5_TURBO)  

                .logRequests(true)  

                .build();  

  

        WebSearchTool webTool = WebSearchTool.from(searchEngine);  

  

        Assistant assistant = AiServices.builder(Assistant.class)  

                .chatModel(chatModel)  

                .tools(webTool)  

                .build();  

  

        String answer = assistant.answer("My family is coming to visit me in Madrid next week, list the best tourist activities suitable for the whole family");  

        System.out.println(answer);  

        /*  

            Here are some of the best tourist activities suitable for the whole family in Madrid:  

              

            1. **Parque del Retiro** - A beautiful public park where families can enjoy nature and various activities.  

            2. **Prado Museum** - A renowned art museum that can be fascinating for both adults and children.  

            3. **Mercado de San Miguel** - A market where you can explore and taste delicious Spanish food.  

            4. **Royal Palace** - Explore the grandeur of the Royal Palace of Madrid.  

            5. **Plaza Mayor** and **Puerta del Sol** - Historic squares with a vibrant atmosphere.  

            6. **Santiago Bernabeu Stadium** - Perfect for sports enthusiasts and soccer fans.  

            7. **Gran Via** - A famous street for shopping, entertainment, and sightseeing.  

            8. **National Archaeological Museum** - Discover Spain's rich history through archaeological artifacts.  

            9. **Templo de Debod** - An ancient Egyptian temple in the heart of Madrid.  

         */  

    }  

}  
```

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

### Complete Batch Workflow

Source: https://docs.langchain4j.dev/integrations/language-models/google-ai-gemini

A full example covering model initialization, request preparation, submission, polling for status, and result processing.

```java
GoogleAiGeminiBatchChatModel batchModel = GoogleAiGeminiBatchChatModel.builder()
    .apiKey(System.getenv("GEMINI_AI_KEY"))
    .modelName("gemini-2.5-flash")
    .build();

// Prepare batch requests
List<ChatRequest> requests = new ArrayList<>();
for (int i = 0; i < 50; i++) {
    requests.add(ChatRequest.builder()
        .messages(UserMessage.from("Generate a creative story idea #" + i))
        .build());
}

// Submit batch
BatchResponse<ChatResponse> result = batchModel.submit(GeminiBatchRequest.from(
    requests, "Story Ideas Batch", 0L));
String batchId = result.batchId();

// Poll for completion
int attempts = 0;
int maxAttempts = 720; // 1 hour with 5-second intervals
while (!result.state().isTerminal()) {
    if (attempts++ >= maxAttempts) {
        throw new RuntimeException("Batch processing timeout");
    }
    Thread.sleep(5000);
    result = batchModel.retrieve(batchId);
    System.out.println("Status: " + result.state());
}

// Process results
if (result.state() == BatchState.SUCCEEDED) {
    System.out.println("Generated " + result.responses().size() + " stories");
    for (int i = 0; i < result.responses().size(); i++) {
        ChatResponse chatResponse = result.responses().get(i);
        System.out.println("Story #" + i + ": " + chatResponse.aiMessage().text());
    }

    // Report any failures
    if (!result.errors().isEmpty()) {
        System.err.println(result.errors().size() + " requests failed:");
        for (BatchError error : result.errors()) {
```

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

### Configure OpenAiChatModel with Demo Key

Source: https://docs.langchain4j.dev/integrations/language-models/open-ai

Initialize the chat model using the provided demo key and proxy URL for demonstration purposes.

```java
OpenAiChatModel model = OpenAiChatModel.builder()  

    .baseUrl("http://langchain4j.dev/demo/openai/v1")  

    .apiKey("demo")  

    .modelName("gpt-4o-mini")  

    .build();  
```

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

### MCP Resource List JSON Example

Source: https://docs.langchain4j.dev/tutorials/mcp

An example of the JSON output format for a list of MCP resources, detailing server, URI, name, and MIME type.

```json
[ {
  "mcpServer" : "alice",
  "uri" : "file:///info",
  "uriTemplate" : null,
  "name" : "basicInfo",
  "description" : "Basic information about Alice",
  "mimeType" : "text/plain"
}, {
  "mcpServer" : "bob",
  "uri" : "file:///info",
  "uriTemplate" : null,
  "name" : "basicInfo",
  "description" : "Basic information about Bob",
  "mimeType" : "text/plain"
} ]
```

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

### Run Sentiment Analysis Examples

Source: https://docs.langchain4j.dev/tutorials/classification

Executes sentiment analysis on example texts using the created SentimentAnalyzer. It demonstrates classifying sentiment and checking if text is positive.

```java
Sentiment sentiment = sentimentAnalyzer.analyzeSentimentOf("I love this product!");

System.out.println(sentiment); // Expected Output: POSITIVE


boolean positive = sentimentAnalyzer.isPositive("This is a terrible experience.");

System.out.println(positive); // Expected Output: false
```

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

### Create Basic MCP Tool Provider

Source: https://docs.langchain4j.dev/tutorials/mcp

Instantiate an McpToolProvider using its builder and providing an McpClient. This is the most basic setup.

```java
McpToolProvider toolProvider = McpToolProvider.builder()
    .mcpClients(mcpClient)
    .build();
```

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

### StreamingChatModelSupplier Example

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/agentic/declarative/StreamingChatModelSupplier.html

This example demonstrates how to use the @StreamingChatModelSupplier annotation to provide a static streaming chat model. The method `chatModel` configures and returns an OpenAiStreamingChatModel with specific settings.

```java
public interface StreamingCreativeWriter {

    @UserMessage("""
            You are a creative writer.
            Generate a draft of a story long no more than 3 sentence around the given topic.
            Return only the story and nothing else.
            The topic is {{topic}}.
            """)
    @Agent(description = "Generate a story based on the given topic", outputKey = "story")
    TokenStream generateStory(@V("topic") String topic);

    @StreamingChatModelSupplier
    static StreamingChatModel chatModel() {
        return OpenAiStreamingChatModel.builder()
                .baseUrl(System.getenv("OPENAI_BASE_URL"))
                .apiKey(System.getenv("OPENAI_API_KEY"))
                .modelName(OpenAiChatModelName.GPT_4_O_MINI)
                .temperature(0.0)
                .logRequests(true)
                .build();
    }
}
```

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

### McpClient.instructions()

Source: https://docs.langchain4j.dev/apidocs/index-all.html

Retrieves the server instructions from the initialize result of an MCP client.

```APIDOC
## Method: McpClient.instructions()

### Description
Returns the server instructions from the initialize result, or null if the server did not provide any.

### Signature
String instructions()
```

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

### Supplier Interface Method - get

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/model/localai/spi/LocalAiEmbeddingModelBuilderFactory.html

The 'get' method inherited from the Supplier interface. This method is responsible for returning an instance of the supplier's type, in this case, LocalAiEmbeddingModel.LocalAiEmbeddingModelBuilder.

```java
/**
 * Returns a Supplier<LocalAiEmbeddingModel.LocalAiEmbeddingModelBuilder>.
 */
Supplier<LocalAiEmbeddingModel.LocalAiEmbeddingModelBuilder> get();
```

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

### Basic Usage Example

Source: https://docs.langchain4j.dev/integrations/embedding-stores/oceanbase

Initialize the OceanBase embedding store, add a document, and perform a similarity search.

```java
import dev.langchain4j.data.document.Metadata;  

import dev.langchain4j.data.embedding.Embedding;  

import dev.langchain4j.data.segment.TextSegment;  

import dev.langchain4j.model.embedding.EmbeddingModel;  

import dev.langchain4j.model.embedding.onnx.allminilml6v2q.AllMiniLmL6V2QuantizedEmbeddingModel;  

import dev.langchain4j.store.embedding.EmbeddingSearchRequest;  

import dev.langchain4j.store.embedding.EmbeddingSearchResult;  

import dev.langchain4j.store.embedding.oceanbase.OceanBaseEmbeddingStore;  

  

// Initialize embedding model  

EmbeddingModel embeddingModel = new AllMiniLmL6V2QuantizedEmbeddingModel();  

  

// Create embedding store  

OceanBaseEmbeddingStore embeddingStore = OceanBaseEmbeddingStore.builder()  

    .url("jdbc:oceanbase://127.0.0.1:2881/test")  

    .user("root@test")  

    .password("password")  

    .tableName("embeddings")  

    .dimension(384)  

    .build();  

  

// Add document with metadata  

String id = embeddingStore.add(  

    embeddingModel.embed("Java is a programming language").content(),  

    TextSegment.from("Java is a programming language",   

        Metadata.from("category", "programming").put("language", "Java"))  

);  

  

// Search  

Embedding queryEmbedding = embeddingModel.embed("programming language").content();  

EmbeddingSearchResult<TextSegment> results = embeddingStore.search(  

    EmbeddingSearchRequest.builder()  

        .queryEmbedding(queryEmbedding)  

        .maxResults(10)  

        .build()  

);  

  

// Process results  

results.matches().forEach(match -> {  

    System.out.println("Score: " + match.score());  

    System.out.println("Text: " + match.embedded().text());  

    System.out.println("Metadata: " + match.embedded().metadata());  

});
```

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

### GET /models

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/model/anthropic/internal/client/DefaultAnthropicClient.html

Lists available models from the Anthropic API. Sends a GET request to the /models endpoint to retrieve information about available Claude models.

```APIDOC
## GET /models

### Description
Lists available models from the Anthropic API. Sends a GET request to the `/models` endpoint to retrieve information about available Claude models.

### Method
GET

### Endpoint
/models

### Parameters
None

### Response
#### Success Response (200)
- **response** (AnthropicModelsListResponse) - The response containing the list of available models.

#### Response Example
```json
{
  "data": [
    {
      "id": "claude-3-opus-20240229",
      "type": "model",
      "created_at": "2024-02-29T10:00:00.000Z",
      "max_tokens": 200000,
      "name": "Claude 3 Opus"
    },
    {
      "id": "claude-3-sonnet-20240229",
      "type": "model",
      "created_at": "2024-02-29T10:00:00.000Z",
      "max_tokens": 200000,
      "name": "Claude 3 Sonnet"
    }
  ],
  "default_model": "claude-3-opus-20240229"
}
```
```

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

### Configure OpenAI Reasoning Models

Source: https://docs.langchain4j.dev/integrations/language-models/open-ai-official

Demonstrates initializing the chat model with reasoning effort and summary settings enabled.

```java
ChatModel model = OpenAiOfficialResponsesChatModel.builder()  

        .apiKey(System.getenv("OPENAI_API_KEY"))  

        .modelName("gpt-5-mini")  

        .reasoningEffort(ReasoningEffort.LOW)  

        .reasoningSummary(Reasoning.Summary.AUTO)  

        .build();  

  

ChatResponse response = model.chat("What is the capital of Germany?");  

response.aiMessage().text();     // "The capital of Germany is Berlin."  

response.aiMessage().thinking(); // reasoning summary text  
```

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

### Build project

Source: https://docs.langchain4j.dev/integrations/language-models/gpullama3-java

Command to clean and package the project.

```bash
mvn clean package  
```

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

### Get Video MIME Type in Java

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/data/video/Video.html

Explains how to get the MIME type of a video using the mimeType() method. Returns null if the MIME type is not set.

```java
String videoMimeType = video.mimeType();
```

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

### Creating a ChromaEmbeddingStore instance

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/store/embedding/chroma/class-use/ChromaEmbeddingStore.Builder.html

Demonstrates how to create a ChromaEmbeddingStore instance using the builder pattern.

```APIDOC
## Creating ChromaEmbeddingStore

### Static Factory Method

- `static ChromaEmbeddingStore.Builder builder()`: Returns a new instance of `ChromaEmbeddingStore.Builder`.

### Constructor

- `ChromaEmbeddingStore(ChromaEmbeddingStore.Builder builder)`: Initializes a new instance of `ChromaEmbeddingStore` with the specified builder.
```

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

### Configure SQLServerEmbeddingStore with DataSource

Source: https://docs.langchain4j.dev/integrations/embedding-stores/sqlserver

Examples for initializing the embedding store with various table creation strategies.

```java
EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()  

   .dataSource(myDataSource)  

   .embeddingTable(EmbeddingTable.builder()  

           .name("my_embedding_table")  

           .dimension(384) // Must specify dimension  

           .build())  

   .build();
```

```java
EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()  

   .dataSource(myDataSource)  

   .embeddingTable(EmbeddingTable.builder()  

           .name("my_embedding_table")  

           .createOption(CreateOption.CREATE)  

           .dimension(384)   

           .build())  

   .build();
```

```java
EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()  

   .dataSource(myDataSource)  

   .embeddingTable(EmbeddingTable.builder()  

           .name("my_embedding_table")  

           .createOption(CreateOption.CREATE_IF_NOT_EXISTS)  

           .dimension(384)   

           .build())  

   .build();
```

```java
EmbeddingStore<TextSegment> embeddingStore = SQLServerEmbeddingStore.dataSourceBuilder()  

   .dataSource(myDataSource)  

   .embeddingTable(EmbeddingTable.builder()  

           .name("my_embedding_table")  

           .createOption(CreateOption.CREATE_OR_REPLACE)  

           .dimension(384)   

           .build())  

   .build();
```

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

### Get PdfFile Base64 Data (Java)

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/data/pdf/PdfFile.html

Illustrates how to get the base64 encoded data of the PDF document. This method returns null if no base64 data is set for the PdfFile.

```java
String base64Data = pdfFile.base64Data();
```

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

### start()

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/service/AiServiceTokenStream.html

Completes the current token stream building and initiates the processing. This method triggers the request to the LLM and begins the response streaming process.

```APIDOC
## void start()

### Description
Completes the current token stream building and starts processing. This method sends a request to the LLM and begins streaming the response.

### Signature
`public void start()`
```

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

### OVHcloud AI Embedding Model Example

Source: https://docs.langchain4j.dev/integrations/embedding-models/ovh-ai

This example demonstrates how to initialize and use the OVHcloud AI Embedding model. It embeds text segments, stores them in an in-memory store, and performs a similarity search.

```java
import dev.langchain4j.data.embedding.Embedding;
import dev.langchain4j.data.segment.TextSegment;
import dev.langchain4j.model.embedding.EmbeddingModel;
import dev.langchain4j.model.ovhai.OvhAiEmbeddingModel;
import dev.langchain4j.store.embedding.EmbeddingMatch;
import dev.langchain4j.store.embedding.EmbeddingStore;
import dev.langchain4j.store.embedding.inmemory.InMemoryEmbeddingStore;

import java.util.List;

public class OvhAiEmbeddingSimpleExample {

    public static void main(String[] args) {

        EmbeddingModel model = OpenAiEmbeddingModel.builder()
                .baseUrl("https://oai.endpoints.kepler.ai.cloud.ovh.net/v1")
                .apiKey(System.getenv("OVHAI_AI_API_KEY"))
                .modelName("Qwen3-Embedding-8B")
                .logRequests(true)
                .logResponses(false) // embeddings are huge in logs
                .build();

        // For simplicity, this example uses an in-memory store, but you can choose any external compatible store for production environments.
        EmbeddingStore<TextSegment> embeddingStore = new InMemoryEmbeddingStore<>();

        TextSegment segment1 = TextSegment.from("I like football.");
        Embedding embedding1 = embeddingModel.embed(segment1).content();
        embeddingStore.add(embedding1, segment1);

        TextSegment segment2 = TextSegment.from("The weather is good today.");
        Embedding embedding2 = embeddingModel.embed(segment2).content();
        embeddingStore.add(embedding2, segment2);

        String userQuery = "What is your favourite sport?";

        Embedding queryEmbedding = embeddingModel.embed(userQuery).content();
        EmbeddingSearchRequest searchRequest = EmbeddingSearchRequest.builder()
                .queryEmbedding(queryEmbedding)
                .maxResults(1)
                .build();
        EmbeddingSearchResult<TextSegment> searchResult = embeddingStore.search(searchRequest);
        EmbeddingMatch<TextSegment> embeddingMatch = searchResult.matches().get(0);

        System.out.println("Question: " + userQuery); // What is your favourite sport?
        System.out.println("Response: " + embeddingMatch.embedded().text()); // I like football.

    }

}
```

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

### Constrain Model Output (Guided Decoding)

Source: https://docs.langchain4j.dev/apidocs/dev/langchain4j/model/watsonx/WatsonxStreamingChatModel.Builder.html

Methods to constrain the model's output using guided decoding, either by providing a list of specific string choices or a regular expression pattern.

```APIDOC
## guidedChoice

### Description
Constrains the model output to one of the given string choices (guided decoding).

### Method
public WatsonxStreamingChatModel.Builder guidedChoice(String... guidedChoice)

### Parameters
* `guidedChoice` (String...) - the allowed output values

### Returns
`this`

## guidedChoice

### Description
Constrains the model output to one of the given string choices (guided decoding).

### Method
public WatsonxStreamingChatModel.Builder guidedChoice(Set<String> guidedChoices)

### Parameters
* `guidedChoices` (Set<String>) - the set of allowed output values

### Returns
`this`

## guidedRegex

### Description
Constrains the model output to match the given regular expression (guided decoding).

### Method
public WatsonxStreamingChatModel.Builder guidedRegex(String guidedRegex)

### Parameters
* `guidedRegex` (String) - the regular expression pattern

### Returns
`this`

## guidedGrammar

### Description
Constrains the model output to conform to the given EBNF grammar (guided decoding).

### Method
public WatsonxStreamingChatModel.Builder guidedGrammar(String guidedGrammar)

### Parameters
* `guidedGrammar` (String) - the EBNF grammar string

### Returns
`this`
```

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

### Initialize VearchEmbeddingStore (Legacy API)

Source: https://docs.langchain4j.dev/integrations/embedding-stores/vearch

Create the VearchEmbeddingStore instance using the legacy configuration.

```java
VearchEmbeddingStore embeddingStore = VearchEmbeddingStore.builder()  

        .vearchConfig(vearchConfig)  

        .baseUrl(baseUrl)  

        .build();
```
Tokens:
Raw