aiagents4pharma 0.0.0__py3-none-any.whl

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

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+
+"""
+Utility functions for Zotero path operations.
+"""
+
+import logging
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+# pylint: disable=broad-exception-caught
+
+
+def get_item_collections(zot):
+    """
+    Fetch all Zotero collections and map item keys to their full collection paths.
+
+    Args:
+        zot (Zotero): An initialized Zotero client.
+
+    Returns:
+        dict: A dictionary mapping item keys to a list of full collection paths.
+    """
+    logger.info("Fetching Zotero collections...")
+
+    # Fetch all collections
+    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):
+        """build collection path from collection key"""
+        path = []
+        while col_key:
+            path.insert(0, collection_map.get(col_key, "Unknown"))
+            col_key = parent_map.get(col_key)
+        return "/" + "/".join(path)  # Convert to "/path/to/collection"
+
+    collection_paths = {key: build_collection_path(key) for key in collection_map}
+
+    # Manually create an item-to-collection mapping with full paths
+    item_to_collections = {}
+
+    for collection in collections:
+        collection_key = collection["key"]
+        collection_items = zot.collection_items(collection_key)  # Fetch items in the collection
+
+        for item in collection_items:
+            item_key = item["data"]["key"]
+            if item_key in item_to_collections:
+                item_to_collections[item_key].append(collection_paths[collection_key])
+            else:
+                item_to_collections[item_key] = [collection_paths[collection_key]]
+
+    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/utils/zotero_pdf_downloader.py

@@ -0,0 +1,133 @@
+#!/usr/bin/env python3
+"""
+Utility functions for downloading PDFs from Zotero.
+"""
+
+import concurrent.futures
+import logging
+import tempfile
+
+import requests
+
+logger = logging.getLogger(__name__)
+
+
+def download_zotero_pdf(
+    session: requests.Session,
+    user_id: str,
+    api_key: str,
+    attachment_key: str,
+    **kwargs,
+) -> tuple[str, str] | None:
+    """
+    Download a PDF from Zotero by attachment key.
+
+    Args:
+        session: requests.Session for HTTP requests.
+        user_id: Zotero user ID.
+        api_key: Zotero API key.
+        attachment_key: Zotero attachment item key.
+        kwargs:
+            timeout (int): Request timeout in seconds (default: 10).
+            chunk_size (int, optional): Chunk size for streaming.
+
+    Returns:
+        Tuple of (local_file_path, filename) if successful, else None.
+    """
+    # Extract optional parameters
+    timeout = kwargs.get("timeout", 10)
+    chunk_size = kwargs.get("chunk_size")
+    # Log configured parameters for verification
+    logger.info("download_zotero_pdf params -> timeout=%s, chunk_size=%s", timeout, chunk_size)
+    # Log download start
+    logger.info("Downloading Zotero PDF for attachment %s from Zotero API", attachment_key)
+    zotero_pdf_url = f"https://api.zotero.org/users/{user_id}/items/{attachment_key}/file"
+    headers = {"Zotero-API-Key": api_key}
+
+    try:
+        response = session.get(zotero_pdf_url, headers=headers, stream=True, timeout=timeout)
+        response.raise_for_status()
+
+        # Download to a temporary file first
+        with tempfile.NamedTemporaryFile(delete=False, suffix=".pdf") as temp_file:
+            for chunk in response.iter_content(chunk_size=chunk_size):
+                temp_file.write(chunk)
+            temp_file_path = temp_file.name
+        # Temp file written to %s
+        logger.info("Zotero PDF downloaded to temporary file: %s", temp_file_path)
+
+        # Determine filename from Content-Disposition header or default
+        if "filename=" in response.headers.get("Content-Disposition", ""):
+            filename = (
+                response.headers.get("Content-Disposition", "").split("filename=")[-1].strip('"')
+            )
+        else:
+            filename = "downloaded.pdf"
+
+        return temp_file_path, filename
+
+    except (requests.exceptions.RequestException, OSError) as e:
+        logger.error("Failed to download Zotero PDF for attachment %s: %s", attachment_key, e)
+        return None
+
+
+def download_pdfs_in_parallel(
+    session: requests.Session,
+    user_id: str,
+    api_key: str,
+    attachment_item_map: dict[str, str],
+    **kwargs,
+) -> dict[str, tuple[str, str, str]]:
+    """
+    Download multiple PDFs in parallel using ThreadPoolExecutor.
+
+    Args:
+        session: requests.Session for HTTP requests.
+        user_id: Zotero user ID.
+        api_key: Zotero API key.
+        attachment_item_map: Mapping of attachment_key to parent item_key.
+        kwargs:
+            max_workers (int, optional): Maximum number of worker threads (default: min(10, n)).
+            chunk_size (int, optional): Chunk size for streaming.
+
+    Returns:
+        Mapping of parent item_key to (local_file_path, filename, attachment_key).
+    """
+    # Extract optional parameters
+    max_workers = kwargs.get("max_workers")
+    chunk_size = kwargs.get("chunk_size")
+    # Log configured parameters for verification
+    logger.info(
+        "download_pdfs_in_parallel params -> max_workers=%s, chunk_size=%s",
+        max_workers,
+        chunk_size,
+    )
+    results: dict[str, tuple[str, str, str]] = {}
+    if not attachment_item_map:
+        return results
+
+    with concurrent.futures.ThreadPoolExecutor(
+        max_workers=(max_workers if max_workers is not None else min(10, len(attachment_item_map)))
+    ) as executor:
+        future_to_keys = {
+            executor.submit(
+                download_zotero_pdf,
+                session,
+                user_id,
+                api_key,
+                attachment_key,
+                chunk_size=chunk_size,
+            ): (attachment_key, item_key)
+            for attachment_key, item_key in attachment_item_map.items()
+        }
+
+        for future in concurrent.futures.as_completed(future_to_keys):
+            attachment_key, item_key = future_to_keys[future]
+            try:
+                res = future.result()
+                if res:
+                    results[item_key] = (*res, attachment_key)
+            except (requests.exceptions.RequestException, OSError) as e:
+                logger.error("Failed to download PDF for key %s: %s", attachment_key, e)
+
+    return results

aiagents4pharma/talk2scholars/tools/zotero/zotero_read.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+
+"""
+Zotero Read Tool
+
+This LangGraph tool searches a user's Zotero library for items matching a query
+and optionally downloads their PDF attachments. It returns structured metadata
+for each found item and makes the results available as an artifact.
+"""
+
+import logging
+from typing import Annotated, Any
+
+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 .utils.read_helper import ZoteroSearchData
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class ZoteroSearchInput(BaseModel):
+    """Input schema for the Zotero search tool.
+
+    Attributes:
+        query (str): Search string to match against item metadata.
+        only_articles (bool): If True, restrict results to 'journalArticle' and similar types.
+        limit (int): Maximum number of items to fetch from Zotero.
+        download_pdfs (bool): If True, download PDF attachments for each item.
+        tool_call_id (str): Internal identifier for this tool invocation.
+    """
+
+    query: str = Field(description="Search query string to find papers in Zotero library.")
+    only_articles: bool = Field(
+        default=True,
+        description="Whether to only search for journal articles/conference papers.",
+    )
+    limit: int = Field(default=2, description="Maximum number of results to return", ge=1, le=100)
+    download_pdfs: bool = Field(
+        default=False,
+        description="Whether to download PDF attachments immediately (default True).",
+    )
+    tool_call_id: Annotated[str, InjectedToolCallId]
+
+
+@tool(args_schema=ZoteroSearchInput, parse_docstring=True)
+def zotero_read(
+    query: str,
+    only_articles: bool,
+    tool_call_id: Annotated[str, InjectedToolCallId],
+    limit: int = 2,
+    download_pdfs: bool = False,
+) -> Command[Any]:
+    """
+    Execute a search on the Zotero library and return matching items.
+
+    Args:
+        query (str): Text query to search in titles, abstracts, tags, etc.
+        only_articles (bool): When True, only include items of type 'journalArticle'
+        or 'conferencePaper'.
+        tool_call_id (str): Internal ID injected by LangGraph to track this tool call.
+        limit (int, optional): Max number of items to return (1–100). Defaults to 2.
+        download_pdfs (bool, optional): If True, PDFs for each returned item will be downloaded now.
+                                        If False, only metadata is fetched. Defaults to False.
+
+    Returns:
+        Command[Any]: A LangGraph Command updating the agent state:
+            - 'article_data': dict mapping item keys to metadata (and 'pdf_url' if downloaded).
+            - 'last_displayed_papers': identifier pointing to the articles in state.
+            - 'messages': list containing a ToolMessage with a human-readable summary
+                           and an 'artifact' referencing the raw article_data.
+    """
+    # Create search data object to organize variables
+    # download_pdfs flag controls whether PDFs are fetched now or deferred
+    search_data = ZoteroSearchData(
+        query=query,
+        only_articles=only_articles,
+        limit=limit,
+        download_pdfs=download_pdfs,
+        tool_call_id=tool_call_id,
+    )
+
+    # Process the search
+    search_data.process_search()
+    results = search_data.get_search_results()
+
+    return Command(
+        update={
+            "article_data": results["article_data"],
+            # Store the latest article_data mapping directly for display
+            "last_displayed_papers": results["article_data"],
+            "messages": [
+                ToolMessage(
+                    content=results["content"],
+                    tool_call_id=tool_call_id,
+                    artifact=results["article_data"],
+                )
+            ],
+        }
+    )

aiagents4pharma/talk2scholars/tools/zotero/zotero_review.py

@@ -0,0 +1,162 @@
+#!/usr/bin/env python3
+
+"""
+This tool implements human-in-the-loop review for Zotero write operations.
+"""
+
+import logging
+from typing import Annotated, Any, Literal
+
+from langchain_core.messages import HumanMessage, ToolMessage
+from langchain_core.tools import tool
+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.review_helper import ReviewData
+from .utils.zotero_path import fetch_papers_for_save
+
+# 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: str | None = 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

@@ -0,0 +1,91 @@
+#!/usr/bin/env python3
+
+"""
+This tool is used to save fetched papers to Zotero library after human approval.
+"""
+
+import logging
+from typing import Annotated, Any
+
+from langchain_core.messages import ToolMessage
+from langchain_core.tools import tool
+from langchain_core.tools.base import InjectedToolCallId
+from langgraph.prebuilt import InjectedState
+from langgraph.types import Command
+from pydantic import BaseModel, Field
+
+from .utils.write_helper import ZoteroWriteData
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class ZoteroSaveInput(BaseModel):
+    """Input schema for the Zotero save 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=ZoteroSaveInput, parse_docstring=True)
+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 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.
+    """
+    # Create write data object to organize variables
+    write_data = ZoteroWriteData(tool_call_id, collection_path, state)
+
+    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"],
+                    )
+                ],
+                "zotero_write_approval_status": {},  # Clear approval info
+            }
+        )
+    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,
+                        )
+                    ],
+                }
+            )
+        # Let other ValueErrors (like no papers) propagate up
+        raise