signalwire-sdk 3.4.0.dev110__tar.gz → 3.4.1.dev111__tar.gz

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: signalwire-sdk
-Version: 3.4.0.dev110
+Version: 3.4.1.dev111
 Summary: SignalWire SDK
 Author-email: SignalWire Team <info@signalwire.com>
 License: MIT

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "signalwire-sdk"
-version = "3.4.0.dev110"
+version = "3.4.1.dev111"
 description = "SignalWire SDK"
 authors = [
     {name = "SignalWire Team", email = "info@signalwire.com"}

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/signalwire/signalwire/__init__.py

@@ -52,7 +52,7 @@ if TYPE_CHECKING:
     from signalwire.utils.schema_utils import SchemaValidationError
     from signalwire.web import WebService
 
-__version__ = "3.4.0.dev110"
+__version__ = "3.4.1.dev111"
 
 # §6.2-python (owner decision: NO packaging split — one package, all deps required;
 # IMPORT-TIME behavior only): the agent/web symbols are lazy-imported via module

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/signalwire/signalwire/agent_server.py

@@ -68,7 +68,7 @@ class AgentServer:
         self.app = FastAPI(
             title="SignalWire AI Agents",
             description="Hosted SignalWire AI Agents",
-            version="3.4.0.dev110",
+            version="3.4.1.dev111",
             redirect_slashes=False,
             docs_url=None,
             redoc_url=None,

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/signalwire/signalwire/cli/build_search.py

@@ -252,6 +252,17 @@ Examples:
         help="Chunk size in words for sliding window strategy (default: 50)",
     )
 
+    parser.add_argument(
+        "--min-chunk-size",
+        type=int,
+        default=0,
+        help=(
+            "Markdown strategy: minimum words before a heading starts a new "
+            "chunk. Sections shorter than this merge into the next one instead "
+            "of being emitted alone (default: 0, split at every heading)"
+        ),
+    )
+
     parser.add_argument(
         "--overlap-size",
         type=int,
@@ -292,7 +303,12 @@ Examples:
         "--index-nlp-backend",
         choices=["nltk", "spacy"],
         default="nltk",
-        help="NLP backend for document processing: nltk (fast, default) or spacy (better quality, slower)",
+        help=(
+            "NLP backend for document processing: nltk (fast, default) or "
+            "spacy (slower; also expands content with WordNet synonyms, whose "
+            "effect depends on your corpus and is written into the index -- "
+            "measure it before choosing, see preprocess_document_content)"
+        ),
     )
 
     parser.add_argument("--verbose", action="store_true", help="Enable verbose output")
@@ -484,6 +500,7 @@ Examples:
                 chunking_strategy=args.chunking_strategy,
                 max_sentences_per_chunk=args.max_sentences_per_chunk,
                 chunk_size=args.chunk_size,
+                min_chunk_size=args.min_chunk_size,
                 chunk_overlap=args.overlap_size,
                 split_newlines=args.split_newlines,
                 index_nlp_backend=args.index_nlp_backend,
@@ -593,6 +610,7 @@ Examples:
             chunking_strategy=args.chunking_strategy,
             max_sentences_per_chunk=args.max_sentences_per_chunk,
             chunk_size=args.chunk_size,
+            min_chunk_size=args.min_chunk_size,
             chunk_overlap=args.overlap_size,
             split_newlines=args.split_newlines,
             index_nlp_backend=args.index_nlp_backend,
@@ -741,7 +759,11 @@ def search_command() -> None:
         "--query-nlp-backend",
         choices=["nltk", "spacy"],
         default="nltk",
-        help="NLP backend for query processing: nltk (fast, default) or spacy (better quality, slower)",
+        help=(
+            "NLP backend for query processing: nltk (fast, default) or spacy "
+            "(slower; expands the query with WordNet synonyms, whose effect "
+            "depends on your corpus -- measure it, see preprocess_query)"
+        ),
     )
     parser.add_argument(
         "--keyword-weight",
@@ -1417,9 +1439,17 @@ def console_entry_point() -> None:
     """Console script entry point for pip installation"""
     import sys
 
-    # Fast help check - show help without importing heavy modules
+    # Fast help check - show help without importing heavy modules.
+    #
+    # NOTE: this text is hand-maintained and has drifted from the parser three
+    # times over. It omitted the `markdown` and `json` strategies (both real and
+    # in daily use), and it advertised all-mpnet-base-v2 as the default model
+    # when DEFAULT_MODEL is all-MiniLM-L6-v2 -- a 768-dim answer to a 384-dim
+    # question, which is the kind of thing someone builds a mismatched index on.
+    # Anything added to the parser below must be added here too, or it is
+    # undiscoverable.
     if len(sys.argv) > 1 and sys.argv[1] in ["--help", "-h"]:
-        print("""usage: sw-search [-h] [--output OUTPUT] [--chunking-strategy {sentence,sliding,paragraph,page,semantic,topic,qa}]
+        print("""usage: sw-search [-h] [--output OUTPUT] [--chunking-strategy {sentence,sliding,paragraph,page,semantic,topic,qa,json,markdown}]
                  [--max-sentences-per-chunk MAX_SENTENCES_PER_CHUNK] [--chunk-size CHUNK_SIZE]
                  [--overlap-size OVERLAP_SIZE] [--split-newlines SPLIT_NEWLINES] [--file-types FILE_TYPES]
                  [--exclude EXCLUDE] [--languages LANGUAGES] [--model MODEL] [--tags TAGS]
@@ -1435,12 +1465,20 @@ positional arguments:
 options:
   -h, --help            show this help message and exit
   --output OUTPUT       Output .swsearch file (default: sources.swsearch)
-  --chunking-strategy {sentence,sliding,paragraph,page,semantic,topic,qa}
-                        Chunking strategy to use (default: sentence)
+  --chunking-strategy {sentence,sliding,paragraph,page,semantic,topic,qa,json,markdown}
+                        Chunking strategy to use (default: sentence). Use
+                        "markdown" for documentation with code blocks.
   --max-sentences-per-chunk MAX_SENTENCES_PER_CHUNK
                         Maximum sentences per chunk for sentence strategy (default: 5)
   --chunk-size CHUNK_SIZE
-                        Chunk size in words for sliding window strategy (default: 50)
+                        Chunk size in words (default: 50). For the markdown
+                        strategy this is the split threshold, applied as
+                        chunk_size * 6 characters.
+  --min-chunk-size MIN_CHUNK_SIZE
+                        Markdown strategy: minimum words before a heading starts
+                        a new chunk. Shorter sections merge into the next one
+                        instead of being emitted alone (default: 0, split at
+                        every heading).
   --overlap-size OVERLAP_SIZE
                         Overlap size in words for sliding window strategy (default: 10)
   --split-newlines SPLIT_NEWLINES
@@ -1450,10 +1488,11 @@ options:
   --exclude EXCLUDE     Comma-separated glob patterns to exclude (e.g., "**/test/**,**/__pycache__/**")
   --languages LANGUAGES
                         Comma-separated language codes (default: en)
-  --model MODEL         Sentence transformer model name (default: sentence-transformers/all-mpnet-base-v2)
+  --model MODEL         Sentence transformer model name or alias (mini/base/
+                        large). Default: mini (sentence-transformers/all-MiniLM-L6-v2)
   --tags TAGS           Comma-separated tags to add to all chunks
   --index-nlp-backend {nltk,spacy}
-                        NLP backend for document processing: nltk (fast, default) or spacy (better quality, slower)
+                        NLP backend for document processing: nltk (fast, default) or spacy (slower, expands with WordNet synonyms — effect depends on your corpus, measure it)
   --verbose             Enable verbose output
   --validate            Validate the created index after building
   --semantic-threshold SEMANTIC_THRESHOLD

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/signalwire/signalwire/search/document_processor.py

@@ -116,6 +116,7 @@ class DocumentProcessor:
         max_sentences_per_chunk: int = 5,
         chunk_size: int = 50,
         chunk_overlap: int = 10,
+        min_chunk_size: int = 0,
         split_newlines: int | None = None,
         index_nlp_backend: str = "nltk",
         verbose: bool = False,
@@ -137,6 +138,11 @@ class DocumentProcessor:
                 - 'json': JSON structure-aware chunking
                 - 'markdown': Markdown structure-aware chunking with code block detection
             max_sentences_per_chunk: For sentence strategy (default: 5)
+            min_chunk_size: For markdown strategy - minimum words before a
+                heading starts a new chunk. Sections shorter than this are
+                merged forward into the next one instead of being emitted
+                alone. Defaults to 0, which preserves the previous behaviour
+                of splitting at every heading.
             chunk_size: For sliding strategy - words per chunk (default: 50)
             chunk_overlap: For sliding strategy - overlap in words (default: 10)
             split_newlines: For sentence strategy - split on multiple newlines (optional)
@@ -148,6 +154,7 @@ class DocumentProcessor:
         self.chunking_strategy = chunking_strategy
         self.max_sentences_per_chunk = max_sentences_per_chunk
         self.chunk_size = chunk_size
+        self.min_chunk_size = min_chunk_size
         self.chunk_overlap = chunk_overlap
         self.split_newlines = split_newlines
         self.semantic_threshold = semantic_threshold
@@ -364,7 +371,7 @@ class DocumentProcessor:
 
     def _extract_powerpoint(self, file_path: str) -> Any:
         """Extract text from PowerPoint files"""
-        if not Presentation:
+        if Presentation is None:
             return json.dumps(
                 {"error": "python-pptx not available for PowerPoint processing"}
             )
@@ -461,6 +468,12 @@ class DocumentProcessor:
         tokens = md.parse(content)
         lines = content.split("\n")
         threshold_chars = max(1, self.chunk_size * 6)
+        # Minimum size before a heading is allowed to start a new chunk. Without
+        # this the walker flushes at EVERY heading, so a document with dense
+        # headings yields chunks that are a title plus one sentence -- true to
+        # the structure but too thin to retrieve on, and they crowd out the
+        # substantial chunks around them. 0 keeps the original behaviour.
+        min_chars = max(0, self.min_chunk_size * 6)
 
         # Group top-level tokens into atomic blocks.
         # A "block" here = heading OR one non-heading container whose source
@@ -537,6 +550,19 @@ class DocumentProcessor:
 
         for block in blocks:
             if block["type"] == "heading":
+                # Too small to stand alone: fold this section into the one being
+                # built rather than emitting it. The heading line stays in the
+                # text, so the reader still sees the structure; only the chunk
+                # boundary moves.
+                if min_chars and 0 < current_size < min_chars:
+                    hierarchy = [
+                        *hierarchy[: block["level"] - 1],
+                        block["heading_text"],
+                    ]
+                    current_lines.extend(block["source_lines"])
+                    current_end_line = block["end_line"]
+                    current_size += sum(len(line) + 1 for line in block["source_lines"])
+                    continue
                 # Flush whatever preceded this heading under the old hierarchy.
                 flush()
                 level = block["level"]
@@ -938,7 +964,13 @@ class DocumentProcessor:
         if not sentences:
             return 1
 
+        # `if not sentences` does not catch a list of EMPTY sentences, which is
+        # what a line of dots or an ASCII rule splits into -- ". . . " becomes
+        # ['', '', '', '']. That averages to 0.0 and the division below raises
+        # ZeroDivisionError on a document that is merely ugly, not invalid.
         avg_sentence_length = sum(len(s) for s in sentences) / len(sentences)
+        if avg_sentence_length <= 0:
+            return 1
         # Target chunk size divided by average sentence length
         optimal_sentences = max(1, int(self.chunk_size / avg_sentence_length))
         return min(optimal_sentences, 10)  # Cap at 10 sentences for readability
@@ -1696,6 +1728,7 @@ class DocumentProcessor:
             # reachable by either. Chunk COUNT and order are untouched, so
             # chunk_index still addresses the same source chunk.
             current_heading = ""
+            current_doc = None
             for idx, json_chunk in enumerate(data["chunks"]):
                 if not isinstance(json_chunk, dict) or "content" not in json_chunk:
                     logger.warning(f"Skipping invalid chunk {idx} in {filename}")
@@ -1741,6 +1774,24 @@ class DocumentProcessor:
                 # Create chunk with proper structure
                 chunk_text = json_chunk["content"]
                 stripped = chunk_text.lstrip()
+
+                # One JSON file routinely holds chunks from many source
+                # documents, and current_heading would otherwise carry across
+                # the boundary: the last heading of one document prepended to
+                # the first subsection of the next, asserting a subject the
+                # chunk does not have. It does not fire on the corpus this was
+                # written for -- every chunk there opens with its own h1, so
+                # the heading is reset each time, and a scan of 16,894 chunks
+                # found no instance -- but that is a property of those inputs,
+                # not of this loop. Reset when the document changes.
+                doc_key = (
+                    json_metadata.get("url")
+                    or json_metadata.get("source")
+                    or json_metadata.get("filename")
+                )
+                if doc_key != current_doc:
+                    current_doc = doc_key
+                    current_heading = ""
                 if stripped.startswith("# ") and not stripped.startswith("## "):
                     # A new topic: remember its heading, and leave it alone -
                     # it already names itself.

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/signalwire/signalwire/search/index_builder.py

@@ -47,6 +47,7 @@ class IndexBuilder:
         chunking_strategy: str = "sentence",
         max_sentences_per_chunk: int = 5,
         chunk_size: int = 50,
+        min_chunk_size: int = 0,
         chunk_overlap: int = 10,
         split_newlines: int | None = None,
         index_nlp_backend: str = "nltk",
@@ -64,6 +65,8 @@ class IndexBuilder:
             chunking_strategy: Strategy for chunking documents ('sentence', 'sliding', 'paragraph', 'page', 'semantic', 'topic', 'qa', 'json')
             max_sentences_per_chunk: For sentence strategy (default: 5)
             chunk_size: For sliding strategy - words per chunk (default: 50)
+            min_chunk_size: For markdown strategy - minimum words before a
+                heading starts a new chunk (default: 0, split at every heading)
             chunk_overlap: For sliding strategy - overlap in words (default: 10)
             split_newlines: For sentence strategy - split on multiple newlines (optional)
             index_nlp_backend: NLP backend for indexing (default: 'nltk')
@@ -77,6 +80,7 @@ class IndexBuilder:
         self.chunking_strategy = chunking_strategy
         self.max_sentences_per_chunk = max_sentences_per_chunk
         self.chunk_size = chunk_size
+        self.min_chunk_size = min_chunk_size
         self.chunk_overlap = chunk_overlap
         self.split_newlines = split_newlines
         self.index_nlp_backend = index_nlp_backend
@@ -106,6 +110,7 @@ class IndexBuilder:
             chunking_strategy=chunking_strategy,
             max_sentences_per_chunk=max_sentences_per_chunk,
             chunk_size=chunk_size,
+            min_chunk_size=min_chunk_size,
             chunk_overlap=chunk_overlap,
             split_newlines=split_newlines,
             index_nlp_backend=self.index_nlp_backend,
@@ -679,6 +684,7 @@ class IndexBuilder:
                 "embedding_model": self.model_name,
                 "embedding_dimensions": str(embedding_dimensions),
                 "chunk_size": str(self.chunk_size),
+                "min_chunk_size": str(self.min_chunk_size),
                 "chunk_overlap": str(self.chunk_overlap),
                 "preprocessing_version": "1.0",
                 "languages": json.dumps(languages),
@@ -778,6 +784,7 @@ class IndexBuilder:
         if not Path(index_file).exists():
             return {"valid": False, "error": "Index file does not exist"}
 
+        conn = None
         try:
             conn = sqlite3.connect(index_file)
             cursor = conn.cursor()
@@ -804,8 +811,6 @@ class IndexBuilder:
             cursor.execute("SELECT COUNT(DISTINCT filename) FROM chunks")
             file_count = cursor.fetchone()[0]
 
-            conn.close()
-
             return {
                 "valid": True,
                 "chunk_count": chunk_count,
@@ -815,6 +820,15 @@ class IndexBuilder:
 
         except Exception as e:
             return {"valid": False, "error": str(e)}
+        finally:
+            # Every failure path here used to leak the handle: the early return
+            # for missing tables, and the except that turns any error into
+            # {"valid": False}. Validating a directory of indexes -- which is
+            # what this function is for -- leaked one descriptor per bad index,
+            # and on Windows kept each file locked. Close it once, on the way
+            # out, however we leave.
+            if conn is not None:
+                conn.close()
 
     def _store_chunks_pgvector(
         self,

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/signalwire/signalwire/search/migration.py

@@ -73,6 +73,7 @@ class SearchIndexMigrator:
             "config": {},
         }
 
+        sqlite_conn = None
         try:
             # Connect to SQLite
             if self.verbose:
@@ -272,7 +273,14 @@ class SearchIndexMigrator:
             logger.error(f"Migration failed: {e}")
             raise
         finally:
-            sqlite_conn.close()
+            # Guarded because sqlite3.connect itself can raise -- a missing
+            # file, a permissions problem, a corrupt database. The name is then
+            # unbound and this finally raised UnboundLocalError ON TOP of the
+            # real failure, so the caller was told "cannot access local
+            # variable" instead of "unable to open database file". A cleanup
+            # handler must not be able to destroy the diagnosis.
+            if sqlite_conn is not None:
+                sqlite_conn.close()
 
         return stats
 
@@ -314,6 +322,10 @@ class SearchIndexMigrator:
             print(f"Connecting to pgvector collection: {collection_name}")
 
         pgvector = PgVectorBackend(connection_string)
+        # Bound before the try so the finally can never raise NameError over
+        # the top of a real failure -- the same defect this commit fixes for
+        # sqlite_conn in migrate_sqlite_to_pgvector.
+        sqlite_out = None
 
         try:
             # Get collection stats and config
@@ -336,6 +348,7 @@ class SearchIndexMigrator:
 
             conn = sqlite3.connect(output_path)
             cursor = conn.cursor()
+            sqlite_out = conn  # closed in the finally below, not inline
 
             # Create schema (matching index_builder.py)
             cursor.execute("""
@@ -425,9 +438,17 @@ class SearchIndexMigrator:
                 print("This feature is planned for future development.")
 
             conn.commit()
-            conn.close()
 
         finally:
+            # The inline conn.close() above only ran when everything succeeded,
+            # while this finally closed pgvector alone -- so any failure between
+            # opening the file and committing leaked the SQLite handle and left
+            # a half-written .swsearch locked on Windows.
+            if sqlite_out is not None:
+                try:
+                    sqlite_out.close()
+                except Exception:  # cleanup must not mask the real error
+                    logger.warning("Could not close SQLite output file", exc_info=True)
             pgvector.close()
 
         return stats
@@ -449,21 +470,27 @@ class SearchIndexMigrator:
             info["type"] = "sqlite"
             info["path"] = index_path
 
+            # try/finally rather than a trailing close(): a corrupt or
+            # partially written index makes any of these statements raise, and
+            # the handle would otherwise be held until GC -- which on Windows
+            # keeps the file locked against the very repair the caller is
+            # probably attempting.
             conn = sqlite3.connect(index_path)
-            cursor = conn.cursor()
-
-            # Get config
-            cursor.execute("SELECT key, value FROM config")
-            info["config"] = dict(cursor.fetchall())
+            try:
+                cursor = conn.cursor()
 
-            # Get stats
-            cursor.execute("SELECT COUNT(*) FROM chunks")
-            info["total_chunks"] = cursor.fetchone()[0]
+                # Get config
+                cursor.execute("SELECT key, value FROM config")
+                info["config"] = dict(cursor.fetchall())
 
-            cursor.execute("SELECT COUNT(DISTINCT filename) FROM chunks")
-            info["total_files"] = cursor.fetchone()[0]
+                # Get stats
+                cursor.execute("SELECT COUNT(*) FROM chunks")
+                info["total_chunks"] = cursor.fetchone()[0]
 
-            conn.close()
+                cursor.execute("SELECT COUNT(DISTINCT filename) FROM chunks")
+                info["total_files"] = cursor.fetchone()[0]
+            finally:
+                conn.close()
 
         else:
             info["type"] = "unknown"

{signalwire_sdk-3.4.0.dev110 → signalwire_sdk-3.4.1.dev111}/signalwire/signalwire/search/pgvector_backend.py

@@ -135,11 +135,32 @@ class PgVectorBackend:
             )
 
             # Create indexes
+            #
+            # HNSW, not IVFFlat. IVFFlat partitions into `lists` clusters and
+            # visits `probes` of them, which has two costs measured on a 21k-row
+            # SignalWire collection at lists=100:
+            #
+            #   - recall is capped by how many lists you dare probe, and the
+            #     ceiling is a CLIFF, not a curve: at probes=50 the planner
+            #     decides half the index costs more than the table, drops to a
+            #     Seq Scan, and latency goes 10ms -> 113ms for +6 points. There
+            #     is nothing available in between.
+            #   - re-clustering on every rebuild moves which chunks a given
+            #     probes value can reach. Rebuilding the index alone, with no
+            #     corpus change, swung recall@1 on one question class by 15
+            #     points, which makes before/after measurement across a rebuild
+            #     nearly worthless.
+            #
+            # HNSW has neither. Measured through the full hybrid pipeline over a
+            # 360-case golden set, HNSW ef_search=200 against IVFFlat probes=30:
+            # recall@1 64%->67%, recall@5 79%->84%, wrong-answer rate 25%->22%,
+            # end-to-end search latency 72ms->66ms, and no question class worse.
+            # Rebuilding the HNSW index from scratch reproduced every number to
+            # within 2 points, against IVFFlat's 15.
             cursor.execute(
                 psycopg2_sql.SQL("""
                 CREATE INDEX IF NOT EXISTS {idx}
-                ON {tbl} USING ivfflat (embedding vector_cosine_ops)
-                WITH (lists = 100)
+                ON {tbl} USING hnsw (embedding vector_cosine_ops)
             """).format(idx=idx_embedding, tbl=tbl)
             )
 
@@ -628,8 +649,23 @@ class PgVectorSearchBackend:
     ) -> list[dict[str, Any]]:
         """Perform vector similarity search"""
         with self.conn.cursor() as cursor:
-            # Set probes for IVFFlat index to ensure we get enough results
-            cursor.execute("SET LOCAL ivfflat.probes = %s", (max(count, 10),))
+            # Set probes for IVFFlat index to ensure we get enough results.
+            #
+            # NOT "SET LOCAL". _connect() enables autocommit - see the docstring
+            # there, it is deliberate, to avoid holding locks that block
+            # DROP TABLE during reindex. Under autocommit every statement is its
+            # own transaction, so a transaction-scoped SET LOCAL is discarded
+            # before the SELECT below ever runs and the index falls back to the
+            # default probes=1. On a lists=100 index that reads 1% of the table:
+            # measured vector recall@5 was 25% at probes=1 against 55% with
+            # probes applied, for ~2ms. Plain SET is session-scoped, survives
+            # autocommit, and opens no transaction of its own.
+            # Both are set because both index types are in the wild: collections
+            # built before the HNSW switch still carry an IVFFlat index and
+            # would silently fall back to probes=1 if only ef_search were set.
+            # Each GUC is inert against the other index type.
+            cursor.execute("SET ivfflat.probes = %s", (max(count, 10),))
+            cursor.execute("SET hnsw.ef_search = %s", (max(count * 6, 200),))
             # Build query parts
             tbl = psycopg2_sql.Identifier(self.table_name)
             parts = [
@@ -1044,6 +1080,58 @@ class PgVectorSearchBackend:
 
         return list(candidates.values())
 
+    # Non-semantic signals may reorder results; they may not choose them.
+    #
+    # Every source used to feed one pool -- base = max(all signals) + 0.1 per
+    # agreeing source -- but the signals are not measured on the same scale.
+    # Cosine similarity is bounded by what the embedding model can express and
+    # tops out near 0.62 on a real corpus. Metadata term coverage maxes at 0.60
+    # by construction, a basename hit is a flat 0.67, and both collect the same
+    # agreement boost. A constant therefore outranks a similarity by design.
+    #
+    # Measured on "play audio to the caller": call-flow-builder/gather-input,
+    # cosine 0.555, scored 0.800 and took rank 1 over swml/reference/calling/play
+    # at 0.620. A page about GATHERING INPUT answered a question about PLAYING
+    # AUDIO, because term coverage saturated where the vector could not.
+    #
+    # Normalising the constants into the cosine range was the other option and
+    # it is worse: that range moves with the corpus and the embedding model, so
+    # the calibration would rot silently. This fails safe instead. A chunk the
+    # vector search actually found keeps its cosine as the score and earns at
+    # most TIEBREAK_MAX from agreement -- enough to order near-ties, never enough
+    # to leapfrog a materially better match. A chunk the vector search never
+    # returned is mapped into the band below the weakest semantic hit: still
+    # reachable, still ordered among its peers, but it cannot take the top from
+    # a page that is genuinely closer to the question.
+    TIEBREAK_MAX = 0.05
+
+    def _blend(
+        self,
+        all_sources: dict[Any, dict[str, float]],
+        results_map: dict[Any, dict[str, Any]],
+        agreement_boost: float,
+    ) -> None:
+        # max, not min: vector search returns `count` rows, so the weakest one
+        # is the count-th best cosine and a floor built from it would move with
+        # `count` -- making the same candidate score differently depending on
+        # how many results were asked for. The best score does not move.
+        vector_scores = [s["vector"] for s in all_sources.values() if "vector" in s]
+        ceiling = max(vector_scores) if vector_scores else None
+        for chunk_id, result in results_map.items():
+            sources = all_sources[chunk_id]
+            if "vector" in sources:
+                boost = agreement_boost * (len(sources) - 1)
+                score = sources["vector"] + min(self.TIEBREAK_MAX, boost)
+            else:
+                base = max(sources.values())
+                # Scale into [0, ceiling) so ordering survives but the top does
+                # not. Without any vector result there is nothing to rank against,
+                # so keep the old behaviour rather than invent a floor.
+                score = base * ceiling * 0.99 if ceiling is not None else base
+            result["score"] = min(1.0, score)
+            result["sources"] = sources
+            result["final_score"] = result["score"]
+
     def _merge_results(
         self,
         vector_results: list[dict[str, Any]],
@@ -1073,13 +1161,7 @@ class PgVectorSearchBackend:
                 results_map[chunk_id] = result.copy()
             all_sources.setdefault(chunk_id, {})["keyword"] = result["score"]
 
-        # Score: max signal wins, boost for agreement
-        for chunk_id, result in results_map.items():
-            sources = all_sources[chunk_id]
-            scores = list(sources.values())
-            base = max(scores)
-            boost = agreement_boost * (len(scores) - 1)
-            result["score"] = min(1.0, base + boost)
+        self._blend(all_sources, results_map, agreement_boost)
 
         merged = list(results_map.values())
         merged.sort(key=lambda x: x["score"], reverse=True)
@@ -1123,15 +1205,7 @@ class PgVectorSearchBackend:
                 results_map[chunk_id] = result.copy()
             all_sources.setdefault(chunk_id, {})["metadata"] = result["score"]
 
-        # Score: max signal wins, boost for each additional agreeing source
-        for chunk_id, result in results_map.items():
-            sources = all_sources[chunk_id]
-            scores = list(sources.values())
-            base = max(scores)
-            boost = agreement_boost * (len(scores) - 1)
-            result["score"] = min(1.0, base + boost)
-            result["sources"] = sources
-            result["final_score"] = result["score"]
+        self._blend(all_sources, results_map, agreement_boost)
 
         merged = list(results_map.values())
         merged.sort(key=lambda x: x["score"], reverse=True)