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

moai_adk/utils/__init__.py

@@ -1,4 +1,3 @@
-# @CODE:LOGGING-001 | SPEC: SPEC-LOGGING-001/spec.md | TEST: tests/unit/test_logger.py
 """
 MoAI-ADK utility module
 """

moai_adk/utils/banner.py

@@ -1,4 +1,3 @@
-# @CODE:UTILS-001 | SPEC: SPEC-CLI-001/spec.md
 """ASCII banner module
 
 Render the MoAI-ADK ASCII art banner

moai_adk/utils/common.py

@@ -0,0 +1,308 @@
+"""
+Common Utilities
+Common utility functions
+"""
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import Dict, List, Optional
+from urllib.parse import urlparse
+
+import aiohttp
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class HTTPResponse:
+    """HTTP response data"""
+
+    status_code: int
+    url: str
+    load_time: float
+    success: bool
+    error_message: Optional[str] = None
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+
+
+class HTTPClient:
+    """HTTP client utility"""
+
+    def __init__(self, max_concurrent: int = 5, timeout: int = 10):
+        self.max_concurrent = max_concurrent
+        self.timeout = timeout
+        self.session: Optional[aiohttp.ClientSession] = None
+
+    async def __aenter__(self):
+        """Async context manager entry"""
+        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):
+        """Async context manager exit"""
+        if self.session:
+            await self.session.close()
+
+    async def fetch_url(self, url: str) -> HTTPResponse:
+        """Fetch single URL"""
+        try:
+            if self.session is None:
+                return HTTPResponse(
+                    status_code=0,
+                    url=url,
+                    load_time=0,
+                    success=False,
+                    error_message="Session not initialized",
+                )
+            start_time = asyncio.get_event_loop().time()
+            async with self.session.get(url, allow_redirects=True) as response:
+                load_time = asyncio.get_event_loop().time() - start_time
+                success = 200 <= response.status < 300
+                return HTTPResponse(
+                    status_code=response.status,
+                    url=str(response.url),
+                    load_time=load_time,
+                    success=success,
+                )
+        except asyncio.TimeoutError:
+            return HTTPResponse(
+                status_code=0,
+                url=url,
+                load_time=self.timeout,
+                success=False,
+                error_message="Request timeout",
+            )
+        except aiohttp.ClientError as e:
+            return HTTPResponse(
+                status_code=0,
+                url=url,
+                load_time=0.0,
+                success=False,
+                error_message=f"HTTP client error: {str(e)}",
+            )
+        except Exception as e:
+            return HTTPResponse(
+                status_code=0,
+                url=url,
+                load_time=0.0,
+                success=False,
+                error_message=f"Unexpected error: {str(e)}",
+            )
+
+    async def fetch_urls(self, urls: List[str]) -> List[HTTPResponse]:
+        """Fetch multiple URLs concurrently"""
+        async with self:
+            tasks = [self.fetch_url(url) for url in urls]
+            return await asyncio.gather(*tasks)
+
+
+def extract_links_from_text(text: str, base_url: Optional[str] = None) -> List[str]:
+    """Extract links from text"""
+    links = []
+
+    # Markdown link pattern: [text](url)
+    markdown_pattern = r"\[([^\]]+)\]\(([^)]+)\)"
+    markdown_matches = re.findall(markdown_pattern, text)
+
+    for match in markdown_matches:
+        url = match[1]
+        # Convert relative URLs to absolute URLs
+        if url.startswith(("http://", "https://")):
+            links.append(url)
+        elif base_url and url.startswith("/"):
+            links.append(f"{base_url}{url}")
+        elif base_url and not url.startswith(("http://", "https://", "#")):
+            links.append(f"{base_url}/{url.rstrip('/')}")
+
+    # General URL pattern
+    url_pattern = r'https?://[^\s<>"\'()]+'
+    url_matches = re.findall(url_pattern, text)
+    links.extend(url_matches)
+
+    logger.info(f"Found {len(links)} links in text")
+    return list(set(links))  # Remove duplicates
+
+
+def is_valid_url(url: str) -> bool:
+    """Validate URL"""
+    try:
+        result = urlparse(url)
+        return all([result.scheme, result.netloc])
+    except Exception:
+        return False
+
+
+def create_report_path(base_path: Path, suffix: str = "report") -> Path:
+    """Create report file path"""
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
+    filename = f"{suffix}_{timestamp}.md"
+    return base_path / filename
+
+
+def format_duration(seconds: float) -> str:
+    """Convert time (seconds) to readable format"""
+    if seconds < 1:
+        return f"{seconds*1000:.0f}ms"
+    elif seconds < 60:
+        return f"{seconds:.1f}s"
+    elif seconds < 3600:
+        minutes = int(seconds // 60)
+        remaining_seconds = seconds % 60
+        return f"{minutes}m {remaining_seconds:.0f}s"
+    else:
+        hours = int(seconds // 3600)
+        remaining_minutes = int((seconds % 3600) // 60)
+        return f"{hours}h {remaining_minutes}m"
+
+
+def calculate_score(
+    values: List[float], weights: Optional[List[float]] = None
+) -> float:
+    """Calculate weighted average score"""
+    if not values:
+        return 0.0
+
+    if weights is None:
+        weights = [1.0] * len(values)
+
+    if len(values) != len(weights):
+        raise ValueError("Values and weights must have the same length")
+
+    weighted_sum = sum(v * w for v, w in zip(values, weights))
+    total_weight = sum(weights)
+
+    return weighted_sum / total_weight if total_weight > 0 else 0.0
+
+
+def get_summary_stats(numbers: List[float]) -> Dict[str, float]:
+    """Calculate basic statistics"""
+    if not numbers:
+        return {"mean": 0.0, "min": 0.0, "max": 0.0, "std": 0.0}
+
+    mean = sum(numbers) / len(numbers)
+    min_val = min(numbers)
+    max_val = max(numbers)
+
+    # Calculate standard deviation
+    if len(numbers) > 1:
+        variance = sum((x - mean) ** 2 for x in numbers) / (len(numbers) - 1)
+        std_dev = variance**0.5
+    else:
+        std_dev = 0.0
+
+    return {"mean": mean, "min": min_val, "max": max_val, "std": std_dev}
+
+
+class RateLimiter:
+    """Request rate limiter"""
+
+    def __init__(self, max_requests: int = 10, time_window: int = 60):
+        self.max_requests = max_requests
+        self.time_window = time_window
+        self.requests: List[datetime] = []
+
+    def can_make_request(self) -> bool:
+        """Check if request can be made"""
+        now = datetime.now()
+
+        # Remove old requests
+        self.requests = [
+            req_time
+            for req_time in self.requests
+            if (now - req_time).total_seconds() < self.time_window
+        ]
+
+        return len(self.requests) < self.max_requests
+
+    def add_request(self):
+        """Add request record"""
+        if self.can_make_request():
+            self.requests.append(datetime.now())
+        else:
+            raise RateLimitError(
+                f"Rate limit exceeded: {self.max_requests} requests per {self.time_window}s"
+            )
+
+    async def wait_if_needed(self):
+        """Wait until request can be made"""
+        if not self.can_make_request():
+            oldest_request = min(self.requests)
+            wait_time = (
+                self.time_window - (datetime.now() - oldest_request).total_seconds()
+            )
+            if wait_time > 0:
+                logger.info(f"Rate limiting: waiting {wait_time:.1f}s")
+                await asyncio.sleep(wait_time)
+
+
+class RateLimitError(Exception):
+    """Rate limit error"""
+
+    pass
+
+
+def load_hook_timeout() -> int:
+    """
+    Load Hook timeout setting from .moai/config/config.json
+
+    Returns:
+        int: timeout value (milliseconds), returns default 5000 if not configured
+    """
+    try:
+        config_path = Path(".moai/config/config.json")
+        if not config_path.exists():
+            return 5000  # Default value
+
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+
+        # Get timeout_ms value from hooks section
+        hooks_config = config.get("hooks", {})
+        timeout_ms = hooks_config.get("timeout_ms", 5000)
+
+        return int(timeout_ms)
+    except (json.JSONDecodeError, FileNotFoundError, KeyError, ValueError):
+        logger.warning("Failed to load hook timeout from config, using default 5000ms")
+        return 5000
+
+
+def get_graceful_degradation() -> bool:
+    """
+    Load graceful_degradation setting from .moai/config/config.json
+
+    Returns:
+        bool: graceful_degradation setting value, returns default True if not configured
+    """
+    try:
+        config_path = Path(".moai/config/config.json")
+        if not config_path.exists():
+            return True  # Default value
+
+        with open(config_path, "r", encoding="utf-8") as f:
+            config = json.load(f)
+
+        # Get graceful_degradation value from hooks section
+        hooks_config = config.get("hooks", {})
+        return hooks_config.get("graceful_degradation", True)
+    except (json.JSONDecodeError, FileNotFoundError, KeyError):
+        logger.warning(
+            "Failed to load graceful_degradation from config, using default True"
+        )
+        return True

moai_adk/utils/link_validator.py

@@ -0,0 +1,249 @@
+"""
+Link Validation Utilities
+Online documentation link validation utilities
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from datetime import datetime
+from pathlib import Path
+from typing import List, Optional
+
+from moai_adk.utils.common import (
+    HTTPClient,
+    create_report_path,
+    extract_links_from_text,
+    is_valid_url,
+)
+from moai_adk.utils.safe_file_reader import SafeFileReader
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LinkResult:
+    """Link validation result"""
+
+    url: str
+    status_code: int
+    is_valid: bool
+    response_time: float
+    error_message: Optional[str] = None
+    checked_at: datetime = field(default_factory=datetime.now)
+
+    def __post_init__(self):
+        if self.checked_at is None:
+            self.checked_at = datetime.now()
+
+
+@dataclass
+class ValidationResult:
+    """Overall validation result"""
+
+    total_links: int
+    valid_links: int
+    invalid_links: int
+    results: List[LinkResult]
+    completed_at: datetime = field(default_factory=datetime.now)
+
+    def __post_init__(self):
+        if self.completed_at is None:
+            self.completed_at = datetime.now()
+
+    @property
+    def success_rate(self) -> float:
+        """Calculate success rate"""
+        if self.total_links == 0:
+            return 0.0
+        return (self.valid_links / self.total_links) * 100
+
+
+class LinkValidator(HTTPClient):
+    """Online documentation link validator"""
+
+    def __init__(self, max_concurrent: int = 5, timeout: int = 10):
+        super().__init__(max_concurrent, timeout)
+
+    def extract_links_from_file(self, file_path: Path) -> List[str]:
+        """Extract all links from file (using safe file reading)"""
+        if not file_path.exists():
+            logger.warning(f"File does not exist: {file_path}")
+            return []
+
+        try:
+            reader = SafeFileReader()
+            content = reader.read_text(file_path)
+            if content is None:
+                logger.error(f"Unable to read file: {file_path}")
+                return []
+
+            base_url = "https://adk.mo.ai.kr"
+            links = extract_links_from_text(content, base_url)
+            logger.info(f"Found {len(links)} links in file: {file_path}")
+            return links
+        except Exception as e:
+            logger.error(f"Error during link extraction: {e}")
+            return []
+
+    async def validate_link(self, url: str) -> LinkResult:
+        """Validate single link"""
+        try:
+            # URL validity check
+            if not is_valid_url(url):
+                return LinkResult(
+                    url=url,
+                    status_code=0,
+                    is_valid=False,
+                    response_time=0.0,
+                    error_message="Invalid URL format",
+                )
+
+            # HTTP request
+            response = await self.fetch_url(url)
+
+            return LinkResult(
+                url=url,
+                status_code=response.status_code,
+                is_valid=response.success,
+                response_time=response.load_time,
+                error_message=response.error_message,
+            )
+
+        except Exception as e:
+            return LinkResult(
+                url=url,
+                status_code=0,
+                is_valid=False,
+                response_time=0.0,
+                error_message=f"Unexpected error: {str(e)}",
+            )
+
+    async def validate_all_links(self, links: List[str]) -> ValidationResult:
+        """Validate all links"""
+        results = []
+
+        # Split into link groups (concurrency control)
+        semaphore = asyncio.Semaphore(self.max_concurrent)
+
+        async def validate_with_semaphore(link: str):
+            async with semaphore:
+                result = await self.validate_link(link)
+                results.append(result)
+                # Log progress
+                logger.info(
+                    f"Validation complete: {link} -> {result.status_code} ({result.is_valid})"
+                )
+                return result
+
+        # Validate all links asynchronously
+        tasks = [validate_with_semaphore(link) for link in links]
+        await asyncio.gather(*tasks)
+
+        # Analyze results
+        valid_links = sum(1 for r in results if r.is_valid)
+        invalid_links = len(results) - valid_links
+
+        return ValidationResult(
+            total_links=len(results),
+            valid_links=valid_links,
+            invalid_links=invalid_links,
+            results=results,
+            completed_at=datetime.now(),
+        )
+
+    def generate_report(self, validation_result: ValidationResult) -> str:
+        """Generate validation report"""
+        from moai_adk.utils.common import get_summary_stats
+
+        report = []
+        report.append("# Online Documentation Link Validation Report")
+        report.append(
+            f"**Validation Time**: {validation_result.completed_at.strftime('%Y-%m-%d %H:%M:%S')}"
+        )
+        report.append(f"**Total Links**: {validation_result.total_links}")
+        report.append(f"**Valid Links**: {validation_result.valid_links}")
+        report.append(f"**Invalid Links**: {validation_result.invalid_links}")
+        report.append(f"**Success Rate**: {validation_result.success_rate:.1f}%")
+        report.append("")
+
+        # Statistics
+        if validation_result.results:
+            response_times = [r.response_time for r in validation_result.results]
+            stats = get_summary_stats(response_times)
+            report.append("## 📊 Statistics")
+            report.append("")
+            report.append(f"- Average Response Time: {stats['mean']:.2f}s")
+            report.append(f"- Minimum Response Time: {stats['min']:.2f}s")
+            report.append(f"- Maximum Response Time: {stats['max']:.2f}s")
+            report.append(f"- Standard Deviation: {stats['std']:.2f}s")
+            report.append("")
+
+        # Failed links detailed report
+        if validation_result.invalid_links > 0:
+            report.append("## ❌ Failed Links")
+            report.append("")
+
+            for result in validation_result.results:
+                if not result.is_valid:
+                    report.append(f"- **{result.url}**")
+                    report.append(f"  - Status Code: {result.status_code}")
+                    report.append(f"  - Response Time: {result.response_time:.2f}s")
+                    if result.error_message:
+                        report.append(f"  - Error: {result.error_message}")
+                    report.append("")
+
+        # Successful links summary
+        if validation_result.valid_links > 0:
+            report.append("## ✅ Successful Links")
+            report.append("")
+            report.append(
+                f"Total of {validation_result.valid_links} links validated successfully."
+            )
+
+        return "\n".join(report)
+
+
+def validate_readme_links(readme_path: Optional[Path] = None) -> ValidationResult:
+    """Validate all links in README file"""
+    if readme_path is None:
+        readme_path = Path("README.ko.md")
+
+    validator = LinkValidator(max_concurrent=3, timeout=8)
+
+    # Extract links from README file
+    links = validator.extract_links_from_file(readme_path)
+
+    if not links:
+        logger.warning("No links to validate")
+        return ValidationResult(
+            total_links=0, valid_links=0, invalid_links=0, results=[]
+        )
+
+    logger.info(f"Validating total of {len(links)} links...")
+
+    # Perform asynchronous validation
+    result = asyncio.run(validator.validate_all_links(links))
+
+    # Generate and save report
+    report = validator.generate_report(result)
+    report_path = create_report_path(Path("."), "link_validation")
+    report_path.write_text(report, encoding="utf-8")
+    logger.info(f"Report saved to: {report_path}")
+
+    return result
+
+
+if __name__ == "__main__":
+    # Execute README file link validation
+    result = validate_readme_links()
+
+    # Print results
+    validator = LinkValidator()
+    report = validator.generate_report(result)
+    print(report)
+
+    # Save to file
+    report_path = Path("link_validation_report.md")
+    report_path.write_text(report, encoding="utf-8")
+    print(f"\nReport saved to: {report_path}")

moai_adk/utils/logger.py

@@ -1,4 +1,3 @@
-# @CODE:LOGGING-001 | SPEC: SPEC-LOGGING-001/spec.md | TEST: tests/unit/test_logger.py
 """
 Logging system built on Python's logging module
 
@@ -36,10 +35,12 @@ class SensitiveDataFilter(logging.Filter):
         API Key: ***REDACTED***
     """
 
-    # @CODE:LOGGING-001:DOMAIN - Define sensitive data patterns
     PATTERNS = [
         (r"sk-[a-zA-Z0-9]+", "***REDACTED***"),  # API Key
-        (r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b", "***REDACTED***"),  # Email
+        (
+            r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",
+            "***REDACTED***",
+        ),  # Email
         (r"(?i)(password|passwd|pwd)[\s:=]+\S+", r"\1: ***REDACTED***"),  # Password
     ]
 
@@ -107,7 +108,6 @@ def setup_logger(
         - Sensitive data (API Key, Email, Password) is automatically masked.
         - Existing handlers are removed to prevent duplicates.
     """
-    # @CODE:LOGGING-001:DOMAIN - Determine logging level
     if level is None:
         env = os.getenv("MOAI_ENV", "").lower()
         level_map = {
@@ -117,31 +117,26 @@ def setup_logger(
         }
         level = level_map.get(env, logging.INFO)
 
-    # @CODE:LOGGING-001:INFRA - Create and configure logger
     logger = logging.getLogger(name)
     logger.setLevel(level)
     logger.handlers.clear()  # Remove existing handlers to avoid duplicates
 
-    # @CODE:LOGGING-001:INFRA - Ensure log directory exists
     if log_dir is None:
         log_dir = ".moai/logs"
     log_path = Path(log_dir)
     log_path.mkdir(parents=True, exist_ok=True)
 
-    # @CODE:LOGGING-001:INFRA - Define log format
     formatter = logging.Formatter(
         fmt="[%(asctime)s] [%(levelname)s] [%(name)s] %(message)s",
         datefmt="%Y-%m-%d %H:%M:%S",
     )
 
-    # @CODE:LOGGING-001:INFRA - Console handler
     console_handler = logging.StreamHandler()
     console_handler.setLevel(level)
     console_handler.setFormatter(formatter)
     console_handler.addFilter(SensitiveDataFilter())
     logger.addHandler(console_handler)
 
-    # @CODE:LOGGING-001:INFRA - File handler
     log_file = log_path / "moai.log"
     file_handler = logging.FileHandler(log_file, encoding="utf-8")
     file_handler.setLevel(level)