Download docs/API.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 27.7 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/API.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/API.md
-
curl -L -o API.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/API.md
API Reference
Complete reference for all Polyhedra MCP tools.
Version 2.1 includes 12 tools total (10 from v2.0 + 2 new literature review tools).
Table of Contents
- API Reference
Literature Search
search_papers
Search for academic papers using Semantic Scholar.
Purpose: Discover papers by keywords, authors, or topics across 200M+ publications.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | Search query (keywords, author names, topics) |
year_range |
string | No | Filter by publication year (e.g., "2020-2024") |
limit |
integer | No | Maximum results (default: 10, max: 100) |
fields |
array[string] | No | Fields to include (default: title, authors, year, abstract, citationCount) |
Returns:
{
"papers": [
{
"paperId": "abc123",
"title": "Attention Is All You Need",
"authors": [{"name": "Ashish Vaswani"}],
"year": 2017,
"abstract": "The dominant sequence...",
"citationCount": 75000,
"url": "https://semanticscholar.org/paper/abc123"
}
],
"total": 1,
"query": "transformers attention"
}
Example Usage:
Search for papers on "neural networks" published 2022-2024 with high citations
Common Patterns:
- By topic:
"transformers in nlp" - By author:
"author:Hinton neural networks" - Recent papers: Combine with
year_range: "2023-2024" - Highly cited: Sort results by
citationCount
Error Scenarios:
- Network error: Returns cached results if available
- Invalid year_range: Falls back to all years
- Empty results: Suggests query refinements
- Rate limit: Automatically retries with backoff
Related Tools:
- Use
get_paperfor detailed information on specific results - Use
index_papersto enable semantic search on results
get_paper
Get detailed information about a specific paper.
Purpose: Retrieve comprehensive metadata for a single paper by ID.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
paper_id |
string | Yes | Semantic Scholar paper ID (e.g., "abc123") |
fields |
array[string] | No | Fields to retrieve (default: all available) |
Returns:
{
"paperId": "abc123",
"title": "Attention Is All You Need",
"authors": [
{"authorId": "456", "name": "Ashish Vaswani"}
],
"year": 2017,
"abstract": "The dominant sequence...",
"citationCount": 75000,
"referenceCount": 35,
"influentialCitationCount": 12000,
"venue": "NeurIPS",
"url": "https://semanticscholar.org/paper/abc123",
"openAccessPdf": {"url": "https://arxiv.org/pdf/1706.03762.pdf"},
"fieldsOfStudy": ["Computer Science"],
"citations": [...],
"references": [...]
}
Example Usage:
Get detailed information for paper abc123
Common Patterns:
- Get full metadata: Use default fields
- Get citations only:
fields: ["citations"] - Get references:
fields: ["references"] - Check PDF availability: Look for
openAccessPdf
Error Scenarios:
- Invalid paper_id: Returns error with suggested format
- Paper not found: Returns 404 with similar papers suggestion
- Network error: Returns cached data if available
Related Tools:
- Use after
search_papersto get full details - Use with
add_citationto add to bibliography
query_similar_papers
Find papers similar to a query using semantic search.
Purpose: Discover related papers through RAG-powered semantic similarity.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
query |
string | Yes | Natural language query or research question |
limit |
integer | No | Maximum results (default: 10) |
min_similarity |
float | No | Minimum similarity score 0-1 (default: 0.7) |
Returns:
{
"papers": [
{
"paperId": "abc123",
"title": "Attention Is All You Need",
"similarity": 0.92,
"reason": "Discusses transformer architecture and attention mechanisms"
}
],
"query": "self-attention in neural networks"
}
Example Usage:
Find papers similar to "improving model interpretability with attention visualization"
Common Patterns:
- Research questions:
"How do transformers handle long sequences?" - Topic exploration:
"alternatives to BERT for document classification" - Methodology search:
"training strategies for large language models" - Gap analysis: Find what's missing in current literature
Requirements:
- Must call
index_papersfirst to build search index - Index must contain relevant papers for query
Error Scenarios:
- Index not built: Returns message to call
index_papersfirst - No similar papers: Returns empty list with suggestion to search more papers
- Model not loaded: Downloads embedding model (~400MB) automatically
Related Tools:
- Use
index_papersbefore querying - Use
search_papersto collect papers to index
index_papers
Build semantic search index from collected papers.
Purpose: Enable RAG-powered similarity search across your paper collection.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
papers |
array[object] | Yes | List of papers to index (from search_papers) |
force_rebuild |
boolean | No | Rebuild index even if exists (default: false) |
Paper Object Schema:
{
"paperId": "abc123",
"title": "Paper Title",
"abstract": "Paper abstract text...",
"year": 2023,
"authors": [{"name": "Author Name"}]
}
Returns:
{
"indexed_count": 25,
"total_papers": 25,
"index_path": "/path/to/.polyhedra/embeddings.index",
"model": "sentence-transformers/all-MiniLM-L6-v2"
}
Example Usage:
Index the papers I just searched for to enable semantic search
Common Patterns:
Search + Index workflow:
1. Search for papers on topic X 2. Index the results 3. Query similar papers with research questionsIncremental indexing:
- Index papers as you discover them
force_rebuild: falseappends to existing index
Rebuild index:
- Use
force_rebuild: trueto start fresh - Useful when changing paper collection focus
- Use
Performance Notes:
- First run downloads embedding model (~400MB)
- Indexing 100 papers takes ~10-30 seconds
- Index is persisted in
.polyhedra/embeddings.index
Error Scenarios:
- Missing abstract: Uses title only for indexing
- Duplicate papers: Automatically deduplicated by paperId
- Disk full: Returns error with space requirements
Related Tools:
- Use
search_papersto collect papers to index - Use
query_similar_papersafter indexing
Citation Management
add_citation
Add BibTeX entry to project bibliography.
Purpose: Maintain formatted citations for papers you reference.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
citation_key |
string | Yes | Unique BibTeX key (e.g., "vaswani2017attention") |
bibtex |
string | Yes | Complete BibTeX entry |
BibTeX Format:
@article{vaswani2017attention,
title={Attention Is All You Need},
author={Vaswani, Ashish and Shazeer, Noam and ...},
journal={Advances in neural information processing systems},
volume={30},
year={2017}
}
Returns:
{
"success": true,
"citation_key": "vaswani2017attention",
"file": "references.bib",
"total_citations": 42
}
Example Usage:
Add this BibTeX citation with key "hinton2012imagenet": @article{...}
Common Patterns:
From paper details:
1. Get paper details with get_paper 2. Generate BibTeX from metadata 3. Add to bibliographyBatch citations:
- Add multiple citations in sequence
- Automatically creates
references.bibif missing
Key naming conventions:
author_year_keyword(e.g.,vaswani2017attention)firstauthor_etal_year(e.g.,brown_etal_2020)
Validation:
- Checks for valid BibTeX syntax
- Prevents duplicate citation keys
- Validates required fields (@article, @inproceedings, etc.)
Error Scenarios:
- Invalid BibTeX: Returns syntax error with line number
- Duplicate key: Suggests appending suffix (e.g.,
_v2) - File locked: Retries with exponential backoff
- Disk full: Returns error with space needed
Related Tools:
- Use
get_citationsto view all citations - Use
get_paperto get BibTeX for a paper
get_citations
List all citations in project bibliography.
Purpose: View and manage your collected citations.
Parameters: None
Returns:
{
"citations": [
{
"key": "vaswani2017attention",
"type": "article",
"title": "Attention Is All You Need",
"authors": "Vaswani, Ashish and Shazeer, Noam and ...",
"year": "2017",
"venue": "Advances in neural information processing systems"
}
],
"total": 1,
"file": "references.bib"
}
Example Usage:
Show me all the citations in my bibliography
Common Patterns:
Review citations:
- Check what papers you've cited
- Find citation keys for writing
Export bibliography:
- Copy references.bib to document
- Use with LaTeX
\bibliography{references}
Citation search:
- Find citation key by author/title
- Check if paper already cited
Output Format:
- Parses BibTeX into structured JSON
- Sorted by citation key alphabetically
- Includes total count for overview
Error Scenarios:
- No references.bib: Returns empty list with suggestion to add citations
- Corrupted file: Returns error with validation details
- Read permission: Returns error with file path
Related Tools:
- Use
add_citationto add new citations - Use
save_fileto export formatted bibliography
File Operations
save_file
Write content to a project file.
Purpose: Create or update research documents, notes, and outputs.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | Yes | File path relative to project root |
content |
string | Yes | Content to write |
create_dirs |
boolean | No | Create parent directories (default: true) |
Returns:
{
"success": true,
"path": "literature-review/transformers.md",
"bytes_written": 1024,
"created": true
}
Example Usage:
Save this literature review to "papers/summary.md": [content]
Common Patterns:
Research notes:
Save paper summaries to notes/ Track ideas in ideas.mdGenerated content:
Write literature review sections Generate paper outlines Create annotated bibliographiesData organization:
Save paper metadata as JSON Export search results Store processed data
Safety Features:
- Creates parent directories automatically
- UTF-8 encoding for international characters
- Atomic writes (tmp file + rename)
- Preserves original on write failure
Path Resolution:
- Relative to project root
- Supports nested paths:
papers/2024/summary.md - Normalizes path separators (cross-platform)
Error Scenarios:
- Invalid path: Returns error with valid path format
- Permission denied: Returns error with required permissions
- Disk full: Returns error with space needed
- Invalid UTF-8: Returns encoding error
Related Tools:
- Use
get_contextto read files - Use
get_project_statusto see project structure
get_context
Read content from project files.
Purpose: Access research documents, notes, and data files.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
paths |
array[string] | Yes | List of file paths to read (relative to project) |
Returns:
{
"files": [
{
"path": "notes/summary.md",
"content": "# Literature Review\n\n...",
"size": 1024,
"encoding": "utf-8"
}
],
"total": 1
}
Example Usage:
Read the files: notes/summary.md, papers/metadata.json
Common Patterns:
Review research:
Read literature review drafts Check project notes Review paper summariesContext for generation:
Read existing content before updating Get context for writing new sections Check what's already documentedBatch reading:
Read all markdown files in notes/ Get all paper summaries Load configuration files
File Types Supported:
- Text files:
.md,.txt,.json,.yaml - Code:
.py,.js,.tex - Config:
.bib,.toml,.ini - Any UTF-8 encoded file
Performance:
- Reads up to 10 files in parallel
- Max file size: 10MB per file
- Returns errors for individual files without failing entire operation
Error Scenarios:
- File not found: Returns empty content with error message
- Permission denied: Skips file with error in response
- Binary file: Returns error suggesting text files only
- Encoding error: Tries fallback encodings (latin-1, cp1252)
Related Tools:
- Use
save_fileto write files - Use
get_project_statusto see available files
Project Management
init_project
Initialize a new research project structure.
Purpose: Create standardized directory structure and starter files.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
project_name |
string | Yes | Name of the project (used for directory naming) |
base_path |
string | No | Parent directory (default: current working directory) |
Created Structure:
project_name/
βββ .polyhedra/ # Tool data (index, cache)
βββ papers/ # Paper PDFs and metadata
βββ notes/ # Research notes
βββ literature-review/ # Literature review drafts
βββ data/ # Datasets and processed data
βββ references.bib # BibTeX bibliography
βββ README.md # Project overview
Returns:
{
"project_name": "my-research",
"path": "/home/user/my-research",
"created_dirs": [
".polyhedra",
"papers",
"notes",
"literature-review",
"data"
],
"created_files": [
"references.bib",
"README.md"
]
}
Example Usage:
Initialize a new research project called "transformer-survey"
Common Patterns:
Start new research:
1. Initialize project 2. Set project as working directory 3. Begin searching for papersOrganize existing research:
1. Create project structure 2. Move existing files into structure 3. Start using tools
Idempotent Operation:
- Safe to run multiple times
- Won't overwrite existing files
- Only creates missing directories
- Reports what was created vs. already existed
README Template:
# [Project Name]
## Research Question
TODO: Define your research question
## Papers
Papers are organized in the `papers/` directory.
## Notes
Research notes are in the `notes/` directory.
## Citations
Bibliography is in `references.bib`.
Error Scenarios:
- Directory exists: Reports existing, doesn't fail
- Permission denied: Returns error with required permissions
- Invalid project name: Suggests valid naming (alphanumeric, dashes, underscores)
Related Tools:
- Use
get_project_statusto see project structure - Use
save_fileandget_contextfor file operations
get_project_status
Get overview of project structure and contents.
Purpose: Understand project organization and find files.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string | No | Project root path (default: current directory) |
Returns:
{
"project_path": "/home/user/my-research",
"structure": {
"papers": {
"file_count": 5,
"total_size": "25.3 MB",
"files": ["paper1.pdf", "paper2.pdf"]
},
"notes": {
"file_count": 3,
"files": ["summary.md", "ideas.md"]
},
"literature-review": {
"file_count": 1,
"files": ["draft.md"]
}
},
"citations": {
"total": 42,
"file": "references.bib"
},
"index": {
"exists": true,
"papers_indexed": 25,
"last_updated": "2024-01-15T10:30:00Z"
}
}
Example Usage:
Show me the status of my research project
Common Patterns:
Project overview:
Check what files exist See how many papers collected Review citation countBefore writing:
Check existing structure Find where to save new content See what's already documentedProgress tracking:
Monitor paper collection growth Track documentation progress Check index status
Status Indicators:
- Papers: Count, total size, recent additions
- Notes: File count, last modified
- Literature Review: Section count, word count
- Citations: Total count in bibliography
- Index: Existence, paper count, freshness
Error Scenarios:
- Not a project: Suggests running
init_project - Permission denied: Returns error with path
- Corrupted structure: Reports issues found
Related Tools:
- Use
init_projectto create project - Use
get_contextto read specific files - Use
get_citationsfor detailed citation info
Literature Review Generation (v2.1)
generate_literature_review
Generate structured academic literature review from paper collection.
Purpose: Synthesize 10-100 papers into coherent academic review with proper citations, taxonomy, critical analysis, and research gaps.
Prerequisites:
- LLM API key configured (
ANTHROPIC_API_KEYorOPENAI_API_KEY) - Papers file from
search_papersor manually created JSON
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
papers_file |
string | No | Path to papers JSON (default: "literature/papers.json") |
focus |
string | No | Specific focus area for review |
structure |
string | No | Organization: "thematic"/"chronological"/"methodological" (default: "thematic") |
depth |
string | No | Review depth: "brief"/"standard"/"comprehensive" (default: "standard") |
include_gaps |
boolean | No | Include research gaps section (default: true) |
output_path |
string | No | Where to save review (default: "literature/review.md") |
llm_model |
string | No | Model override (default: claude-3-5-sonnet-20241022) |
Returns:
{
"success": true,
"saved_to": "literature/review.md",
"metadata": {
"paper_count": 47,
"word_count": 3542,
"sections": ["Overview", "Taxonomy", "Critical Analysis", "Research Gaps", "Conclusion"],
"citations_found": 45,
"citation_coverage": 0.96,
"research_gaps": [
{
"title": "Efficiency at Scale",
"description": "Current transformers struggle with sequences >10K tokens"
}
]
},
"cost": {
"input_tokens": 18234,
"output_tokens": 5890,
"total_tokens": 24124,
"total_usd": 0.14
},
"citations_added": 47
}
Review Depth Levels:
| Depth | Words | Pages | Cost (50 papers) | Use Case |
|---|---|---|---|---|
| brief | ~650 | 2-3 | $0.08-0.12 | Quick overview, presentation prep |
| standard | ~2000 | 5-8 | $0.12-0.20 | Paper background section, grant proposals |
| comprehensive | ~2500 | 10-15 | $0.20-0.35 | Dissertation chapters, major surveys |
Structure Types:
- thematic: Groups papers by research themes and approaches (recommended for most cases)
- chronological: Orders papers by publication timeline (good for tracking field evolution)
- methodological: Organizes by research methods used (good for comparing techniques)
Example Usage:
"Generate a literature review from my papers focused on mobile deployment"
"Generate a comprehensive review with chronological structure"
"Generate brief review without research gaps, save to method/background.md"
Common Patterns:
- Quick Synopsis: Use
depth="brief"for rapid overview - Focused Review: Set
focusparameter to narrow scope - Cost-Conscious: Use
estimate_review_costfirst - Custom Location: Set
output_pathto save anywhere in project - Chronological Survey: Use
structure="chronological"for historical perspective
Error Scenarios:
| Error | Cause | Solution |
|---|---|---|
| "LLM service not configured" | Missing API key | Set ANTHROPIC_API_KEY or OPENAI_API_KEY |
| "Papers file not found" | No papers.json | Run search_papers first or create file |
| "Papers file is empty" | Empty JSON array | Search for papers or add manually |
| "API rate limit exceeded" | Too many requests | Wait 60 seconds and retry |
| "Token limit exceeded" | Too many papers | Reduce paper count or use brief depth |
Cost Guidance:
- 25 papers, brief: $0.05-0.08
- 50 papers, standard: $0.12-0.20
- 75 papers, comprehensive: $0.25-0.40
- 100 papers, comprehensive: $0.35-0.60
Cost scales with:
- Number of papers (more input tokens)
- Review depth (more output tokens)
- Model choice (Claude Sonnet < GPT-4 Turbo)
Output Format:
Generated review includes:
- Overview: Field introduction and scope
- Taxonomy: Hierarchical organization of approaches
- Critical Analysis: Strengths, weaknesses, comparisons
- Research Gaps (if enabled): Underexplored areas and opportunities
- Conclusion: Summary and future directions
- Proper Citations: All papers cited as
[Author et al., Year]
Related Tools:
- Use
search_papersto find papers first - Use
estimate_review_costto check cost before generation - Use
add_citationto add more citations manually - Use
save_fileto modify and save the review
estimate_review_cost
Estimate cost before generating literature review.
Purpose: Get accurate cost estimate without consuming API credits. Helps budget and plan expensive operations.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
paper_count |
number | Yes | Number of papers to review |
depth |
string | No | Review depth (default: "standard") |
llm_model |
string | No | Model to use (affects pricing) |
Returns:
{
"estimated_input_tokens": 18000,
"estimated_output_tokens": 2000,
"estimated_total_tokens": 20000,
"estimated_usd": 0.15,
"paper_count": 50,
"depth": "standard"
}
Example Usage:
"Estimate cost for reviewing 75 papers with comprehensive depth"
"How much will it cost to generate a brief review of 30 papers?"
Cost Examples:
| Papers | Depth | Model | Estimated Cost |
|---|---|---|---|
| 25 | brief | Claude Sonnet | $0.05-0.08 |
| 50 | standard | Claude Sonnet | $0.12-0.20 |
| 50 | standard | GPT-4 Turbo | $0.30-0.40 |
| 75 | comprehensive | Claude Sonnet | $0.25-0.40 |
| 100 | comprehensive | Claude Sonnet | $0.40-0.65 |
When to Use:
- Before generating reviews with >50 papers
- When using comprehensive depth
- When working with budget constraints
- Before batch processing multiple reviews
Accuracy: Estimates are typically within Β±20% of actual cost. Actual cost depends on:
- Actual paper abstract lengths (estimated at 300 words avg)
- LLM's response length (may vary from target)
- Model pricing changes
Related Tools:
- Use before
generate_literature_reviewfor cost-conscious workflows - Combine with
get_project_statusto track total costs
Error Handling
All tools follow consistent error handling patterns:
Error Response Format
{
"error": true,
"message": "Human-readable error description",
"error_type": "NetworkError",
"details": {
"path": "/path/to/file",
"suggestion": "Try checking your internet connection"
}
}
Common Error Types
| Error Type | Description | Recovery |
|---|---|---|
NetworkError |
API or connection issues | Retries automatically, uses cache |
FileNotFoundError |
File doesn't exist | Returns suggestion for valid path |
ValidationError |
Invalid input parameters | Returns validation details |
RateLimitError |
API rate limit exceeded | Waits and retries automatically |
IndexNotBuiltError |
Semantic index missing | Suggests calling index_papers |
Automatic Retries
- Network errors: 3 retries with exponential backoff
- Rate limits: Waits for reset time, then retries
- Transient errors: Retries with jitter
Graceful Degradation
- Offline mode: Uses cached data when available
- Partial results: Returns successful operations even if some fail
- Fallbacks: Switches to alternative methods when primary fails
See Error Handling Guide for detailed troubleshooting.
Rate Limits & Performance
Semantic Scholar API
- Rate limit: 100 requests/5 minutes
- Burst: 10 requests/second
- Handling: Automatic backoff and retry
Local Operations
- File reads: No limit, cached in memory
- File writes: No limit, atomic operations
- Indexing: ~100 papers/minute (after model download)
Best Practices
- Batch operations when possible
- Reuse index instead of rebuilding
- Cache search results for repeated queries
- Use specific queries to reduce API calls
Version Compatibility
- Python: 3.11+
- MCP SDK: 1.0+
- Semantic Scholar API: v1
- IDEs: Cursor 0.40+, VS Code 1.85+, Windsurf 1.0+
For updates and changelog, see GitHub Releases.