aiagents4pharma 0.0.0__py3-none-any.whl

aiagents4pharma/talk2biomodels/agents/t2b_agent.py

@@ -0,0 +1,104 @@
+# /usr/bin/env python3
+
+"""
+This is the agent file for the Talk2BioModels agent.
+"""
+
+import logging
+from typing import Annotated
+
+import hydra
+from langchain_core.language_models.chat_models import BaseChatModel
+from langgraph.checkpoint.memory import MemorySaver
+from langgraph.graph import START, StateGraph
+from langgraph.prebuilt import InjectedState, ToolNode, create_react_agent
+
+from ..states.state_talk2biomodels import Talk2Biomodels
+from ..tools.ask_question import AskQuestionTool
+from ..tools.custom_plotter import CustomPlotterTool
+from ..tools.get_annotation import GetAnnotationTool
+from ..tools.get_modelinfo import GetModelInfoTool
+from ..tools.parameter_scan import ParameterScanTool
+from ..tools.query_article import QueryArticle
+from ..tools.save_model import SaveModelTool
+from ..tools.search_models import SearchModelsTool
+from ..tools.simulate_model import SimulateModelTool
+from ..tools.steady_state import SteadyStateTool
+
+# Initialize logger
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+def get_app(uniq_id, llm_model: BaseChatModel):
+    """
+    This function returns the langraph app.
+    """
+
+    def agent_t2b_node(state: Annotated[dict, InjectedState]):
+        """
+        This function calls the model.
+        """
+        logger.log(logging.INFO, "Calling t2b_agent node with thread_id %s", uniq_id)
+        response = model.invoke(state, {"configurable": {"thread_id": uniq_id}})
+        return response
+
+    # Define the tools
+    tools = ToolNode(
+        [
+            SimulateModelTool(),
+            AskQuestionTool(),
+            CustomPlotterTool(),
+            SearchModelsTool(),
+            GetModelInfoTool(),
+            SteadyStateTool(),
+            ParameterScanTool(),
+            GetAnnotationTool(),
+            QueryArticle(),
+            SaveModelTool(),
+        ]
+    )
+
+    # Load hydra configuration
+    logger.log(logging.INFO, "Load Hydra configuration for Talk2BioModels agent.")
+    with hydra.initialize(version_base=None, config_path="../configs"):
+        cfg = hydra.compose(config_name="config", overrides=["agents/t2b_agent=default"])
+        cfg = cfg.agents.t2b_agent
+    logger.log(logging.INFO, "state_modifier: %s", cfg.state_modifier)
+    # Create the agent
+    model = create_react_agent(
+        llm_model,
+        tools=tools,
+        state_schema=Talk2Biomodels,
+        prompt=cfg.state_modifier,
+        version="v2",
+        checkpointer=MemorySaver(),
+    )
+
+    # Define a new graph
+    workflow = StateGraph(Talk2Biomodels)
+
+    # Define the two nodes we will cycle between
+    workflow.add_node("agent_t2b", agent_t2b_node)
+
+    # Set the entrypoint as the first node
+    # This means that this node is the first one called
+    workflow.add_edge(START, "agent_t2b")
+
+    # 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, name="T2B_Agent")
+    logger.log(
+        logging.INFO,
+        "Compiled the graph with thread_id %s and llm_model %s",
+        uniq_id,
+        llm_model,
+    )
+
+    return app

aiagents4pharma/talk2biomodels/api/__init__.py

@@ -0,0 +1,5 @@
+"""
+This file is used to import the modules in the package.
+"""
+
+from . import ols, uniprot

aiagents4pharma/talk2biomodels/api/ols.py

@@ -0,0 +1,75 @@
+"""
+This module contains the API for fetching ols database
+"""
+
+import requests
+
+
+def fetch_from_ols(term: str) -> str:
+    """
+    Fetch the label for a single term from OLS.
+
+    Args:
+        term (str): The term in the format "ONTOLOGY:TERM_ID".
+
+    Returns:
+        str: The label for the term or an error message.
+    """
+    try:
+        ontology, _ = term.split(":")
+        base_url = f"https://www.ebi.ac.uk/ols4/api/ontologies/{ontology.lower()}/terms"
+        params = {"obo_id": term}
+        response = requests.get(
+            base_url, params=params, headers={"Accept": "application/json"}, timeout=10
+        )
+        response.raise_for_status()
+        data = response.json()
+        label = "-"
+        # Extract and return the label
+        if (
+            "_embedded" in data
+            and "terms" in data["_embedded"]
+            and len(data["_embedded"]["terms"]) > 0
+        ):
+            label = data["_embedded"]["terms"][0].get("label", "Label not found")
+        return label
+    except (requests.exceptions.RequestException, KeyError, IndexError) as e:
+        return f"Error: {str(e)}"
+
+
+def fetch_ols_labels(terms: list[str]) -> dict[str, str]:
+    """
+    Fetch labels for multiple terms from OLS.
+
+    Args:
+        terms (List[str]): A list of terms in the format "ONTOLOGY:TERM_ID".
+
+    Returns:
+        Dict[str, str]: A mapping of term IDs to their labels or error messages.
+    """
+    results = {}
+    for term in terms:
+        results[term] = fetch_from_ols(term)
+    return results
+
+
+def search_ols_labels(data: list[dict[str, str]]) -> dict[str, dict[str, str]]:
+    """
+    Fetch OLS annotations grouped by ontology type.
+
+    Args:
+        data (List[Dict[str, str]]): A list of dictionaries containing 'Id' and 'Database'.
+
+    Returns:
+        Dict[str, Dict[str, str]]: A mapping of ontology type to term labels.
+    """
+    grouped_data = {}
+    for entry in data:
+        ontology = entry["Database"].lower()
+        grouped_data.setdefault(ontology, []).append(entry["Id"])
+
+    results = {}
+    for ontology, terms in grouped_data.items():
+        results[ontology] = fetch_ols_labels(terms)
+
+    return results

aiagents4pharma/talk2biomodels/api/uniprot.py

@@ -0,0 +1,36 @@
+"""
+This module contains the API for fetching uniprot database
+"""
+
+import requests
+
+
+def search_uniprot_labels(identifiers: list[str]) -> dict[str, str]:
+    """
+    Fetch protein names or labels for a list of UniProt identifiers by making sequential requests.
+
+    Args:
+        identifiers (List[str]): A list of UniProt identifiers.
+
+    Returns:
+        Dict[str, str]: A mapping of UniProt identifiers to their protein names or error messages.
+    """
+    results = {}
+    base_url = "https://www.uniprot.org/uniprot/"
+
+    for identifier in identifiers:
+        url = f"{base_url}{identifier}.json"
+        try:
+            response = requests.get(url, timeout=10)
+            response.raise_for_status()
+            data = response.json()
+            protein_name = (
+                data.get("proteinDescription", {})
+                .get("recommendedName", {})
+                .get("fullName", {})
+                .get("value", "Name not found")
+            )
+            results[identifier] = protein_name
+        except requests.exceptions.RequestException as e:
+            results[identifier] = f"Error: {str(e)}"
+    return results

aiagents4pharma/talk2biomodels/configs/__init__.py

@@ -0,0 +1,5 @@
+"""
+Import all the modules in the package
+"""
+
+from . import agents, tools

aiagents4pharma/talk2biomodels/configs/agents/__init__.py

@@ -0,0 +1,5 @@
+"""
+Import all the modules in the package
+"""
+
+from . import t2b_agent

aiagents4pharma/talk2biomodels/configs/agents/t2b_agent/__init__.py

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

aiagents4pharma/talk2biomodels/configs/agents/t2b_agent/default.yaml

@@ -0,0 +1,14 @@
+_target_: agents.t2b_agent.get_app
+state_modifier: >
+  You are Talk2BioModels agent.
+  If the user asks for the uploaded model,
+  then pass the use_uploaded_model argument
+  as True. If the user asks for simulation
+  or param_scan or steady state, suggest a
+  value for the `experiment_name` argument.
+
+  If the user asks question related to the
+  uploaded document/pdf/article/document,
+  use the tool `query_article` to answer the
+  question. Please note that the `experiment_name`
+  argument may be unrelated to the question asked.

aiagents4pharma/talk2biomodels/configs/app/frontend/default.yaml

@@ -0,0 +1,72 @@
+_target_: app.frontend.streamlit_app_talk2biomodels
+default_user: "talk2biomodels_user"
+
+# File upload configuration
+upload_data_dir: "../files"
+sbml_allowed_file_types:
+  - "xml"
+  - "sbml"
+article_allowed_file_types:
+  - "pdf"
+
+# OpenAI configuration - can use custom base_url for enterprise/Azure deployments
+openai_api_key: ${oc.env:OPENAI_API_KEY}
+openai_base_url: ${oc.env:OPENAI_BASE_URL,null} # Optional: custom OpenAI endpoint
+openai_llms:
+  - "OpenAI/gpt-4o-mini"
+
+# Rate limiting and retry configuration
+llm_max_retries: 5  # Number of retries on rate limit or transient errors
+llm_timeout: 60     # Timeout in seconds for LLM requests
+embedding_max_retries: 3  # Number of retries for embedding requests
+embedding_timeout: 30     # Timeout in seconds for embedding requests
+
+# NVIDIA configuration
+nvidia_api_key: ${oc.env:NVIDIA_API_KEY}
+nvidia_llms:
+  - "NVIDIA/llama-3.3-70b-instruct"
+  - "NVIDIA/llama-3.1-70b-instruct"
+  - "NVIDIA/llama-3.1-405b-instruct"
+
+# Azure OpenAI configuration
+azure_openai_endpoint: ${oc.env:AZURE_OPENAI_ENDPOINT,null} # Azure OpenAI endpoint
+azure_openai_deployment: ${oc.env:AZURE_OPENAI_DEPLOYMENT,null} # Azure deployment name
+azure_openai_api_version: ${oc.env:AZURE_OPENAI_API_VERSION,"2024-02-01"} # Azure API version
+azure_openai_model_name: ${oc.env:AZURE_OPENAI_MODEL_NAME,null} # Model name for analytics
+azure_openai_model_version: ${oc.env:AZURE_OPENAI_MODEL_VERSION,null} # Model version
+# Azure AD authentication (uses AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET)
+azure_client_id: ${oc.env:AZURE_CLIENT_ID,null}
+azure_tenant_id: ${oc.env:AZURE_TENANT_ID,null}
+azure_client_secret: ${oc.env:AZURE_CLIENT_SECRET,null}
+azure_openai_llms:
+  - "Azure/gpt-4o-mini" # Will map to Azure deployment
+
+# Text embedding models
+openai_embeddings:
+  - "OpenAI/text-embedding-ada-002"
+  - "text-embedding-3-small"
+nvidia_embeddings:
+  - "NVIDIA/llama-3.2-nv-embedqa-1b-v2"
+azure_openai_embeddings:
+  - "Azure/text-embedding-ada-002"
+
+# Ollama configuration (for local deployment)
+ollama_llms:
+  - "Ollama/llama3.1:8b"
+ollama_embeddings:
+  - "nomic-embed-text"
+
+# Default models
+default_llm_provider: "openai"
+default_embedding_provider: "nvidia" # Default as per current T2B app
+
+# App settings
+temperature: 0
+streaming: true
+
+# Logo configuration
+logo_paths:
+  container: "/app/docs/assets/VPE.png"
+  local: "docs/assets/VPE.png"
+  relative: "../../docs/assets/VPE.png"
+logo_link: "https://github.com/VirtualPatientEngine"

aiagents4pharma/talk2biomodels/configs/config.yaml

@@ -0,0 +1,7 @@
+defaults:
+  - _self_
+  - agents/t2b_agent: default
+  - tools/ask_question: default
+  - tools/get_annotation: default
+  - tools/custom_plotter: default
+  - app/frontend: default

aiagents4pharma/talk2biomodels/configs/tools/__init__.py

@@ -0,0 +1,5 @@
+"""
+Import all the modules in the package
+"""
+
+from . import ask_question, custom_plotter, get_annotation

aiagents4pharma/talk2biomodels/configs/tools/ask_question/__init__.py

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

aiagents4pharma/talk2biomodels/configs/tools/ask_question/default.yaml

@@ -0,0 +1,30 @@
+_target_: tools.ask_question.AskQuestionTool
+steady_state_prompt: >
+  Following are header columns of the data:
+  `species_name`: Name of the species,
+  `compartment`: Compartment of the species,
+  `initial_concentration`: Concentration of the species at the start of steady state,
+  `steady_state_concentration`: Concentration of the species at steady state,
+  `steady_state_transition_time`: Time taken to reach steady state,
+  `display_name`: An alias for the species name.
+
+  Here are some instructions to help you answer questions:
+
+  1. If the user wants to know the time taken by the model to reach
+  steady state, you should look at the `steady_state_transition_time`
+  column of the data for the model species.
+
+  2. The highest value in the column `steady_state_transition_time`
+  is the time taken by the model to reach steady state.
+
+  3. Please use the units provided below to answer the questions.
+simulation_prompt: >
+  Following is the information about the data frame:
+  1. First column is the time column, and the rest of the columns
+  are the species names.
+
+  2. While the time column records the simulation time points, the
+  rest of the columns record the concentration of the species at
+  each time point.
+
+  3. Please use the units provided below to answer the questions.

aiagents4pharma/talk2biomodels/configs/tools/custom_plotter/__init__.py

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

aiagents4pharma/talk2biomodels/configs/tools/custom_plotter/default.yaml

@@ -0,0 +1,8 @@
+system_prompt_custom_header: >
+  You are custom plotter tool. You can extract species from the given
+  list of species names based on user question. If no species is relevant,
+  set the attribute `relevant_species` to None.
+  If the user asks for very specific species (for example, using the
+  keyword `only` or `exactly` in the question), set this attribute to
+  correspond strictly to the species available in the simulation results,
+  otherwise set it to None.

aiagents4pharma/talk2biomodels/configs/tools/get_annotation/__init__.py

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

aiagents4pharma/talk2biomodels/configs/tools/get_annotation/default.yaml

@@ -0,0 +1,8 @@
+_target_: tools.get_annotation.GetAnnotationTool
+prompt: >
+  Given the user question, extract the relevant species names.
+  If the user aks for a specific species, extract that species.
+  If none of the species match the user question, return None.
+  If the user asks for all species, return all species.
+  If the user does not specify any species or simpley asks for
+  model annotations, return all species.

aiagents4pharma/talk2biomodels/install.md

@@ -0,0 +1,63 @@
+# Talk2BioModels
+
+## Installation
+
+### Docker (stable-release)
+
+_This agent is available on Docker Hub._
+
+### Run via `docker run`
+
+```sh
+docker run -d \
+  --name talk2biomodels \
+  -e OPENAI_API_KEY=<your_openai_api_key> \
+  -e NVIDIA_API_KEY=<your_nvidia_api_key> \
+  -p 8501:8501 \
+  virtualpatientengine/talk2biomodels
+```
+
+### Access the Web UI
+
+Once started, open:
+
+```
+http://localhost:8501
+```
+
+---
+
+## Environment Variables
+
+- `OPENAI_API_KEY` – required
+- `NVIDIA_API_KEY` – required
+
+---
+
+## Get Key
+
+- `NVIDIA_API_KEY` – required (obtain a free key at [https://build.nvidia.com/explore/discover](https://build.nvidia.com/explore/discover))
+
+**LangSmith** support is optional. To enable it, create an API key [here](https://docs.smith.langchain.com/administration/how_to_guides/organization_management/create_account_api_key).
+
+_Please note that this will create a new tracing project in your Langsmith
+account with the name `T2X-xxxx`, where `X` can be `B` (Biomodels).
+If you skip the previous step, it will default to the name `default`.
+`xxxx` will be the 4-digit ID created for the session._
+
+---
+
+## Running Multiple Agents
+
+By default, this agent listens on port `8501`. To run another agent on a different port, map a different host port:
+
+```sh
+docker run -d \
+  --name talk2biomodels \
+  -e OPENAI_API_KEY=<your_openai_api_key> \
+  -e NVIDIA_API_KEY=<your_nvidia_api_key> \
+  -p 8502:8501 \
+  virtualpatientengine/talk2biomodels
+```
+
+Then visit: [http://localhost:8502](http://localhost:8502)

aiagents4pharma/talk2biomodels/models/__init__.py

@@ -0,0 +1,5 @@
+"""
+This file is used to import all the models in the package.
+"""
+
+from . import basico_model, sys_bio_model

aiagents4pharma/talk2biomodels/models/basico_model.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python3
+
+"""
+BasicoModel class for loading and simulating SBML models
+using the basico package.
+"""
+
+import logging
+
+import basico
+import pandas as pd
+from pydantic import Field, model_validator
+
+from .sys_bio_model import SysBioModel
+
+# Initialize logger
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+
+class BasicoModel(SysBioModel):
+    """
+    Model that loads and simulates SBML models using the basico package.
+    Can load models from an SBML file or download them using a BioModels biomodel_id.
+    """
+
+    biomodel_id: int | str | None = Field(
+        None, description="BioModels model ID to download and load"
+    )
+    sbml_file_path: str | None = Field(None, description="Path to an SBML file to load")
+    simulation_results: str | None = None
+    name: str | None = Field("", description="Name of the model")
+    description: str | None = Field("", description="Description of the model")
+
+    # Additional attribute not included in the schema
+    copasi_model: object | None = None  # Holds the loaded Copasi model
+
+    @model_validator(mode="after")
+    def check_biomodel_id_or_sbml_file_path(self):
+        """
+        Validate that either biomodel_id or sbml_file_path is provided.
+        """
+        if not self.biomodel_id and not self.sbml_file_path:
+            logger.error("Either biomodel_id or sbml_file_path must be provided.")
+            raise ValueError("Either biomodel_id or sbml_file_path must be provided.")
+        if self.biomodel_id:
+            self.copasi_model = basico.load_biomodel(self.biomodel_id)
+            self.description = basico.biomodels.get_model_info(self.biomodel_id)["description"]
+            self.name = basico.model_info.get_model_name(model=self.copasi_model)
+        elif self.sbml_file_path:
+            self.copasi_model = basico.load_model(self.sbml_file_path)
+            self.description = basico.model_info.get_notes(model=self.copasi_model)
+            self.name = basico.model_info.get_model_name(model=self.copasi_model)
+        return self
+
+    def update_parameters(self, parameters: dict[str, float | int]) -> None:
+        """
+        Update model parameters with new values.
+        """
+        # Update parameters in the model
+        for param_name, param_value in parameters.items():
+            # check if the param_name is not None
+            if param_name is None:
+                continue
+            # Extract all parameters and species from the model
+            df_all_params = basico.model_info.get_parameters(model=self.copasi_model)
+            df_all_species = basico.model_info.get_species(model=self.copasi_model)
+            # if param is a kinetic parameter
+            if param_name in df_all_params.index.tolist():
+                basico.model_info.set_parameters(
+                    name=param_name,
+                    exact=True,
+                    initial_value=param_value,
+                    model=self.copasi_model,
+                )
+            # if param is a species
+            elif param_name in df_all_species.index.tolist():
+                basico.model_info.set_species(
+                    name=param_name,
+                    exact=True,
+                    initial_concentration=param_value,
+                    model=self.copasi_model,
+                )
+            else:
+                logger.error("Parameter/Species %s not found in the model.", param_name)
+                raise ValueError(f"Parameter/Species {param_name} not found in the model.")
+
+    def simulate(self, duration: int | float = 10, interval: int = 10) -> pd.DataFrame:
+        """
+        Simulate the COPASI model over a specified range of time points.
+
+        Args:
+            duration: Duration of the simulation in time units.
+            interval: Interval between time points in the simulation.
+
+        Returns:
+            Pandas DataFrame with time-course simulation results.
+        """
+        # Run the simulation and return results
+        df_result = basico.run_time_course(
+            model=self.copasi_model, intervals=interval, duration=duration
+        )
+        # # Replace curly braces in column headers with square brackets
+        # # Because curly braces in the world of LLMS are used for
+        # # structured output
+        # df_result.columns = df_result.columns.str.replace('{', '[', regex=False).\
+        #             str.replace('}', ']', regex=False)
+        # Reset the index
+        df_result.reset_index(inplace=True)
+        # Store the simulation results
+        self.simulation_results = df_result
+        # Return copy of the simulation results
+        return df_result.copy()
+
+    def get_model_metadata(self) -> dict[str, str | int]:
+        """
+        Retrieve metadata specific to the COPASI model.
+
+        Returns:
+            Dictionary of model metadata.
+        """
+        return {
+            "Model Type": "SBML Model (COPASI)",
+            "Parameter Count": len(basico.get_parameters()),
+        }

aiagents4pharma/talk2biomodels/models/sys_bio_model.py

@@ -0,0 +1,60 @@
+"""
+An abstract base class for BioModels in the BioModels repository.
+"""
+
+from abc import ABC, abstractmethod
+
+from pydantic import BaseModel, Field, model_validator
+
+
+class SysBioModel(ABC, BaseModel):
+    """
+    Abstract base class for BioModels in the BioModels repository.
+    This class serves as a general structure for models, allowing
+    different mathematical approaches to be implemented in subclasses.
+    """
+
+    biomodel_id: int | None = Field(None, description="BioModel ID of the model")
+    sbml_file_path: str | None = Field(None, description="Path to an SBML file")
+    name: str | None = Field(..., description="Name of the model")
+    description: str | None = Field("", description="Description of the model")
+
+    @model_validator(mode="after")
+    def check_biomodel_id_or_sbml_file_path(self):
+        """
+        Validate that either biomodel_id or sbml_file_path is provided.
+        """
+        if not self.biomodel_id and not self.sbml_file_path:
+            raise ValueError("Either biomodel_id or sbml_file_path must be provided.")
+        return self
+
+    @abstractmethod
+    def get_model_metadata(self) -> dict[str, str | int]:
+        """
+        Abstract method to retrieve metadata of the model.
+        This method should return a dictionary containing model metadata.
+
+        Returns:
+            dict: Dictionary with model metadata
+        """
+
+    @abstractmethod
+    def update_parameters(self, parameters: dict[str, float | int]) -> None:
+        """
+        Abstract method to update model parameters.
+
+        Args:
+            parameters: Dictionary of parameter values.
+        """
+
+    @abstractmethod
+    def simulate(self, duration: int | float) -> list[float]:
+        """
+        Abstract method to run a simulation of the model.
+
+        Args:
+            duration: Duration of the simulation.
+
+        Returns:
+            list: List of simulation results.
+        """