Download docs/SETUP.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 8.74 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/SETUP.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/SETUP.md
-
curl -L -o SETUP.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/SETUP.md
IDE Setup Guide
This guide will help you configure Polyhedra in your IDE in less than 5 minutes.
Prerequisites
- Python 3.11 or higher
- One of the supported IDEs:
- Cursor
- VS Code with GitHub Copilot
- Windsurf
- VS Code with MCP extension
Installation
Step 1: Install Polyhedra
Using pip:
pip install polyhedra
Using uv (recommended):
uv pip install polyhedra
Step 2: Verify Installation
polyhedra --version
IDE Configuration
Choose your IDE and follow the specific setup instructions:
Cursor Setup
Create MCP config directory (if it doesn't exist):
mkdir -p ~/.cursorCreate or edit
~/.cursor/mcp.json:{ "mcpServers": { "polyhedra": { "command": "uvx", "args": ["--from", "polyhedra", "polyhedra"], "env": {} } } }Add
.cursorrulesto your project (optional but recommended): Copy.cursorrulesfrom the Polyhedra repository to your research project root.Restart Cursor
Verify: Open Cursor chat and type "List available Polyhedra tools"
VS Code + GitHub Copilot Setup
Install GitHub Copilot Chat extension (if not already installed)
Add to your workspace
.vscode/settings.json:{ "github.copilot.chat.codeGeneration.instructions": [ { "text": "When working on research projects, use the Polyhedra MCP tools to search papers, manage citations, and organize literature." } ], "mcp.servers": { "polyhedra": { "command": "uvx", "args": ["--from", "polyhedra", "polyhedra"], "env": {} } } }Add
.github/copilot-instructions.mdto your project (optional): Copycopilot-instructions.mdfrom the Polyhedra repository.Restart VS Code
Verify: Open Copilot Chat and ask "What Polyhedra tools are available?"
Windsurf Setup
Create MCP config directory (if it doesn't exist):
mkdir -p ~/.windsurfCreate or edit
~/.windsurf/mcp.json:{ "mcpServers": { "polyhedra": { "command": "uvx", "args": ["--from", "polyhedra", "polyhedra"], "env": {} } } }Add
.cursorrulesto your project (Windsurf uses same format): Copy.cursorrulesfrom the Polyhedra repository to your research project root.Restart Windsurf
Verify: Open chat and ask about available tools
VS Code + MCP Extension Setup
Install the MCP extension from VS Code marketplace
Add to your workspace
.vscode/settings.json:{ "mcp.servers": { "polyhedra": { "command": "uvx", "args": ["--from", "polyhedra", "polyhedra"], "env": {} } } }Restart VS Code
Verify: Check the MCP extension panel for Polyhedra tools
Initialize Your First Project
Once configured, initialize a new research project:
Create project directory:
mkdir my-research-project cd my-research-projectIn your IDE chat, run:
Use init_project to set up this research projectVerify the structure was created:
literature/ ideas/ method/ paper/ references.bib .poly/
Quick Start Example
Try this workflow in your IDE chat:
Search for papers:
Search for recent papers on "large language models" from 2023-2024Add a citation:
Add this paper to my bibliography: [paste BibTeX]Get project status:
Show me my current project status
LLM Configuration (for v2.1 Literature Review Features)
Polyhedra v2.1 adds AI-powered literature review generation. This requires an API key from Anthropic or OpenAI.
Option 1: Anthropic Claude (Recommended)
Why Claude? Better academic writing, lower cost ($3/M input, $15/M output)
Get API Key:
- Visit https://console.anthropic.com/
- Sign up or log in
- Navigate to API Keys section
- Click Create Key (name it "Polyhedra")
- Copy the key (starts with
sk-ant-)
Configure Environment Variable:
Windows:
$env:ANTHROPIC_API_KEY = "sk-ant-api03-your-key-here" # Or add permanently: setx ANTHROPIC_API_KEY "sk-ant-api03-your-key-here"Mac/Linux:
export ANTHROPIC_API_KEY=sk-ant-api03-your-key-here # Add to ~/.bashrc or ~/.zshrc for persistenceOr create
.envfile in your project:ANTHROPIC_API_KEY=sk-ant-api03-your-key-hereVerify Configuration:
# In your IDE chat: "Estimate cost for reviewing 50 papers"Should return cost estimate without errors.
Option 2: OpenAI GPT
Why GPT? You may already have an account, familiar models
Get API Key:
- Visit https://platform.openai.com/api-keys
- Sign up or log in
- Click Create new secret key
- Copy the key (starts with
sk-)
Configure:
export OPENAI_API_KEY=sk-your-key-here export POLYHEDRA_LLM_PROVIDER=openai # Optional: specify providerModel Selection (optional):
export POLYHEDRA_LLM_MODEL=gpt-4-turbo # Default: gpt-4o
Cost Management
Set maximum cost per operation (recommended):
export POLYHEDRA_MAX_COST=1.00 # Default: $1.00
Polyhedra will:
- β Estimate cost before each review generation
- β Warn if estimated cost exceeds $0.10
- β
Block operations exceeding
POLYHEDRA_MAX_COST(unless forced) - β Log all LLM API calls with token counts
Example .env file:
# LLM Provider (choose one)
ANTHROPIC_API_KEY=sk-ant-api03-your-key-here
# OPENAI_API_KEY=sk-your-key-here
# Optional: Provider selection (default: anthropic)
# POLYHEDRA_LLM_PROVIDER=anthropic
# Optional: Cost limit (default: $1.00)
POLYHEDRA_MAX_COST=0.50
# Optional: Model override
# POLYHEDRA_LLM_MODEL=claude-3-5-sonnet-20241022
Verify LLM Setup
In your IDE chat:
"Check if my LLM configuration is working"
Should confirm:
- β API key detected
- β Provider configured (anthropic or openai)
- β Connection successful
- β Ready to generate reviews
LLM Features
Once configured, you can:
Generate Literature Reviews:
"Generate a literature review from my papers focused on efficiency"Estimate Costs:
"Estimate cost for reviewing 75 papers with comprehensive depth"Check Budget:
"What's my current cost limit?"
Note: All v2.0 features (search, citations, files) work WITHOUT LLM configuration. Only literature review generation requires API keys.
Troubleshooting
"Command not found: uvx"
Install uv:
pip install uv
Or use python -m polyhedra instead:
{
"command": "python",
"args": ["-m", "polyhedra"]
}
"No tools available"
- Check that Polyhedra is installed:
pip list | grep polyhedra - Verify the MCP config file is in the correct location
- Restart your IDE completely
- Check IDE logs for MCP connection errors
"Tool execution failed"
- Verify you're in a project directory
- Check that required files exist (e.g.,
literature/papers.jsonfor indexing) - Ensure you have internet connectivity for paper searches
"LLM service not configured"
This error appears when trying to use literature review generation without API keys:
- Set
ANTHROPIC_API_KEYorOPENAI_API_KEYenvironment variable - Restart your IDE to pick up the new environment variable
- Verify with:
"Check if my LLM configuration is working"
"API rate limit exceeded"
Anthropic: 50 requests/minute limit
- Wait 60 seconds and retry
- Check your API usage dashboard
OpenAI: Varies by account tier
- Upgrade your account tier
- Wait for rate limit reset
"Cost exceeds configured limit"
If you see: "Estimated cost $0.75 exceeds limit $0.50"
Options:
- Increase limit:
export POLYHEDRA_MAX_COST=1.00 - Reduce paper count or use brief depth
- Force execution: Add
force=trueto your request (not recommended)
Next Steps
- Read the API Documentation for detailed tool information
- Follow Example Workflows for common research tasks
- Check the Architecture Guide to understand how Polyhedra works
Getting Help
- GitHub Issues: https://github.com/polyhedra/polyhedra/issues
- Documentation: https://github.com/polyhedra/polyhedra#readme