DeepCritical / docs /api /tools.md
Joseph Pollack
implements documentation improvements
d45d242
# 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