Base Source

class agent.browsing.manual.sources.base.ManualSource(*args, **kwargs)

Bases: Protocol

Protocol for manual browsing sources.

Implementations should be stateless or manage their own lightweight state.

iter_all(query, chunk_size=100, limit=None, **kwargs)

Iterate over results by fetching in chunks.

Parameters:

• query (str) – Free-text query.

• chunk_size (int) – Number of items to fetch per request.

• limit (Optional[int]) – Optional maximum number of items to yield.

• kwargs (object)

Return type:

Iterator[SearchItem]

Returns:

Iterator over search items.

search(query, max_results=25, start=0, **kwargs)

Return a single page of results for a query.

Parameters:

• query (str) – Free-text query.

• max_results (int) – Maximum number of results to return.

• start (int) – Zero-based start index for pagination across results.

• kwargs (object)

Return type:

List[SearchItem]

Returns:

List of search items for the requested page.

search_all(query, chunk_size=100, limit=None, **kwargs)

Collect results for a query into a list by consuming the iterator.

Parameters:

• query (str) – Free-text query.

• chunk_size (int) – Number of items to fetch per request.

• limit (Optional[int]) – Optional maximum number of items to collect.

• kwargs (object)

Return type:

List[SearchItem]

Returns:

List of collected search items.

class agent.browsing.manual.sources.base.SearchItem(title, url, snippet=None, item_id=None, extra=None)

Bases: object

Lightweight search result item for manual browsing.

Variables:

• title – Human-readable title of the item.

• url – Canonical URL for the item.

• snippet – Optional short snippet or summary.

• item_id – Optional stable identifier when available, e.g., a PubMed ID.

• extra – Optional provider-specific metadata.

Parameters:

• title (str)

• url (str)

• snippet (str | None)

• item_id (str | None)

• extra (dict | None)

extra: Optional[dict] = None

item_id: Optional[str] = None

snippet: Optional[str] = None

title: str

url: str

agent.browsing.manual.sources.base.paginate_results(results, limit)

Yield up to a limit of results from an iterable.

Parameters:

• results (Iterable[SearchItem]) – Iterable of search items to paginate.

• limit (Optional[int]) – Optional maximum number of items to yield.

Return type:

Iterator[SearchItem]

Returns:

Iterator yielding up to limit items.