Package com.tnsai.tools.academic

Class AcademicTools

java.lang.Object

com.tnsai.tools.academic.AcademicTools

public class AcademicTools
extends Object

Function-shape academic / research-database tools — wraps the most-useful FREE academic APIs (no auth needed) into typed @Tool methods. Replaces the legacy ArxivTool, PubMedTool, SemanticScholarTool, OpenAlexTool, CrossRefTool, and DBLPTool.

The remaining 13 academic legacy tools (CORE / IEEE / Lens.org / Dimensions / AlphaXiv / BioRxiv / MedRxiv / GoogleScholar / ConnectedPapers / Unpaywall / ORCID / PubChem / PapersWithCode) are deferred — most need API keys, custom scraping, or are aggregators that compose the free ones above. They can be added piecewise as real consumers need them.

Method	Backend	Auth	Idempotent
arxivSearch(java.lang.String, int)	arxiv.org /api/query	none	true
pubmedSearch(java.lang.String, int)	NCBI E-utilities (esearch + esummary)	none	true
semanticScholarSearch(java.lang.String, int)	api.semanticscholar.org /graph/v1	optional SEMANTIC_SCHOLAR_API_KEY (raises rate limit)	true
openalexSearch(java.lang.String, int)	api.openalex.org /works	optional OPENALEX_MAILTO (raises rate limit)	true
crossrefSearch(java.lang.String, int)	api.crossref.org /works	none	true
dblpSearch(java.lang.String, int)	dblp.org /search/publ/api	none	true

Returns raw API responses so the LLM can structure the result. arxiv returns Atom XML; the rest return JSON.

Since:

0.5.7 (Phase 2 batch 27 — built-in tool migration to function shape, see #188)

Constructor Summary

Constructors

Constructor	Description
AcademicTools()	Default constructor — picks SEMANTIC_SCHOLAR_API_KEY + OPENALEX_MAILTO from env.
AcademicTools(String semanticScholarApiKey, String openAlexMailto)	Explicit-credentials constructor (both optional — APIs work without them).
AcademicTools(String semanticScholarApiKey, String openAlexMailto, okhttp3.OkHttpClient http, com.fasterxml.jackson.databind.ObjectMapper mapper)	Full constructor for tests / shared HTTP.

Method Summary

Modifier and Type	Method	Description
String	arxivSearch(String query, int limit)
String	crossrefSearch(String query, int limit)
String	dblpSearch(String query, int limit)
String	openalexSearch(String query, int limit)
String	pubmedSearch(String query, int limit)
String	semanticScholarSearch(String query, int limit)

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Details

AcademicTools

public AcademicTools()

Default constructor — picks SEMANTIC_SCHOLAR_API_KEY + OPENALEX_MAILTO from env.

AcademicTools

public AcademicTools(String semanticScholarApiKey,
 String openAlexMailto)

Explicit-credentials constructor (both optional — APIs work without them).

AcademicTools

public AcademicTools(String semanticScholarApiKey,
 String openAlexMailto,
 okhttp3.OkHttpClient http,
 com.fasterxml.jackson.databind.ObjectMapper mapper)

Full constructor for tests / shared HTTP.

Method Details

arxivSearch

@Tool(name="arxiv_search",
      description="Search arXiv preprints by free-text {query}. {limit} clamps to [1, 50]. Returns the raw Atom XML response from the arxiv.org API (entries under <entry> tags with <title>, <author>, <summary>, <link>, <published>). No auth required.",
      keywords={"arxiv","academic","paper","preprint","research","search"},
      idempotent=true)
public String arxivSearch(@ToolParam(description="Free-text search query")
 String query,
 @ToolParam(description="Max results (1..50); 0 \u2192 default 10",required=false,defaultValue="0")
 int limit)
                   throws IOException

Throws:

IOException

pubmedSearch

@Tool(name="pubmed_search",
      description="Search PubMed for biomedical papers (NCBI E-utilities). Two-step: esearch resolves ids, esummary fetches the metadata. {limit} clamps to [1, 50]. Returns the raw esummary JSON response with paper metadata.",
      keywords={"pubmed","medical","biomedical","ncbi","search"},
      idempotent=true)
public String pubmedSearch(@ToolParam(description="Free-text search query")
 String query,
 @ToolParam(description="Max results (1..50); 0 \u2192 default 10",required=false,defaultValue="0")
 int limit)
                    throws IOException

Throws:

IOException

semanticScholarSearch

@Tool(name="semantic_scholar_search",
      description="Search Semantic Scholar (AI-powered academic search). Returns paper metadata + abstract + TLDR + citation counts + authors. {limit} clamps to [1, 50]. Optional SEMANTIC_SCHOLAR_API_KEY raises the rate limit (100 req/5min anonymous \u2192 1 req/s authenticated).",
      keywords={"semantic scholar","academic","paper","tldr","citation"},
      idempotent=true)
public String semanticScholarSearch(@ToolParam(description="Free-text search query")
 String query,
 @ToolParam(description="Max results (1..50); 0 \u2192 default 10",required=false,defaultValue="0")
 int limit)
                             throws IOException

Throws:

IOException

openalexSearch

@Tool(name="openalex_search",
      description="Search OpenAlex (open academic database, 200M+ works). Returns work metadata + concepts + citation graph + open-access status. {limit} clamps to [1, 50]. Optional OPENALEX_MAILTO env var puts you in the polite-pool (faster rate limit).",
      keywords={"openalex","academic","open access","citations"},
      idempotent=true)
public String openalexSearch(@ToolParam(description="Free-text search query")
 String query,
 @ToolParam(description="Max results (1..50); 0 \u2192 default 10",required=false,defaultValue="0")
 int limit)
                      throws IOException

Throws:

IOException

crossrefSearch

@Tool(name="crossref_search",
      description="Search CrossRef (90M+ scholarly works metadata). Returns work metadata: DOI / title / authors / publication / year / type / citations. {limit} clamps to [1, 50]. No auth required.",
      keywords={"crossref","doi","academic","metadata","citation"},
      idempotent=true)
public String crossrefSearch(@ToolParam(description="Free-text search query")
 String query,
 @ToolParam(description="Max results (1..50); 0 \u2192 default 10",required=false,defaultValue="0")
 int limit)
                      throws IOException

Throws:

IOException

dblpSearch

@Tool(name="dblp_search",
      description="Search DBLP (computer science bibliography). Returns publication metadata: title / authors / venue / year / type. {limit} clamps to [1, 50]. No auth required. Specialised for CS \u2014 broader queries land better in openalex_search or semantic_scholar_search.",
      keywords={"dblp","computer science","academic","bibliography"},
      idempotent=true)
public String dblpSearch(@ToolParam(description="Free-text search query")
 String query,
 @ToolParam(description="Max results (1..50); 0 \u2192 default 10",required=false,defaultValue="0")
 int limit)
                  throws IOException

Throws:

IOException