What is PaperProbe?

PaperProbe bridges the gap between scientific papers and their associated code repositories. It automatically:

• Scans research papers (arXiv URLs or local PDFs) for GitHub repository links
• Analyzes repositories to understand structure, dependencies, and usage patterns
• Generates usage examples using AI-powered code analysis
• Provides insights on repository statistics, code quality, and documentation

Perfect for researchers, developers, and students who want to quickly understand and utilize code from scientific publications.

Features

Interactive TUI

• Beautiful terminal interface built with Textual
• Real-time progress updates and visual feedback
• Keyboard shortcuts for efficient navigation

Multi-Source Support

• arXiv papers: Direct URL scanning
• Local PDFs: Parse papers from your filesystem
• GitHub URLs: Direct repository analysis

AI-Powered Analysis

• Intelligent code structure analysis
• Automated usage example generation
• Context-aware documentation extraction

Repository Insights

• GitHub statistics (stars, forks, contributors)
• Dependency analysis
• Code quality metrics
• File structure visualization

Installation

Using pipx (Recommended)

pipx install paperprobe

Using pip

pip install paperprobe

From Source

git clone https://github.com/Brook-B-Nigatu/PaperProbe.git
cd PaperProbe
pip install -e .

[!TIP] Package version may need to be specified. pipx install paperprobe==0.2.0

Prerequisites

• Python: 3.12 or higher (some dependencies don't work on Python v3.13)
• API Keys: AI API key for AI-powered analysis
• GitHub Token (optional): For enhanced GitHub API access

Configuration

Environment Variables

PaperProbe requires API keys to function.

Environment Variables (Recommended)

Add to your shell configuration file (~/.zshrc, ~/.bashrc, etc.):

export CONSTRUCTOR_KM_ID=""
export CONSTRUCTOR_API_KEY=""
export CONSTRUCTOR_API_URL=""
export GITHUB_TOKEN="" #optional

Then reload your shell:

source ~/.zshrc

Usage

Launch the TUI

paperprobe

Basic Workflow

1. Enter a source:

   • arXiv URL: https://arxiv.org/abs/2301.12345
   • Local PDF: /path/to/paper.pdf
   • GitHub URL: https://github.com/username/repo

2. Scan for repositories: PaperProbe extracts GitHub links from papers

3. Select a repository: Choose from the discovered repos

4. Choose analysis mode:

   • Basic: Quick repository overview
   • Deep: Comprehensive analysis with usage examples

5. View results: Interactive markdown display with insights

Keyboard Shortcuts

Shortcut	Action
Ctrl+S	Use sample URL
Ctrl+Q	Quit application
Enter	Submit input / Select item
↑/↓	Navigate lists

Sample Usage

Try the built-in sample by pressing Ctrl+S on the intro screen, or paste this URL:

https://github.com/Brook-B-Nigatu/PaperProbe

Project Structure

PaperProbe/
├── src/
│   ├── core/               # Core analysis logic
│   │   ├── llm_service.py  # AI service integration
│   │   └── task_manager.py # Async task orchestration
│   ├── github_repo/        # GitHub repository handling
│   ├── preprocessing_utilities/
│   │   └── pdf_parser.py   # PDF text extraction
│   ├── tool_providers/     # Analysis tool providers
│   └── ui/                 # Terminal UI components
│       ├── app.py          # Main TUI application
│       ├── controller.py   # Business logic
│       └── style.tcss      # TUI styling
├── pyproject.toml          # Project configuration
└── README.md

Development

Setup Development Environment

# Clone the repository
git clone https://github.com/Brook-B-Nigatu/PaperProbe.git
cd PaperProbe

# Install in editable mode
pip install -e .

# Or use uv for faster installs
uv pip install -e .

Running Tests

# Run linter
ruff check .

# Format code
ruff format .

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.

Acknowledgments

• Built with Textual for the beautiful TUI
• Powered by LangChain and OpenAI for intelligent analysis
• PDF parsing with pdfminer.six

---