[25.05.18 / TASK-193] Feature - module for velog api & llm (v0.6 배치) (#28)

* feature: velog 를 독립성 높게 분리, 모듈화
* feature: HttpSession 프로토콜 업데이트
* modify: 프로토콜 활용 세션 실제 메소드 호출시 mypy 이슈 해결
* feature: 라이브러리 추가
* feature: llm module 추가
* feature: llm module 추가 v2
* feature: llm module 추가 v4
* feature: temp 파일, 임시 트랜드 분석 처리 파일
* hotfix: 제 토큰 노출 ㅋㅋㅋ 하 어짜피 만료될꺼 그냥 커밋 롤백 안하고 상남자식 푸시
* refactor: 모듈들 코멘트 리펙토링, 싱글톤 & 레이지 이니셜라이징 강화
* refactor: 마지막 런타임 레벨에서 타입 강화
* refactor: client 와 service 분리, 파사드 와 레이지 싱클톤 패턴으로 취합
* refactor: clinet 의 service 를 다루는 방법 리펙토링

Author: Nuung

.env.sample

@@ -27,4 +27,7 @@ POSTGRES_PORT=5432
 # Sentry info
 SENTRY_DSN=https://sentry.io/project # https://<key>@sentry.io/<project>
 SENTRY_ENVIRONMENT=local # develop
-SENTRY_TRACES_SAMPLE_RATE=0.2
+SENTRY_TRACES_SAMPLE_RATE=0.2
+
+# LLM
+OPENAI_API_KEY=sk-proj-...

.github/workflows/test-ci.yaml

@@ -70,6 +70,7 @@ jobs:
           echo "SENTRY_DSN=${{ secrets.SENTRY_DSN }}" >> .env
           echo "SENTRY_ENVIRONMENT=gitaction" >> .env
           echo "SENTRY_TRACES_SAMPLE_RATE=0.2" >> .env
+          echo "OPENAI_API_KEY= sk-proj" >> .env
           echo "AES_KEY_0=${{ secrets.AES_KEY_0 }}" >> .env
           echo "AES_KEY_1=${{ secrets.AES_KEY_1 }}" >> .env
           echo "AES_KEY_2=${{ secrets.AES_KEY_2 }}" >> .env

modules/llm/__init__.py

@@ -0,0 +1,109 @@
+from abc import ABC, abstractmethod
+from typing import Any, Generic, TypeVar
+
+# 클라이언트 타입을 위한 제네릭 타입 변수
+T = TypeVar("T")
+
+
+class LLMClient(ABC, Generic[T]):
+    """
+    모든 LLM 클라이언트를 위한 추상 기본 클래스로 Lazy Initialization 패턴을 따릅니다.
+    모든 LLM 서비스 구현을 위한 템플릿을 제공합니다.
+    """
+
+    @classmethod
+    @abstractmethod
+    def get_client(cls, api_key: str) -> "LLMClient[T]":
+        """
+        LLM 클라이언트를 가져오거나 초기화합니다.
+
+        Args:
+            api_key: API 키 (필수)
+
+        Returns:
+            초기화된 클라이언트 인스턴스
+
+        Raises:
+            AuthenticationError: API 키가 유효하지 않은 경우
+            ConnectionError: 서비스 연결에 실패한 경우
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def _initialize_client(cls, api_key: str) -> T:
+        """
+        특정 LLM 클라이언트를 초기화하는 추상 메서드.
+        각 구체적인 하위 클래스에서 구현되어야 합니다.
+
+        Args:
+            api_key: API 키 (필수)
+
+        Returns:
+            초기화된 클라이언트 인스턴스
+
+        Raises:
+            AuthenticationError: API 키가 유효하지 않은 경우
+            ConnectionError: 서비스 연결에 실패한 경우
+        """
+        pass
+
+    @abstractmethod
+    def generate_text(
+        self,
+        prompt: str,
+        system_prompt: str = "",
+        model: str = "",
+        **kwargs: Any,
+    ) -> str:
+        """
+        LLM을 사용하여 텍스트를 생성합니다.
+
+        Args:
+            prompt: 텍스트 생성을 위한 입력 프롬프트
+            system_prompt: 시스템 프롬프트 (선택적)
+            model: 사용할 모델 (선택적)
+            **kwargs: LLM에 특화된 추가 인자
+
+        Returns:
+            LLM에서 생성된 텍스트
+
+        Raises:
+            ClientNotInitializedError: 클라이언트가 초기화되지 않은 경우
+            ValueError: 잘못된 입력 값
+            ConnectionError: API 연결 실패
+            GenerationError: 생성 과정에서 오류 발생
+        """
+        pass
+
+    @abstractmethod
+    def generate_embedding(
+        self,
+        text: str | list[str],
+        model: str = "",
+    ) -> list[float] | list[list[float]]:
+        """
+        LLM을 사용하여 텍스트 임베딩을 생성합니다.
+
+        Args:
+            text: 임베딩을 생성할 텍스트 또는 텍스트 목록
+            model: 사용할 임베딩 모델 (선택적)
+
+        Returns:
+            벡터 임베딩 리스트(단일 텍스트 입력의 경우) 또는 벡터 임베딩 리스트의 리스트(다중 텍스트 입력의 경우)
+
+        Raises:
+            ClientNotInitializedError: 클라이언트가 초기화되지 않은 경우
+            ValueError: 잘못된 입력 값
+            ConnectionError: API 연결 실패
+            GenerationError: 생성 과정에서 오류 발생
+        """
+        pass
+
+    @classmethod
+    @abstractmethod
+    def reset_client(cls) -> None:
+        """
+        클라이언트 인스턴스를 재설정합니다(테스트나 설정 변경 시 사용하기 위함)
+        """
+        pass

modules/llm/base_client.py

@@ -0,0 +1,28 @@
+class LLMError(Exception):
+    """LLM 서비스 관련 기본 예외 클래스"""
+
+    pass
+
+
+class AuthenticationError(LLMError):
+    """API 키 인증 실패 시 발생하는 예외"""
+
+    pass
+
+
+class ConnectionError(LLMError):
+    """LLM 서비스 연결 실패 시 발생하는 예외"""
+
+    pass
+
+
+class GenerationError(LLMError):
+    """텍스트 또는 임베딩 생성 중 발생하는 예외"""
+
+    pass
+
+
+class ClientNotInitializedError(LLMError):
+    """클라이언트가 초기화되지 않았을 때 발생하는 예외"""
+
+    pass