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-research

Run it inside Claude Code after adding the marketplace with /plugin marketplace add hongsw/plugin-for-claude-research.

Contents

Discovered from source

Skills 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:

  1. Check status first: Run python pdf_research.py status to see current configuration
  2. Auto-index if requested: When user provides a PDF directory, run indexing automatically
  3. 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

  1. Verify the path exists
  2. Run: python pdf_research.py index <path>
  3. Report results (documents indexed, chunks created, storage size)

When User Asks a Question About Documents

  1. Check if storage exists: python pdf_research.py status
  2. If not indexed, ask user for PDF directory
  3. Run search: python pdf_research.py search "<question>"
  4. Format and present results with source references

When User Wants to Configure

  1. Run: python pdf_research.py config --pdf-dir <path> --storage-dir <path>
  2. 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

ModeBest ForDescription
hybridGeneral queriesCombined local + global (default)
localSpecific factsNames, numbers, definitions
globalSummariesThemes, trends, overviews
naiveExact termsSimple keyword matching

Storage Structure

After indexing, rag_storage/ contains:

FileDescription
config.jsonUser configuration
kv_store_full_docs.jsonFull document text
kv_store_text_chunks.jsonSemantic chunks
kv_store_full_entities.jsonExtracted entities
vdb_*.jsonVector embeddings
graph_*.graphmlKnowledge 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.9
  • pymupdf>=1.24.0
  • python-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

  1. 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
    
  2. 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:

  1. Verify path exists
  2. Run indexing:
    python pdf_research.py index /path/to/pdfs
    
  3. Report results:
    ✅ Indexing complete!
    - Documents indexed: [count]
    - Chunks created: [count]
    - Storage size: [MB]
    - Location: [storage path]
    

Intent: Search/Question About PDFs

Actions:

  1. Check if index exists (via status command)
  2. If no index:
    No indexed documents found. Please provide a PDF directory to index first:
    Example: "Index PDFs from ~/Documents/research"
    
  3. If index exists, run search:
    python pdf_research.py search "user's question" --mode hybrid
    
  4. 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:

ModeBest ForWhen to Use
hybridGeneral queriesDefault, combines local + global
localSpecific factsNames, numbers, definitions
globalSummariesThemes, trends, overviews
naiveExact termsSimple 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:

  1. Python environment

    python --version  # Should be 3.10+
    
  2. Dependencies

    pip list | grep -E "lightrag|pymupdf|dotenv"
    

    If missing:

    pip install lightrag-hku[api] pymupdf python-dotenv
    
  3. OpenAI API Key

    echo $OPENAI_API_KEY
    

    If 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

More from hongsw/plugin-for-claude-research

All 5