mcp-souschef 3.2.0__py3-none-any.whl → 3.5.2__py3-none-any.whl

souschef/converters/template.py

@@ -1,6 +1,7 @@
 """Chef ERB template to Jinja2 converter."""
 
 from pathlib import Path
+from typing import Any
 
 from souschef.parsers.template import (
     _convert_erb_to_jinja2,
@@ -168,10 +169,126 @@ def convert_template_with_ai(erb_path: str, ai_service=None) -> dict:
     # Add conversion method metadata
     result["conversion_method"] = "rule-based"
 
-    # Future enhancement: Use AI service to validate/improve complex conversions
-    if ai_service is not None:
-        # AI validation/improvement logic deferred to future enhancement
-        # when AI integration becomes more critical to the template conversion process
-        pass
+    # Use AI service to validate and improve complex conversions
+    if ai_service is not None and result.get("success"):
+        try:
+            # Enhanced AI validation for template conversion
+            result = _enhance_template_with_ai(result, erb_path, ai_service)
+            result["conversion_method"] = "ai-enhanced"
+        except Exception as e:
+            # If AI enhancement fails, return the rule-based result
+            result["ai_enhancement_error"] = str(e)
+            result["conversion_method"] = "rule-based-fallback"
 
     return result
+
+
+def _enhance_template_with_ai(
+    rule_based_result: dict, erb_path: str, ai_service: Any
+) -> dict:
+    """
+    Enhance rule-based template conversion using AI validation.
+
+    Args:
+        rule_based_result: Result from rule-based conversion
+        erb_path: Path to original ERB template
+        ai_service: AI service instance (Anthropic, OpenAI, etc.)
+
+    Returns:
+        Enhanced conversion result with AI improvements
+
+    """
+    # Read original ERB content
+    file_path = Path(erb_path)
+    with file_path.open(encoding="utf-8") as f:
+        erb_content = f.read()
+
+    jinja2_content = rule_based_result.get("jinja2_template", "")
+
+    # Create validation prompt
+    prompt = f"""You are an expert in both Chef ERB templates and \
+Ansible Jinja2 templates.
+
+Review the following ERB to Jinja2 conversion and provide feedback:
+
+**Original ERB Template:**
+```erb
+{erb_content}
+```
+
+**Converted Jinja2 Template:**
+```jinja2
+{jinja2_content}
+```
+
+Analyse the conversion and provide:
+1. Validation: Is the conversion accurate and complete?
+2. Issues: Any Ruby logic that wasn't properly converted?
+3. Improvements: Suggested improvements for better Jinja2 syntax
+4. Security: Any security concerns in the template
+
+Respond in JSON format:
+{{
+    "valid": true/false,
+    "issues": ["list of issues"],
+    "improvements": ["list of improvements"],
+    "security_concerns": ["list of security concerns"],
+    "improved_template": "improved Jinja2 template if applicable"
+}}
+"""
+
+    # Call AI service based on type
+    response_text = ""
+
+    if hasattr(ai_service, "messages") and hasattr(ai_service.messages, "create"):
+        # Anthropic API
+        response = ai_service.messages.create(
+            model="claude-3-5-sonnet-20241022",
+            max_tokens=2000,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        response_text = response.content[0].text
+    elif hasattr(ai_service, "chat") and hasattr(ai_service.chat, "completions"):
+        # OpenAI API
+        response = ai_service.chat.completions.create(
+            model="gpt-4o",
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=2000,
+        )
+        response_text = response.choices[0].message.content
+    else:
+        # Unsupported AI service
+        return rule_based_result
+
+    # Parse AI response
+    import json
+    import re
+
+    # Extract JSON from response (may be wrapped in markdown code blocks)
+    json_match = re.search(r"```json\s*(\{[^\}]*\})\s*```", response_text, re.DOTALL)
+    if json_match:
+        response_text = json_match.group(1)
+
+    try:
+        ai_feedback = json.loads(response_text)
+
+        # Enhance result with AI feedback
+        enhanced_result = rule_based_result.copy()
+        enhanced_result["ai_validation"] = {
+            "valid": ai_feedback.get("valid", True),
+            "issues": ai_feedback.get("issues", []),
+            "improvements": ai_feedback.get("improvements", []),
+            "security_concerns": ai_feedback.get("security_concerns", []),
+        }
+
+        # Use improved template if provided and valid
+        if ai_feedback.get("improved_template") and ai_feedback.get("valid"):
+            enhanced_result["jinja2_template"] = ai_feedback["improved_template"]
+            enhanced_result["ai_improved"] = True
+
+        return enhanced_result
+
+    except json.JSONDecodeError:
+        # If AI response isn't valid JSON, add raw feedback
+        rule_based_result["ai_feedback_raw"] = response_text
+        return rule_based_result

souschef/core/ai_schemas.py

@@ -0,0 +1,81 @@
+"""
+Pydantic schemas for AI structured outputs.
+
+This module defines schemas for structured AI responses, enabling
+reliable parsing of AI-generated content with type safety.
+"""
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class AnsibleTask(BaseModel):
+    """Schema for a single Ansible task."""
+
+    name: str = Field(..., description="Human-readable task name")
+    module: str = Field(
+        ..., description="Ansible module name (e.g., 'package', 'service')"
+    )
+    parameters: dict[str, Any] = Field(
+        default_factory=dict, description="Module parameters as key-value pairs"
+    )
+    when: str | None = Field(
+        None, description="Conditional expression for task execution"
+    )
+    notify: list[str] | None = Field(
+        None, description="List of handlers to notify on change"
+    )
+    tags: list[str] | None = Field(
+        None, description="List of tags for task categorization"
+    )
+    become: bool | None = Field(None, description="Whether to use privilege escalation")
+    register: str | None = Field(None, description="Variable name to store task result")
+
+
+class AnsibleHandler(BaseModel):
+    """Schema for an Ansible handler."""
+
+    name: str = Field(..., description="Handler name")
+    module: str = Field(..., description="Ansible module name")
+    parameters: dict[str, Any] = Field(
+        default_factory=dict, description="Module parameters"
+    )
+
+
+class AnsiblePlaybook(BaseModel):
+    """Schema for a complete Ansible playbook."""
+
+    name: str = Field(..., description="Playbook name")
+    hosts: str = Field(default="all", description="Target hosts pattern")
+    become: bool | None = Field(None, description="Whether to use privilege escalation")
+    vars: dict[str, Any] | None = Field(None, description="Playbook variables")
+    tasks: list[AnsibleTask] = Field(default_factory=list, description="List of tasks")
+    handlers: list[AnsibleHandler] | None = Field(None, description="List of handlers")
+
+
+class ConversionResult(BaseModel):
+    """Schema for AI conversion results."""
+
+    playbook: AnsiblePlaybook = Field(..., description="Generated Ansible playbook")
+    notes: list[str] | None = Field(
+        None,
+        description="Conversion notes, warnings, or manual steps required",
+    )
+    confidence: float | None = Field(
+        None,
+        description="Confidence score (0.0-1.0) for the conversion accuracy",
+        ge=0.0,
+        le=1.0,
+    )
+
+
+class TemplateConversion(BaseModel):
+    """Schema for template conversion results."""
+
+    jinja2_template: str = Field(..., description="Converted Jinja2 template content")
+    variable_mappings: dict[str, str] | None = Field(
+        None,
+        description="Mapping of Chef variables to Ansible variables",
+    )
+    notes: list[str] | None = Field(None, description="Conversion notes or warnings")

souschef/core/http_client.py

@@ -0,0 +1,394 @@
+"""
+HTTP client abstraction for SousChef.
+
+Provides a unified interface for making HTTP requests with consistent
+error handling, authentication, and retry logic.
+"""
+
+from typing import TYPE_CHECKING, Any, Literal
+from urllib.parse import urlparse
+
+if TYPE_CHECKING:
+    from requests.adapters import HTTPAdapter
+    from requests.exceptions import (
+        ConnectionError as RequestsConnectionError,
+    )
+    from requests.exceptions import (
+        HTTPError as RequestsHTTPError,
+    )
+    from requests.exceptions import (
+        RequestException,
+    )
+    from requests.exceptions import (
+        Timeout as RequestsTimeout,
+    )
+    from urllib3.util.retry import Retry
+
+try:
+    import requests
+    from requests.adapters import HTTPAdapter
+    from requests.exceptions import (
+        ConnectionError as RequestsConnectionError,
+    )
+    from requests.exceptions import (
+        HTTPError as RequestsHTTPError,
+    )
+    from requests.exceptions import (
+        RequestException,
+    )
+    from requests.exceptions import (
+        Timeout as RequestsTimeout,
+    )
+    from urllib3.util.retry import Retry
+
+    REQUESTS_AVAILABLE = True
+except ImportError:  # pragma: no cover
+    # Fallback when requests is not installed
+    requests = None  # type: ignore[assignment]
+    HTTPAdapter = None  # type: ignore[assignment,misc]
+    Retry = None  # type: ignore[assignment,misc]
+    RequestsHTTPError = Exception  # type: ignore[misc,assignment]
+    RequestsTimeout = Exception  # type: ignore[misc,assignment]
+    RequestsConnectionError = Exception  # type: ignore[misc,assignment]
+    RequestException = Exception  # type: ignore[misc,assignment]
+    REQUESTS_AVAILABLE = False
+
+from souschef.core.errors import SousChefError
+
+
+class HTTPError(SousChefError):
+    """Raised when an HTTP request fails."""
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        response_text: str | None = None,
+    ):
+        """
+        Initialise HTTP error.
+
+        Args:
+            status_code: HTTP status code.
+            message: Error message.
+            response_text: Optional response body text.
+
+        """
+        self.status_code = status_code
+        self.response_text = response_text
+
+        full_message = f"HTTP {status_code}: {message}"
+        if response_text:
+            full_message += f"\nResponse: {response_text[:500]}"
+
+        suggestion = self._get_suggestion(status_code)
+        super().__init__(full_message, suggestion)
+
+    @staticmethod
+    def _get_suggestion(status_code: int) -> str:
+        """Get helpful suggestion based on status code."""
+        if status_code == 401:
+            return "Check that your API key is valid and properly configured."
+        elif status_code == 403:
+            return (
+                "Your API key doesn't have permission for this operation. "
+                "Verify the key has the required scopes."
+            )
+        elif status_code == 404:
+            return "The requested API endpoint was not found. Check the base URL."
+        elif status_code == 429:
+            return "Rate limit exceeded. Wait a moment and try again."
+        elif 500 <= status_code < 600:
+            return "The API service is experiencing issues. Try again later."
+        else:
+            return "Check the API documentation for this error code."
+
+
+class HTTPClient:
+    """
+    HTTP client with authentication and error handling.
+
+    Provides a simple interface for making authenticated HTTP requests
+    with automatic retries and consistent error handling.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        api_key: str | None = None,
+        timeout: int = 60,
+        max_retries: int = 3,
+        backoff_factor: float = 0.5,
+        user_agent: str = "SousChef/1.0",
+    ):
+        """
+        Initialise HTTP client.
+
+        Args:
+            base_url: Base URL for API requests.
+            api_key: Optional API key for authentication.
+            timeout: Request timeout in seconds.
+            max_retries: Maximum number of retry attempts.
+            backoff_factor: Exponential backoff multiplier for retries.
+            user_agent: User-Agent header value.
+
+        Raises:
+            SousChefError: If base_url does not use HTTPS.
+
+        """
+        if not REQUESTS_AVAILABLE or Retry is None or HTTPAdapter is None:
+            raise SousChefError(
+                "requests library not available",
+                "Install with: pip install requests",
+            )
+
+        assert requests is not None
+
+        self.base_url = base_url.rstrip("/")
+
+        # Validate HTTPS usage for security
+        parsed_url = urlparse(self.base_url)
+        if parsed_url.scheme != "https":
+            raise SousChefError(
+                "Insecure HTTP connection not allowed",
+                "Use HTTPS for secure communication with the API.",
+            )
+
+        self.api_key = api_key
+        self.timeout = timeout
+        self.user_agent = user_agent
+
+        # Create session with retry configuration
+        self.session = requests.Session()
+
+        # Configure retries for transient errors
+        retry_strategy = Retry(
+            total=max_retries,
+            backoff_factor=backoff_factor,
+            status_forcelist=[429, 500, 502, 503, 504],
+            allowed_methods=["GET", "POST", "PUT", "DELETE"],
+        )
+        adapter = HTTPAdapter(max_retries=retry_strategy)
+
+        https_scheme = "https://"
+        self.session.mount(https_scheme, adapter)
+
+    def _get_headers(
+        self,
+        auth_type: Literal["bearer", "api_key"] = "bearer",
+        extra_headers: dict[str, str] | None = None,
+    ) -> dict[str, str]:
+        """
+        Build request headers with authentication.
+
+        Args:
+            auth_type: Authentication type ("bearer" or "api_key").
+            extra_headers: Additional headers to include.
+
+        Returns:
+            Complete headers dictionary.
+
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "User-Agent": self.user_agent,
+        }
+
+        if self.api_key:
+            if auth_type == "bearer":
+                headers["Authorization"] = f"Bearer {self.api_key}"
+            elif auth_type == "api_key":
+                headers["X-API-Key"] = self.api_key
+
+        if extra_headers:
+            headers.update(extra_headers)
+
+        return headers
+
+    def post(
+        self,
+        endpoint: str,
+        json_data: dict[str, Any] | None = None,
+        auth_type: Literal["bearer", "api_key"] = "bearer",
+        extra_headers: dict[str, str] | None = None,
+        timeout: int | None = None,
+    ) -> dict[str, Any]:
+        """
+        Make a POST request.
+
+        Args:
+            endpoint: API endpoint (relative to base_url).
+            json_data: JSON request body.
+            auth_type: Authentication type.
+            extra_headers: Additional headers.
+            timeout: Request timeout (overrides default).
+
+        Returns:
+            JSON response data.
+
+        Raises:
+            HTTPError: If request fails.
+
+        """
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+        headers = self._get_headers(auth_type, extra_headers)
+        timeout_value = timeout if timeout is not None else self.timeout
+
+        response = None
+        try:
+            response = self.session.post(
+                url,
+                json=json_data,
+                headers=headers,
+                timeout=timeout_value,
+            )
+            response.raise_for_status()
+
+            # Parse and validate JSON response
+            json_response = response.json()
+            if not isinstance(json_response, dict):
+                response_type = type(json_response).__name__
+                raise SousChefError(
+                    f"Expected JSON object response, got {response_type}",
+                    "The API returned an unexpected response format. "
+                    "Check the API documentation and endpoint.",
+                )
+            return json_response
+        except RequestsHTTPError as e:
+            if response is not None:
+                raise HTTPError(
+                    response.status_code,
+                    str(e),
+                    response.text,
+                ) from e
+            else:
+                raise SousChefError(
+                    f"HTTP request failed: {e}",
+                    "Check the API endpoint and your network connection.",
+                ) from e
+        except RequestsTimeout as e:
+            raise SousChefError(
+                f"Request timed out after {timeout_value} seconds",
+                "The API service may be slow or unresponsive. Try increasing "
+                "the timeout value or try again later.",
+            ) from e
+        except RequestsConnectionError as e:
+            raise SousChefError(
+                f"Failed to connect to {url}",
+                "Check your network connection and verify the base URL is correct.",
+            ) from e
+        except RequestException as e:
+            raise SousChefError(
+                f"Request failed: {e}",
+                "Check the API documentation and your request parameters.",
+            ) from e
+
+    def get(
+        self,
+        endpoint: str,
+        params: dict[str, Any] | None = None,
+        auth_type: Literal["bearer", "api_key"] = "bearer",
+        extra_headers: dict[str, str] | None = None,
+        timeout: int | None = None,
+    ) -> dict[str, Any]:
+        """
+        Make a GET request.
+
+        Args:
+            endpoint: API endpoint (relative to base_url).
+            params: Query parameters.
+            auth_type: Authentication type.
+            extra_headers: Additional headers.
+            timeout: Request timeout (overrides default).
+
+        Returns:
+            JSON response data.
+
+        Raises:
+            HTTPError: If request fails.
+
+        """
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+        headers = self._get_headers(auth_type, extra_headers)
+        timeout_value = timeout if timeout is not None else self.timeout
+
+        response = None
+        try:
+            response = self.session.get(
+                url,
+                params=params,
+                headers=headers,
+                timeout=timeout_value,
+            )
+            response.raise_for_status()
+
+            # Parse and validate JSON response
+            json_response = response.json()
+            if not isinstance(json_response, dict):
+                response_type = type(json_response).__name__
+                raise SousChefError(
+                    f"Expected JSON object response, got {response_type}",
+                    "The API returned an unexpected response format. "
+                    "Check the API documentation and endpoint.",
+                )
+            return json_response
+        except RequestsHTTPError as e:
+            if response is not None:
+                raise HTTPError(
+                    response.status_code,
+                    str(e),
+                    response.text,
+                ) from e
+            else:
+                raise SousChefError(
+                    f"HTTP request failed: {e}",
+                    "Check the API endpoint and your network connection.",
+                ) from e
+        except RequestsTimeout as e:
+            raise SousChefError(
+                f"Request timed out after {timeout_value} seconds",
+                "The API service may be slow or unresponsive. Try increasing "
+                "the timeout value or try again later.",
+            ) from e
+        except RequestsConnectionError as e:
+            raise SousChefError(
+                f"Failed to connect to {url}",
+                "Check your network connection and verify the base URL is correct.",
+            ) from e
+        except RequestException as e:
+            raise SousChefError(
+                f"Request failed: {e}",
+                "Check the API documentation and your request parameters.",
+            ) from e
+
+    def close(self) -> None:
+        """Close the HTTP session."""
+        self.session.close()
+
+    def __enter__(self) -> "HTTPClient":
+        """Enter context manager."""
+        return self
+
+    def __exit__(self, exc_type: Any, exc_val: Any, exc_tb: Any) -> None:
+        """Exit context manager and close session."""
+        self.close()
+
+
+def create_client(
+    base_url: str,
+    api_key: str | None = None,
+    **kwargs: Any,
+) -> HTTPClient:
+    """
+    Create an HTTP client with default settings.
+
+    Args:
+        base_url: Base URL for API requests.
+        api_key: Optional API key for authentication.
+        **kwargs: Additional HTTPClient arguments.
+
+    Returns:
+        Configured HTTP client.
+
+    """
+    return HTTPClient(base_url=base_url, api_key=api_key, **kwargs)