sa-assistant 0.1.1__py3-none-any.whl

agentskills/errors.py

@@ -0,0 +1,38 @@
+"""스킬 관련 예외 정의"""
+
+
+class SkillError(Exception):
+    """스킬 관련 기본 예외"""
+    pass
+
+
+class ParseError(SkillError):
+    """SKILL.md 파싱 실패 시 발생"""
+    pass
+
+
+class ValidationError(SkillError):
+    """스킬 속성 검증 실패 시 발생"""
+
+    def __init__(self, message: str, errors: list[str] | None = None):
+        super().__init__(message)
+        self.errors = errors if errors is not None else [message]
+
+
+class SkillNotFoundError(SkillError):
+    """요청한 스킬을 찾을 수 없을 때 발생"""
+    pass
+
+
+class SkillActivationError(SkillError):
+    """스킬 활성화 실패 시 발생"""
+    pass
+
+
+__all__ = [
+    "SkillError",
+    "ParseError",
+    "ValidationError",
+    "SkillNotFoundError",
+    "SkillActivationError",
+]

agentskills/models.py

@@ -0,0 +1,48 @@
+"""스킬 데이터 모델"""
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+
+@dataclass
+class SkillProperties:
+    """SKILL.md frontmatter에서 파싱된 스킬 메타데이터
+    
+    Progressive Disclosure Phase 1: 경량 메타데이터만 포함 (~100 tokens)
+    
+    Attributes:
+        name: 스킬 이름 (kebab-case)
+        description: 스킬 설명 및 사용 시점
+        path: SKILL.md 파일의 절대 경로
+        skill_dir: 스킬 디렉토리의 절대 경로
+        license: 라이선스 정보 (선택)
+        allowed_tools: 스킬이 사용하는 도구 패턴 (선택)
+        metadata: 커스텀 메타데이터 (선택)
+    """
+
+    name: str
+    description: str
+    path: str
+    skill_dir: str
+    license: Optional[str] = None
+    allowed_tools: Optional[str] = None
+    metadata: dict[str, str] = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """딕셔너리로 변환 (None 값 제외)"""
+        result = {
+            "name": self.name,
+            "description": self.description,
+            "path": self.path,
+            "skill_dir": self.skill_dir,
+        }
+        if self.license is not None:
+            result["license"] = self.license
+        if self.allowed_tools is not None:
+            result["allowed_tools"] = self.allowed_tools
+        if self.metadata:
+            result["metadata"] = self.metadata
+        return result
+
+
+__all__ = ["SkillProperties"]

agentskills/parser.py

@@ -0,0 +1,183 @@
+"""SKILL.md 파일 파싱
+
+YAML frontmatter와 Markdown body를 분리하여 파싱합니다.
+"""
+
+import re
+from pathlib import Path
+from typing import Optional
+
+import yaml
+
+from .errors import ParseError, ValidationError
+from .models import SkillProperties
+
+
+def find_skill_md(skill_dir: Path) -> Optional[Path]:
+    """스킬 디렉토리에서 SKILL.md 파일 찾기
+    
+    SKILL.md (대문자) 우선, skill.md (소문자)도 허용
+    """
+    for name in ("SKILL.md", "skill.md"):
+        path = skill_dir / name
+        if path.exists():
+            return path
+    return None
+
+
+def _parse_skill_md(content: str) -> tuple[dict, str]:
+    """SKILL.md 내용을 frontmatter와 body로 분리
+    
+    Args:
+        content: SKILL.md 파일 내용
+        
+    Returns:
+        (frontmatter dict, body string) 튜플
+        
+    Raises:
+        ParseError: frontmatter가 유효하지 않을 때
+    """
+    match = re.match(r'^---\s*\n(.*?)\n---\s*\n?(.*)$', content, re.DOTALL)
+    if not match:
+        raise ParseError("SKILL.md는 YAML frontmatter (---)로 시작해야 합니다")
+
+    frontmatter_str = match.group(1)
+    body = match.group(2).strip()
+
+    try:
+        frontmatter = yaml.safe_load(frontmatter_str)
+    except yaml.YAMLError as e:
+        raise ParseError(f"frontmatter YAML 파싱 오류: {e}")
+
+    if not isinstance(frontmatter, dict):
+        raise ParseError("SKILL.md frontmatter는 YAML 매핑이어야 합니다")
+
+    # metadata 필드가 있으면 문자열로 변환
+    if "metadata" in frontmatter and isinstance(frontmatter["metadata"], dict):
+        frontmatter["metadata"] = {
+            str(k): str(v) for k, v in frontmatter["metadata"].items()
+        }
+
+    return frontmatter, body
+
+
+def load_metadata(skill_dir: str | Path) -> SkillProperties:
+    """SKILL.md frontmatter에서 메타데이터 로드 (Phase 1)
+    
+    경량 메타데이터만 로드하여 컨텍스트 절약
+    
+    Args:
+        skill_dir: 스킬 디렉토리 경로
+        
+    Returns:
+        SkillProperties (instructions 미포함)
+        
+    Raises:
+        ParseError: SKILL.md가 없거나 YAML이 유효하지 않을 때
+        ValidationError: 필수 필드가 없을 때
+    """
+    skill_dir = Path(skill_dir).resolve()
+    skill_md = find_skill_md(skill_dir)
+
+    if skill_md is None:
+        raise ParseError(f"SKILL.md를 찾을 수 없습니다: {skill_dir}")
+
+    content = skill_md.read_text(encoding="utf-8")
+    frontmatter, _ = _parse_skill_md(content)
+
+    # 필수 필드 검증
+    if "name" not in frontmatter:
+        raise ValidationError("frontmatter에 'name' 필드가 필요합니다")
+    if "description" not in frontmatter:
+        raise ValidationError("frontmatter에 'description' 필드가 필요합니다")
+
+    name = frontmatter["name"]
+    description = frontmatter["description"]
+
+    if not isinstance(name, str) or not name.strip():
+        raise ValidationError("'name'은 비어있지 않은 문자열이어야 합니다")
+    if not isinstance(description, str) or not description.strip():
+        raise ValidationError("'description'은 비어있지 않은 문자열이어야 합니다")
+
+    return SkillProperties(
+        name=name.strip(),
+        description=description.strip(),
+        path=str(skill_md.absolute()),
+        skill_dir=str(skill_dir.absolute()),
+        license=frontmatter.get("license"),
+        allowed_tools=frontmatter.get("allowed-tools"),
+        metadata=frontmatter.get("metadata", {}),
+    )
+
+
+def load_instructions(skill_path: str | Path) -> str:
+    """SKILL.md body에서 instructions 로드 (Phase 2)
+    
+    스킬이 활성화될 때 전체 Markdown body를 로드
+    
+    Args:
+        skill_path: SKILL.md 파일 경로
+        
+    Returns:
+        Markdown body (instructions)
+        
+    Raises:
+        ParseError: 파일을 읽거나 파싱할 수 없을 때
+    """
+    skill_path = Path(skill_path)
+
+    try:
+        content = skill_path.read_text(encoding="utf-8")
+        _, instructions = _parse_skill_md(content)
+        return instructions
+    except Exception as e:
+        raise ParseError(f"instructions 로드 실패 ({skill_path}): {e}")
+
+
+def load_resource(skill_dir: str | Path, resource_path: str) -> str:
+    """스킬 디렉토리에서 리소스 파일 로드 (Phase 3)
+    
+    scripts/, references/, assets/ 등의 파일을 필요 시 로드
+    
+    Args:
+        skill_dir: 스킬 디렉토리 경로
+        resource_path: 상대 경로 (예: "references/html2pptx.md")
+        
+    Returns:
+        리소스 파일 내용
+        
+    Raises:
+        ParseError: 리소스를 읽을 수 없거나 디렉토리 외부일 때
+    """
+    skill_dir = Path(skill_dir).resolve()
+    resource_file = (skill_dir / resource_path).resolve()
+
+    # 보안: 스킬 디렉토리 내부인지 확인
+    try:
+        resource_file.relative_to(skill_dir)
+    except ValueError:
+        raise ParseError(f"리소스 경로가 스킬 디렉토리 외부입니다: {resource_path}")
+
+    if not resource_file.exists():
+        raise ParseError(f"리소스를 찾을 수 없습니다: {resource_path}")
+
+    if not resource_file.is_file():
+        raise ParseError(f"리소스가 파일이 아닙니다: {resource_path}")
+
+    # 파일 크기 제한 (10MB)
+    MAX_FILE_SIZE = 10 * 1024 * 1024
+    if resource_file.stat().st_size > MAX_FILE_SIZE:
+        raise ParseError(f"리소스가 너무 큽니다 (최대 10MB): {resource_path}")
+
+    try:
+        return resource_file.read_text(encoding="utf-8")
+    except Exception as e:
+        raise ParseError(f"리소스 읽기 실패 ({resource_path}): {e}")
+
+
+__all__ = [
+    "find_skill_md",
+    "load_metadata",
+    "load_instructions",
+    "load_resource",
+]

agentskills/prompt.py

@@ -0,0 +1,70 @@
+"""스킬 프롬프트 생성
+
+시스템 프롬프트에 포함할 스킬 메타데이터 XML 생성
+"""
+
+from typing import List
+from .models import SkillProperties
+
+
+SKILLS_SYSTEM_PROMPT = """
+## Skills System
+
+You have access to a skills library that provides specialized capabilities.
+
+<skills_instructions>
+**스킬 사용 방법:**
+
+스킬은 **Progressive Disclosure** 패턴을 따릅니다:
+- 시스템 프롬프트에는 스킬 메타데이터(이름, 설명)만 포함됩니다
+- 전체 instructions는 스킬이 필요할 때 로드됩니다
+
+1. **스킬 적용 여부 확인**: 사용자 요청이 아래 스킬 설명과 일치하는지 확인
+2. **스킬 instructions 로드**: `skill(skill_name="스킬이름")` 도구 호출
+3. **instructions 따르기**: 로드된 워크플로우, 예제, 베스트 프랙티스 준수
+4. **리소스 파일 접근**: 필요 시 `file_read`로 추가 파일 로드
+
+**스킬 사용 시점:**
+- 사용자 요청이 스킬 도메인과 일치할 때 (예: "PPT 만들어줘" → pptx 스킬)
+- 전문 지식이나 구조화된 워크플로우가 필요할 때
+- 복잡한 작업에 검증된 패턴이 있을 때
+</skills_instructions>
+
+<available_skills>
+{skills_list}
+</available_skills>
+"""
+
+
+def generate_skills_prompt(skills: List[SkillProperties]) -> str:
+    """스킬 메타데이터로 시스템 프롬프트 섹션 생성
+    
+    Progressive Disclosure Phase 1: 메타데이터만 포함하여 컨텍스트 절약
+    
+    Args:
+        skills: 발견된 스킬 속성 리스트
+        
+    Returns:
+        XML 형식의 프롬프트 텍스트
+    """
+    if not skills:
+        return ""
+
+    # XML 스킬 리스트 생성 (메타데이터만)
+    skill_elements = []
+    for skill in sorted(skills, key=lambda s: s.name):
+        skill_xml = (
+            "  <skill>\n"
+            f"    <name>{skill.name}</name>\n"
+            f"    <description>{skill.description}</description>\n"
+            f"    <location>{skill.path}</location>\n"
+            "  </skill>"
+        )
+        skill_elements.append(skill_xml)
+
+    skills_list = "\n".join(skill_elements)
+
+    return SKILLS_SYSTEM_PROMPT.format(skills_list=skills_list)
+
+
+__all__ = ["generate_skills_prompt"]

agentskills/tool.py

@@ -0,0 +1,138 @@
+"""스킬 도구 - Progressive Disclosure Phase 2
+
+스킬이 필요할 때 전체 instructions를 로드하는 Strands 도구
+"""
+
+import logging
+from pathlib import Path
+from typing import List, Dict
+
+from strands import tool
+
+from .models import SkillProperties
+from .errors import SkillNotFoundError, SkillActivationError
+from .parser import load_instructions
+
+logger = logging.getLogger(__name__)
+
+
+def _scan_skill_resources(skill_dir: Path) -> List[str]:
+    """스킬 디렉토리에서 사용 가능한 리소스 스캔
+    
+    references/, scripts/, assets/ 하위 디렉토리의 파일 목록 반환
+    """
+    resources = []
+    for subdir in ["references", "scripts", "assets"]:
+        resource_dir = skill_dir / subdir
+        if resource_dir.exists() and resource_dir.is_dir():
+            for file_path in sorted(resource_dir.rglob("*")):
+                if file_path.is_file():
+                    resources.append(str(file_path.absolute()))
+    return resources
+
+
+def _build_skill_header(skill: SkillProperties) -> str:
+    """스킬 헤더 문자열 생성 (메타데이터 + 리소스 목록)"""
+    header = (
+        f"# Skill: {skill.name}\n\n"
+        f"**Description:** {skill.description}\n\n"
+        f"**Skill Directory:** `{skill.skill_dir}/`\n\n"
+    )
+
+    # allowed-tools가 있으면 표시
+    if skill.allowed_tools:
+        header += f"\n**IMPORTANT:** Only use these tools: `{skill.allowed_tools}`\n"
+
+    # 리소스 파일 목록
+    skill_dir = Path(skill.skill_dir)
+    resources = _scan_skill_resources(skill_dir)
+
+    if resources:
+        header += "\n**Available Resources (use file_read to access):**\n"
+        for resource in resources:
+            header += f"- `{resource}`\n"
+        header += "\n"
+
+    header += "---\n\n"
+
+    return header
+
+
+def create_skill_tool(skills: List[SkillProperties], skills_dir: str | Path):
+    """스킬 활성화 도구 생성 (Inline Mode)
+    
+    Progressive Disclosure를 구현하는 팩토리 함수:
+    - Phase 1: 시스템 프롬프트에 메타데이터 (이미 로드됨)
+    - Phase 2: 스킬 호출 시 전체 instructions 로드
+    - Phase 3: LLM이 file_read로 리소스 접근
+    
+    Args:
+        skills: 발견된 스킬 속성 리스트
+        skills_dir: 스킬 기본 디렉토리
+        
+    Returns:
+        @tool 데코레이터가 적용된 Strands 도구 함수
+        
+    Example:
+        >>> from agentskills import discover_skills, create_skill_tool
+        >>> from strands import Agent
+        >>> from strands_tools import file_read
+        >>>
+        >>> skills = discover_skills("./skills")
+        >>> skill_tool = create_skill_tool(skills, "./skills")
+        >>>
+        >>> agent = Agent(tools=[skill_tool, file_read])
+    """
+    skills_dir = Path(skills_dir).expanduser().resolve()
+
+    # 빠른 조회를 위한 맵 생성
+    skill_map: Dict[str, SkillProperties] = {skill.name: skill for skill in skills}
+
+    @tool
+    def skill(skill_name: str) -> str:
+        """전문 스킬 instructions를 로드합니다.
+        
+        사용자 요청이 특정 스킬 도메인과 일치할 때 호출하세요.
+        로드된 instructions에는 워크플로우, 예제, 베스트 프랙티스가 포함됩니다.
+        
+        Args:
+            skill_name: 스킬 이름 (시스템 프롬프트의 available_skills 참조)
+                - "pptx": PowerPoint 프레젠테이션 생성
+                - "docx": Word 문서 생성
+                - "mcp": MCP 도구 사용 가이드
+                
+        Returns:
+            스킬 헤더 + 전체 instructions + 리소스 정보
+            
+        Example:
+            skill(skill_name="pptx")  # PPTX 생성 스킬 로드
+        """
+        # 스킬 존재 여부 확인
+        if skill_name not in skill_map:
+            available = ", ".join(skill_map.keys())
+            raise SkillNotFoundError(
+                f"스킬 '{skill_name}'을 찾을 수 없습니다. "
+                f"사용 가능한 스킬: {available}"
+            )
+
+        skill_props = skill_map[skill_name]
+
+        try:
+            # Phase 2: instructions 로드
+            instructions = load_instructions(skill_props.path)
+            logger.info(f"스킬 로드됨: {skill_name}")
+
+            # 헤더 + instructions 조합
+            header = _build_skill_header(skill_props)
+            return header + instructions
+
+        except Exception as e:
+            logger.error(f"스킬 '{skill_name}' 로드 오류: {e}", exc_info=True)
+            raise SkillActivationError(
+                f"스킬 '{skill_name}' 로드 실패: {e}"
+            ) from e
+
+    return skill
+
+
+__all__ = ["create_skill_tool"]

cli/__init__.py

@@ -0,0 +1,51 @@
+"""SA Assistant CLI Module - Rich-based modern CLI interface."""
+
+from .console import (
+    SAConsole,
+    get_console,
+    print_error,
+    print_warning,
+    print_info,
+    print_success,
+)
+from .components import (
+    AgentPanel,
+    ToolStatus,
+    ResponseRenderer,
+    print_banner,
+    print_help,
+)
+from .callback import (
+    RichCallbackHandler,
+    MinimalCallbackHandler,
+    VerboseCallbackHandler,
+)
+from .mdstream import (
+    MarkdownStream,
+    SimpleMarkdownStream,
+    SAMarkdown,
+    render_markdown,
+    render_code,
+)
+
+__all__ = [
+    "SAConsole",
+    "get_console",
+    "print_error",
+    "print_warning",
+    "print_info",
+    "print_success",
+    "AgentPanel",
+    "ToolStatus",
+    "ResponseRenderer",
+    "RichCallbackHandler",
+    "MinimalCallbackHandler",
+    "VerboseCallbackHandler",
+    "print_banner",
+    "print_help",
+    "MarkdownStream",
+    "SimpleMarkdownStream",
+    "SAMarkdown",
+    "render_markdown",
+    "render_code",
+]

cli/callback.py

@@ -0,0 +1,145 @@
+"""SA Assistant Rich Callback Handler - Strands Agent callback to Rich UI."""
+
+from typing import Any, Set, Optional
+from .console import get_console
+from .components import ToolStatus
+from .mdstream import MarkdownStream
+
+
+class RichCallbackHandler:
+    """Rich-based Strands Agent callback handler with markdown streaming.
+
+    Usage:
+        handler = RichCallbackHandler()
+        agent = Agent(callback_handler=handler)
+    """
+
+    def __init__(
+        self,
+        show_tool_calls: bool = True,
+        show_thinking: bool = False,
+        use_markdown_stream: bool = True,
+    ):
+        self.console = get_console()
+        self.show_tool_calls = show_tool_calls
+        self.show_thinking = show_thinking
+        self.use_markdown_stream = use_markdown_stream
+
+        self._tool_status = ToolStatus()
+        self._printed_tool_ids: Set[str] = set()
+        self._in_response = False
+        self._text_buffer = ""
+        self._md_stream: Optional[MarkdownStream] = None
+
+    def reset(self) -> None:
+        """Reset state for new conversation."""
+        self._printed_tool_ids.clear()
+        self._in_response = False
+        self._text_buffer = ""
+        if self._md_stream:
+            self._md_stream.finish()
+            self._md_stream = None
+
+    def __call__(self, **kwargs) -> None:
+        """Strands Agent callback entry point."""
+        if "data" in kwargs:
+            self._handle_data(kwargs["data"])
+
+        if "current_tool_use" in kwargs and self.show_tool_calls:
+            self._handle_tool_use(kwargs["current_tool_use"])
+
+        if "thinking" in kwargs and self.show_thinking:
+            self._handle_thinking(kwargs["thinking"])
+
+        if "tool_result" in kwargs:
+            self._handle_tool_result(kwargs["tool_result"])
+
+        if "stop" in kwargs:
+            self._handle_stop()
+
+    def _handle_data(self, data: str) -> None:
+        """Handle streaming text."""
+        if not self._in_response:
+            self._in_response = True
+            if self.use_markdown_stream:
+                self._md_stream = MarkdownStream(console=self.console)
+
+        self._text_buffer += data
+
+        if self.use_markdown_stream and self._md_stream:
+            self._md_stream.update(self._text_buffer)
+        else:
+            print(data, end="", flush=True)
+
+    def _handle_tool_use(self, tool_use: Any) -> None:
+        """Handle tool invocation."""
+        if not isinstance(tool_use, dict):
+            return
+
+        tool_id = tool_use.get("toolUseId", "")
+        tool_name = tool_use.get("name", "")
+
+        if tool_id and tool_id in self._printed_tool_ids:
+            return
+
+        if not tool_name:
+            return
+
+        if tool_id:
+            self._printed_tool_ids.add(tool_id)
+
+        self._finalize_response()
+
+        args = tool_use.get("input", {})
+        self._tool_status.tool_start(tool_id, tool_name, args)
+
+    def _handle_thinking(self, thinking: str) -> None:
+        """Handle thinking text."""
+        display = f"{thinking[:100]}..." if len(thinking) > 100 else thinking
+        self.console.print(f"[text.thinking]💭 {display}[/]")
+
+    def _handle_tool_result(self, result: Any) -> None:
+        """Handle tool result."""
+        if isinstance(result, dict) and result.get("status") == "error":
+            error_msg = result.get("error", "Unknown error")
+            self.console.print(f"[tool.error]  ↳ Error: {error_msg}[/]")
+
+    def _handle_stop(self) -> None:
+        """Handle stop event - finalize markdown rendering."""
+        self._finalize_response()
+
+    def _finalize_response(self) -> None:
+        """Finalize current response."""
+        if self._in_response:
+            if self.use_markdown_stream and self._md_stream:
+                self._md_stream.update(self._text_buffer, final=True)
+                self._md_stream = None
+            else:
+                print()
+            self._in_response = False
+            self._text_buffer = ""
+
+
+class MinimalCallbackHandler:
+    """Minimal callback handler - text streaming only."""
+
+    def __call__(self, **kwargs) -> None:
+        if "data" in kwargs:
+            print(kwargs["data"], end="", flush=True)
+
+
+class VerboseCallbackHandler(RichCallbackHandler):
+    """Verbose callback handler - shows all events."""
+
+    def __init__(self):
+        super().__init__(show_tool_calls=True, show_thinking=True)
+
+    def __call__(self, **kwargs) -> None:
+        super().__call__(**kwargs)
+
+        if "message" in kwargs:
+            self.console.print("[text.dim]📨 Message event[/]")
+
+        if "stop" in kwargs:
+            reason = kwargs.get("stop_reason", "unknown")
+            self.console.print(f"[text.dim]🛑 Stop reason: {reason}[/]")