Skip to content

Retrieve ID

Tool for retrieving a Semantic Scholar paper ID given a paper title.

This tool queries the Semantic Scholar API for the best match of the provided paper title and returns the unique Semantic Scholar paperId. Use when you have a known title and need its Semantic Scholar identifier for further metadata retrieval or pipeline integration. Do not use this tool for broad literature search; use the search tool instead.

RetrieveSemanticScholarPaperIdInput

Bases: BaseModel

Pydantic schema for retrieving a Semantic Scholar paper ID.

Fields

paper_title: The title (full or partial) of the paper to look up on Semantic Scholar. tool_call_id: LangGraph-injected identifier for tracking the tool invocation.

Source code in aiagents4pharma/talk2scholars/tools/s2/retrieve_semantic_scholar_paper_id.py
28
29
30
31
32
33
34
35
36
37
38
39
40
class RetrieveSemanticScholarPaperIdInput(BaseModel):
    """
    Pydantic schema for retrieving a Semantic Scholar paper ID.

    Fields:
      paper_title: The title (full or partial) of the paper to look up on Semantic Scholar.
      tool_call_id: LangGraph-injected identifier for tracking the tool invocation.
    """

    paper_title: str = Field(
        ..., description="The paper title to search for on Semantic Scholar."
    )
    tool_call_id: Annotated[str, InjectedToolCallId]

retrieve_semantic_scholar_paper_id(paper_title, tool_call_id)

Retrieve a Semantic Scholar paper ID using a paper title.

This tool searches Semantic Scholar for the best match to the provided paper title and returns the corresponding unique paper ID. It is intended to support downstream tasks such as recommendations, metadata lookups, or citation graph queries.

Use this tool when you know the full or partial title of a paper and need its Semantic Scholar ID. For broad literature searches or topic-based queries, use a general search tool instead.

Parameters:

Name Type Description Default
paper_title str

The full or partial title of the paper to look up.

required
tool_call_id str

LangGraph-injected identifier for this tool call.

required

Returns:

Name Type Description
Command Command[Any]

A structured response containing a ToolMessage whose content is the Semantic Scholar paper ID string (e.g., 'abc123xyz').

Raises:

Type Description
ValueError

If no matching paper is found for the given title.

RequestException

If the API request fails.

Source code in aiagents4pharma/talk2scholars/tools/s2/retrieve_semantic_scholar_paper_id.py
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
@tool(
    "retrieve_semantic_scholar_paper_id",
    args_schema=RetrieveSemanticScholarPaperIdInput,
    parse_docstring=True,
)
def retrieve_semantic_scholar_paper_id(
    paper_title: str,
    tool_call_id: str,
) -> Command[Any]:
    """
    Retrieve a Semantic Scholar paper ID using a paper title.

    This tool searches Semantic Scholar for the best match to the provided paper title
    and returns the corresponding unique paper ID. It is intended to support downstream
    tasks such as recommendations, metadata lookups, or citation graph queries.

    Use this tool when you know the full or partial title of a paper and need its
    Semantic Scholar ID.
    For broad literature searches or topic-based queries, use a general `search` tool instead.

    Args:
        paper_title (str): The full or partial title of the paper to look up.
        tool_call_id (str): LangGraph-injected identifier for this tool call.

    Returns:
        Command: A structured response containing a ToolMessage whose content is
            the Semantic Scholar paper ID string (e.g., 'abc123xyz').

    Raises:
        ValueError: If no matching paper is found for the given title.
        requests.RequestException: If the API request fails.
    """
    # Load hydra configuration
    with hydra.initialize(version_base=None, config_path="../../configs"):
        cfg = hydra.compose(
            config_name="config",
            overrides=["tools/retrieve_semantic_scholar_paper_id=default"],
        )
        cfg = cfg.tools.retrieve_semantic_scholar_paper_id
        logger.info("Loaded configuration for Semantic Scholar paper ID retrieval tool")
    logger.info("Retrieving ID of paper with title: %s", paper_title)
    endpoint = cfg.api_endpoint
    params = {
        "query": paper_title,
        "limit": 1,
        "fields": ",".join(cfg.api_fields),
    }

    response = requests.get(endpoint, params=params, timeout=10)
    data = response.json()
    papers = data.get("data", [])
    logger.info("Received %d papers", len(papers))
    if not papers:
        logger.error("No papers found for query: %s", paper_title)
        raise ValueError(f"No papers found for query: {paper_title}. Try again.")
    # Extract the paper ID from the top result
    paper_id = papers[0]["paperId"]
    logger.info("Found paper ID: %s", paper_id)
    # Prepare the response content (just the ID)
    response_text = paper_id
    return Command(
        update={
            "messages": [
                ToolMessage(
                    content=response_text,
                    tool_call_id=tool_call_id,
                )
            ],
        }
    )