Skip to content
Open
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 11 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -106,7 +106,7 @@ This project is for:

**Optional requirements:**
- Tavily API key (for web search functionality)
- Serper API key (for academic paper search functionality)
- A paper search API key for one of the supported providers: Serper (`SERPER_API_KEY`), SerpAPI (`SERPAPI_API_KEY`), or SearchAPI (`SEARCHAPI_API_KEY`)

> **Note:** Configure at least one data source (Tavily web search, Serper search tool, or knowledge layer) to enable research functionality.

Expand Down Expand Up @@ -206,10 +206,17 @@ uv pip install -e "./sources/knowledge_layer[llamaindex,foundational_rag]"
2. Navigate to your dashboard
3. Generate an API key

#### Obtain a Serper API Key
#### Obtain a Paper Search API Key

1. Sign in to [Serper](https://serper.dev/)
2. Generate an API key from your dashboard
Paper search supports three interchangeable providers. Set the `provider` field on the `paper_search` function in your workflow config (defaults to `serper`):

| Provider | Environment Variable | Sign-up |
|----------|----------------------|---------|
| Serper (default) | `SERPER_API_KEY` | [serper.dev](https://serper.dev/) |
| SerpAPI | `SERPAPI_API_KEY` | [serpapi.com](https://serpapi.com/) |
| SearchAPI | `SEARCHAPI_API_KEY` | [searchapi.io](https://www.searchapi.io/) |

See [sources/google_scholar_paper_search/README.md](sources/google_scholar_paper_search/README.md) for configuration details.

### Set Up Environment Variables

Expand Down
8 changes: 6 additions & 2 deletions deploy/.env.example
Original file line number Diff line number Diff line change
Expand Up @@ -20,8 +20,12 @@ NVIDIA_API_KEY=
# Web search (Required)
TAVILY_API_KEY=

# Paper search (Optional)
# SERPER_API_KEY= # to enable, set API key and update the relevant config in configs/ directory
# Paper search (Optional — choose one provider)
# The provider is selected in your workflow config via the `provider` field
# on the paper_search function (defaults to 'serper').
# SERPER_API_KEY= # provider: serper — https://serper.dev/
# SERPAPI_API_KEY= # provider: serpapi — https://serpapi.com/
# SEARCHAPI_API_KEY= # provider: searchapi — https://www.searchapi.io/


# -----------------------------------------------------------------------------
Expand Down
66 changes: 52 additions & 14 deletions sources/google_scholar_paper_search/README.md
Original file line number Diff line number Diff line change
@@ -1,17 +1,29 @@
# Google Scholar Paper Search

A NeMo Agent Toolkit function that searches for academic papers using Google Scholar through the Serper API.
A NeMo Agent Toolkit function that searches for academic papers using Google Scholar. You can choose between three backend providers:

| Provider | `_type` value | Env var | Sign-up |
|----------|---------------|---------|---------|
| **Serper** (default) | `serper` | `SERPER_API_KEY` | [serper.dev](https://serper.dev/) |
| **SerpAPI** | `serpapi` | `SERPAPI_API_KEY` | [serpapi.com](https://serpapi.com/) |
| **SearchAPI** | `searchapi` | `SEARCHAPI_API_KEY` | [searchapi.io](https://www.searchapi.io/) |
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

All three query Google Scholar and return the same normalized result shape (title, year, snippet, link, publication info, citations), so the agent-facing tool behavior is identical regardless of provider.

## Prerequisites

Before using this function, you need a Serper API key:
You need an API key for **one** of the supported providers. The default is Serper.

1. Go to [serper.dev](https://serper.dev/) and create an account
2. Generate an API key from your dashboard
3. Add the API key to your `deploy/.env` file in the project root:
1. Create an account at your chosen provider (see table above)
2. Generate an API key from the dashboard
3. Add the key to your `deploy/.env` file in the project root, for example:

```bash
SERPER_API_KEY="your-serper-api-key"
# OR
SERPAPI_API_KEY="your-serpapi-api-key"
# OR
SEARCHAPI_API_KEY="your-searchapi-api-key"
```

Alternatively, you can provide the API key directly in the configuration file (see below).
Expand All @@ -34,24 +46,48 @@ nat info components -t function | grep paper_search

### Adding the Function

Add the `paper_search` function to the `functions` section of your workflow configuration file:
Add the `paper_search` function to the `functions` section of your workflow configuration file. Use the `provider` field to select the backend (defaults to `serper`):

```yaml
functions:
paper_search_tool:
_type: paper_search
provider: serper # 'serper' (default), 'serpapi', or 'searchapi'
max_results: 10
timeout: 30
serper_api_key: ${SERPER_API_KEY}
```

To use SerpAPI instead:

```yaml
functions:
paper_search_tool:
_type: paper_search
provider: serpapi
serpapi_api_key: ${SERPAPI_API_KEY}
```

To use SearchAPI:

```yaml
functions:
paper_search_tool:
_type: paper_search
provider: searchapi
searchapi_api_key: ${SEARCHAPI_API_KEY}
```

#### Configuration Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `provider` | string | `serper` | Backend provider: `serper`, `serpapi`, or `searchapi` |
| `max_results` | integer | 10 | Maximum number of search results to return (capped at 50) |
| `timeout` | integer | 30 | Timeout in seconds for search requests |
| `serper_api_key` | string | None | Serper API key (can also be set through the `SERPER_API_KEY` environment variable) |
| `serper_api_key` | string | None | Serper API key (required when `provider: serper`; also read from `SERPER_API_KEY` env var) |
| `serpapi_api_key` | string | None | SerpAPI key (required when `provider: serpapi`; also read from `SERPAPI_API_KEY` env var) |
| `searchapi_api_key` | string | None | SearchAPI key (required when `provider: searchapi`; also read from `SEARCHAPI_API_KEY` env var) |

### Adding as a Tool to an Agent

Expand All @@ -74,7 +110,7 @@ functions:

### Complete Example

Here is a complete configuration example showing how to integrate the paper search tool:
Here is a complete configuration example showing how to integrate the paper search tool with SerpAPI as the provider:

```yaml
llms:
Expand All @@ -87,8 +123,9 @@ llms:
functions:
paper_search_tool:
_type: paper_search
provider: serpapi
max_results: 10
serper_api_key: ${SERPER_API_KEY}
serpapi_api_key: ${SERPAPI_API_KEY}

web_search_tool:
_type: tavily_internet_search
Expand All @@ -115,7 +152,6 @@ The paper search function accepts the following arguments when called by an agen
|----------|------|----------|-------------|
| `query` | string | Yes | The search query for finding academic papers |
| `year` | string | No | Year or year range filter (for example, "2023" or "2020-2023") |
| `source` | string | No | Search source (defaults to "serper") |

## Troubleshooting

Expand All @@ -125,8 +161,9 @@ The paper search function accepts the following arguments when called by an agen

If you see an error about the API key not being found:

- Verify the `SERPER_API_KEY` environment variable is set correctly
- Alternatively, ensure the `serper_api_key` is specified in the configuration file
- Verify the correct environment variable is set for your chosen `provider` (`SERPER_API_KEY`, `SERPAPI_API_KEY`, or `SEARCHAPI_API_KEY`)
- Alternatively, ensure the matching key field is specified in the configuration file
- Make sure the `provider` field matches the key you provided

**Request timeout**

Expand All @@ -141,11 +178,11 @@ If no papers are found:

- Try a broader search query
- Remove year filters to expand the search range
- Verify your Serper API key has available quota
- Verify your provider API key has available quota

## Disabling Paper Search

If you don't have a Serper API key or don't need paper search functionality, you can disable it by removing the tool from your configuration:
If you don't have a provider API key or don't need paper search functionality, you can disable it by removing the tool from your configuration:

### Remove from Configuration

Expand All @@ -156,6 +193,7 @@ functions:
# Remove or comment out this section
# paper_search_tool:
# _type: paper_search
# provider: serper
# max_results: 5
# serper_api_key: ${SERPER_API_KEY}
```
Expand Down
6 changes: 3 additions & 3 deletions sources/google_scholar_paper_search/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -23,13 +23,13 @@ package-dir = {"google_scholar_paper_search" = "src"}

[project]
name = "google-scholar-paper-search"
version = "1.0.0"
description = "NAT-based Google Scholar paper search tool using Serper (Google Scholar)"
version = "1.1.0"
description = "NAT-based Google Scholar paper search tool supporting Serper, SerpAPI, and SearchAPI backends"
readme = "README.md"
requires-python = ">=3.11,<3.14"
license = {text = "Apache-2.0"}
dependencies = [
"httpx>=0.24.0",
"aiohttp>=3.8.0",
"pydantic>=2.0.0",
]

Expand Down
Loading