feat: setup talk2comp (#67)

* feat: initialize agents package with main and s2 agent exports

* feat: implement main supervisor agent with LangGraph routing

* feat: add Semantic Scholar agent with ReAct pattern

* feat: initialize Semantic Scholar tools package

* feat: implement paper search tool with pagination

* feat: add single paper recommendation tool

* feat: implement multi-paper recommendation tool

* feat: add results display formatting tool

* feat: initialize utils package

* feat: add LLM manager with OpenAI integration and tool binding

* feat: initialize testing package

* feat: add test configuration and fixtures

* feat: implement comprehensive test suite for agents and tools

* feat: add Streamlit configuration for UI customization

* feat: implement Streamlit chat interface with session management

* feat: add centralized configuration with system prompts and API settings

* feat: implement shared state management for agent communication

* fix: update

* feat: update

* chore: remove outdated streamlit application

* chore: Ignored macOS specific metadata file

* chore: Fixed zsh bad assignment error for OPENAI_API_KEY env variable

* feat: Used Command instead of AIMessage for return and added year specifc search

* feat: added year based search capabilities, and used Dict instead of list

* feat: updated to use Dict instead of list for strcutured ouput

* fix: updated the system prompts

* fix: string length for pylint test

* fix: added Unit and integration tests for Talk2Competitors

* fix: __init__ paths for PyPI

* fix: __init__ paths for PyPI

* feat: tutorial for talk2competitors

* feat: tools documentation for MkDocs

* feat: state documentation for MkDocs

* feat: agents documentation for MkDocs

* feat: Introduction documentation for Talk2Competitors

* feat: MkDocs documentation for Talk2Competitors

* fix: update

* fix: update for Zotero

* fix: Add complete example for loading API key with dummy .env path

* fix: pylint missing docstrings

* fix: line length issues (C0301) by breaking long lines into multiple lines

* chore: update README and pyproject.toml

---------

Co-authored-by: gurdeep330 <gurdeep330@gmail.com>

Author: ansh-info

.gitignore

@@ -163,4 +163,7 @@ cython_debug/
 experiment/web/vectordb
 
 # Streamlit
-.streamlit/secrets.toml
+.streamlit/secrets.toml
+
+# macOS metadata file
+.DS_Store

README.md

@@ -2,6 +2,9 @@
 [![Talk2Cells](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2cells.yml/badge.svg)](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2cells.yml)
 [![Talk2KnowledgeGraphs](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2knowledgegraphs.yml/badge.svg)](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2knowledgegraphs.yml)
 [![Talk2Competitors](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2competitors.yml/badge.svg)](https://github.com/VirtualPatientEngine/AIAgents4Pharma/actions/workflows/tests_talk2competitors.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.github.com%2FVirtualPatientEngine%2FAIAgents4Pharma%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
+
 
 <h1 align="center" style="border-bottom: none;">🤖 AIAgents4Pharma</h1>
 
@@ -10,9 +13,9 @@ Welcome to **AIAgents4Pharma** – an open-source project by [Team VPE](https://
 Our toolkit currently consists of three intelligent agents, each designed to simplify and enhance access to specialized data in biology:
 
 - **Talk2BioModels**: Engage directly with mathematical models in systems biology.
-- **Talk2Cells** *(Work in progress)*: Query and analyze sequencing data with ease.
-- **Talk2KnowledgeGraphs** *(Work in progress)*: Access and explore complex biological knowledge graphs for insightful data connections.
-- **Talk2Competitors** *(Coming soon)*: Get recommendations for articles related to your choice. Download, query, and write/retrieve them to your reference manager (currently supporting Zotero).
+- **Talk2Cells** _(Work in progress)_: Query and analyze sequencing data with ease.
+- **Talk2KnowledgeGraphs** _(Work in progress)_: Access and explore complex biological knowledge graphs for insightful data connections.
+- **Talk2Competitors** _(Coming soon)_: Get recommendations for articles related to your choice. Download, query, and write/retrieve them to your reference manager (currently supporting Zotero).
 
 ---
 
@@ -26,15 +29,15 @@ Our toolkit currently consists of three intelligent agents, each designed to sim
 - Adjust parameters within the model to simulate different conditions.
 - Query simulation results.
 
-### 2. Talk2Cells *(Work in Progress)*
+### 2. Talk2Cells _(Work in Progress)_
 
 **Talk2Cells** is being developed to provide direct access to and analysis of sequencing data, such as RNA-Seq or DNA-Seq, using natural language.
 
-### 3. Talk2KnowledgeGraphs *(Work in Progress)*
+### 3. Talk2KnowledgeGraphs _(Work in Progress)_
 
 **Talk2KnowledgeGraphs** is an agent designed to enable interaction with biological knowledge graphs (KGs). KGs integrate vast amounts of structured biological data into a format that highlights relationships between entities, such as proteins, genes, and diseases.
 
-### 4. Talk2KnowledgeGraphs *(Coming soon)*
+### 4. Talk2Competitors _(Coming soon)_
 
 ## Getting Started
 
@@ -45,48 +48,60 @@ Our toolkit currently consists of three intelligent agents, each designed to sim
 - Required libraries specified in `requirements.txt`
 
 ### Installation
+
 #### Option 1: PyPI
-   ```bash
-   pip install aiagents4pharma
-   ```
+
+```bash
+pip install aiagents4pharma
+```
 
 Check out the tutorials on each agent for detailed instrcutions.
 
 #### Option 2: git
+
 1. **Clone the repository:**
+
    ```bash
    git clone https://github.com/VirtualPatientEngine/AIAgents4Pharma
    cd AIAgents4Pharma
    ```
 
 2. **Install dependencies:**
+
    ```bash
    pip install .
    ```
 
 3. **Initialize OPENAI_API_KEY**
+
    ```bash
-   export OPENAI_API_KEY = ....
+   export OPENAI_API_KEY=....
    ```
 
 4. **[Optional] Set up login credentials**
+
    ```bash
    vi .streamlit/secrets.toml
    ```
+
    and enter
+
    ```
    password='XXX'
    ```
-   Please note that the passowrd will be same for all the users.
+
+   Please note that the passoword will be same for all the users.
 
 5. **[Optional] Initialize LANGSMITH_API_KEY**
+
    ```bash
    export LANGCHAIN_TRACING_V2=true
    export LANGCHAIN_API_KEY=<your-api-key>
    ```
-   Please note that this will create a new tracing project in your Langsmith 
-   account with the name `<user_name>@<uuid>`, where `user_name` is the name 
-   you provided in the previous step. If you skip the previous step, it will 
+
+   Please note that this will create a new tracing project in your Langsmith
+   account with the name `<user_name>@<uuid>`, where `user_name` is the name
+   you provided in the previous step. If you skip the previous step, it will
    default to `default`. <uuid> will be the 128 bit unique ID created for the
    session.
 
@@ -118,6 +133,7 @@ We welcome contributions to AIAgents4Pharma! Here’s how you can help:
 5. **Open a pull request**
 
 ### Current Needs
+
 - **Beta testers** for Talk2BioModels.
 - **Developers** with experience in natural language processing, bioinformatics, or knowledge graphs for contributions to AIAgents4Pharma.
 
@@ -128,19 +144,22 @@ Check out our [CONTRIBUTING.md](CONTRIBUTING.md) for more information.
 ## Roadmap
 
 ### Completed
+
 - **Talk2BioModels**: Initial release with core capabilities for interacting with systems biology models.
 
 ### Planned
+
 - **User Interface**: Interactive web UI for all agents.
 - **Talk2Cells**: Integration of sequencing data analysis tools.
 - **Talk2KnowledgeGraphs**: Interface for biological knowledge graph interaction.
-- **Talk2Competitors**
+- **Talk2Competitors**: Interface for exploring articles
 
-We’re excited to bring AIAgents4Pharma to the bioinformatics and pharmaceutical research community. Together, let’s make data-driven biological research more accessible and insightful. 
+We’re excited to bring AIAgents4Pharma to the bioinformatics and pharmaceutical research community. Together, let’s make data-driven biological research more accessible and insightful.
 
 **Get Started** with AIAgents4Pharma today and transform the way you interact with biological data.
 
 ---
 
 ## Feedback
+
 Questions/Bug reports/Feature requests/Comments/Suggestions? We welcome all. Please use the `Isssues` tab 😀

aiagents4pharma/__init__.py

@@ -1,8 +1,11 @@
-'''
+"""
 This file is used to import aiagents4pharma modules.
-'''
+"""
 
-from . import talk2biomodels
-from . import talk2cells
-from . import talk2knowledgegraphs
-from . import configs
+from . import (
+    configs,
+    talk2biomodels,
+    talk2cells,
+    talk2competitors,
+    talk2knowledgegraphs,
+)

aiagents4pharma/talk2competitors/__init__.py

@@ -0,0 +1,5 @@
+"""
+This file is used to import all the modules in the package.
+"""
+
+from . import agents, config, state, tests, tools

aiagents4pharma/talk2competitors/agents/__init__.py

@@ -0,0 +1,6 @@
+'''
+This file is used to import all the modules in the package.
+'''
+
+from . import main_agent
+from . import s2_agent

aiagents4pharma/talk2competitors/agents/main_agent.py

@@ -0,0 +1,130 @@
+#!/usr/bin/env python3
+
+"""
+Main agent for the talk2competitors app.
+"""
+
+import logging
+from typing import Literal
+from dotenv import load_dotenv
+from langchain_core.language_models.chat_models import BaseChatModel
+from langchain_core.messages import AIMessage
+from langchain_openai import ChatOpenAI
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import END, START, StateGraph
+from langgraph.types import Command
+from ..agents import s2_agent
+from ..config.config import config
+from ..state.state_talk2competitors import Talk2Competitors
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+load_dotenv()
+
+def make_supervisor_node(llm: BaseChatModel) -> str:
+    """
+    Creates a supervisor node following LangGraph patterns.
+
+    Args:
+        llm (BaseChatModel): The language model to use for generating responses.
+
+    Returns:
+        str: The supervisor node function.
+    """
+    # options = ["FINISH", "s2_agent"]
+
+    def supervisor_node(state: Talk2Competitors) -> Command[Literal["s2_agent", "__end__"]]:
+        """
+        Supervisor node that routes to appropriate sub-agents.
+
+        Args:
+            state (Talk2Competitors): The current state of the conversation.
+
+        Returns:
+            Command[Literal["s2_agent", "__end__"]]: The command to execute next.
+        """
+        logger.info("Supervisor node called")
+
+        messages = [{"role": "system", "content": config.MAIN_AGENT_PROMPT}] + state[
+            "messages"
+        ]
+        response = llm.invoke(messages)
+        goto = (
+            "FINISH"
+            if not any(
+                kw in state["messages"][-1].content.lower()
+                for kw in ["search", "paper", "find"]
+            )
+            else "s2_agent"
+        )
+
+        if goto == "FINISH":
+            return Command(
+                goto=END,
+                update={
+                    "messages": state["messages"]
+                    + [AIMessage(content=response.content)],
+                    "is_last_step": True,
+                    "current_agent": None,
+                },
+            )
+
+        return Command(
+            goto="s2_agent",
+            update={
+                "messages": state["messages"],
+                "is_last_step": False,
+                "current_agent": "s2_agent",
+            },
+        )
+
+    return supervisor_node
+
+def get_app(thread_id: str, llm_model ='gpt-4o-mini') -> StateGraph:
+    """
+    Returns the langraph app with hierarchical structure.
+
+    Args:
+        thread_id (str): The thread ID for the conversation.
+
+    Returns:
+        The compiled langraph app.
+    """
+    def call_s2_agent(state: Talk2Competitors) -> Command[Literal["__end__"]]:
+        """
+        Node for calling the S2 agent.
+
+        Args:
+            state (Talk2Competitors): The current state of the conversation.
+
+        Returns:
+            Command[Literal["__end__"]]: The command to execute next.
+        """
+        logger.info("Calling S2 agent")
+        app = s2_agent.get_app(thread_id, llm_model)
+        response = app.invoke(state)
+        logger.info("S2 agent completed")
+        return Command(
+            goto=END,
+            update={
+                "messages": response["messages"],
+                "papers": response.get("papers", []),
+                "is_last_step": True,
+                "current_agent": "s2_agent",
+            },
+        )
+    llm = ChatOpenAI(model=llm_model, temperature=0)
+    workflow = StateGraph(Talk2Competitors)
+
+    supervisor = make_supervisor_node(llm)
+    workflow.add_node("supervisor", supervisor)
+    workflow.add_node("s2_agent", call_s2_agent)
+
+    # Define edges
+    workflow.add_edge(START, "supervisor")
+    workflow.add_edge("s2_agent", END)
+
+    app = workflow.compile(checkpointer=MemorySaver())
+    logger.info("Main agent workflow compiled")
+    return app

aiagents4pharma/talk2competitors/agents/s2_agent.py

@@ -0,0 +1,75 @@
+#/usr/bin/env python3
+
+'''
+Agent for interacting with Semantic Scholar
+'''
+
+import logging
+from dotenv import load_dotenv
+from langchain_openai import ChatOpenAI
+from langgraph.graph import START, StateGraph
+from langgraph.prebuilt import create_react_agent
+from langgraph.checkpoint.memory import MemorySaver
+from ..config.config import config
+from ..state.state_talk2competitors import Talk2Competitors
+# from ..tools.s2 import s2_tools
+from ..tools.s2.search import search_tool
+from ..tools.s2.display_results import display_results
+from ..tools.s2.single_paper_rec import get_single_paper_recommendations
+from ..tools.s2.multi_paper_rec import get_multi_paper_recommendations
+
+load_dotenv()
+
+# Initialize logger
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+def get_app(uniq_id, llm_model='gpt-4o-mini'):
+    '''
+    This function returns the langraph app.
+    '''
+    def agent_s2_node(state: Talk2Competitors):
+        '''
+        This function calls the model.
+        '''
+        logger.log(logging.INFO, "Creating Agent_S2 node with thread_id %s", uniq_id)
+        response = model.invoke(state, {"configurable": {"thread_id": uniq_id}})
+        return response
+
+    # Define the tools
+    tools = [search_tool,
+            display_results,
+            get_single_paper_recommendations,
+            get_multi_paper_recommendations]
+
+    # Create the LLM
+    llm = ChatOpenAI(model=llm_model, temperature=0)
+    model = create_react_agent(
+                            llm,
+                            tools=tools,
+                            state_schema=Talk2Competitors,
+                            state_modifier=config.S2_AGENT_PROMPT,
+                            checkpointer=MemorySaver()
+                        )
+
+    # Define a new graph
+    workflow = StateGraph(Talk2Competitors)
+
+    # Define the two nodes we will cycle between
+    workflow.add_node("agent_s2", agent_s2_node)
+
+    # Set the entrypoint as `agent`
+    # This means that this node is the first one called
+    workflow.add_edge(START, "agent_s2")
+
+    # Initialize memory to persist state between graph runs
+    checkpointer = MemorySaver()
+
+    # Finally, we compile it!
+    # 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")
+
+    return app

aiagents4pharma/talk2competitors/config/__init__.py

@@ -0,0 +1,5 @@
+"""
+This package contains configuration settings and prompts used by various AI agents
+"""
+
+from . import config