Skip to content

API Reference

OpenCite is a library as well as a CLI. The programmatic surface centers on two async orchestrators and a set of data models, all configured by a single Config object.

At a glance

Symbol Module Use it for
SearchOrchestrator opencite.search Parallel multi-source search with dedup/merge
CitationExplorer opencite.citations Citation-graph traversal and canonical papers
Config opencite.config Load and merge configuration
Paper, IDSet, ... opencite.models Data models returned by the orchestrators
OpenCiteError, ... opencite.exceptions Error hierarchy to catch

Typical usage

Both orchestrators are async context managers. Open one, run your queries, and let the async with block close the underlying HTTP clients:

import asyncio
from opencite import Config
from opencite.search import SearchOrchestrator


async def main():
    config = Config.from_env()
    async with SearchOrchestrator(config) as searcher:
        result = await searcher.search(
            "transformer attention",
            max_results=10,
            sources=("openalex", "s2"),
            sort="citations",
        )
        print(f"{len(result.papers)} papers, by source: {result.total_by_source}")
        for paper in result.papers:
            print(paper.year, paper.title)


asyncio.run(main())

Top-level exports

The package re-exports the data models and Config for convenience:

opencite: Academic literature search, citation management, and PDF retrieval.

Config dataclass

Configuration for opencite.

from_env classmethod 

from_env(config_path: Path | None = None) -> Config

Create config from TOML, .env files, and environment variables.

Priority (later overrides earlier): 1. Config dataclass defaults 2. ~/.opencite/config.toml 3. .env files (~/.opencite/.env, then CWD .env) 4. Environment variables

validate 

validate() -> list[str]

Validate configuration. Returns list of warnings.

setup_logging 

setup_logging() -> None

Configure logging based on log_level.

show 

show(mask_keys: bool = True) -> str

Return a human-readable string of the resolved config.

API keys are masked by default.

Paper dataclass

Central data model for an academic paper.

Designed to be populated incrementally: a search fills basic fields, then enrichment passes add TLDR, PDF locations, etc.

authors_short property 

authors_short: str

'Smith et al.' format.

best_pdf_url property 

best_pdf_url: str | None

Return the best available PDF URL.

Author dataclass

Structured author representation.

citation_name 

citation_name() -> str

Format for citation: 'Smith, J.'

IDSet dataclass

All known identifiers for a single paper.

Immutable so it can be used for dedup lookups.

best_lookup_id 

best_lookup_id() -> tuple[IDType, str]

Return the most useful ID for cross-API lookup.

Priority: DOI > PMID > PMCID > S2 > OpenAlex > ArXiv.

merge 

merge(other: IDSet) -> IDSet

Create a new IDSet with the union of both sets' identifiers.

Source dataclass

Journal or venue information.

PDFLocation dataclass

A known location where a PDF can be retrieved.

SearchResult dataclass

Result of a multi-source search.

CitationResult dataclass

Result of a citation graph query.