@nhtio/adk/batteries/tools/web_retrieval

RAG glue: turn web-search and web-scrape results into Retrievable records for a turn.

Remarks

The seam from "I searched / scraped something" to "it is in the turn as a Retrievable", shared by the SearXNG and Scrapper batteries. It is deliberately decoupled from the ADK core at runtime:

• The converters are pure (payload) => RawRetrievable[] — they build plain data objects and never instantiate a core class, so the module's only core coupling is erased import type.
• The recommended spool-artifact type travels as an open resolver (@nhtio/adk/forge!ArtifactConstructorResolver), never a closed string enum — a consumer's future YAML/HTML SpooledArtifact subclass works with no change here. The converter hands the recommendation to the caller's spool hook; the caller owns the actual class import.
• The one helper that must construct a Retrievable (storeRetrievables) takes the constructor via a resolver (constructor / sync / async / dynamic-import), exactly like the vector battery's createVectorStore client.

Web content is 'third-party-public' by default — a definitional constant for open-web data (NOT inferred from the URL, which CONTRIBUTING Design Decision #12 forbids); override via trustTier when you know better.

Interfaces

Interface	Description
ArticleToRetrievableOptions	Options for scrapperArticleToRetrievable.
ArtifactRecommendations	The artifact-resolver recommendations a caller may supply so the glue names no concrete class itself. Each converter asks for the relevant key; if the caller omits it, content stays inline.
RetrievableStoreCtx	The minimal context surface storeRetrievables needs.
ScrapperArticleLike	Minimal structural shape of a Scrapper normalised article.
ScrapperLinkLike	Minimal structural shape of a Scrapper normalised link.
ScrapperLinksLike	Minimal structural shape of a Scrapper normalised links payload.
SearxngPayloadLike	Minimal structural shape of a SearXNG normalised payload.
SearxngResultLike	Minimal structural shape of a SearXNG normalised result the converter reads.
ToRetrievableOptions	Options common to every converter.

Type Aliases

Type Alias	Description
ArticleContentSource	Which article text field to use as the record content.
Resolver	A resolver of T: the value itself, or a (sync/async) thunk, optionally a module { default }.
RetrievableCtor	A constructor that builds a @nhtio/adk!Retrievable from a @nhtio/adk!RawRetrievable.
SpoolHook	A reader-backed-artifact hook. Called by a converter for content that may be large; the converter passes the artifact constructor it recommends for this content (an open @nhtio/adk/forge!ArtifactConstructorResolver) so the caller can wrap with the right subclass — preserving its forged query tools — using the caller's own core import. Return a @nhtio/adk!SpooledArtifact to store the content reader-backed, or undefined to keep it inline as a string.

Functions

Function	Description
scrapperArticleToRetrievable	Convert a Scrapper normalised article into a single @nhtio/adk!RawRetrievable.
scrapperLinksToRetrievables	Convert a Scrapper normalised links payload into one @nhtio/adk!RawRetrievable per link.
searxngResultsToRetrievables	Convert a SearXNG normalised payload into one @nhtio/adk!RawRetrievable per result.
storeRetrievables	Construct @nhtio/adk!Retrievables from RawRetrievables and store each via ctx.