cite-extractor 0.10.8

Extracts citations from PDF, URLs and local media files in CSL-JSON.

🔍 Citation Extractor

We're living in an era where AI can write beautifully, but can't cite properly.
Because every claim deserves a source, and every source deserves proper citation.

Why This Matters • Features • Quick Start • Usage • Contributing

---

🚨 Why This Matters

We're living in an era where AI can write beautifully, but can't cite properly.

Large Language Models (LLMs) like ChatGPT, Claude, and Gemini are incredible at generating human-like text, but they have a fundamental flaw: they lack reliable citation mechanisms. When an LLM tells you about a scientific study, historical event, or technical concept, you're left wondering:

• 📚 Where did this information come from?
• 🔍 How can I verify these claims?
• 📝 How do I properly cite this in my research?

This creates a trust gap that undermines the reliability of AI-generated content, especially in academic, professional, and research contexts.

Citation Extractor exists to fill this gap.

While LLMs struggle with proper citations, this tool excels at extracting structured, verifiable citation data from any source. It's the missing piece that makes AI-generated content trustworthy and academically sound.

🌟 Features

🎯 Universal Source Support

• 📄 Document Versatility: Handles .pdf, .docx, .djvu, .epub, and more.
• 🌐 Web & Media: Extracts citations directly from URLs and media files (.mp4, .mp3).

🧠 AI-Powered Intelligence

• Smart Document Classification: Automatically detects if a source is a book, journal article, thesis, or chapter.
• Advanced, Multilingual OCR: Accurately processes scanned documents, including those with vertical text layouts (e.g., Chinese, Japanese).
• Smarter Language Detection: Intelligently skips blank cover pages to find the first page with text, ensuring the correct language is used for OCR.
• Automatic OCR Error Correction: Proactively fixes common OCR mistakes (e.g., 郭庆沙 → 郭庆藩) before extraction for higher accuracy.
• Flexible LLM Backend: Works with Ollama (local) or cloud APIs (Gemini, OpenAI).

📚 Research-Grade Output

• CSL-JSON Standard: Compatible with Zotero, Mendeley, and all major reference managers.
• Multiple Citation Styles: Instantly format in Chicago, APA, MLA, or any other CSL style.
• Rich, Structured Metadata: Captures author, title, date, DOI, ISBN, and even complex author details like historical dynasties ([清]).

⚡ Optimized Performance

• Smart Page Selection: Processes only the most relevant pages for speed.
• Iterative Extraction: Stops as soon as all essential citation fields are found.
• Batch Processing: Handle multiple documents efficiently.

🚀 Quick Start

Installation

pip install cite-extractor

System Dependencies

# Ubuntu/Debian
sudo apt-get install tesseract-ocr mediainfo

# macOS
brew install tesseract mediainfo

# For local LLM support (optional)
# Install Ollama: https://ollama.ai/

First Citation

# Extract from a PDF
citation "path/to/research-paper.pdf"

# Extract from a URL
citation "https://www.nature.com/articles/s41586-023-06627-7"

# Extract from a document with vertical text
citation "path/to/vertical-text-document.pdf" --text-direction vertical

📖 Usage

Command Line Interface

# Basic usage
citation "document.pdf"

# Specify document type
citation "thesis.pdf" --type thesis

# Use different LLM
citation "paper.pdf" --llm gemini/gemini-1.5-flash

# Custom output directory
citation "book.pdf" --output-dir ./citations

# Specific page range for large documents
citation "book.pdf" --page-range "1-5, -3"

# Different citation style
citation "article.pdf" --citation-style apa

Python API

from citation.main import CitationExtractor
from citation.citation_style import format_bibliography

# Initialize with your preferred LLM
extractor = CitationExtractor(llm_model="ollama/qwen3")

# Extract citation data
csl_data = extractor.extract_citation("research-paper.pdf")

if csl_data:
    # Format as bibliography
    bibliography, in_text = format_bibliography([csl_data], "chicago-author-date")
    
    print("📚 Bibliography:")
    print(bibliography)
    
    print("\n📝 In-text citation:")
    print(in_text)

Advanced Configuration

# For non-English documents, let the tool auto-detect the language
citation "chinese-paper.pdf" --lang auto

# Or specify manually
citation "another-paper.pdf" --lang chi_sim+eng

# Verbose output for debugging
citation "document.pdf" --verbose

🤝 Contributing

We're thrilled to have you join this mission! 🎉

This project addresses a fundamental need in our AI-driven world, and we believe it can make a real difference in how we handle information credibility. Whether you're a developer, researcher, or just someone who cares about proper attribution, there's a place for you here.

🚀 How to Contribute

1. 🐛 Report Issues: Found a bug or have a feature request?
2. 💡 Suggest Improvements: Ideas for better citation extraction?
3. 🔧 Submit Code: Bug fixes, new features, or optimizations
4. 📚 Improve Documentation: Help others understand and use the tool
5. 🌍 Add Language Support: Extend OCR and extraction to new languages
6. 🎨 Citation Styles: Add support for more academic citation styles

💻 Development Setup

git clone https://github.com/your-username/citation-extractor.git
cd citation-extractor

# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black .

🏆 Acknowledgments

This project stands on the shoulders of giants:

• DSPy: For flexible LLM integration
• Tesseract: For OCR capabilities
• citeproc-py: For citation formatting
• The Open Source Community: For making tools like this possible

📄 License

MIT License - feel free to use this in your projects, commercial or otherwise.

---

Made with ❤️ for the research community
Because every claim deserves a source, and every source deserves respect.

⭐ Star this repo if you find it useful! ⭐