Skip to main content

Class: SemanticScholarPlugin

Defined in: src/plugins/builtin/semantic-scholar.ts:322

Semantic Scholar integration plugin.

Remarks​

Provides paper and author lookup from Semantic Scholar's 200M+ paper database. Semantic Scholar profiles with linked ORCID provide high-confidence identity verification for the multi-authority claiming system.

Example​

const plugin = new SemanticScholarPlugin();
await manager.loadBuiltinPlugin(plugin);

// Look up paper by DOI
const paper = await plugin.getPaperByDoi('10.1234/example');

// Get author for claiming verification
const author = await plugin.getAuthor('12345678');
if (author?.externalIds?.ORCID) {
  // High-confidence match for claiming
}

Extends​

Constructors​

new SemanticScholarPlugin()​

new SemanticScholarPlugin(): SemanticScholarPlugin

Returns​

SemanticScholarPlugin

Inherited from​

BasePlugin.constructor

Properties​

cache​

protected cache: ICacheProvider

Defined in: src/plugins/builtin/base-plugin.ts:88

Cache provider (available after initialization).

Inherited from​

BasePlugin.cache

context​

protected context: IPluginContext

Defined in: src/plugins/builtin/base-plugin.ts:78

Plugin context (available after initialization).

Inherited from​

BasePlugin.context

id​

readonly id: "pub.chive.plugin.semantic-scholar" = 'pub.chive.plugin.semantic-scholar'

Defined in: src/plugins/builtin/semantic-scholar.ts:326

Plugin ID.

Overrides​

BasePlugin.id

logger​

protected logger: ILogger

Defined in: src/plugins/builtin/base-plugin.ts:83

Logger instance (available after initialization).

Inherited from​

BasePlugin.logger

manifest​

readonly manifest: IPluginManifest

Defined in: src/plugins/builtin/semantic-scholar.ts:331

Plugin manifest.

Overrides​

BasePlugin.manifest

metrics​

protected metrics: IMetrics

Defined in: src/plugins/builtin/base-plugin.ts:93

Metrics provider (available after initialization).

Inherited from​

BasePlugin.metrics

Methods​

getAuthor()​

getAuthor(authorId): Promise<null | SemanticScholarAuthor>

Defined in: src/plugins/builtin/semantic-scholar.ts:591

Gets author by Semantic Scholar ID.

Parameters​

authorId​

string

Semantic Scholar author ID

Returns​

Promise<null | SemanticScholarAuthor>

Author profile or null

Remarks​

Semantic Scholar author profiles with linked ORCID provide high-confidence identity verification for the multi-authority claiming system.

getAuthorPapers()​

getAuthorPapers(authorId, options?): Promise<readonly SemanticScholarPaper[]>

Defined in: src/plugins/builtin/semantic-scholar.ts:767

Gets papers by an author.

Parameters​

authorId​

string

Semantic Scholar author ID

options?​

Query options

limit​

number

Returns​

Promise<readonly SemanticScholarPaper[]>

Author's papers

getCitations()​

getCitations(paperId, options?): Promise<{ citations: readonly CitationEdge[]; next: number; total: number; }>

Defined in: src/plugins/builtin/semantic-scholar.ts:1065

Gets papers that cite this paper.

Parameters​

paperId​

string

Semantic Scholar paper ID

options?​

Query options

limit​

number

Number of citations to return (max 1000).

Default Value

100
offset​

number

Offset for pagination.

Returns​

Promise<{ citations: readonly CitationEdge[]; next: number; total: number; }>

Paginated citation results

Remarks​

Returns papers that cite the specified paper, with influence markers indicating whether each citation is influential (based on Semantic Scholar's citation influence model).

Example​

const { citations, total, next } = await plugin.getCitations('649def34...', {
  limit: 50,
});

for (const { paper, isInfluential } of citations) {
  console.log(`${paper.title} ${isInfluential ? '(influential)' : ''}`);
}

getConfig()​

protected getConfig<T>(key): undefined | T

Defined in: src/plugins/builtin/base-plugin.ts:226

Gets a configuration value with type safety.

Type Parameters​

• T

Parameters​

key​

string

Configuration key

Returns​

undefined | T

Configuration value or undefined

Example​

const apiKey = this.getConfig<string>('apiKey');

Inherited from​

BasePlugin.getConfig

getPaper()​

getPaper(paperId): Promise<null | SemanticScholarPaper>

Defined in: src/plugins/builtin/semantic-scholar.ts:414

Gets paper by Semantic Scholar ID.

Parameters​

paperId​

string

Semantic Scholar paper ID

Returns​

Promise<null | SemanticScholarPaper>

Paper metadata or null

getPaperByArxiv()​

getPaperByArxiv(arxivId): Promise<null | SemanticScholarPaper>

Defined in: src/plugins/builtin/semantic-scholar.ts:531

Gets paper by arXiv ID.

Parameters​

arxivId​

string

arXiv ID (e.g., "2301.01234")

Returns​

Promise<null | SemanticScholarPaper>

Paper metadata or null

getPaperByDoi()​

getPaperByDoi(doi): Promise<null | SemanticScholarPaper>

Defined in: src/plugins/builtin/semantic-scholar.ts:470

Gets paper by DOI.

Parameters​

doi​

string

DOI string

Returns​

Promise<null | SemanticScholarPaper>

Paper metadata or null

getRecommendations()​

getRecommendations(paperId, options?): Promise<readonly SemanticScholarPaper[]>

Defined in: src/plugins/builtin/semantic-scholar.ts:857

Gets paper recommendations for a single paper.

Parameters​

paperId​

string

Semantic Scholar paper ID

options?​

Recommendation options

from​

"recent" | "all-cs"

Paper pool: 'recent' or 'all-cs'.

Default Value

'recent'
limit​

number

Number of recommendations (max 500).

Default Value

10

Returns​

Promise<readonly SemanticScholarPaper[]>

Array of recommended papers

Remarks​

Uses the Semantic Scholar Recommendations API with SPECTER2 embeddings to find semantically similar papers. Supports filtering by paper pool:

  • recent: Recent papers from all fields (default)
  • all-cs: All computer science papers

Example​

const recommendations = await plugin.getRecommendations('649def34f8be52c8b66281af98ae884c09aef38b', {
  limit: 20,
  from: 'recent',
});

for (const paper of recommendations) {
  console.log(`${paper.title} (${paper.citationCount} citations)`);
}

See​

Semantic Scholar Recommendations API

getRecommendationsFromLists()​

getRecommendationsFromLists(options): Promise<readonly SemanticScholarPaper[]>

Defined in: src/plugins/builtin/semantic-scholar.ts:954

Gets recommendations based on positive and negative paper examples.

Parameters​

options​

Paper lists and limit

limit​

number

Number of recommendations (max 500).

Default Value

100
negativePaperIds​

readonly string[]

Paper IDs to exclude from recommendations (optional).

positivePaperIds​

readonly string[]

Paper IDs to find similar papers for. Supports S2 paper IDs, DOI prefixed (DOI:xxx), or arXiv prefixed (ARXIV:xxx).

Returns​

Promise<readonly SemanticScholarPaper[]>

Array of recommended papers

Remarks​

Uses the Semantic Scholar Recommendations API with multi-example learning. Provide papers the user likes as positive examples and papers they don't want as negative examples for personalized recommendations.

This is used to power the "For You" feed by using the user's claimed papers as positive examples and dismissed recommendations as negatives.

Example​

// Get recommendations based on user's claimed papers
const recommendations = await plugin.getRecommendationsFromLists({
  positivePaperIds: ['649def34f8be52c8b66281af98ae884c09aef38b', 'ARXIV:2106.15928'],
  negativePaperIds: ['ArXiv:1805.02262'], // Dismissed recommendations
  limit: 50,
});

See​

Semantic Scholar Recommendations API

getReferences()​

getReferences(paperId, options?): Promise<{ next: number; references: readonly CitationEdge[]; total: number; }>

Defined in: src/plugins/builtin/semantic-scholar.ts:1181

Gets papers that this paper cites (references).

Parameters​

paperId​

string

Semantic Scholar paper ID

options?​

Query options

limit​

number

Number of references to return (max 1000).

Default Value

100
offset​

number

Offset for pagination.

Returns​

Promise<{ next: number; references: readonly CitationEdge[]; total: number; }>

Paginated reference results

Remarks​

Returns papers referenced by the specified paper, with influence markers indicating whether each reference is influential.

Example​

const { references, total, next } = await plugin.getReferences('649def34...', {
  limit: 50,
});

for (const { paper, isInfluential } of references) {
  console.log(`${paper.title} ${isInfluential ? '(influential)' : ''}`);
}

getRequiredConfig()​

protected getRequiredConfig<T>(key): T

Defined in: src/plugins/builtin/base-plugin.ts:242

Gets a required configuration value.

Type Parameters​

• T

Parameters​

key​

string

Configuration key

Returns​

T

Configuration value

Throws​

Error if key not found

Example​

const apiKey = this.getRequiredConfig<string>('apiKey');

Inherited from​

BasePlugin.getRequiredConfig

getState()​

getState(): PluginState

Defined in: src/plugins/builtin/base-plugin.ts:162

Gets current plugin state.

Returns​

PluginState

Current lifecycle state

Inherited from​

BasePlugin.getState

initialize()​

initialize(context): Promise<void>

Defined in: src/plugins/builtin/base-plugin.ts:111

Initializes the plugin.

Parameters​

context​

IPluginContext

Plugin context with injected dependencies

Returns​

Promise<void>

Remarks​

Sets up context and calls onInitialize(). Subclasses should override onInitialize() instead of this method.

Inherited from​

BasePlugin.initialize

onInitialize()​

protected onInitialize(): Promise<void>

Defined in: src/plugins/builtin/semantic-scholar.ts:384

Initializes the plugin.

Returns​

Promise<void>

Overrides​

BasePlugin.onInitialize

onShutdown()​

protected onShutdown(): Promise<void>

Defined in: src/plugins/builtin/base-plugin.ts:211

Override in subclass for shutdown logic.

Returns​

Promise<void>

Remarks​

Called during shutdown(). Use this to:

  • Save state
  • Close connections
  • Clean up resources

Default implementation does nothing.

Example​

protected async onShutdown(): Promise<void> {
  await this.saveState();
  this.connection?.close();
}

Inherited from​

BasePlugin.onShutdown

recordCounter()​

protected recordCounter(name, labels?, value?): void

Defined in: src/plugins/builtin/base-plugin.ts:257

Records a counter metric.

Parameters​

name​

string

Metric name

labels?​

Record<string, string>

Optional labels

value?​

number

Optional increment value (default 1)

Returns​

void

Inherited from​

BasePlugin.recordCounter

recordGauge()​

protected recordGauge(name, value, labels?): void

Defined in: src/plugins/builtin/base-plugin.ts:268

Records a gauge metric.

Parameters​

name​

string

Metric name

value​

number

Gauge value

labels?​

Record<string, string>

Optional labels

Returns​

void

Inherited from​

BasePlugin.recordGauge

searchAuthors()​

searchAuthors(query, options?): Promise<readonly SemanticScholarAuthor[]>

Defined in: src/plugins/builtin/semantic-scholar.ts:648

Searches for authors by name.

Parameters​

query​

string

Author name to search

options?​

Search options

limit​

number

Returns​

Promise<readonly SemanticScholarAuthor[]>

Matching authors

searchPapers()​

searchPapers(query, options?): Promise<readonly SemanticScholarPaper[]>

Defined in: src/plugins/builtin/semantic-scholar.ts:703

Searches for papers.

Parameters​

query​

string

Search query

options?​

Search options

fieldsOfStudy​

string

limit​

number

year​

string

Returns​

Promise<readonly SemanticScholarPaper[]>

Matching papers

shutdown()​

shutdown(): Promise<void>

Defined in: src/plugins/builtin/base-plugin.ts:142

Shuts down the plugin.

Returns​

Promise<void>

Remarks​

Calls onShutdown() and updates state. Subclasses should override onShutdown() instead of this method.

Inherited from​

BasePlugin.shutdown

startTimer()​

protected startTimer(name, labels?): () => void

Defined in: src/plugins/builtin/base-plugin.ts:286

Starts a timer for histogram metrics.

Parameters​

name​

string

Metric name

labels?​

Record<string, string>

Optional labels

Returns​

Function

Function to call when operation completes

Returns​

void

Example​

const endTimer = this.startTimer('api_request');
await this.fetchData();
endTimer(); // Records duration

Inherited from​

BasePlugin.startTimer