ClassyGitshadowzzh

pubchem.py

pubchem.py

"""
PubChem MCP Server

This module provides MCP server functionality for accessing PubChem database programmatically.
It supports compound searches, property retrieval, and structure-based queries using PubChem's REST API.

Key features:
- Compound search by name, CID, SMILES, or InChI
- Property retrieval (molecular weight, formula, etc.)
- Structure similarity searches
- Bioactivity data access
- 3D structure downloads
- Rate limiting compliance (max 5 requests/second)

Main functions:
- mcp_search_compounds: Search for compounds by various identifiers
- mcp_get_compound_properties: Retrieve compound properties
- mcp_get_compound_synonyms: Get compound names and synonyms
- mcp_search_similar_compounds: Find structurally similar compounds
- mcp_get_bioactivity_data: Retrieve bioactivity assay data
- mcp_download_structure: Download 2D/3D structure files
"""

import time
import traceback
from datetime import datetime
from typing import Literal
from urllib.parse import quote

import requests
from dotenv import load_dotenv
from pydantic import BaseModel, Field
from pydantic.fields import FieldInfo

from aworld.logs.util import Color
from examples.gaia.mcp_collections.base import ActionArguments, ActionCollection, ActionResponse


# pylint: disable=C0301
class CompoundData(BaseModel):
    """Structured compound data from PubChem."""

    cid: int | None = None
    name: str | None = None
    molecular_formula: str | None = None
    molecular_weight: float | None = None
    smiles: str | None = None
    inchi: str | None = None
    synonyms: list[str] = []


class PubChemMetadata(BaseModel):
    """Metadata for PubChem operation results."""

    query_type: str
    query_value: str
    api_endpoint: str
    response_time: float
    total_results: int | None = None
    rate_limit_delay: float | None = None
    error_type: str | None = None
    timestamp: str


class PubChemCollection(ActionCollection):
    """MCP service for PubChem database access with comprehensive chemical data retrieval.

    Provides access to PubChem's extensive chemical database including:
    - Compound identification and search capabilities
    - Chemical property and structure data
    - Bioactivity and assay information
    - Structure similarity searches
    - 2D/3D molecular structure downloads
    - Synonym and nomenclature data

    Complies with PubChem usage policies:
    - Maximum 5 requests per second
    - Automatic rate limiting
    - Proper error handling for timeouts
    """

    def __init__(self, arguments: ActionArguments) -> None:
        super().__init__(arguments)

        # PubChem API configuration
        self.base_url = "https://pubchem.ncbi.nlm.nih.gov/rest/pug"
        self.base_url_view = "https://pubchem.ncbi.nlm.nih.gov/rest/pug_view"
        self.request_delay = 0.2  # 200ms delay to stay under 5 req/sec limit
        self.last_request_time = 0.0

        # Request timeout settings
        self.timeout = 30  # PubChem's 30-second limit

        # Initialize request session with headers
        self.session = requests.Session()
        self.session.headers.update(
            {"User-Agent": "AWorld-PubChem-MCP/1.0 (https://github.com/aworld-framework)", "Accept": "application/json"}
        )

        self._color_log("PubChem MCP Service initialized", Color.green, "debug")
        self._color_log(f"Base URL: {self.base_url}", Color.blue, "debug")

    def _rate_limit(self) -> float:
        """Enforce rate limiting to comply with PubChem usage policy.

        Returns:
            Actual delay time applied
        """
        current_time = time.time()
        time_since_last = current_time - self.last_request_time

        if time_since_last < self.request_delay:
            delay = self.request_delay - time_since_last
            time.sleep(delay)
            self.last_request_time = time.time()
            return delay

        self.last_request_time = current_time
        return 0.0

    def _make_request(self, url: str, params: dict = None) -> tuple[dict | None, float]:
        """Make a rate-limited request to PubChem API.

        Args:
            url: API endpoint URL
            params: Query parameters

        Returns:
            Tuple of (response_data, response_time)

        Raises:
            requests.RequestException: For API request failures
        """
        start_time = time.time()

        try:
            response = self.session.get(url, params=params, timeout=self.timeout)
            response_time = time.time() - start_time

            if response.status_code == 200:
                return response.json(), response_time
            elif response.status_code == 503:
                raise requests.RequestException("PubChem service temporarily unavailable (503)")
            else:
                raise requests.RequestException(f"HTTP {response.status_code}: {response.text}")

        except requests.Timeout as e:
            response_time = time.time() - start_time
            raise requests.RequestException(f"Request timeout after {self.timeout}s") from e
        except requests.RequestException:
            response_time = time.time() - start_time
            raise

    def mcp_search_compounds(
        self,
        query: str = Field(description="Search query (compound name, CID, SMILES, InChI, etc.)"),
        search_type: Literal["name", "cid", "smiles", "inchi", "formula"] = Field(
            default="name",
            description="Type of search: name (compound name), cid (PubChem ID), smiles, inchi, or formula",
        ),
        max_results: int = Field(default=10, description="Maximum number of results to return (1-100)", ge=1, le=100),
    ) -> ActionResponse:
        """Search for chemical compounds in PubChem database.

        Supports multiple search types:
        - Name: Search by common or IUPAC names
        - CID: Search by PubChem Compound ID
        - SMILES: Search by SMILES notation
        - InChI: Search by InChI identifier
        - Formula: Search by molecular formula

        Args:
            query: Search term or identifier
            search_type: Type of search to perform
            max_results: Maximum number of compounds to return

        Returns:
            ActionResponse with compound search results and metadata
        """
        try:
            # Handle FieldInfo objects
            if isinstance(query, FieldInfo):
                query = query.default
            if isinstance(search_type, FieldInfo):
                search_type = search_type.default
            if isinstance(max_results, FieldInfo):
                max_results = max_results.default

            if not query or not query.strip():
                raise ValueError("Search query is required")

            self._color_log(f"Searching PubChem for: {query} (type: {search_type})", Color.cyan)

            # Build API URL based on search type
            if search_type == "cid":
                url = f"{self.base_url}/compound/cid/{quote(str(query))}/property/Title,MolecularFormula,MolecularWeight,CanonicalSMILES,InChI/JSON"
            elif search_type == "name":
                url = f"{self.base_url}/compound/name/{quote(query)}/property/Title,MolecularFormula,MolecularWeight,CanonicalSMILES,InChI/JSON"
            elif search_type == "smiles":
                url = f"{self.base_url}/compound/smiles/{quote(query)}/property/Title,MolecularFormula,MolecularWeight,CanonicalSMILES,InChI/JSON"
            elif search_type == "inchi":
                url = f"{self.base_url}/compound/inchi/{quote(query)}/property/Title,MolecularFormula,MolecularWeight,CanonicalSMILES,InChI/JSON"
            elif search_type == "formula":
                url = f"{self.base_url}/compound/formula/{quote(query)}/property/Title,MolecularFormula,MolecularWeight,CanonicalSMILES,InChI/JSON"
            else:
                raise ValueError(f"Unsupported search type: {search_type}")

            # Make API request
            data, response_time = self._make_request(url)

            # Parse results
            compounds = []
            if data and "PropertyTable" in data and "Properties" in data["PropertyTable"]:
                properties_list = data["PropertyTable"]["Properties"][:max_results]

                for prop in properties_list:
                    compound = CompoundData(
                        cid=prop.get("CID"),
                        name=prop.get("Title"),
                        molecular_formula=prop.get("MolecularFormula"),
                        molecular_weight=prop.get("MolecularWeight"),
                        smiles=prop.get("CanonicalSMILES"),
                        inchi=prop.get("InChI"),
                    )
                    compounds.append(compound)

            # Format results for LLM
            if compounds:
                result_lines = [f"Found {len(compounds)} compound(s) for query '{query}':\n"]

                for i, compound in enumerate(compounds, 1):
                    result_lines.append(f"{i}. **{compound.name}** (CID: {compound.cid})")
                    result_lines.append(f"   - Formula: {compound.molecular_formula}")
                    result_lines.append(f"   - Molecular Weight: {compound.molecular_weight} g/mol")
                    result_lines.append(f"   - SMILES: {compound.smiles}")
                    if compound.inchi:
                        result_lines.append(
                            f"   - InChI: {compound.inchi[:100]}..."
                            if len(compound.inchi) > 100
                            else f"   - InChI: {compound.inchi}"
                        )
                    result_lines.append("")

                message = "\n".join(result_lines)
            else:
                message = f"No compounds found for query '{query}' using search type '{search_type}'"

            # Prepare metadata
            metadata = PubChemMetadata(
                query_type=search_type,
                query_value=query,
                api_endpoint=url,
                response_time=response_time,
                total_results=len(compounds),
                timestamp=datetime.now().isoformat(),
            )

            self._color_log(f"Found {len(compounds)} compounds ({response_time:.2f}s)", Color.green)

            return ActionResponse(success=True, message=message, metadata=metadata.model_dump())

        except ValueError as e:
            self.logger.error(f"Invalid input: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"Invalid input: {str(e)}",
                metadata={"error_type": "invalid_input", "error_message": str(e)},
            )
        except requests.RequestException as e:
            self.logger.error(f"PubChem API error: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"PubChem API error: {str(e)}",
                metadata={"error_type": "api_error", "error_message": str(e)},
            )
        except Exception as e:
            self.logger.error(f"Search failed: {str(e)}: {traceback.format_exc()}")
            return ActionResponse(
                success=False,
                message=f"Search failed: {str(e)}",
                metadata={"error_type": "general_error", "error_message": str(e)},
            )

    def mcp_get_compound_synonyms(
        self,
        cid: int = Field(description="PubChem Compound ID (CID)"),
        max_synonyms: int = Field(default=20, description="Maximum number of synonyms to return (1-100)", ge=1, le=100),
    ) -> ActionResponse:
        """Retrieve synonyms and alternative names for a PubChem compound.

        Args:
            cid: PubChem Compound ID
            max_synonyms: Maximum number of synonyms to return

        Returns:
            ActionResponse with compound synonyms and metadata
        """
        try:
            # Handle FieldInfo objects
            if isinstance(cid, FieldInfo):
                cid = cid.default
            if isinstance(max_synonyms, FieldInfo):
                max_synonyms = max_synonyms.default

            if not cid or cid <= 0:
                raise ValueError("Valid PubChem CID is required")

            self._color_log(f"Retrieving synonyms for CID: {cid}", Color.cyan)

            # Build API URL for synonyms
            url = f"{self.base_url}/compound/cid/{cid}/synonyms/JSON"

            # Make API request
            data, response_time = self._make_request(url)

            # Parse synonyms
            synonyms = []
            if data and "InformationList" in data and "Information" in data["InformationList"]:
                info_list = data["InformationList"]["Information"]
                if info_list and "Synonym" in info_list[0]:
                    synonyms = info_list[0]["Synonym"][:max_synonyms]

            # Format results for LLM
            if synonyms:
                result_lines = [f"Found {len(synonyms)} synonym(s) for CID {cid}:\n"]

                for i, synonym in enumerate(synonyms, 1):
                    result_lines.append(f"{i}. {synonym}")

                message = "\n".join(result_lines)
            else:
                message = f"No synonyms found for CID {cid}"

            # Prepare metadata
            metadata = PubChemMetadata(
                query_type="synonyms",
                query_value=str(cid),
                api_endpoint=url,
                response_time=response_time,
                total_results=len(synonyms),
                timestamp=datetime.now().isoformat(),
            )

            self._color_log(f"Retrieved {len(synonyms)} synonyms ({response_time:.2f}s)", Color.green)

            return ActionResponse(success=True, message=message, metadata=metadata.model_dump())

        except ValueError as e:
            self.logger.error(f"Invalid input: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"Invalid input: {str(e)}",
                metadata={"error_type": "invalid_input", "error_message": str(e)},
            )
        except requests.RequestException as e:
            self.logger.error(f"PubChem API error: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"PubChem API error: {str(e)}",
                metadata={"error_type": "api_error", "error_message": str(e)},
            )
        except Exception as e:
            self.logger.error(f"Synonym retrieval failed: {str(e)}: {traceback.format_exc()}")
            return ActionResponse(
                success=False,
                message=f"Synonym retrieval failed: {str(e)}",
                metadata={"error_type": "general_error", "error_message": str(e)},
            )

    def mcp_get_compound_properties(
        self,
        cid: int = Field(description="PubChem Compound ID (CID)"),
        properties: list[str] = Field(
            default=[
                "MolecularWeight",
                "MolecularFormula",
                "CanonicalSMILES",
                "InChI",
                "XLogP",
                "TPSA",
                "HBondDonorCount",
                "HBondAcceptorCount",
            ],
            description="List of properties to retrieve (e.g., MolecularWeight, XLogP, TPSA)",
        ),
    ) -> ActionResponse:
        """Retrieve detailed chemical properties for a PubChem compound.

        Common properties include:
        - MolecularWeight: Molecular weight in g/mol
        - MolecularFormula: Chemical formula
        - CanonicalSMILES: SMILES notation
        - InChI: InChI identifier
        - XLogP: Partition coefficient
        - TPSA: Topological polar surface area
        - HBondDonorCount: Hydrogen bond donor count
        - HBondAcceptorCount: Hydrogen bond acceptor count

        Args:
            cid: PubChem Compound ID
            properties: List of property names to retrieve

        Returns:
            ActionResponse with compound properties and metadata
        """
        try:
            # Handle FieldInfo objects
            if isinstance(cid, FieldInfo):
                cid = cid.default
            if isinstance(properties, FieldInfo):
                properties = properties.default

            if not cid or cid <= 0:
                raise ValueError("Valid PubChem CID is required")

            if not properties:
                properties = ["MolecularWeight", "MolecularFormula", "CanonicalSMILES"]

            self._color_log(f"Retrieving properties for CID: {cid}", Color.cyan)

            # Build API URL for properties
            props_str = ",".join(properties)
            url = f"{self.base_url}/compound/cid/{cid}/property/{props_str}/JSON"

            # Make API request
            data, response_time = self._make_request(url)

            # Parse properties
            compound_props = {}
            if data and "PropertyTable" in data and "Properties" in data["PropertyTable"]:
                props_data = data["PropertyTable"]["Properties"][0]
                compound_props = {k: v for k, v in props_data.items() if k != "CID"}

            # Format results for LLM
            if compound_props:
                result_lines = [f"Properties for PubChem CID {cid}:\n"]

                for prop_name, prop_value in compound_props.items():
                    if prop_name == "InChI" and isinstance(prop_value, str) and len(prop_value) > 100:
                        result_lines.append(f"**{prop_name}**: {prop_value[:100]}...")
                    else:
                        result_lines.append(f"**{prop_name}**: {prop_value}")

                message = "\n".join(result_lines)
            else:
                message = f"No properties found for CID {cid}"

            # Prepare metadata
            metadata = PubChemMetadata(
                query_type="properties",
                query_value=str(cid),
                api_endpoint=url,
                response_time=response_time,
                total_results=len(compound_props),
                timestamp=datetime.now().isoformat(),
            )

            self._color_log(f"Retrieved {len(compound_props)} properties ({response_time:.2f}s)", Color.green)

            return ActionResponse(success=True, message=message, metadata=metadata.model_dump())

        except ValueError as e:
            self.logger.error(f"Invalid input: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"Invalid input: {str(e)}",
                metadata={"error_type": "invalid_input", "error_message": str(e)},
            )
        except requests.RequestException as e:
            self.logger.error(f"PubChem API error: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"PubChem API error: {str(e)}",
                metadata={"error_type": "api_error", "error_message": str(e)},
            )
        except Exception as e:
            self.logger.error(f"Property retrieval failed: {str(e)}: {traceback.format_exc()}")
            return ActionResponse(
                success=False,
                message=f"Property retrieval failed: {str(e)}",
                metadata={"error_type": "general_error", "error_message": str(e)},
            )

    def mcp_search_similar_compounds(
        self,
        cid: int = Field(description="PubChem Compound ID to find similar compounds for"),
        similarity_threshold: float = Field(
            default=0.9, description="Similarity threshold (0.0-1.0, higher = more similar)", ge=0.0, le=1.0
        ),
        max_results: int = Field(
            default=10, description="Maximum number of similar compounds to return (1-50)", ge=1, le=50
        ),
    ) -> ActionResponse:
        """Find structurally similar compounds using PubChem's similarity search.

        Uses Tanimoto similarity coefficient for 2D structure comparison.

        Args:
            cid: Reference compound CID for similarity search
            similarity_threshold: Minimum similarity score (0.0-1.0)
            max_results: Maximum number of similar compounds to return

        Returns:
            ActionResponse with similar compounds and metadata
        """
        try:
            # Handle FieldInfo objects
            if isinstance(cid, FieldInfo):
                cid = cid.default
            if isinstance(similarity_threshold, FieldInfo):
                similarity_threshold = similarity_threshold.default
            if isinstance(max_results, FieldInfo):
                max_results = max_results.default

            if not cid or cid <= 0:
                raise ValueError("Valid PubChem CID is required")

            self._color_log(f"Searching for compounds similar to CID: {cid}", Color.cyan)

            # Build API URL for similarity search
            threshold_percent = int(similarity_threshold * 100)
            url = f"{self.base_url}/compound/fastsimilarity_2d/cid/{cid}/property/Title,MolecularFormula,MolecularWeight/JSON"
            params = {"Threshold": threshold_percent, "MaxRecords": max_results}

            # Make API request
            data, response_time = self._make_request(url, params)

            # Parse similar compounds
            similar_compounds: list[CompoundData] = []
            if data and "PropertyTable" in data and "Properties" in data["PropertyTable"]:
                properties_list = data["PropertyTable"]["Properties"]

                for prop in properties_list:
                    if prop.get("CID") != cid:  # Exclude the query compound itself
                        compound = CompoundData(
                            cid=prop.get("CID"),
                            name=prop.get("Title"),
                            molecular_formula=prop.get("MolecularFormula"),
                            molecular_weight=prop.get("MolecularWeight"),
                        )
                        similar_compounds.append(compound)

            # Format results for LLM
            if similar_compounds:
                result_lines = [
                    f"Found {len(similar_compounds)} compound(s) similar to CID {cid} (threshold: {similarity_threshold}):\n"
                ]

                for i, compound in enumerate(similar_compounds, 1):
                    result_lines.append(f"{i}. **{compound.name}** (CID: {compound.cid})")
                    result_lines.append(f"   - Formula: {compound.molecular_formula}")
                    result_lines.append(f"   - Molecular Weight: {compound.molecular_weight} g/mol")
                    result_lines.append("")

                message = "\n".join(result_lines)
            else:
                message = f"No similar compounds found for CID {cid} with similarity threshold {similarity_threshold}"

            # Prepare metadata
            metadata = PubChemMetadata(
                query_type="similarity",
                query_value=str(cid),
                api_endpoint=url,
                response_time=response_time,
                total_results=len(similar_compounds),
                timestamp=datetime.now().isoformat(),
            )

            self._color_log(f"Found {len(similar_compounds)} similar compounds ({response_time:.2f}s)", Color.green)

            return ActionResponse(success=True, message=message, metadata=metadata.model_dump())

        except ValueError as e:
            self.logger.error(f"Invalid input: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"Invalid input: {str(e)}",
                metadata={"error_type": "invalid_input", "error_message": str(e)},
            )
        except requests.RequestException as e:
            self.logger.error(f"PubChem API error: {str(e)}")
            return ActionResponse(
                success=False,
                message=f"PubChem API error: {str(e)}",
                metadata={"error_type": "api_error", "error_message": str(e)},
            )
        except Exception as e:
            self.logger.error(f"Similarity search failed: {str(e)}: {traceback.format_exc()}")
            return ActionResponse(
                success=False,
                message=f"Similarity search failed: {str(e)}",
                metadata={"error_type": "general_error", "error_message": str(e)},
            )

    def mcp_get_pubchem_capabilities(self) -> ActionResponse:
        """Get information about the PubChem service capabilities.

        Returns:
            ActionResponse with service capabilities and configuration
        """
        capabilities = {
            "Compound Search": "Search by name, CID, SMILES, InChI, or molecular formula",
            "Property Retrieval": "Get molecular weight, formula, SMILES, physicochemical properties",
            "Synonym Lookup": "Retrieve alternative names and identifiers for compounds",
            "Similarity Search": "Find structurally similar compounds using Tanimoto similarity",
            "Rate Limiting": "Compliant with PubChem's 5 requests/second limit",
            "Data Formats": "JSON responses with structured compound data",
        }

        capability_list = "\n".join(
            [f"**{capability}**: {description}" for capability, description in capabilities.items()]
        )

        metadata = {
            "base_url": self.base_url,
            "rate_limit": "5 requests/second",
            "timeout": f"{self.timeout} seconds",
            "supported_capabilities": list(capabilities.keys()),
            "total_capabilities": len(capabilities),
            "search_types": ["name", "cid", "smiles", "inchi", "formula"],
            "data_source": "PubChem (NCBI)",
        }

        return ActionResponse(
            success=True, message=f"PubChem MCP Service Capabilities:\n\n{capability_list}", metadata=metadata
        )


# Example usage and entry point
if __name__ == "__main__":
    load_dotenv()

    # Default arguments for testing
    args = ActionArguments(name="pubchem_service", transport="stdio", workspace="~")

    # Initialize and run the PubChem service
    try:
        service = PubChemCollection(args)
        service.run()
    except Exception as e:
        print(f"An error occurred: {e}: {traceback.format_exc()}")