Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: impl duckduckgo search tool #5

Merged
merged 1 commit into from
Dec 26, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 98 additions & 0 deletions components/tool/duckduckgo/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# DuckDuckGo Search Tool

English | [简体中文](README_zh.md)

A DuckDuckGo search tool implementation for [Eino](https://github.com/cloudwego/eino) that implements the `InvokableTool` interface. This enables seamless integration with Eino's ChatModel interaction system and `ToolsNode` for enhanced search capabilities.

## Features

- Implements `github.com/cloudwego/eino/components/tool.InvokableTool`
- Easy integration with Eino's tool system
- Configurable search parameters

## Installation

```bash
go get github.com/cloudwego/eino-ext/components/tool/duckduckgo
```

## Quick Start

```go
package main

import (
"context"
"log"

"github.com/cloudwego/eino-ext/components/tool/duckduckgo"
"github.com/cloudwego/eino-ext/components/tool/duckduckgo/ddgsearch"
"github.com/cloudwego/eino/components/tool"
)

func main() {
// Create tool config
cfg := &duckduckgo.Config{ // All of these parameters are default values, for demonstration purposes only
ToolName: "duckduckgo_search",
ToolDesc: "search web for information by duckduckgo",
Region: ddgsearch.RegionWT,
Retries: 3,
Timeout: 10,
MaxResults: 10,
}

// Create the search tool
searchTool, err := duckduckgo.NewTool(context.Background(), cfg)
if err != nil {
log.Fatal(err)
}

// Use with Eino's ToolsNode
tools := []tool.BaseTool{searchTool}
// ... configure and use with ToolsNode
}
```

## Configuration

The tool can be configured using the `Config` struct:

```go
type Config struct {
ToolName string // Tool name for LLM interaction (default: "duckduckgo_search")
ToolDesc string // Tool description (default: "search web for information by duckduckgo")
Region ddgsearch.Region // Search region (default: "wt-wt" of no specified region)
Retries int // Number of retries (default: 3)
Timeout int // Max timeout in seconds (default: 10)
MaxResults int // Maximum results per search (default: 10)
Proxy string // Optional proxy URL
}
```

## Search

### Request Schema
```go
type SearchRequest struct {
Query string `json:"query" jsonschema_description:"The query to search the web for"`
Page int `json:"page" jsonschema_description:"The page number to search for, default: 1"`
}
```

### Response Schema
```go
type SearchResponse struct {
Results []SearchResult `json:"results" jsonschema_description:"The results of the search"`
}

type SearchResult struct {
Title string `json:"title" jsonschema_description:"The title of the search result"`
Description string `json:"description" jsonschema_description:"The description of the search result"`
Link string `json:"link" jsonschema_description:"The link of the search result"`
}
```

## For More Details

- [DuckDuckGo Search Library Documentation](ddgsearch/README.md)
- [Eino Documentation](https://github.com/cloudwego/eino)
98 changes: 98 additions & 0 deletions components/tool/duckduckgo/README_zh.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
# DuckDuckGo 搜索工具

[English](README.md) | 简体中文

这是一个为 [Eino](https://github.com/cloudwego/eino) 实现的 DuckDuckGo 搜索工具。该工具实现了 `InvokableTool` 接口,可以与 Eino 的 ChatModel 交互系统和 `ToolsNode` 无缝集成。

## 特性

- 实现了 `github.com/cloudwego/eino/components/tool.InvokableTool` 接口
- 易于与 Eino 工具系统集成
- 可配置的搜索参数

## 安装

```bash
go get github.com/cloudwego/eino-ext/components/tool/duckduckgo
```

## 快速开始

```go
package main

import (
"context"
"log"

"github.com/cloudwego/eino-ext/components/tool/duckduckgo"
"github.com/cloudwego/eino-ext/components/tool/duckduckgo/ddgsearch"
"github.com/cloudwego/eino/components/tool"
)

func main() {
// 创建工具配置
cfg := &duckduckgo.Config{ // 下面所有这些参数都是默认值,仅作用法展示
ToolName: "duckduckgo_search",
ToolDesc: "search web for information by duckduckgo",
Region: ddgsearch.RegionWT,
Retries: 3,
Timeout: 10,
MaxResults: 10,
}

// 创建搜索工具
searchTool, err := duckduckgo.NewTool(context.Background(), cfg)
if err != nil {
log.Fatal(err)
}

// 与 Eino 的 ToolsNode 一起使用
tools := []tool.BaseTool{searchTool}
// ... 配置并使用 ToolsNode
}
```

## 配置

工具可以通过 `Config` 结构体进行配置:

```go
type Config struct {
ToolName string // 用于 LLM 交互的工具名称(默认:"duckduckgo_search")
ToolDesc string // 工具描述(默认:"search web for information by duckduckgo")
Region ddgsearch.Region // 搜索地区(默认:"wt-wt")
Retries int // 重试次数(默认:3)
Timeout int // 最大超时时间(秒)(默认:10)
MaxResults int // 每次搜索的最大结果数(默认:10)
Proxy string // 可选的代理 URL
}
```

## Search

### 请求 Schema
```go
type SearchRequest struct {
Query string `json:"query" jsonschema_description:"要搜索的查询内容"`
Page int `json:"page" jsonschema_description:"要搜索的页码,默认:1"`
}
```

### 响应 Schema
```go
type SearchResponse struct {
Results []SearchResult `json:"results" jsonschema_description:"搜索结果列��"`
}

type SearchResult struct {
Title string `json:"title" jsonschema_description:"搜索结果的标题"`
Description string `json:"description" jsonschema_description:"搜索结果的描述"`
Link string `json:"link" jsonschema_description:"搜索结果的链接"`
}
```

## 更多详情

- [DuckDuckGo 搜索库文档](ddgsearch/README_zh.md)
- [Eino 文档](https://github.com/cloudwego/eino)
149 changes: 149 additions & 0 deletions components/tool/duckduckgo/ddgsearch/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,149 @@
# DDGSearch

English | [简体中文](README_zh.md)

A native Go library for DuckDuckGo search functionality. This library provides a simple and efficient way to perform searches using DuckDuckGo's search engine.

## Why DuckDuckGo?

DuckDuckGo offers several advantages:
- **No Authentication Required**: Unlike other search engines, DuckDuckGo's API can be used without any API keys or authentication
- Privacy-focused search results
- No rate limiting for reasonable usage
- Support for multiple regions and languages
- Clean and relevant search results

## Features

- Clean and idiomatic Go implementation
- Comprehensive error handling
- Configurable search parameters
- In-memory caching with TTL
- Support for:
- Multiple regions (us-en, uk-en, de-de, etc.)
- Safe search levels (strict, moderate, off)
- Time-based filtering (day, week, month, year)
- Result pagination
- Custom HTTP headers
- Proxy configuration

## Installation

```bash
go get github.com/cloudwego/eino-ext/components/tool/duckduckgo
```

## Quick Start

```go
package main

import (
"context"
"fmt"
"log"
"time"

"github.com/cloudwego/eino-ext/components/tool/duckduckgo/ddgsearch"
)

func main() {
// Create a new client with configuration
cfg := &ddgsearch.Config{
Timeout: 30 * time.Second,
MaxRetries: 3,
Cache: true,
}
client, err := ddgsearch.New(cfg)
if err != nil {
log.Fatal(err)
}

// Configure search parameters
params := &ddgsearch.SearchParams{
Query: "what is golang",
Region: ddgsearch.RegionUSEN,
SafeSearch: ddgsearch.SafeSearchModerate,
TimeRange: ddgsearch.TimeRangeMonth,
MaxResults: 10,
}

// Perform search
response, err := client.Search(context.Background(), params)
if err != nil {
log.Fatal(err)
}

// Print results
for i, result := range response.Results {
fmt.Printf("%d. %s\n URL: %s\n Description: %s\n\n",
i+1, result.Title, result.URL, result.Description)
}
}
```

## Advanced Usage

### Configuration

```go
// Create client with custom configuration
cfg := &ddgsearch.Config{
Timeout: 20 * time.Second,
MaxRetries: 3,
Proxy: "http://proxy:8080",
Cache: true,
Headers: map[string]string{
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
},
}
client, err := ddgsearch.New(cfg)
```

### Search Parameters

```go
params := &ddgsearch.SearchParams{
Query: "golang tutorial", // Search query
Region: ddgsearch.RegionUS, // Region for results (us-en, uk-en, etc.)
SafeSearch: ddgsearch.SafeSearchModerate, // Safe search level
TimeRange: ddgsearch.TimeRangeWeek, // Time filter
MaxResults: 10, // Maximum results to return
}
```

Available regions:
- RegionUS (United States)
- RegionUK (United Kingdom)
- RegionDE (Germany)
- RegionFR (France)
- RegionJP (Japan)
- RegionCN (China)
- RegionRU (Russia)

Safe search levels:
- SafeSearchStrict
- SafeSearchModerate
- SafeSearchOff

Time range options:
- TimeRangeDay
- TimeRangeWeek
- TimeRangeMonth
- TimeRangeYear

### Proxy Support

```go
// HTTP proxy
cfg := &ddgsearch.Config{
Proxy: "http://proxy:8080",
}
client, err := ddgsearch.New(cfg)

// SOCKS5 proxy
cfg := &ddgsearch.Config{
Proxy: "socks5://proxy:1080",
}
client, err := ddgsearch.New(cfg)
```
Loading
Loading