|
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
8.96 kB
| # 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 | |
| ```bash | |
| cd polyhedra | |
| git pull origin main | |
| pip install -e . | |
| ``` | |
| Or if using pip: | |
| ```bash | |
| 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**: | |
| 1. Get API key from [Anthropic](https://console.anthropic.com/) or [OpenAI](https://platform.openai.com/) | |
| 2. Set environment variable: | |
| ```bash | |
| export ANTHROPIC_API_KEY=sk-ant-your-key | |
| # OR | |
| export OPENAI_API_KEY=sk-your-key | |
| ``` | |
| 3. 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) | |
| ```json | |
| { | |
| "mcpServers": { | |
| "polyhedra": { | |
| "command": "python", | |
| "args": ["-m", "polyhedra.server"] | |
| } | |
| } | |
| } | |
| ``` | |
| ### v2.1 Configuration (Optional Additions) | |
| ```json | |
| { | |
| "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 model | |
| - `POLYHEDRA_MAX_COST`: Maximum cost per operation (default: $1.00) | |
| ## Dependencies | |
| ### v2.0 Dependencies | |
| ```toml | |
| [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 | |
| ```toml | |
| # 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**: | |
| ```bash | |
| 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 | |
| ```python | |
| # 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 | |
| ```python | |
| # 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 | |
| 1. Configure LLM API key (see Step 4 above) | |
| 2. Use existing search workflows to collect papers | |
| 3. Generate reviews: | |
| ``` | |
| "Generate a literature review from my papers" | |
| ``` | |
| ### Scenario 3: Cost-Conscious Usage | |
| 1. Configure `POLYHEDRA_MAX_COST` environment variable | |
| 2. Always estimate before generating: | |
| ``` | |
| "Estimate cost for reviewing 50 papers" | |
| "If under $0.20, generate the review" | |
| ``` | |
| ### Scenario 4: Team Migration | |
| **Gradual rollout recommended**: | |
| 1. **Week 1**: Upgrade to v2.1, continue using v2.0 features | |
| 2. **Week 2**: One team member configures LLM, tests review generation | |
| 3. **Week 3**: Share results, others configure LLM if desired | |
| 4. **Week 4**: Establish team cost budgets and review workflows | |
| ## Troubleshooting | |
| ### "No new tools appearing" | |
| 1. Verify upgrade: `pip show polyhedra` (should show v2.1.x) | |
| 2. Restart IDE completely (not just reload) | |
| 3. 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" | |
| 1. Check actual token usage in response | |
| 2. Use `estimate_review_cost` before generating | |
| 3. Try brief depth or reduce paper count | |
| 4. Consider using Claude Sonnet (cheaper than GPT-4) | |
| ### "Want to rollback to v2.0" | |
| ```bash | |
| 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](API.md), [docs/SETUP.md](SETUP.md), [docs/USER_GUIDE.md](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!** π | |