feat: llm friendly style response

Author: kentzhu

README.md

@@ -23,6 +23,8 @@ Based on Playwright and DuckDuckGo's search engine, it encapsulates to provide s
 
 Simple, lightweight, reliable, Docker deployable, easy to maintain.
 
+Large Language Model (LLM) Friendly. Support Plain Text Response.
+
 ## Status
 
 > Experimentally under development and not recommended for use in production environments.
@@ -47,13 +49,14 @@ docker run -d -p 8080:8080 --restart=unless-stopped --name lessapi-duckduckgo le
 
 - keyword: Search keyword (required)
 - region: Region (optional) such as en-US, fr-FR, zh-CN, ru-RU, etc. Default is en-US
-- maxCount: Maximum number of results returned (optional) Default is 20
-- viaProxyUrl: The address of the proxy used by the browser (optional) e.g., http://proxy.server:3000 Default is empty
+- maxCount: Maximum number of results returned. (optional) Default is 20
+- viaProxyUrl: The address of the proxy used by the browser. e.g., http://proxy.server:3000 (optional) Default is empty
+- llmStyle: Whether to use Large Language Model (LLM) Friendly style response. e.g. 1, 0 (optional) Default is 0
 
 **Request Example:**
 
 ```shell
-curl 'http://127.0.0.1:8080/search/text?keyword=USA&maxCount=10'
+curl 'http://127.0.0.1:8080/search/text?keyword=lessapi&maxCount=10'
 ```
 
 ```shell

docs/zhs/README.md

@@ -26,6 +26,8 @@ LessAPI-DuckDuckGo 是一个搜索引擎API服务。
 
 简单、轻量、可靠、Docker部署、易于维护。
 
+大型语言模型(LLM)友好。支持纯文本响应。
+
 ## 状态
 
 > 实验性地开发中，不建议在生产环境中使用。
@@ -52,11 +54,16 @@ docker run -d -p 8080:8080 --restart=unless-stopped --name lessapi-duckduckgo le
 - region: 地区(选填)  en-US, fr-FR, zh-CN, ru-RU, 等 默认值 en-US
 - maxCount: 最大返回数量(选填)  默认值 20
 - viaProxyUrl: 浏览器使用代理的地址(选填) 如 http://proxy.server:3000  默认值 空
+- llmStyle: 是否使用大型语言模型(LLM)友好风格响应(选填)  1, 0 默认值 0
 
 **请求示例:**
 
 ```shell
-curl 'http://127.0.0.1:8080/search/text?keyword=hello&maxCount=2'
+curl 'http://127.0.0.1:8080/search/text?keyword=lessapi&maxCount=10'
+```
+
+```shell
+curl 'http://127.0.0.1:8080/search/text?keyword=lessapi&maxCount=99&viaProxyUrl=http://proxy.server:3000'
 ```
 
 **响应示例:**

docs/zht/README.md

@@ -27,10 +27,20 @@ LessAPI-DuckDuckGo 是一個搜索引擎API服務。
 
 簡單、輕量、可靠、Docker部署、易於維護。
 
+大型語言模型(LLM)友好。支持純文本響應。
+
 ## 狀態
 
 > 專案正在實驗性地開發中，不建議在生產環境中使用。
 
+## 部署
+
+使用Docker只需要一個命令即可將服務部署到8080端口。
+
+```shell
+docker run -d -p 8080:8080 --restart=unless-stopped --name lessapi-duckduckgo lessapi/lessapi-duckduckgo:v0.0.2
+```
+
 ## 使用
 
 ### OpenAPI標準文檔 (Swagger 3.0)
@@ -45,11 +55,16 @@ LessAPI-DuckDuckGo 是一個搜索引擎API服務。
 - region: 地區(選填)  en-US, fr-FR, zh-CN, ru-RU, 等 預設值 en-US
 - maxCount: 最大返回數量(選填)  預設值 20
 - viaProxyUrl: 瀏覽器使用代理的地址(選填) 如 http://proxy.server:3000  預設值 空
+- llmStyle: 是否使用大型語言模型(LLM)友好風格響應(選填)  1, 0 預設值 0
 
 **請求示例:**
 
 ```shell
-curl 'http://127.0.0.1:8080/search/text?keyword=hello&maxCount=2'
+curl 'http://127.0.0.1:8080/search/text?keyword=lessapi&maxCount=10'
+```
+
+```shell
+curl 'http://127.0.0.1:8080/search/text?keyword=lessapi&maxCount=99&viaProxyUrl=http://proxy.server:3000'
 ```
 
 **響應示例:**

internal/handles/index_handle.go

@@ -8,10 +8,20 @@ import (
 )
 
 func IndexHandle(c *gin.Context) {
-	resp := gin.H{
-		"server":  lessapi_duckduckgo.ServerName,
-		"github":  lessapi_duckduckgo.ProjectGithub,
-		"version": lessapi_duckduckgo.Version,
+	resp := IndexResponse{
+		Server:  lessapi_duckduckgo.ServerName,
+		Github:  lessapi_duckduckgo.ProjectGithub,
+		Version: lessapi_duckduckgo.Version,
 	}
-	c.JSON(200, utils.BuildApiSuccessData(resp))
+	utils.SendResponse(c, utils.BuildApiSuccessData(resp))
+}
+
+type IndexResponse struct {
+	Server  string `json:"server"`
+	Github  string `json:"github"`
+	Version string `json:"version"`
+}
+
+func (i IndexResponse) ToLLMStyle() string {
+	return "Server: " + i.Server + "\nGithub: " + i.Github + "\nVersion: " + i.Version
 }

internal/handles/list_language_handle.go

@@ -18,23 +18,24 @@ func ListLanguageHandle(c *gin.Context) {
 	// parse request params
 	var payload types.ListLanguagePayload
 	if err := c.ShouldBindQuery(&payload); err != nil {
-		c.JSON(200, utils.BuildApiError("invalid_params", "invalid request params"))
+		utils.SendResponse(c, utils.BuildApiError("invalid_params", "invalid request params"))
 		return
 	}
 
 	// get from cache
 	languages, found := languagesCache.Get("languages")
 	if found {
-		c.JSON(200, utils.BuildApiSuccessData(types.ListLanguageResponse{
+		resp := types.ListLanguageResponse{
 			Languages: languages.([]types.LanguageType),
-		}))
+		}
+		utils.SendResponse(c, utils.BuildApiSuccessData(resp))
 		return
 	}
 
 	// search text
 	resp, err := searchs.ListLanguage(payload)
 	if err != nil {
-		c.JSON(200, utils.BuildApiError("search_error", err.Error()))
+		utils.SendResponse(c, utils.BuildApiError("fetch_error", err.Error()))
 		return
 	}
 
@@ -43,5 +44,5 @@ func ListLanguageHandle(c *gin.Context) {
 	}
 
 	// return response
-	c.JSON(200, utils.BuildApiSuccessData(resp))
+	utils.SendResponse(c, utils.BuildApiSuccessData(resp))
 }

internal/handles/text_handle.go

@@ -1,29 +1,29 @@
 package handles
 
 import (
-	"github.com/gin-gonic/gin"
-
 	"github.com/lessapidev/lessapi-duckduckgo/internal/searchs"
 	"github.com/lessapidev/lessapi-duckduckgo/internal/types"
 	"github.com/lessapidev/lessapi-duckduckgo/internal/utils"
+
+	"github.com/gin-gonic/gin"
 )
 
 // SearchTextHandle search text
 func SearchTextHandle(c *gin.Context) {
 	// parse request params
 	var payload types.SearchTextPayload
 	if err := c.ShouldBindQuery(&payload); err != nil {
-		c.JSON(200, utils.BuildApiError("invalid_params", "invalid request params"))
+		utils.SendResponse(c, utils.BuildApiError("invalid_params", "invalid request params"))
 		return
 	}
 
 	// search text
 	resp, err := searchs.SearchText(payload)
 	if err != nil {
-		c.JSON(200, utils.BuildApiError("search_error", err.Error()))
+		utils.SendResponse(c, utils.BuildApiError("search_error", err.Error()))
 		return
 	}
 
 	// return response
-	c.JSON(200, utils.BuildApiSuccessData(resp))
+	utils.SendResponse(c, utils.BuildApiSuccessData(resp))
 }

internal/types/responses.go

@@ -0,0 +1,59 @@
+package types
+
+import "fmt"
+
+type SearchTextPayload struct {
+	// Keywords to search (required)
+	Keyword string `json:"keyword" form:"keyword" validate:"required"`
+	// Region to search (optional) (default "en-US")
+	Region string `json:"region" form:"region"`
+	// Time limit to search (optional) ( "" default all , "d" past day, "w" past week, "m" past month, "y" past year)
+	TimeLimit string `json:"timeLimit" form:"timeLimit"`
+	// Max count of search results (optional) (default 20)
+	MaxCount int `json:"maxCount" form:"maxCount"`
+	// Proxy url to use (optional)
+	ViaProxyUrl string `json:"viaProxyUrl" form:"viaProxyUrl"`
+}
+
+type SearchTextResponse struct {
+	Results []SearchTextResultItem `json:"results"`
+}
+
+func (s SearchTextResponse) ToLLMStyle() string {
+	var resultStr string
+	for i, item := range s.Results {
+		resultStr += fmt.Sprintf("# %d. %s\nURL:%s\nAbstract:%s\n\n", i+1, item.Title, item.Url, item.Description)
+	}
+	return resultStr
+}
+
+type SearchTextResultItem struct {
+	Order       int    `json:"order"`       // order of the result
+	Title       string `json:"title"`       // title of the result
+	Url         string `json:"url"`         // url of the result
+	Description string `json:"description"` // description of the result
+}
+
+// -----------------------------------------------------------
+
+type LanguageType struct {
+	Code string `json:"code"`
+	Name string `json:"name"`
+}
+
+type ListLanguagePayload struct {
+	// Proxy url to use (optional)
+	ViaProxyUrl string `json:"viaProxyUrl" form:"viaProxyUrl"`
+}
+
+type ListLanguageResponse struct {
+	Languages []LanguageType `json:"languages"`
+}
+
+func (l ListLanguageResponse) ToLLMStyle() string {
+	var resultStr string
+	for _, item := range l.Languages {
+		resultStr += fmt.Sprintf("%s (%s)\n", item.Name, item.Code)
+	}
+	return resultStr
+}

internal/types/types.go

@@ -1,45 +1,17 @@
 package types
 
-type ApiResponse[T any] struct {
-	Code    string  `json:"code"`
-	Message *string `json:"message,omitempty"`
-	Data    T       `json:"data,omitempty"`
+type IResponse interface {
+	ToLLMStyle() string
 }
 
-type SearchTextPayload struct {
-	// Keywords to search (required)
-	Keyword string `json:"keyword" form:"keyword" validate:"required"`
-	// Region to search (optional) (default "en-US")
-	Region string `json:"region" form:"region"`
-	// Time limit to search (optional) ( "" default all , "d" past day, "w" past week, "m" past month, "y" past year)
-	TimeLimit string `json:"timeLimit" form:"timeLimit"`
-	// Max count of search results (optional) (default 20)
-	MaxCount int `json:"maxCount" form:"maxCount"`
-	// Proxy url to use (optional)
-	ViaProxyUrl string `json:"viaProxyUrl" form:"viaProxyUrl"`
+type ApiResponse struct {
+	Code    string    `json:"code"`
+	Message *string   `json:"message,omitempty"`
+	Data    IResponse `json:"data,omitempty"`
 }
 
-type SearchTextResponse struct {
-	Results []SearchTextResultItem `json:"results"`
-}
-
-type SearchTextResultItem struct {
-	Order       int    `json:"order"`       // order of the result
-	Title       string `json:"title"`       // title of the result
-	Url         string `json:"url"`         // url of the result
-	Description string `json:"description"` // description of the result
-}
-
-type LanguageType struct {
-	Code string `json:"code"`
-	Name string `json:"name"`
-}
-
-type ListLanguagePayload struct {
-	// Proxy url to use (optional)
-	ViaProxyUrl string `json:"viaProxyUrl" form:"viaProxyUrl"`
-}
+type EmptyResponse struct{}
 
-type ListLanguageResponse struct {
-	Languages []LanguageType `json:"languages"`
+func (e EmptyResponse) ToLLMStyle() string {
+	return "success"
 }

internal/utils/api_util.go

@@ -1,8 +1,9 @@
 package utils
 
 import (
-	"github.com/lessapidev/lessapi-duckduckgo/internal/envs"
 	"os"
+
+	"github.com/lessapidev/lessapi-duckduckgo/internal/envs"
 )
 
 // GetEnvOrDefault returns the value of the environment variable with the given key.