JSON mode

README.md

@@ -43,6 +43,19 @@ include Groq::Helpers
 # => {"role"=>"assistant", "content"=>"Cat"}
 ```
 
+JSON mode:
+
+```ruby
+response = @client.chat([
+  S("Reply with JSON. Use {\"number\": 7} for the answer."),
+  U("What's 3+4?")
+], json: true)
+# => {"role"=>"assistant", "content"=>"{\"number\": 7}"}
+
+JSON.parse(response["content"])
+# => {"number"=>7}
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -190,6 +203,28 @@ Assistant reply with model gemma-7b-it:
 {"role"=>"assistant", "content"=>"Hello to you too! 👋🌎 It's great to hear from you. What would you like to talk about today? 😊"}
 ```
 
+### JSON mode
+
+JSON mode is a beta feature that guarantees all chat completions are valid JSON.
+
+To use JSON mode:
+
+1. Pass `json: true` to the `chat()` call
+2. Provide a system message that contains `JSON` in the content, e.g. `S("Reply with JSON")`
+
+A good idea is to provide an example JSON schema in the system message that you'd prefer to receive.
+
+```ruby
+response = @client.chat([
+  S("Reply with JSON. Use {\"number\": 7} for the answer."),
+  U("What's 3+4?")
+], json: true)
+# => {"role"=>"assistant", "content"=>"{\"number\": 7}"}
+
+JSON.parse(response["content"])
+# => {"number"=>7}
+```
+
 ### Tools/Functions
 
 LLMs are increasingly supporting deferring to tools or functions to fetch data, perform calculations, or store structured data. Groq Cloud in turn then supports their tool implementations through its API.

lib/groq/client.rb

@@ -22,7 +22,7 @@ def initialize(config = {}, &faraday_middleware)
   end
 
   # TODO: support stream: true; or &stream block
-  def chat(messages, model_id: nil, tools: nil, max_tokens: nil, temperature: nil)
+  def chat(messages, model_id: nil, tools: nil, max_tokens: nil, temperature: nil, json: false)
     unless messages.is_a?(Array) || messages.is_a?(String)
       raise ArgumentError, "require messages to be an Array or String"
     end
@@ -38,7 +38,8 @@ def chat(messages, model_id: nil, tools: nil, max_tokens: nil, temperature: nil)
       messages: messages,
       tools: tools,
       max_tokens: max_tokens || @max_tokens,
-      temperature: temperature || @temperature
+      temperature: temperature || @temperature,
+      response_format: json ? {type: "json_object"} : nil
     }.compact
     response = post(path: "/openai/v1/chat/completions", body: body)
     if response.status == 200

test/groq/test_client.rb

@@ -74,6 +74,17 @@ def test_chat_messages_with_U_A_helpers
     end
   end
 
+  def test_json_mode
+    VCR.use_cassette("llama3-8b-8192/chat_json_mode") do
+      client = Groq::Client.new(model_id: "llama3-8b-8192")
+      response = client.chat([
+        S("Reply with JSON. Use {\"number\": 7} for the answer."),
+        U("What's 3+4?")
+      ], json: true)
+      assert_equal response, {"role" => "assistant", "content" => "{\"number\": 7}"}
+    end
+  end
+
   def test_tools_weather_report
     VCR.use_cassette("mixtral-8x7b-32768/chat_tools_weather_report") do
       client = Groq::Client.new(model_id: "mixtral-8x7b-32768")