docs: strengthen README badges + refine _search_local.py

- README: 4 badges -> 8 (CI, PyPI version, downloads, GitHub stars, MIT, Python, black, Docker)
- _search_local.py: max(1,...) guard on bm25_top_k, named uri sets, res->result rename, log args inline

Author: Flamehaven CI

README.md

@@ -6,9 +6,13 @@
 
 ### Self-hosted RAG search engine. Production-ready in 3 minutes.
 
+[![CI](https://github.com/flamehaven01/Flamehaven-Filesearch/actions/workflows/ci.yml/badge.svg)](https://github.com/flamehaven01/Flamehaven-Filesearch/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/flamehaven-filesearch.svg)](https://pypi.org/project/flamehaven-filesearch/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/flamehaven-filesearch.svg?label=PyPI%20downloads)](https://pypi.org/project/flamehaven-filesearch/)
+[![GitHub stars](https://img.shields.io/github/stars/flamehaven01/Flamehaven-Filesearch?style=flat&label=stars)](https://github.com/flamehaven01/Flamehaven-Filesearch/stargazers)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-1.6.2-blue.svg)](CHANGELOG.md)
 [![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
 [![Docker](https://img.shields.io/badge/docker-ready-brightgreen.svg)](https://hub.docker.com/r/flamehaven/filesearch)
 
 [Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [API Reference](http://localhost:8000/docs) • [Contributing](#-contributing)

flamehaven_filesearch/_search_local.py

@@ -10,11 +10,7 @@
 from urllib.parse import quote
 
 from .engine.hybrid_search import BM25, reciprocal_rank_fusion
-from .engine.quality_gate import (
-    SearchQualityGate,
-    SearchMetaLearner,
-    compute_search_confidence,
-)
+from .engine.quality_gate import SearchQualityGate, SearchMetaLearner, compute_search_confidence
 
 logger = logging.getLogger(__name__)
 
@@ -104,13 +100,18 @@ def _resolve_fused_docs(
     def _run_hybrid_rerank(
         self, store_name: str, query: str, semantic_results: List
     ) -> Tuple[List[Dict[str, Any]], float]:
-        """BM25 + ChronosGrid semantic -> RRF -> resolved docs + confidence score."""
+        """BM25 + ChronosGrid semantic -> RRF -> resolved docs + confidence score.
+
+        Returns:
+            (resolved_docs, confidence) where confidence is rank-divergence-gated [0, 1].
+        """
         if store_name not in self._bm25_indices or store_name in self._bm25_dirty:
             self._rebuild_bm25(store_name)
 
         # alpha->0 (keyword-dominant): expand BM25 pool; alpha->1: contract it.
         alpha = (getattr(self, "_meta_alpha", {})).get(store_name, 0.5)
-        bm25_top_k = int(self.config.max_sources * 2 * max(0.5, 1.5 - alpha))
+        bm25_multiplier = max(0.5, 1.5 - alpha)  # alpha=0.2->1.3x, 0.5->1.0x, 0.8->0.7x
+        bm25_top_k = max(1, int(self.config.max_sources * 2 * bm25_multiplier))
 
         bm25_ranked = self._collect_bm25_ranked(store_name, query, bm25_top_k)
         sem_ranked = self._collect_sem_ranked(store_name, semantic_results)
@@ -119,10 +120,11 @@ def _run_hybrid_rerank(
             [sem_ranked, bm25_ranked], k=60, top_k=self.config.max_sources
         )
 
+        bm25_uri_set = {r["id"] for r in bm25_ranked}
+        sem_uri_set = {r["id"] for r in sem_ranked}
         raw_score = fused[0]["score"] if fused else 0.0
-        confidence = compute_search_confidence(
-            raw_score, {r["id"] for r in bm25_ranked}, {r["id"] for r in sem_ranked}
-        )
+        confidence = compute_search_confidence(raw_score, bm25_uri_set, sem_uri_set)
+
         return self._resolve_fused_docs(store_name, fused), confidence
 
     # ------------------------------------------------------------------
@@ -184,28 +186,22 @@ def _local_search(
         }
 
         if not docs:
-            res = {
+            result = {
                 "status": "success",
                 "answer": "No documents indexed yet.",
                 "sources": [],
                 **base,
             }
             if search_mode in ["semantic", "hybrid", "multimodal"]:
-                res["semantic_results"] = semantic_results or []
-            return res
+                result["semantic_results"] = semantic_results or []
+            return result
 
-        quality_gate: SearchQualityGate = getattr(
-            self, "_quality_gate", SearchQualityGate()
-        )
-        meta_learner: SearchMetaLearner = getattr(
-            self, "_meta_learner", SearchMetaLearner()
-        )
+        quality_gate: SearchQualityGate = getattr(self, "_quality_gate", SearchQualityGate())
+        meta_learner: SearchMetaLearner = getattr(self, "_meta_learner", SearchMetaLearner())
 
         # Hybrid: BM25 + semantic RRF with quality gate
         if search_mode == "hybrid" and semantic_results:
-            fused_docs, confidence = self._run_hybrid_rerank(
-                store_name, query, semantic_results
-            )
+            fused_docs, confidence = self._run_hybrid_rerank(store_name, query, semantic_results)
             verdict = quality_gate.evaluate(confidence)
 
             if fused_docs:
@@ -274,9 +270,7 @@ def _local_search(
             result["semantic_results"] = semantic_results or []
         return result
 
-    def _run_meta_adapt(
-        self, store_name: str, meta_learner: "SearchMetaLearner"
-    ) -> None:
+    def _run_meta_adapt(self, store_name: str, meta_learner: "SearchMetaLearner") -> None:
         """Apply MetaLearner alpha recommendation when adaptation cycle triggers."""
         if not meta_learner.should_adapt():
             return
@@ -288,10 +282,7 @@ def _run_meta_adapt(
             self._meta_alpha[store_name] = new_alpha
             logger.info(
                 "[QualityGate] store=%s alpha %.3f -> %.3f trend=%s",
-                store_name,
-                current,
-                new_alpha,
-                meta_learner.store_trend(store_name),
+                store_name, current, new_alpha, meta_learner.store_trend(store_name),
             )
 
     # ------------------------------------------------------------------
@@ -322,8 +313,7 @@ def _resolve_semantic_sources(
         if not resolved:
             return None
         snippets = [
-            self._build_snippet(d.get("content", ""), query)
-            or d.get("content", "")[:200]
+            self._build_snippet(d.get("content", ""), query) or d.get("content", "")[:200]
             for d in resolved[:5]
         ]
         answer = " ".join(s for s in snippets if s) or (