Download docs/USER_GUIDE.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 23.7 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/USER_GUIDE.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/USER_GUIDE.md
-
curl -L -o USER_GUIDE.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/USER_GUIDE.md
# Polyhedra User Guide
Complete guide to using Polyhedra MCP Server for academic research.
Table of Contents
- Quick Start
- Installation
- IDE Setup
- Core Concepts
- Using the Tools
- Research Workflows
- Tips & Best Practices
- Troubleshooting
Quick Start
Get started in 3 steps:
Install Polyhedra
git clone https://github.com/yourusername/polyhedra.git cd polyhedra pip install -e .Configure Your IDE (example for Cursor)
Add to ~/.cursor/mcp.json:
{ "mcpServers": { "polyhedra": { "command": "python", "args": ["-m", "polyhedra.server"] } } }Start Using
Open your IDE and ask:
"Initialize a new research project called 'deep-learning-review'"
Installation
Requirements
- Python 3.11 or higher
- Git
- One of the supported IDEs:
- Cursor
- VS Code with GitHub Copilot
- Windsurf
- VS Code with MCP extension
Method 1: Standard Installation
git clone https://github.com/yourusername/polyhedra.git
cd polyhedra
pip install -e .
Method 2: Using uv (faster)
git clone https://github.com/yourusername/polyhedra.git
cd polyhedra
pip install uv
uv pip install -e .
Verify Installation
python -m polyhedra.server --version
IDE Setup
Cursor
Open MCP Settings: ~/.cursor/mcp.json
Add Polyhedra:
{ "mcpServers": { "polyhedra": { "command": "python", "args": ["-m", "polyhedra.server"] } } }Restart Cursor
Test: Ask Copilot "What Polyhedra tools are available?"
VS Code with GitHub Copilot
Create workspace settings: .vscode/settings.json
Add configuration:
json { "github.copilot.chat.codeGeneration.instructions": [ { "file": ".github/copilot-instructions.md" } ] }Create instructions file: .github/copilot-instructions.md
markdown Use the Polyhedra MCP tools for academic research tasks. Available tools: search_papers, add_citation, index_papers, etc.Reload window: Ctrl+Shift+P "Developer: Reload Window"
Windsurf
Same as Cursor, but use ~/.windsurf/mcp.json
VS Code with MCP Extension
- Install MCP extension from marketplace
- Configure in workspace settings
- Point to uvx --from polyhedra polyhedra
For detailed setup instructions, see docs/SETUP.md
Core Concepts
Project Structure
Polyhedra expects this directory structure:
my-research-project/ literature/ # Research papers (JSON, PDF) references.bib # BibTeX citations writing/ # Your papers and drafts ideas/ # Notes and brainstorming data/ # Research data .poly/ # Polyhedra metadata (auto-created) embeddings/ # Semantic search index
Semantic Search (RAG)
Polyhedra uses RAG (Retrieval Augmented Generation) to find relevant papers:
- Index papers Creates embeddings from titles and abstracts
- Query with natural language Finds semantically similar papers
- Get ranked results Papers sorted by relevance score
Citation Management
- BibTeX format for all citations
- Automatic deduplication by citation key
- Auto-generated keys from author/year/title
- Stored in eferences.bib
Using the Tools
1. Initialize Project
What it does: Creates standard research project structure
When to use: Starting a new research project
Example:
"Initialize a new research project called 'transformer-survey'"
Creates:
- 5 directories (literature, writing, ideas, data, notes)
- 2 files (README.md, references.bib)
Literature Review Generation (v2.1) 🆕
Generate AI-powered literature reviews from your paper collection.
Prerequisites
- Papers collected via
search_papersor manual JSON file - LLM API key configured (see Setup Guide)
- Anthropic (recommended):
export ANTHROPIC_API_KEY=sk-ant-... - OpenAI (alternative):
export OPENAI_API_KEY=sk-...
- Anthropic (recommended):
Basic Workflow
Step 1: Search and Collect Papers
"Search for 50 papers on transformer efficiency techniques"
Papers automatically saved to literature/papers.json
Step 2: Estimate Cost (Recommended)
"Estimate cost for reviewing these 50 papers with standard depth"
Returns: {"estimated_usd": 0.15, "paper_count": 50, "depth": "standard"}
Step 3: Generate Review
"Generate a literature review from my papers focused on mobile deployment"
Generates:
literature/review.md- Structured academic review- Auto-adds all citations to
references.bib - Returns metadata and actual cost
Step 4: Review and Refine
Open literature/review.md to see:
- ✅ Overview: Field introduction and scope
- ✅ Taxonomy: Hierarchical organization of approaches
- ✅ Critical Analysis: Strengths, weaknesses, comparisons
- ✅ Research Gaps: Underexplored areas and opportunities
- ✅ Conclusion: Summary and future directions
- ✅ Proper Citations: All papers cited as
[Author et al., Year]
Review Depth Levels
Choose the right depth for your use case:
Brief (~650 words, 2-3 pages)
Best for: Quick overviews, presentation prep, initial exploration
"Generate a brief literature review"
Output:
- High-level overview
- Major themes only
- 5-10 minute read
- Cost: $0.05-0.12 (50 papers)
Standard (~2000 words, 5-8 pages)
Best for: Paper background sections, grant proposals, comprehensive understanding
"Generate a standard literature review"
Output:
- Comprehensive coverage
- Detailed taxonomy
- Critical analysis
- Research gaps section
- 20-30 minute read
- Cost: $0.12-0.25 (50 papers)
Comprehensive (~2500 words, 10-15 pages)
Best for: Dissertation chapters, major survey papers, formal publications
"Generate a comprehensive literature review"
Output:
- Exhaustive review
- Deep analysis of each approach
- Extensive gaps section
- Methodology comparison
- 45-60 minute read
- Cost: $0.20-0.40 (50 papers)
Review Structure Types
Choose how to organize your review:
Thematic (Default)
Groups papers by research themes and approaches.
"Generate a thematic literature review"
Best for: Understanding the landscape, identifying main directions
Example sections:
- Attention Mechanisms
- Efficiency Techniques
- Mobile Architectures
- Quantization Methods
Chronological
Orders papers by publication timeline.
"Generate a chronological literature review"
Best for: Tracking field evolution, understanding historical context
Example sections:
- Early Work (2017-2019)
- Breakthrough Period (2020-2021)
- Recent Advances (2022-2024)
Methodological
Organizes by research methods used.
"Generate a methodological literature review"
Best for: Comparing approaches, identifying methodology gaps
Example sections:
- Neural Architecture Search
- Knowledge Distillation
- Pruning and Quantization
- Hardware-Aware Design
Advanced Usage
Focused Review
Narrow the scope to specific aspects:
"Generate a comprehensive review focused on quantization techniques for edge devices"
The focus parameter helps the LLM:
- Prioritize relevant papers
- Emphasize specific aspects
- Filter out tangential content
- Provide deeper analysis of focus area
Custom Output Location
"Generate a review and save to method/related-work.md"
Specific Model Selection
"Generate review using GPT-4 Turbo"
Available models:
claude-3-5-sonnet-20241022(default, recommended)claude-3-opus-20240229(higher quality, higher cost)gpt-4o(OpenAI default)gpt-4-turbo(OpenAI alternative)
Skip Research Gaps
"Generate a brief review without research gaps section"
Useful when you only need synthesis, not gap analysis.
Cost Management
Always Estimate First
For large collections or expensive depths:
"Estimate cost before generating a comprehensive review of 100 papers"
Returns detailed cost breakdown before spending credits.
Understanding Cost Warnings
If estimated cost > $0.10, Polyhedra will warn you:
⚠️ Estimated cost: $0.25 for comprehensive review of 75 papers
Add confirm_cost=true to proceed
To proceed:
"Generate the review with confirm_cost=true"
Budget Limits
Default maximum cost: $1.00 per operation
To change:
export POLYHEDRA_MAX_COST=0.50 # Set lower limit
Polyhedra will block operations exceeding the limit.
To override (not recommended):
"Generate the review with force=true"
Tracking Costs
Each generation returns actual cost:
{
"cost": {
"input_tokens": 18234,
"output_tokens": 5890,
"total_tokens": 24124,
"total_usd": 0.14
}
}
Tips & Best Practices
1. Start Small
Begin with brief reviews to understand output quality:
"Generate a brief review to see the format first"
2. Curate Papers
Better input = Better output
Ideal paper count: 20-50 papers
- Too few (<10): Shallow analysis
- Just right (20-50): Comprehensive but manageable
- Too many (>100): May hit token limits or high costs
3. Use Focus Parameter
Narrow scope improves relevance:
"Generate review focused on real-time inference optimization"
4. Check Cost for Large Collections
Always estimate for >50 papers:
"Estimate cost first for 80 papers"
5. Iterate Depth Levels
Progressive refinement:
- Start with
brieffor quick overview - Expand to
standardfor more detail - Use
comprehensiveonly for formal publications
6. Manual Refinement
Generated reviews are starting points:
- Review for accuracy
- Add domain-specific insights
- Verify citations against source papers
- Refine structure to match your needs
7. Combine with Search
Iterative workflow:
1. "Search for initial papers on topic X"
2. "Generate brief review"
3. "Based on gaps, search for papers on Y"
4. "Add new papers to literature/papers.json"
5. "Generate updated standard review"
Common Issues
"LLM service not configured"
Cause: Missing API key
Solution:
# Choose one:
export ANTHROPIC_API_KEY=sk-ant-your-key
export OPENAI_API_KEY=sk-your-key
# Restart IDE
Verify:
"Check if my LLM configuration is working"
"Papers file not found"
Cause: No papers.json exists
Solution:
"Search for papers first, then generate review"
Or manually create literature/papers.json:
[
{
"title": "Paper Title",
"authors": [{"name": "Author Name"}],
"year": 2024,
"abstract": "Paper abstract...",
"venue": "Conference Name"
}
]
"Papers file is empty"
Cause: Empty JSON array []
Solution:
"Search for papers to populate the file"
"Cost exceeds configured limit"
Cause: Estimated cost > POLYHEDRA_MAX_COST
Solutions:
- Increase limit:
export POLYHEDRA_MAX_COST=1.50 - Reduce paper count (filter to most relevant)
- Use brief depth instead of comprehensive
- Force execution: Add
force=true(not recommended)
"Review quality insufficient"
Causes & Solutions:
Too generic:
- Add specific focus parameter
- Curate papers more carefully
- Try different structure type
Missing key papers:
- Verify papers.json includes them
- Check citation coverage in metadata
Poor organization:
- Try different structure (thematic vs chronological)
- Add focus to narrow scope
Shallow analysis:
- Upgrade from brief to standard/comprehensive
- Reduce paper count for deeper analysis
"Token limit exceeded"
Cause: Too many papers for context window
Solutions:
- Reduce paper count (aim for <75)
- Use brief depth (less output tokens)
- Split into multiple focused reviews
Cost Examples (Real Scenarios)
| Scenario | Papers | Depth | Cost | Time |
|---|---|---|---|---|
| Conference presentation prep | 20 | brief | $0.06 | 1-2 min |
| Paper background section | 40 | standard | $0.14 | 2-3 min |
| PhD qualifying exam | 60 | comprehensive | $0.28 | 3-4 min |
| Grant proposal literature review | 50 | standard | $0.18 | 2-3 min |
| Dissertation chapter | 80 | comprehensive | $0.42 | 4-5 min |
| Survey paper | 100 | comprehensive | $0.55 | 5-6 min |
Costs are estimates for Anthropic Claude Sonnet. GPT-4 Turbo costs ~2.5x more.
2. Search Papers
What it does: Searches Semantic Scholar for academic papers
When to use: Literature review, finding related work
Example:
"Search for recent papers on 'attention mechanisms in transformers' published between 2020-2023, limit to 10 results"
Parameters:
- query: Search terms (required)
- limit: Max results (default: 10, max: 100)
- year_start: Filter by year (optional)
- year_end: Filter by year (optional)
Returns: Paper details with titles, authors, abstracts, citations, BibTeX
3. Get Paper Details
What it does: Gets detailed info for a specific paper by ID
When to use: Following up on a specific paper
Example:
"Get details for paper ID 204e3073870fae3d05bcbc2f6a8e263d9b72e776"
Returns: Full paper metadata, BibTeX entry, citation count
4. Add Citation
What it does: Adds a BibTeX entry to references.bib
When to use: Building your bibliography
Example:
"Add this citation to my bibliography: @article{vaswani2017attention, title={Attention is all you need}, author={Vaswani, Ashish and Shazeer, Noam}, year={2017} }"
Features:
- Automatic deduplication
- Validates BibTeX format
- Returns citation key for use in writing
5. Get Citations
What it does: Lists all citations in your bibliography
When to use: Reviewing your references, checking what's already added
Example:
"Show me all my citations"
Returns: Array of all BibTeX entries with keys
6. Index Papers
What it does: Creates semantic search index from saved papers
When to use: After collecting papers, before querying
Example:
"Index the papers in literature/recent-papers.json"
Requirements: Papers file must exist with title and abstract fields
Performance: ~2 seconds for 50 papers
7. Query Similar Papers
What it does: Semantic search over indexed papers
When to use: Finding relevant papers in your collection
Example:
"Find papers similar to 'self-attention mechanisms for NLP' from my indexed papers, show top 5"
Parameters:
- query: Natural language search (required)
- k: Number of results (default: 5)
Returns: Papers ranked by relevance score (0.0-1.0)
Requires: Papers must be indexed first
8. Save File
What it does: Writes content to a file in your project
When to use: Saving generated content, creating drafts
Example:
"Save this abstract to writing/draft-abstract.md: [your abstract text]"
Features:
- Creates parent directories automatically
- Supports append mode
- UTF-8 encoding
9. Get Context
What it does: Reads files from your project
When to use: Reviewing content, including context in prompts
Example:
"Read the contents of writing/introduction.md and ideas/key-points.md"
Features:
- Batch reading (multiple files at once)
- Reports missing files without failing
- UTF-8 decoding
Returns: Dictionary of file contents + list of missing files
10. Get Project Status
What it does: Overview of your research project
When to use: Checking progress, understanding project state
Example:
"Give me the status of my research project"
Returns:
- Paper count in literature/
- Citation count in references.bib
- RAG index status
- List of standard files
- Total file count
Research Workflows
Workflow 1: Literature Review
Goal: Find and organize relevant papers
`
"Initialize a project called 'literature-review-transformers'"
"Search for papers on 'transformer architecture' from 2017-2023, limit 20"
"Save those papers to literature/transformer-papers.json"
"Add citations for the top 5 papers to my bibliography"
"Index the papers in literature/transformer-papers.json"
"Find papers similar to 'positional encoding in transformers'"
"Get project status" `
Result: Organized collection of papers with citations ready for writing
Workflow 2: Writing with Citations
Goal: Draft a paper section with proper citations
`
"Search for papers on 'BERT pretraining' and add the top 3 to my citations"
"Show me all my citations"
"Save this introduction to writing/intro.md: [AI generates introduction with citation keys]"
"Read writing/intro.md to verify" `
Result: Draft with citation keys that match references.bib
Workflow 3: Finding Research Gaps
Goal: Identify under-explored areas
`
"Search for 'multimodal transformers' papers from 2020-2023"
"Save to literature/multimodal.json and index them"
"Query for papers about 'video understanding transformers'"
"Query for papers about 'audio-visual fusion'"
"Compare the results to find gaps" `
Result: Understand coverage of different topics in your collection
Workflow 4: Related Work Section
Goal: Build comprehensive related work
`
"Search for papers on [my topic] and save to literature/related.json"
"Index literature/related.json"
"For each subsection topic, query similar papers"
"Add relevant citations to references.bib"
"Save organized related work to writing/related-work.md" `
Result: Well-organized related work section with citations
Tips & Best Practices
Search Strategies
DO:
- Use specific technical terms: "attention mechanisms" vs "AI"
- Combine concepts: "BERT pretraining methodology"
- Filter by year for recent work: year_start=2020
- Start with small limits (5-10) and expand
DON'T:
- Use overly broad terms: "machine learning"
- Request too many results at once (API rate limits)
- Search without year filters when recency matters
Citation Management
DO:
- Let Polyhedra generate citation keys automatically
- Review citations before adding to bibliography
- Use consistent citation styles
- Check for duplicates with "Show me all my citations"
DON'T:
- Manually create citation keys (error-prone)
- Add same paper twice (auto-dedup handles this)
- Mix citation formats (stick to BibTeX)
Semantic Search
DO:
- Index papers before querying
- Re-index when adding new papers to collection
- Use natural language queries: "papers about X"
- Check relevance scores (>0.7 is high relevance)
DON'T:
- Query before indexing (returns empty results)
- Use too many keywords (semantic search handles concepts)
- Ignore low relevance scores (<0.3)
File Organization
DO:
- Keep papers in literature/ directory
- Name files descriptively: ransformer-papers-2023.json
- Use subdirectories: literature/attention/, literature/pretraining/
- Back up your eferences.bib file
DON'T:
- Store papers in random locations
- Use generic names: papers.json, data.json
- Forget to commit .poly/ to git (contains index)
Performance
DO:
- Index once, query many times
- Batch operations when possible
- Use local operations (file read/write) for speed
- Save search results to avoid re-querying
DON'T:
- Re-index on every query
- Make many small API calls (use limits)
- Query API when local search works
Troubleshooting
"No tools available"
Cause: IDE hasn't loaded Polyhedra MCP server
Fix:
- Check MCP config file location and syntax
- Restart IDE completely
- Verify installation: pip show polyhedra
- Check IDE console for error messages
"Papers not indexed. Run index_papers first"
Cause: Trying to query before indexing
Fix:
"Index the papers in literature/my-papers.json first"
Then query again.
"Papers file not found"
Cause: File path doesn't exist or incorrect
Fix:
- Check file exists: "Get project status"
- Use relative path from project root
- Verify spelling: literature/papers.json not literature/paper.json
"Invalid BibTeX format"
Cause: Malformed BibTeX entry
Fix:
- Ensure @article{key, format
- Include required fields: itle, uthor, year
- Close all braces: }
- Check for special characters in values
Example valid entry:
ibtex @article{smith2023, title={My Paper Title}, author={Smith, John and Doe, Jane}, year={2023}, journal={Conference Name} }
"Rate limit exceeded"
Cause: Too many API requests to Semantic Scholar
Fix:
- Wait 60 seconds before next request
- Reduce search limits
- Use indexed/cached papers when possible
- Polyhedra automatically retries with exponential backoff
Search returns no results
Possible causes:
- Query too specific: Try broader terms
- Year filter too narrow: Remove or expand year range
- Spelling error: Check technical term spelling
- API issue: Try again in a few minutes
Fix: Start broad, then narrow down
Slow performance
Indexing takes long:
- Normal for large collections (>100 papers)
- First run downloads ML model (~50MB)
- Subsequent runs are faster
Searches take long:
- Normal for first API call (cold start)
- API rate limiting may cause delays
- Use indexed papers for faster local search
Advanced Usage
Batch Operations
Add multiple citations:
"Search for papers on [topic], then add all of them to my bibliography"
Read multiple files:
"Read all markdown files in the writing/ directory"
Complex Queries
Semantic Scholar supports:
- Boolean operators: "attention AND transformers"
- Author filtering: "author:Vaswani"
- Venue filtering: "venue:NeurIPS"
Example:
"Search for 'author:Vaswani transformers' from 2017-2020"
Chaining Workflows
Automated pipeline:
"Search for [topic], save to literature/, index them, query for [specific aspect], add top 5 to citations, and give me a project status"
Need More Help?
- Documentation: docs/API.md - Full API reference
- Setup Guide: docs/SETUP.md - Detailed IDE setup
- Workflows: docs/WORKFLOWS.md - More examples
- Architecture: docs/ARCHITECTURE.md - Technical details
- Error Handling: docs/ERROR_HANDLING.md - All error scenarios
Quick Reference Card
| Task | Example Prompt |
|---|---|
| Initialize | "Initialize project 'my-research'" |
| Search | "Search for 'topic' papers from 2020-2023" |
| Save Results | "Save those papers to literature/papers.json" |
| Add Citation | "Add citation for the first paper" |
| Index Papers | "Index literature/papers.json" |
| Find Similar | "Find papers similar to 'concept'" |
| Check Status | "Get project status" |
| Read File | "Read writing/draft.md" |
| Save File | "Save [content] to writing/notes.md" |
| List Citations | "Show all my citations" |
**Happy Researching with Polyhedra! **