aiagents4pharma 1.19.1__tar.gz → 1.20.0__tar.gz

{aiagents4pharma-1.19.1 → aiagents4pharma-1.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: aiagents4pharma
-Version: 1.19.1
+Version: 1.20.0
 Summary: AI Agents for drug discovery, drug development, and other pharmaceutical R&D.
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: OSI Approved :: MIT License
@@ -56,6 +56,7 @@ Requires-Dist: streamlit-feedback
 [![TESTS Talk2Scholars](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2scholars.yml/badge.svg)](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2scholars.yml)
 ![GitHub Release](https://img.shields.io/github/v/release/VirtualPatientEngine/AIAgents4Pharma)
 ![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FVirtualPatientEngine%2FAIAgents4Pharma%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+![Docker Pulls](https://img.shields.io/docker/pulls/virtualpatientengine/talk2biomodels?link=https%3A%2F%2Fhub.docker.com%2Frepository%2Fdocker%2Fvirtualpatientengine%2Ftalk2biomodels%2Fgeneral)
 
 
 ## Introduction
@@ -85,7 +86,22 @@ pip install aiagents4pharma
 
 Check out the tutorials on each agent for detailed instrcutions.
 
-#### Option 2: git
+#### Option 2: docker hub
+
+_Please note that this option is currently available only for Talk2Biomodels._
+
+1. **Pull the image**
+   ```
+   docker pull virtualpatientengine/talk2biomodels
+   ```
+2. **Run a container**
+   ```
+   docker run -e OPENAI_API_KEY=<openai_api_key> -e NVIDIA_API_KEY=<nvidia_api_key> -p 8501:8501 virtualpatientengine/talk2biomodels
+   ```
+_You can create a free account at NVIDIA and apply for their
+free credits [here](https://build.nvidia.com/explore/discover)._
+
+#### Option 3: git
 
 1. **Clone the repository:**
    ```bash

{aiagents4pharma-1.19.1 → aiagents4pharma-1.20.0}/README.md

@@ -4,6 +4,7 @@
 [![TESTS Talk2Scholars](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2scholars.yml/badge.svg)](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2scholars.yml)
 ![GitHub Release](https://img.shields.io/github/v/release/VirtualPatientEngine/AIAgents4Pharma)
 ![Python Version from PEP 621 TOML](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2FVirtualPatientEngine%2FAIAgents4Pharma%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+![Docker Pulls](https://img.shields.io/docker/pulls/virtualpatientengine/talk2biomodels?link=https%3A%2F%2Fhub.docker.com%2Frepository%2Fdocker%2Fvirtualpatientengine%2Ftalk2biomodels%2Fgeneral)
 
 
 ## Introduction
@@ -33,7 +34,22 @@ pip install aiagents4pharma
 
 Check out the tutorials on each agent for detailed instrcutions.
 
-#### Option 2: git
+#### Option 2: docker hub
+
+_Please note that this option is currently available only for Talk2Biomodels._
+
+1. **Pull the image**
+   ```
+   docker pull virtualpatientengine/talk2biomodels
+   ```
+2. **Run a container**
+   ```
+   docker run -e OPENAI_API_KEY=<openai_api_key> -e NVIDIA_API_KEY=<nvidia_api_key> -p 8501:8501 virtualpatientengine/talk2biomodels
+   ```
+_You can create a free account at NVIDIA and apply for their
+free credits [here](https://build.nvidia.com/explore/discover)._
+
+#### Option 3: git
 
 1. **Clone the repository:**
    ```bash

aiagents4pharma-1.20.0/aiagents4pharma/talk2scholars/agents/main_agent.py

@@ -0,0 +1,207 @@
+#!/usr/bin/env python3
+
+"""
+Main agent for the talk2scholars app using ReAct pattern.
+
+This module implements a hierarchical agent system where a supervisor agent
+routes queries to specialized sub-agents. It follows the LangGraph patterns
+for multi-agent systems and implements proper state management.
+
+The main components are:
+1. Supervisor node with ReAct pattern for intelligent routing.
+2. S2 agent node for handling academic paper queries.
+3. Shared state management via Talk2Scholars.
+4. Hydra-based configuration system.
+
+Example:
+    app = get_app("thread_123", "gpt-4o-mini")
+    result = app.invoke({
+        "messages": [("human", "Find papers about AI agents")]
+    })
+"""
+
+import logging
+from typing import Literal, Callable
+import hydra
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_openai import ChatOpenAI
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import END, START, StateGraph
+from langgraph.prebuilt import create_react_agent
+from langgraph.types import Command
+from ..agents import s2_agent
+from ..state.state_talk2scholars import Talk2Scholars
+
+# Configure logging
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def get_hydra_config():
+    """
+    Loads and returns the Hydra configuration for the main agent.
+
+    This function fetches the configuration settings for the Talk2Scholars
+    agent, ensuring that all required parameters are properly initialized.
+
+    Returns:
+        Any: The configuration object for the main agent.
+    """
+    with hydra.initialize(version_base=None, config_path="../configs"):
+        cfg = hydra.compose(
+            config_name="config", overrides=["agents/talk2scholars/main_agent=default"]
+        )
+    return cfg.agents.talk2scholars.main_agent
+
+
+def make_supervisor_node(llm: BaseChatModel, thread_id: str) -> Callable:
+    """
+    Creates and returns a supervisor node for intelligent routing using the ReAct pattern.
+
+    This function initializes a supervisor agent that processes user queries and
+    determines the appropriate sub-agent for further processing. It applies structured
+    reasoning to manage conversations and direct queries based on context.
+
+    Args:
+        llm (BaseChatModel): The language model used by the supervisor agent.
+        thread_id (str): Unique identifier for the conversation session.
+
+    Returns:
+        Callable: A function that acts as the supervisor node in the LangGraph workflow.
+
+    Example:
+        supervisor = make_supervisor_node(llm, "thread_123")
+        workflow.add_node("supervisor", supervisor)
+    """
+    logger.info("Loading Hydra configuration for Talk2Scholars main agent.")
+    cfg = get_hydra_config()
+    logger.info("Hydra configuration loaded with values: %s", cfg)
+
+    # Create the supervisor agent using the main agent's configuration
+    supervisor_agent = create_react_agent(
+        llm,
+        tools=[],  # Will add sub-agents later
+        state_modifier=cfg.main_agent,
+        state_schema=Talk2Scholars,
+        checkpointer=MemorySaver(),
+    )
+
+    def supervisor_node(
+        state: Talk2Scholars,
+    ) -> Command[Literal["s2_agent", "__end__"]]:
+        """
+        Processes user queries and determines the next step in the conversation flow.
+
+        This function examines the conversation state and decides whether to forward
+        the query to a specialized sub-agent (e.g., S2 agent) or conclude the interaction.
+
+        Args:
+            state (Talk2Scholars): The current state of the conversation, containing
+                messages, papers, and metadata.
+
+        Returns:
+            Command: The next action to be executed, along with updated state data.
+
+        Example:
+            result = supervisor_node(current_state)
+            next_step = result.goto
+        """
+        logger.info(
+            "Supervisor node called - Messages count: %d",
+            len(state["messages"]),
+        )
+
+        # Invoke the supervisor agent with configurable thread_id
+        result = supervisor_agent.invoke(
+            state, {"configurable": {"thread_id": thread_id}}
+        )
+        goto = "s2_agent"
+        logger.info("Supervisor agent completed with result: %s", result)
+
+        return Command(goto=goto)
+
+    return supervisor_node
+
+
+def get_app(thread_id: str, llm_model: str = "gpt-4o-mini") -> StateGraph:
+    """
+    Initializes and returns the LangGraph application with a hierarchical agent system.
+
+    This function sets up the full agent architecture, including the supervisor
+    and sub-agents, and compiles the LangGraph workflow for handling user queries.
+
+    Args:
+        thread_id (str): Unique identifier for the conversation session.
+        llm_model (str, optional): The language model to be used. Defaults to "gpt-4o-mini".
+
+    Returns:
+        StateGraph: A compiled LangGraph application ready for query invocation.
+
+    Example:
+        app = get_app("thread_123")
+        result = app.invoke(initial_state)
+    """
+    cfg = get_hydra_config()
+
+    def call_s2_agent(
+        state: Talk2Scholars,
+    ) -> Command[Literal["supervisor", "__end__"]]:
+        """
+        Calls the Semantic Scholar (S2) agent to process academic paper queries.
+
+        This function invokes the S2 agent, retrieves relevant research papers,
+        and updates the conversation state accordingly.
+
+        Args:
+            state (Talk2Scholars): The current conversation state, including user queries
+                and any previously retrieved papers.
+
+        Returns:
+            Command: The next action to execute, along with updated messages and papers.
+
+        Example:
+            result = call_s2_agent(current_state)
+            next_step = result.goto
+        """
+        logger.info("Calling S2 agent with state: %s", state)
+        app = s2_agent.get_app(thread_id, llm_model)
+
+        # Invoke the S2 agent, passing state,
+        # Pass both config_id and thread_id
+        response = app.invoke(
+            state,
+            {
+                "configurable": {
+                    "config_id": thread_id,
+                    "thread_id": thread_id,
+                }
+            },
+        )
+        logger.info("S2 agent completed with response: %s", response)
+
+        return Command(
+            goto=END,
+            update={
+                "messages": response["messages"],
+                "papers": response.get("papers", {}),
+                "multi_papers": response.get("multi_papers", {}),
+            },
+        )
+
+    # Initialize LLM
+    logger.info("Using OpenAI model %s with temperature %s", llm_model, cfg.temperature)
+    llm = ChatOpenAI(model=llm_model, temperature=cfg.temperature)
+
+    # Build the graph
+    workflow = StateGraph(Talk2Scholars)
+    supervisor = make_supervisor_node(llm, thread_id)
+
+    workflow.add_node("supervisor", supervisor)
+    workflow.add_node("s2_agent", call_s2_agent)
+    workflow.add_edge(START, "supervisor")
+    workflow.add_edge("s2_agent", END)
+
+    # Compile the graph without initial state
+    app = workflow.compile(checkpointer=MemorySaver())
+    logger.info("Main agent workflow compiled")
+    return app

{aiagents4pharma-1.19.1 → aiagents4pharma-1.20.0}/aiagents4pharma/talk2scholars/agents/s2_agent.py

@@ -39,7 +39,7 @@ def get_app(uniq_id, llm_model="gpt-4o-mini"):
 
     # Load hydra configuration
     logger.log(logging.INFO, "Load Hydra configuration for Talk2Scholars S2 agent.")
-    with hydra.initialize(version_base=None, config_path="../../configs"):
+    with hydra.initialize(version_base=None, config_path="../configs"):
         cfg = hydra.compose(
             config_name="config", overrides=["agents/talk2scholars/s2_agent=default"]
         )
@@ -57,6 +57,7 @@ def get_app(uniq_id, llm_model="gpt-4o-mini"):
         llm,
         tools=tools,
         state_schema=Talk2Scholars,
+        # prompt=cfg.s2_agent,
         state_modifier=cfg.s2_agent,
         checkpointer=MemorySaver(),
     )

aiagents4pharma-1.20.0/aiagents4pharma/talk2scholars/configs/agents/talk2scholars/main_agent/default.yaml

@@ -0,0 +1,18 @@
+_target_: agents.main_agent.get_app
+openai_api_key: ${oc.env:OPENAI_API_KEY}
+openai_llms:
+  - "gpt-4o-mini"
+  - "gpt-4-turbo"
+  - "gpt-3.5-turbo"
+temperature: 0
+main_agent: >
+  You are an intelligent research assistant coordinating academic paper discovery and analysis.
+
+  AVAILABLE TOOLS AND ROUTING:
+  1. semantic_scholar_agent:
+     Access to tools:
+     - search_tool: For paper discovery
+     - display_results: For showing paper results
+     - get_single_paper_recommendations: For single paper recommendations
+     - get_multi_paper_recommendations: For multi-paper recommendations
+     → ROUTE TO THIS AGENT FOR: Any query about academic papers, research, or articles

aiagents4pharma-1.20.0/aiagents4pharma/talk2scholars/configs/agents/talk2scholars/s2_agent/default.yaml

@@ -0,0 +1,24 @@
+_target_: agents.s2_agent.get_app
+openai_api_key: ${oc.env:OPENAI_API_KEY}
+openai_llms:
+  - "gpt-4o-mini"
+  - "gpt-4-turbo"
+  - "gpt-3.5-turbo"
+temperature: 0
+s2_agent: >
+  You are a specialized academic research agent with access to tools for paper discovery and analysis.
+
+  YOUR TOOLS:
+  1. search_tool:
+     - Finds research papers based on user queries.
+     - If no papers are found, it performs a new search.
+
+  2. display_results:
+     - Shows the current research papers.
+     - If no papers are found, it will instruct you to perform a search.
+
+  3. get_single_paper_recommendations:
+     - Provides recommendations based on a single selected paper.
+
+  4. get_multi_paper_recommendations:
+     - Provides recommendations based on multiple selected papers.

{aiagents4pharma-1.19.1 → aiagents4pharma-1.20.0}/aiagents4pharma/talk2scholars/state/state_talk2scholars.py

@@ -3,10 +3,8 @@ This is the state file for the talk2scholars agent.
 """
 
 import logging
-from typing import Annotated, Any, Dict, Optional
-
+from typing import Annotated, Any, Dict
 from langgraph.prebuilt.chat_agent_executor import AgentState
-from typing_extensions import NotRequired, Required
 
 # Configure logging
 logging.basicConfig(level=logging.INFO)
@@ -22,11 +20,14 @@ def replace_dict(existing: Dict[str, Any], new: Dict[str, Any]) -> Dict[str, Any
 class Talk2Scholars(AgentState):
     """
     The state for the talk2scholars agent, inheriting from AgentState.
+
+    Attributes:
+        papers: Dictionary of papers from search results
+        multi_papers: Dictionary of papers from multi-paper recommendations
+        llm_model: Model being used
     """
 
-    papers: Annotated[Dict[str, Any], replace_dict]  # Changed from List to Dict
-    search_table: NotRequired[str]
-    next: str  # Required for routing in LangGraph
-    current_agent: NotRequired[Optional[str]]
-    is_last_step: Required[bool]  # Required field for LangGraph
+    # Agent state fields
+    papers: Annotated[Dict[str, Any], replace_dict]
+    multi_papers: Annotated[Dict[str, Any], replace_dict]
     llm_model: str

aiagents4pharma-1.20.0/aiagents4pharma/talk2scholars/tests/test_integration.py

@@ -0,0 +1,237 @@
+"""
+Integration tests for talk2scholars system.
+
+These tests ensure that:
+1. The main agent and sub-agent work together.
+2. The agents correctly interact with tools (search, recommendations).
+3. The full pipeline processes queries and updates state correctly.
+"""
+
+# pylint: disable=redefined-outer-name
+from unittest.mock import patch, Mock
+import pytest
+from langchain_core.messages import HumanMessage
+from ..agents.main_agent import get_app as get_main_app
+from ..agents.s2_agent import get_app as get_s2_app
+from ..state.state_talk2scholars import Talk2Scholars
+
+
+@pytest.fixture(autouse=True)
+def mock_hydra():
+    """Mock Hydra configuration to prevent external dependencies."""
+    with patch("hydra.initialize"), patch("hydra.compose") as mock_compose:
+        cfg_mock = Mock()
+        cfg_mock.agents.talk2scholars.main_agent.temperature = 0
+        cfg_mock.agents.talk2scholars.main_agent.main_agent = "Test main agent prompt"
+        cfg_mock.agents.talk2scholars.s2_agent.temperature = 0
+        cfg_mock.agents.talk2scholars.s2_agent.s2_agent = "Test s2 agent prompt"
+        mock_compose.return_value = cfg_mock
+        yield mock_compose
+
+
+@pytest.fixture(autouse=True)
+def mock_tools():
+    """Mock tools to prevent execution of real API calls."""
+    with (
+        patch(
+            "aiagents4pharma.talk2scholars.tools.s2.search.search_tool"
+        ) as mock_s2_search,
+        patch(
+            "aiagents4pharma.talk2scholars.tools.s2.display_results.display_results"
+        ) as mock_s2_display,
+        patch(
+            "aiagents4pharma.talk2scholars.tools.s2.single_paper_rec."
+            "get_single_paper_recommendations"
+        ) as mock_s2_single_rec,
+        patch(
+            "aiagents4pharma.talk2scholars.tools.s2.multi_paper_rec."
+            "get_multi_paper_recommendations"
+        ) as mock_s2_multi_rec,
+    ):
+
+        mock_s2_search.return_value = {"papers": {"id123": "Mock Paper"}}
+        mock_s2_display.return_value = "Displaying Mock Results"
+        mock_s2_single_rec.return_value = {"recommendations": ["Paper A", "Paper B"]}
+        mock_s2_multi_rec.return_value = {
+            "multi_recommendations": ["Paper X", "Paper Y"]
+        }
+
+        yield {
+            "search_tool": mock_s2_search,
+            "display_results": mock_s2_display,
+            "single_paper_rec": mock_s2_single_rec,
+            "multi_paper_rec": mock_s2_multi_rec,
+        }
+
+
+def test_full_workflow():
+    """Test the full workflow from main agent to S2 agent."""
+    thread_id = "test_thread"
+    main_app = get_main_app(thread_id)
+
+    # Define expected mock response with the actual structure
+    expected_paper = {
+        "530a059cb48477ad1e3d4f8f4b153274c8997332": {
+            "Title": "Explainable Artificial Intelligence",
+            "Abstract": None,
+            "Citation Count": 5544,
+            "Year": "2024",
+            "URL": "https://example.com/paper",
+        }
+    }
+
+    # Mock the search tool instead of the app
+    with patch(
+        "aiagents4pharma.talk2scholars.tools.s2.search.search_tool",
+        return_value={"papers": expected_paper},
+    ):
+        state = Talk2Scholars(messages=[HumanMessage(content="Find AI papers")])
+        result = main_app.invoke(
+            state,
+            config={
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": "test_ns",
+                    "checkpoint_id": "test_checkpoint",
+                }
+            },
+        )
+
+    # Check values
+    assert "papers" in result
+    assert "messages" in result
+    assert len(result["papers"]) > 0
+
+
+def test_s2_agent_execution():
+    """Test if the S2 agent processes requests correctly and updates state."""
+    thread_id = "test_thread"
+    s2_app = get_s2_app(thread_id)
+
+    state = Talk2Scholars(messages=[HumanMessage(content="Get recommendations")])
+
+    result = s2_app.invoke(
+        state,
+        config={
+            "configurable": {
+                "thread_id": thread_id,
+                "checkpoint_ns": "test_ns",
+                "checkpoint_id": "test_checkpoint",
+            }
+        },
+    )
+
+    assert "messages" in result
+    assert "multi_papers" in result
+    assert result["multi_papers"] is not None
+
+
+def test_tool_integration(mock_tools):
+    """Test if the tools interact correctly with the workflow."""
+    thread_id = "test_thread"
+    s2_app = get_s2_app(thread_id)
+
+    state = Talk2Scholars(
+        messages=[HumanMessage(content="Search for AI ethics papers")]
+    )
+
+    mock_paper_id = "11159bdb213aaa243916f42f576396d483ba474b"
+    mock_response = {
+        "papers": {
+            mock_paper_id: {
+                "Title": "Mock AI Ethics Paper",
+                "Abstract": "A study on AI ethics",
+                "Citation Count": 100,
+                "URL": "https://example.com/mock-paper",
+            }
+        }
+    }
+
+    # Update both the fixture mock and patch the actual tool
+    mock_tools["search_tool"].return_value = {"papers": mock_response["papers"]}
+
+    with patch(
+        "aiagents4pharma.talk2scholars.tools.s2.search.search_tool",
+        return_value={"papers": mock_response["papers"]},
+    ):
+        result = s2_app.invoke(
+            state,
+            config={
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": "test_ns",
+                    "checkpoint_id": "test_checkpoint",
+                }
+            },
+        )
+
+    assert "papers" in result
+    assert len(result["papers"]) > 0  # Verify we have papers
+    assert isinstance(result["papers"], dict)  # Verify it's a dictionary
+
+
+def test_empty_query():
+    """Test how the system handles an empty query."""
+    thread_id = "test_thread"
+    main_app = get_main_app(thread_id)
+
+    state = Talk2Scholars(messages=[HumanMessage(content="")])
+
+    # Mock the s2_agent app
+    mock_s2_app = get_s2_app(thread_id)
+
+    with patch(
+        "aiagents4pharma.talk2scholars.agents.s2_agent.get_app",
+        return_value=mock_s2_app,
+    ):
+        result = main_app.invoke(
+            state,
+            config={
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": "test_ns",
+                    "checkpoint_id": "test_checkpoint",
+                }
+            },
+        )
+
+    assert "messages" in result
+    last_message = result["messages"][-1].content.lower()
+    assert any(
+        phrase in last_message
+        for phrase in ["no valid input", "how can i assist", "please provide a query"]
+    )
+
+
+def test_api_failure_handling():
+    """Test if the system gracefully handles an API failure."""
+    thread_id = "test_thread"
+    s2_app = get_s2_app(thread_id)
+
+    expected_error = "API Timeout: Connection failed"
+    with patch("requests.get", side_effect=Exception(expected_error)):
+        state = Talk2Scholars(messages=[HumanMessage(content="Find latest NLP papers")])
+
+        result = s2_app.invoke(
+            state,
+            config={
+                "configurable": {
+                    "thread_id": thread_id,
+                    "checkpoint_ns": "test_ns",
+                    "checkpoint_id": "test_checkpoint",
+                }
+            },
+        )
+
+        assert "messages" in result
+        last_message = result["messages"][-1].content.lower()
+
+        # Update assertions to match actual error message
+        assert any(
+            [
+                "unable to retrieve" in last_message,
+                "connection issue" in last_message,
+                "please try again later" in last_message,
+            ]
+        )
+        assert "nlp papers" in last_message  # Verify context is maintained