Spaces:
Running
Running
| # Tools API Reference | |
| This page documents the API for DeepCritical search tools. | |
| ## SearchTool Protocol | |
| All tools implement the `SearchTool` protocol: | |
| ```python | |
| 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` | |
| ```python | |
| @property | |
| def name(self) -> str | |
| ``` | |
| Returns tool name: `"pubmed"` | |
| ### Methods | |
| #### `search` | |
| ```python | |
| 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` | |
| ```python | |
| @property | |
| def name(self) -> str | |
| ``` | |
| Returns tool name: `"clinicaltrials"` | |
| ### Methods | |
| #### `search` | |
| ```python | |
| 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` | |
| ```python | |
| @property | |
| def name(self) -> str | |
| ``` | |
| Returns tool name: `"europepmc"` | |
| ### Methods | |
| #### `search` | |
| ```python | |
| 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 | |
| ```python | |
| 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` | |
| ```python | |
| @property | |
| def name(self) -> str | |
| ``` | |
| Returns tool name: `"rag"` | |
| ### Methods | |
| #### `search` | |
| ```python | |
| 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 | |
| ```python | |
| 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` | |
| <!--codeinclude--> | |
| [SearchHandler.execute](../src/tools/search_handler.py) start_line:86 end_line:86 | |
| <!--/codeinclude--> | |
| 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 | |
| - [Architecture - Tools](../architecture/tools.md) - Architecture overview | |
| - [Models API](models.md) - Data models used by tools | |