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

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],
@@ -104,9 +102,10 @@ def zotero_search_tool(
 
     # Define filter criteria
     filter_item_types = cfg.zotero.filter_item_types if only_articles else []
-    filter_excluded_types = (
-        cfg.zotero.filter_excluded_types
-    )  # Exclude non-research items
+    logger.debug("Filtering item types: %s", filter_item_types)
+    # filter_excluded_types = (
+    #     cfg.zotero.filter_excluded_types
+    # )  # Exclude non-research items
 
     # Filter and format papers
     filtered_papers = {}
@@ -119,19 +118,19 @@ def zotero_search_tool(
         if not isinstance(data, dict):
             continue
 
-        item_type = data.get("itemType")
+        item_type = data.get("itemType", "N/A")
         logger.debug("Item type: %s", item_type)
 
         # Exclude attachments, notes, and other unwanted types
-        if (
-            not item_type
-            or not isinstance(item_type, str)
-            or item_type in filter_excluded_types  # Skip attachments & notes
-            or (
-                only_articles and item_type not in filter_item_types
-            )  # Skip non-research types
-        ):
-            continue
+        # if (
+        #     not item_type
+        #     or not isinstance(item_type, str)
+        #     or item_type in filter_excluded_types  # Skip attachments & notes
+        #     or (
+        #         only_articles and item_type not in filter_item_types
+        #     )  # Skip non-research types
+        # ):
+        #     continue
 
         key = data.get("key")
         if not key:
@@ -140,13 +139,29 @@ def zotero_search_tool(
         # Use the imported utility function's mapping to get collection paths
         collection_paths = item_to_collections.get(key, ["/Unknown"])
 
+        # Extract metadata safely
         filtered_papers[key] = {
             "Title": data.get("title", "N/A"),
             "Abstract": data.get("abstractNote", "N/A"),
-            "Date": data.get("date", "N/A"),
+            "Publication Date": data.get(
+                "date", "N/A"
+            ),  # Correct field for publication date
             "URL": data.get("url", "N/A"),
             "Type": item_type if isinstance(item_type, str) else "N/A",
-            "Collections": collection_paths,  # Now displays full paths
+            "Collections": collection_paths,  # Displays full collection paths
+            "Citation Count": data.get("citationCount", "N/A"),  # Shows citations
+            "Venue": data.get("venue", "N/A"),  # Displays venue
+            "Publication Venue": data.get(
+                "publicationTitle", "N/A"
+            ),  # Matches with Zotero Write
+            "Journal Name": data.get("journalAbbreviation", "N/A"),  # Journal Name
+            # "Journal Volume": data.get("volume", "N/A"),  # Journal Volume
+            # "Journal Pages": data.get("pages", "N/A"),  # Journal Pages
+            "Authors": [
+                f"{creator.get('firstName', '')} {creator.get('lastName', '')}".strip()
+                for creator in data.get("creators", [])  # Prevents NoneType error
+                if isinstance(creator, dict) and creator.get("creatorType") == "author"
+            ],
         }
 
     if not filtered_papers:
@@ -170,7 +185,7 @@ def zotero_search_tool(
     content += " And here is a summary of the retrieval results:\n"
     content += f"Number of papers found: {len(filtered_papers)}\n"
     content += f"Query: {query}\n"
-    content += "Top papers:\n" + top_papers_info
+    content += "Here are a few of these papers:\n" + top_papers_info
 
     return Command(
         update={

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,
+                },
+            }
+        )