Streamlit UI sample
===================

The Streamlit UI is a small sample application, not the core interface of the
package. It is included to make the feedback loop visible: search for evidence,
mark what helps or does not help, rerank the current list, and optionally expand
retrieval with a feedback-refined query.

Install the UI extra
--------------------

Install ``evidence-fetcher`` with the optional UI dependencies:

.. code-block:: console

   pip install "evidence-fetcher[ui]"

Make sure ``BRAVE_SEARCH_API_KEY`` is configured before launching the app.

Launch the app
--------------

Start the browser-based sample:

.. code-block:: console

   evidence-fetcher-ui

Streamlit opens the app in a local browser tab. If the browser does not open
automatically, visit the local URL printed in the terminal, usually
``http://localhost:8501``.

Review evidence step by step
----------------------------

1. Enter a search query in the sidebar.

   The default query is only an example. Replace it with the topic you want to
   investigate.

2. Choose a result limit.

   Smaller limits are useful for quick review. Larger limits give the local
   ranker more candidates to reorder.

3. Click ``Search``.

   The app retrieves web evidence with Brave Search, normalizes the results,
   removes duplicate URLs, and displays the ranked candidates.

4. Read the result titles, URLs, and snippets.

   Each result is a candidate evidence item. The UI does not decide whether a
   result is correct; it gives you controls to record your judgment.

5. Mark each useful result.

   Use ``more`` for evidence you want to see more of, ``less`` for evidence that
   is somewhat off target, ``irrelevant`` for evidence that should move away
   from the current ranking direction, and ``unsure`` when you want to record
   that you reviewed the item without changing the ranking direction.

6. Click ``Rerank results``.

   Reranking reorders the current candidate list using only the evidence already
   shown and the feedback you marked.

7. Click ``Expand search`` when the current candidates are not enough.

   Expansion builds a deterministic refined query from your feedback, performs
   one additional Brave retrieval, merges new URLs into the session, and reranks
   the expanded list.

8. Repeat marking, reranking, and expansion as needed.

   The sample is designed to show an explicit Interactive Information Retrieval
   loop. Searches expand only when you ask for expansion; feedback buttons do not
   automatically run background retrieval.

How to interpret the controls
-----------------------------

``more``
   This result is useful and should pull the ranking toward similar evidence.

``less``
   This result is related but less useful, so similar evidence should receive
   less emphasis.

``irrelevant``
   This result is off target and should push the ranking away from similar
   evidence.

``unsure``
   This records that the item was reviewed, but it does not change the ranking
   direction.

``Rerank results``
   Reorder the current results with accumulated feedback.

``Expand search``
   Fetch additional candidates with a refined query derived from accumulated
   feedback.