llm4s-core
API
Generated with
llm4s-core/org.llm4s/org.llm4s.toolapi/org.llm4s.toolapi.builtin/org.llm4s.toolapi.builtin.search

org.llm4s.toolapi.builtin.search

package org.llm4s.toolapi.builtin.search

Search tools for web searches and lookups.

These tools provide web search capabilities using various search engines. All search tools follow the "config at the edge" pattern where configuration is loaded at the application boundary via org.llm4s.config.Llm4sConfig and passed to the tool's create() method.

== Available Tools ==

  • DuckDuckGoSearchTool: Search using DuckDuckGo Instant Answer API

  • Best for definitions, facts, quick lookups

  • No API key required

  • Returns abstracts, related topics, and infobox data

  • Configuration: API URL

  • BraveSearchTool: Search using Brave Search API

  • Comprehensive web search results

  • Requires API key (paid service)

  • Returns web pages, snippets, and metadata

  • Configuration: API key, URL, result count, safe search settings

  • ExaSearchTool: Search using Exa (formerly Metaphor) API

  • AI-powered semantic search engine

  • Requires API key (paid service)

  • Supports multiple search types: auto, neural, fast, deep

  • Returns rich content with text, highlights, summaries, and metadata

  • Configuration: API key, URL, result count, search type, max characters, max age

== Usage Pattern ==

All search tools follow the Result-based error handling pattern. Use for-comprehensions to chain operations and handle errors gracefully:

Attributes

Example 
import org.llm4s.config.Llm4sConfig
import org.llm4s.toolapi.builtin.search._
import org.llm4s.toolapi.ToolRegistry
import org.llm4s.types.Result
// Load and create all search tools using Result
val toolsResult: Result[ToolRegistry] = for {
 // Load DuckDuckGo configuration and create tool
 duckDuckGoConfig <- Llm4sConfig.loadDuckDuckGoSearchTool()
 duckDuckGoTool   <- DuckDuckGoSearchTool.create(duckDuckGoConfig)
 // Load Brave Search configuration and create tool
 braveConfig <- Llm4sConfig.loadBraveSearchTool()
 braveTool   <- BraveSearchTool.create(braveConfig)
 // Load Exa Search configuration and create tool
 exaConfig <- Llm4sConfig.loadExaSearchTool()
 exaTool   <- ExaSearchTool.create(exaConfig)
 // Register all tools
 tools = new ToolRegistry(Seq(duckDuckGoTool, braveTool, exaTool))
} yield tools
// Handle the result
toolsResult match {
 case Right(tools) =>
   // Use tools with agent
   println(s"Successfully loaded $${tools.tools.size} search tools")
 case Left(error) =>
   // Handle configuration or validation errors
   println(s"Failed to load search tools: $${error.message}")
}

== Individual Tool Usage == You can also load and use tools individually:

import org.llm4s.toolapi.builtin.search.ExaSearchTool
// Load just Exa Search
val exaToolResult = for {
 config <- Llm4sConfig.loadExaSearchTool()
 tool   <- ExaSearchTool.create(config)
} yield tool
exaToolResult match {
 case Right(tool) => // Use tool
 case Left(error) => // Handle error
}

== Configuration == Configure search tools in your application.conf:

llm4s {
 tools {
   duckduckgo {
     apiUrl = "https://api.duckduckgo.com"
   }
   brave {
     apiKey = "your-api-key"
     apiUrl = "https://api.search.brave.com/res/v1"
     count = 10
     safeSearch = "moderate"
   }
   exa {
     apiKey = "your-exa-api-key"
     apiUrl = "https://api.exa.ai"
     numResults = 10
     searchType = "auto"        # Options: auto, neural, fast, deep
     maxCharacters = 500
   }
 }
}

Members list

Type members

Classlikes

case class BraveImageResult(title: String, url: String, thumbnail: String)

A single image result from the Brave Image Search API.

A single image result from the Brave Image Search API.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveImageResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class BraveImageSearchResult(query: String, results: List[BraveImageResult])

Image search result container returned by BraveSearchCategory.Image.

Image search result container returned by BraveSearchCategory.Image.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveImageSearchResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class BraveNewsResult(title: String, url: String, description: String)

A single news article result from the Brave News Search API.

A single news article result from the Brave News Search API.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveNewsResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class BraveNewsSearchResult(query: String, results: List[BraveNewsResult])

News search result container returned by BraveSearchCategory.News.

News search result container returned by BraveSearchCategory.News.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveNewsSearchResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait BraveSearchCategory[R]

Type-class describing a Brave Search category (Web, Image, Video, News).

Type-class describing a Brave Search category (Web, Image, Video, News).

Each case object encodes the API endpoint, the tool name exposed to the LLM, a human-readable description, result parsing logic, and how to map a SafeSearch level to the string the Brave API expects.

Type parameters

R

The Scala type that represents a search result for this category

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Image
object News
object Video
object Web
object BraveSearchCategory

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
case class BraveSearchConfig(timeoutMs: Int, count: Int, safeSearch: SafeSearch, extraParams: Map[String, Value])

Runtime configuration for Brave Search API requests.

Runtime configuration for Brave Search API requests.

Value parameters

count

Number of results to return per request

extraParams

Additional key-value parameters merged into every request

safeSearch

Safe-search filtering level (default: SafeSearch.Strict)

timeoutMs

HTTP request timeout in milliseconds

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveSearchTool

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
case class BraveVideoResult(title: String, url: String, description: String)

A single video result from the Brave Video Search API.

A single video result from the Brave Video Search API.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveVideoResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class BraveVideoSearchResult(query: String, results: List[BraveVideoResult])

Video search result container returned by BraveSearchCategory.Video.

Video search result container returned by BraveSearchCategory.Video.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveVideoSearchResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class BraveWebResult(title: String, url: String, description: String)

A single organic web result from the Brave Web Search API.

A single organic web result from the Brave Web Search API.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveWebResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
case class BraveWebSearchResult(query: String, results: List[BraveWebResult])

Web search result container returned by BraveSearchCategory.Web.

Web search result container returned by BraveSearchCategory.Web.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object BraveWebSearchResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait Category

Content category filter for the Exa Search API.

Content category filter for the Exa Search API.

Restricts search results to pages belonging to a specific vertical. Use with ExaSearchConfig.category to narrow the result set.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Company
object Github
object News
object Pdf
object PersonalSite
object ResearchPaper
object Tweet
Show all
object Category

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
Category.type
case class DuckDuckGoSearchConfig(timeoutMs: Int, maxResults: Int, safeSearch: Boolean)

Configuration for DuckDuckGo search tool.

Configuration for DuckDuckGo search tool.

Value parameters

maxResults

Maximum number of related topics to return.

safeSearch

Whether to enable safe search.

timeoutMs

Request timeout in milliseconds.

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class DuckDuckGoSearchResult(query: String, abstract_: String, abstractSource: String, abstractUrl: String, answer: String, answerType: String, relatedTopics: Seq[RelatedTopic])

DuckDuckGo search result.

DuckDuckGo search result.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object DuckDuckGoSearchResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object DuckDuckGoSearchTool

Tool for web searching using DuckDuckGo's Instant Answer API.

Tool for web searching using DuckDuckGo's Instant Answer API.

This tool provides quick answers and definitions without requiring an API key. It's best suited for factual queries, definitions, and quick lookups.

Note: This uses DuckDuckGo's free Instant Answer API which provides:

  • Definitions from Wikipedia
  • Quick facts
  • Related topics
  • Disambiguation pages

It does NOT provide full web search results (that would require a paid API).

Architecture: This tool follows the "config at the edge" pattern:

  1. Configuration is loaded at the application boundary via Llm4sConfig.loadDuckDuckGoSearchTool()
  2. The loaded DuckDuckGoSearchToolConfig is passed to create() method
  3. The tool operates with the provided configuration

This keeps the tool implementation pure and testable without direct config dependencies.

Attributes

Example 
import org.llm4s.config.Llm4sConfig
import org.llm4s.toolapi.builtin.search._
// Load configuration at the application edge
val toolConfigResult = Llm4sConfig.loadDuckDuckGoSearchTool()
toolConfigResult match {
 case Right(toolConfig) =>
   // Create the tool with loaded configuration
   val searchTool = DuckDuckGoSearchTool.create(toolConfig)
   val tools = new ToolRegistry(Seq(searchTool))
   agent.run("What is Scala programming language?", tools)
 case Left(error) =>
   println(s"Failed to load DuckDuckGo config: $$error")
}

For testing, you can create a config directly:

import org.llm4s.config.DuckDuckGoSearchToolConfig
val testConfig = DuckDuckGoSearchToolConfig(apiUrl = "https://api.duckduckgo.com")
val searchTool = DuckDuckGoSearchTool.create(testConfig)
Supertypes
class Object
trait Matchable
class Any
Self type
case class ExaResult(title: String, url: String, id: Option[String], publishedDate: Option[String], author: Option[String], text: Option[String], highlights: Option[List[String]], highlightScores: Option[List[Double]], summary: Option[String], favicon: Option[String], image: Option[String], subPages: Option[List[ExaResult]])

A single result returned by the Exa Search API.

A single result returned by the Exa Search API.

Value parameters

author

Author name, if available

favicon

URL of the site's favicon

highlightScores

Relevance scores for each highlight

highlights

Relevant text snippets highlighted by Exa

id

Exa's internal document identifier

image

URL of the page's representative image

publishedDate

ISO-8601 date string of the page's publication date

subPages

Nested sub-page results for deep crawl searches

summary

AI-generated summary of the page, if requested

text

Extracted page text (truncated to maxCharacters)

title

Page title

url

Page URL

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ExaResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
ExaResult.type
case class ExaSearchConfig(timeoutMs: Int, numResults: Int, searchType: SearchType, maxCharacters: Int, maxAgeHours: Int, category: Option[Category], additionalQueries: Option[List[String]], userLocation: Option[String], livecrawlTimeout: Option[Int], extraParams: Map[String, Value])

Runtime configuration for Exa Search requests. Allows overriding defaults and providing advanced parameters via extraParams.

Runtime configuration for Exa Search requests. Allows overriding defaults and providing advanced parameters via extraParams.

Value parameters

additionalQueries

Additional queries for deep search (optional, default None)

category

Data category (optional, default None)

extraParams

Advanced parameters merged into the request body

livecrawlTimeout

Timeout for livecrawl (optional, default None)

maxAgeHours

Max content age in hours (default 1)

maxCharacters

Max text characters (mandatory, default 500)

numResults

Number of results (mandatory, default 10)

searchType

Search type (mandatory, default Auto)

timeoutMs

Request timeout in milliseconds

userLocation

User location for local search (optional, default None)

Attributes

Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
case class ExaSearchResult(query: String, results: List[ExaResult], requestId: Option[String], searchType: Option[String])

Container for search results returned by the Exa Search API.

Container for search results returned by the Exa Search API.

Value parameters

query

The original search query

requestId

Exa's unique identifier for this request (useful for debugging)

results

Ordered list of matching results

searchType

The search type that was actually applied by Exa

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object ExaSearchResult

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
object ExaSearchTool

Attributes

Supertypes
class Object
trait Matchable
class Any
Self type
case class RelatedTopic(text: String, url: Option[String])

A related topic from web search.

A related topic from web search.

Attributes

Companion
object
Supertypes
trait Serializable
trait Product
trait Equals
class Object
trait Matchable
class Any
Show all
object RelatedTopic

Attributes

Companion
class
Supertypes
trait Product
trait Mirror
class Object
trait Matchable
class Any
Self type
sealed trait SafeSearch

Safe-search filtering level for Brave Search API requests.

Safe-search filtering level for Brave Search API requests.

Controls whether adult or otherwise sensitive content is filtered from results.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Moderate
object Off
object Strict
object SafeSearch

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
SafeSearch.type
sealed trait SearchType

Search algorithm type used by the Exa Search API.

Search algorithm type used by the Exa Search API.

Controls the ranking and crawling strategy applied to a query.

Attributes

Companion
object
Supertypes
class Object
trait Matchable
class Any
Known subtypes
object Auto
object Deep
object Fast
object Neural
object SearchType

Attributes

Companion
trait
Supertypes
trait Sum
trait Mirror
class Object
trait Matchable
class Any
Self type
SearchType.type
Generated with