Package com.tnsai.llm.format

Class JsonModeClient

java.lang.Object
com.tnsai.llm.format.JsonModeClient
All Implemented Interfaces:
com.tnsai.llm.LLMClient
public class JsonModeClient extends Object implements com.tnsai.llm.LLMClient
LLM client wrapper that enforces JSON mode output.

Wraps any LLMClient to provide structured JSON output support. Uses provider-native JSON mode when available, falls back to prompt engineering for providers that don't support it natively.

Quick Start


 // Wrap an existing client
 LLMClient baseClient = new OpenAIClient("gpt-4o");
 JsonModeClient client = JsonModeClient.wrap(baseClient);

 // Get JSON response
 ChatResponse response = client.chat("List 3 programming languages");
 // Response: {"languages": ["Python", "Java", "JavaScript"]}

 // Parse to specific type
 LanguageList list = client.chatAs(LanguageList.class, "List 3 programming languages");

With JSON Schema


 // Define schema
 ResponseFormat format = ResponseFormat.jsonSchema("Person", Map.of(
     "type", "object",
     "properties", Map.of(
         "name", Map.of("type", "string"),
         "age", Map.of("type", "integer")
     ),
     "required", List.of("name", "age")
 ));

 // Create client with schema
 JsonModeClient client = JsonModeClient.builder()
     .client(baseClient)
     .responseFormat(format)
     .build();

 ChatResponse response = client.chat("Generate a person");
 // Response: {"name": "Alice", "age": 30}
Author:
TnsAI Team

  • Method Details

    • wrap

      public static JsonModeClient wrap(com.tnsai.llm.LLMClient client)
      Creates a simple JSON mode wrapper with default settings.
      Parameters:
      client - The LLM client to wrap
      Returns:
      JsonModeClient with JSON_OBJECT format

    • wrap

      public static JsonModeClient wrap(com.tnsai.llm.LLMClient client, ResponseFormat format)
      Creates a JSON mode wrapper with the specified format.
      Parameters:
      client - The LLM client to wrap
      format - The response format to use
      Returns:
      JsonModeClient with specified format

    • builder

      public static JsonModeClient.Builder builder()
      Creates a new builder.

    • getModel

      public String getModel()
      Specified by:
      getModel in interface com.tnsai.llm.LLMClient

    • getTemperature

      public float getTemperature()
      Specified by:
      getTemperature in interface com.tnsai.llm.LLMClient

    • getMaxTokens

      public Optional<Integer> getMaxTokens()
      Specified by:
      getMaxTokens in interface com.tnsai.llm.LLMClient

    • chat

      public com.tnsai.llm.ChatResponse chat(String message, Optional<String> systemPrompt, Optional<List<Map<String,Object>>> history, Optional<List<Map<String,Object>>> tools)
      Specified by:
      chat in interface com.tnsai.llm.LLMClient

    • chat

      public com.tnsai.llm.ChatResponse chat(List<com.tnsai.models.chat.ContentPart> messageParts, Optional<String> systemPrompt, Optional<List<Map<String,Object>>> history, Optional<List<Map<String,Object>>> tools)
      Specified by:
      chat in interface com.tnsai.llm.LLMClient

    • streamChat

      public Stream<String> streamChat(String message, Optional<String> systemPrompt, Optional<List<Map<String,Object>>> history, Optional<List<Map<String,Object>>> tools)
      Specified by:
      streamChat in interface com.tnsai.llm.LLMClient

    • getCapabilities

      public com.tnsai.llm.LLMCapabilities getCapabilities()
      Specified by:
      getCapabilities in interface com.tnsai.llm.LLMClient

    • chatAs

      public <T> T chatAs(Class<T> clazz, String message)
      Sends a chat message and parses the JSON response to the specified type.
      Type Parameters:
      T - The type to parse to
      Parameters:
      clazz - The class to parse the response to
      message - The user message
      Returns:
      Parsed object
      Throws:
      JsonModeClient.JsonParseException - if parsing fails

    • chatAs

      public <T> T chatAs(Class<T> clazz, String message, Optional<String> systemPrompt)
      Sends a chat message with system prompt and parses the JSON response.
      Type Parameters:
      T - The type to parse to
      Parameters:
      clazz - The class to parse the response to
      message - The user message
      systemPrompt - Optional system prompt
      Returns:
      Parsed object
      Throws:
      JsonModeClient.JsonParseException - if parsing fails

    • chatAs

      public <T> T chatAs(Class<T> clazz, String message, Optional<String> systemPrompt, Optional<List<Map<String,Object>>> history, Optional<List<Map<String,Object>>> tools)
      Sends a full chat request and parses the JSON response.
      Type Parameters:
      T - The type to parse to
      Parameters:
      clazz - The class to parse the response to
      message - The user message
      systemPrompt - Optional system prompt
      history - Optional conversation history
      tools - Optional tools
      Returns:
      Parsed object
      Throws:
      JsonModeClient.JsonParseException - if parsing fails

    • parseResponse

      public <T> T parseResponse(String json, Class<T> clazz)
      Parses a JSON response to the specified type.
      Type Parameters:
      T - The type to parse to
      Parameters:
      json - The JSON string to parse
      clazz - The class to parse to
      Returns:
      Parsed object
      Throws:
      JsonModeClient.JsonParseException - if parsing fails

    • getDelegate

      public com.tnsai.llm.LLMClient getDelegate()
      Gets the wrapped delegate client.

    • getResponseFormat

      public ResponseFormat getResponseFormat()
      Gets the response format being used.

    • supportsNativeJsonMode

      public boolean supportsNativeJsonMode()
      Checks if the underlying provider supports native JSON mode.