
pdf-research
LightRAG-based PDF document indexing and semantic search - index your PDF files and perform intelligent queries with knowledge graph
- GitHub stars
- 20
Install
/plugin install pdf-research@plugin-for-claude-researchRun it inside Claude Code after adding the marketplace with /plugin marketplace add hongsw/plugin-for-claude-research.
Contents
Discovered from sourceSkills 1
PDF Research Skill
LightRAG-based PDF document indexing and semantic search for Claude Code research workflows.
Quick Start (For Claude)
When user invokes /pdf-research, Claude should:
- Check status first: Run
python pdf_research.py statusto see current configuration - Auto-index if requested: When user provides a PDF directory, run indexing automatically
- Search queries: Execute searches and return formatted results
Automatic Workflow
# Always run from scripts directory
cd ~/.claude/skills/pdf-research/scripts
# Check current status
python pdf_research.py status
# Index PDFs (when user provides a directory)
python pdf_research.py index /path/to/pdfs
# Search (single query)
python pdf_research.py search "user's question" --mode hybrid
# Interactive search session
python pdf_research.py search
Environment Requirements
Before running commands, ensure:
# Activate Python environment with dependencies
source /path/to/venv/bin/activate # or use system Python with deps installed
# Ensure OpenAI API key is set
export OPENAI_API_KEY=sk-...
Core Capabilities
1. PDF Indexing (index command)
- Extracts text from PDF documents using PyMuPDF
- Creates semantic chunks with metadata
- Builds knowledge graph with entities and relationships
- Generates vector embeddings for semantic search
- Supports incremental indexing (only new files)
2. Semantic Search (search command)
- naive: Simple keyword matching
- local: Focus on specific entities and details
- global: Focus on broad themes and summaries
- hybrid: Combined local + global (recommended)
3. Status Check (status command)
- Shows current configuration
- Lists indexed documents
- Reports storage statistics
4. Configuration (config command)
- Set default PDF directory
- Set default storage directory
- Set default search mode
Claude Integration Protocol
When User Says "Index PDFs" or Provides a Path
- Verify the path exists
- Run:
python pdf_research.py index <path> - Report results (documents indexed, chunks created, storage size)
When User Asks a Question About Documents
- Check if storage exists:
python pdf_research.py status - If not indexed, ask user for PDF directory
- Run search:
python pdf_research.py search "<question>" - Format and present results with source references
When User Wants to Configure
- Run:
python pdf_research.py config --pdf-dir <path> --storage-dir <path> - Confirm configuration saved
Command Reference
# Configure defaults (run once)
python pdf_research.py config --pdf-dir /path/to/pdfs --storage-dir ./rag_storage
# Index PDFs
python pdf_research.py index [pdf_dir] [--storage <path>]
# Search (single query)
python pdf_research.py search "query" [--mode hybrid|local|global|naive]
# Search (interactive)
python pdf_research.py search
# Check status
python pdf_research.py status
Search Modes
| Mode | Best For | Description |
|---|---|---|
hybrid | General queries | Combined local + global (default) |
local | Specific facts | Names, numbers, definitions |
global | Summaries | Themes, trends, overviews |
naive | Exact terms | Simple keyword matching |
Storage Structure
After indexing, rag_storage/ contains:
| File | Description |
|---|---|
config.json | User configuration |
kv_store_full_docs.json | Full document text |
kv_store_text_chunks.json | Semantic chunks |
kv_store_full_entities.json | Extracted entities |
vdb_*.json | Vector embeddings |
graph_*.graphml | Knowledge graph |
Example Session
User: /pdf-research ~/Documents/papers 인덱싱해줘
Claude: [Runs indexing]
Indexing complete!
- Documents: 5
- Chunks: 247
- Storage: 32.5 MB
User: AI 인재 양성 전략에 대해 알려줘
Claude: [Runs search]
Based on the indexed documents...
[Detailed response with references]
Troubleshooting
"OPENAI_API_KEY not set"
export OPENAI_API_KEY=sk-your-key
"No indexed data found"
python pdf_research.py index /path/to/pdfs
"Module not found" errors
pip install lightrag-hku[api] pymupdf python-dotenv
Dependencies
- Python 3.10+
lightrag-hku[api]>=1.4.9pymupdf>=1.24.0python-dotenv>=1.0.0- OpenAI API key
Commands 1
PDF Research - LightRAG Semantic Search
You are a research assistant with access to LightRAG-based PDF indexing and semantic search capabilities.
Core Directive
When this command is invoked, help users index PDF documents and perform semantic searches over their content.
Immediate Action
-
Check Current Status First
Always start by checking the current configuration:
cd ~/.claude/plugins/cache/plugin-for-claude-research/pdf-research/*/skills/pdf-research/scripts python pdf_research.py status -
Report Status to User
Based on status output, report:
- ✅ PDF directory configured: [path] or ❌ Not configured
- ✅ Storage directory: [path] or ❌ Not set
- ✅ Documents indexed: [count] or ❌ No index found
- Search mode: [hybrid/local/global/naive]
User Intent Detection
Intent: "Index PDFs" or Provides Path
Actions:
- Verify path exists
- Run indexing:
python pdf_research.py index /path/to/pdfs - Report results:
✅ Indexing complete! - Documents indexed: [count] - Chunks created: [count] - Storage size: [MB] - Location: [storage path]
Intent: Search/Question About PDFs
Actions:
- Check if index exists (via status command)
- If no index:
No indexed documents found. Please provide a PDF directory to index first: Example: "Index PDFs from ~/Documents/research" - If index exists, run search:
python pdf_research.py search "user's question" --mode hybrid - Format and present results with source references
Intent: Configure Settings
Actions:
python pdf_research.py config --pdf-dir /path/to/pdfs --storage-dir ./rag_storage
Search Modes
Explain when appropriate:
| Mode | Best For | When to Use |
|---|---|---|
hybrid | General queries | Default, combines local + global |
local | Specific facts | Names, numbers, definitions |
global | Summaries | Themes, trends, overviews |
naive | Exact terms | Simple keyword matching |
Command Reference
# All commands run from scripts directory:
cd ~/.claude/plugins/cache/plugin-for-claude-research/pdf-research/*/skills/pdf-research/scripts
# Status check
python pdf_research.py status
# Index PDFs
python pdf_research.py index [pdf_dir]
# Search
python pdf_research.py search "query" --mode hybrid
# Configure
python pdf_research.py config --pdf-dir [path]
Prerequisites Check
If commands fail, check:
-
Python environment
python --version # Should be 3.10+ -
Dependencies
pip list | grep -E "lightrag|pymupdf|dotenv"If missing:
pip install lightrag-hku[api] pymupdf python-dotenv -
OpenAI API Key
echo $OPENAI_API_KEYIf not set:
export OPENAI_API_KEY=sk-your-key
Error Handling
"OPENAI_API_KEY not set"
⚠️ OpenAI API key not found. Please set it:
export OPENAI_API_KEY=sk-your-key
Then try again.
"No indexed data found"
⚠️ No indexed documents. Let's index some PDFs first.
Please provide the directory path containing your PDF files.
"Module not found"
⚠️ Required dependencies not installed. Installing:
pip install lightrag-hku[api] pymupdf python-dotenv
Example Session Flow
User: /pdf-research
---
## 관련 정보 (See Also)
- **Skill tool 호출**: Skill 이름 `pdf-research` 으로도 실행 가능
- **플러그인 문서**: `plugins/pdf-research/README.md`
- **전제 조건**: LightRAG 서버가 실행 중이어야 함 (`localhost:9621`)
Sponsors
Details
- Marketplace
- hongsw/plugin-for-claude-research
- Source
- plugins/pdf-research
- Category
- Community