pypi-query-mcp/pypi_query_mcp/prompts/package_analysis.py

"""Package analysis prompt templates for PyPI MCP server."""

from typing import Annotated, Literal

from fastmcp import Context
from pydantic import Field


class Message:
    """Simple message class for prompt templates."""

    def __init__(self, text: str, role: str = "user"):
        self.text = text
        self.role = role


async def analyze_package_quality(
    package_name: Annotated[str, Field(description="Name of the PyPI package to analyze")],
    version: Annotated[str | None, Field(description="Specific version to analyze")] = None,
    ctx: Context | None = None,
) -> list[Message]:
    """Generate a comprehensive package quality analysis prompt.

    This prompt template helps analyze a Python package's quality, maintenance status,
    security, performance, and overall suitability for use in projects.
    """
    version_text = f" version {version}" if version else ""

    return [
        Message(
            f"""Please provide a comprehensive quality analysis of the Python package '{package_name}'{version_text}.

Analyze the following aspects:

## 📊 Package Overview
- Package purpose and functionality
- Current version and release history
- Maintenance status and activity

## 🔧 Technical Quality
- Code quality indicators
- Test coverage and CI/CD setup
- Documentation quality
- API design and usability

## 🛡️ Security & Reliability
- Known security vulnerabilities
- Dependency security assessment
- Stability and backward compatibility

## 📈 Community & Ecosystem
- Download statistics and popularity
- Community support and contributors
- Issue resolution and responsiveness

## 🎯 Recommendations
- Suitability for production use
- Alternative packages to consider
- Best practices for integration

Please provide specific examples and actionable insights where possible."""
        )
    ]


async def compare_packages(
    packages: Annotated[
        list[str],
        Field(description="List of package names to compare", min_length=2, max_length=5)
    ],
    use_case: Annotated[
        str,
        Field(description="Specific use case or project context for comparison")
    ],
    criteria: Annotated[
        list[str] | None,
        Field(description="Specific criteria to focus on (e.g., performance, security, ease of use)")
    ] = None,
    ctx: Context | None = None,
) -> list[Message]:
    """Generate a detailed package comparison prompt.

    This prompt template helps compare multiple Python packages to determine
    the best choice for a specific use case.
    """
    packages_text = ", ".join(f"'{pkg}'" for pkg in packages)
    criteria_text = ""
    if criteria:
        criteria_text = f"\n\nFocus particularly on these criteria: {', '.join(criteria)}"

    return [
        Message(
            f"""Please provide a detailed comparison of these Python packages: {packages_text}

## 🎯 Use Case Context
{use_case}{criteria_text}

## 📋 Comparison Framework

For each package, analyze:

### Core Functionality
- Feature completeness for the use case
- API design and ease of use
- Performance characteristics

### Ecosystem & Support
- Documentation quality
- Community size and activity
- Learning resources availability

### Technical Considerations
- Dependencies and compatibility
- Installation and setup complexity
- Integration with other tools

### Maintenance & Reliability
- Release frequency and versioning
- Bug fix responsiveness
- Long-term viability

## 🏆 Final Recommendation

Provide a clear recommendation with:
- Best overall choice and why
- Specific scenarios where each package excels
- Migration considerations if switching between them

Please include specific examples and quantitative data where available."""
        )
    ]


async def suggest_alternatives(
    package_name: Annotated[str, Field(description="Name of the package to find alternatives for")],
    reason: Annotated[
        Literal["deprecated", "security", "performance", "licensing", "maintenance", "features"],
        Field(description="Reason for seeking alternatives")
    ],
    requirements: Annotated[
        str | None,
        Field(description="Specific requirements or constraints for alternatives")
    ] = None,
    ctx: Context | None = None,
) -> list[Message]:
    """Generate a prompt for finding package alternatives.

    This prompt template helps find suitable alternatives to a Python package
    based on specific concerns or requirements.
    """
    reason_context = {
        "deprecated": "the package is deprecated or no longer maintained",
        "security": "security vulnerabilities or concerns",
        "performance": "performance issues or requirements",
        "licensing": "licensing conflicts or restrictions",
        "maintenance": "poor maintenance or lack of updates",
        "features": "missing features or functionality gaps"
    }

    reason_text = reason_context.get(reason, reason)
    requirements_text = f"\n\nSpecific requirements: {requirements}" if requirements else ""

    return [
        Message(
            f"""I need to find alternatives to the Python package '{package_name}' because of {reason_text}.{requirements_text}

Please help me identify suitable alternatives by analyzing:

## 🔍 Alternative Discovery
- Popular packages with similar functionality
- Emerging or newer solutions
- Enterprise or commercial alternatives if relevant

## 📊 Alternative Analysis

For each suggested alternative:

### Functional Compatibility
- Feature parity with '{package_name}'
- API similarity and migration effort
- Unique advantages or improvements

### Quality Assessment
- Maintenance status and community health
- Documentation and learning curve
- Performance comparisons

### Migration Considerations
- Breaking changes from '{package_name}'
- Migration tools or guides available
- Estimated effort and timeline

## 🎯 Recommendations

Provide:
- Top 3 recommended alternatives ranked by suitability
- Quick migration path for the best option
- Pros and cons summary for each alternative
- Any hybrid approaches or gradual migration strategies

Please include specific examples of how to replace key functionality from '{package_name}'."""
        )
    ]