Metadata-Version: 2.4
Name: evidence-fetcher
Version: 0.1.0
Summary: Interactive evidence-search and relevance-feedback experiment scaffold.
Project-URL: Homepage, https://github.com/yeiichi/evidence-fetcher
Project-URL: Documentation, https://evidence-fetcher.readthedocs.io/
Project-URL: Repository, https://github.com/yeiichi/evidence-fetcher
Project-URL: Issues, https://github.com/yeiichi/evidence-fetcher/issues
Author: Eiichi YAMAMOTO
License-Expression: MIT
License-File: LICENSE
Keywords: evidence,relevance-feedback,search
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# 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:

```bash
pip install evidence-fetcher
```

## Configuration

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

```bash
export BRAVE_SEARCH_API_KEY="..."
```

## Python API

```python
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:

```bash
evidence-fetcher "retrieval augmented generation evaluation"
```

JSON output:

```bash
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.

```bash
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`:

```bash
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.
