briefsearch 0.1.0

Async DDG search with LLM-ready output

briefsearch

Thin async wrapper around duckduckgo_search + trafilatura that returns LLM-ready markdown from a search query. Designed for use in a daily brief generation pipeline.

Installation

pip install briefsearch

Quick Start

import asyncio
from briefsearch import search, search_many, results_to_markdown, SearchResult

async def main():
    # Snippet-only (default, fast)
    results: list[SearchResult] = await search("Tauri framework news", max_results=5)

    # With full article text for top N results
    results = await search("Tauri framework news", max_results=5, fetch_content=True, fetch_top_n=2)

    # Batch (parallel queries)
    all_results: dict[str, list[SearchResult]] = await search_many(
        ["query one", "query two"],
        max_results=5,
        timeout=8.0,
    )

    # Render to LLM-ready markdown
    md: str = results_to_markdown("Tauri framework news", results)
    print(md)

asyncio.run(main())

API Reference

search(query, *, max_results=5, fetch_content=False, fetch_top_n=1, fetch_timeout=5.0)

Search DuckDuckGo. Returns list[SearchResult]. Never raises — returns [] on failure.

Parameter	Type	Default	Description
query	str	—	Search query
max_results	int	5	Max DDG results
fetch_content	bool	False	Fetch full article text
fetch_top_n	int	1	How many top results to fetch content for
fetch_timeout	float	5.0	Per-URL fetch timeout in seconds

search_many(queries, *, max_results=5, fetch_content=False, fetch_top_n=1, fetch_timeout=5.0, timeout=10.0)

Run multiple queries in parallel. Returns dict[str, list[SearchResult]]. Queries that exceed timeout return [].

results_to_markdown(query, results)

Render results as LLM-ready markdown:

**Query:** {query}
- [{title}]({url}): {snippet}
  {first 300 chars of content if available}

SearchResult

@dataclass
class SearchResult:
    title: str
    url: str
    snippet: str                  # DDG body text
    content: str | None = None    # trafilatura full text, if fetched
    fetch_error: str | None = None