evidence-fetcher 0.1.0

Interactive evidence-search and relevance-feedback experiment scaffold.

evidence-fetcher

evidence-fetcher is an interactive evidence-search and relevance-feedback experiment.

The current vertical slice fetches web evidence from Brave Search, normalizes the provider response, removes duplicate URLs, and exposes the results through a Python API and a small command-line interface.

Installation

Install the core package:

pip install evidence-fetcher

Configuration

Create a Brave Search API key and expose it as BRAVE_SEARCH_API_KEY:

export BRAVE_SEARCH_API_KEY="..."

Python API

from evidence_fetcher import fetch_evidence

results = fetch_evidence("retrieval augmented generation evaluation")

for evidence in results:
    print(evidence.title)
    print(evidence.url)
    print(evidence.snippet)

fetch_evidence() returns typed Evidence objects with normalized title, url, snippet, source, and rank fields.

CLI

Readable text output:

evidence-fetcher "retrieval augmented generation evaluation"

JSON output:

evidence-fetcher "retrieval augmented generation evaluation" --format json

Use --limit to control the maximum number of results.

Architecture

The public API is intentionally small: fetch_evidence() accepts a query and returns normalized, deduplicated Evidence results. Provider-specific HTTP requests, credential handling, and response parsing live behind an internal Brave Search provider. The provider depends on a small HTTP client protocol, so tests and future integrations can inject a mock client instead of using the network.

Package-specific exceptions distinguish configuration errors, request failures, and malformed provider responses.

Only Brave Search is implemented in this slice. No Streamlit UI or additional search providers are included yet.

Development

This project uses uv for environment and dependency management.

uv sync
uv run pytest
uv run ruff check .
uv run mypy src
uv build
uv run sphinx-build -b html docs/source docs/built

Common shortcuts are available through make:

make check
make docs
make clean

Documentation

Documentation is built with Sphinx and Furo from docs/source/ into docs/built/. Read the Docs should build the documentation through its normal repository integration.

Releases

Releases are managed with Python Semantic Release and Conventional Commits. The GitHub Actions release workflow is intended to create the release commit, tag, GitHub release, wheel, sdist, and PyPI publication through trusted publishing.