sa-assistant 0.1.1__py3-none-any.whl

agents/__init__.py

@@ -0,0 +1,32 @@
+# SA 에이전트 모듈
+# Orchestrator + Guru Sub-agents + Specialist Sub-agents 아키텍처
+
+from .orchestrator import (
+    create_orchestrator,
+    consult_guru,
+    list_gurus,
+    get_available_gurus,
+)
+
+from .specialists import (
+    consult_specialist,
+    list_specialists,
+    get_available_specialists,
+    parallel_research,
+    run_specialists_parallel,
+)
+
+__all__ = [
+    # Orchestrator
+    "create_orchestrator",
+    # Guru
+    "consult_guru",
+    "list_gurus",
+    "get_available_gurus",
+    # Specialist
+    "consult_specialist",
+    "list_specialists",
+    "get_available_specialists",
+    "parallel_research",
+    "run_specialists_parallel",
+]

agents/orchestrator.py

@@ -0,0 +1,283 @@
+# SA Orchestrator - AWS Solutions Architect Professional Agent
+# Guru Sub-agents를 활용한 전문가 자문 시스템
+# ThreadPoolExecutor를 사용하여 Sub-agent를 별도 스레드에서 실행 (OpenTelemetry 컨텍스트 격리)
+
+from concurrent.futures import ThreadPoolExecutor
+from typing import List, Any
+from strands import Agent, tool
+
+# 로컬 모듈 임포트
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from model.load import load_opus, load_sonnet
+from prompts.system_prompts import (
+    ORCHESTRATOR_PROMPT,
+    GURU_PROMPTS,
+    get_orchestrator_prompt,
+)
+
+
+# =============================================================================
+# Guru Sub-agent 도구 (ThreadPoolExecutor로 별도 스레드에서 실행)
+# =============================================================================
+
+def get_available_gurus() -> List[str]:
+    """사용 가능한 Guru 목록을 반환합니다."""
+    return list(GURU_PROMPTS.keys())
+
+
+def _run_guru_in_thread(guru_name: str, question: str) -> str:
+    """
+    별도 스레드에서 Guru Agent 실행 (OpenTelemetry 컨텍스트 격리)
+    
+    ThreadPoolExecutor에서 호출되어 독립적인 스레드에서 실행됩니다.
+    OpenTelemetry 컨텍스트를 명시적으로 분리하여
+    "Failed to detach context" 오류를 방지합니다.
+    
+    Args:
+        guru_name: Guru 이름 (소문자)
+        question: 자문을 구할 질문
+    
+    Returns:
+        str: Guru의 응답 텍스트
+    """
+    # OpenTelemetry 컨텍스트 명시적 분리
+    try:
+        from opentelemetry import context as otel_context
+        # 새로운 빈 컨텍스트에서 실행
+        token = otel_context.attach(otel_context.Context())
+    except ImportError:
+        token = None
+    
+    try:
+        guru_agent = Agent(
+            model=load_sonnet(enable_thinking=False),
+            system_prompt=GURU_PROMPTS[guru_name],
+        )
+        result = guru_agent(question)
+        return str(result)
+    finally:
+        # 컨텍스트 복원
+        if token is not None:
+            try:
+                otel_context.detach(token)
+            except Exception:
+                pass  # detach 실패 무시
+
+
+@tool
+def consult_guru(guru_name: str, question: str) -> str:
+    """
+    전문가 Guru에게 자문을 구합니다.
+    
+    복잡한 아키텍처 결정, 비즈니스 전략, 학습 방법 등에 대해
+    저명한 전문가들의 사고방식을 기반으로 조언을 받습니다.
+    
+    Args:
+        guru_name: Guru 이름
+            - "bezos": Jeff Bezos - 고객 중심 사고, 장기적 비전, Day 1 문화
+            - "vogels": Werner Vogels - 분산 시스템, 확장성, 운영 우수성
+            - "naval": Naval Ravikant - 레버리지, 비대칭적 결과, 시스템적 사고
+            - "feynman": Richard Feynman - 복잡한 개념 단순화, 학습 최적화
+        question: 자문을 구할 질문
+    
+    Returns:
+        str: Guru의 조언
+    
+    Example:
+        consult_guru("bezos", "이 아키텍처가 고객에게 어떤 가치를 제공하나요?")
+        consult_guru("vogels", "이 시스템의 확장성을 어떻게 개선할 수 있을까요?")
+    """
+    guru_name_lower = guru_name.lower()
+    
+    if guru_name_lower not in GURU_PROMPTS:
+        available = ", ".join(get_available_gurus())
+        return f"알 수 없는 Guru입니다: {guru_name}. 사용 가능한 Guru: {available}"
+    
+    try:
+        # ThreadPoolExecutor로 별도 스레드에서 Guru Agent 실행
+        # OpenTelemetry 컨텍스트가 스레드별로 격리되어 충돌 방지
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(_run_guru_in_thread, guru_name_lower, question)
+            response_text = future.result()
+        
+        return f"[{guru_name.upper()} GURU 조언]\n\n{response_text}"
+    except Exception as e:
+        return f"Guru 자문 중 오류 발생: {str(e)}"
+
+
+@tool
+def list_gurus() -> str:
+    """
+    사용 가능한 Guru 목록과 전문 분야를 반환합니다.
+    
+    Returns:
+        str: Guru 목록 및 설명
+    """
+    guru_descriptions = {
+        "bezos": "Jeff Bezos - 고객 중심 사고, 장기적 비전, Day 1 문화, 역방향 사고",
+        "vogels": "Werner Vogels - 분산 시스템, 확장성, 운영 우수성, 장애 대응",
+        "naval": "Naval Ravikant - 레버리지, 비대칭적 결과, 시스템적 사고, 복리 효과",
+        "feynman": "Richard Feynman - 복잡한 개념 단순화, 학습 최적화, First Principles"
+    }
+    
+    result = "## 사용 가능한 Guru 전문가\n\n"
+    for name, desc in guru_descriptions.items():
+        result += f"- **{name}**: {desc}\n"
+    
+    result += "\n`consult_guru(guru_name, question)` 도구로 자문을 구할 수 있습니다."
+    return result
+
+
+# =============================================================================
+# Orchestrator 생성
+# =============================================================================
+
+def create_orchestrator(
+    tools: List[Any] = None,
+    system_prompt: str = None,
+    enable_thinking: bool = True
+) -> Agent:
+    """
+    SA Orchestrator 에이전트를 생성합니다.
+    
+    Args:
+        tools: 추가할 도구 목록 (MCP 도구 등)
+        system_prompt: 커스텀 시스템 프롬프트 (None이면 기본 프롬프트 사용)
+        enable_thinking: Extended Thinking 활성화 여부
+    
+    Returns:
+        Agent: SA Orchestrator 에이전트
+    """
+    # 시스템 프롬프트 구성
+    if system_prompt is None:
+        system_prompt = get_orchestrator_prompt()
+    
+    # 기본 도구 목록
+    default_tools = [
+        consult_guru,
+        list_gurus,
+    ]
+    
+    # 추가 도구 병합
+    all_tools = default_tools + (tools or [])
+    
+    # Conversation Manager 설정
+    conversation_manager = SlidingWindowConversationManager(
+        window_size=20  # 최근 20개 메시지 유지
+    )
+    
+    # Orchestrator 에이전트 생성
+    orchestrator = Agent(
+        model=load_opus(enable_thinking=enable_thinking),
+        system_prompt=system_prompt,
+        tools=all_tools,
+        conversation_manager=conversation_manager
+    )
+    
+    return orchestrator
+
+
+# =============================================================================
+# CLI 실행 지원
+# =============================================================================
+
+# ANSI 색상 코드
+class Colors:
+    """터미널 색상 코드"""
+    CYAN = '\033[96m'
+    GREEN = '\033[92m'
+    YELLOW = '\033[93m'
+    RED = '\033[91m'
+    BLUE = '\033[94m'
+    MAGENTA = '\033[95m'
+    WHITE = '\033[97m'
+    RESET = '\033[0m'
+    BOLD = '\033[1m'
+    DIM = '\033[2m'
+    ORANGE = '\033[38;5;208m'  # AWS Orange
+
+
+def print_banner():
+    """SA Assistant 배너를 출력합니다."""
+    banner = f"""
+{Colors.ORANGE}╔══════════════════════════════════════════════════════════════╗
+║                                                              ║
+║   {Colors.WHITE}AWS SA Assistant{Colors.ORANGE}                                          ║
+║   {Colors.DIM}Solutions Architect Professional Agent{Colors.ORANGE}                    ║
+║                                                              ║
+║   {Colors.CYAN}Powered by Claude Opus 4.5 with Extended Thinking{Colors.ORANGE}         ║
+║                                                              ║
+╚══════════════════════════════════════════════════════════════╝{Colors.RESET}
+"""
+    print(banner)
+
+
+def tool_callback_handler(**kwargs):
+    """도구 호출 콜백 핸들러"""
+    if "current_tool_use" in kwargs:
+        tool_use = kwargs["current_tool_use"]
+        if isinstance(tool_use, dict):
+            tool_name = tool_use.get("name", "")
+            if tool_name:
+                if tool_name == "consult_guru":
+                    guru = tool_use.get("input", {}).get("guru_name", "")
+                    print(f"\n{Colors.MAGENTA}🧙 Consulting {guru.upper()} Guru...{Colors.RESET}", flush=True)
+                elif tool_name == "list_gurus":
+                    print(f"\n{Colors.BLUE}📋 Listing available Gurus...{Colors.RESET}", flush=True)
+                else:
+                    print(f"\n{Colors.CYAN}🔧 [{tool_name}]{Colors.RESET}", flush=True)
+    
+    if "data" in kwargs:
+        print(kwargs["data"], end="", flush=True)
+
+
+def run_cli(tools: List[Any] = None):
+    """CLI 모드로 실행합니다."""
+    print_banner()
+    
+    print(f"{Colors.WHITE}안녕하세요! AWS Solutions Architect Assistant입니다.{Colors.RESET}")
+    print(f"{Colors.DIM}아키텍처 설계, 비용 분석, 보안 검토 등을 도와드립니다.{Colors.RESET}")
+    print(f"\n{Colors.YELLOW}💡 Guru 전문가 자문: 'list_gurus'로 사용 가능한 전문가를 확인하세요.{Colors.RESET}")
+    print(f"{Colors.DIM}종료하려면 'exit' 또는 'quit'을 입력하세요.{Colors.RESET}\n")
+    
+    # Orchestrator 생성 (Progressive Disclosure: 스킬은 main.py에서 처리)
+    orchestrator = create_orchestrator(
+        tools=tools,
+        enable_thinking=True
+    )
+    
+    # 콜백 핸들러 설정
+    orchestrator.callback_handler = tool_callback_handler
+    
+    while True:
+        try:
+            user_input = input(f"\n{Colors.GREEN}You: {Colors.RESET}").strip()
+            
+            if not user_input:
+                continue
+            
+            if user_input.lower() in ["exit", "quit", "종료"]:
+                print(f"\n{Colors.ORANGE}감사합니다. 좋은 하루 되세요! 👋{Colors.RESET}")
+                break
+            
+            print(f"\n{Colors.ORANGE}{Colors.BOLD}SA Assistant:{Colors.RESET} ", end="", flush=True)
+            
+            try:
+                response = orchestrator(user_input)
+                print()  # 줄바꿈
+            except Exception as e:
+                print(f"\n{Colors.RED}오류 발생: {e}{Colors.RESET}")
+                continue
+                
+        except KeyboardInterrupt:
+            print(f"\n\n{Colors.YELLOW}중단되었습니다.{Colors.RESET}")
+            break
+        except Exception as e:
+            print(f"\n{Colors.RED}오류: {e}{Colors.RESET}")
+
+
+if __name__ == "__main__":
+    run_cli()

agents/specialists.py

@@ -0,0 +1,230 @@
+"""Specialist Sub-agents - 전문 영역별 서브 에이전트
+
+Explorer, Researcher, Reviewer 등 전문 분야별 서브에이전트를 제공합니다.
+ThreadPoolExecutor를 사용하여 OpenTelemetry 컨텍스트 격리를 보장합니다.
+"""
+
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from typing import List, Dict, Any, Optional
+from strands import Agent, tool
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).parent.parent))
+
+from model.load import load_sonnet, load_haiku
+from prompts.system_prompts import SPECIALIST_PROMPTS, get_specialist_prompt
+
+
+def get_available_specialists() -> List[str]:
+    return list(SPECIALIST_PROMPTS.keys())
+
+
+def _isolate_otel_context():
+    """OpenTelemetry 컨텍스트를 격리합니다."""
+    try:
+        from opentelemetry import context as otel_context
+
+        return otel_context.attach(otel_context.Context())
+    except ImportError:
+        return None
+
+
+def _restore_otel_context(token):
+    """OpenTelemetry 컨텍스트를 복원합니다."""
+    if token is not None:
+        try:
+            from opentelemetry import context as otel_context
+
+            otel_context.detach(token)
+        except Exception:
+            pass
+
+
+def _run_specialist_in_thread(
+    specialist_name: str, task: str, context: str = ""
+) -> str:
+    """
+    별도 스레드에서 Specialist Agent 실행
+    """
+    token = _isolate_otel_context()
+
+    try:
+        prompt = get_specialist_prompt(specialist_name)
+        if not prompt:
+            return f"알 수 없는 Specialist: {specialist_name}"
+
+        # Specialist는 Haiku 사용 (빠른 응답)
+        specialist_agent = Agent(
+            model=load_haiku(enable_thinking=False),
+            system_prompt=prompt,
+        )
+
+        full_task = task
+        if context:
+            full_task = f"## Context\n{context}\n\n## Task\n{task}"
+
+        result = specialist_agent(full_task)
+        return str(result)
+    finally:
+        _restore_otel_context(token)
+
+
+@tool
+def consult_specialist(specialist_name: str, task: str, context: str = "") -> str:
+    """
+    전문 Specialist 에이전트에게 작업을 위임합니다.
+
+    Specialist는 특정 도메인에 특화된 분석/조사 작업을 수행합니다.
+
+    Args:
+        specialist_name: Specialist 이름
+            - "explorer": 기존 아키텍처 분석, 다이어그램 해석
+            - "researcher": AWS 서비스/가격/Best Practice 조사
+            - "reviewer": Well-Architected Framework 기반 검토
+        task: 수행할 작업 설명
+        context: 추가 컨텍스트 (선택)
+
+    Returns:
+        str: Specialist의 분석 결과
+
+    Example:
+        consult_specialist("explorer", "이 아키텍처 다이어그램을 분석해주세요")
+        consult_specialist("researcher", "DynamoDB vs Aurora 비교")
+        consult_specialist("reviewer", "이 설계의 보안 취약점을 검토해주세요")
+    """
+    specialist_name_lower = specialist_name.lower()
+
+    if specialist_name_lower not in SPECIALIST_PROMPTS:
+        available = ", ".join(get_available_specialists())
+        return f"알 수 없는 Specialist: {specialist_name}. 사용 가능: {available}"
+
+    try:
+        with ThreadPoolExecutor(max_workers=1) as executor:
+            future = executor.submit(
+                _run_specialist_in_thread, specialist_name_lower, task, context
+            )
+            response_text = future.result(timeout=120)
+
+        return f"[{specialist_name.upper()} SPECIALIST 결과]\n\n{response_text}"
+    except Exception as e:
+        return f"Specialist 실행 중 오류 발생: {str(e)}"
+
+
+@tool
+def list_specialists() -> str:
+    """
+    사용 가능한 Specialist 목록과 전문 분야를 반환합니다.
+
+    Returns:
+        str: Specialist 목록 및 설명
+    """
+    specialist_descriptions = {
+        "explorer": "🔍 Architecture Explorer - 기존 아키텍처 분석, 다이어그램 해석, 코드 탐색",
+        "researcher": "📚 AWS Researcher - 서비스 정보, 가격, Best Practice 조사",
+        "reviewer": "✅ Architecture Reviewer - Well-Architected 검토, 보안 분석, 개선 권장",
+    }
+
+    result = "## 사용 가능한 Specialist 에이전트\n\n"
+    for name, desc in specialist_descriptions.items():
+        result += f"- **{name}**: {desc}\n"
+
+    result += "\n`consult_specialist(specialist_name, task)` 도구로 작업을 위임할 수 있습니다."
+    return result
+
+
+def run_specialists_parallel(
+    tasks: List[Dict[str, str]], max_workers: int = 3
+) -> List[Dict[str, Any]]:
+    """
+    여러 Specialist를 병렬로 실행합니다.
+
+    Args:
+        tasks: 작업 목록 [{"specialist": "name", "task": "...", "context": "..."}]
+        max_workers: 최대 동시 실행 수
+
+    Returns:
+        결과 목록 [{"specialist": "name", "result": "...", "success": bool}]
+    """
+    results = []
+
+    with ThreadPoolExecutor(max_workers=max_workers) as executor:
+        future_to_task = {}
+        for task_info in tasks:
+            future = executor.submit(
+                _run_specialist_in_thread,
+                task_info["specialist"],
+                task_info["task"],
+                task_info.get("context", ""),
+            )
+            future_to_task[future] = task_info
+
+        for future in as_completed(future_to_task):
+            task_info = future_to_task[future]
+            try:
+                result = future.result(timeout=120)
+                results.append(
+                    {
+                        "specialist": task_info["specialist"],
+                        "result": result,
+                        "success": True,
+                    }
+                )
+            except Exception as e:
+                results.append(
+                    {
+                        "specialist": task_info["specialist"],
+                        "result": str(e),
+                        "success": False,
+                    }
+                )
+
+    return results
+
+
+@tool
+def parallel_research(tasks_json: str) -> str:
+    """
+    여러 Specialist에게 병렬로 작업을 위임합니다.
+
+    복잡한 분석을 위해 여러 전문가를 동시에 활용할 때 사용합니다.
+
+    Args:
+        tasks_json: JSON 형식의 작업 목록
+            예: '[{"specialist": "researcher", "task": "DynamoDB 가격 조사"},
+                  {"specialist": "reviewer", "task": "보안 검토"}]'
+
+    Returns:
+        str: 모든 Specialist의 결과를 종합한 보고서
+
+    Example:
+        parallel_research('[
+            {"specialist": "explorer", "task": "현재 아키텍처 분석"},
+            {"specialist": "researcher", "task": "대안 서비스 조사"},
+            {"specialist": "reviewer", "task": "개선안 검토"}
+        ]')
+    """
+    import json
+
+    try:
+        tasks = json.loads(tasks_json)
+    except json.JSONDecodeError as e:
+        return f"JSON 파싱 오류: {e}"
+
+    if not isinstance(tasks, list):
+        return "tasks_json은 배열 형식이어야 합니다."
+
+    results = run_specialists_parallel(tasks)
+
+    # 결과 종합
+    output = "## 병렬 분석 결과\n\n"
+
+    for r in results:
+        specialist = r["specialist"].upper()
+        if r["success"]:
+            output += f"### {specialist} 결과\n{r['result']}\n\n"
+        else:
+            output += f"### {specialist} (실패)\n오류: {r['result']}\n\n"
+
+    return output

agentskills/__init__.py

@@ -0,0 +1,38 @@
+"""Agent Skills - SA Agent용 스킬 시스템
+
+Progressive Disclosure 패턴을 따르는 스킬 로딩 시스템:
+- Phase 1: 메타데이터만 로드 (discovery)
+- Phase 2: 필요 시 전체 instructions 로드 (skill tool)
+- Phase 3: 리소스 파일 로드 (file_read)
+"""
+
+from .models import SkillProperties
+from .parser import find_skill_md, load_metadata, load_instructions, load_resource
+from .discovery import discover_skills
+from .prompt import generate_skills_prompt
+from .tool import create_skill_tool
+from .errors import (
+    SkillError,
+    ParseError,
+    ValidationError,
+    SkillNotFoundError,
+    SkillActivationError,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "SkillProperties",
+    "find_skill_md",
+    "load_metadata",
+    "load_instructions",
+    "load_resource",
+    "discover_skills",
+    "generate_skills_prompt",
+    "create_skill_tool",
+    "SkillError",
+    "ParseError",
+    "ValidationError",
+    "SkillNotFoundError",
+    "SkillActivationError",
+]

agentskills/discovery.py

@@ -0,0 +1,107 @@
+"""스킬 디스커버리 - Progressive Disclosure Phase 1
+
+스킬 디렉토리를 스캔하여 경량 메타데이터만 로드합니다.
+"""
+
+import logging
+from pathlib import Path
+from typing import List
+
+from .parser import find_skill_md, load_metadata
+from .errors import ParseError, ValidationError
+from .models import SkillProperties
+
+logger = logging.getLogger(__name__)
+
+
+def is_safe_path(path: Path, base_dir: Path) -> bool:
+    """경로가 base_dir 내부에 안전하게 포함되어 있는지 확인
+    
+    심볼릭 링크나 경로 조작을 통한 디렉토리 탐색 공격 방지
+    """
+    try:
+        resolved_path = path.resolve()
+        resolved_base = base_dir.resolve()
+        resolved_path.relative_to(resolved_base)
+        return True
+    except (ValueError, OSError, RuntimeError):
+        return False
+
+
+def discover_skills(skills_dir: str | Path) -> List[SkillProperties]:
+    """디렉토리에서 모든 스킬 발견
+    
+    스킬 디렉토리를 스캔하고 각 스킬의 SKILL.md frontmatter에서
+    메타데이터를 로드합니다. (Progressive Disclosure Phase 1)
+    
+    디렉토리 구조:
+        skills/
+        ├── pptx/
+        │   ├── SKILL.md          # 필수
+        │   └── references/       # 선택
+        │       └── html2pptx.md
+        ├── docx/
+        │   └── SKILL.md
+        └── mcp/
+            └── SKILL.md
+    
+    Args:
+        skills_dir: 스킬 하위 디렉토리들이 있는 경로
+        
+    Returns:
+        SkillProperties 리스트 (이름순 정렬)
+    """
+    skills_dir = Path(skills_dir).expanduser().resolve()
+
+    if not skills_dir.exists():
+        logger.info(f"스킬 디렉토리가 존재하지 않습니다: {skills_dir}")
+        return []
+
+    if not skills_dir.is_dir():
+        logger.warning(f"스킬 경로가 디렉토리가 아닙니다: {skills_dir}")
+        return []
+
+    skills: List[SkillProperties] = []
+
+    # 각 하위 디렉토리 스캔
+    for skill_dir in skills_dir.iterdir():
+        if not skill_dir.is_dir():
+            continue
+
+        # 보안: 경로 검증
+        if not is_safe_path(skill_dir, skills_dir):
+            logger.warning(f"안전하지 않은 경로 건너뜀: {skill_dir}")
+            continue
+
+        # SKILL.md 찾기
+        skill_md_path = find_skill_md(skill_dir)
+        if skill_md_path is None:
+            logger.debug(f"SKILL.md를 찾을 수 없음: {skill_dir}")
+            continue
+
+        # 보안: SKILL.md 경로 검증
+        if not is_safe_path(skill_md_path, skills_dir):
+            logger.warning(f"안전하지 않은 SKILL.md 건너뜀: {skill_md_path}")
+            continue
+
+        # 메타데이터 파싱
+        try:
+            skill_props = load_metadata(skill_dir)
+            skills.append(skill_props)
+            logger.debug(f"스킬 발견: {skill_props.name}")
+
+        except (ParseError, ValidationError) as e:
+            logger.warning(f"유효하지 않은 스킬 건너뜀 ({skill_dir}): {e}")
+            continue
+        except Exception as e:
+            logger.error(f"예상치 못한 오류 ({skill_dir}): {e}")
+            continue
+
+    # 이름순 정렬
+    skills.sort(key=lambda s: s.name)
+
+    logger.info(f"{skills_dir}에서 {len(skills)}개 스킬 발견")
+    return skills
+
+
+__all__ = ["discover_skills"]