aiagents4pharma 1.30.1__py3-none-any.whl → 1.30.2__py3-none-any.whl

aiagents4pharma/talk2scholars/agents/zotero_agent.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 """
-Agent for interacting with Zotero
+Agent for interacting with Zotero with human-in-the-loop features
 """
 
 import logging
@@ -13,8 +13,9 @@ from langgraph.graph import START, StateGraph
 from langgraph.prebuilt import create_react_agent, ToolNode
 from langgraph.checkpoint.memory import MemorySaver
 from ..state.state_talk2scholars import Talk2Scholars
-from ..tools.zotero.zotero_read import zotero_search_tool
-from ..tools.zotero.zotero_write import zotero_save_tool
+from ..tools.zotero.zotero_read import zotero_read
+from ..tools.zotero.zotero_review import zotero_review
+from ..tools.zotero.zotero_write import zotero_write
 from ..tools.s2.display_results import display_results as s2_display
 from ..tools.s2.query_results import query_results as s2_query_results
 from ..tools.s2.retrieve_semantic_scholar_paper_id import (
@@ -32,7 +33,7 @@ def get_app(uniq_id, llm_model: BaseChatModel):
 
     This function sets up the Zotero agent, which integrates various tools to search,
     retrieve, and display research papers from Zotero. The agent follows the ReAct
-    pattern for structured interaction.
+    pattern for structured interaction and includes human-in-the-loop features.
 
     Args:
         uniq_id (str): Unique identifier for the current conversation session.
@@ -87,11 +88,12 @@ def get_app(uniq_id, llm_model: BaseChatModel):
     # Define the tools
     tools = ToolNode(
         [
-            zotero_search_tool,
+            zotero_read,
             s2_display,
             s2_query_results,
             retrieve_semantic_scholar_paper_id,
-            zotero_save_tool,
+            zotero_review,  # First review
+            zotero_write,  # Then save with user confirmation
         ]
     )
 
@@ -104,7 +106,7 @@ def get_app(uniq_id, llm_model: BaseChatModel):
         tools=tools,
         state_schema=Talk2Scholars,
         prompt=cfg.zotero_agent,
-        checkpointer=MemorySaver(),
+        checkpointer=MemorySaver(),  # Required for interrupts to work
     )
 
     workflow = StateGraph(Talk2Scholars)

aiagents4pharma/talk2scholars/configs/agents/talk2scholars/zotero_agent/default.yaml

@@ -1,19 +1,13 @@
 target: agents.zotero_agent.get_app
 zotero_agent: >
-  You are a specialized Zotero library agent with access to tools for paper retrieval and management.
+  You are a knowledgeable research assistant with expertise in academic literature.
+  Your goal is to help users find, manage, and save relevant research papers and display them.
 
-  AVAILABLE TOOLS:
-  1. zotero_search_tool - Search and retrieve papers from Zotero library
-  2. display_results - Display the papers retrieved by other tools
-  3. query_results - Ask questions about the current set of papers
-  4. retrieve_semantic_scholar_paper_id - Get Semantic Scholar ID for a paper title for the papers from zotero library
-  5. zotero_write - Save paper to users zotero library under specfied collections
+  When saving papers to Zotero:
+  1. First use zotero_review with the collection path.
+  2. Wait for user confirmation (they must say "Yes" or "Approve").
+  3. Use zotero_write with both the collection_path and user_confirmation and call `s2_display` tool after the papers as saved.
 
-
-  WORKFLOW STEPS
-  1. When user requests papers, use `zotero_search_tool` to find papers
-  2. Use `display_results` tool to display the response
-  3. Use `query_results` tool to query over the selected paper only when the user asks to
-  4. Use `retrieve_semantic_scholar_paper_id` to get the semantic scholar id of a paper title for the papers from zotero library
-  5. Use `zotero_write` to save the papers to users zotero library under collections and call `display_results` only after you recive
-     the save was successfull
+  IMPORTANT: Human approval is required for saving papers to Zotero. Never save papers
+  without explicit approval from the user. Always respect the user's decision if they
+  choose not to save papers.

aiagents4pharma/talk2scholars/configs/tools/zotero_write/default.yaml

@@ -0,0 +1,55 @@
+# Default configuration for Zotero search tool
+library_type: "user" # Type of library ('user' or 'group')
+default_limit: 2
+request_timeout: 10
+user_id: ${oc.env:ZOTERO_USER_ID} # Load from environment variable
+api_key: ${oc.env:ZOTERO_API_KEY} # Load from environment variable
+
+# Default search parameters
+search_params:
+  limit: ${.default_limit}
+
+# Item Types and Limit
+zotero:
+  max_limit: 100
+  filter_item_types:
+    [
+      "Artwork",
+      "Audio Recording",
+      "Bill",
+      "Blog Post",
+      "Book",
+      "Book Section",
+      "Case",
+      "Conference Paper",
+      "Dataset",
+      "Dictionary Entry",
+      "Document",
+      "E-mail",
+      "Encyclopedia Article",
+      "Film",
+      "Forum Post",
+      "Hearing",
+      "Instant Message",
+      "Interview",
+      "Journal Article",
+      "Letter",
+      "Magazine Article",
+      "Manuscript",
+      "Map",
+      "Newspaper Article",
+      "Patent",
+      "Podcast",
+      "Preprint",
+      "Presentation",
+      "Radio Broadcast",
+      "Report",
+      "Software",
+      "Standard",
+      "Statute",
+      "Thesis",
+      "TV Broadcast",
+      "Video Recording",
+      "Web Page",
+    ]
+  # filter_excluded_types: ["attachment", "note", "annotation"]

aiagents4pharma/talk2scholars/state/state_talk2scholars.py

@@ -54,6 +54,8 @@ class Talk2Scholars(AgentState):
         papers (Dict[str, Any]): Stores the research papers retrieved from the agent's queries.
         multi_papers (Dict[str, Any]): Stores multiple recommended papers from various sources.
         zotero_read (Dict[str, Any]): Stores the papers retrieved from Zotero.
+        zotero_write_approval_status (Dict[str, Any]): Stores the approval status and collection
+        path for Zotero save operations.
         llm_model (BaseChatModel): The language model instance used for generating responses.
         text_embedding_model (Embeddings): The text embedding model used for
         similarity calculations.
@@ -65,5 +67,6 @@ class Talk2Scholars(AgentState):
     multi_papers: Annotated[Dict[str, Any], replace_dict]
     pdf_data: Annotated[Dict[str, Any], replace_dict]
     zotero_read: Annotated[Dict[str, Any], replace_dict]
+    zotero_write_approval_status: Annotated[Dict[str, Any], replace_dict]
     llm_model: BaseChatModel
     text_embedding_model: Embeddings

aiagents4pharma/talk2scholars/tests/test_routing_logic.py

@@ -22,6 +22,7 @@ def mock_router():
     """Creates a mock supervisor router that routes based on keyword matching."""
 
     def mock_supervisor_node(state):
+        """Mock supervisor node that routes based on keyword matching."""
         query = state["messages"][-1].content.lower()
         # Define keywords for each sub-agent.
         s2_keywords = [
@@ -70,6 +71,4 @@ def test_routing_logic(mock_state, mock_router, user_query, expected_agent):
     mock_state["messages"].append(HumanMessage(content=user_query))
     result = mock_router(mock_state)
 
-    print(f"\nDEBUG: Query '{user_query}' routed to: {result.goto}")
-
     assert result.goto == expected_agent, f"Failed for query: {user_query}"

aiagents4pharma/talk2scholars/tests/test_zotero_agent.py

@@ -10,7 +10,8 @@ from langchain_openai import ChatOpenAI
 from ..agents.zotero_agent import get_app
 from ..state.state_talk2scholars import Talk2Scholars
 
-LLM_MODEL = ChatOpenAI(model='gpt-4o-mini', temperature=0)
+LLM_MODEL = ChatOpenAI(model="gpt-4o-mini", temperature=0)
+
 
 @pytest.fixture(autouse=True)
 def mock_hydra_fixture():
@@ -39,7 +40,7 @@ def mock_tools_fixture():
             "retrieve_semantic_scholar_paper_id"
         ) as mock_s2_retrieve_id,
         mock.patch(
-            "aiagents4pharma.talk2scholars.tools.zotero.zotero_read.zotero_search_tool"
+            "aiagents4pharma.talk2scholars.tools.zotero.zotero_read.zotero_read"
         ) as mock_zotero_query_results,
     ):
         mock_s2_display.return_value = {"result": "Mock Display Result"}

aiagents4pharma/talk2scholars/tests/test_zotero_human_in_the_loop.py

@@ -0,0 +1,273 @@
+"""
+Unit tests for Zotero human in the loop in zotero_review.py with structured output.
+"""
+
+import unittest
+from unittest.mock import patch, MagicMock
+from aiagents4pharma.talk2scholars.tools.zotero.zotero_review import zotero_review
+
+
+class TestZoteroReviewTool(unittest.TestCase):
+    """Test class for Zotero review tool with structured LLM output."""
+
+    def setUp(self):
+        self.tool_call_id = "tc"
+        self.collection_path = "/Col"
+        # Create a sample fetched papers dictionary with one paper.
+        self.sample_papers = {"p1": {"Title": "T1", "Authors": ["A1", "A2", "A3"]}}
+
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.fetch_papers_for_save",
+        return_value=None,
+    )
+    def test_no_fetched_papers(self, mock_fetch):
+        """Test when no fetched papers are found."""
+        with self.assertRaises(ValueError) as context:
+            zotero_review.run(
+                {
+                    "tool_call_id": self.tool_call_id,
+                    "collection_path": self.collection_path,
+                    "state": {},
+                }
+            )
+        self.assertIn("No fetched papers were found to save", str(context.exception))
+        mock_fetch.assert_called_once()
+
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.fetch_papers_for_save",
+        return_value={"p1": {"Title": "T1", "Authors": ["A1", "A2"]}},
+    )
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.interrupt",
+        return_value="dummy_response",
+    )
+    def test_missing_llm_model(self, mock_interrupt, mock_fetch):
+        """Test when LLM model is not available in state, expecting fallback confirmation."""
+        state = {"last_displayed_papers": self.sample_papers}  # llm_model missing
+        result = zotero_review.run(
+            {
+                "tool_call_id": self.tool_call_id,
+                "collection_path": self.collection_path,
+                "state": state,
+            }
+        )
+        upd = result.update
+        # The fallback message should start with "REVIEW REQUIRED:"
+        self.assertTrue(upd["messages"][0].content.startswith("REVIEW REQUIRED:"))
+        # Check that the approval status is set as fallback values.
+        approval = upd["zotero_write_approval_status"]
+        self.assertEqual(approval["collection_path"], self.collection_path)
+        self.assertTrue(approval["papers_reviewed"])
+        self.assertFalse(approval["approved"])
+        self.assertEqual(approval["papers_count"], len(self.sample_papers))
+        mock_fetch.assert_called_once()
+        mock_interrupt.assert_called_once()
+
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.fetch_papers_for_save",
+        return_value={"p1": {"Title": "T1", "Authors": ["A1", "A2"]}},
+    )
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.interrupt",
+        return_value="dummy_response",
+    )
+    def test_human_approve(self, mock_interrupt, mock_fetch):
+        """Test when human approves saving papers using structured output."""
+        # Prepare a fake llm_model with structured output.
+        fake_structured_llm = MagicMock()
+        # Simulate invoke() returns an object with decision "approve"
+        fake_decision = MagicMock()
+        fake_decision.decision = "approve"
+        fake_structured_llm.invoke.return_value = fake_decision
+
+        fake_llm_model = MagicMock()
+        fake_llm_model.with_structured_output.return_value = fake_structured_llm
+
+        state = {
+            "last_displayed_papers": self.sample_papers,
+            "llm_model": fake_llm_model,
+        }
+
+        result = zotero_review.run(
+            {
+                "tool_call_id": self.tool_call_id,
+                "collection_path": self.collection_path,
+                "state": state,
+            }
+        )
+
+        upd = result.update
+        self.assertEqual(
+            upd["zotero_write_approval_status"],
+            {"collection_path": self.collection_path, "approved": True},
+        )
+        self.assertIn(
+            f"Human approved saving 1 papers to Zotero collection '{self.collection_path}'",
+            upd["messages"][0].content,
+        )
+        mock_fetch.assert_called_once()
+        mock_interrupt.assert_called_once()
+
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.fetch_papers_for_save",
+        return_value={"p1": {"Title": "T1", "Authors": ["A1", "A2"]}},
+    )
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.interrupt",
+        return_value="dummy_response",
+    )
+    def test_human_approve_custom(self, mock_interrupt, mock_fetch):
+        """Test when human approves with a custom collection path."""
+        fake_structured_llm = MagicMock()
+        fake_decision = MagicMock()
+        fake_decision.decision = "custom"
+        fake_decision.custom_path = "/Custom"
+        fake_structured_llm.invoke.return_value = fake_decision
+
+        fake_llm_model = MagicMock()
+        fake_llm_model.with_structured_output.return_value = fake_structured_llm
+
+        state = {
+            "last_displayed_papers": self.sample_papers,
+            "llm_model": fake_llm_model,
+        }
+
+        result = zotero_review.run(
+            {
+                "tool_call_id": self.tool_call_id,
+                "collection_path": self.collection_path,
+                "state": state,
+            }
+        )
+
+        upd = result.update
+        self.assertEqual(
+            upd["zotero_write_approval_status"],
+            {"collection_path": "/Custom", "approved": True},
+        )
+        self.assertIn(
+            "Human approved saving papers to custom Zotero collection '/Custom'",
+            upd["messages"][0].content,
+        )
+        mock_fetch.assert_called_once()
+        mock_interrupt.assert_called_once()
+
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.fetch_papers_for_save",
+        return_value={"p1": {"Title": "T1", "Authors": ["A1", "A2"]}},
+    )
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.interrupt",
+        return_value="dummy_response",
+    )
+    def test_human_reject(self, mock_interrupt, mock_fetch):
+        """Test when human rejects saving papers via structured output."""
+        fake_structured_llm = MagicMock()
+        fake_decision = MagicMock()
+        fake_decision.decision = "reject"
+        fake_structured_llm.invoke.return_value = fake_decision
+
+        fake_llm_model = MagicMock()
+        fake_llm_model.with_structured_output.return_value = fake_structured_llm
+
+        state = {
+            "last_displayed_papers": self.sample_papers,
+            "llm_model": fake_llm_model,
+        }
+
+        result = zotero_review.run(
+            {
+                "tool_call_id": self.tool_call_id,
+                "collection_path": self.collection_path,
+                "state": state,
+            }
+        )
+
+        upd = result.update
+        self.assertEqual(upd["zotero_write_approval_status"], {"approved": False})
+        self.assertIn(
+            "Human rejected saving papers to Zotero", upd["messages"][0].content
+        )
+        mock_fetch.assert_called_once()
+        mock_interrupt.assert_called_once()
+
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.fetch_papers_for_save"
+    )
+    @patch("aiagents4pharma.talk2scholars.tools.zotero.zotero_review.interrupt")
+    def test_structured_processing_failure(self, mock_interrupt, mock_fetch):
+        """Test fallback when structured review processing fails."""
+        # Simulate valid fetched papers with multiple entries.
+        papers = {
+            f"p{i}": {"Title": f"Title{i}", "Authors": [f"A{i}"]} for i in range(1, 8)
+        }
+        mock_fetch.return_value = papers
+        mock_interrupt.return_value = "dummy_response"
+        # Provide a fake llm_model whose invoke() raises an exception.
+        fake_structured_llm = MagicMock()
+        fake_structured_llm.invoke.side_effect = Exception("structured error")
+        fake_llm_model = MagicMock()
+        fake_llm_model.with_structured_output.return_value = fake_structured_llm
+
+        state = {"last_displayed_papers": papers, "llm_model": fake_llm_model}
+
+        result = zotero_review.run(
+            {
+                "tool_call_id": self.tool_call_id,
+                "collection_path": "/MyCol",
+                "state": state,
+            }
+        )
+
+        upd = result.update
+        content = upd["messages"][0].content
+        # The fallback message should start with "REVIEW REQUIRED:".
+        self.assertTrue(content.startswith("REVIEW REQUIRED:"))
+        self.assertIn("Would you like to save 7 papers", content)
+        self.assertIn("... and 2 more papers", content)
+
+        approved = upd["zotero_write_approval_status"]
+        self.assertEqual(approved["collection_path"], "/MyCol")
+        self.assertTrue(approved["papers_reviewed"])
+        self.assertFalse(approved["approved"])
+        self.assertEqual(approved["papers_count"], 7)
+
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.fetch_papers_for_save",
+        return_value={
+            "p1": {"Title": "Test Paper", "Authors": ["Alice", "Bob", "Charlie"]}
+        },
+    )
+    @patch(
+        "aiagents4pharma.talk2scholars.tools.zotero.zotero_review.interrupt",
+        return_value="dummy_response",
+    )
+    def test_authors_et_al_in_summary(self, mock_interrupt, mock_fetch):
+        """
+        Test that the papers summary includes 'et al.' when a paper has more than two authors.
+        This is achieved by forcing a fallback (structured processing failure) so that the fallback
+        message with the papers summary is generated.
+        """
+        # Create a fake llm_model whose structured output processing fails.
+        fake_structured_llm = MagicMock()
+        fake_structured_llm.invoke.side_effect = Exception("structured error")
+        fake_llm_model = MagicMock()
+        fake_llm_model.with_structured_output.return_value = fake_structured_llm
+
+        state = {
+            "last_displayed_papers": {
+                "p1": {"Title": "Test Paper", "Authors": ["Alice", "Bob", "Charlie"]}
+            },
+            "llm_model": fake_llm_model,
+        }
+        result = zotero_review.run(
+            {
+                "tool_call_id": self.tool_call_id,
+                "collection_path": self.collection_path,
+                "state": state,
+            }
+        )
+        fallback_message = result.update["messages"][0].content
+        self.assertIn("et al.", fallback_message)
+        mock_fetch.assert_called_once()
+        mock_interrupt.assert_called_once()