moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/utils/banner.py

@@ -9,8 +9,8 @@ from rich.console import Console
 console = Console()
 
 MOAI_BANNER = """
-███╗   ███╗ ██████╗  █████╗ ██╗       █████╗ ██████╗ ██╗  ██╗
-████╗ ████║██╔═══██╗██╔══██╗██║      ██╔══██╗██╔══██╗██║ ██╔╝
+███╗   ███╗          █████╗ ██╗       █████╗ ██████╗ ██╗  ██╗
+████╗ ████║ ██████╗ ██╔══██╗██║      ██╔══██╗██╔══██╗██║ ██╔╝
 ██╔████╔██║██║   ██║███████║██║█████╗███████║██║  ██║█████╔╝
 ██║╚██╔╝██║██║   ██║██╔══██║██║╚════╝██╔══██║██║  ██║██╔═██╗
 ██║ ╚═╝ ██║╚██████╔╝██║  ██║██║      ██║  ██║██████╔╝██║  ██╗
@@ -33,10 +33,10 @@ def print_banner(version: str = "0.3.0") -> None:
 
 def print_welcome_message() -> None:
     """Print the welcome message"""
-    console.print("[cyan bold]🚀 Welcome to MoAI-ADK Project Initialization![/cyan bold]\n")
     console.print(
-        "[dim]This wizard will guide you through setting up your MoAI-ADK project.[/dim]"
+        "[cyan bold]🚀 Welcome to MoAI-ADK Project Initialization![/cyan bold]\n"
     )
     console.print(
-        "[dim]You can press Ctrl+C at any time to cancel.\n[/dim]"
+        "[dim]This wizard will guide you through setting up your MoAI-ADK project.[/dim]"
     )
+    console.print("[dim]You can press Ctrl+C at any time to cancel.\n[/dim]")

moai_adk/utils/common.py

@@ -0,0 +1,294 @@
+# @CODE:COMMON-UTILITIES-001
+
+"""
+Common Utilities
+공통 유틸리티 함수들
+"""
+
+import asyncio
+import json
+import logging
+import re
+from dataclasses import dataclass
+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 응답 데이터"""
+    status_code: int
+    url: str
+    load_time: float
+    success: bool
+    error_message: Optional[str] = None
+    timestamp: datetime = None
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.now()
+
+
+class HTTPClient:
+    """HTTP 클라이언트 유틸리티"""
+
+    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):
+        """비동기 컨텍스트 매니저 진입"""
+        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):
+        """비동기 컨텍스트 매니저 종료"""
+        if self.session:
+            await self.session.close()
+
+    async def fetch_url(self, url: str) -> HTTPResponse:
+        """단일 URL 가져오기"""
+        try:
+            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]:
+        """여러 URL 동시 가져오기"""
+        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: str = None) -> List[str]:
+    """텍스트에서 링크 추출"""
+    links = []
+
+    # Markdown 링크 패턴: [text](url)
+    markdown_pattern = r'\[([^\]]+)\]\(([^)]+)\)'
+    markdown_matches = re.findall(markdown_pattern, text)
+
+    for match in markdown_matches:
+        url = match[1]
+        # 상대 URL을 절대 URL로 변환
+        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('/')}")
+
+    # 일반 URL 패턴
+    url_pattern = r'https?://[^\s<>"\'()]+'
+    url_matches = re.findall(url_pattern, text)
+    links.extend(url_matches)
+
+    logger.info(f"텍스트에서 {len(links)}개의 링크를 발견했습니다")
+    return list(set(links))  # 중복 제거
+
+
+def is_valid_url(url: str) -> bool:
+    """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:
+    """보고서 파일 경로 생성"""
+    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:
+    """시간(초)을 읽기 쉬운 형식으로 변환"""
+    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:
+    """가중 평균 점수 계산"""
+    if not values:
+        return 0.0
+
+    if weights is None:
+        weights = [1.0] * len(values)
+
+    if len(values) != len(weights):
+        raise ValueError("값과 가중치의 길이가 일치해야 합니다")
+
+    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]:
+    """기통계량 계산"""
+    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)
+
+    # 표준편차 계산
+    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:
+    """요청 속도 제한기"""
+
+    def __init__(self, max_requests: int = 10, time_window: int = 60):
+        self.max_requests = max_requests
+        self.time_window = time_window
+        self.requests = []
+
+    def can_make_request(self) -> bool:
+        """요청 가능 여부 확인"""
+        now = datetime.now()
+
+        # 오래된 요청 제거
+        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):
+        """요청 기록 추가"""
+        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):
+        """요청이 가능할 때까지 대기"""
+        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):
+    """속도 제한 오류"""
+    pass
+
+
+def load_hook_timeout() -> int:
+    """
+    .moai/config.json에서 Hook timeout 설정 로드
+
+    Returns:
+        int: timeout 값 (밀리초), 설정이 없으면 기본값 5000 반환
+    """
+    try:
+        config_path = Path(".moai/config.json")
+        if not config_path.exists():
+            return 5000  # 기본값
+
+        with open(config_path, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+
+        # hooks 섹션에서 timeout_ms 값 가져오기
+        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:
+    """
+    .moai/config.json에서 graceful_degradation 설정 로드
+
+    Returns:
+        bool: graceful_degradation 설정값, 설정이 없으면 기본값 True 반환
+    """
+    try:
+        config_path = Path(".moai/config.json")
+        if not config_path.exists():
+            return True  # 기본값
+
+        with open(config_path, 'r', encoding='utf-8') as f:
+            config = json.load(f)
+
+        # hooks 섹션에서 graceful_degradation 값 가져오기
+        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,235 @@
+# @CODE:PORTAL-LINK-001: 온라인 문서 링크 검증 유틸리티 | @TEST:PORTAL-LINK-001: 링크 검증 테스트
+
+"""
+Link Validation Utilities
+온라인 문서 링크 검증 유틸리티
+"""
+
+import asyncio
+import logging
+from dataclasses import dataclass
+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
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LinkResult:
+    """링크 검증 결과"""
+    url: str
+    status_code: int
+    is_valid: bool
+    response_time: float
+    error_message: Optional[str] = None
+    checked_at: datetime = None
+
+    def __post_init__(self):
+        if self.checked_at is None:
+            self.checked_at = datetime.now()
+
+
+@dataclass
+class ValidationResult:
+    """전체 검증 결과"""
+    total_links: int
+    valid_links: int
+    invalid_links: int
+    results: List[LinkResult]
+    completed_at: datetime = None
+
+    def __post_init__(self):
+        if self.completed_at is None:
+            self.completed_at = datetime.now()
+
+    @property
+    def success_rate(self) -> float:
+        """성공률 계산"""
+        if self.total_links == 0:
+            return 0.0
+        return (self.valid_links / self.total_links) * 100
+
+
+class LinkValidator(HTTPClient):
+    """온라인 문서 링크 검증기"""
+
+    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]:
+        """파일에서 모든 링크 추출"""
+        if not file_path.exists():
+            logger.warning(f"파일이 존재하지 않습니다: {file_path}")
+            return []
+
+        try:
+            content = file_path.read_text(encoding='utf-8')
+            base_url = "https://adk.mo.ai.kr"
+            links = extract_links_from_text(content, base_url)
+            logger.info(f"파일에서 {len(links)}개의 링크를 발견했습니다: {file_path}")
+            return links
+        except Exception as e:
+            logger.error(f"링크 추출 중 오류 발생: {e}")
+            return []
+
+    async def validate_link(self, url: str) -> LinkResult:
+        """단일 링크 검증"""
+        try:
+            # URL 유효성 검사
+            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 요청
+            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:
+        """모든 링크 검증"""
+        results = []
+
+        # 링크 그룹으로 분할 (동시성 제어)
+        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)
+                # 진행 상황 로깅
+                logger.info(f"검증 완료: {link} -> {result.status_code} ({result.is_valid})")
+                return result
+
+        # 모든 링크를 비동기로 검증
+        tasks = [validate_with_semaphore(link) for link in links]
+        await asyncio.gather(*tasks)
+
+        # 결과 분석
+        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:
+        """검증 보고서 생성"""
+        from moai_adk.utils.common import get_summary_stats
+
+        report = []
+        report.append("# 온라인 문서 링크 검증 보고서")
+        report.append(f"**검증 시간**: {validation_result.completed_at.strftime('%Y-%m-%d %H:%M:%S')}")
+        report.append(f"**총 링크 수**: {validation_result.total_links}")
+        report.append(f"**유효한 링크**: {validation_result.valid_links}")
+        report.append(f"**유효하지 않은 링크**: {validation_result.invalid_links}")
+        report.append(f"**성공률**: {validation_result.success_rate:.1f}%")
+        report.append("")
+
+        # 통계 정보
+        if validation_result.results:
+            response_times = [r.response_time for r in validation_result.results]
+            stats = get_summary_stats(response_times)
+            report.append("## 📊 통계 정보")
+            report.append("")
+            report.append(f"- 평균 응답 시간: {stats['mean']:.2f}초")
+            report.append(f"- 최소 응답 시간: {stats['min']:.2f}초")
+            report.append(f"- 최대 응답 시간: {stats['max']:.2f}초")
+            report.append(f"- 표준편차: {stats['std']:.2f}초")
+            report.append("")
+
+        # 실패한 링크 상세 보고
+        if validation_result.invalid_links > 0:
+            report.append("## ❌ 실패한 링크")
+            report.append("")
+
+            for result in validation_result.results:
+                if not result.is_valid:
+                    report.append(f"- **{result.url}**")
+                    report.append(f"  - 상태 코드: {result.status_code}")
+                    report.append(f"  - 응답 시간: {result.response_time:.2f}초")
+                    if result.error_message:
+                        report.append(f"  - 오류: {result.error_message}")
+                    report.append("")
+
+        # 성공한 링크 요약
+        if validation_result.valid_links > 0:
+            report.append("## ✅ 성공한 링크")
+            report.append("")
+            report.append(f"총 {validation_result.valid_links}개의 링크가 정상적으로 검증되었습니다.")
+
+        return "\n".join(report)
+
+
+def validate_readme_links(readme_path: Path = None) -> ValidationResult:
+    """README 파일의 모든 링크 검증"""
+    if readme_path is None:
+        readme_path = Path("README.ko.md")
+
+    validator = LinkValidator(max_concurrent=3, timeout=8)
+
+    # README 파일에서 링크 추출
+    links = validator.extract_links_from_file(readme_path)
+
+    if not links:
+        logger.warning("검증할 링크가 없습니다")
+        return ValidationResult(
+            total_links=0,
+            valid_links=0,
+            invalid_links=0,
+            results=[]
+        )
+
+    logger.info(f"총 {len(links)}개의 링크를 검증합니다...")
+
+    # 비동기 검증 수행
+    result = asyncio.run(validator.validate_all_links(links))
+
+    # 보고서 생성 및 저장
+    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_path}")
+
+    return result
+
+
+if __name__ == "__main__":
+    # README 파일 기준 링크 검증 실행
+    result = validate_readme_links()
+
+    # 결과 출력
+    validator = LinkValidator()
+    report = validator.generate_report(result)
+    print(report)
+
+    # 파일로 저장
+    report_path = Path("link_validation_report.md")
+    report_path.write_text(report, encoding='utf-8')
+    print(f"\n보고서가 저장되었습니다: {report_path}")

moai_adk/utils/logger.py

@@ -1,4 +1,4 @@
-# @CODE:LOGGING-001 | SPEC: SPEC-LOGGING-001/spec.md | TEST: tests/unit/test_logger.py
+# @CODE:LOGGER-MAIN-001 | SPEC: SPEC-LOGGING-001/spec.md | TEST: tests/unit/test_logger.py
 """
 Logging system built on Python's logging module
 
@@ -36,7 +36,7 @@ class SensitiveDataFilter(logging.Filter):
         API Key: ***REDACTED***
     """
 
-    # @CODE:LOGGING-001:DOMAIN - Define sensitive data patterns
+    # @CODE:LOGGER-MAIN-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
@@ -107,7 +107,7 @@ 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
+    # @CODE:LOGGER-MAIN-001:DOMAIN - Determine logging level
     if level is None:
         env = os.getenv("MOAI_ENV", "").lower()
         level_map = {
@@ -117,31 +117,31 @@ def setup_logger(
         }
         level = level_map.get(env, logging.INFO)
 
-    # @CODE:LOGGING-001:INFRA - Create and configure logger
+    # @CODE:LOGGER-MAIN-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
+    # @CODE:LOGGER-MAIN-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
+    # @CODE:LOGGER-MAIN-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
+    # @CODE:LOGGER-MAIN-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
+    # @CODE:LOGGER-MAIN-001:INFRA - File handler
     log_file = log_path / "moai.log"
     file_handler = logging.FileHandler(log_file, encoding="utf-8")
     file_handler.setLevel(level)