Download docs/MIGRATION_V2.1.md from polyHedra/PolyHedra: direct link, hf CLI and curl.
- Browser
- Download file 8.96 kB
-
https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/MIGRATION_V2.1.md
- Command line
-
hf download hf://spaces/polyHedra/PolyHedra/docs/MIGRATION_V2.1.md
-
curl -L -o MIGRATION_V2.1.md https://huggingface.co/spaces/polyHedra/PolyHedra/resolve/main/docs/MIGRATION_V2.1.md
Migration Guide: v2.0 β v2.1
Overview
Polyhedra v2.1 adds AI-powered literature review generation while maintaining 100% backward compatibility with v2.0.
Summary of Changes
What's New β¨
- π Literature Review Generation: Synthesize papers into structured academic reviews
- π° Cost Estimation: Pre-generation cost estimates for budget planning
- π― Multiple Review Styles: Brief, standard, or comprehensive depth
- π Research Gap Identification: Automatically identify underexplored areas
What's Unchanged β
- All 10 existing v2.0 tools work exactly the same
- No changes to existing tool APIs
- No changes to project structure
- No changes to IDE configuration
- No breaking changes whatsoever
Breaking Changes
None! v2.1 is fully backward compatible.
Upgrade Steps
Step 1: Update Polyhedra
cd polyhedra
git pull origin main
pip install -e .
Or if using pip:
pip install --upgrade polyhedra
Step 2: Restart Your IDE
Close and reopen your IDE to reload the MCP server with the new version.
Step 3: Verify Upgrade
In your IDE chat:
"List all available Polyhedra tools"
Should show 12 tools (was 10 in v2.0):
- 10 existing tools from v2.0
- 2 new tools:
generate_literature_review,estimate_review_cost
Step 4: Optional - Configure LLM (for new features)
If you want to use literature review generation:
- Get API key from Anthropic or OpenAI
- Set environment variable:
export ANTHROPIC_API_KEY=sk-ant-your-key # OR export OPENAI_API_KEY=sk-your-key - Restart IDE
If you don't configure LLM: All v2.0 tools continue working normally.
Feature Comparison
| Feature | v2.0 | v2.1 |
|---|---|---|
| Paper search | β | β |
| Citation management | β | β |
| Semantic search (RAG) | β | β |
| File operations | β | β |
| Project initialization | β | β |
| Literature review generation | β | β |
| Cost estimation | β | β |
| Research gap identification | β | β |
Configuration Changes
v2.0 Configuration (Still Works)
{
"mcpServers": {
"polyhedra": {
"command": "python",
"args": ["-m", "polyhedra.server"]
}
}
}
v2.1 Configuration (Optional Additions)
{
"mcpServers": {
"polyhedra": {
"command": "python",
"args": ["-m", "polyhedra.server"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-your-key",
"POLYHEDRA_MAX_COST": "1.00"
}
}
}
}
New environment variables (all optional):
ANTHROPIC_API_KEY: For Claude models (recommended)OPENAI_API_KEY: For GPT models (alternative)POLYHEDRA_LLM_PROVIDER: Choose provider (default: anthropic)POLYHEDRA_LLM_MODEL: Override default modelPOLYHEDRA_MAX_COST: Maximum cost per operation (default: $1.00)
Dependencies
v2.0 Dependencies
[dependencies]
mcp = "^1.0.0"
httpx = "^0.27.0"
sentence-transformers = "^2.2.0"
faiss-cpu = "^1.7.4"
bibtexparser = "^2.0.0"
v2.1 New Dependencies
# Added for LLM integration:
anthropic = "^0.40.0" # Optional: only if using Claude
openai = "^1.54.0" # Optional: only if using GPT
tiktoken = "^0.8.0" # For token counting
Installation:
pip install -e ".[llm]" # Install with LLM support
# OR
pip install -e . # Basic installation (v2.0 features only)
API Changes
No Breaking Changes
All v2.0 tool signatures remain identical.
New Tools (v2.1)
generate_literature_review
# New in v2.1
{
"name": "generate_literature_review",
"parameters": {
"papers_file": "literature/papers.json", # Optional
"focus": "mobile deployment", # Optional
"structure": "thematic", # Optional: thematic/chronological/methodological
"depth": "standard", # Optional: brief/standard/comprehensive
"include_gaps": true, # Optional
"output_path": "literature/review.md", # Optional
"llm_model": "claude-3-5-sonnet-20241022" # Optional
}
}
estimate_review_cost
# New in v2.1
{
"name": "estimate_review_cost",
"parameters": {
"paper_count": 50, # Required
"depth": "standard", # Optional
"llm_model": "claude-3-5-sonnet-20241022" # Optional
}
}
Workflow Changes
v2.0 Workflow (Still Works)
1. Search papers
2. Index papers
3. Query similar papers
4. Add citations
5. Manually write literature review
v2.1 Enhanced Workflow (Optional)
1. Search papers
2. Estimate review cost β New
3. Generate literature review β New
4. Refine and customize review
5. Citations auto-added
Common Migration Scenarios
Scenario 1: Continue Using v2.0 Features Only
No action required! Everything works exactly as before.
# Your existing workflows continue unchanged:
"Search for papers on transformers"
"Add citation for this paper"
"Index my papers"
"Find papers similar to attention mechanisms"
Scenario 2: Add Literature Review Generation
- Configure LLM API key (see Step 4 above)
- Use existing search workflows to collect papers
- Generate reviews:
"Generate a literature review from my papers"
Scenario 3: Cost-Conscious Usage
- Configure
POLYHEDRA_MAX_COSTenvironment variable - Always estimate before generating:
"Estimate cost for reviewing 50 papers"
"If under $0.20, generate the review"
Scenario 4: Team Migration
Gradual rollout recommended:
- Week 1: Upgrade to v2.1, continue using v2.0 features
- Week 2: One team member configures LLM, tests review generation
- Week 3: Share results, others configure LLM if desired
- Week 4: Establish team cost budgets and review workflows
Troubleshooting
"No new tools appearing"
- Verify upgrade:
pip show polyhedra(should show v2.1.x) - Restart IDE completely (not just reload)
- Check MCP logs in IDE for errors
"generate_literature_review fails"
Error: "LLM service not configured"
Solution: Configure ANTHROPIC_API_KEY or OPENAI_API_KEY
"Costs higher than expected"
- Check actual token usage in response
- Use
estimate_review_costbefore generating - Try brief depth or reduce paper count
- Consider using Claude Sonnet (cheaper than GPT-4)
"Want to rollback to v2.0"
pip install polyhedra==2.0.0
# Restart IDE
All v2.0 features will work. v2.1 features will be unavailable.
FAQ
Q: Do I need to reconfigure my IDE?
A: No, existing MCP configuration works unchanged.
Q: Do I need API keys for v2.0 features?
A: No, all v2.0 features work WITHOUT API keys.
Q: Will my existing projects break?
A: No, v2.1 is 100% backward compatible.
Q: Can I use both Anthropic and OpenAI?
A: Yes, set both keys. Polyhedra uses Anthropic by default, or set POLYHEDRA_LLM_PROVIDER=openai.
Q: How much do literature reviews cost?
A: Typical costs with Claude Sonnet:
- Brief (50 papers): $0.08-0.12
- Standard (50 papers): $0.12-0.20
- Comprehensive (50 papers): $0.20-0.35
Q: Can I opt out of v2.1 features?
A: Yes, simply don't configure LLM API keys. v2.0 features continue working.
Q: How do I track my LLM spending?
A: Each review generation returns actual cost in the response. Also check your provider dashboard (Anthropic/OpenAI).
Q: What if I hit rate limits?
A: Polyhedra automatically retries with backoff. For persistent issues:
- Wait 60 seconds and retry
- Check your API dashboard for limits
- Consider upgrading your account tier
Getting Help
- Documentation: docs/API.md, docs/SETUP.md, docs/USER_GUIDE.md
- GitHub Issues: https://github.com/polyhedra/polyhedra/issues
- Migration Issues: Tag with
migration-v2.1
Changelog
v2.1.0 (2024-12-07)
Added:
- Literature review generation tool (
generate_literature_review) - Cost estimation tool (
estimate_review_cost) - LLM service foundation (Anthropic Claude, OpenAI GPT)
- Support for three review depths (brief/standard/comprehensive)
- Support for three review structures (thematic/chronological/methodological)
- Research gap identification
- Cost management with configurable limits
- Comprehensive documentation updates
Changed:
- Tool count increased from 10 to 12
- Added optional LLM dependencies
- Enhanced error messages for new features
Fixed:
- No bug fixes (new feature release)
Deprecated:
- Nothing deprecated
Removed:
- Nothing removed
Security:
- API keys stored in environment variables (never in code)
- Cost limits prevent accidental overspending
Welcome to Polyhedra v2.1! π