Documenting why we drop embeddings (#995)

Co-authored-by: Copilot <[email protected]>

Author: jamesbraza

paperqa/agents/models.py

@@ -72,7 +72,7 @@ def strip_answer(
     ) -> PQASession:
         # This modifies in place, this is fine
         # because when a response is being constructed,
-        # we should be done with the Answer object
+        # we should be done with the PQASession object
         v.filter_content_for_user()
         return v
 

paperqa/core.py

@@ -209,9 +209,12 @@ async def map_fxn_summary(
             context=context,
             question=question,
             text=Text(
-                text=text.text,
-                name=text.name,
+                # Embeddings enable the retrieval of Texts to make Contexts.
+                # Once we already have Contexts, we filter them by score
+                # (and not the underlying Text's embeddings),
+                # so embeddings can be safely dropped from the deepcopy
                 doc=text.doc.model_dump(exclude={"embedding"}),
+                **text.model_dump(exclude={"embedding", "doc"}),
             ),
             score=score,  # pylint: disable=possibly-used-before-assignment
             **extras,

paperqa/types.py

@@ -289,16 +289,23 @@ def get_unique_docs_from_contexts(self, score_threshold: int = 0) -> set[Doc]:
         }
 
     def filter_content_for_user(self) -> None:
-        """Filter out extra items (inplace) that do not need to be returned to the user."""
+        """
+        In-place filter/drop items that are irrelevant to the user.
+
+        This is mainly done to keep HTTP requests reasonably sized.
+        """
         self.contexts = [
             Context(
                 # Dump all fields from the original context (including extras),
                 # but exclude 'text' so we can replace it below.
                 **c.model_dump(exclude={"text"}),
                 text=Text(
                     text="",
-                    **c.text.model_dump(exclude={"text", "embedding", "doc"}),
+                    # Similar to the explanation in `map_fxn_summary`'s internals
+                    # on why we drop embeddings, drop embeddings here too because
+                    # embeddings aren't displayed to front end users
                     doc=c.text.doc.model_dump(exclude={"embedding"}),
+                    **c.text.model_dump(exclude={"text", "embedding", "doc"}),
                 ),
             )
             for c in self.contexts