aiagents4pharma 1.28.0__tar.gz → 1.29.0__tar.gz

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: aiagents4pharma
-Version: 1.28.0
+Version: 1.29.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
@@ -91,6 +91,7 @@ Our toolkit currently consists of the following agents:
 ![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)
 
 ### Installation
+
 _Please use version 1.26.2 or later for better support with NVIDIA NIM models._
 
 #### Option 1: PyPI
@@ -135,10 +136,10 @@ cd AIAgents4Pharma/aiagents4pharma/talk2knowledgegraphs
    LANGCHAIN_TRACING_V2=true
    LANGCHAIN_API_KEY=your_langchain_api_key_here
    # Notes:
-   # - The API endpoint for Ollama is already set in env.example.
-   # - Both API keys (OPENAI_API_KEY and NVIDIA_API_KEY) are required for Talk2AIAgents4Pharma.
-   # - If using Talk2KnowledgeGraphs separately, only the OPENAI_API_KEY is needed.
-   # - Langsmith API for tracing is optional for both, set it in env.example if required.
+   # The API endpoint for Ollama is already set in env.example.
+   # Both API keys (OPENAI_API_KEY and NVIDIA_API_KEY) are required for Talk2AIAgents4Pharma.
+   # If using Talk2KnowledgeGraphs separately, only the OPENAI_API_KEY is needed.
+   # Langsmith API for tracing is optional for both, set it in env.example if required.
    ```
 
 4. Save the file.

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/README.md

@@ -26,6 +26,7 @@ Our toolkit currently consists of the following agents:
 ![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)
 
 ### Installation
+
 _Please use version 1.26.2 or later for better support with NVIDIA NIM models._
 
 #### Option 1: PyPI
@@ -70,10 +71,10 @@ cd AIAgents4Pharma/aiagents4pharma/talk2knowledgegraphs
    LANGCHAIN_TRACING_V2=true
    LANGCHAIN_API_KEY=your_langchain_api_key_here
    # Notes:
-   # - The API endpoint for Ollama is already set in env.example.
-   # - Both API keys (OPENAI_API_KEY and NVIDIA_API_KEY) are required for Talk2AIAgents4Pharma.
-   # - If using Talk2KnowledgeGraphs separately, only the OPENAI_API_KEY is needed.
-   # - Langsmith API for tracing is optional for both, set it in env.example if required.
+   # The API endpoint for Ollama is already set in env.example.
+   # Both API keys (OPENAI_API_KEY and NVIDIA_API_KEY) are required for Talk2AIAgents4Pharma.
+   # If using Talk2KnowledgeGraphs separately, only the OPENAI_API_KEY is needed.
+   # Langsmith API for tracing is optional for both, set it in env.example if required.
    ```
 
 4. Save the file.

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

@@ -0,0 +1,78 @@
+#!/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.
+"""
+
+import logging
+import hydra
+from langgraph_supervisor import create_supervisor
+from langchain_openai import ChatOpenAI
+from langchain_core.language_models.chat_models import BaseChatModel
+from langgraph.checkpoint.memory import MemorySaver
+from ..agents.s2_agent import get_app as get_app_s2
+from ..agents.zotero_agent import get_app as get_app_zotero
+from ..state.state_talk2scholars import Talk2Scholars
+
+# Initialize logger
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def get_app(uniq_id, llm_model: BaseChatModel):
+    """
+    Initializes and returns the LangGraph-based hierarchical agent system.
+
+    This function constructs the agent workflow by defining nodes for the supervisor
+    and sub-agents. It compiles the graph using `StateGraph` to enable structured
+    conversational workflows.
+
+    Args:
+        thread_id (str): A unique session identifier for tracking conversation state.
+        llm_model (BaseChatModel, optional): The language model used for query processing.
+            Defaults to `ChatOpenAI(model="gpt-4o-mini", temperature=0)`.
+
+    Returns:
+        StateGraph: A compiled LangGraph application that can process user queries.
+
+    Example:
+        >>> app = get_app("thread_123")
+        >>> result = app.invoke(initial_state)
+    """
+    if llm_model.model_name == "gpt-4o-mini":
+        llm_model = ChatOpenAI(
+            model="gpt-4o-mini",
+            temperature=0,
+            model_kwargs={"parallel_tool_calls": False},
+        )
+    # Load hydra configuration
+    logger.log(logging.INFO, "Launching Talk2Scholars with thread_id %s", uniq_id)
+    with hydra.initialize(version_base=None, config_path="../configs/"):
+        cfg = hydra.compose(
+            config_name="config", overrides=["agents/talk2scholars/main_agent=default"]
+        )
+        cfg = cfg.agents.talk2scholars.main_agent
+    logger.log(logging.INFO, "System_prompt of Talk2Scholars: %s", cfg.system_prompt)
+    # Create supervisor workflow
+    workflow = create_supervisor(
+        [
+            get_app_s2(uniq_id, llm_model),  # semantic scholar
+            get_app_zotero(uniq_id, llm_model),  # zotero
+        ],
+        model=llm_model,
+        state_schema=Talk2Scholars,
+        # Full history is needed to extract
+        # the tool artifacts
+        output_mode="full_history",
+        add_handoff_back_messages=False,
+        prompt=cfg.system_prompt,
+    )
+
+    # Compile and run
+    app = workflow.compile(checkpointer=MemorySaver(), name="Talk2Scholars_MainAgent")
+
+    return app

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/aiagents4pharma/talk2scholars/agents/s2_agent.py

@@ -28,9 +28,7 @@ logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
-def get_app(
-    uniq_id, llm_model: BaseChatModel
-):
+def get_app(uniq_id, llm_model: BaseChatModel):
     """
     Initializes and returns the LangGraph application for the Semantic Scholar (S2) agent.
 
@@ -86,6 +84,7 @@ def get_app(
             config_name="config", overrides=["agents/talk2scholars/s2_agent=default"]
         )
         cfg = cfg.agents.talk2scholars.s2_agent
+        logger.log(logging.INFO, "Loaded configuration for S2 agent")
 
     # Define the tools
     tools = ToolNode(
@@ -107,7 +106,7 @@ def get_app(
         llm_model,
         tools=tools,
         state_schema=Talk2Scholars,
-        state_modifier=cfg.s2_agent,
+        prompt=cfg.s2_agent,
         checkpointer=MemorySaver(),
     )
 
@@ -122,7 +121,12 @@ def get_app(
     # This compiles it into a LangChain Runnable,
     # meaning you can use it as you would any other runnable.
     # Note that we're (optionally) passing the memory when compiling the graph
-    app = workflow.compile(checkpointer=checkpointer)
-    logger.log(logging.INFO, "Compiled the graph")
+    app = workflow.compile(checkpointer=checkpointer, name="agent_s2")
+    logger.log(
+        logging.INFO,
+        "Compiled the graph with thread_id %s and llm_model %s",
+        uniq_id,
+        llm_model,
+    )
 
     return app

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/aiagents4pharma/talk2scholars/agents/zotero_agent.py

@@ -14,6 +14,7 @@ from langgraph.prebuilt import create_react_agent, ToolNode
 from langgraph.checkpoint.memory import MemorySaver
 from ..state.state_talk2scholars import Talk2Scholars
 from ..tools.zotero.zotero_read import zotero_search_tool
+from ..tools.zotero.zotero_write import zotero_save_tool
 from ..tools.s2.display_results import display_results as s2_display
 from ..tools.s2.query_results import query_results as s2_query_results
 from ..tools.s2.retrieve_semantic_scholar_paper_id import (
@@ -25,9 +26,7 @@ logging.basicConfig(level=logging.INFO)
 logger = logging.getLogger(__name__)
 
 
-def get_app(
-    uniq_id, llm_model: BaseChatModel
-):
+def get_app(uniq_id, llm_model: BaseChatModel):
     """
     Initializes and returns the LangGraph application for the Zotero agent.
 
@@ -83,6 +82,7 @@ def get_app(
             overrides=["agents/talk2scholars/zotero_agent=default"],
         )
         cfg = cfg.agents.talk2scholars.zotero_agent
+        logger.log(logging.INFO, "Loaded configuration for Zotero agent")
 
     # Define the tools
     tools = ToolNode(
@@ -91,6 +91,7 @@ def get_app(
             s2_display,
             s2_query_results,
             retrieve_semantic_scholar_paper_id,
+            zotero_save_tool,
         ]
     )
 
@@ -102,7 +103,7 @@ def get_app(
         llm_model,
         tools=tools,
         state_schema=Talk2Scholars,
-        state_modifier=cfg.zotero_agent,
+        prompt=cfg.zotero_agent,
         checkpointer=MemorySaver(),
     )
 
@@ -114,7 +115,12 @@ def get_app(
     checkpointer = MemorySaver()
 
     # Compile the graph
-    app = workflow.compile(checkpointer=checkpointer)
-    logger.log(logging.INFO, "Compiled the graph")
+    app = workflow.compile(checkpointer=checkpointer, name="agent_zotero")
+    logger.log(
+        logging.INFO,
+        "Compiled the graph with thread_id %s and llm_model %s",
+        uniq_id,
+        llm_model,
+    )
 
     return app

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

@@ -0,0 +1,13 @@
+_target_: agents.main_agent.get_app
+temperature: 0
+system_prompt: >
+  You are the Talk2Scholars agent coordinating academic paper discovery and analysis.
+
+  You have access to the following agents:
+  1. S2_agent: This agent can be used to search and recommend papers
+     from Semantic Scholar. Use this agent when the user asks for
+     general paper searches and recommendations.
+  2. Zotero_agent: This agent can be used to retrieve, display, and query
+     papers from the Zotero library. Use this agent only when the user
+     explicitly asks for papers from Zotero. This tool can also be used to
+     save papers in under collections in the zotero library

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

@@ -0,0 +1,19 @@
+_target_: agents.s2_agent.get_app
+s2_agent: >
+  You are an academic research assistant with access to the
+  Semantic Scholar API for paper discovery and analysis.
+
+  AVAILABLE TOOLS:
+  1. search - Search for academic papers by query string
+  2. display_results - Display the papers retrieved by other tools
+  3. single_paper_rec - Get recommendations based on a SINGLE paper
+  4. multi_paper_rec - Get recommendations based on MULTIPLE papers
+  5. query_results - Ask questions about the current set of papers
+  6. retrieve_semantic_scholar_paper_id - Get Semantic Scholar ID for a paper title
+
+  WORKFLOW STEPS:
+  1. When user requests papers, use search/recommendation tools to find papers
+  2. Use `display_results` tool to display the response from the search/recommendation tools 
+  3. Use `query_results` tool to query over the selected paper only when the user asks to
+  4. When the user wants recommendations, you can get the "paper_id" using `query_results` tool in the "last_displayed_results" key, then
+     pass the "paper_id" to `search`, `single_paper_rec` or `multi_paper_rec` tools depending on the user's query. Do not use "arxiv_id"

aiagents4pharma-1.29.0/aiagents4pharma/talk2scholars/configs/agents/talk2scholars/zotero_agent/default.yaml

@@ -0,0 +1,19 @@
+target: agents.zotero_agent.get_app
+zotero_agent: >
+  You are a specialized Zotero library agent with access to tools for paper retrieval and management.
+
+  AVAILABLE TOOLS:
+  1. zotero_search_tool - Search and retrieve papers from Zotero library
+  2. display_results - Display the papers retrieved by other tools
+  3. query_results - Ask questions about the current set of papers
+  4. retrieve_semantic_scholar_paper_id - Get Semantic Scholar ID for a paper title for the papers from zotero library
+  5. zotero_write - Save paper to users zotero library under specfied collections
+
+
+  WORKFLOW STEPS
+  1. When user requests papers, use `zotero_search_tool` to find papers
+  2. Use `display_results` tool to display the response
+  3. Use `query_results` tool to query over the selected paper only when the user asks to
+  4. Use `retrieve_semantic_scholar_paper_id` to get the semantic scholar id of a paper title for the papers from zotero library
+  5. Use `zotero_write` to save the papers to users zotero library under collections and call `display_results` only after you recive
+     the save was successfull

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/aiagents4pharma/talk2scholars/configs/config.yaml

@@ -11,3 +11,4 @@ defaults:
   - tools/retrieve_semantic_scholar_paper_id: default
   - tools/question_and_answer: default
   - tools/zotero_read: default
+  - tools/zotero_write: default

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/aiagents4pharma/talk2scholars/configs/tools/__init__.py

@@ -7,3 +7,4 @@ from . import single_paper_recommendation
 from . import multi_paper_recommendation
 from . import question_and_answer
 from . import zotero_read
+from . import zotero_write

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/aiagents4pharma/talk2scholars/configs/tools/multi_paper_recommendation/default.yaml

@@ -9,8 +9,8 @@ api_fields:
   - "authors"
   - "citationCount"
   - "url"
+  - "externalIds"
 # Commented fields that could be added later if needed
-# - "externalIds"
 
 # Default headers and params
 headers:

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/aiagents4pharma/talk2scholars/configs/tools/search/default.yaml

@@ -9,8 +9,8 @@ api_fields:
   - "authors"
   - "citationCount"
   - "url"
+  - "externalIds"
 # Commented fields that could be added later if needed
-# - "externalIds"
 #  - "publicationTypes"
 #  - "openAccessPdf"
 

{aiagents4pharma-1.28.0 → aiagents4pharma-1.29.0}/aiagents4pharma/talk2scholars/configs/tools/single_paper_recommendation/default.yaml

@@ -9,8 +9,8 @@ api_fields:
   - "authors"
   - "citationCount"
   - "url"
+  - "externalIds"
 # Commented fields that could be added later if needed
-# - "externalIds"
 #  - "publicationTypes"
 #  - "openAccessPdf"
 

aiagents4pharma-1.29.0/aiagents4pharma/talk2scholars/configs/tools/zotero_read/default.yaml

@@ -0,0 +1,56 @@
+# Default configuration for Zotero search tool
+library_type: "user" # Type of library ('user' or 'group')
+default_limit: 2
+request_timeout: 10
+user_id: ${oc.env:ZOTERO_USER_ID} # Load from environment variable
+api_key: ${oc.env:ZOTERO_API_KEY} # Load from environment variable
+
+# Default search parameters
+search_params:
+  limit: ${.default_limit}
+
+# Item Types and Limit
+zotero:
+  max_limit: 100
+  filter_item_types:
+    [
+      "Artwork",
+      "Audio Recording",
+      "Bill",
+      "Blog Post",
+      "Book",
+      "Book Section",
+      "Case",
+      "Conference Paper",
+      "Dataset",
+      "Dictionary Entry",
+      "Document",
+      "E-mail",
+      "Encyclopedia Article",
+      "Film",
+      "Forum Post",
+      "Hearing",
+      "Instant Message",
+      "Interview",
+      "Journal Article",
+      "Letter",
+      "Magazine Article",
+      "Manuscript",
+      "Map",
+      "Newspaper Article",
+      "Patent",
+      "Podcast",
+      "Preprint",
+      "Presentation",
+      "Radio Broadcast",
+      "Report",
+      "Software",
+      "Standard",
+      "Statute",
+      "Thesis",
+      "TV Broadcast",
+      "Video Recording",
+      "Web Page",
+    ]
+
+  filter_excluded_types: ["attachment", "note", "annotation"]

aiagents4pharma-1.29.0/aiagents4pharma/talk2scholars/configs/tools/zotero_write/__inti__.py

@@ -0,0 +1,3 @@
+"""
+Import all the modules in the package
+"""

aiagents4pharma-1.29.0/aiagents4pharma/talk2scholars/tests/test_main_agent.py

@@ -0,0 +1,196 @@
+"""
+Unit tests for main agent functionality.
+Tests the supervisor agent's routing logic and state management.
+"""
+
+# pylint: disable=redefined-outer-name,too-few-public-methods
+
+from types import SimpleNamespace
+import pytest
+import hydra
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_openai import ChatOpenAI
+from pydantic import Field
+from aiagents4pharma.talk2scholars.agents.main_agent import get_app
+
+# --- Dummy LLM Implementation ---
+
+
+class DummyLLM(BaseChatModel):
+    """A dummy language model implementation for testing purposes."""
+
+    model_name: str = Field(...)
+
+    def _generate(self, prompt, stop=None):
+        """Generate a response given a prompt."""
+        DummyLLM.called_prompt = prompt
+        return "dummy output"
+
+    @property
+    def _llm_type(self):
+        """Return the type of the language model."""
+        return "dummy"
+
+
+# --- Dummy Workflow and Sub-agent Functions ---
+
+
+class DummyWorkflow:
+    """A dummy workflow class that records arguments for verification."""
+
+    def __init__(self, supervisor_args=None):
+        """Initialize the workflow with the given supervisor arguments."""
+        self.supervisor_args = supervisor_args or {}
+        self.checkpointer = None
+        self.name = None
+
+    def compile(self, checkpointer, name):
+        """Compile the workflow with the given checkpointer and name."""
+        self.checkpointer = checkpointer
+        self.name = name
+        return self
+
+
+def dummy_get_app_s2(uniq_id, llm_model):
+    """Return a DummyWorkflow for the S2 agent."""
+    dummy_get_app_s2.called_uniq_id = uniq_id
+    dummy_get_app_s2.called_llm_model = llm_model
+    return DummyWorkflow(supervisor_args={"agent": "s2", "uniq_id": uniq_id})
+
+
+def dummy_get_app_zotero(uniq_id, llm_model):
+    """Return a DummyWorkflow for the Zotero agent."""
+    dummy_get_app_zotero.called_uniq_id = uniq_id
+    dummy_get_app_zotero.called_llm_model = llm_model
+    return DummyWorkflow(supervisor_args={"agent": "zotero", "uniq_id": uniq_id})
+
+
+def dummy_create_supervisor(apps, model, state_schema, **kwargs):
+    """Return a DummyWorkflow for the supervisor."""
+    dummy_create_supervisor.called_kwargs = kwargs
+    return DummyWorkflow(
+        supervisor_args={
+            "apps": apps,
+            "model": model,
+            "state_schema": state_schema,
+            **kwargs,
+        }
+    )
+
+
+# --- Dummy Hydra Configuration Setup ---
+
+
+class DummyHydraContext:
+    """A dummy context manager for mocking Hydra's initialize and compose functions."""
+
+    def __enter__(self):
+        """Return None when entering the context."""
+        return None
+
+    def __exit__(self, exc_type, exc_val, traceback):
+        """Exit function that does nothing."""
+        return None
+
+
+def dict_to_namespace(d):
+    """Convert a dictionary to a SimpleNamespace object."""
+    return SimpleNamespace(
+        **{
+            key: dict_to_namespace(val) if isinstance(val, dict) else val
+            for key, val in d.items()
+        }
+    )
+
+
+dummy_config = {
+    "agents": {
+        "talk2scholars": {"main_agent": {"system_prompt": "Dummy system prompt"}}
+    }
+}
+
+
+class DummyHydraCompose:
+    """A dummy class that returns a namespace from a dummy config dictionary."""
+
+    def __init__(self, config):
+        """Constructor that stores the dummy config."""
+        self.config = config
+
+    def __getattr__(self, item):
+        """Return a namespace from the dummy config."""
+        return dict_to_namespace(self.config.get(item, {}))
+
+
+# --- Pytest Fixtures to Patch Dependencies ---
+
+
+@pytest.fixture(autouse=True)
+def patch_hydra(monkeypatch):
+    """Patch the hydra.initialize and hydra.compose functions to return dummy objects."""
+    monkeypatch.setattr(
+        hydra, "initialize", lambda version_base, config_path: DummyHydraContext()
+    )
+    monkeypatch.setattr(
+        hydra, "compose", lambda config_name, overrides: DummyHydraCompose(dummy_config)
+    )
+
+
+@pytest.fixture(autouse=True)
+def patch_sub_agents_and_supervisor(monkeypatch):
+    """Patch the sub-agents and supervisor creation functions."""
+    monkeypatch.setattr(
+        "aiagents4pharma.talk2scholars.agents.main_agent.get_app_s2", dummy_get_app_s2
+    )
+    monkeypatch.setattr(
+        "aiagents4pharma.talk2scholars.agents.main_agent.get_app_zotero",
+        dummy_get_app_zotero,
+    )
+    monkeypatch.setattr(
+        "aiagents4pharma.talk2scholars.agents.main_agent.create_supervisor",
+        dummy_create_supervisor,
+    )
+
+
+# --- Test Cases ---
+
+
+def test_dummy_llm_generate():
+    """Test the dummy LLM's generate function."""
+    dummy = DummyLLM(model_name="test-model")
+    output = getattr(dummy, "_generate")("any prompt")
+    assert output == "dummy output"
+
+
+def test_dummy_llm_llm_type():
+    """Test the dummy LLM's _llm_type property."""
+    dummy = DummyLLM(model_name="test-model")
+    assert getattr(dummy, "_llm_type") == "dummy"
+
+
+def test_get_app_with_gpt4o_mini():
+    """
+    Test that get_app replaces a 'gpt-4o-mini' LLM with a new ChatOpenAI instance.
+    """
+    uniq_id = "test_thread"
+    dummy_llm = DummyLLM(model_name="gpt-4o-mini")
+    app = get_app(uniq_id, dummy_llm)
+
+    supervisor_args = getattr(app, "supervisor_args", {})
+    assert isinstance(supervisor_args.get("model"), ChatOpenAI)
+    assert supervisor_args.get("prompt") == "Dummy system prompt"
+    assert getattr(app, "name", "") == "Talk2Scholars_MainAgent"
+
+
+def test_get_app_with_other_model():
+    """
+    Test that get_app does not replace the LLM if its model_name is not 'gpt-4o-mini'.
+    """
+    uniq_id = "test_thread_2"
+    dummy_llm = DummyLLM(model_name="other-model")
+    app = get_app(uniq_id, dummy_llm)
+
+    supervisor_args = getattr(app, "supervisor_args", {})
+    assert supervisor_args.get("model") is dummy_llm
+    assert supervisor_args.get("prompt") == "Dummy system prompt"
+    assert getattr(app, "name", "") == "Talk2Scholars_MainAgent"

aiagents4pharma-1.29.0/aiagents4pharma/talk2scholars/tests/test_s2_display.py

@@ -0,0 +1,74 @@
+"""
+Unit tests for S2 tools functionality.
+"""
+
+# pylint: disable=redefined-outer-name
+import pytest
+from langgraph.types import Command
+from ..tools.s2.display_results import (
+    display_results,
+    NoPapersFoundError as raised_error,
+)
+
+
+@pytest.fixture
+def initial_state():
+    """Provides an empty initial state for tests."""
+    return {"papers": {}, "multi_papers": {}}
+
+
+# Fixed test data for deterministic results
+MOCK_SEARCH_RESPONSE = {
+    "data": [
+        {
+            "paperId": "123",
+            "title": "Machine Learning Basics",
+            "abstract": "An introduction to ML",
+            "year": 2023,
+            "citationCount": 100,
+            "url": "https://example.com/paper1",
+            "authors": [{"name": "Test Author"}],
+        }
+    ]
+}
+
+MOCK_STATE_PAPER = {
+    "123": {
+        "Title": "Machine Learning Basics",
+        "Abstract": "An introduction to ML",
+        "Year": 2023,
+        "Citation Count": 100,
+        "URL": "https://example.com/paper1",
+    }
+}
+
+
+class TestS2Tools:
+    """Unit tests for individual S2 tools"""
+
+    def test_display_results_empty_state(self, initial_state):
+        """Verifies display_results tool behavior when state is empty and raises an exception"""
+        with pytest.raises(
+            raised_error,
+            match="No papers found. A search/rec needs to be performed first.",
+        ):
+            display_results.invoke({"state": initial_state, "tool_call_id": "test123"})
+
+    def test_display_results_shows_papers(self, initial_state):
+        """Verifies display_results tool correctly returns papers from state"""
+        state = initial_state.copy()
+        state["last_displayed_papers"] = "papers"
+        state["papers"] = MOCK_STATE_PAPER
+
+        result = display_results.invoke(
+            input={"state": state, "tool_call_id": "test123"}
+        )
+
+        assert isinstance(result, Command)  # Expect a Command object
+        assert isinstance(result.update, dict)  # Ensure update is a dictionary
+        assert "messages" in result.update
+        assert len(result.update["messages"]) == 1
+        assert (
+            "1 papers found. Papers are attached as an artifact."
+            in result.update["messages"][0].content
+        )