scholar-sidekick

Resolve, verify, format and audit scholarly citations from Python.

A thin client for the Scholar Sidekick REST API — citation formatting in 10,000+ CSL styles, bibliography export, retraction and open-access checks, and verification that a citation is real rather than fabricated.

pip install scholar-sidekick

Quick start

from scholar_sidekick import ScholarSidekick

client = ScholarSidekick()

# Format an identifier
print(client.format(text="10.1038/nphys1170", style="vancouver").text)

# Export a bibliography
print(client.export(text="10.1038/nphys1170", format="bibtex"))

Verifying citations

The dominant AI-fabrication pattern is a real, resolvable DOI paired with an invented title. Such citations resolve cleanly under doi.org, so "follow the link and see if it loads" does not catch them. Comparing the claimed title against the resolved record does.

# Add semantic_title=True (any tier) to also judge whether the cited and resolved
# titles describe the same work — catches a one-word swap in a long title that
# string similarity misses. A flagged match comes back "ambiguous" for review,
# never "mismatch". Not byte-deterministic; see result.provenance["semantic_title"].
result = client.verify(
    title="Quantum entanglement in biological systems",
    doi="10.1038/nphys1170",
)

print(result.verdict)  # matched | mismatch | ambiguous | not_found
print(result.confidence)  # high | medium | low

A mismatch is returned as a value, never raised as an exception — it is the expected outcome for a fabricated citation, and the reason this method exists.

Interpreting verdicts

not_found is not proof of fabrication. Standards documents, software repositories, model cards and institutional reports are frequently real but absent from the scholarly registries the API searches. Treat it as "could not confirm", not "invented".

Auditing a whole bibliography

The API audits up to 25 references per call and rate-limits those calls. audit_bibliography() handles both for you: it chunks, paces itself from the server's rate-limit headers, and sends chunks serially — the server already fans out internally, so parallelising here would compete with it for the same upstream budget.

report = client.audit_bibliography(
    references, progress=lambda done, total: print(f"{done}/{total}")
)

print(report.summary)  # verdict counts across every chunk
print(len(report.needs_review))  # entries a human should look at

for entry in report.needs_review:
    print(entry.input_index, entry.verdict, entry.claimed_title, entry.resolved_title)

entry.input_index is the 0-based position in the list you passed in, so it always points at the right reference regardless of how the work was chunked. An entry carries both claimed_title (what you sent) and resolved_title (what the identifier resolves to) — a mismatch is the gap between the two.

A chunk that fails is recorded rather than raised, so one transient upstream error does not discard several minutes of completed work:

if not report.complete:
    for failure in report.errors:
        print(f"entries {failure.start_index}-{failure.end_index} failed: {failure.error}")

With pandas installed (pip install 'scholar-sidekick[pandas]'):

df = report.to_dataframe()
df[df.verdict != "matched"]

There is a runnable end-to-end example in examples/systematic_review_audit.ipynb.

Authentication

Every endpoint works anonymously — no key, no signup. An API key raises the rate limit (about fivefold on the free tier) but is never required.

client = ScholarSidekick(api_key="ssk_…")

Or set SCHOLAR_SIDEKICK_API_KEY in the environment. Precedence is the explicit argument, then the environment variable, then anonymous. Free keys are issued at scholar-sidekick.com/account.

Async

Every method has an async equivalent:

from scholar_sidekick import AsyncScholarSidekick

async with AsyncScholarSidekick() as client:
    result = await client.verify(title="…", doi="10.1038/nphys1170")

Note that audit_bibliography() still issues its chunks serially in the async client — the constraint is the server's upstream budget, not this client's concurrency.

Errors

Exceptions are selected by the API's stable error code, not by HTTP status (the contract guarantees the code; statuses may change).

from scholar_sidekick import APIError, RateLimitError, UpstreamError

try:
    client.format(text="10.1038/nphys1170")
except RateLimitError as exc:
    print("retry after", exc.retry_after)
except UpstreamError as exc:
    print("a data source failed:", exc.code)
except APIError as exc:
    print(exc.code, exc.message, exc.request_id)

Every APIError carries .request_id — include it in bug reports.

API surface

format() returns whole-batch text/html strings covering every input, newline-joined — the API has no per-item formatted field, and this client does not invent one by splitting that string. format_items() names the same concept output. The difference is preserved deliberately rather than papered over.

Related

• Scholar Sidekick API docs
• scholar-sidekick-cli — the same API from the terminal
• scholar-sidekick-mcp — MCP server for AI assistants

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev,pandas]"
pytest --cov

License

MIT