% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/public__s3_methods.R
\name{search_options}
\alias{search_options}
\title{Create Search Options}
\usage{
search_options(
  max_results = NULL,
  timeout = NULL,
  max_retries = NULL,
  retry_delay = NULL,
  backoff_multiplier = NULL,
  inter_search_delay = NULL,
  humanize_timing = NULL,
  jitter_factor = NULL,
  allow_direct_fallback = NULL,
  selenium_browser_preference = NULL,
  stability_profile = NULL,
  performance_profile = NULL,
  webpage_policy = NULL,
  auto_openwebpage_policy = NULL,
  langgraph_node_retries = NULL,
  langgraph_cache_enabled = NULL,
  finalize_when_all_unresolved_exhausted = NULL,
  field_attempt_budget_mode = NULL,
  allow_read_webpages = NULL,
  webpage_relevance_mode = NULL,
  webpage_heuristic_profile = NULL,
  webpage_embedding_provider = NULL,
  webpage_embedding_model = NULL,
  webpage_timeout = NULL,
  webpage_max_bytes = NULL,
  webpage_max_chars = NULL,
  webpage_max_chunks = NULL,
  webpage_chunk_chars = NULL,
  webpage_embedding_api_base = NULL,
  webpage_prefilter_k = NULL,
  webpage_use_mmr = NULL,
  webpage_mmr_lambda = NULL,
  webpage_cache_enabled = NULL,
  webpage_cache_max_entries = NULL,
  webpage_cache_max_text_chars = NULL,
  webpage_blocked_cache_ttl_sec = NULL,
  webpage_blocked_cache_max_entries = NULL,
  webpage_blocked_probe_bytes = NULL,
  webpage_blocked_detect_on_200 = NULL,
  webpage_blocked_body_scan_bytes = NULL,
  webpage_pdf_enabled = NULL,
  webpage_pdf_timeout = NULL,
  webpage_pdf_max_bytes = NULL,
  webpage_pdf_max_pages = NULL,
  webpage_pdf_max_text_chars = NULL,
  webpage_user_agent = NULL,
  wikidata_template_path = NULL,
  wiki_top_k_results = NULL,
  wiki_doc_content_chars_max = NULL,
  search_doc_content_chars_max = NULL
)
}
\arguments{
\item{max_results}{Maximum number of search results to return per query.
Higher values provide more context but increase latency. Default: 10.}

\item{timeout}{Timeout in seconds for individual search requests.
Applies to each tier attempt separately. Default: 30.}

\item{max_retries}{Maximum number of retry attempts when a search tier fails.
After exhausting retries, the system falls back to the next tier. Default: 3.}

\item{retry_delay}{Initial delay in seconds before the first retry.
Subsequent retries use exponential backoff. Default: 2.}

\item{backoff_multiplier}{Multiplier for exponential backoff between retries.
E.g., with retry_delay=2 and multiplier=1.5, delays are 2s, 3s, 4.5s. Default: 1.5.}

\item{inter_search_delay}{Minimum delay in seconds between consecutive searches.
Helps avoid rate limiting from search providers. Default: 1.5.}

\item{humanize_timing}{Whether to humanize search timing with non-uniform
delays. Default uses \code{ASA_HUMANIZE_TIMING}.}

\item{jitter_factor}{Random jitter factor applied to humanized timing and
retry spacing. Default uses \code{ASA_JITTER_FACTOR}.}

\item{allow_direct_fallback}{Whether to allow direct fallback requests in the
search transport. Default: FALSE.}

\item{selenium_browser_preference}{Selenium browser engine preference order.
One of \code{"firefox_first"} (default) or \code{"chrome_first"}.}

\item{stability_profile}{High-level search stability profile. One of
\code{"deterministic"}, \code{"balanced"}, or \code{"stealth_first"}
(default). This controls default anti-detection and orchestration behavior.}

\item{performance_profile}{Orchestration profile optimized for one of:
\code{"latency"}, \code{"balanced"}, or \code{"quality"}.}

\item{webpage_policy}{Structured OpenWebpage policy list with keys:
\code{max_open_calls}, \code{host_cooldown_seconds},
\code{blocked_host_ttl_seconds}, \code{open_only_if_score_ge}, and
\code{parallel_open_limit}.}

\item{auto_openwebpage_policy}{Automatic OpenWebpage follow-up policy. Use
\code{"auto"} for profile-driven automatic opening or \code{"off"} to
disable it. Defaults to \code{"off"} for the deterministic profile and
\code{"auto"} otherwise.}

\item{langgraph_node_retries}{Whether to enable LangGraph node-level retries
in agent graph construction. Default: TRUE.}

\item{langgraph_cache_enabled}{Whether to enable LangGraph node caching.
Default: FALSE.}

\item{finalize_when_all_unresolved_exhausted}{Optional override for
orchestration finalizer behavior. When TRUE, finalize once all unresolved
fields have exhausted their search-attempt budget.}

\item{field_attempt_budget_mode}{Optional field-attempt budget mode passed to
orchestration field_resolver. One of \code{"strict_cap"} or
\code{"soft_cap"}.}

\item{allow_read_webpages}{If TRUE, allows the agent to open and read full
webpages (HTML/text) via the OpenWebpage tool. Disabled by default.}

\item{webpage_relevance_mode}{Relevance selection for opened webpages.
One of: "auto", "lexical", "embeddings".}

\item{webpage_heuristic_profile}{Heuristic profile used when annotating links
from opened webpages. Must be "generic" (task-agnostic default).}

\item{webpage_embedding_provider}{Embedding provider for relevance. One of:
"auto", "openai", "sentence_transformers".}

\item{webpage_embedding_model}{Embedding model identifier for relevance.}

\item{webpage_timeout}{Timeout in seconds for OpenWebpage fetches and (when
used) relevance embeddings.}

\item{webpage_max_bytes}{Maximum bytes to download per page (hard cap).}

\item{webpage_max_chars}{Maximum characters returned from an opened page
(hard cap on tool output).}

\item{webpage_max_chunks}{Maximum number of relevant excerpts to include from
a page.}

\item{webpage_chunk_chars}{Approximate size (in characters) of each excerpt.}

\item{webpage_embedding_api_base}{Optional OpenAI-compatible base URL for
embeddings. If NULL, uses \code{OPENAI_API_BASE} or
\code{https://api.openai.com/v1}.}

\item{webpage_prefilter_k}{Optional lexical prefilter size before embedding
relevance selection.}

\item{webpage_use_mmr}{Whether to apply maximal marginal relevance (MMR) for
more diverse excerpts.}

\item{webpage_mmr_lambda}{MMR tradeoff between relevance (1.0) and diversity (0.0).}

\item{webpage_cache_enabled}{Enable per-run caching of opened pages.}

\item{webpage_cache_max_entries}{Max cached page entries per run.}

\item{webpage_cache_max_text_chars}{Max characters of extracted page text to
store per cached page (separate from \code{webpage_max_chars}, which caps
tool output).}

\item{webpage_blocked_cache_ttl_sec}{TTL in seconds for cached blocked URL
responses (HTTP 403/429 and anti-bot pages).}

\item{webpage_blocked_cache_max_entries}{Max blocked-URL cache entries per run.}

\item{webpage_blocked_probe_bytes}{Max bytes to inspect when classifying a
response as blocked.}

\item{webpage_blocked_detect_on_200}{If TRUE, classify anti-bot interstitials
served with HTTP 200 as blocked responses.}

\item{webpage_blocked_body_scan_bytes}{Max response bytes scanned on HTTP 200
pages for anti-bot marker detection.}

\item{webpage_pdf_enabled}{If TRUE, OpenWebpage attempts PDF extraction via
\code{pdftotext}.}

\item{webpage_pdf_timeout}{Timeout in seconds for \code{pdftotext}.}

\item{webpage_pdf_max_bytes}{Max PDF bytes to download before extraction.}

\item{webpage_pdf_max_pages}{Max pages passed to \code{pdftotext}.}

\item{webpage_pdf_max_text_chars}{Max extracted PDF characters kept before
relevance selection/output truncation.}

\item{webpage_user_agent}{User-Agent string used for webpage fetches.}

\item{wikidata_template_path}{Optional path to a Wikidata template JSON file.
When provided, Wikidata known-entity catalogs are loaded from this file.
If NULL (default), no task-specific template catalog is auto-loaded.}

\item{wiki_top_k_results}{Number of Wikipedia search results to fetch per
query (default: 5). Higher values may provide more coverage at the cost of
latency/noise.}

\item{wiki_doc_content_chars_max}{Maximum number of characters to include
from each Wikipedia page/summary in the Wikipedia tool output (default: 1000).}

\item{search_doc_content_chars_max}{Maximum number of characters to include
from DuckDuckGo Search tool outputs (default: 500). This caps the text
returned to the LLM per Search tool invocation.}
}
\value{
An object of class \code{asa_search}
}
\description{
Creates search configuration for controlling DuckDuckGo search behavior,
including rate limiting, retry policies, and result limits. These options
are used by the 4-tier search fallback system.
}
\details{
The search system uses a 4-tier fallback architecture:
\enumerate{
  \item \strong{PRIMP}: HTTP/2 with browser TLS fingerprint
  \item \strong{Selenium}: Headless browser for JS-rendered content
  \item \strong{DDGS}: Standard ddgs Python library
  \item \strong{Requests}: Raw POST to DuckDuckGo HTML endpoint
}

The retry/backoff settings apply within each tier. If all retries
are exhausted, the system automatically falls back to the next tier.
Selenium browser initialization defaults to \code{"firefox_first"} and
falls back to Chrome engines when Firefox is unavailable.
}
\examples{
\dontrun{
# Default settings
search <- search_options()

# More aggressive settings for faster searches
search <- search_options(
  max_results = 5,
  timeout = 10,
  max_retries = 2
)

# Conservative settings for rate-limited environments
search <- search_options(
  inter_search_delay = 2.0,
  max_retries = 5,
  backoff_multiplier = 2.0
)

# Use with asa_config
config <- asa_config(
  backend = "openai",
  search = search_options(max_results = 15)
)
}

}
\seealso{
\code{\link{asa_config}}, \code{\link{configure_search}}
}
