Clarity Literature Skill

Search and retrieve research papers from Clarity Protocol's curated literature database, sourced from PubMed and enriched with citation metrics from Semantic Scholar.

Quick Start

List all papers in the database:

python scripts/search_papers.py

Get details for a specific paper by PMID:

python scripts/get_paper.py --pmid 12345678

Get paper details in readable format:

python scripts/get_paper.py --pmid 12345678 --format summary

Paper Fields

Each paper includes:

• pmid: PubMed identifier
• doi: Digital Object Identifier
• title: Paper title
• first_author: First author name
• publication_year: Year published
• journal: Journal name
• abstract: Paper abstract (when available)
• citation_count: Number of citations (from Semantic Scholar)
• influential_citations: Number of highly influential citations
• has_fulltext: Whether full text is available in PubMed Central

Rate Limits

• Anonymous (no API key): 10 requests/minute
• With API key: 100 requests/minute

To use an API key, set the CLARITY_API_KEY environment variable:

export CLARITY_API_KEY=your_key_here
python scripts/search_papers.py

Get your API key at https://clarityprotocol.io

Error Handling

404 Not Found: The paper with the specified PMID does not exist in the database.

429 Rate Limit: You've exceeded the rate limit. The script will display how long to wait.

500 Server Error: The API server encountered an error. Try again later.

Timeout: The request took longer than 30 seconds.

Pagination

Paper lists are paginated. The API returns a next_cursor field if more results are available.

Use Cases

• Find research papers related to protein variants
• Get citation metrics for a specific paper
• Check if a paper has full text available
• Extract abstracts for literature reviews
• Build bibliographies for protein research