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 - RateLimitError: If rate limit is exceeded

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

Raises: - SearchError: If search fails

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.

Raises: - SearchError: If search fails

RAGTool

Module: src.tools.rag_tool

Purpose: Semantic search within collected evidence.

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.

Note: Requires evidence to be ingested into RAG service first.

SearchHandler

Module: src.tools.search_handler

Purpose: Orchestrates parallel searches across multiple tools.

Methods

search

async def search(
    self,
    query: str,
    tools: list[SearchTool] | None = None,
    max_results_per_tool: int = 10
) -> SearchResult

Searches multiple tools in parallel.

Parameters: - query: Search query string - tools: List of tools to use (default: all available tools) - max_results_per_tool: Maximum results per tool (default: 10)

Returns: SearchResult with: - evidence: Aggregated list of evidence - tool_results: Results per tool - total_count: Total number of results

Note: Uses asyncio.gather() for parallel execution. Handles tool failures gracefully.

See Also