Merge pull request #26 from kookmin-sw/feature/#17-ai-scaffolding

[#17][AI] ai/ 프로젝트 스캐폴딩 + config + exceptions

Author: jys705

ai/.gitkeep

@@ -0,0 +1 @@
+"""Poco AI Orchestrator — backend 의존성 없이 독립 동작하는 AI 모듈."""

ai/__init__.py

@@ -0,0 +1 @@
+# ai/clients — Bedrock Claude + KB 클라이언트

ai/clients/__init__.py

@@ -0,0 +1,26 @@
+"""환경 변수 기반 AI 모듈 설정.
+
+backend 의존성 없이 독립 동작하며, pydantic-settings로 환경 변수를 로드한다.
+"""
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class AISettings(BaseSettings):
+    """AI 모듈 환경 설정.
+
+    환경 변수 또는 .env 파일에서 값을 로드한다.
+    모든 필드에 sensible default가 있으므로 최소 설정으로 동작 가능.
+    """
+
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
+
+    AWS_REGION: str = "ap-northeast-2"
+    MODEL_ID: str = "anthropic.claude-3-5-sonnet-20241022-v2:0"
+    KB_A_ID: str = ""
+    KB_B_ID: str = ""
+    MAX_TOKENS: int = 4096
+    TEMPERATURE: float = 0.7
+
+
+ai_settings = AISettings()

ai/config.py

@@ -0,0 +1,61 @@
+"""AI 모듈 커스텀 예외 및 에러 코드.
+
+backend 의존성(FastAPI 등) 없이 독립 동작한다.
+"""
+
+from enum import Enum
+
+
+class AIErrorCode(str, Enum):
+    """AI 모듈 에러 코드."""
+
+    AI_GENERATION_FAILED = "AI_GENERATION_FAILED"
+    SCHEMA_VALIDATION_ERROR = "SCHEMA_VALIDATION_ERROR"
+    RAG_SEARCH_FAILED = "RAG_SEARCH_FAILED"
+    PROMPT_TEMPLATE_NOT_FOUND = "PROMPT_TEMPLATE_NOT_FOUND"
+    BEDROCK_API_ERROR = "BEDROCK_API_ERROR"
+
+
+class AIError(Exception):
+    """AI 모듈 기반 예외 클래스."""
+
+    def __init__(self, code: AIErrorCode, message: str, details: dict | None = None):
+        self.code = code
+        self.message = message
+        self.details = details or {}
+        super().__init__(f"[{code.value}] {message}")
+
+
+class AIGenerationFailedError(AIError):
+    """Claude 호출 실패 또는 재시도 초과."""
+
+    def __init__(self, message: str = "AI 생성에 실패했습니다.", details: dict | None = None):
+        super().__init__(AIErrorCode.AI_GENERATION_FAILED, message, details)
+
+
+class SchemaValidationError(AIError):
+    """출력 스키마 불일치."""
+
+    def __init__(self, message: str = "응답 스키마 검증에 실패했습니다.", details: dict | None = None):
+        super().__init__(AIErrorCode.SCHEMA_VALIDATION_ERROR, message, details)
+
+
+class RAGSearchFailedError(AIError):
+    """KB 검색 실패 (비치명적)."""
+
+    def __init__(self, message: str = "RAG 검색에 실패했습니다.", details: dict | None = None):
+        super().__init__(AIErrorCode.RAG_SEARCH_FAILED, message, details)
+
+
+class PromptTemplateNotFoundError(AIError):
+    """프롬프트 파일 미존재."""
+
+    def __init__(self, message: str = "프롬프트 템플릿을 찾을 수 없습니다.", details: dict | None = None):
+        super().__init__(AIErrorCode.PROMPT_TEMPLATE_NOT_FOUND, message, details)
+
+
+class BedrockAPIError(AIError):
+    """Bedrock API 레벨 에러 (throttling, timeout 등)."""
+
+    def __init__(self, message: str = "Bedrock API 호출에 실패했습니다.", details: dict | None = None):
+        super().__init__(AIErrorCode.BEDROCK_API_ERROR, message, details)

ai/exceptions.py

@@ -0,0 +1 @@
+{# accept 프롬프트 템플릿 — Phase 3에서 구현 #}

ai/prompts/accept.txt

@@ -0,0 +1 @@
+{# generate 프롬프트 템플릿 — Phase 3에서 구현 #}

ai/prompts/generate.txt

@@ -0,0 +1 @@
+{# side_panel 프롬프트 템플릿 — Phase 3에서 구현 #}

ai/prompts/side_panel.txt

@@ -0,0 +1,21 @@
+[project]
+name = "poco-ai"
+version = "0.1.0"
+description = "Poco AI Orchestrator — Bedrock Claude 기반 독립 AI 모듈"
+requires-python = ">=3.13"
+dependencies = [
+    "boto3>=1.35.0,<2.0.0",
+    "pydantic>=2.10.0,<3.0.0",
+    "pydantic-settings>=2.5.0,<3.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0,<9.0.0",
+    "pytest-asyncio>=0.24.0,<1.0.0",
+    "hypothesis>=6.100.0,<7.0.0",
+]
+
+[build-system]
+requires = ["setuptools>=75.0.0"]
+build-backend = "setuptools.build_meta"

ai/pyproject.toml

@@ -0,0 +1 @@
+# ai/schemas — Pydantic 입출력 스키마