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

souschef/assessment.py

@@ -6,18 +6,67 @@ generating migration plans, analyzing dependencies, and validating conversions.
 """
 
 import json
+import os
 import re
 from pathlib import Path
 from typing import Any
 
-from souschef.core import METADATA_FILENAME, _normalize_path, _safe_join
+from souschef.core import (
+    METADATA_FILENAME,
+    _ensure_within_base_path,
+    _normalize_path,
+    _safe_join,
+)
 from souschef.core.errors import format_error_with_context
+from souschef.core.metrics import (
+    ComplexityLevel,
+    EffortMetrics,
+    categorize_complexity,
+    estimate_effort_for_complexity,
+)
+from souschef.core.path_utils import _validated_candidate, safe_glob
 from souschef.core.validation import (
     ValidationEngine,
     ValidationLevel,
     ValidationResult,
+    _format_validation_results_summary,
 )
 
+# Optional AI provider imports
+try:
+    import requests  # type: ignore[import-untyped]
+except ImportError:
+    requests = None
+
+try:
+    from ibm_watsonx_ai import APIClient  # type: ignore[import-not-found]
+except ImportError:
+    APIClient = None
+
+
+def _normalize_cookbook_root(cookbook_path: Path | str) -> Path:
+    """
+    Normalise cookbook paths.
+
+    Args:
+        cookbook_path: User-provided cookbook path.
+
+    Returns:
+        A resolved Path.
+
+    Raises:
+        ValueError: If the path cannot be normalised.
+
+    """
+    # Normalise the path (resolves symlinks, expands ~, etc.)
+    # Safety for accessing files within this cookbook is enforced per-operation
+    # using _ensure_within_base_path with the cookbook dir as the base
+    return _normalize_path(cookbook_path)
+
+
+# Optimised patterns to avoid catastrophic backtracking in resource parsing
+RESOURCE_BLOCK_PATTERN = re.compile(r"\w{1,100}\s+['\"]([^'\"\r\n]{0,200})['\"]\s+do")
+
 
 def assess_chef_migration_complexity(
     cookbook_paths: str,
@@ -127,8 +176,9 @@ def parse_chef_migration_assessment(
             "recommendations": recommendations,
             "roadmap": roadmap,
             "complexity": _get_overall_complexity_level(overall_metrics),
-            "estimated_hours": overall_metrics.get("estimated_effort_days", 0)
-            * 8,  # Convert days to hours
+            "estimated_hours": EffortMetrics(
+                overall_metrics.get("estimated_effort_days", 0)
+            ).estimated_hours,
         }
 
     except Exception as e:
@@ -202,7 +252,6 @@ def _parse_and_assess_cookbooks(cookbook_paths: str) -> tuple[list, str | None]:
 
     cookbook_assessments = []
     for cookbook_path in valid_paths:
-        # deepcode ignore PT: path normalized via _normalize_path
         assessment = _assess_single_cookbook(cookbook_path)
         cookbook_assessments.append(assessment)
 
@@ -305,7 +354,8 @@ def analyse_cookbook_dependencies(
         dependency_depth: Analysis depth (direct, transitive, full)
 
     Returns:
-        Dependency analysis with migration order recommendations
+        Dependency analysis with migration order recommendations.
+
 
     """
     try:
@@ -317,15 +367,21 @@ def analyse_cookbook_dependencies(
                 f"Suggestion: Use one of {', '.join(valid_depths)}"
             )
 
-        cookbook_path_obj = _normalize_path(cookbook_path)
-        if not cookbook_path_obj.exists():
+        # Validate and normalise user-provided path
+        # Containment is enforced at filesystem operation level
+        try:
+            normalized_input: Path = _normalize_path(cookbook_path)
+        except (ValueError, OSError) as e:
+            return f"Error: Invalid cookbook path '{cookbook_path}': {e}"
+
+        if not normalized_input.exists():
             return (
                 f"Error: Cookbook path not found: {cookbook_path}\n\n"
                 "Suggestion: Check that the path exists and points to a cookbook directory"
             )
 
-        # Analyze dependencies
-        dependency_analysis = _analyse_cookbook_dependencies_detailed(cookbook_path_obj)
+        # Analyze dependencies using normalized path
+        dependency_analysis = _analyse_cookbook_dependencies_detailed(normalized_input)
 
         # Determine migration order
         migration_order = _determine_migration_order(dependency_analysis)
@@ -334,7 +390,7 @@ def analyse_cookbook_dependencies(
         circular_deps = _identify_circular_dependencies(dependency_analysis)
 
         return f"""# Cookbook Dependency Analysis
-# Cookbook: {cookbook_path_obj.name}
+# Cookbook: {normalized_input.name}
 # Analysis Depth: {dependency_depth}
 
 ## Dependency Overview:
@@ -534,7 +590,9 @@ def _parse_cookbook_paths(cookbook_paths: str) -> list[Any]:
         List of valid Path objects (may be empty)
 
     """
-    paths = [_normalize_path(path.strip()) for path in cookbook_paths.split(",")]
+    paths = [
+        _normalize_cookbook_root(path.strip()) for path in cookbook_paths.split(",")
+    ]
     valid_paths = [p for p in paths if p.exists()]
     return valid_paths
 
@@ -562,7 +620,6 @@ def _analyse_cookbook_metrics(
     }
 
     for cookbook_path in valid_paths:
-        # deepcode ignore PT: path normalized via _normalize_path
         assessment = _assess_single_cookbook(cookbook_path)
         cookbook_assessments.append(assessment)
 
@@ -632,62 +689,438 @@ def _format_assessment_report(
 """
 
 
-def _count_cookbook_artifacts(cookbook_path) -> dict[str, int]:
-    """Count basic cookbook artifacts (recipes, templates, files)."""
-    recipes_dir = _safe_join(cookbook_path, "recipes")
-    recipe_count = len(list(recipes_dir.glob("*.rb"))) if recipes_dir.exists() else 0
+def _count_cookbook_artifacts(cookbook_path: Path) -> dict[str, int]:  # noqa: C901
+    """Count comprehensive cookbook artifacts including all Chef components."""
+    # Note: cookbook_path is expected to be pre-validated
+    base = cookbook_path
+
+    # Helper function to safely glob within a directory
+    def _glob_safe(directory: Path, pattern: str) -> int:
+        """Count files matching a glob pattern within a directory."""
+        if not directory.exists() or not directory.is_dir():
+            return 0
+        try:
+            return len(list(directory.glob(pattern)))
+        except (OSError, ValueError):
+            return 0
+
+    # Helper function to check existence safely
+    def _exists_safe(path: Path) -> bool:
+        """Check if a path exists."""
+        try:
+            return path.exists()
+        except (OSError, ValueError):
+            return False
+
+    # All paths are safe-joined to the validated base
+    recipes_dir: Path = _safe_join(base, "recipes")
+    recipe_count: int = _glob_safe(recipes_dir, "*.rb")
+
+    templates_dir: Path = _safe_join(base, "templates")
+    template_count: int = _glob_safe(templates_dir, "**/*.erb")
+
+    files_dir: Path = _safe_join(base, "files")
+    file_count: int = _glob_safe(files_dir, "**/*")
+
+    attributes_dir: Path = _safe_join(base, "attributes")
+    attributes_count: int = _glob_safe(attributes_dir, "*.rb")
 
-    templates_count = (
-        len(list(_safe_join(cookbook_path, "templates").glob("*")))
-        if _safe_join(cookbook_path, "templates").exists()
-        else 0
+    libraries_dir: Path = _safe_join(base, "libraries")
+    libraries_count: int = _glob_safe(libraries_dir, "*.rb")
+
+    definitions_dir: Path = _safe_join(base, "definitions")
+    definitions_count: int = _glob_safe(definitions_dir, "*.rb")
+
+    resources_dir: Path = _safe_join(base, "resources")
+    resources_count: int = _glob_safe(resources_dir, "*.rb")
+
+    providers_dir: Path = _safe_join(base, "providers")
+    providers_count: int = _glob_safe(providers_dir, "*.rb")
+
+    berksfile: Path = _safe_join(base, "Berksfile")
+    has_berksfile: bool = _exists_safe(berksfile)
+
+    chefignore: Path = _safe_join(base, "chefignore")
+    has_chefignore: bool = _exists_safe(chefignore)
+
+    thorfile: Path = _safe_join(base, "Thorfile")
+    has_thorfile: bool = _exists_safe(thorfile)
+
+    kitchen_yml: Path = _safe_join(base, ".kitchen.yml")
+    kitchen_yaml: Path = _safe_join(base, "kitchen.yml")
+    has_kitchen_yml: bool = _exists_safe(kitchen_yml) or _exists_safe(kitchen_yaml)
+
+    test_dir: Path = _safe_join(base, "test")
+    spec_dir: Path = _safe_join(base, "spec")
+    has_test_dir: bool = _exists_safe(test_dir) or _exists_safe(spec_dir)
+
+    libraries_dir = cookbook_path / "libraries"
+    libraries_count = (
+        len(list(libraries_dir.glob("*.rb"))) if libraries_dir.exists() else 0
+    )
+
+    definitions_dir = cookbook_path / "definitions"
+    definitions_count = (
+        len(list(definitions_dir.glob("*.rb"))) if definitions_dir.exists() else 0
     )
 
-    files_count = (
-        len(list(_safe_join(cookbook_path, "files").glob("*")))
-        if _safe_join(cookbook_path, "files").exists()
-        else 0
+    resources_dir = cookbook_path / "resources"
+    resources_count = (
+        len(list(resources_dir.glob("*.rb"))) if resources_dir.exists() else 0
     )
 
+    providers_dir = cookbook_path / "providers"
+    providers_count = (
+        len(list(providers_dir.glob("*.rb"))) if providers_dir.exists() else 0
+    )
+
+    # Configuration files
+    has_berksfile = (cookbook_path / "Berksfile").exists()
+    has_chefignore = (cookbook_path / "chefignore").exists()
+    has_thorfile = (cookbook_path / "Thorfile").exists()
+    has_kitchen_yml = (cookbook_path / ".kitchen.yml").exists() or (
+        cookbook_path / "kitchen.yml"
+    ).exists()
+    has_test_dir = (cookbook_path / "test").exists() or (
+        cookbook_path / "spec"
+    ).exists()
+
     return {
         "recipe_count": recipe_count,
-        "templates": templates_count,
-        "files": files_count,
+        "template_count": template_count,
+        "file_count": file_count,
+        "attributes_count": attributes_count,
+        "libraries_count": libraries_count,
+        "definitions_count": definitions_count,
+        "resources_count": resources_count,
+        "providers_count": providers_count,
+        "has_berksfile": int(has_berksfile),
+        "has_chefignore": int(has_chefignore),
+        "has_thorfile": int(has_thorfile),
+        "has_kitchen_yml": int(has_kitchen_yml),
+        "has_test_dir": int(has_test_dir),
     }
 
 
-def _analyse_recipe_complexity(cookbook_path) -> dict[str, int]:
-    """Analyse recipe files for resource counts, Ruby blocks, and custom resources."""
-    recipes_dir = _safe_join(cookbook_path, "recipes")
+def _analyse_recipe_complexity(cookbook_path: Path) -> dict[str, int]:
+    """Analyse recipe files and other cookbook components for resource counts, Ruby blocks, and custom resources."""
+    # Note: cookbook_path is expected to be pre-validated at function entry points
+    # Do not call _normalize_cookbook_root here as it's already a validated Path
+
     resource_count = 0
     custom_resources = 0
     ruby_blocks = 0
-
-    if recipes_dir.exists():
-        for recipe_file in recipes_dir.glob("*.rb"):
-            with recipe_file.open("r", encoding="utf-8", errors="ignore") as f:
-                content = f.read()
-                # Count Chef resources
-                resources = len(
-                    re.findall(r'\w{1,100}\s+[\'"]([^\'"]{0,200})[\'"]\s+do', content)
-                )
-                ruby_blocks += len(
-                    re.findall(r"ruby_block|execute|bash", content, re.IGNORECASE)
-                )
-                custom_resources += len(
-                    re.findall(
-                        r"custom_resource|provides|use_inline_resources", content
-                    )
-                )
-                resource_count += resources
+    erb_templates = 0
+    attribute_complexity = 0
+    library_complexity = 0
+    definition_count = 0
+
+    # Analyze different cookbook components
+    resource_count, ruby_blocks, custom_resources = _analyze_recipes(cookbook_path)
+    attribute_complexity = _analyze_attributes(cookbook_path)
+    erb_templates = _analyze_templates(cookbook_path)
+    library_complexity = _analyze_libraries(cookbook_path)
+    definition_count = _count_definitions(cookbook_path)
 
     return {
         "resource_count": resource_count,
         "custom_resources": custom_resources,
         "ruby_blocks": ruby_blocks,
+        "erb_templates": erb_templates,
+        "attribute_complexity": attribute_complexity,
+        "library_complexity": library_complexity,
+        "definition_count": definition_count,
     }
 
 
+def _analyze_recipes(cookbook_path: Path) -> tuple[int, int, int]:
+    """Analyze recipe files for resources, ruby blocks, and custom resources."""
+    resource_count = 0
+    ruby_blocks = 0
+    custom_resources = 0
+
+    # Note: cookbook_path is expected to be pre-validated
+    # Use it directly with _safe_join to access recipes directory
+    recipes_dir: Path = _safe_join(cookbook_path, "recipes")
+    try:
+        recipe_files: list[Path] = (
+            list(recipes_dir.glob("*.rb")) if recipes_dir.exists() else []
+        )
+    except (OSError, ValueError):
+        recipe_files = []
+
+    for recipe_file in recipe_files:
+        try:
+            # Validate each glob result
+            validated_file: Path = _validated_candidate(recipe_file, cookbook_path)
+        except ValueError:
+            continue
+        try:
+            content = validated_file.read_text(encoding="utf-8", errors="ignore")
+            resources = len(RESOURCE_BLOCK_PATTERN.findall(content))
+            ruby_blocks += len(
+                re.findall(r"ruby_block|execute|bash|script", content, re.IGNORECASE)
+            )
+            custom_resources += len(
+                re.findall(
+                    r"custom_resource|provides|use_inline_resources|lwrp_resource",
+                    content,
+                )
+            )
+            resource_count += resources
+        except Exception:
+            continue
+
+    return resource_count, ruby_blocks, custom_resources
+
+
+def _analyze_attributes(cookbook_path: Path) -> int:
+    """Analyse attribute files for complexity."""
+    attribute_complexity = 0
+
+    # Note: cookbook_path is expected to be pre-validated
+    attributes_dir: Path = _safe_join(cookbook_path, "attributes")
+    try:
+        attr_files: list[Path] = (
+            list(attributes_dir.glob("*.rb")) if attributes_dir.exists() else []
+        )
+    except (OSError, ValueError):
+        attr_files = []
+
+    for attr_file in attr_files:
+        try:
+            # Validate each glob result
+            validated_file: Path = _validated_candidate(attr_file, cookbook_path)
+        except ValueError:
+            continue
+        try:
+            content = validated_file.read_text(encoding="utf-8", errors="ignore")
+            assignments = len(
+                re.findall(
+                    r"^[ \t]{0,20}\w+[ \t]{0,10}(?:\[\w*\])?[ \t]{0,10}=",
+                    content,
+                    re.MULTILINE,
+                )
+            )
+            complex_expressions = len(
+                re.findall(r"(?:node|default|override)\[", content)
+            )
+            attribute_complexity += assignments + complex_expressions
+        except Exception:
+            continue
+
+    return attribute_complexity
+
+
+def _analyze_templates(cookbook_path: Path) -> int:
+    """Analyze template files for ERB complexity."""
+    erb_templates = 0
+
+    # Note: cookbook_path is expected to be pre-validated
+    templates_dir: Path = _safe_join(cookbook_path, "templates")
+    try:
+        template_files: list[Path] = (
+            list(templates_dir.glob("**/*.erb")) if templates_dir.exists() else []
+        )
+    except (OSError, ValueError):
+        template_files = []
+
+    for template_file in template_files:
+        try:
+            # Validate each glob result
+            validated_file: Path = _validated_candidate(template_file, cookbook_path)
+        except ValueError:
+            continue
+
+        try:
+            content = validated_file.read_text(encoding="utf-8", errors="ignore")
+            erb_expressions = len(re.findall(r"<%.*?%>", content))
+            erb_templates += erb_expressions
+        except Exception:
+            continue
+
+    return erb_templates
+
+
+def _analyze_libraries(cookbook_path: Path) -> int:
+    """Analyse library files for complexity."""
+    library_complexity = 0
+
+    # Note: cookbook_path is expected to be pre-validated
+    libraries_dir: Path = _safe_join(cookbook_path, "libraries")
+    try:
+        lib_files: list[Path] = (
+            safe_glob(libraries_dir, "*.rb", cookbook_path)
+            if libraries_dir.exists()
+            else []
+        )
+    except (OSError, ValueError):
+        lib_files = []
+
+    for lib_file in lib_files:
+        try:
+            # lib_file is already validated by safe_glob
+            content = lib_file.read_text(encoding="utf-8", errors="ignore")
+            classes = len(re.findall(r"class\s+\w+", content))
+            methods = len(re.findall(r"def\s+\w+", content))
+            library_complexity += classes * 2 + methods
+        except Exception:
+            continue
+
+    return library_complexity
+
+
+def _count_definitions(cookbook_path: Path) -> int:
+    """Count definition files."""
+    # Note: cookbook_path is expected to be pre-validated
+    definitions_dir: Path = _safe_join(cookbook_path, "definitions")
+    try:
+        def_files: list[Path] = (
+            safe_glob(definitions_dir, "*.rb", cookbook_path)
+            if definitions_dir.exists()
+            else []
+        )
+    except (OSError, ValueError):
+        def_files = []
+    return len(def_files)
+
+
+def _parse_berksfile(cookbook_path: Path) -> dict[str, Any]:
+    """Parse Berksfile for dependency information."""
+    base = _normalize_cookbook_root(cookbook_path)
+    berksfile_path = _safe_join(base, "Berksfile")
+
+    if not berksfile_path.exists():
+        return {"dependencies": [], "external_cookbooks": [], "complexity": 0}
+
+    try:
+        content = berksfile_path.read_text(encoding="utf-8", errors="ignore")
+
+        cookbook_deps = re.findall(r'cookbook\s+[\'"]([^\'"]+)[\'"]', content)
+        external_deps = re.findall(
+            r'cookbook\s+[\'"]([^\'"]+)[\'"]\s*,\s*[\'"]([^\'"]+)[\'"]', content
+        )
+
+        complex_deps = len(re.findall(r'cookbook\s+[\'"]([^\'"]+)[\'"]\s*,', content))
+        git_sources = len(re.findall(r"git:", content))
+        path_sources = len(re.findall(r"path:", content))
+
+        return {
+            "dependencies": cookbook_deps,
+            "external_cookbooks": [dep[0] for dep in external_deps],
+            "complexity": complex_deps + git_sources * 2 + path_sources * 2,
+            "has_git_sources": git_sources > 0,
+            "has_path_sources": path_sources > 0,
+        }
+    except Exception:
+        return {"dependencies": [], "external_cookbooks": [], "complexity": 0}
+
+
+def _parse_chefignore(cookbook_path) -> dict[str, Any]:
+    """Parse chefignore file for ignore patterns."""
+    base = _normalize_cookbook_root(cookbook_path)
+    chefignore_path = _ensure_within_base_path(_safe_join(base, "chefignore"), base)
+
+    if not chefignore_path.exists():
+        return {"patterns": [], "complexity": 0}
+
+    try:
+        content = chefignore_path.read_text(encoding="utf-8", errors="ignore")
+        lines = [
+            line.strip()
+            for line in content.split("\n")
+            if line.strip() and not line.startswith("#")
+        ]
+
+        wildcard_patterns = len([p for p in lines if "*" in p or "?" in p])
+        directory_patterns = len([p for p in lines if p.endswith("/") or "/" in p])
+
+        return {
+            "patterns": lines,
+            "pattern_count": len(lines),
+            "complexity": wildcard_patterns + directory_patterns,
+            "has_wildcards": wildcard_patterns > 0,
+        }
+    except Exception:
+        return {"patterns": [], "complexity": 0}
+
+
+def _parse_thorfile(cookbook_path) -> dict[str, Any]:
+    """Parse Thorfile for Thor tasks."""
+    base = _normalize_cookbook_root(cookbook_path)
+    thorfile_path = _ensure_within_base_path(_safe_join(base, "Thorfile"), base)
+
+    if not thorfile_path.exists():
+        return {"tasks": [], "complexity": 0}
+
+    try:
+        content = thorfile_path.read_text(encoding="utf-8", errors="ignore")
+
+        tasks = len(re.findall(r'desc\s+[\'"]([^\'"]+)[\'"]', content))
+        methods = len(re.findall(r"def\s+\w+", content))
+
+        return {
+            "tasks": tasks,
+            "methods": methods,
+            "complexity": tasks + methods,
+            "has_tasks": tasks > 0,
+        }
+    except Exception:
+        return {"tasks": [], "complexity": 0}
+
+
+def _parse_metadata_file(cookbook_path) -> dict[str, Any]:
+    """Parse metadata.rb for cookbook information."""
+    base = _normalize_cookbook_root(cookbook_path)
+    metadata_path = _ensure_within_base_path(_safe_join(base, "metadata.rb"), base)
+
+    if not metadata_path.exists():
+        return {
+            "name": "",
+            "version": "",
+            "dependencies": [],
+            "supports": [],
+            "complexity": 0,
+        }
+
+    try:
+        content = metadata_path.read_text(encoding="utf-8", errors="ignore")
+
+        name_match = re.search(r'name\s+[\'"]([^\'"]+)[\'"]', content)
+        version_match = re.search(r'version\s+[\'"]([^\'"]+)[\'"]', content)
+
+        # Parse dependencies
+        depends_matches = re.findall(r'depends\s+[\'"]([^\'"]+)[\'"]', content)
+
+        # Parse supported platforms
+        supports_matches = re.findall(r'supports\s+[\'"]([^\'"]+)[\'"]', content)
+
+        # Count complex metadata (recipes, attributes, etc.)
+        recipes = len(re.findall(r'recipe\s+[\'"]([^\'"]+)[\'"]', content))
+        attributes = len(re.findall(r'attribute\s+[\'"]([^\'"]+)[\'"]', content))
+
+        return {
+            "name": name_match.group(1) if name_match else "",
+            "version": version_match.group(1) if version_match else "",
+            "dependencies": depends_matches,
+            "supports": supports_matches,
+            "recipes": recipes,
+            "attributes": attributes,
+            "complexity": len(depends_matches)
+            + len(supports_matches)
+            + recipes
+            + attributes,
+        }
+    except Exception:
+        return {
+            "name": "",
+            "version": "",
+            "dependencies": [],
+            "supports": [],
+            "complexity": 0,
+        }
+
+
 def _calculate_complexity_score(metrics: dict[str, int]) -> int:
     """Calculate complexity score (0-100) based on metrics."""
     recipe_count = metrics["recipe_count"]
@@ -698,8 +1131,8 @@ def _calculate_complexity_score(metrics: dict[str, int]) -> int:
         "resource_density": min(resource_count / max(recipe_count, 1) * 5, 25),
         "custom_resources": metrics["custom_resources"] * 10,
         "ruby_blocks": metrics["ruby_blocks"] * 5,
-        "templates": min(metrics["templates"] * 2, 15),
-        "files": min(metrics["files"] * 1, 10),
+        "templates": min(metrics["template_count"] * 2, 15),
+        "files": min(metrics["file_count"] * 1, 10),
     }
 
     return int(sum(complexity_factors.values()))
@@ -736,21 +1169,22 @@ def _determine_migration_priority(complexity_score: int) -> str:
 
 def _assess_single_cookbook(cookbook_path: Path) -> dict:
     """Assess complexity of a single cookbook."""
-    # cookbook_path is already normalized to a Path object
-    cookbook = cookbook_path
+    cookbook = _normalize_cookbook_root(cookbook_path)
 
     # Collect metrics
     artifact_counts = _count_cookbook_artifacts(cookbook)
     recipe_complexity = _analyse_recipe_complexity(cookbook)
     metrics = {**artifact_counts, **recipe_complexity}
 
-    # Calculate complexity and effort
+    # Calculate complexity score using existing function
     complexity_score = _calculate_complexity_score(metrics)
-    # More realistic effort: 0.5-2 hours per recipe with AI assistance
-    # Base: 1 hour per recipe = 0.125 days (8-hour day)
-    base_effort = metrics["recipe_count"] * 0.125  # 0.125 days per recipe
-    complexity_multiplier = 1 + (complexity_score / 100)
-    estimated_effort = round(base_effort * complexity_multiplier, 1)
+
+    # Use centralized EffortMetrics for consistent calculations
+    effort_metrics = estimate_effort_for_complexity(
+        complexity_score=complexity_score,
+        resource_count=metrics["recipe_count"],
+    )
+    estimated_effort = effort_metrics.estimated_days
 
     # Build assessment
     return {
@@ -772,7 +1206,7 @@ def _format_overall_metrics(metrics: dict) -> str:
 • Total Resources: {metrics["total_resources"]}
 • Average Complexity: {metrics.get("avg_complexity", 0):.1f}/100
 • Estimated Total Effort: {metrics["estimated_effort_days"]:.1f} person-days
-• Estimated Duration: {max(1, int(metrics["estimated_effort_days"] / 2))}-{max(2, int(metrics["estimated_effort_days"]))} weeks (with 2-4 parallel engineers)"""
+• Estimated Duration: {EffortMetrics(metrics["estimated_effort_days"]).estimated_weeks_range}"""
 
 
 def _format_cookbook_assessments(assessments: list) -> str:
@@ -859,7 +1293,9 @@ def _generate_migration_recommendations_from_assessment(
 
     # Complexity-based recommendations
     avg_complexity = metrics.get("avg_complexity", 0)
-    if avg_complexity > 60:
+    complexity_level = categorize_complexity(avg_complexity)
+
+    if complexity_level == ComplexityLevel.HIGH:
         recommendations.append(
             "• Consider phased migration approach due to high complexity"
         )
@@ -867,9 +1303,12 @@ def _generate_migration_recommendations_from_assessment(
             "• Allocate additional time for custom resource conversion"
         )
         recommendations.append("• Plan for comprehensive testing and validation")
-    else:
+    elif complexity_level == ComplexityLevel.LOW:
         recommendations.append("• Standard migration timeline should be sufficient")
         recommendations.append("• Consider big-bang approach for faster delivery")
+    else:
+        recommendations.append("• Balanced approach recommended for medium complexity")
+        recommendations.append("• Plan iterative validation checkpoints")
 
     # Effort-based recommendations
     total_effort = metrics["estimated_effort_days"]
@@ -899,6 +1338,7 @@ def _create_migration_roadmap(assessments: list) -> str:
     # Sort cookbooks by complexity (low to high for easier wins first)
     sorted_cookbooks = sorted(assessments, key=lambda x: x["complexity_score"])
 
+    # Use complexity thresholds from metrics module for consistency
     phases = {
         "Phase 1 - Foundation (Weeks 1-2)": [
             "Set up Ansible/AWX environment",
@@ -917,17 +1357,19 @@ def _create_migration_roadmap(assessments: list) -> str:
         ],
     }
 
-    # Distribute cookbooks across phases
+    # Distribute cookbooks across phases using centralized complexity thresholds
     for cookbook in sorted_cookbooks:
-        if cookbook["complexity_score"] < 30:
+        complexity_level = categorize_complexity(cookbook["complexity_score"])
+
+        if complexity_level == ComplexityLevel.LOW:
             phases["Phase 2 - Low Complexity Migration (Weeks 3-5)"].append(
                 f"Migrate {cookbook['cookbook_name']} ({cookbook['estimated_effort_days']} days)"
             )
-        elif cookbook["complexity_score"] < 70:
+        elif complexity_level == ComplexityLevel.MEDIUM:
             phases["Phase 3 - Medium Complexity Migration (Weeks 6-9)"].append(
                 f"Migrate {cookbook['cookbook_name']} ({cookbook['estimated_effort_days']} days)"
             )
-        else:
+        else:  # HIGH
             phases["Phase 4 - High Complexity Migration (Weeks 10-12)"].append(
                 f"Migrate {cookbook['cookbook_name']} ({cookbook['estimated_effort_days']} days)"
             )
@@ -1025,38 +1467,92 @@ def _estimate_resource_requirements(metrics: dict, target_platform: str) -> str:
 • **Training:** 2-3 days Ansible/AWX training for team"""
 
 
-def _analyse_cookbook_dependencies_detailed(cookbook_path) -> dict:
-    """Analyze cookbook dependencies in detail."""
-    analysis = {
-        "cookbook_name": cookbook_path.name,
-        "direct_dependencies": [],
+def _analyse_cookbook_dependencies_detailed(cookbook_path: Path | str) -> dict:
+    """
+    Analyse cookbook dependencies in detail.
+
+    Args:
+        cookbook_path: Path to the cookbook (may be string or Path).
+
+    Returns:
+        Dictionary with dependency information.
+
+    Raises:
+        ValueError: If the path is invalid.
+
+    """
+    # Normalize the input path
+    base_path: Path = _normalize_path(cookbook_path)
+
+    # Validate basic accessibility
+    if not base_path.exists():
+        msg = f"Cookbook path does not exist: {cookbook_path}"
+        raise ValueError(msg)
+    if not base_path.is_dir():
+        msg = f"Cookbook path is not a directory: {cookbook_path}"
+        raise ValueError(msg)
+
+    # Collect dependencies from metadata and Berksfile
+    direct_dependencies = _collect_metadata_dependencies(base_path)
+    external_dependencies = _collect_berks_dependencies(base_path)
+    community_cookbooks = _identify_community_cookbooks_from_list(
+        direct_dependencies + external_dependencies
+    )
+
+    return {
+        "cookbook_name": base_path.name,
+        "direct_dependencies": direct_dependencies,
         "transitive_dependencies": [],
-        "external_dependencies": [],
-        "community_cookbooks": [],
+        "external_dependencies": external_dependencies,
+        "community_cookbooks": community_cookbooks,
         "circular_dependencies": [],
     }
 
-    # Read metadata.rb for dependencies
-    metadata_file = _safe_join(cookbook_path, METADATA_FILENAME)
-    if metadata_file.exists():
-        with metadata_file.open("r", encoding="utf-8", errors="ignore") as f:
-            content = f.read()
 
-        # Parse dependencies
+def _collect_metadata_dependencies(base_path: Path) -> list[str]:
+    """Collect dependency declarations from metadata.rb with containment checks."""
+    # Build metadata path safely within the cookbook
+    metadata_path: Path = _safe_join(base_path, METADATA_FILENAME)
 
-        depends_matches = re.findall(r'depends\s+[\'"]([^\'"]+)[\'"]', content)
-        analysis["direct_dependencies"] = depends_matches
+    if not metadata_path.is_file():
+        return []
+
+    try:
+        # Validate metadata_path is within base_path
+        _validated_candidate(metadata_path, base_path)
+    except ValueError:
+        # metadata.rb is outside cookbook root
+        return []
 
-    # Read Berksfile for additional dependencies
-    berksfile = _safe_join(cookbook_path, "Berksfile")
-    if berksfile.exists():
-        with berksfile.open("r", encoding="utf-8", errors="ignore") as f:
-            content = f.read()
+    with metadata_path.open(encoding="utf-8", errors="ignore") as f:
+        content = f.read()
 
-        cookbook_matches = re.findall(r'cookbook\s+[\'"]([^\'"]+)[\'"]', content)
-        analysis["external_dependencies"].extend(cookbook_matches)
+    return re.findall(r'depends\s+[\'"]([^\'"]+)[\'"]', content)
 
-    # Identify community cookbooks (common ones)
+
+def _collect_berks_dependencies(base_path: Path) -> list[str]:
+    """Collect dependency declarations from Berksfile with containment checks."""
+    # Build Berksfile path safely within the cookbook
+    berksfile_path: Path = _safe_join(base_path, "Berksfile")
+
+    if not berksfile_path.is_file():
+        return []
+
+    try:
+        # Validate berksfile_path is within base_path
+        _validated_candidate(berksfile_path, base_path)
+    except ValueError:
+        # Berksfile is outside cookbook root
+        return []
+
+    with berksfile_path.open(encoding="utf-8", errors="ignore") as f:
+        content = f.read()
+
+    return re.findall(r'cookbook\s+[\'"]([^\'"]+)[\'"]', content)
+
+
+def _identify_community_cookbooks_from_list(dependencies: list[str]) -> list[str]:
+    """Return dependencies considered community cookbooks based on patterns."""
     community_cookbook_patterns = [
         "apache2",
         "nginx",
@@ -1073,12 +1569,11 @@ def _analyse_cookbook_dependencies_detailed(cookbook_path) -> dict:
         "users",
     ]
 
-    all_deps = analysis["direct_dependencies"] + analysis["external_dependencies"]
-    for dep in all_deps:
-        if any(pattern in dep.lower() for pattern in community_cookbook_patterns):
-            analysis["community_cookbooks"].append(dep)
-
-    return analysis
+    return [
+        dep
+        for dep in dependencies
+        if any(pattern in dep.lower() for pattern in community_cookbook_patterns)
+    ]
 
 
 def _determine_migration_order(dependency_analysis: dict) -> list:
@@ -1556,26 +2051,877 @@ def _format_validation_results_text(
     return "\n".join(output_lines)
 
 
-def _format_validation_results_summary(
-    conversion_type: str, summary: dict[str, int]
+def assess_single_cookbook_with_ai(
+    cookbook_path: str,
+    ai_provider: str = "anthropic",
+    api_key: str = "",
+    model: str = "claude-3-5-sonnet-20241022",
+    temperature: float = 0.3,
+    max_tokens: int = 2000,
+    project_id: str = "",
+    base_url: str = "",
+) -> dict[str, Any]:
+    """
+    Assess a single Chef cookbook using AI analysis.
+
+    Args:
+        cookbook_path: Path to the Chef cookbook directory
+        ai_provider: AI provider (anthropic, openai, watson)
+        api_key: API key for the AI provider
+        model: AI model to use
+        temperature: AI temperature setting
+        max_tokens: Maximum tokens for AI response
+        project_id: Project ID for IBM Watsonx (required for watson provider)
+        base_url: Custom base URL for the AI provider
+
+    Returns:
+        Dictionary containing assessment data with complexity, recommendations, etc.
+
+    """
+    try:
+        cookbook_path_obj = _normalize_path(cookbook_path)
+        if not cookbook_path_obj.exists():  # Read-only check on normalized path
+            return {"error": f"Cookbook path not found: {cookbook_path}"}
+
+        # Check if AI is available
+        ai_available = _is_ai_available(ai_provider, api_key)
+        if not ai_available:
+            # Fall back to rule-based analysis
+            return parse_chef_migration_assessment(cookbook_path)
+
+        # Get AI-enhanced assessment
+        assessment = _assess_single_cookbook_with_ai(
+            cookbook_path_obj,
+            ai_provider,
+            api_key,
+            model,
+            temperature,
+            max_tokens,
+            project_id,
+            base_url,
+        )
+
+        # Convert to the format expected by the UI
+        complexity_level = "Low"
+        if assessment["complexity_score"] > 70:
+            complexity_level = "High"
+        elif assessment["complexity_score"] > 30:
+            complexity_level = "Medium"
+
+        return {
+            "complexity": complexity_level,
+            "estimated_hours": EffortMetrics(
+                assessment["estimated_effort_days"]
+            ).estimated_hours,
+            "recommendations": assessment.get(
+                "ai_insights", "AI-enhanced analysis completed"
+            ),
+        }
+
+    except Exception as e:
+        return {
+            "error": format_error_with_context(
+                e, "assessing single cookbook with AI", cookbook_path
+            )
+        }
+
+
+def assess_chef_migration_complexity_with_ai(
+    cookbook_paths: str,
+    migration_scope: str = "full",
+    target_platform: str = "ansible_awx",
+    ai_provider: str = "anthropic",
+    api_key: str = "",
+    model: str = "claude-3-5-sonnet-20241022",
+    temperature: float = 0.3,
+    max_tokens: int = 2000,
+    project_id: str = "",
+    base_url: str = "",
 ) -> str:
     """
-    Format validation results as summary.
+    Assess the complexity of migrating Chef cookbooks to Ansible using AI analysis.
+
+    This function uses AI to provide more intelligent analysis of cookbook complexity,
+    migration challenges, and recommendations. Falls back to rule-based analysis
+    if AI is not available.
 
     Args:
-        conversion_type: Type of conversion.
-        summary: Summary of validation results.
+        cookbook_paths: Comma-separated paths to Chef cookbooks or cookbook directory
+        migration_scope: Scope of migration (full, recipes_only, infrastructure_only)
+        target_platform: Target platform (ansible_awx, ansible_core, ansible_tower)
+        ai_provider: AI provider (anthropic, openai, watson)
+        api_key: API key for the AI provider
+        model: AI model to use
+        temperature: AI temperature setting
+        max_tokens: Maximum tokens for AI response
+        project_id: Project ID for IBM Watsonx (required for watson provider)
+        base_url: Custom base URL for the AI provider
+
+    Returns:
+        Comprehensive migration complexity assessment with AI-enhanced recommendations
+
+    """
+    try:
+        # Validate and parse inputs
+        error_msg = _validate_assessment_inputs(
+            cookbook_paths, migration_scope, target_platform
+        )
+        if error_msg:
+            return error_msg
+
+        # Check if AI is available
+        ai_available = _is_ai_available(ai_provider, api_key)
+        if not ai_available:
+            # Fall back to rule-based analysis
+            return assess_chef_migration_complexity(
+                cookbook_paths, migration_scope, target_platform
+            )
+
+        # Process cookbook analysis with AI
+        return _process_cookbook_assessment_with_ai(
+            cookbook_paths,
+            migration_scope,
+            target_platform,
+            ai_provider,
+            api_key,
+            model,
+            temperature,
+            max_tokens,
+            project_id,
+            base_url,
+        )
+
+    except Exception as e:
+        return format_error_with_context(
+            e, "assessing Chef migration complexity with AI", cookbook_paths
+        )
+
+
+def _is_ai_available(ai_provider: str, api_key: str) -> bool:
+    """Check if AI analysis is available."""
+    if not api_key:
+        return False
+
+    if ai_provider == "anthropic" or ai_provider == "openai":
+        return requests is not None
+    elif ai_provider == "watson":
+        return APIClient is not None
+    else:
+        return False
+
+
+def _process_cookbook_assessment_with_ai(
+    cookbook_paths: str,
+    migration_scope: str,
+    target_platform: str,
+    ai_provider: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str = "",
+    base_url: str = "",
+) -> str:
+    """Process the cookbook assessment workflow with AI analysis."""
+    # Parse cookbook paths (may be empty if none exist)
+    valid_paths = _parse_cookbook_paths(cookbook_paths)
+
+    # Analyze all cookbooks with AI enhancement
+    cookbook_assessments, overall_metrics = _analyse_cookbook_metrics_with_ai(
+        valid_paths,
+        ai_provider,
+        api_key,
+        model,
+        temperature,
+        max_tokens,
+        project_id,
+        base_url,
+    )
+
+    # Generate AI-enhanced recommendations and reports
+    recommendations = _generate_ai_migration_recommendations(
+        cookbook_assessments,
+        overall_metrics,
+        target_platform,
+        ai_provider,
+        api_key,
+        model,
+        temperature,
+        max_tokens,
+        project_id,
+        base_url,
+    )
+    roadmap = _create_ai_migration_roadmap(
+        cookbook_assessments,
+        ai_provider,
+        api_key,
+        model,
+        temperature,
+        max_tokens,
+        project_id,
+        base_url,
+    )
+
+    # Format final assessment report
+    return _format_ai_assessment_report(
+        migration_scope,
+        target_platform,
+        overall_metrics,
+        cookbook_assessments,
+        recommendations,
+        roadmap,
+    )
+
+
+def _analyse_cookbook_metrics_with_ai(
+    valid_paths: list[Any],
+    ai_provider: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str = "",
+    base_url: str = "",
+) -> tuple[list[Any], dict[str, int]]:
+    """
+    Analyse metrics for all cookbooks with AI enhancement.
+
+    Args:
+        valid_paths: List of valid cookbook paths
+        ai_provider: AI provider name
+        api_key: API key
+        model: AI model
+        temperature: AI temperature
+        max_tokens: Max tokens
+        project_id: Project ID for IBM Watsonx (required for watson provider)
+        base_url: Custom base URL for the AI provider
+
+    Returns:
+        Tuple of (cookbook_assessments, overall_metrics)
+
+    """
+    cookbook_assessments = []
+    overall_metrics = {
+        "total_cookbooks": 0,
+        "total_recipes": 0,
+        "total_resources": 0,
+        "complexity_score": 0,
+        "estimated_effort_days": 0,
+    }
+
+    for cookbook_path in valid_paths:
+        # deepcode ignore PT: path normalized via _normalize_path
+        assessment = _assess_single_cookbook_with_ai(
+            cookbook_path,
+            ai_provider,
+            api_key,
+            model,
+            temperature,
+            max_tokens,
+            project_id,
+            base_url,
+        )
+        cookbook_assessments.append(assessment)
+
+        # Aggregate metrics
+        overall_metrics["total_cookbooks"] += 1
+        overall_metrics["total_recipes"] += assessment["metrics"]["recipe_count"]
+        overall_metrics["total_resources"] += assessment["metrics"]["resource_count"]
+        overall_metrics["complexity_score"] += assessment["complexity_score"]
+        overall_metrics["estimated_effort_days"] += assessment["estimated_effort_days"]
+
+    # Calculate averages
+    if cookbook_assessments:
+        overall_metrics["avg_complexity"] = int(
+            overall_metrics["complexity_score"] / len(cookbook_assessments)
+        )
+
+    return cookbook_assessments, overall_metrics
+
+
+def _assess_single_cookbook_with_ai(
+    cookbook_path: Path,
+    ai_provider: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str = "",
+    base_url: str = "",
+) -> dict:
+    """Assess complexity of a single cookbook using AI analysis."""
+    cookbook = _normalize_cookbook_root(cookbook_path)
+
+    # Collect basic metrics (same as rule-based)
+    artifact_counts = _count_cookbook_artifacts(cookbook)
+    recipe_complexity = _analyse_recipe_complexity(cookbook)
+    metrics = {**artifact_counts, **recipe_complexity}
+
+    # Get AI analysis for this cookbook
+    ai_analysis = _get_ai_cookbook_analysis(
+        cookbook,
+        metrics,
+        ai_provider,
+        api_key,
+        model,
+        temperature,
+        max_tokens,
+        project_id,
+        base_url,
+    )
+
+    # Use AI-provided complexity score if available, otherwise fall back to rule-based
+    if ai_analysis and "complexity_score" in ai_analysis:
+        complexity_score = ai_analysis["complexity_score"]
+    else:
+        complexity_score = _calculate_complexity_score(metrics)
+
+    # Use AI-provided effort estimate if available, otherwise fall back to rule-based
+    if ai_analysis and "estimated_effort_days" in ai_analysis:
+        estimated_effort = ai_analysis["estimated_effort_days"]
+    else:
+        base_effort = metrics["recipe_count"] * 0.125  # 0.125 days per recipe
+        complexity_multiplier = 1 + (complexity_score / 100)
+        estimated_effort = round(base_effort * complexity_multiplier, 1)
+
+    # Build assessment with AI insights
+    assessment = {
+        "cookbook_name": cookbook.name,
+        "cookbook_path": str(cookbook),
+        "metrics": metrics,
+        "complexity_score": complexity_score,
+        "estimated_effort_days": estimated_effort,
+        "challenges": ai_analysis.get("challenges", [])
+        if ai_analysis
+        else _identify_migration_challenges(metrics, complexity_score),
+        "migration_priority": ai_analysis.get(
+            "migration_priority", _determine_migration_priority(complexity_score)
+        )
+        if ai_analysis
+        else _determine_migration_priority(complexity_score),
+        "ai_insights": ai_analysis.get("insights", "") if ai_analysis else "",
+        "dependencies": [],
+    }
+
+    return assessment
+
+
+def _get_ai_cookbook_analysis(
+    cookbook_path: Path,
+    metrics: dict,
+    ai_provider: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str = "",
+    base_url: str = "",
+) -> dict | None:
+    """Get AI analysis for a single cookbook."""
+    try:
+        # Read key files for AI analysis
+        recipe_content = _get_recipe_content_sample(cookbook_path)
+        metadata_content = _get_metadata_content(cookbook_path)
+
+        # Prepare prompt for AI
+        prompt = f"""Analyze this Chef cookbook for migration to Ansible. Provide a detailed assessment including:
+
+1. Complexity score (0-100, where 100 is most complex)
+2. Estimated effort in days (realistic estimate for an experienced engineer)
+3. Key migration challenges and risks
+4. Migration priority (low/medium/high)
+5. Specific insights about this cookbook's conversion difficulty
+
+Cookbook: {cookbook_path.name}
+Basic metrics: {json.dumps(metrics, indent=2)}
+
+Metadata:
+{metadata_content}
+
+Sample recipe content:
+{recipe_content}
+
+Provide your analysis in JSON format with keys: complexity_score, estimated_effort_days, challenges (array), migration_priority, insights."""
+
+        # Call AI API
+        ai_response = _call_ai_api(
+            prompt,
+            ai_provider,
+            api_key,
+            model,
+            temperature,
+            max_tokens,
+            project_id,
+            base_url,
+        )
+
+        if ai_response:
+            # Parse JSON response
+            try:
+                parsed = json.loads(ai_response.strip())
+                return dict(parsed)  # Cast to dict to satisfy type checker
+            except json.JSONDecodeError:
+                # Try to extract JSON from response
+                json_match = re.search(r"\{.*\}", ai_response, re.DOTALL)
+                if json_match:
+                    parsed = json.loads(json_match.group())
+                    return dict(parsed)  # Cast to dict to satisfy type checker
+                else:
+                    return None
+        return None
+
+    except Exception:
+        # If AI analysis fails, return None to fall back to rule-based
+        return None
+
+
+def _get_recipe_content_sample(cookbook_path: Path) -> str:
+    """Get a sample of ALL recipe content for AI analysis."""
+    # Inline guard directly adjacent to sink
+    base = os.path.realpath(str(cookbook_path))  # noqa: PTH111
+    recipes_dir_str = os.path.realpath(os.path.join(base, "recipes"))  # noqa: PTH111, PTH118
+    if os.path.commonpath([base, recipes_dir_str]) != base:
+        raise RuntimeError("Path traversal")
+    if not os.path.exists(recipes_dir_str):  # noqa: PTH110
+        return "No recipes directory found"
+
+    recipes_dir = Path(recipes_dir_str)
+    recipe_files = list(recipes_dir.glob("*.rb"))
+    if not recipe_files:
+        return "No recipe files found"
+
+    # Read ALL recipe files, with reasonable size limits
+    all_recipes_content = []
+    total_chars = 0
+    max_total_chars = 8000  # Increased limit to cover multiple recipes
+
+    for recipe_file in recipe_files:
+        try:
+            content = recipe_file.read_text(encoding="utf-8", errors="ignore")
+            recipe_header = f"\n=== {recipe_file.name} ===\n"
+
+            # Add this recipe if we have room
+            if total_chars + len(recipe_header) + len(content) < max_total_chars:
+                all_recipes_content.append(recipe_header + content)
+                total_chars += len(recipe_header) + len(content)
+            else:
+                # Add truncated version
+                remaining = max_total_chars - total_chars - len(recipe_header)
+                if remaining > 100:
+                    all_recipes_content.append(
+                        recipe_header + content[:remaining] + "..."
+                    )
+                break
+        except Exception:
+            continue
+
+    if not all_recipes_content:
+        return "Could not read recipe content"
+
+    return "\n".join(all_recipes_content)
+
+
+def _get_metadata_content(cookbook_path: Path) -> str:
+    """Get metadata content for AI analysis."""
+    # Inline guard directly adjacent to sink
+    base = os.path.realpath(str(cookbook_path))  # noqa: PTH111
+    metadata_file_str = os.path.realpath(os.path.join(base, METADATA_FILENAME))  # noqa: PTH111, PTH118
+    if os.path.commonpath([base, metadata_file_str]) != base:
+        raise RuntimeError("Path traversal")
+    if not os.path.exists(metadata_file_str):  # noqa: PTH110
+        return "No metadata.rb found"
+
+    try:
+        return Path(metadata_file_str).read_text(encoding="utf-8", errors="ignore")
+    except Exception:
+        return "Could not read metadata"
+
+
+def _call_ai_api(
+    prompt: str,
+    ai_provider: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str | None = None,
+    base_url: str | None = None,
+) -> str | None:
+    """Call the AI API for analysis."""
+    try:
+        if ai_provider == "anthropic":
+            return _call_anthropic_api(prompt, api_key, model, temperature, max_tokens)
+        elif ai_provider == "openai":
+            return _call_openai_api(prompt, api_key, model, temperature, max_tokens)
+        elif ai_provider == "watson":
+            return _call_watson_api(
+                prompt, api_key, model, temperature, max_tokens, project_id, base_url
+            )
+        else:
+            return None
+    except Exception:
+        return None
+
+
+def _call_anthropic_api(
+    prompt: str, api_key: str, model: str, temperature: float, max_tokens: int
+) -> str | None:
+    """Call Anthropic Claude API."""
+    if not requests:
+        return None
+
+    try:
+        response = requests.post(
+            "https://api.anthropic.com/v1/messages",
+            headers={
+                "x-api-key": api_key,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            },
+            json={
+                "model": model,
+                "max_tokens": max_tokens,
+                "temperature": temperature,
+                "system": "You are an expert in Chef to Ansible migration analysis. Provide accurate, detailed assessments.",
+                "messages": [{"role": "user", "content": prompt}],
+            },
+            timeout=30,
+        )
+
+        if response.status_code == 200:
+            result = response.json()
+            return str(result["content"][0]["text"])
+        return None
+    except Exception:
+        return None
+
+
+def _call_openai_api(
+    prompt: str, api_key: str, model: str, temperature: float, max_tokens: int
+) -> str | None:
+    """Call OpenAI API."""
+    if not requests:
+        return None
+
+    try:
+        response = requests.post(
+            "https://api.openai.com/v1/chat/completions",
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            json={
+                "model": model,
+                "messages": [
+                    {
+                        "role": "system",
+                        "content": "You are an expert in Chef to Ansible migration analysis. Provide accurate, detailed assessments.",
+                    },
+                    {"role": "user", "content": prompt},
+                ],
+                "temperature": temperature,
+                "max_tokens": max_tokens,
+            },
+            timeout=30,
+        )
+
+        if response.status_code == 200:
+            result = response.json()
+            return str(result["choices"][0]["message"]["content"])
+        return None
+    except Exception:
+        return None
+
+
+def _call_watson_api(
+    prompt: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str | None = None,
+    base_url: str | None = None,
+) -> str | None:
+    """Call IBM Watsonx API."""
+    if not APIClient:
+        return None
+
+    try:
+        # Initialize Watsonx API client
+        client = (
+            APIClient(api_key=api_key, url=base_url)
+            if base_url
+            else APIClient(api_key=api_key)
+        )
+
+        # Prepare request parameters
+        request_params = {
+            "prompt": prompt,
+            "max_tokens": max_tokens,
+            "temperature": temperature,
+            "model_id": model,
+            "project_id": project_id,
+        }
+
+        # Call Watsonx API for text generation
+        response = (
+            client.deployments.text_generation_stream(**request_params)
+            if hasattr(client, "deployments")
+            else None
+        )
+
+        if response:
+            # Collect streamed response
+            generated_text = ""
+            for chunk in response:
+                if hasattr(chunk, "results") and chunk.results:
+                    generated_text += str(chunk.results[0].generated_text)
+            return generated_text if generated_text else None
+
+        return None
+    except Exception:
+        return None
+
+
+def _generate_ai_migration_recommendations(
+    assessments: list,
+    metrics: dict,
+    target_platform: str,
+    ai_provider: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str | None = None,
+    base_url: str | None = None,
+) -> str:
+    """Generate AI-enhanced migration recommendations."""
+    try:
+        # Prepare assessment summary for AI
+        assessment_summary = {
+            "total_cookbooks": metrics["total_cookbooks"],
+            "avg_complexity": metrics.get("avg_complexity", 0),
+            "total_effort_days": metrics["estimated_effort_days"],
+            "target_platform": target_platform,
+            "cookbook_highlights": [
+                {
+                    "name": a["cookbook_name"],
+                    "complexity": a["complexity_score"],
+                    "effort": a["estimated_effort_days"],
+                    "insights": a.get("ai_insights", ""),
+                }
+                for a in assessments[:5]  # Top 5 cookbooks
+            ],
+        }
+
+        prompt = f"""Based on this Chef to Ansible migration assessment, provide specific, actionable recommendations:
+
+Assessment Summary: {json.dumps(assessment_summary, indent=2)}
+
+Provide recommendations covering:
+1. Migration strategy (phased vs big-bang vs parallel)
+2. Team composition and skills needed
+3. Timeline considerations
+4. Risk mitigation approaches
+5. Platform-specific advice for {target_platform}
+6. Priority ordering for cookbook migration
+
+Format as a bulleted list of specific recommendations."""
+
+        ai_response = _call_ai_api(
+            prompt,
+            ai_provider,
+            api_key,
+            model,
+            temperature,
+            max_tokens,
+            project_id,
+            base_url,
+        )
+
+        if ai_response:
+            return ai_response
+        else:
+            # Fall back to rule-based recommendations
+            return _generate_migration_recommendations_from_assessment(
+                assessments, metrics, target_platform
+            )
+
+    except Exception:
+        # Fall back to rule-based recommendations
+        return _generate_migration_recommendations_from_assessment(
+            assessments, metrics, target_platform
+        )
+
+
+def _create_ai_migration_roadmap(
+    assessments: list,
+    ai_provider: str,
+    api_key: str,
+    model: str,
+    temperature: float,
+    max_tokens: int,
+    project_id: str | None = None,
+    base_url: str | None = None,
+) -> str:
+    """Create AI-enhanced migration roadmap."""
+    try:
+        # Prepare cookbook complexity data for AI
+        cookbook_data = [
+            {
+                "name": a["cookbook_name"],
+                "complexity": a["complexity_score"],
+                "effort": a["estimated_effort_days"],
+                "priority": a["migration_priority"],
+                "insights": a.get("ai_insights", ""),
+            }
+            for a in assessments
+        ]
+
+        prompt = f"""Create a detailed migration roadmap for these Chef cookbooks. Consider complexity, dependencies, and migration priorities.
+
+Cookbook Data: {json.dumps(cookbook_data, indent=2)}
+
+Provide a phased migration plan with:
+1. Phase breakdown (Foundation, Core Migration, Advanced, Finalization)
+2. Week-by-week milestones
+3. Success criteria for each phase
+4. Risk mitigation strategies
+5. Team resource allocation recommendations
+
+Format as structured markdown with clear phases and timelines."""
+
+        ai_response = _call_ai_api(
+            prompt,
+            ai_provider,
+            api_key,
+            model,
+            temperature,
+            max_tokens,
+            project_id,
+            base_url,
+        )
+
+        if ai_response:
+            return ai_response
+        else:
+            # Fall back to rule-based roadmap
+            return _create_migration_roadmap(assessments)
+
+    except Exception:
+        # Fall back to rule-based roadmap
+        return _create_migration_roadmap(assessments)
+
+
+def _format_ai_assessment_report(
+    migration_scope: str,
+    target_platform: str,
+    overall_metrics: dict[str, int],
+    cookbook_assessments: list[dict],
+    recommendations: str,
+    roadmap: str,
+) -> str:
+    """
+    Format the AI-enhanced assessment report.
+
+    Args:
+        migration_scope: Scope of migration
+        target_platform: Target platform
+        overall_metrics: Overall metrics dictionary
+        cookbook_assessments: List of cookbook assessments
+        recommendations: AI-generated recommendations
+        roadmap: AI-generated roadmap
 
     Returns:
-        Formatted summary output.
+        Formatted AI-enhanced report string
 
     """
-    return f"""# Validation Summary
+    ai_indicator = "\n🤖 **AI-Enhanced Analysis**: This report includes AI-powered insights for more accurate complexity assessment and migration planning.\n"
+
+    return f"""# Chef to Ansible Migration Assessment (AI-Enhanced)
+# Scope: {migration_scope}
+# Target Platform: {target_platform}
+{ai_indicator}
+
+## Overall Migration Metrics:
+{_format_overall_metrics(overall_metrics)}
+
+## Cookbook Assessments:
+{_format_ai_cookbook_assessments(cookbook_assessments)}
 
-✓ Conversion Type: {conversion_type}
-• Errors: {summary["errors"]}
-• Warnings: {summary["warnings"]}
-• Info: {summary["info"]}
+## Migration Complexity Analysis:
+{_format_ai_complexity_analysis(cookbook_assessments)}
+
+## AI-Generated Migration Recommendations:
+{recommendations}
 
-{"✅ No critical issues found!" if summary["errors"] == 0 else "❌ Critical issues found - review errors"}
+## AI-Generated Migration Roadmap:
+{roadmap}
+
+## Risk Assessment:
+{_assess_migration_risks(cookbook_assessments, target_platform)}
+
+## Resource Requirements:
+{_estimate_resource_requirements(overall_metrics, target_platform)}
 """
+
+
+def _format_ai_cookbook_assessments(assessments: list) -> str:
+    """Format individual cookbook assessments with AI insights."""
+    if not assessments:
+        return "No cookbooks assessed."
+
+    def _get_priority_icon(priority: str) -> str:
+        """Get priority icon based on migration priority level."""
+        if priority == "high":
+            return "🔴"
+        elif priority == "medium":
+            return "🟡"
+        else:
+            return "🟢"
+
+    formatted = []
+    for assessment in assessments:
+        priority_icon = _get_priority_icon(assessment["migration_priority"])
+        ai_insights = assessment.get("ai_insights", "")
+        insights_section = (
+            f"\n   🤖 **AI Insights**: {ai_insights}" if ai_insights else ""
+        )
+
+        formatted.append(f"""### {assessment["cookbook_name"]} {priority_icon}
+• Complexity Score: {assessment["complexity_score"]:.1f}/100
+• Estimated Effort: {assessment["estimated_effort_days"]} days
+• Recipes: {assessment["metrics"]["recipe_count"]}
+• Resources: {assessment["metrics"]["resource_count"]}
+• Custom Resources: {assessment["metrics"]["custom_resources"]}
+• Challenges: {len(assessment["challenges"])}{insights_section}""")
+
+    return "\n\n".join(formatted)
+
+
+def _format_ai_complexity_analysis(assessments: list) -> str:
+    """Format AI-enhanced complexity analysis."""
+    if not assessments:
+        return "No complexity analysis available."
+
+    high_complexity = [a for a in assessments if a["complexity_score"] > 70]
+    medium_complexity = [a for a in assessments if 30 <= a["complexity_score"] <= 70]
+    low_complexity = [a for a in assessments if a["complexity_score"] < 30]
+
+    # Check for AI insights
+    ai_insights_count = sum(1 for a in assessments if a.get("ai_insights"))
+
+    analysis = f"""• High Complexity (>70): {len(high_complexity)} cookbooks
+• Medium Complexity (30-70): {len(medium_complexity)} cookbooks
+• Low Complexity (<30): {len(low_complexity)} cookbooks
+• AI-Enhanced Assessments: {ai_insights_count}/{len(assessments)} cookbooks
+
+**Top Migration Challenges:**
+{_identify_top_challenges(assessments)}
+
+**AI Analysis Summary:**
+• {ai_insights_count} cookbooks received AI-powered complexity analysis
+• Enhanced accuracy for effort estimation and risk identification
+• Context-aware migration recommendations"""
+
+    return analysis