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

aiagents4pharma/talk2scholars/tools/zotero/zotero_read.py

@@ -6,18 +6,13 @@ This tool is used to search for papers in Zotero library.
 
 import logging
 from typing import Annotated, Any
-import hydra
-from pyzotero import zotero
 from langchain_core.messages import ToolMessage
 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.read_helper import ZoteroSearchData
 
-# pylint: disable=R0914,R0912,R0915
 
 # Configure logging
 logging.basicConfig(level=logging.INFO)
@@ -41,7 +36,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],
@@ -58,146 +53,22 @@ def zotero_search_tool(
     Returns:
         Dict[str, Any]: The search results and related information.
     """
-    # Load hydra configuration
-    with hydra.initialize(version_base=None, config_path="../../configs"):
-        cfg = hydra.compose(
-            config_name="config", overrides=["tools/zotero_read=default"]
-        )
-        logger.info("Loaded configuration for Zotero search tool")
-        cfg = cfg.tools.zotero_read
-        logger.info(
-            "Searching Zotero for query: '%s' (only_articles: %s, limit: %d)",
-            query,
-            only_articles,
-            limit,
-        )
+    # Create search data object to organize variables
+    search_data = ZoteroSearchData(query, only_articles, limit, tool_call_id)
 
-    # Initialize Zotero client
-    zot = zotero.Zotero(cfg.user_id, cfg.library_type, cfg.api_key)
-
-    # Fetch collection mapping once
-    item_to_collections = get_item_collections(zot)
-
-    # If the query is empty, fetch all items (up to max_limit), otherwise use the query
-    try:
-        if query.strip() == "":
-            logger.info(
-                "Empty query provided, fetching all items up to max_limit: %d",
-                cfg.zotero.max_limit,
-            )
-            items = zot.items(limit=cfg.zotero.max_limit)
-        else:
-            items = zot.items(q=query, limit=min(limit, cfg.zotero.max_limit))
-    except Exception as e:
-        logger.error("Failed to fetch items from Zotero: %s", e)
-        raise RuntimeError(
-            "Failed to fetch items from Zotero. Please retry the same query."
-        ) from e
-
-    logger.info("Received %d items from Zotero", len(items))
-
-    if not items:
-        logger.error("No items returned from Zotero for query: '%s'", query)
-        raise RuntimeError(
-            "No items returned from Zotero. Please retry the same query."
-        )
-
-    # Define filter criteria
-    filter_item_types = cfg.zotero.filter_item_types if only_articles else []
-    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 = {}
-
-    for item in items:
-        if not isinstance(item, dict):
-            continue
-
-        data = item.get("data")
-        if not isinstance(data, dict):
-            continue
-
-        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
-
-        key = data.get("key")
-        if not key:
-            continue
-
-        # 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"),
-            "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,  # 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:
-        logger.error("No matching papers returned from Zotero for query: '%s'", query)
-        raise RuntimeError(
-            "No matching papers returned from Zotero. Please retry the same query."
-        )
-
-    logger.info("Filtered %d items", len(filtered_papers))
-
-    # Prepare content with top 2 paper titles and types
-    top_papers = list(filtered_papers.values())[:2]
-    top_papers_info = "\n".join(
-        [
-            f"{i+1}. {paper['Title']} ({paper['Type']})"
-            for i, paper in enumerate(top_papers)
-        ]
-    )
-
-    content = "Retrieval was successful. Papers are attached as an artifact."
-    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 += "Here are a few of these papers:\n" + top_papers_info
+    # Process the search
+    search_data.process_search()
+    results = search_data.get_search_results()
 
     return Command(
         update={
-            "zotero_read": filtered_papers,
+            "zotero_read": results["filtered_papers"],
             "last_displayed_papers": "zotero_read",
             "messages": [
                 ToolMessage(
-                    content=content,
+                    content=results["content"],
                     tool_call_id=tool_call_id,
-                    artifact=filtered_papers,
+                    artifact=results["filtered_papers"],
                 )
             ],
         }

aiagents4pharma/talk2scholars/tools/zotero/zotero_review.py

@@ -0,0 +1,164 @@
+#!/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
+from .utils.review_helper import ReviewData
+
+# 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."
+        )
+
+    # Create review data object to organize variables
+    review_data = ReviewData(collection_path, fetched_papers, tool_call_id, state)
+
+    try:
+        # Interrupt the graph to get human approval
+        human_review = interrupt(review_data.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=review_data.get_approval_message(),
+                            tool_call_id=tool_call_id,
+                        )
+                    ],
+                    "zotero_write_approval_status": {
+                        "collection_path": review_data.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=review_data.get_custom_path_approval_message(
+                                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 "
+                            f"{review_data.total_papers} papers to Zotero collection "
+                            f"'{review_data.collection_path}'?\n\n"
+                            f"Papers to save:\n{review_data.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": review_data.collection_path,
+                    "papers_reviewed": True,
+                    "approved": False,  # Not approved yet
+                    "papers_count": review_data.total_papers,
+                },
+            }
+        )

aiagents4pharma/talk2scholars/tools/zotero/zotero_write.py

@@ -1,24 +1,19 @@
 #!/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
 from typing import Annotated, Any
-import hydra
-from pyzotero import zotero
 from langchain_core.messages import ToolMessage
 from langchain_core.tools import tool
 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.write_helper import ZoteroWriteData
 
-# pylint: disable=R0914,R0912,R0915
 
 # Configure logging
 logging.basicConfig(level=logging.INFO)
@@ -30,250 +25,66 @@ 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.
     """
-    # Load hydra configuration
-    with hydra.initialize(version_base=None, config_path="../../configs"):
-        cfg = hydra.compose(
-            config_name="config", overrides=["tools/zotero_write=default"]
-        )
-        cfg = cfg.tools.zotero_write
-        logger.info("Loaded configuration for Zotero write tool")
-    logger.info(
-        "Saving fetched papers to Zotero under collection path: %s", collection_path
-    )
-
-    # 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")
-
-    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"
-        )
-        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)
-    normalized_path = collection_path.rstrip("/").lower()
-
-    # Find matching collection
-    matched_collection_key = None
+    # Create write data object to organize variables
+    write_data = ZoteroWriteData(tool_call_id, collection_path, state)
 
-    # 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
-
-    # 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,
+    try:
+        # Process the write operation
+        results = write_data.process_write()
+
+        return Command(
+            update={
+                "messages": [
+                    ToolMessage(
+                        content=results["content"],
+                        tool_call_id=tool_call_id,
+                        artifact=results["fetched_papers"],
                     )
-                    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}"
+                ],
+                "zotero_write_approval_status": {},  # Clear approval info
+            }
         )
-
-    # Format papers for Zotero and assign to the specified collection
-    zotero_items = []
-    for paper_id, paper in fetched_papers.items():
-        title = paper.get("Title", "N/A")
-        abstract = paper.get("Abstract", "N/A")
-        publication_date = paper.get("Publication Date", "N/A")  # Use Publication Date
-        url = paper.get("URL", "N/A")
-        citations = paper.get("Citation Count", "N/A")
-        venue = paper.get("Venue", "N/A")
-        publication_venue = paper.get("Publication Venue", "N/A")
-        journal_name = paper.get("Journal Name", "N/A")
-        journal_volume = paper.get("Journal Volume", "N/A")
-        journal_pages = paper.get("Journal Pages", "N/A")
-
-        # Convert Authors list to Zotero format
-        authors = [
-            (
-                {
-                    "creatorType": "author",
-                    "firstName": name.split(" ")[0],
-                    "lastName": " ".join(name.split(" ")[1:]),
+    except ValueError as e:
+        # Only handle collection not found errors with a Command
+        if "collection path" in str(e).lower():
+            return Command(
+                update={
+                    "messages": [
+                        ToolMessage(
+                            content=str(e),
+                            tool_call_id=tool_call_id,
+                        )
+                    ],
                 }
-                if " " in name
-                else {"creatorType": "author", "lastName": name}
             )
-            for name in [
-                author.split(" (ID: ")[0] for author in paper.get("Authors", [])
-            ]
-        ]
-
-        zotero_items.append(
-            {
-                "itemType": "journalArticle",
-                "title": title,
-                "abstractNote": abstract,
-                "date": publication_date,  # Now saving full publication date
-                "url": url,
-                "extra": f"Paper ID: {paper_id}\nCitations: {citations}",
-                "collections": [matched_collection_key],
-                "publicationTitle": (
-                    publication_venue if publication_venue != "N/A" else venue
-                ),  # Use publication venue if available
-                "journalAbbreviation": journal_name,  # Save Journal Name
-                "volume": (
-                    journal_volume if journal_volume != "N/A" else None
-                ),  # Save Journal Volume
-                "pages": (
-                    journal_pages if journal_pages != "N/A" else None
-                ),  # Save Journal Pages
-                "creators": authors,  # Save authors list properly
-            }
-        )
-
-    # Save items to Zotero
-    try:
-        response = zot.create_items(zotero_items)
-        logger.info("Papers successfully saved to Zotero: %s", response)
-    except Exception as e:
-        logger.error("Error saving to Zotero: %s", str(e))
-        raise RuntimeError(f"Error saving papers to Zotero: {str(e)}") from e
-
-    # Get the collection name for better feedback
-    collection_name = ""
-    for col in collections:
-        if col["key"] == matched_collection_key:
-            collection_name = col["data"]["name"]
-            break
-
-    content = (
-        f"Save was successful. Papers have been saved to Zotero collection '{collection_name}' "
-        f"with the requested path '{collection_path}'.\n"
-    )
-    content += "Summary of saved papers:\n"
-    content += f"Number of articles saved: {len(fetched_papers)}\n"
-    content += f"Query: {state.get('query', 'N/A')}\n"
-    top_papers = list(fetched_papers.values())[:2]
-    top_papers_info = "\n".join(
-        [
-            f"{i+1}. {paper.get('Title', 'N/A')} ({paper.get('URL', 'N/A')})"
-            for i, paper in enumerate(top_papers)
-        ]
-    )
-    content += "Here are a few of these articles:\n" + top_papers_info
-
-    return Command(
-        update={
-            "messages": [
-                ToolMessage(
-                    content=content,
-                    tool_call_id=tool_call_id,
-                    artifact=fetched_papers,
-                )
-            ],
-        }
-    )
+        # Let other ValueErrors (like no papers) propagate up
+        raise

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

@@ -1,6 +1,6 @@
-Metadata-Version: 2.2
+Metadata-Version: 2.4
 Name: aiagents4pharma
-Version: 1.30.1
+Version: 1.30.3
 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)