moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/utils/user_experience.py

@@ -1,531 +0,0 @@
-"""
-User Experience Enhancement Utilities
-
-This module provides utilities for analyzing and improving user experience
-across multiple dimensions including performance, navigation, content quality,
-and accessibility.
-"""
-
-import asyncio
-import logging
-import time
-from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Any, Dict, List, Tuple
-from urllib.parse import urljoin
-
-import aiohttp
-
-from moai_adk.utils.common import HTTPClient
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class PerformanceMetrics:
-    """Performance metrics for user experience analysis"""
-
-    load_time: float
-    response_time: float
-    success_rate: float
-    throughput: float
-    error_rate: float
-    timestamp: datetime = field(default_factory=datetime.now)
-
-    @property
-    def is_good(self) -> bool:
-        """Check if performance meets quality thresholds"""
-        return (
-            self.load_time <= 2.0
-            and self.response_time <= 1.0
-            and self.success_rate >= 0.9
-            and self.throughput >= 10
-            and self.error_rate <= 0.1
-        )
-
-
-@dataclass
-class NavigationMetrics:
-    """Navigation structure metrics for UX analysis"""
-
-    structure_score: float
-    link_count: int
-    depth: int
-    completeness: float
-    timestamp: datetime = field(default_factory=datetime.now)
-
-    @property
-    def is_good(self) -> bool:
-        """Check if navigation structure meets quality thresholds"""
-        return (
-            self.structure_score >= 0.8
-            and self.link_count >= 5
-            and self.depth <= 3
-            and self.completeness >= 0.9
-        )
-
-
-@dataclass
-class ContentMetrics:
-    """Content quality metrics for UX analysis"""
-
-    accuracy_score: float
-    completeness_score: float
-    organization_score: float
-    readability_score: float
-    timestamp: datetime = field(default_factory=datetime.now)
-
-    @property
-    def is_good(self) -> bool:
-        """Check if content quality meets quality thresholds"""
-        return (
-            self.accuracy_score >= 0.9
-            and self.completeness_score >= 0.9
-            and self.organization_score >= 0.8
-            and self.readability_score >= 0.8
-        )
-
-
-@dataclass
-class AccessibilityMetrics:
-    """Accessibility metrics for UX analysis"""
-
-    keyboard_navigation: bool
-    screen_reader_support: bool
-    color_contrast: bool
-    responsive_design: bool
-    aria_labels: bool
-    timestamp: datetime = field(default_factory=datetime.now)
-
-    @property
-    def is_good(self) -> bool:
-        """Check if accessibility meets quality thresholds"""
-        return all(
-            [
-                self.keyboard_navigation,
-                self.screen_reader_support,
-                self.color_contrast,
-                self.responsive_design,
-                self.aria_labels,
-            ]
-        )
-
-
-class UserExperienceAnalyzer(HTTPClient):
-    """
-    User experience analyzer for comprehensive UX assessment
-
-    Analyzes multiple dimensions of user experience including performance,
-    navigation, content quality, and accessibility. Provides actionable
-    recommendations for improvement.
-    """
-
-    def __init__(self, base_url: str, max_workers: int = 5):
-        super().__init__(max_concurrent=max_workers, timeout=10)
-        self.base_url = base_url
-
-    async def __aenter__(self):
-        """Enter async context manager"""
-        connector = aiohttp.TCPConnector(limit=self.max_concurrent)
-        timeout = aiohttp.ClientTimeout(total=self.timeout)
-        self.session = aiohttp.ClientSession(
-            connector=connector,
-            timeout=timeout,
-            headers={
-                "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
-            },
-        )
-        return self
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        """Exit async context manager"""
-        if self.session:
-            await self.session.close()
-
-    async def analyze_performance(self) -> PerformanceMetrics:
-        """
-        Analyze website performance metrics
-
-        Tests multiple pages concurrently to measure load times, success rates,
-        throughput, and error rates.
-        """
-        # Test multiple pages with concurrent loading
-        pages = [
-            self.base_url,
-            urljoin(self.base_url, "/getting-started"),
-            urljoin(self.base_url, "/api"),
-            urljoin(self.base_url, "/guides"),
-            urljoin(self.base_url, "/search"),
-        ]
-
-        load_times = []
-        success_count = 0
-        total_requests = len(pages)
-
-        async def load_page(url: str) -> Tuple[float, bool]:
-            page_start = time.time()
-            try:
-                response = await self.fetch_url(url)
-                load_time = time.time() - page_start
-                success = response.success
-                return load_time, success
-            except Exception:
-                load_time = time.time() - page_start
-                return load_time, False
-
-        # Load all pages concurrently
-        tasks = [load_page(url) for url in pages]
-        results = await asyncio.gather(*tasks)
-
-        # Analyze results
-        total_load_time = 0.0
-        success_count = 0
-
-        for load_time, success in results:
-            load_times.append(load_time)
-            total_load_time += load_time
-            if success:
-                success_count += 1
-
-        avg_load_time = total_load_time / total_requests if total_requests > 0 else 0
-        success_rate = success_count / total_requests if total_requests > 0 else 0
-
-        # Mock measurements (actual implementation would use real metrics)
-        response_time = 0.5  # Mock response time
-        throughput = 15.0  # Mock throughput
-        error_rate = 1.0 - success_rate
-
-        return PerformanceMetrics(
-            load_time=avg_load_time,
-            response_time=response_time,
-            success_rate=success_rate,
-            throughput=throughput,
-            error_rate=error_rate,
-        )
-
-    async def analyze_navigation(self) -> NavigationMetrics:
-        """
-        Analyze navigation structure
-
-        Evaluates navigation hierarchy, link distribution, and completeness
-        to assess ease of navigation.
-        """
-        # Mock navigation data (actual implementation would perform real crawling)
-        navigation_data: Dict[str, Any] = {
-            "main_links": ["Getting Started", "API Documentation", "Guides", "Search"],
-            "sub_links": {
-                "Getting Started": ["Installation", "Configuration", "First Steps"],
-                "API Documentation": ["Core API", "Authentication", "Webhooks"],
-                "Guides": ["Best Practices", "Examples", "Troubleshooting"],
-                "Search": ["Advanced Search", "Filters", "Results"],
-            },
-            "depth": 2,
-            "total_links": 15,
-        }
-
-        # Calculate structure score
-        structure_score = self._calculate_structure_score(navigation_data)
-
-        return NavigationMetrics(
-            structure_score=structure_score,
-            link_count=int(navigation_data["total_links"]),
-            depth=int(navigation_data["depth"]),
-            completeness=0.95,
-        )
-
-    def _calculate_structure_score(self, navigation_data: Dict) -> float:
-        """
-        Calculate navigation structure score
-
-        Considers link balance and hierarchical structure to determine
-        overall navigation quality.
-        """
-        main_links = len(navigation_data["main_links"])
-        sub_links_count = sum(
-            len(links) for links in navigation_data["sub_links"].values()
-        )
-
-        # Calculate structure score (considering link balance and hierarchy)
-        balance_score = min(1.0, main_links / 4.0)  # Main link balance
-        hierarchy_score = max(
-            0.5, 1.0 - navigation_data["depth"] / 5.0
-        )  # Hierarchy depth
-        coverage_score = min(1.0, sub_links_count / 20.0)  # Sub-link coverage
-
-        return (balance_score + hierarchy_score + coverage_score) / 3.0
-
-    async def analyze_content(self) -> ContentMetrics:
-        """
-        Analyze content quality
-
-        Evaluates content accuracy, completeness, organization, and readability
-        to assess overall content quality.
-        """
-        # Mock content data (actual implementation would perform real content analysis)
-        content_data = {
-            "word_count": 5000,
-            "code_examples": 25,
-            "images": 15,
-            "links": 30,
-            "readability_score": 8.5,
-            "completeness_score": 0.95,
-        }
-
-        # Calculate accuracy score
-        accuracy_score = self._calculate_accuracy_score(content_data)
-        organization_score = self._calculate_organization_score(content_data)
-        readability_score = content_data["readability_score"] / 10.0
-
-        return ContentMetrics(
-            accuracy_score=accuracy_score,
-            completeness_score=content_data["completeness_score"],
-            organization_score=organization_score,
-            readability_score=readability_score,
-        )
-
-    def _calculate_accuracy_score(self, content_data: Dict) -> float:
-        """
-        Calculate content accuracy score
-
-        Evaluates the presence and quality of code examples, images, and links
-        to determine content accuracy.
-        """
-        code_examples_ratio = min(1.0, content_data["code_examples"] / 20.0)
-        images_ratio = min(1.0, content_data["images"] / 10.0)
-        links_ratio = min(1.0, content_data["links"] / 25.0)
-
-        return (code_examples_ratio + images_ratio + links_ratio) / 3.0
-
-    def _calculate_organization_score(self, content_data: Dict) -> float:
-        """
-        Calculate content organization score
-
-        Evaluates content structure and word count to determine organization quality.
-        """
-        word_count_ratio = min(1.0, content_data["word_count"] / 5000.0)
-        structure_score = min(1.0, content_data["code_examples"] / 15.0)
-
-        return (word_count_ratio + structure_score) / 2.0
-
-    async def analyze_accessibility(self) -> AccessibilityMetrics:
-        """
-        Analyze accessibility compliance
-
-        Evaluates keyboard navigation, screen reader support, color contrast,
-        responsive design, and ARIA labels to assess accessibility.
-        """
-        # Mock accessibility data (actual implementation would perform real accessibility checks)
-        accessibility_data = {
-            "keyboard_navigation": True,
-            "screen_reader_support": True,
-            "color_contrast": True,
-            "responsive_design": True,
-            "aria_labels": True,
-        }
-
-        return AccessibilityMetrics(
-            keyboard_navigation=accessibility_data["keyboard_navigation"],
-            screen_reader_support=accessibility_data["screen_reader_support"],
-            color_contrast=accessibility_data["color_contrast"],
-            responsive_design=accessibility_data["responsive_design"],
-            aria_labels=accessibility_data["aria_labels"],
-        )
-
-    async def generate_report(self) -> Dict[str, Any]:
-        """
-        Generate comprehensive user experience report
-
-        Analyzes all UX dimensions concurrently and provides an overall score
-        with actionable recommendations for improvement.
-        """
-        async with self:
-            # Analyze all metrics concurrently
-            performance_task = self.analyze_performance()
-            navigation_task = self.analyze_navigation()
-            content_task = self.analyze_content()
-            accessibility_task = self.analyze_accessibility()
-
-            # Execute all analyses in parallel
-            performance, navigation, content, accessibility = await asyncio.gather(
-                performance_task, navigation_task, content_task, accessibility_task
-            )
-
-            # Calculate overall score
-            overall_score = (
-                performance.success_rate * 0.3
-                + navigation.structure_score * 0.2
-                + content.accuracy_score * 0.3
-                + (1 if accessibility.is_good else 0) * 0.2
-            )
-
-            # Generate improvement recommendations
-            recommendations = self._generate_recommendations(
-                performance, navigation, content, accessibility
-            )
-
-            return {
-                "overall_score": overall_score,
-                "performance": performance,
-                "navigation": navigation,
-                "content": content,
-                "accessibility": accessibility,
-                "recommendations": recommendations,
-                "generated_at": datetime.now().isoformat(),
-            }
-
-    def _generate_recommendations(
-        self,
-        performance: PerformanceMetrics,
-        navigation: NavigationMetrics,
-        content: ContentMetrics,
-        accessibility: AccessibilityMetrics,
-    ) -> List[str]:
-        """
-        Generate improvement recommendations
-
-        Analyzes all metrics to provide specific, actionable recommendations
-        for improving user experience.
-        """
-        recommendations = []
-
-        # Performance improvement recommendations
-        if not performance.is_good:
-            if performance.load_time > 2.0:
-                recommendations.append(
-                    "Improve page load time: Optimize images, use CDN, consider code splitting"
-                )
-            if performance.error_rate > 0.1:
-                recommendations.append(
-                    "Improve error handling: Enhance 404 pages, improve error messages"
-                )
-
-        # Navigation improvement recommendations
-        if not navigation.is_good:
-            if navigation.structure_score < 0.8:
-                recommendations.append(
-                    "Redesign navigation structure: Simplify hierarchy, reorganize categories"
-                )
-            if navigation.completeness < 0.9:
-                recommendations.append(
-                    "Improve link completeness: Connect missing pages, add breadcrumb links"
-                )
-
-        # Content improvement recommendations
-        if not content.is_good:
-            if content.accuracy_score < 0.9:
-                recommendations.append(
-                    "Improve content accuracy: Update information, validate code examples"
-                )
-            if content.organization_score < 0.8:
-                recommendations.append(
-                    "Improve content structure: Add section divisions, table of contents, related links"
-                )
-
-        # Accessibility improvement recommendations
-        if not accessibility.is_good:
-            if not accessibility.keyboard_navigation:
-                recommendations.append(
-                    "Improve keyboard navigation: Optimize tab order, add keyboard shortcuts"
-                )
-            if not accessibility.screen_reader_support:
-                recommendations.append(
-                    "Improve screen reader support: Add ARIA labels, use semantic HTML"
-                )
-
-        return recommendations
-
-
-def generate_improvement_plan(analysis_report: Dict[str, Any]) -> Dict[str, Any]:
-    """
-    Generate improvement plan from analysis report
-
-    Creates a prioritized action plan based on UX analysis results, categorizing
-    improvements by priority and timeline.
-    """
-    overall_score = analysis_report["overall_score"]
-
-    # Set priorities
-    priorities: Dict[str, List[str]] = {"high": [], "medium": [], "low": []}
-
-    # Performance priorities
-    performance = analysis_report["performance"]
-    if not performance.is_good:
-        if performance.error_rate > 0.2:
-            priorities["high"].append("Improve error handling system")
-        elif performance.load_time > 3.0:
-            priorities["high"].append("Improve load time")
-        else:
-            priorities["medium"].append("Optimize performance")
-
-    # Content priorities
-    content = analysis_report["content"]
-    if not content.is_good:
-        if content.accuracy_score < 0.8:
-            priorities["high"].append("Validate content accuracy")
-        elif content.completeness_score < 0.8:
-            priorities["medium"].append("Improve content completeness")
-        else:
-            priorities["low"].append("Fine-tune content")
-
-    # Accessibility priorities
-    accessibility = analysis_report["accessibility"]
-    if not accessibility.is_good:
-        if not accessibility.keyboard_navigation:
-            priorities["high"].append("Improve keyboard accessibility")
-        elif not accessibility.screen_reader_support:
-            priorities["high"].append("Improve screen reader support")
-        else:
-            priorities["medium"].append("Ensure accessibility standards compliance")
-
-    # Generate execution plan
-    timeline = {
-        "immediate": priorities["high"],
-        "short_term": priorities["medium"],
-        "long_term": priorities["low"],
-    }
-
-    return {
-        "overall_score": overall_score,
-        "priorities": priorities,
-        "timeline": timeline,
-        "estimated_duration": (
-            f"{len(priorities['high']) + len(priorities['medium']) * 2 + len(priorities['low']) * 3} weeks"
-        ),
-        "success_criteria": {
-            "performance_score": 0.9,
-            "content_score": 0.9,
-            "accessibility_score": 1.0,
-            "overall_score": 0.85,
-        },
-    }
-
-
-if __name__ == "__main__":
-    # User experience analysis execution example
-    analyzer = UserExperienceAnalyzer("https://adk.mo.ai.kr")
-
-    async def main():
-        analysis_report = await analyzer.generate_report()
-
-        print("=== User Experience Analysis Report ===")
-        print(f"Overall Score: {analysis_report['overall_score']:.2f}")
-        print(f"Performance Score: {analysis_report['performance'].success_rate:.2f}")
-        print(f"Navigation Score: {analysis_report['navigation'].structure_score:.2f}")
-        print(f"Content Score: {analysis_report['content'].accuracy_score:.2f}")
-        print(
-            f"Accessibility Score: {1.0 if analysis_report['accessibility'].is_good else 0.0:.2f}"
-        )
-
-        print("\nImprovement Recommendations:")
-        for recommendation in analysis_report["recommendations"]:
-            print(f"- {recommendation}")
-
-        # Generate improvement plan
-        improvement_plan = generate_improvement_plan(analysis_report)
-        print("\nImprovement Plan:")
-        print(f"Estimated Duration: {improvement_plan['estimated_duration']}")
-        print(f"Immediate Actions: {improvement_plan['timeline']['immediate']}")
-        print(f"Short-term Actions: {improvement_plan['timeline']['short_term']}")
-        print(f"Long-term Actions: {improvement_plan['timeline']['long_term']}")
-
-    asyncio.run(main())