PolyHedra / docs /MIGRATION_V2.1.md
yf176
Deploy Polyhedra to HF Spaces
891fe52
|
Raw History Blame Contribute Delete
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

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:

  1. Get API key from Anthropic or OpenAI
  2. Set environment variable:
    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)

{
  "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 model
  • POLYHEDRA_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

  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"

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

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! πŸŽ‰