tooluniverse 1.0.6__py3-none-any.whl → 1.0.8__py3-none-any.whl

tooluniverse/tools/_shared_client.py

@@ -0,0 +1,138 @@
+"""
+Shared ToolUniverse client for all tools.
+
+This module provides a singleton ToolUniverse client to avoid reloading
+tools multiple times when using different tool functions.
+
+Thread Safety:
+    The shared client is thread-safe and uses double-checked locking to
+    ensure only one ToolUniverse instance is created even in multi-threaded
+    environments.
+
+Configuration:
+    You can provide custom configuration parameters that will be used during
+    the initial creation of the ToolUniverse instance. These parameters are
+    ignored if the client has already been initialized.
+
+Custom Instance:
+    You can provide your own ToolUniverse instance to be used instead of
+    the shared singleton. This is useful when you need specific configurations
+    or want to maintain separate instances.
+
+Examples:
+    Basic usage (default behavior):
+        from tooluniverse.tools import get_shared_client
+        client = get_shared_client()
+
+    With custom configuration (only effective on first call):
+        client = get_shared_client(hooks_enabled=True, log_level="INFO")
+
+    Using your own instance:
+        my_tu = ToolUniverse(hooks_enabled=True)
+        client = get_shared_client(custom_instance=my_tu)
+
+    Reset for testing:
+        from tooluniverse.tools import reset_shared_client
+        reset_shared_client()
+"""
+
+import threading
+from typing import Optional
+from tooluniverse import ToolUniverse
+
+_client: Optional[ToolUniverse] = None
+_client_lock = threading.Lock()
+
+
+def get_shared_client(
+    custom_instance: Optional[ToolUniverse] = None, **config_kwargs
+) -> ToolUniverse:
+    """
+    Get the shared ToolUniverse client instance.
+
+    This function implements a thread-safe singleton pattern with support for
+    custom configurations and external instances.
+
+    Args:
+        custom_instance: Optional ToolUniverse instance to use instead of
+                        the shared singleton. If provided, this instance
+                        will be returned directly without any singleton logic.
+
+        **config_kwargs: Optional configuration parameters to pass to
+                        ToolUniverse constructor. These are only used during
+                        the initial creation of the shared instance. If the
+                        shared instance already exists, these parameters are
+                        ignored.
+
+    Returns:
+        ToolUniverse: The client instance to use for tool execution
+
+    Thread Safety:
+        This function is thread-safe. Multiple threads can call this function
+        concurrently without risk of creating multiple ToolUniverse instances.
+
+    Configuration:
+        Configuration parameters are only applied during the initial creation
+        of the shared instance. Subsequent calls with different parameters
+        will not affect the already-created instance.
+
+    Examples:
+        # Basic usage
+        client = get_shared_client()
+
+        # With custom configuration (only effective on first call)
+        client = get_shared_client(hooks_enabled=True, log_level="DEBUG")
+
+        # Using your own instance
+        my_tu = ToolUniverse(hooks_enabled=True)
+        client = get_shared_client(custom_instance=my_tu)
+    """
+    # If user provides their own instance, use it directly
+    if custom_instance is not None:
+        return custom_instance
+
+    global _client
+
+    # Double-checked locking pattern for thread safety
+    if _client is None:
+        with _client_lock:
+            # Check again inside the lock to avoid race conditions
+            if _client is None:
+                # Create new instance with provided configuration
+                if config_kwargs:
+                    _client = ToolUniverse(**config_kwargs)
+                else:
+                    _client = ToolUniverse()
+                _client.load_tools()
+
+    return _client
+
+
+def reset_shared_client():
+    """
+    Reset the shared client (useful for testing or when you need to reload).
+
+    This function clears the shared client instance, allowing a new instance
+    to be created on the next call to get_shared_client(). This is primarily
+    useful for testing scenarios where you need to ensure a clean state.
+
+    Thread Safety:
+        This function is thread-safe and uses the same lock as
+        get_shared_client() to ensure proper synchronization.
+
+    Warning:
+        Calling this function while other threads are using the shared client
+        may cause unexpected behavior. It's recommended to only call this
+        function when you're certain no other threads are accessing the client.
+
+    Examples:
+        # Reset for testing
+        reset_shared_client()
+
+        # Now get_shared_client() will create a new instance
+        client = get_shared_client(hooks_enabled=True)
+    """
+    global _client
+
+    with _client_lock:
+        _client = None

tooluniverse/tools/alphafold_get_annotations.py

@@ -0,0 +1,52 @@
+"""
+alphafold_get_annotations
+
+Retrieve AlphaFold variant annotations (e.g., missense mutations) for a given UniProt accession (...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def alphafold_get_annotations(
+    qualifier: str,
+    type: str,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Retrieve AlphaFold variant annotations (e.g., missense mutations) for a given UniProt accession (...
+
+    Parameters
+    ----------
+    qualifier : str
+        Protein identifier: UniProt accession, entry name, or CRC64 checksum.
+    type : str
+        Annotation type (currently only 'MUTAGEN' is supported).
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "alphafold_get_annotations",
+            "arguments": {"qualifier": qualifier, "type": type},
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["alphafold_get_annotations"]

tooluniverse/tools/alphafold_get_prediction.py

@@ -0,0 +1,55 @@
+"""
+alphafold_get_prediction
+
+Retrieve full AlphaFold 3D structure predictions for a given protein. Input must be a UniProt acc...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def alphafold_get_prediction(
+    qualifier: str,
+    sequence_checksum: str,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> list[Any]:
+    """
+    Retrieve full AlphaFold 3D structure predictions for a given protein. Input must be a UniProt acc...
+
+    Parameters
+    ----------
+    qualifier : str
+        Protein identifier: UniProt accession (e.g., 'P69905'), entry name (e.g., 'HB...
+    sequence_checksum : str
+        Optional CRC64 checksum of the UniProt sequence.
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    list[Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "alphafold_get_prediction",
+            "arguments": {
+                "qualifier": qualifier,
+                "sequence_checksum": sequence_checksum,
+            },
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["alphafold_get_prediction"]

tooluniverse/tools/alphafold_get_summary.py

@@ -0,0 +1,46 @@
+"""
+alphafold_get_summary
+
+Retrieve summary details of AlphaFold 3D models for a given protein. Input must be a UniProt acce...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def alphafold_get_summary(
+    qualifier: str,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Retrieve summary details of AlphaFold 3D models for a given protein. Input must be a UniProt acce...
+
+    Parameters
+    ----------
+    qualifier : str
+        Protein identifier: UniProt accession, entry name, or CRC64 checksum.
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {"name": "alphafold_get_summary", "arguments": {"qualifier": qualifier}},
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["alphafold_get_summary"]

tooluniverse/tools/call_agentic_human.py

@@ -0,0 +1,46 @@
+"""
+call_agentic_human
+
+Produces a concise, practical answer that emulates how a well-informed human would respond to the...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def call_agentic_human(
+    question: str,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> Any:
+    """
+    Produces a concise, practical answer that emulates how a well-informed human would respond to the...
+
+    Parameters
+    ----------
+    question : str
+        The user's question to be answered in a human-like manner.
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    Any
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {"name": "call_agentic_human", "arguments": {"question": question}},
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["call_agentic_human"]

tooluniverse/tools/cancer_biomarkers_disease_target_score.py

@@ -0,0 +1,52 @@
+"""
+cancer_biomarkers_disease_target_score
+
+Extract disease-target association scores from cancer biomarkers data. This includes known cancer...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def cancer_biomarkers_disease_target_score(
+    efoId: str,
+    pageSize: int,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Extract disease-target association scores from cancer biomarkers data. This includes known cancer...
+
+    Parameters
+    ----------
+    efoId : str
+        The EFO (Experimental Factor Ontology) ID of the disease, e.g., 'EFO_0000339'...
+    pageSize : int
+        Number of results per page (default: 100, max: 100)
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "cancer_biomarkers_disease_target_score",
+            "arguments": {"efoId": efoId, "pageSize": pageSize},
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["cancer_biomarkers_disease_target_score"]

tooluniverse/tools/cancer_gene_census_disease_target_score.py

@@ -0,0 +1,52 @@
+"""
+cancer_gene_census_disease_target_score
+
+Extract disease-target association scores from Cancer Gene Census. This provides curated cancer g...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def cancer_gene_census_disease_target_score(
+    efoId: str,
+    pageSize: int,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Extract disease-target association scores from Cancer Gene Census. This provides curated cancer g...
+
+    Parameters
+    ----------
+    efoId : str
+        The EFO (Experimental Factor Ontology) ID of the disease, e.g., 'EFO_0000339'...
+    pageSize : int
+        Number of results per page (default: 100, max: 100)
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "cancer_gene_census_disease_target_score",
+            "arguments": {"efoId": efoId, "pageSize": pageSize},
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["cancer_gene_census_disease_target_score"]

tooluniverse/tools/cellosaurus_get_cell_line_info.py

@@ -0,0 +1,55 @@
+"""
+cellosaurus_get_cell_line_info
+
+Get detailed information about a specific cell line using its Cellosaurus accession number (CVCL_...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def cellosaurus_get_cell_line_info(
+    accession: str,
+    format: str,
+    fields: list[Any],
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Get detailed information about a specific cell line using its Cellosaurus accession number (CVCL_...
+
+    Parameters
+    ----------
+    accession : str
+        Cellosaurus accession number (must start with 'CVCL_')
+    format : str
+        Response format
+    fields : list[Any]
+        Specific fields to retrieve (e.g., ['id', 'ox', 'char']). If not specified, a...
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "cellosaurus_get_cell_line_info",
+            "arguments": {"accession": accession, "format": format, "fields": fields},
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["cellosaurus_get_cell_line_info"]

tooluniverse/tools/cellosaurus_query_converter.py

@@ -0,0 +1,52 @@
+"""
+cellosaurus_query_converter
+
+Convert natural language queries to Solr syntax for Cellosaurus API searches. Uses semantic simil...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def cellosaurus_query_converter(
+    query: str,
+    include_explanation: bool,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Convert natural language queries to Solr syntax for Cellosaurus API searches. Uses semantic simil...
+
+    Parameters
+    ----------
+    query : str
+        Natural language query to convert to Solr syntax (e.g., 'human cancer cells',...
+    include_explanation : bool
+        Whether to include detailed explanation of the conversion process
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "cellosaurus_query_converter",
+            "arguments": {"query": query, "include_explanation": include_explanation},
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["cellosaurus_query_converter"]

tooluniverse/tools/cellosaurus_search_cell_lines.py

@@ -0,0 +1,55 @@
+"""
+cellosaurus_search_cell_lines
+
+Search Cellosaurus cell lines using the /search/cell-line endpoint. Supports Solr query syntax fo...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def cellosaurus_search_cell_lines(
+    q: str,
+    offset: int,
+    size: int,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Search Cellosaurus cell lines using the /search/cell-line endpoint. Supports Solr query syntax fo...
+
+    Parameters
+    ----------
+    q : str
+        Search query. Supports Solr syntax for field-specific searches (e.g., 'id:HeL...
+    offset : int
+        Number of results to skip (for pagination)
+    size : int
+        Maximum number of results to return
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "cellosaurus_search_cell_lines",
+            "arguments": {"q": q, "offset": offset, "size": size},
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["cellosaurus_search_cell_lines"]

tooluniverse/tools/chembl_disease_target_score.py

@@ -0,0 +1,52 @@
+"""
+chembl_disease_target_score
+
+Extract disease-target association scores specifically from ChEMBL database. ChEMBL provides bioa...
+"""
+
+from typing import Any, Optional, Callable
+from ._shared_client import get_shared_client
+
+
+def chembl_disease_target_score(
+    efoId: str,
+    pageSize: int,
+    *,
+    stream_callback: Optional[Callable[[str], None]] = None,
+    use_cache: bool = False,
+    validate: bool = True,
+) -> dict[str, Any]:
+    """
+    Extract disease-target association scores specifically from ChEMBL database. ChEMBL provides bioa...
+
+    Parameters
+    ----------
+    efoId : str
+        The EFO (Experimental Factor Ontology) ID of the disease, e.g., 'EFO_0000339'...
+    pageSize : int
+        Number of results per page (default: 100, max: 100)
+    stream_callback : Callable, optional
+        Callback for streaming output
+    use_cache : bool, default False
+        Enable caching
+    validate : bool, default True
+        Validate parameters
+
+    Returns
+    -------
+    dict[str, Any]
+    """
+    # Handle mutable defaults to avoid B006 linting error
+
+    return get_shared_client().run_one_function(
+        {
+            "name": "chembl_disease_target_score",
+            "arguments": {"efoId": efoId, "pageSize": pageSize},
+        },
+        stream_callback=stream_callback,
+        use_cache=use_cache,
+        validate=validate,
+    )
+
+
+__all__ = ["chembl_disease_target_score"]