Skip to content

Single Paper Recommendation

Recommend research papers related to a single input paper using Semantic Scholar.

Given a Semantic Scholar paper ID, this tool retrieves related works (citations and references) and returns a curated list of recommended papers.

SinglePaperRecInput

Bases: BaseModel

Defines the input schema for the single-paper recommendation tool.

Attributes:

Name Type Description
paper_id str

40-character Semantic Scholar Paper ID to base recommendations on.
limit int

Maximum number of recommendations to return (1-500).
year Optional[str]

Optional publication year filter; supports 'YYYY', 'YYYY-', '-YYYY', 'YYYY:YYYY'.
tool_call_id Annotated[str, InjectedToolCallId]

Internal tool call identifier injected by the system.
Source code in aiagents4pharma/talk2scholars/tools/s2/single_paper_rec.py 
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
class SinglePaperRecInput(BaseModel):
    """Defines the input schema for the single-paper recommendation tool.

    Attributes:
        paper_id: 40-character Semantic Scholar Paper ID to base recommendations on.
        limit: Maximum number of recommendations to return (1-500).
        year: Optional publication year filter; supports 'YYYY', 'YYYY-', '-YYYY', 'YYYY:YYYY'.
        tool_call_id: Internal tool call identifier injected by the system.
    """

    paper_id: str = Field(
        description="40-character Semantic Scholar Paper ID to base recommendations on"
    )
    limit: int = Field(
        default=10,
        description="Maximum number of recommendations to return (1-500)",
        ge=1,
        le=500,
    )
    year: Optional[str] = Field(
        default=None,
        description="Publication year filter; supports formats::"
        "'YYYY', 'YYYY-', '-YYYY', 'YYYY:YYYY'",
    )
    tool_call_id: Annotated[str, InjectedToolCallId]
    model_config = {"arbitrary_types_allowed": True}

get_single_paper_recommendations(paper_id, tool_call_id, limit=10, year=None)

Recommend related research papers using the Semantic Scholar API for a single paper ID.

This tool is designed to suggest relevant papers based on one input Semantic Scholar paper ID. It fetches citations and references for the given paper and returns a set of recommended works.

Parameters:

Name Type Description Default
paper_id str

40-character Semantic Scholar paper ID.

 required
tool_call_id str

Internal tool call identifier injected by the system.

 required
limit int

Maximum number of recommendations to return. Defaults to 5.

 10
year str

Filter recommendations by publication year. Supports formats: 'YYYY', 'YYYY-', '-YYYY', or 'YYYY:YYYY'. Defaults to None.

 None

Returns:

Name Type Description
Command Command[Any]

A Command object containing: - papers: List of recommended papers. - last_displayed_papers: Same list for display purposes. - messages: List containing a ToolMessage with recommendation details.
Source code in aiagents4pharma/talk2scholars/tools/s2/single_paper_rec.py 
 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
@tool(
    args_schema=SinglePaperRecInput,
    parse_docstring=True,
)
def get_single_paper_recommendations(
    paper_id: str,
    tool_call_id: Annotated[str, InjectedToolCallId],
    limit: int = 10,
    year: Optional[str] = None,
) -> Command[Any]:
    """
    Recommend related research papers using the Semantic Scholar API for a single paper ID.

    This tool is designed to suggest relevant papers based on one input Semantic Scholar paper ID.
    It fetches citations and references for the given paper and returns a set of recommended works.

    Args:
        paper_id (str): 40-character Semantic Scholar paper ID.
        tool_call_id (str): Internal tool call identifier injected by the system.
        limit (int, optional): Maximum number of recommendations to return. Defaults to 5.
        year (str, optional): Filter recommendations by publication year.
            Supports formats: 'YYYY', 'YYYY-', '-YYYY', or 'YYYY:YYYY'. Defaults to None.

    Returns:
        Command: A Command object containing:
            - papers: List of recommended papers.
            - last_displayed_papers: Same list for display purposes.
            - messages: List containing a ToolMessage with recommendation details.
    """
    # Create recommendation data object to organize variables
    rec_data = SinglePaperRecData(paper_id, limit, year, tool_call_id)

    # Process the recommendations
    results = rec_data.process_recommendations()

    return Command(
        update={
            "papers": results["papers"],
            # Store the latest single-paper results mapping directly for display
            "last_displayed_papers": results["papers"],
            "messages": [
                ToolMessage(
                    content=results["content"],
                    tool_call_id=tool_call_id,
                    artifact=results["papers"],
                )
            ],
        }
    )