pgvector-template 0.4__tar.gz → 0.5__tar.gz

{pgvector_template-0.4 → pgvector_template-0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgvector-template
-Version: 0.4
+Version: 0.5
 Summary: Template library for flexible PGVector RAG implementations
 Author-email: DL <v49t9zpqd@mozmail.com>
 License: MIT

{pgvector_template-0.4 → pgvector_template-0.5}/pgvector_template/core/search.py

@@ -69,38 +69,43 @@ class BaseSearchClient:
             query: Search query containing text, metadata filters, and pagination.
 
         Returns:
-            List of retrieval results matching the search criteria.
+            List of retrieval results matching the search criteria. Each result's `score`
+            is a float in [0, 1] when `query.text` is set (1.0 = most similar), or `None`
+            for keyword/metadata-only queries.
         """
-        db_query = select(self.config.document_cls)
+        distance_expr: ColumnElement | None = None
 
         if query.text:
-            db_query = self._apply_semantic_search(db_query, query)
+            distance_expr = self._build_distance_expr(query)
+            db_query = select(self.config.document_cls, distance_expr).order_by(distance_expr)
+        else:
+            db_query = select(self.config.document_cls)
+
         db_query = self._apply_keyword_search(db_query, query)
         if query.metadata_filters:
             db_query = self._apply_metadata_filters(db_query, query)
         db_query = db_query.limit(query.limit)
 
-        # execute query and return results
-        results = self.session.scalars(db_query).all()
-        return self._convert_to_retrieval_results(results)
+        if distance_expr is not None:
+            rows = self.session.execute(db_query).all()
+            return self._convert_to_retrieval_results(rows)
+        else:
+            results = self.session.scalars(db_query).all()
+            return self._convert_to_retrieval_results([(doc, None) for doc in results])
 
-    def _apply_semantic_search(self, db_query: Select, search_query: SearchQuery) -> Select:
-        """Apply semantic (vector) search criteria to the query.
-        `embedding_provider` must be provided at instantiation, or an `ValueError` will be raised.
-        In PGVector, `<=>` operator is used to compare cosine distance. Lower = more similar.
+    def _build_distance_expr(self, search_query: SearchQuery) -> ColumnElement:
+        """Build a labeled cosine-distance expression for the given query text.
 
-        Args:
-            query: The base SQLAlchemy query.
-            search_query: The search query containing the text to search for.
+        `embedding_provider` must be provided at instantiation, or a `ValueError` is raised.
+        In PGVector, `<=>` computes cosine distance (0 = identical, up to 2 = opposite).
 
         Returns:
-            Updated SQLAlchemy query with semantic search applied.
+            A SQLAlchemy labeled column expression suitable for SELECT and ORDER BY.
         """
-        if not search_query.text:
-            return db_query
+        assert search_query.text is not None
         query_embedding = self.embedding_provider.embed_text(search_query.text)
-        return db_query.order_by(
-            self.config.document_cls.embedding.cosine_distance(query_embedding)
+        return self.config.document_cls.embedding.cosine_distance(query_embedding).label(
+            "_score_distance"
         )
 
     def _apply_keyword_search(self, db_query: Select, search_query: SearchQuery) -> Select:
@@ -199,16 +204,18 @@ class BaseSearchClient:
             raise ValueError(f"Unsupported condition: {filter_obj.condition}")
 
     def _convert_to_retrieval_results(self, results: Sequence[Any]) -> list[RetrievalResult]:
-        """Convert database results to RetrievalResult objects.
+        """Convert (document, distance | None) pairs to RetrievalResult objects.
 
         Args:
-            results: Raw database results.
-            search_query: The original search query.
+            results: Sequence of (document, cosine_distance) tuples. Pass distance=None
+                     for keyword/metadata-only queries that have no semantic ranking.
 
         Returns:
-            List of RetrievalResult objects.
+            List of RetrievalResult objects with score = max(0.0, 1.0 - distance),
+            or score=None when distance is None.
         """
         retrieval_results = []
-        for result in results:
-            retrieval_results.append(RetrievalResult(document=result, score=1.0))
+        for document, distance in results:
+            score = max(0.0, 1.0 - distance / 2.0) if distance is not None else None
+            retrieval_results.append(RetrievalResult(document=document, score=score))
         return retrieval_results

{pgvector_template-0.4 → pgvector_template-0.5}/pgvector_template/models/search.py

@@ -1,5 +1,4 @@
 from dataclasses import dataclass, asdict
-from datetime import datetime
 from typing import Any, Literal
 
 from pydantic import BaseModel, ConfigDict, Field, model_validator
@@ -38,7 +37,13 @@ class SearchQuery(BaseModel):
     text: str | None = None
     """String to match against using in a semantic search, i.e. using vector distance."""
     keywords: list[str] = []
-    """List of keywords to **exact-match** in a keyword search."""
+    """
+    List of keywords for a case-insensitive **substring** search (SQL `ILIKE '%keyword%'`).
+    An entry matches if **any** keyword appears anywhere in its content (OR-combined).
+    Pass multiple variants, synonyms, or spellings to increase recall — e.g.
+    ["run", "running", "ran"] will match entries containing any of those forms.
+    Note: substring matching means "cat" also matches "category"; prefer distinctive stems.
+    """
     metadata_filters: list[MetadataFilter] = Field(
         default=[],
         json_schema_extra={"metadata_schema": BaseDocumentMetadata.model_json_schema()},
@@ -47,8 +52,6 @@ class SearchQuery(BaseModel):
     List of metadata conditions that must be matched.
     Refer to `metadata_schema` for the expected schema, as it exists in the database.
     """
-    date_range: tuple[datetime, datetime] | None = None
-    """Retrieve/limit results based on created_at & updated_at timestamps (i.e. database operations)"""
     limit: int = Field(
         ...,
         ge=1,
@@ -62,7 +65,7 @@ class SearchQuery(BaseModel):
 
     @model_validator(mode="after")
     def ensure_criterion(self):
-        if not any([self.text, self.keywords, self.metadata_filters, self.date_range]):
+        if not any([self.text, self.keywords, self.metadata_filters]):
             raise ValueError("At least one search criterion is required")
         return self
 
@@ -72,7 +75,12 @@ class RetrievalResult:
     """Standardized result structure for all retrieval operations"""
 
     document: BaseDocument
-    score: float
+    score: float | None
+    """
+    Semantic similarity score in [0, 1] when a `text` query was provided (1.0 = identical,
+    0.0 = maximally distant). `None` when the search had no semantic component (keywords /
+    metadata filters only) — results are still filtered correctly but have no meaningful ranking.
+    """
 
     def to_dict(self) -> dict[str, Any]:
         return asdict(self)

{pgvector_template-0.4 → pgvector_template-0.5}/pgvector_template.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pgvector-template
-Version: 0.4
+Version: 0.5
 Summary: Template library for flexible PGVector RAG implementations
 Author-email: DL <v49t9zpqd@mozmail.com>
 License: MIT

{pgvector_template-0.4 → pgvector_template-0.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "pgvector-template"
-version = "0.4"
+version = "0.5"
 description = "Template library for flexible PGVector RAG implementations"
 authors = [{ name="DL", email="v49t9zpqd@mozmail.com" }]
 license = { text = "MIT" }