Skip to content

Tools API Reference

This page documents the API for DeepCritical search tools.

SearchTool Protocol

All tools implement the SearchTool protocol:

class SearchTool(Protocol):
    @property
    def name(self) -> str: ...
    
    async def search(
        self, 
        query: str, 
        max_results: int = 10
    ) -> list[Evidence]: ...

PubMedTool

Module: src.tools.pubmed

Purpose: Search peer-reviewed biomedical literature from PubMed.

Properties

name

@property
def name(self) -> str

Returns tool name: "pubmed"

Methods

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches PubMed for articles.

Parameters: - query: Search query string - max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects with PubMed articles.

Raises: - SearchError: If search fails (timeout, HTTP error, XML parsing error) - RateLimitError: If rate limit is exceeded (429 status code)

Note: Uses NCBI E-utilities (ESearch → EFetch). Rate limit: 0.34s between requests. Handles single vs. multiple articles.

ClinicalTrialsTool

Module: src.tools.clinicaltrials

Purpose: Search ClinicalTrials.gov for interventional studies.

Properties

name

@property
def name(self) -> str

Returns tool name: "clinicaltrials"

Methods

search

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches ClinicalTrials.gov for trials.

Parameters: - query: Search query string - max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects with clinical trials.

Note: Only returns interventional studies with status: COMPLETED, ACTIVE_NOT_RECRUITING, RECRUITING, ENROLLING_BY_INVITATION. Uses requests library (NOT httpx - WAF blocks httpx). Runs in thread pool for async compatibility.

Raises: - SearchError: If search fails (HTTP error, request exception)

EuropePMCTool

Module: src.tools.europepmc

Purpose: Search Europe PMC for preprints and peer-reviewed articles.

Properties

name

@property
def name(self) -> str

Returns tool name: "europepmc"

Methods

search

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches Europe PMC for articles and preprints.

Parameters: - query: Search query string - max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects with articles/preprints.

Note: Includes both preprints (marked with [PREPRINT - Not peer-reviewed]) and peer-reviewed articles. Handles preprint markers. Builds URLs from DOI or PMID.

Raises: - SearchError: If search fails (HTTP error, connection error)

RAGTool

Module: src.tools.rag_tool

Purpose: Semantic search within collected evidence.

Initialization

def __init__(
    self,
    rag_service: LlamaIndexRAGService | None = None,
    oauth_token: str | None = None
) -> None

Parameters: - rag_service: Optional RAG service instance. If None, will be lazy-initialized. - oauth_token: Optional OAuth token from HuggingFace login (for RAG LLM)

Properties

name

@property
def name(self) -> str

Returns tool name: "rag"

Methods

search

async def search(
    self,
    query: str,
    max_results: int = 10
) -> list[Evidence]

Searches collected evidence using semantic similarity.

Parameters: - query: Search query string - max_results: Maximum number of results to return (default: 10)

Returns: List of Evidence objects from collected evidence.

Raises: - ConfigurationError: If RAG service is unavailable

Note: Requires evidence to be ingested into RAG service first. Wraps LlamaIndexRAGService. Returns Evidence from RAG results.

SearchHandler

Module: src.tools.search_handler

Purpose: Orchestrates parallel searches across multiple tools.

Initialization

def __init__(
    self,
    tools: list[SearchTool],
    timeout: float = 30.0,
    include_rag: bool = False,
    auto_ingest_to_rag: bool = True,
    oauth_token: str | None = None
) -> None

Parameters: - tools: List of search tools to use - timeout: Timeout for each search in seconds (default: 30.0) - include_rag: Whether to include RAG tool in searches (default: False) - auto_ingest_to_rag: Whether to automatically ingest results into RAG (default: True) - oauth_token: Optional OAuth token from HuggingFace login (for RAG LLM)

Methods

execute

Searches multiple tools in parallel.

Parameters: - query: Search query string - max_results_per_tool: Maximum results per tool (default: 10)

Returns: SearchResult with: - query: The search query - evidence: Aggregated list of evidence - sources_searched: List of source names searched - total_found: Total number of results - errors: List of error messages from failed tools

Raises: - SearchError: If search times out

Note: Uses asyncio.gather() for parallel execution. Handles tool failures gracefully (returns errors in SearchResult.errors). Automatically ingests evidence into RAG if enabled.

See Also