Tool Reference

Tool Reference

Sisyphus Academica ships with two Python CLI tools for the literature search and citation verification pipeline.

literature_client.py

Multi-source literature search aggregator.

Location: tools/literature_client.py

Usage:

python3 tools/literature_client.py "transformer efficiency" --output papers/literature.json

Sources

Source	API	Results
arXiv	REST (Atom XML)	Up to 200
Semantic Scholar	Graph API v1	Up to 100
CrossRef	REST (JSON)	Up to 50
OpenAlex	REST (JSON)	Up to 50

Output

{
  "query": "transformer efficiency",
  "total_raw": 400,
  "total_unique": 310,
  "by_source": {
    "arxiv": 200,
    "semantic_scholar": 100,
    "crossref": 50,
    "openalex": 50
  },
  "papers": [
    {
      "title": "Efficient Transformers: A Survey",
      "authors": ["Tay, Y.", "Dehghani, M."],
      "year": 2022,
      "abstract": "...",
      "citation_count": 450,
      "doi": "10.1145/3530811",
      "source": "semantic_scholar"
    }
  ]
}

Functions

Function	Description
search_arxiv(query, max_results=200)	Search arXiv OAI-PMH
search_semantic_scholar(query, limit=100)	Search Semantic Scholar
search_crossref(query, rows=50)	Search CrossRef
search_openalex(query, per_page=50)	Search OpenAlex
deduplicate_papers(all_papers)	Remove duplicates by title (first 80 chars)
search_all(query)	Search all sources, merge, deduplicate

Arguments

Arg	Description
query	Search query (positional, required)
-o, --output	Output JSON file path

---

citation_verifier.py

Verifies citations against multiple sources and generates BibTeX.

Location: tools/citation_verifier.py

Usage:

python3 tools/citation_verifier.py --findings papers/draft.json --output papers/verified.json
python3 tools/citation_verifier.py --citation "Attention is all you need"

Verification Process

1. Extract citation keys from text using [bracket] notation
2. Search Semantic Scholar for each citation
3. Search CrossRef for each citation
4. Compare: do both sources agree on the paper's existence and title?
5. If found in 2+ sources: verified
6. If found in 1 source: weak verification (flagged)
7. If found in 0 sources: hallucinated (blocks submission)

Output

{
  "total_citations": 45,
  "verified": 42,
  "hallucinated_count": 0,
  "issues_count": 3,
  "hallucinated_citations": [],
  "blocked": false,
  "details": [...]
}

Exit code 1 if any citation is hallucinated (blocked). Exit code 0 if all pass.

Functions

Function	Description
search_semantic_scholar(title)	Search Semantic Scholar by title
search_crossref(title)	Search CrossRef by title
verify_citation(citation_key, claim)	Verify single citation against both sources
verify_citations(findings)	Extract and verify all citations from paper text
generate_bibtex(paper)	Generate BibTeX entry from verified metadata

Arguments

Arg	Description
-f, --findings	Findings JSON file (paper with citations)
-o, --output	Output verification report file
-c, --citation	Verify a single citation string (overrides --findings)