Skip to content

Multi Paper Recommendation

Recommend research papers related to a set of input papers using Semantic Scholar.

Given a list of Semantic Scholar paper IDs, this tool aggregates related works (citations and references) from each input paper and returns a consolidated list of recommended papers.

MultiPaperRecInput

Bases: BaseModel

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

Attributes:

Name Type Description
paper_ids List[str]

List of 40-character Semantic Scholar Paper IDs (provide at least two).
limit int

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

Optional publication year filter; supports formats: '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/multi_paper_rec.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
class MultiPaperRecInput(BaseModel):
    """Defines the input schema for the multi-paper recommendation tool.

    Attributes:
        paper_ids: List of 40-character Semantic Scholar Paper IDs (provide at least two).
        limit: Maximum total number of recommendations to return (1-500).
        year: Optional publication year filter; supports formats:
            'YYYY', 'YYYY-', '-YYYY', 'YYYY:YYYY'.
        tool_call_id: Internal tool call identifier injected by the system.
    """

    paper_ids: List[str] = Field(
        description="List of 40-character Semantic Scholar Paper IDs"
        "(at least two) to base recommendations on"
    )
    limit: int = Field(
        default=10,
        description="Maximum total 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_multi_paper_recommendations(paper_ids, tool_call_id, limit=10, year=None)

Recommend related research papers using the Semantic Scholar API.

This tool is designed to suggest relevant papers based on a list of input Semantic Scholar paper IDs.

It fetches citations and references for each input paper and aggregates them to generate a set of recommended papers.

Parameters:

Name Type Description Default
paper_ids List[str]

List of 40-character Semantic Scholar paper IDs. Provide at least two IDs to improve the relevance of recommendations.

 required
tool_call_id str

Internal tool call identifier injected by the system.

 required
limit int

Maximum number of recommendations to return. Defaults to 10.

 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: - multi_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/multi_paper_rec.py 
 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
@tool(
    args_schema=MultiPaperRecInput,
    parse_docstring=True,
)
def get_multi_paper_recommendations(
    paper_ids: List[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.

    This tool is designed to suggest relevant papers based on a list of
    input Semantic Scholar paper IDs.

    It fetches citations and references for each input paper and aggregates
    them to generate a set of
    recommended papers.

    Args:
        paper_ids (List[str]): List of 40-character Semantic Scholar paper IDs.
            Provide at least two IDs to improve the relevance of recommendations.
        tool_call_id (str): Internal tool call identifier injected by the system.
        limit (int, optional): Maximum number of recommendations to return. Defaults to 10.
        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:
            - multi_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 = MultiPaperRecData(paper_ids, limit, year, tool_call_id)

    # Process the recommendations
    results = rec_data.process_recommendations()

    return Command(
        update={
            "multi_papers": results["papers"],
            # Store the latest multi-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"],
                )
            ],
        }
    )