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

aiagents4pharma/talk2scholars/tools/zotero/__init__.py

@@ -5,3 +5,4 @@ Import statements
 from . import zotero_read
 from . import zotero_write
 from . import utils
+from . import zotero_review

aiagents4pharma/talk2scholars/tools/zotero/utils/zotero_path.py

@@ -9,6 +9,7 @@ import logging
 # Configure logging
 logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
+# pylint: disable=broad-exception-caught
 
 
 def get_item_collections(zot):
@@ -34,6 +35,7 @@ def get_item_collections(zot):
 
     # Build full paths for collections
     def build_collection_path(col_key):
+        """build collection path from collection key"""
         path = []
         while col_key:
             path.insert(0, collection_map.get(col_key, "Unknown"))
@@ -61,3 +63,126 @@ def get_item_collections(zot):
     logger.info("Successfully mapped items to collection paths.")
 
     return item_to_collections
+
+
+def find_or_create_collection(zot, path, create_missing=False):
+    """find collection or create if missing"""
+    logger.info(
+        "Finding collection for path: %s (create_missing=%s)", path, create_missing
+    )
+    # Normalize path: remove leading/trailing slashes and convert to lowercase
+    normalized = path.strip("/").lower()
+    path_parts = normalized.split("/") if normalized else []
+
+    if not path_parts:
+        logger.warning("Empty path provided")
+        return None
+
+    # Get all collections from Zotero
+    all_collections = zot.collections()
+    logger.info("Found %d collections in Zotero", len(all_collections))
+
+    # Determine target name (last part) and, if nested, find the parent's key
+    target_name = path_parts[-1]
+    parent_key = None
+    if len(path_parts) > 1:
+        parent_name = path_parts[-2]
+        # Look for a collection with name matching the parent (case-insensitive)
+        for col in all_collections:
+            if col["data"]["name"].lower() == parent_name:
+                parent_key = col["key"]
+                break
+
+    # Try to find an existing collection by direct match (ignoring hierarchy)
+    for col in all_collections:
+        if col["data"]["name"].lower() == target_name:
+            logger.info("Found direct match for %s: %s", target_name, col["key"])
+            return col["key"]
+
+    # No match found: create one if allowed
+    if create_missing:
+        payload = {"name": target_name}
+        if parent_key:
+            payload["parentCollection"] = parent_key
+        try:
+            result = zot.create_collection(payload)
+            # Interpret result based on structure
+            if "success" in result:
+                new_key = result["success"]["0"]
+            else:
+                new_key = result["successful"]["0"]["data"]["key"]
+            logger.info("Created collection %s with key %s", target_name, new_key)
+            return new_key
+        except Exception as e:
+            logger.error("Failed to create collection: %s", e)
+            return None
+    else:
+        logger.warning("No matching collection found for %s", target_name)
+        return None
+
+
+def get_all_collection_paths(zot):
+    """
+    Get all available collection paths in Zotero.
+
+    Args:
+        zot (Zotero): An initialized Zotero client.
+
+    Returns:
+        list: List of all available collection paths
+    """
+    logger.info("Getting all collection paths")
+    collections = zot.collections()
+
+    # Create mappings: collection key → name and collection key → parent key
+    collection_map = {col["key"]: col["data"]["name"] for col in collections}
+    parent_map = {
+        col["key"]: col["data"].get("parentCollection") for col in collections
+    }
+
+    # Build full paths for collections
+    def build_collection_path(col_key):
+        path = []
+        while col_key:
+            path.insert(0, collection_map.get(col_key, "Unknown"))
+            col_key = parent_map.get(col_key)
+        return "/" + "/".join(path)
+
+    collection_paths = [build_collection_path(key) for key in collection_map]
+    logger.info("Found %d collection paths", len(collection_paths))
+    return collection_paths
+
+
+def fetch_papers_for_save(state):
+    """
+    Retrieve papers from the state for saving to Zotero.
+
+    Args:
+        state (dict): The state containing previously fetched papers.
+
+    Returns:
+        dict: Dictionary of papers to save, or None if no papers found
+    """
+    logger.info("Fetching papers from state for saving")
+
+    # Retrieve last displayed papers from the agent state
+    last_displayed_key = state.get("last_displayed_papers", "")
+
+    if not last_displayed_key:
+        logger.warning("No last_displayed_papers key in state")
+        return None
+
+    if isinstance(last_displayed_key, str):
+        # If it's a string (key to another state object), get that object
+        fetched_papers = state.get(last_displayed_key, {})
+        logger.info("Using papers from '%s' state key", last_displayed_key)
+    else:
+        # If it's already the papers object
+        fetched_papers = last_displayed_key
+        logger.info("Using papers directly from last_displayed_papers")
+
+    if not fetched_papers:
+        logger.warning("No fetched papers found to save.")
+        return None
+
+    return fetched_papers

aiagents4pharma/talk2scholars/tools/zotero/zotero_read.py

@@ -13,9 +13,7 @@ from langchain_core.tools import tool
 from langchain_core.tools.base import InjectedToolCallId
 from langgraph.types import Command
 from pydantic import BaseModel, Field
-from aiagents4pharma.talk2scholars.tools.zotero.utils.zotero_path import (
-    get_item_collections,
-)
+from .utils.zotero_path import get_item_collections
 
 # pylint: disable=R0914,R0912,R0915
 
@@ -41,7 +39,7 @@ class ZoteroSearchInput(BaseModel):
 
 
 @tool(args_schema=ZoteroSearchInput, parse_docstring=True)
-def zotero_search_tool(
+def zotero_read(
     query: str,
     only_articles: bool,
     tool_call_id: Annotated[str, InjectedToolCallId],

aiagents4pharma/talk2scholars/tools/zotero/zotero_review.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python3
+
+"""
+This tool implements human-in-the-loop review for Zotero write operations.
+"""
+
+import logging
+from typing import Annotated, Any, Optional, Literal
+from langchain_core.tools import tool
+from langchain_core.messages import ToolMessage, HumanMessage
+from langchain_core.tools.base import InjectedToolCallId
+from langgraph.prebuilt import InjectedState
+from langgraph.types import Command, interrupt
+from pydantic import BaseModel, Field
+from .utils.zotero_path import fetch_papers_for_save
+
+# pylint: disable=R0914,R0911,R0912,R0915
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class ZoteroReviewDecision(BaseModel):
+    """
+    Structured output schema for the human review decision.
+    - decision: "approve", "reject", or "custom"
+    - custom_path: Optional custom collection path if the decision is "custom"
+    """
+
+    decision: Literal["approve", "reject", "custom"]
+    custom_path: Optional[str] = None
+
+
+class ZoteroReviewInput(BaseModel):
+    """Input schema for the Zotero review tool."""
+
+    tool_call_id: Annotated[str, InjectedToolCallId]
+    collection_path: str = Field(
+        description="The path where the paper should be saved in the Zotero library."
+    )
+    state: Annotated[dict, InjectedState]
+
+
+@tool(args_schema=ZoteroReviewInput, parse_docstring=True)
+def zotero_review(
+    tool_call_id: Annotated[str, InjectedToolCallId],
+    collection_path: str,
+    state: Annotated[dict, InjectedState],
+) -> Command[Any]:
+    """
+    Use this tool to get human review and approval before saving papers to Zotero.
+    This tool should be called before the zotero_write to ensure the user approves
+    the operation.
+
+    Args:
+        tool_call_id (str): The tool call ID.
+        collection_path (str): The Zotero collection path where papers should be saved.
+        state (dict): The state containing previously fetched papers.
+
+    Returns:
+        Command[Any]: The next action to take based on human input.
+    """
+    logger.info("Requesting human review for saving to collection: %s", collection_path)
+
+    # Use our utility function to fetch papers from state
+    fetched_papers = fetch_papers_for_save(state)
+
+    if not fetched_papers:
+        raise ValueError(
+            "No fetched papers were found to save. "
+            "Please retrieve papers using Zotero Read or Semantic Scholar first."
+        )
+
+    # Prepare papers summary for review
+    papers_summary = []
+    for paper_id, paper in list(fetched_papers.items())[
+        :5
+    ]:  # Limit to 5 papers for readability
+        logger.info("Paper ID: %s", paper_id)
+        title = paper.get("Title", "N/A")
+        authors = ", ".join(
+            [author.split(" (ID: ")[0] for author in paper.get("Authors", [])[:2]]
+        )
+        if len(paper.get("Authors", [])) > 2:
+            authors += " et al."
+        papers_summary.append(f"- {title} by {authors}")
+
+    if len(fetched_papers) > 5:
+        papers_summary.append(f"... and {len(fetched_papers) - 5} more papers")
+
+    papers_preview = "\n".join(papers_summary)
+    total_papers = len(fetched_papers)
+
+    # Prepare review information
+    review_info = {
+        "action": "save_to_zotero",
+        "collection_path": collection_path,
+        "total_papers": total_papers,
+        "papers_preview": papers_preview,
+        "message": (
+            f"Would you like to save {total_papers} papers to Zotero "
+            f"collection '{collection_path}'? Please respond with a structured decision "
+            f"using one of the following options: 'approve', 'reject', or 'custom' "
+            f"(with a custom_path)."
+        ),
+    }
+
+    try:
+        # Interrupt the graph to get human approval
+        human_review = interrupt(review_info)
+        # Process human response using structured output via LLM
+        llm_model = state.get("llm_model")
+        if llm_model is None:
+            raise ValueError("LLM model is not available in the state.")
+        structured_llm = llm_model.with_structured_output(ZoteroReviewDecision)
+        # Convert the raw human response to a message for structured parsing
+        decision_response = structured_llm.invoke(
+            [HumanMessage(content=str(human_review))]
+        )
+
+        # Process the structured response
+        if decision_response.decision == "approve":
+            logger.info("User approved saving papers to Zotero")
+            return Command(
+                update={
+                    "messages": [
+                        ToolMessage(
+                            content=(
+                                f"Human approved saving {total_papers} papers to Zotero "
+                                f"collection '{collection_path}'."
+                            ),
+                            tool_call_id=tool_call_id,
+                        )
+                    ],
+                    "zotero_write_approval_status": {
+                        "collection_path": collection_path,
+                        "approved": True,
+                    },
+                }
+            )
+        if decision_response.decision == "custom" and decision_response.custom_path:
+            logger.info(
+                "User approved with custom path: %s", decision_response.custom_path
+            )
+            return Command(
+                update={
+                    "messages": [
+                        ToolMessage(
+                            content=(
+                                f"Human approved saving papers to custom Zotero "
+                                f"collection '{decision_response.custom_path}'."
+                            ),
+                            tool_call_id=tool_call_id,
+                        )
+                    ],
+                    "zotero_write_approval_status": {
+                        "collection_path": decision_response.custom_path,
+                        "approved": True,
+                    },
+                }
+            )
+        logger.info("User rejected saving papers to Zotero")
+        return Command(
+            update={
+                "messages": [
+                    ToolMessage(
+                        content="Human rejected saving papers to Zotero.",
+                        tool_call_id=tool_call_id,
+                    )
+                ],
+                "zotero_write_approval_status": {"approved": False},
+            }
+        )
+        # pylint: disable=broad-except
+    except Exception as e:
+        # If interrupt or structured output processing fails, fallback to explicit confirmation
+        logger.warning("Structured review processing failed: %s", e)
+        return Command(
+            update={
+                "messages": [
+                    ToolMessage(
+                        content=(
+                            f"REVIEW REQUIRED: Would you like to save {total_papers} papers "
+                            f"to Zotero collection '{collection_path}'?\n\n"
+                            f"Papers to save:\n{papers_preview}\n\n"
+                            "Please respond with 'Yes' to confirm or 'No' to cancel."
+                        ),
+                        tool_call_id=tool_call_id,
+                    )
+                ],
+                "zotero_write_approval_status": {
+                    "collection_path": collection_path,
+                    "papers_reviewed": True,
+                    "approved": False,  # Not approved yet
+                    "papers_count": total_papers,
+                },
+            }
+        )

aiagents4pharma/talk2scholars/tools/zotero/zotero_write.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 
 """
-This tool is used to save fetched papers to Zotero library.
+This tool is used to save fetched papers to Zotero library after human approval.
 """
 
 import logging
@@ -14,11 +14,13 @@ from langchain_core.tools.base import InjectedToolCallId
 from langgraph.types import Command
 from langgraph.prebuilt import InjectedState
 from pydantic import BaseModel, Field
-from aiagents4pharma.talk2scholars.tools.zotero.utils.zotero_path import (
-    get_item_collections,
+from .utils.zotero_path import (
+    find_or_create_collection,
+    fetch_papers_for_save,
 )
 
-# pylint: disable=R0914,R0912,R0915
+
+# pylint: disable=R0914,R0911,R0912,R0915
 
 # Configure logging
 logging.basicConfig(level=logging.INFO)
@@ -30,29 +32,31 @@ class ZoteroSaveInput(BaseModel):
 
     tool_call_id: Annotated[str, InjectedToolCallId]
     collection_path: str = Field(
-        default=None,
-        description=(
-            "The path where the paper should be saved in the Zotero library."
-            "Example: '/machine/cern/mobile'"
-        ),
+        description="The path where the paper should be saved in the Zotero library."
     )
     state: Annotated[dict, InjectedState]
 
 
 @tool(args_schema=ZoteroSaveInput, parse_docstring=True)
-def zotero_save_tool(
+def zotero_write(
     tool_call_id: Annotated[str, InjectedToolCallId],
     collection_path: str,
     state: Annotated[dict, InjectedState],
 ) -> Command[Any]:
     """
     Use this tool to save previously fetched papers from Semantic Scholar
-    to a specified Zotero collection.
+    to a specified Zotero collection after human approval.
+
+    This tool checks if the user has approved the save operation via the
+    zotero_review. If approved, it will save the papers to the
+    approved collection path.
 
     Args:
         tool_call_id (Annotated[str, InjectedToolCallId]): The tool call ID.
         collection_path (str): The Zotero collection path where papers should be saved.
         state (Annotated[dict, InjectedState]): The state containing previously fetched papers.
+        user_confirmation (str, optional): User confirmation message when interrupt is
+        not available.
 
     Returns:
         Command[Any]: The save results and related information.
@@ -71,115 +75,44 @@ def zotero_save_tool(
     # Initialize Zotero client
     zot = zotero.Zotero(cfg.user_id, cfg.library_type, cfg.api_key)
 
-    # Retrieve last displayed papers from the agent state
-    last_displayed_key = state.get("last_displayed_papers", {})
-    if isinstance(last_displayed_key, str):
-        # If it's a string (key to another state object), get that object
-        fetched_papers = state.get(last_displayed_key, {})
-        logger.info("Using papers from '%s' state key", last_displayed_key)
-    else:
-        # If it's already the papers object
-        fetched_papers = last_displayed_key
-        logger.info("Using papers directly from last_displayed_papers")
+    # Use our utility function to fetch papers from state
+    fetched_papers = fetch_papers_for_save(state)
 
     if not fetched_papers:
-        logger.warning("No fetched papers found to save.")
-        raise RuntimeError(
-            "No fetched papers were found to save. Please retry the same query."
-        )
-
-    # First, check if zotero_read exists in state and has collection data
-    zotero_read_data = state.get("zotero_read", {})
-    logger.info("Retrieved zotero_read from state: %d items", len(zotero_read_data))
-
-    # If zotero_read is empty, use get_item_collections as fallback
-    if not zotero_read_data:
-        logger.info(
-            "zotero_read is empty, fetching paths dynamically using get_item_collections"
+        raise ValueError(
+            "No fetched papers were found to save. "
+            "Please retrieve papers using Zotero Read or Semantic Scholar first."
         )
-        try:
-            zotero_read_data = get_item_collections(zot)
-            logger.info(
-                "Successfully generated %d path mappings", len(zotero_read_data)
-            )
-        except Exception as e:
-            logger.error("Error generating path mappings: %s", str(e))
-            raise RuntimeError(
-                "Failed to generate collection path mappings. Please retry the same query."
-            ) from e
 
-    # Get all collections to find the correct one
-    collections = zot.collections()
-    logger.info("Found %d collections", len(collections))
-
-    # Normalize the requested collection path (remove trailing slash, lowercase for comparison)
+    # Normalize the requested collection path
     normalized_path = collection_path.rstrip("/").lower()
 
-    # Find matching collection
-    matched_collection_key = None
-
-    # First, try to directly find the collection key in zotero_read data
-    for key, paths in zotero_read_data.items():
-        if isinstance(paths, list):
-            for path in paths:
-                if path.lower() == normalized_path:
-                    matched_collection_key = key
-                    logger.info(
-                        "Found direct match in zotero_read: %s -> %s", path, key
-                    )
-                    break
-        elif isinstance(paths, str) and paths.lower() == normalized_path:
-            matched_collection_key = key
-            logger.info("Found direct match in zotero_read: %s -> %s", paths, key)
-            break
-
-    # If not found in zotero_read, try matching by collection name
-    if not matched_collection_key:
-        for col in collections:
-            col_name = col["data"]["name"]
-            if f"/{col_name}".lower() == normalized_path:
-                matched_collection_key = col["key"]
-                logger.info(
-                    "Found direct match by collection name: %s (key: %s)",
-                    col_name,
-                    col["key"],
-                )
-                break
+    # Use our utility function to find or optionally create the collection
+    # First try to find the exact collection
+    matched_collection_key = find_or_create_collection(
+        zot, normalized_path, create_missing=False  # First try without creating
+    )
 
-    # If still not found, try part-matching
     if not matched_collection_key:
-        name_to_key = {col["data"]["name"].lower(): col["key"] for col in collections}
-        collection_name = normalized_path.lstrip("/")
-        if collection_name in name_to_key:
-            matched_collection_key = name_to_key[collection_name]
-            logger.info(
-                "Found match by collection name: %s -> %s",
-                collection_name,
-                matched_collection_key,
-            )
-        else:
-            path_parts = normalized_path.strip("/").split("/")
-            for part in path_parts:
-                if part in name_to_key:
-                    matched_collection_key = name_to_key[part]
-                    logger.info(
-                        "Found match by path component: %s -> %s",
-                        part,
-                        matched_collection_key,
+        # Get all collection names without hierarchy for clearer display
+        available_collections = zot.collections()
+        collection_names = [col["data"]["name"] for col in available_collections]
+        names_display = ", ".join(collection_names)
+
+        return Command(
+            update={
+                "messages": [
+                    ToolMessage(
+                        content=(
+                            f"Error: The collection path '{collection_path}' does "
+                            f"not exist in Zotero. "
+                            f"Available collections are: {names_display}. "
+                            f"Please try saving to one of these existing collections."
+                        ),
+                        tool_call_id=tool_call_id,
                     )
-                    break
-
-    # Do not fall back to a default collection: raise error if no match found
-    if not matched_collection_key:
-        logger.error(
-            "Invalid collection path: %s. No matching collection found in Zotero.",
-            collection_path,
-        )
-
-        available_paths = ", ".join(["/" + col["data"]["name"] for col in collections])
-        raise RuntimeError(
-            f"Error: The collection path '{collection_path}' does not exist in Zotero. "
-            f"Available collections are: {available_paths}"
+                ],
+            }
         )
 
     # Format papers for Zotero and assign to the specified collection
@@ -244,6 +177,7 @@ def zotero_save_tool(
         raise RuntimeError(f"Error saving papers to Zotero: {str(e)}") from e
 
     # Get the collection name for better feedback
+    collections = zot.collections()
     collection_name = ""
     for col in collections:
         if col["key"] == matched_collection_key:
@@ -266,6 +200,7 @@ def zotero_save_tool(
     )
     content += "Here are a few of these articles:\n" + top_papers_info
 
+    # Clear the approval info so it's not reused
     return Command(
         update={
             "messages": [
@@ -275,5 +210,6 @@ def zotero_save_tool(
                     artifact=fetched_papers,
                 )
             ],
+            "zotero_write_approval_status": {},  # Clear approval info
         }
     )

{aiagents4pharma-1.30.1.dist-info → aiagents4pharma-1.30.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: aiagents4pharma
-Version: 1.30.1
+Version: 1.30.2
 Summary: AI Agents for drug discovery, drug development, and other pharmaceutical R&D.
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
@@ -62,6 +62,7 @@ Requires-Dist: umap-learn==0.5.7
 Requires-Dist: plotly-express==0.4.1
 Requires-Dist: seaborn==0.13.2
 Requires-Dist: scanpy==1.11.0
+Dynamic: license-file
 
 [![Talk2BioModels](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2biomodels.yml/badge.svg)](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2biomodels.yml)
 [![Talk2Cells](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2cells.yml/badge.svg)](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2cells.yml)