Package com.tnsai.llm

Class ChatChunk

java.lang.Object

com.tnsai.llm.ChatChunk

public final class ChatChunk
extends Object

Represents a single chunk in a streaming LLM response.

ChatChunk is emitted during streaming chat operations, providing both the content token and rich metadata about the streaming progress. This enables real-time monitoring, token counting, and latency tracking.

Chunk Types

Type	Description	Content
ChatChunk.ChunkType.START	Stream started	Empty
ChatChunk.ChunkType.CONTENT	Token content	Text token
ChatChunk.ChunkType.TOOL_CALL	Tool invocation	Tool JSON
ChatChunk.ChunkType.DONE	Stream completed	Empty
ChatChunk.ChunkType.ERROR	Error occurred	Error message

Usage Example

 LLMClient client = new OpenAIClient("gpt-4o");

 // Stream with metadata
 client.streamChatWithSpec("Tell me a story", Optional.empty(), Optional.empty(), Optional.empty())
     .forEach(chunk -> {
         if (chunk.isContent()) {
             System.out.print(chunk.getContent());
         }

         // Track progress
         chunk.getTokenCount().ifPresent(count -> {
             System.err.println("Tokens so far: " + count);
         });

         // Check finish reason
         if (chunk.isDone()) {
             System.out.println("\nFinished: " + chunk.getFinishReason().orElse("unknown"));
         }
     });
 

Token Tracking

 AtomicInteger totalTokens = new AtomicInteger();
 long startTime = System.currentTimeMillis();

 client.streamChatWithSpec(message, system, history, tools)
     .forEach(chunk -> {
         chunk.getTokenCount().ifPresent(totalTokens::set);
     });

 long latency = System.currentTimeMillis() - startTime;
 System.out.printf("Generated %d tokens in %dms%n", totalTokens.get(), latency);
 

Error Handling

 client.streamChatWithSpec(message, system, history, tools)
     .forEach(chunk -> {
         if (chunk.isError()) {
             System.err.println("Stream error: " + chunk.getContent());
             return;
         }
         System.out.print(chunk.getContent());
     });
 

See Also:

• LLMClient.streamChatWithSpec(com.tnsai.llm.ChatRequest)
• ChatChunk.ChunkType

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static enum	ChatChunk.ChunkType	The type of streaming chunk.
static enum	ChatChunk.FinishReason	The reason why generation stopped.

Constructor Summary

Constructors

Constructor	Description
ChatChunk(ChatChunk.ChunkType type, String content, Instant timestamp, Integer tokenCount, Integer chunkIndex, ChatChunk.FinishReason finishReason, String model, String requestId)
ChatChunk(ChatChunk.ChunkType type, String content, Instant timestamp, Integer tokenCount, Integer chunkIndex, ChatChunk.FinishReason finishReason, String model, String requestId, ChatResponse.ToolCall toolCall)

Method Summary

Modifier and Type	Method	Description
static ChatChunk	content(String text)	Creates a CONTENT chunk with text token.
static ChatChunk	content(String text, int tokenCount, int chunkIndex)	Creates a CONTENT chunk with metadata.
static ChatChunk	content(String text, int tokenCount, int chunkIndex, String model, String requestId)	Creates a CONTENT chunk with full metadata.
static ChatChunk	done(ChatChunk.FinishReason reason, int totalTokens)	Creates a DONE chunk indicating successful completion.
static ChatChunk	done(ChatChunk.FinishReason reason, int totalTokens, String model, String requestId)	Creates a DONE chunk with full metadata.
static ChatChunk	error(String errorMessage)	Creates an ERROR chunk.
Optional<Integer>	getChunkIndex()	Gets the chunk index if available.
Optional<ChatChunk.FinishReason>	getFinishReason()	Gets the finish reason if available.
Optional<String>	getModel()	Gets the model if available.
Optional<String>	getRequestId()	Gets the request ID if available.
Optional<Integer>	getTokenCount()	Gets the token count if available.
Optional<ChatResponse.ToolCall>	getToolCall()	Gets the structured ToolCall data if this is a TOOL_CALL chunk.
boolean	isContent()	Checks if this is a content chunk.
boolean	isDone()	Checks if this is a done chunk.
boolean	isError()	Checks if this is an error chunk.
boolean	isStart()	Checks if this is a start chunk.
boolean	isToolCall()	Checks if this is a tool call chunk.
static ChatChunk	start(String model, String requestId)	Creates a START chunk indicating stream beginning.
static ChatChunk	toolCall(ChatResponse.ToolCall toolCall)	Creates a TOOL_CALL chunk with structured ToolCall data.
static ChatChunk	toolCall(String toolJson)	Creates a TOOL_CALL chunk with JSON content.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

ChatChunk

public ChatChunk(ChatChunk.ChunkType type,
 String content,
 Instant timestamp,
 Integer tokenCount,
 Integer chunkIndex,
 ChatChunk.FinishReason finishReason,
 String model,
 String requestId)

ChatChunk

public ChatChunk(ChatChunk.ChunkType type,
 String content,
 Instant timestamp,
 Integer tokenCount,
 Integer chunkIndex,
 ChatChunk.FinishReason finishReason,
 String model,
 String requestId,
 ChatResponse.ToolCall toolCall)

Method Details

start

public static ChatChunk start(String model,
 String requestId)

Creates a START chunk indicating stream beginning.

content

public static ChatChunk content(String text)

Creates a CONTENT chunk with text token.

content

public static ChatChunk content(String text,
 int tokenCount,
 int chunkIndex)

Creates a CONTENT chunk with metadata.

content

public static ChatChunk content(String text,
 int tokenCount,
 int chunkIndex,
 String model,
 String requestId)

Creates a CONTENT chunk with full metadata.

toolCall

public static ChatChunk toolCall(String toolJson)

Creates a TOOL_CALL chunk with JSON content.

toolCall

public static ChatChunk toolCall(ChatResponse.ToolCall toolCall)

Creates a TOOL_CALL chunk with structured ToolCall data.

done

public static ChatChunk done(ChatChunk.FinishReason reason,
 int totalTokens)

Creates a DONE chunk indicating successful completion.

done

public static ChatChunk done(ChatChunk.FinishReason reason,
 int totalTokens,
 String model,
 String requestId)

Creates a DONE chunk with full metadata.

error

public static ChatChunk error(String errorMessage)

Creates an ERROR chunk.

isContent

public boolean isContent()

Checks if this is a content chunk.

isStart

public boolean isStart()

Checks if this is a start chunk.

isDone

public boolean isDone()

Checks if this is a done chunk.

isError

public boolean isError()

Checks if this is an error chunk.

isToolCall

public boolean isToolCall()

Checks if this is a tool call chunk.

getTokenCount

public Optional<Integer> getTokenCount()

Gets the token count if available.

getChunkIndex

public Optional<Integer> getChunkIndex()

Gets the chunk index if available.

getFinishReason

public Optional<ChatChunk.FinishReason> getFinishReason()

Gets the finish reason if available.

getModel

public Optional<String> getModel()

Gets the model if available.

getRequestId

public Optional<String> getRequestId()

Gets the request ID if available.

getToolCall

public Optional<ChatResponse.ToolCall> getToolCall()

Gets the structured ToolCall data if this is a TOOL_CALL chunk.