### Start Node Registry Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-webapp-demo/README.md

Provides a configuration example for the 'Start' node, specifying its type, metadata (like non-deletable and non-copyable), and default ports.

```typescript
export const StartNodeRegistry: FlowNodeRegistry = {
  type: WorkflowNodeType.Start,
  meta: {
    isStart: true,
    deleteDisable: true,        // Not deletable
    copyDisable: true,          // Not copyable
    nodePanelVisible: false,    // Hidden in node panel
    defaultPorts: [{ type: 'output' }],
    size: { width: 360, height: 211 }
  },
  info: {
    icon: iconStart,
    description: 'The starting node of the workflow, used to set up information needed to launch the workflow.'
  },
  formMeta,
  canAdd() { return false; }    // Disallow multiple start nodes
};
```

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

### Interactive AI4J CLI example

Source: https://github.com/lnyo-cly/ai4j/blob/main/README-EN.md

Starts an interactive AI4J CLI session for chat with the Zhipu provider, specifying a base URL and workspace.

```powershell
ai4j code `
  --provider zhipu `
  --protocol chat `
  --model glm-4.7 `
  --base-url https://open.bigmodel.cn/api/coding/paas/v4 `
  --workspace .
```

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

### Simplified RAG Setup with DenseRetriever

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/rag/hybrid-retrieval-and-rerank-workflow.md

For simpler use cases like small demos or when latency is critical, start with a DenseRetriever and DefaultRagService. This can be expanded later to include more complex retrieval methods.

```text
DenseRetriever -> DefaultRagService
```

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

### Starting an MCP Server with McpServerFactory

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/mcp/build-your-mcp-server.md

Use McpServerFactory to create and start an MCP server instance. It normalizes transport type strings and instantiates the appropriate server. Streamable HTTP is recommended for external systems.

```java
import ai4j.mcp.server.McpServer;
import ai4j.mcp.server.McpServerFactory;

McpServer server = McpServerFactory.createServer(
        "streamable_http",
        "weather-server",
        "1.0.0",
        8081
);
server.start().join();
```

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

### Configure and Initialize OllamaAiChatService

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/chat-service.md

Example showing how to configure the Ollama service host and initialize the chat service.

```java
OllamaConfig config = new OllamaConfig();
config.setApiHost("http://localhost:11434");

Configuration configuration = new Configuration();
configuration.setOllamaConfig(config);

AiService aiService = new AiService(configuration);
IChatService chatService = aiService.getChatService(PlatformType.OLLAMA);
```

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

### Vector Store Configuration Example (Qdrant and pgvector)

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/rag/architecture-and-indexing.md

Example of configuring Qdrant and pgvector as vector stores in a Spring Boot application. Ensure the correct host, API key, and JDBC URL are provided.

```yaml
ai:
  vector:
    qdrant:
      enabled: true
      host: http://localhost:6333
      api-key: ""
    pgvector:
      enabled: false
      jdbc-url: jdbc:postgresql://localhost:5432/postgres
      username: postgres
      password: postgres
      table-name: ai4j_vectors
```

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

### Configuration Normalization Examples

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/coding-agent/configuration.md

Illustrates common normalization steps applied to loaded configurations. These steps ensure consistency and control over configuration values.

```text
- Trim whitespace from fields.
- Normalize empty strings to null.
- Remove empty profile names.
- Clear non-existent defaultProfile.
- Deduplicate and order lists like enabledMcpServers, skillDirectories, agentDirectories.
- Normalize 'http' MCP transport to 'streamable_http'.
```

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

### Install AI4J CLI using curl

Source: https://github.com/lnyo-cly/ai4j/blob/main/README-EN.md

Installs the AI4J CLI by downloading the script from the provided URL. Ensure Java 8+ is installed.

```bash
curl -fsSL https://lnyo-cly.github.io/ai4j/install.sh | sh
```

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

### Implement Realtime service client

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Example of creating a WebSocket client with a listener to handle real-time audio and transcript events.

```java
IRealtimeService realtimeService = aiService.getRealtimeService(PlatformType.OPENAI);

RealtimeListener listener = new RealtimeListener() {
    @Override
    public void onConnected(WebSocket ws) {
        System.out.println("Connected to realtime API");
    }

    @Override
    public void onAudioDelta(String delta) {
        // Handle audio chunk
    }

    @Override
    public void onTranscriptDelta(String delta) {
        System.out.print(delta);
    }

    @Override
    public void onError(Exception e) {
        e.printStackTrace();
    }
};

WebSocket ws = realtimeService.createRealtimeClient("gpt-4o-realtime-preview", listener);

// Send audio
ws.send("{\"type\": \"input_audio_buffer.append\", \"audio\": \"...\"}");

// Close when done
ws.close(1000, "Closing");
```

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

### Install AI4J CLI using PowerShell

Source: https://github.com/lnyo-cly/ai4j/blob/main/README-EN.md

Installs the AI4J CLI by downloading the PowerShell script. Java 8+ must be pre-installed.

```powershell
irm https://lnyo-cly.github.io/ai4j/install.ps1 | iex
```

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

### Speech-to-Text (Transcription) Minimum Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/services/audio.md

Basic example for transcribing speech from an audio file to text. Requires specifying the audio file, model, language, and response format.

```java
Transcription request = Transcription.builder()
        .file(new File("D:/audio/demo.mp3"))
        .model("whisper-1")
        .language("zh")
        .responseFormat("json")
        .build();

TranscriptionResponse response = audioService.transcription(request);
System.out.println(response.getText());
```

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

### Configure and Initialize OpenAiChatService

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/chat-service.md

Example showing how to configure the OpenAI service using an API key and host, then initializing the chat service.

```java
OpenAiConfig config = new OpenAiConfig();
config.setApiKey(System.getenv("OPENAI_API_KEY"));
config.setApiHost("https://api.openai.com");

Configuration configuration = new Configuration();
configuration.setOpenAiConfig(config);

AiService aiService = new AiService(configuration);
IChatService chatService = aiService.getChatService(PlatformType.OPENAI);
```

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

### Execute a RAG search

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/rag-service.md

Example of initializing the RagService and executing a search query with specific parameters.

```java
RagService ragService = aiService.getRagService(
    PlatformType.OPENAI,
    vectorStore
);

RagQuery query = RagQuery.builder()
    .query("What are the leave policies?")
    .dataset("employee_handbook")
    .embeddingModel("text-embedding-3-small")
    .topK(5)
    .includeCitations(true)
    .includeTrace(true)
    .build();

RagResult result = ragService.search(query);
System.out.println("Context:\n" + result.getContext());
System.out.println("Citations:\n" + result.getCitations());
System.out.println("Trace:\n" + result.getTrace());
```

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

### Generate Image Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Demonstrates how to configure an ImageGeneration request and process the response using the OpenAI service.

```java
IImageService imageService = aiService.getImageService(PlatformType.OPENAI);

ImageGeneration request = ImageGeneration.builder()
    .model("dall-e-3")
    .prompt("A serene landscape with mountains and a lake at sunset")
    .size("1024x1024")
    .quality("hd")
    .n(1)
    .build();

ImageGenerationResponse response = imageService.generate(request);
response.getData().forEach(image -> {
    System.out.println("Image URL: " + image.getUrl());
    System.out.println("Revised prompt: " + image.getRevisedPrompt());
});
```

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

### Text-to-Speech (TTS) Minimum Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/services/audio.md

Basic example for converting text to speech using the TTS capability. Requires specifying model, voice, input text, and response format.

```java
IAudioService audioService = aiService.getAudioService(PlatformType.OPENAI);

TextToSpeech request = TextToSpeech.builder()
        .model("tts-1")
        .voice("alloy")
        .input("欢迎使用 AI4J")
        .responseFormat("mp3")
        .speed(1.0)
        .build();

InputStream stream = audioService.textToSpeech(request);
```

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

### Dependency Injection Setup

Source: https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-webapp-demo/README.md

Sets up dependency injection using Inversify, allowing for singleton scope management of custom services.

```typescript
onBind: ({ bind }) => {
  bind(CustomService).toSelf().inSingletonScope();
}
```

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

### Configure Spring Boot Integration

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/README.md

Setup instructions for Spring Boot applications including dependency management, configuration, and service injection.

```xml
<dependency>
    <groupId>io.github.lnyo-cly</groupId>
    <artifactId>ai4j-spring-boot-starter</artifactId>
    <version>latest</version>
</dependency>
```

```yaml
ai:
  openai:
    api-key: "${OPENAI_API_KEY}"
```

```java
@Autowired
private AiService aiService;

// Or directly:
@Autowired
private IChatService chatService;
```

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

### create

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Starts an asynchronous completion task and returns a Response object containing the task ID.

```APIDOC
## create

### Description
Starts an async completion task.

### Signature
- Response create(ResponseRequest request) throws Exception
- Response create(String baseUrl, String apiKey, ResponseRequest request) throws Exception

### Returns
- Response - Task object containing the ID for polling
```

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

### Use Fetch Service for Web Retrieval

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/mcp-integration.md

Example of utilizing the 'fetch' MCP service to retrieve and summarize content from a URL.

```java
ChatCompletion request = ChatCompletion.builder()
    .model("gpt-4o")
    .message(ChatMessage.withUser("Summarize https://example.com"))
    .mcpService("fetch")
    .build();

ChatCompletionResponse response = chatService.chatCompletion(request);
String summary = response.getChoices().get(0).getMessage().getContent().getText();
System.out.println(summary);
```

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

### One-shot AI4J CLI command example

Source: https://github.com/lnyo-cly/ai4j/blob/main/README-EN.md

Executes a single AI4J command to read a README and summarize the project structure using the OpenAI provider.

```powershell
ai4j code `
  --provider openai `
  --protocol responses `
  --model gpt-5-mini `
  --prompt "Read README and summarize the project structure"
```

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

### Get Image Service Entry Point

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/services/image-generation.md

Obtain an instance of the IImageService for a specific platform. An exception is thrown if the platform does not support image services.

```java
IImageService imageService = aiService.getImageService(PlatformType.OPENAI);
```

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

### AI4J TUI example

Source: https://github.com/lnyo-cly/ai4j/blob/main/README-EN.md

Launches the AI4J Text User Interface (TUI) for chat with the Zhipu provider, including base URL and workspace configuration.

```powershell
ai4j tui `
  --provider zhipu `
  --protocol chat `
  --model glm-4.7 `
  --base-url https://open.bigmodel.cn/api/coding/paas/v4 `
  --workspace .
```

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

### Get Audio Service Entry Point

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/services/audio.md

Obtain an instance of IAudioService for audio operations. If the platform does not support audio capabilities, AiService will throw an exception.

```java
IAudioService audioService = aiService.getAudioService(PlatformType.OPENAI);
```

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

### Real LLM Example FlowGram Task

Source: https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-demo/README.md

Constructs a FlowGram with a Start, LLM, and End node to interact with an LLM. It sends a prompt and retrieves the result.

```powershell
$body = @{
  schema = @{
    nodes = @(
      @{ 
        id = "start_0"
        type = "Start"
        name = "start_0"
        data = @{
          outputs = @{
            type = "object"
            required = @("message")
            properties = @{
              message = @{ type = "string" }
            }
          }
        }
      },
      @{ 
        id = "llm_0"
        type = "LLM"
        name = "llm_0"
        data = @{
          inputs = @{
            type = "object"
            required = @("modelName", "prompt")
            properties = @{
              modelName = @{ type = "string" }
              prompt = @{ type = "string" }
            }
          }
          outputs = @{
            type = "object"
            required = @("result")
            properties = @{
              result = @{ type = "string" }
            }
          }
          inputsValues = @{
            modelName = @{
              type = "constant"
              content = "glm-4.7"
            }
            prompt = @{
              type = "ref"
              content = @("start_0", "message")
            }
          }
        }
      },
      @{ 
        id = "end_0"
        type = "End"
        name = "end_0"
        data = @{
          inputs = @{
            type = "object"
            required = @("result")
            properties = @{
              result = @{ type = "string" }
            }
          }
          inputsValues = @{
            result = @{
              type = "ref"
              content = @("llm_0", "result")
            }
          }
        }
      }
    )
    edges = @(
      @{ 
        sourceNodeID = "start_0"
        targetNodeID = "llm_0"
      },
      @{ 
        sourceNodeID = "llm_0"
        targetNodeID = "end_0"
      }
    )
  }
  inputs = @{
    message = "Please answer with exactly three words: FlowGram spring boot."
  }
} | ConvertTo-Json -Depth 12

$run = Invoke-RestMethod -Method Post -Uri "http://127.0.0.1:18080/flowgram/tasks/run" -ContentType "application/json" -Body $body
$result = Invoke-RestMethod -Method Get -Uri ("http://127.0.0.1:18080/flowgram/tasks/" + $run.taskId + "/result")
```

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

### Build and Run the Demo

Source: https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-demo/README.md

Sets the ZHIPU_API_KEY environment variable, packages the demo using Maven, and then runs the packaged JAR file.

```powershell
$env:ZHIPU_API_KEY="your-key"
cmd /c "mvn -pl ai4j-flowgram-demo -am -DskipTests package"
java -jar ai4j-flowgram-demo/target/ai4j-flowgram-demo-2.1.0.jar
```

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

### Configure OkHttp Client

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/configuration.md

Demonstrates setting up the OkHttpConfig and applying a custom OkHttpClient to the main configuration.

```java
OkHttpConfig httpConfig = new OkHttpConfig();
httpConfig.setConnectTimeout(30000L);
httpConfig.setReadTimeout(60000L);
httpConfig.setWriteTimeout(60000L);
httpConfig.setProxyHost("127.0.0.1");
httpConfig.setProxyPort(10809);
httpConfig.setLog(HttpLoggingInterceptor.Level.HEADERS);

Configuration configuration = new Configuration();
// Note: OkHttpClient is set directly on Configuration
OkHttpClient okHttpClient = new OkHttpClient.Builder()
    .connectTimeout(30, TimeUnit.SECONDS)
    .readTimeout(60, TimeUnit.SECONDS)
    .writeTimeout(60, TimeUnit.SECONDS)
    .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1", 10809)))
    .addInterceptor(new HttpLoggingInterceptor().setLevel(HttpLoggingInterceptor.Level.HEADERS))
    .build();
configuration.setOkHttpClient(okHttpClient);
```

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

### Minimal STDIO MCP Client Integration

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/mcp/client-integration.md

This example demonstrates the shortest path to connect to a local MCP server via stdio, initialize the client, call a tool, and disconnect. It verifies subprocess startup, stdio transport handshake, and basic tool listing/calling functionality.

```java
McpTransport transport = new StdioTransport(
        "npx",
        Arrays.asList("-y", "@modelcontextprotocol/server-filesystem", "D:/workspace"),
        null
);

McpClient client = new McpClient("demo-client", "1.0.0", transport);
client.connect().join();

List<McpToolDefinition> tools = client.getAvailableTools().join();
String result = client.callTool("read_file", Collections.singletonMap("path", "README.md")).join();

client.disconnect().join();
```

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

### LLM Example Result

Source: https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-demo/README.md

The expected JSON output from a successful execution of the Real LLM Example FlowGram task.

```json
{
  "status": "success",
  "result": "FlowGram spring boot"
}
```

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

### Frontend and Documentation Build Commands

Source: https://github.com/lnyo-cly/ai4j/blob/main/AGENTS.md

Commands for building frontend and documentation surfaces.

```bash
npm run build
```

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

### Example Context for Model Consumption

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/rag/citations-trace-and-ui-integration.md

This is an example of the text blocks provided as context for a language model. It includes source identifiers like [S1] and [S2] which can be mapped to citations.

```text
[S1] employee-handbook.pdf / 员工请假
员工请假需至少提前 3 个工作日提交申请，紧急病假除外。

[S2] employee-handbook.pdf / 医疗报销
补充医疗报销需在费用发生后 30 日内提交单据。
```

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

### Audio Translation Minimum Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/services/audio.md

Basic example for translating audio content from a foreign language to English text. Requires specifying the audio file, model, and response format.

```java
Translation request = Translation.builder()
        .file(new File("D:/audio/jp.wav"))
        .model("whisper-1")
        .responseFormat("json")
        .build();

TranslationResponse response = audioService.translation(request);
System.out.println(response.getText());
```

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

### Initialize Configuration for Non-Spring Projects

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/unified-service-entry.md

Set up the Configuration object with platform-specific settings (e.g., OpenAI API key) and an OkHttpClient for network requests. This is for applications not using Spring Boot.

```java
OpenAiConfig openAiConfig = new OpenAiConfig();
openAiConfig.setApiKey(System.getenv("OPENAI_API_KEY"));

Configuration configuration = new Configuration();
configuration.setOpenAiConfig(openAiConfig);

OkHttpClient okHttpClient = new OkHttpClient.Builder()
        .addInterceptor(new ErrorInterceptor())
        .connectTimeout(300, TimeUnit.SECONDS)
        .writeTimeout(300, TimeUnit.SECONDS)
        .readTimeout(300, TimeUnit.SECONDS)
        .build();

configuration.setOkHttpClient(okHttpClient);

AiService aiService = new AiService(configuration);
```

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

### Initialize AI Service without Spring Boot

Source: https://github.com/lnyo-cly/ai4j/blob/main/README-EN.md

Demonstrates manual initialization of AI services using OkHttpClient for custom configurations like logging and proxy settings. This is for non-Spring applications.

```java
public void test_init(){
    OpenAiConfig openAiConfig = new OpenAiConfig();

    Configuration configuration = new Configuration();
    configuration.setOpenAiConfig(openAiConfig);

    HttpLoggingInterceptor httpLoggingInterceptor = new HttpLoggingInterceptor();
    httpLoggingInterceptor.setLevel(HttpLoggingInterceptor.Level.HEADERS);

    OkHttpClient okHttpClient = new OkHttpClient
            .Builder()
            .addInterceptor(httpLoggingInterceptor)
            .addInterceptor(new ErrorInterceptor())
            .connectTimeout(300, TimeUnit.SECONDS)
            .writeTimeout(300, TimeUnit.SECONDS)
            .readTimeout(300, TimeUnit.SECONDS)
            .proxy(new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1",10809)))
            .build();
    configuration.setOkHttpClient(okHttpClient);

    AiService aiService = new AiService(configuration);

    embeddingService = aiService.getEmbeddingService(PlatformType.OPENAI);
    chatService = aiService.getChatService(PlatformType.getPlatform("OPENAI"));

}
```

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

### Initialize McpGateway with Configuration File

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/mcp/gateway-management.md

Initializes the McpGateway using a local JSON configuration file. The initialization process loads server configurations, starts enabled services, creates McpClients, connects them, and refreshes the tool registry. Note that successful initialization does not guarantee all services are connected.

```java
McpGateway gateway = new McpGateway();
gateway.initialize("mcp-servers-config.json").join();
```

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

### Initializing McpGateway with MySQL Configuration Source

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/mcp/mysql-dynamic-datasource.md

This Java snippet demonstrates how to integrate a custom MySQL-based configuration source with the McpGateway. It shows the process of creating an instance of the custom source, binding it to the gateway, and initializing the gateway.

```java
MysqlMcpConfigSource source = new MysqlMcpConfigSource(...);
McpGateway gateway = new McpGateway();
gateway.setConfigSource(source);
gateway.initialize().join();
```

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

### Register and Use MCP Service in Java

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/mcp-integration.md

Demonstrates initializing the AI service with MCP configuration and executing a chat completion request that utilizes an MCP tool.

```java
// Setup
Configuration configuration = new Configuration();
OpenAiConfig openAiConfig = new OpenAiConfig();
openAiConfig.setApiKey(System.getenv("OPENAI_API_KEY"));
configuration.setOpenAiConfig(openAiConfig);

McpConfig mcpConfig = new McpConfig();
mcpConfig.setServerUrl("http://localhost:8000");
mcpConfig.setTransportType("http");
mcpConfig.setEnableHeartbeat(true);
configuration.setMcpConfig(mcpConfig);

AiService aiService = new AiService(configuration);
IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

// Use MCP tools
ChatCompletion request = ChatCompletion.builder()
    .model("gpt-4o")
    .message(ChatMessage.withSystem(
        "You are a helpful assistant with access to web search."))
    .message(ChatMessage.withUser(
        "What are the latest developments in quantum computing?"))
    .mcpService("web-search")
    .build();

try {
    ChatCompletionResponse response = chatService.chatCompletion(request);
    System.out.println(response.getChoices().get(0).getMessage().getContent().getText());
} catch (Exception e) {
    System.err.println("Error: " + e.getMessage());
    e.printStackTrace();
}
```

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

### Responses Linkage Minimal Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/ai-basics/chat/chat-memory.md

This example shows how to use ChatMemory with the Responses API. It initializes memory, adds system and user messages, constructs a ResponseRequest, sends it to the service, and extracts the output text. The assistant's response is then added back to memory.

```java
IResponsesService responsesService = aiService.getResponsesService(PlatformType.DOUBAO);

ChatMemory memory = new InMemoryChatMemory();
memory.addSystem("你是一个简洁的中文助手");
memory.addUser("请用一句话介绍 Responses API");

ResponseRequest request = ResponseRequest.builder()
        .model("doubao-seed-1-8-251228")
        .input(memory.toResponsesInput())
        .build();

Response response = responsesService.create(request);
String answer = extractOutputText(response);

memory.addAssistant(answer);
```

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

### Configure Qdrant Connection

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/configuration.md

Initializes Qdrant configuration and registers it with the main configuration object.

```java
QdrantConfig config = new QdrantConfig();
config.setHost("localhost");
config.setPort(6333);

Configuration configuration = new Configuration();
configuration.setQdrantConfig(config);
```

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

### Get Realtime Service

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/ai-service.md

Retrieves a service for WebSocket-based streaming.

```java
public IRealtimeService getRealtimeService(PlatformType platform)
```

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

### Get Messages Service

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/ai-service.md

Retrieves an Anthropic messages service instance.

```java
public IMessagesService getMessagesService(PlatformType platform)
```

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

### Sequential Workflow Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/agent/workflow-stategraph.md

Demonstrates a sequential workflow where the output of one node becomes the input of the next. Useful for step-by-step processing like draft to review to formatting.

```java
SequentialWorkflow workflow = new SequentialWorkflow()
        .addNode(new RuntimeAgentNode(draftAgent.newSession()))
        .addNode(new RuntimeAgentNode(formatAgent.newSession()));
```

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

### Qdrant VectorStore Implementation

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/rag-service.md

Initializes the Qdrant vector store and configures connection settings.

```java
VectorStore vectorStore = aiService.getQdrantVectorStore();
```

```java
QdrantConfig qdrantConfig = new QdrantConfig();
qdrantConfig.setHost("localhost");
qdrantConfig.setPort(6333);
// Optional TLS and auth settings
```

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

### Install AI4J Dependency

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/README.md

Add the AI4J dependency to your Maven project configuration.

```xml
<dependency>
    <groupId>io.github.lnyo-cly</groupId>
    <artifactId>ai4j</artifactId>
    <version>latest</version>
</dependency>
```

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

### Create ChatCompletion with image

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/chat-service.md

Example of building a request that includes an image URL.

```java
ChatCompletion request = ChatCompletion.builder()
    .model("gpt-4o")
    .message(ChatMessage.withUser("What's in this image?", "https://example.com/image.jpg"))
    .build();

ChatCompletionResponse response = chatService.chatCompletion(request);
```

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

### Get Vector Store

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/ai-service.md

Retrieves a vector store implementation for RAG operations.

```java
public VectorStore getQdrantVectorStore()
public VectorStore getPineconeVectorStore()
public VectorStore getMilvusVectorStore()
public VectorStore getPgVectorStore()
```

```java
VectorStore vectorStore = aiService.getQdrantVectorStore();
```

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

### Agent Service Selection Example

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/mcp/mysql-dynamic-datasource.md

This Java code illustrates how an Agent selects visible services using a tool registry. It highlights that even when using a MySQL-based configuration source, the Agent's service visibility is controlled by its own configuration, not directly by the MySQL data.

```java
.toolRegistry(Collections.<String>emptyList(), Arrays.asList("weather-http"))
```

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

### Get Responses Service

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/ai-service.md

Retrieves an OpenAI async API service for long-running tasks.

```java
public IResponsesService getResponsesService(PlatformType platform)
```

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

### Execute Anthropic messages request

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Example of building and sending a chat completion request to Anthropic.

```java
IMessagesService messagesService = aiService.getMessagesService(PlatformType.ANTHROPIC);

AnthropicChatCompletion request = AnthropicChatCompletion.builder()
    .model("claude-3-opus-20240229")
    .maxTokens(1024)
    .message(ChatMessage.withUser("Explain quantum entanglement"))
    .build();

AnthropicChatCompletionResponse response = messagesService.messages(request);
System.out.println(response.getContent().get(0).getText());
```

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

### Perform Document Reranking

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Example usage of the IRerankService to rerank documents using the Jina platform.

```java
IRerankService rerankService = aiService.getRerankService(PlatformType.JINA);

RerankRequest request = RerankRequest.builder()
    .model("jina-reranker-v2-base-multilingual")
    .query("What is the return policy?")
    .document(RerankDocument.builder()
        .id("doc1")
        .text("We offer 30-day money-back guarantee on all purchases")
        .build())
    .document(RerankDocument.builder()
        .id("doc2")
        .text("Our company was founded in 2010 in San Francisco")
        .build())
    .document(RerankDocument.builder()
        .id("doc3")
        .text("Refunds are processed within 5-7 business days")
        .build())
    .topN(2)
    .build();

RerankResponse response = rerankService.rerank(request);
response.getResults().forEach(result -> {
    System.out.println("Document index: " + result.getIndex());
    System.out.println("Relevance score: " + result.getRelevanceScore());
});
```

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

### Configure via Environment Variables

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/configuration.md

Set API keys and proxy settings using standard environment variables for auto-configuration.

```bash
# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=...

# Zhipu
ZHIPU_API_KEY=...

# DeepSeek
DEEPSEEK_API_KEY=...

# Moonshot
MOONSHOT_API_KEY=...

# Ollama (optional)
OLLAMA_API_KEY=...

# Vector Databases
PINECONE_API_KEY=...

# Proxy (optional)
HTTP_PROXY=http://127.0.0.1:10809
HTTPS_PROXY=http://127.0.0.1:10809
```

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

### Translate audio with IAudioService

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Example of building a translation request and printing the resulting translated text.

```java
Translation request = Translation.builder()
    .file(new File("spanish_audio.mp3"))
    .model("whisper-1")
    .responseFormat(WhisperEnum.ResponseFormat.JSON)
    .build();

TranslationResponse response = audioService.translation(request);
System.out.println("Translated text: " + response.getText());
```

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

### Smoke Test HTTP Endpoint

Source: https://github.com/lnyo-cly/ai4j/blob/main/skills/ai4j-app-builder/references/verification.md

Verifies an HTTP endpoint using curl after the application has started.

```bash
curl "http://localhost:8080/ai/chat?q=hello"
```

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

### Configure AI4J Service Parameters

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/configuration.md

Demonstrates the difference between providing direct parameters and using the default Configuration object.

```java
// These use direct parameters, overriding all other configs
chatService.chatCompletion("https://custom.api.com", "custom-key", request);

// These use Configuration from AiService
chatService.chatCompletion(request);
```

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

### Configure AI4J in Spring Boot

Source: https://github.com/lnyo-cly/ai4j/blob/main/skills/ai4j-app-builder/references/app-paths.md

Example configuration for Spring Boot applications using environment variables.

```yaml
ai:
  openai:
    api-key: ${OPENAI_API_KEY}
```

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

### Packaging a Module for Release

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/getting-started/modules-and-maven-central.md

This command packages a specific module (e.g., 'ai4j') for release, skipping tests. Use the '-Prelease' profile for release-related configurations. The actual deployment to Maven Central would follow with a 'deploy' goal.

```bash
mvn -pl ai4j -Prelease -DskipTests package
```

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

### Gradle Dependency with BOM

Source: https://github.com/lnyo-cly/ai4j/blob/main/docs-site/docs/getting-started/installation.md

Example of how to include AI4J dependencies using Gradle and the BOM for version management.

```gradle
dependencies {
    implementation platform('io.github.lnyo-cly:ai4j-bom:2.1.0')
    implementation 'io.github.lnyo-cly:ai4j'
}
```

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

### Implement a complete RAG pipeline in Java

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/rag-service.md

Configures the AI service, ingests documents into Qdrant, performs retrieval with Jina reranking, and generates responses using OpenAI.

```java
// Setup
Configuration configuration = new Configuration();
OpenAiConfig openAiConfig = new OpenAiConfig();
openAiConfig.setApiKey(System.getenv("OPENAI_API_KEY"));
configuration.setOpenAiConfig(openAiConfig);

QdrantConfig qdrantConfig = new QdrantConfig();
qdrantConfig.setHost("localhost");
qdrantConfig.setPort(6333);
configuration.setQdrantConfig(qdrantConfig);

AiService aiService = new AiService(configuration);

// 1. Ingest documents
VectorStore vectorStore = aiService.getQdrantVectorStore();
IngestionPipeline pipeline = aiService.getIngestionPipeline(
    PlatformType.OPENAI,
    vectorStore
);

IngestionResult result = pipeline.ingest(IngestionRequest.builder()
    .dataset("company_docs")
    .embeddingModel("text-embedding-3-small")
    .document(RagDocument.builder()
        .sourceName("Policy Manual")
        .sourcePath("/docs/policies.pdf")
        .tenant("company_a")
        .version("2024.03")
        .build())
    .source(IngestionSource.file(new File("policies.pdf")))
    .build());

System.out.println("Indexed " + result.getUpsertedCount() + " documents");

// 2. Retrieve with reranking
Reranker reranker = aiService.getModelReranker(
    PlatformType.JINA,
    "jina-reranker-v2-base-multilingual",
    5,
    "Prioritize policy documents and official language"
);

RagService ragService = new DefaultRagService(
    new DenseRetriever(
        aiService.getEmbeddingService(PlatformType.OPENAI),
        vectorStore
    ),
    reranker,
    new DefaultRagContextAssembler()
);

// 3. Query
RagQuery query = RagQuery.builder()
    .query("What is the vacation policy?")
    .dataset("company_docs")
    .embeddingModel("text-embedding-3-small")
    .topK(10)
    .finalTopK(3)
    .includeCitations(true)
    .build();

RagResult ragResult = ragService.search(query);

// 4. Use with LLM
IChatService chatService = aiService.getChatService(PlatformType.OPENAI);

ChatCompletion llmRequest = ChatCompletion.builder()
    .model("gpt-4o-mini")
    .message(ChatMessage.withSystem(
        "You are a helpful HR assistant. Answer using the provided context."))
    .message(ChatMessage.withSystem(
        "Context:\n" + ragResult.getContext()))
    .message(ChatMessage.withUser("What is the vacation policy?"))
    .build();

ChatCompletionResponse llmResponse = chatService.chatCompletion(llmRequest);
System.out.println(llmResponse.getChoices().get(0).getMessage().getContent().getText());

// 5. Show citations
ragResult.getCitations().forEach(citation -> {
    System.out.println("Source: " + citation.getSourceName());
});
```

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

### Convert text to speech with IAudioService

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Example of generating an audio stream from text and saving the output to a file.

```java
TextToSpeech request = TextToSpeech.builder()
    .input("Hello, this is a test of text to speech")
    .model("tts-1")
    .voice(AudioEnum.Voice.NOVA)
    .responseFormat(AudioEnum.ResponseFormat.MP3)
    .speed(1.0f)
    .build();

InputStream audioStream = audioService.textToSpeech(request);

// Save to file
try (FileOutputStream fos = new FileOutputStream("output.mp3")) {
    audioStream.transferTo(fos);
}
```

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

### Verify the Plugin with Maven

Source: https://github.com/lnyo-cly/ai4j/blob/main/ai4j-plugin-ask-user/README.md

Run tests for the ask-user plugin module using Maven.

```bash
mvn -pl ai4j-plugin-ask-user -am -DskipTests=false test
```

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

### Transcribe audio with IAudioService

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/other-services.md

Example of building a transcription request and processing the response to extract text and segments.

```java
IAudioService audioService = aiService.getAudioService(PlatformType.OPENAI);

Transcription request = Transcription.builder()
    .file(new File("audio.mp3"))
    .model("whisper-1")
    .responseFormat(WhisperEnum.ResponseFormat.VERBOSE_JSON)
    .language("en")
    .temperature(0.5f)
    .build();

TranscriptionResponse response = audioService.transcription(request);
System.out.println("Text: " + response.getText());
response.getSegments().forEach(segment -> {
    System.out.println("Segment: " + segment.getText());
    System.out.println("Start: " + segment.getStart());
    System.out.println("End: " + segment.getEnd());
});
```

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

### Initialize Development Worktree

Source: https://github.com/lnyo-cly/ai4j/blob/main/coding-agent-harness/planning/modules/cli-host/tasks/2026-06-20-cli-memory-compact-command-ux-d56c15fd/references/cli-memory-compact-command-ux-plan.md

Sets up a new git worktree for the feature branch and verifies the harness status.

```powershell
git fetch origin dev
git worktree add -b feature/cli-memory-compact-ux .worktrees/feature/cli-memory-compact-ux origin/dev
cd .worktrees/feature/cli-memory-compact-ux
npx --yes coding-agent-harness status --json .
```

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

### Get Token Usage for Embedding Requests

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/api-reference/embedding-service.md

Retrieves and prints prompt and total token counts from an embedding response.

```java
EmbeddingResponse response = embeddingService.embedding(request);
Usage usage = response.getUsage();
System.out.println("Prompt tokens: " + usage.getPromptTokens());
System.out.println("Total tokens: " + usage.getTotalTokens());
```

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

### Get FlowGram Task Result

Source: https://github.com/lnyo-cly/ai4j/blob/main/ai4j-flowgram-demo/README.md

Retrieves the result of a previously submitted FlowGram task using its task ID.

```APIDOC
## GET /flowgram/tasks/{taskId}/result

### Description
Fetches the final result of a FlowGram task identified by its unique task ID.

### Method
GET

### Endpoint
`/flowgram/tasks/{taskId}/result`

### Parameters
#### Path Parameters
- **taskId** (string) - Required - The unique identifier of the task whose result is to be retrieved.

### Response
#### Success Response (200)
- **status** (string) - The execution status of the task (e.g., "success").
- **result** (string) - The output of the completed FlowGram task.

### Response Example
```json
{
  "status": "success",
  "result": "FlowGram spring boot"
}
```
```

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

### Configure Multiple AI Platforms

Source: https://github.com/lnyo-cly/ai4j/blob/main/_autodocs/README.md

Initialize the configuration object with multiple platform providers and switch between them using the service instance.

```java
// Same configuration object handles all platforms
Configuration config = new Configuration();
config.setOpenAiConfig(openAiConfig);
config.setZhipuConfig(zhipuConfig);
config.setOllamaConfig(ollamaConfig);

AiService aiService = new AiService(config);

// Switch between them
IChatService openAi = aiService.getChatService(PlatformType.OPENAI);
IChatService zhipu = aiService.getChatService(PlatformType.ZHIPU);
IChatService ollama = aiService.getChatService(PlatformType.OLLAMA);
```