Merge pull request #52 from deepseek-php/feat-support-response-format-option

feat / support response format option

Author: omaralalwi

README-AR.md

@@ -22,14 +22,13 @@
 
 [الإنجليزية](README.md) | [الصينية](README-CN.md)
 
-</p>
-
 ## فهرس المحتويات
 - [✨ المميزات](#-المميزات)
 - [📦 التثبيت](#-التثبيت)
 - [🚀 البداية السريعة](#-البداية-السريعة)
   - [الاستخدام الأساسي](#الاستخدام-الأساسي)
   - [التكوين المتقدم](#التكوين-المتقدم)
+  - [تحذير هام عند استخدام وضع JSON](#-متطلب-وضع-json-في-deepseek)
   - [الاستخدام مع عميل HTTP من Symfony](#الاستخدام-مع-عميل-http-من-symfony)
   - [الحصول على قائمة النماذج](#الحصول-على-قائمة-النماذج)
   - [استدعاء الدوال](#استدعاء-الدوال)
@@ -101,12 +100,48 @@ $response = $client
     ->withStream()
     ->withTemperature(1.2)
     ->setMaxTokens(8192)
+    ->setResponseFormat('text')
     ->query('Explain quantum computing in simple terms')
     ->run();
 
 echo 'API Response:'.$response;
 ```
 
+
+## ⚠️ متطلب وضع JSON في DeepSeek
+
+عند استخدام:
+
+```php
+->setResponseFormat('json_object')
+```
+
+يجب أن يحتوي الـ برومبت على **كلمة "json"** بشكل واضح.
+
+وإلا سيتم رفض الطلب من قبل  وترجع رسالة الخطأ التالية:
+
+> `"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'"`
+
+---
+
+### 🚫 استخدام غير صحيح
+
+```php
+->setResponseFormat('json_object')
+->query('اشرح الحوسبة الكمومية بطريقة مبسطة')
+```
+
+### ✅ استخدام صحيح
+
+```php
+->setResponseFormat('json_object')
+->query('أجب بصيغة JSON صحيحة. اشرح الحوسبة الكمومية بطريقة مبسطة.')
+```
+
+> ✅ **نصيحة**: للحصول على أفضل النتائج، قم أيضًا بإعطاء مثال على صيغة JSON في الرسالة.
+
+---
+
 ### الاستخدام مع عميل HTTP من Symfony
 الحزمة مبنية مسبقاً مع `symfony Http client`، فإذا كنت بحاجة إلى استخدامها مع عميل HTTP الخاص بـ Symfony، فيمكن تحقيق ذلك بسهولة عن طريق تمرير `clientType:'symfony'` إلى دالة `build`.
 

README-CN.md

@@ -22,14 +22,13 @@
 
 [EN](README.md) | [AR](README-AR.md)
 
-</p>
-
 ## 目录
 - [✨ 特性](#-特性)
 - [📦 安装](#-安装)
 - [🚀 快速入门](#-快速入门)
   - [基本用法](#基本用法)
   - [高级配置](#高级配置)
+  - [使用 JSON 模式的重要警告](#-deepseek-json-模式使用要求)
   - [使用 Symfony HttpClient](#使用-symfony-httpclient)
   - [获取模型列表](#获取模型列表)
   - [函数调用](#函数调用)
@@ -100,12 +99,47 @@ $response = $client
     ->withStream()
     ->withTemperature(1.2)
     ->setMaxTokens(8192)
+    ->setResponseFormat('text')
     ->query('Explain quantum computing in simple terms')
     ->run();
 
 echo 'API Response:'.$response;
 ```
 
+
+## ⚠️ DeepSeek JSON 模式使用要求
+
+当使用：
+
+```php
+->setResponseFormat('json_object')
+```
+
+你的提示语（prompt）**必须包含 "json" 这个词**，否则 API 会返回以下错误：
+
+> `"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'"`
+
+---
+
+### 🚫 错误示例
+
+```php
+->setResponseFormat('json_object')
+->query('用简单的语言解释量子计算')
+```
+
+### ✅ 正确示例
+
+```php
+->setResponseFormat('json_object')
+->query('请以有效的 JSON 格式回答，并用简单语言解释量子计算。')
+```
+
+> ✅ **建议**：为了获得更好的结果，最好也在提示中提供一个 JSON 示例，并强调 “只返回 JSON”。
+
+
+---
+
 ### Use with Symfony HttpClient
 the package already built with `symfony Http client`,  if you need to use package with `symfony` Http Client , it is easy to achieve that, just pass `clientType:'symfony'` with `build` function.
 

README.md

@@ -18,17 +18,17 @@
     <a href="https://github.com/deepseek-php/deepseek-php-client/stargazers">
       <img src="https://img.shields.io/github/stars/deepseek-php/deepseek-php-client?style=social" alt="GitHub Stars">
     </a>
-  
-[AR](README-AR.md) | [CN](README-CN.md)
+  </p>
 
-</p>
+[AR](README-AR.md) | [CN](README-CN.md)
 
 ## Table of Contents
 - [✨ Features](#-features)
 - [📦 Installation](#-installation)
 - [🚀 Quick Start](#-quick-start)
   - [Basic Usage](#basic-usage)
   - [Advanced Configuration](#advanced-configuration)
+  - [important warning with json mode](#-deepseek-json-mode-requirement)
   - [Use with Symfony HttpClient](#use-with-symfony-httpclient)
   - [Get Models List](#get-models-list)
   - [Function Calling](#function-calling)
@@ -100,12 +100,47 @@ $response = $client
     ->withStream()
     ->setTemperature(1.2)
     ->setMaxTokens(8192)
+    ->setResponseFormat('text') // or "json_object"  with careful .
     ->query('Explain quantum computing in simple terms')
     ->run();
 
 echo 'API Response:'.$response;
 ```
 
+## ⚠️ DeepSeek JSON Mode Requirement
+
+When using:
+
+```php
+->setResponseFormat('json_object')
+```
+
+Your prompt **must contain the word `"json"`** in some form. Otherwise, the API will reject the request with the following error:
+
+> `"Prompt must contain the word 'json' in some form to use 'response_format' of type 'json_object'"`
+
+---
+
+### 🚫 Incorrect Usage
+
+```php
+->setResponseFormat('json_object')
+->query('Explain quantum computing in simple terms')
+```
+
+### ✅ Correct Usage
+
+```php
+->setResponseFormat('json_object')
+->query('Respond in valid JSON format. Explain quantum computing in simple terms.')
+```
+
+> ✅ **Tip**: For best results, also provide a JSON example or explicitly say:
+> *"Respond only in valid JSON."*
+
+
+---
+
 ### Use with Symfony HttpClient
 the package already built with `symfony Http client`,  if you need to use package with `symfony` Http Client , it is easy to achieve that, just pass `clientType:'symfony'` with `build` function.
 

composer.json

@@ -49,7 +49,7 @@
             "role": "creator"
         }
     ],
-    "version": "2.0.5",
+    "version": "2.0.6",
     "require": {
         "php": "^8.1.0",
         "nyholm/psr7": "^1.8",

src/DeepSeekClient.php

@@ -50,6 +50,7 @@ class DeepSeekClient implements ClientContract
 
     protected float $temperature;
     protected int $maxTokens;
+    protected string $responseFormatType;
 
     /**
      * response result contract
@@ -81,6 +82,7 @@ public function __construct(ClientInterface $httpClient)
         $this->endpointSuffixes = EndpointSuffixes::CHAT->value;
         $this->temperature = (float) TemperatureValues::GENERAL_CONVERSATION->value;
         $this->maxTokens = (int) TemperatureValues::MAX_TOKENS->value;
+        $this->responseFormatType = TemperatureValues::RESPONSE_FORMAT_TYPE->value;
         $this->tools = null;
     }
 
@@ -93,6 +95,9 @@ public function run(): string
             QueryFlags::TEMPERATURE->value   => $this->temperature,
             QueryFlags::MAX_TOKENS->value   => $this->maxTokens,
             QueryFlags::TOOLS->value  => $this->tools,
+            QueryFlags::RESPONSE_FORMAT->value  => [
+                'type' => $this->responseFormatType
+            ],
         ];
 
         $this->setResult((new Resource($this->httpClient, $this->endpointSuffixes))->sendRequest($requestData, $this->requestMethod));
@@ -192,6 +197,12 @@ public function setMaxTokens(int $maxTokens): self
         return $this;
     }
 
+    public function setResponseFormat(string $type): self
+    {
+        $this->responseFormatType = $type;
+        return $this;
+    }
+
     public function buildQuery(string $content, ?string $role = null): array
     {
         return [

src/Enums/Configs/TemperatureValues.php

@@ -13,4 +13,5 @@ enum TemperatureValues: string
     case CREATIVE_WRITING = "1.5";
     case POETRY = "1.6";
     case MAX_TOKENS = "4096";
+    case RESPONSE_FORMAT_TYPE = "text";
 }

src/Enums/Requests/QueryFlags.php

@@ -10,4 +10,5 @@ enum QueryFlags: string
     case TEMPERATURE = 'temperature';
     case MAX_TOKENS = 'max_tokens';
     case TOOLS = 'tools';
+    case RESPONSE_FORMAT = 'response_format';
 }