@didim365/agent-cli-core 0.1.0 → 0.1.2

package/dist/docs/ai_adapter/02-architecture.md

@@ -1,452 +0,0 @@
-# 02. 아키텍처 설계
-
-## 2.1 현재 아키텍처
-
-### 2.1.1 전체 구조
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                       GeminiClient                           │
-│                  (High-level orchestration)                  │
-│                                                              │
-│  - 세션 관리                                                  │
-│  - 턴 처리                                                    │
-│  - 컨텍스트 압축                                              │
-│  - 훅 실행                                                    │
-└────────────────────────────┬────────────────────────────────┘
-                             │
-           ┌─────────────────┼─────────────────┐
-           │                 │                 │
-    ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼────────┐
-    │ GeminiChat  │  │BaseLlmClient│  │ ModelRouter   │
-    │             │  │             │  │ Service       │
-    │ - 채팅 히스토리│  │ - JSON 생성  │  │               │
-    │ - 메시지 스트림│  │ - 임베딩     │  │ - 폴백 전략    │
-    │ - 도구 처리   │  │ - 토큰 카운트 │  │ - 오버라이드   │
-    └──────┬──────┘  └──────┬──────┘  └──────┬────────┘
-           │                │                │
-           └────────────────┼────────────────┘
-                            │
-           ┌────────────────▼────────────────┐
-           │       ContentGenerator          │
-           │         (Interface)             │
-           │                                 │
-           │  + generateContent()            │
-           │  + generateContentStream()      │
-           │  + countTokens()                │
-           │  + embedContent()               │
-           └────────────────┬────────────────┘
-                            │
-        ┌───────────────────┼───────────────────┐
-        │                   │                   │
-   ┌────▼────┐    ┌────────▼─────────┐   ┌────▼──────┐
-   │GoogleGenAI│   │CodeAssistServer  │   │  Logging/ │
-   │          │   │                  │   │  Fake/    │
-   │@google/  │   │ OAuth 기반       │   │  Recording│
-   │genai SDK │   │ 엔터프라이즈      │   │           │
-   └────┬─────┘   └────────┬─────────┘   └───────────┘
-        │                  │
-        └────────┬─────────┘
-                 │
-        ┌────────▼────────┐
-        │   Gemini API    │
-        │   (Google)      │
-        └─────────────────┘
-```
-
-### 2.1.2 데이터 흐름
-
-```
-User Input
-    │
-    ▼
-┌─────────────┐
-│  CLI Layer  │ ──────────────────┐
-│ (packages/  │                   │
-│  cli)       │                   │
-└──────┬──────┘                   │
-       │                          │
-       ▼                          ▼
-┌─────────────┐           ┌──────────────┐
-│   Core      │           │   Config     │
-│   Client    │◄─────────►│   (Settings, │
-│             │           │    Models)   │
-└──────┬──────┘           └──────────────┘
-       │
-       ▼
-┌─────────────┐
-│  Content    │
-│  Generator  │
-└──────┬──────┘
-       │
-       ▼
-┌─────────────┐
-│  Gemini     │
-│  API        │
-└─────────────┘
-```
-
-### 2.1.3 현재 ContentGenerator 인터페이스
-
-```typescript
-// packages/core/src/core/contentGenerator.ts
-
-export interface ContentGenerator {
-  generateContent(
-    request: GenerateContentParameters,
-    userPromptId?: string
-  ): Promise<GenerateContentResponse>;
-
-  generateContentStream(
-    request: GenerateContentParameters,
-    userPromptId?: string
-  ): Promise<AsyncGenerator<GenerateContentResponse>>;
-
-  countTokens(
-    request: CountTokensRequest
-  ): Promise<CountTokensResponse>;
-
-  embedContent(
-    request: EmbedContentRequest
-  ): Promise<EmbedContentResponse>;
-}
-```
-
-**문제점**: 모든 타입이 `@google/genai`에서 직접 import됨
-
-## 2.2 목표 아키텍처
-
-### 2.2.1 어댑터 패턴 적용
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                       GeminiClient                           │
-│                  (High-level orchestration)                  │
-└────────────────────────────┬────────────────────────────────┘
-                             │
-           ┌─────────────────┼─────────────────┐
-           │                 │                 │
-    ┌──────▼──────┐  ┌──────▼──────┐  ┌──────▼────────┐
-    │  LlmChat    │  │BaseLlmClient│  │ ModelRouter   │
-    │ (Generic)   │  │             │  │ Service       │
-    └──────┬──────┘  └──────┬──────┘  └──────┬────────┘
-           │                │                │
-           └────────────────┼────────────────┘
-                            │
-           ┌────────────────▼────────────────┐
-           │       ContentGenerator          │
-           │    (Provider-Agnostic Types)    │
-           └────────────────┬────────────────┘
-                            │
-           ┌────────────────▼────────────────┐
-           │       ProviderRegistry          │
-           │                                 │
-           │  + register(name, adapter)      │
-           │  + get(name): ContentGenerator  │
-           │  + getDefault(): ContentGenerator│
-           └────────────────┬────────────────┘
-                            │
-    ┌───────────────────────┼───────────────────────┐
-    │                       │                       │
-┌───▼────┐           ┌──────▼──────┐         ┌─────▼─────┐
-│ Gemini │           │   Claude    │         │  OpenAI   │
-│Adapter │           │   Adapter   │         │  Adapter  │
-│        │           │             │         │           │
-│@google/│           │ @anthropic/ │         │  openai   │
-│genai   │           │ sdk         │         │  SDK      │
-└───┬────┘           └──────┬──────┘         └─────┬─────┘
-    │                       │                      │
-    ▼                       ▼                      ▼
-┌─────────┐          ┌────────────┐         ┌──────────┐
-│ Gemini  │          │  Claude    │         │  OpenAI  │
-│ API     │          │  API       │         │  API     │
-└─────────┘          └────────────┘         └──────────┘
-```
-
-### 2.2.2 계층 구조
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    Application Layer                         │
-│  (GeminiClient, CLI, Tools)                                 │
-├─────────────────────────────────────────────────────────────┤
-│                    Abstraction Layer                         │
-│  (ContentGenerator, LlmTypes, ProviderRegistry)             │
-├─────────────────────────────────────────────────────────────┤
-│                    Adapter Layer                             │
-│  (GeminiAdapter, ClaudeAdapter, OpenAIAdapter)              │
-├─────────────────────────────────────────────────────────────┤
-│                    SDK Layer                                 │
-│  (@google/genai, @anthropic/sdk, openai)                    │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### 2.2.3 새 디렉토리 구조
-
-```
-packages/core/src/
-├── core/
-│   ├── client.ts              # 기존 (수정)
-│   ├── baseLlmClient.ts       # 기존 (수정)
-│   └── contentGenerator.ts    # 기존 → 인터페이스만 유지
-│
-├── providers/                  # 새로 추가
-│   ├── types.ts               # 프로바이더 독립적 타입
-│   ├── registry.ts            # 프로바이더 레지스트리
-│   ├── factory.ts             # 프로바이더 팩토리
-│   │
-│   ├── gemini/                # Gemini 어댑터
-│   │   ├── adapter.ts
-│   │   ├── types.ts
-│   │   ├── models.ts
-│   │   └── features.ts
-│   │
-│   ├── claude/                # Claude 어댑터
-│   │   ├── adapter.ts
-│   │   ├── types.ts
-│   │   ├── models.ts
-│   │   └── features.ts
-│   │
-│   └── openai/                # OpenAI 어댑터
-│       ├── adapter.ts
-│       ├── types.ts
-│       ├── models.ts
-│       └── features.ts
-│
-└── config/
-    ├── models.ts              # 기존 → 리팩토링
-    └── providerConfig.ts      # 새로 추가
-```
-
-## 2.3 핵심 설계 원칙
-
-### 2.3.1 의존성 역전 원칙 (DIP)
-
-```typescript
-// Before: 고수준 모듈이 저수준 모듈에 직접 의존
-import { GoogleGenAI } from '@google/genai';
-
-class GeminiClient {
-  private generator = new GoogleGenAI(apiKey);  // 직접 의존
-}
-
-// After: 추상화에 의존
-import { ContentGenerator } from './providers/types';
-import { ProviderRegistry } from './providers/registry';
-
-class GeminiClient {
-  constructor(private generator: ContentGenerator) {}  // 인터페이스에 의존
-}
-```
-
-### 2.3.2 개방-폐쇄 원칙 (OCP)
-
-```typescript
-// 새 프로바이더 추가 시 기존 코드 수정 없이 확장
-// 1. 새 어댑터 구현
-class LlamaAdapter implements ContentGenerator { ... }
-
-// 2. 레지스트리에 등록
-registry.register('llama', new LlamaAdapter());
-
-// 기존 코드는 변경 없음!
-```
-
-### 2.3.3 단일 책임 원칙 (SRP)
-
-| 컴포넌트 | 책임 |
-|----------|------|
-| `ContentGenerator` | 콘텐츠 생성 인터페이스 정의 |
-| `GeminiAdapter` | Gemini API 호출 및 응답 변환 |
-| `ClaudeAdapter` | Claude API 호출 및 응답 변환 |
-| `ProviderRegistry` | 프로바이더 관리 및 조회 |
-| `ProviderFactory` | 설정 기반 프로바이더 생성 |
-
-## 2.4 프로바이더 선택 흐름
-
-### 2.4.1 초기화 시퀀스
-
-```
-┌──────────────────────────────────────────────────────────┐
-│                     Application Start                     │
-└─────────────────────────┬────────────────────────────────┘
-                          │
-                          ▼
-┌──────────────────────────────────────────────────────────┐
-│                   Load Configuration                      │
-│                                                          │
-│  1. 환경 변수 확인 (LLM_PROVIDER, API keys)               │
-│  2. 설정 파일 로드 (~/.gemini/settings.json)              │
-│  3. 프로젝트 설정 확인 (.gemini/settings.json)            │
-└─────────────────────────┬────────────────────────────────┘
-                          │
-                          ▼
-┌──────────────────────────────────────────────────────────┐
-│              Determine Active Provider                    │
-│                                                          │
-│  Priority:                                               │
-│  1. CLI 인자 (--provider claude)                         │
-│  2. 환경 변수 (LLM_PROVIDER=claude)                      │
-│  3. 프로젝트 설정                                         │
-│  4. 글로벌 설정                                           │
-│  5. 기본값 (gemini)                                       │
-└─────────────────────────┬────────────────────────────────┘
-                          │
-                          ▼
-┌──────────────────────────────────────────────────────────┐
-│                Create Provider Adapter                    │
-│                                                          │
-│  ProviderFactory.create(providerName, config)            │
-└─────────────────────────┬────────────────────────────────┘
-                          │
-                          ▼
-┌──────────────────────────────────────────────────────────┐
-│              Register with ProviderRegistry               │
-│                                                          │
-│  registry.setActive(adapter)                             │
-└─────────────────────────┬────────────────────────────────┘
-                          │
-                          ▼
-┌──────────────────────────────────────────────────────────┐
-│                   Ready for Requests                      │
-└──────────────────────────────────────────────────────────┘
-```
-
-### 2.4.2 요청 처리 흐름
-
-```
-User Prompt
-    │
-    ▼
-┌─────────────┐
-│ GeminiClient│
-└──────┬──────┘
-       │
-       ▼
-┌─────────────────────────────────────┐
-│         ProviderRegistry            │
-│                                     │
-│  getActive() → ContentGenerator     │
-└──────────────────┬──────────────────┘
-                   │
-       ┌───────────┴───────────┐
-       │                       │
-       ▼                       ▼
-┌──────────────┐       ┌──────────────┐
-│ if Gemini    │       │ if Claude    │
-│              │       │              │
-│ GeminiAdapter│       │ClaudeAdapter │
-│     ↓        │       │     ↓        │
-│ Gemini API   │       │ Claude API   │
-└──────────────┘       └──────────────┘
-```
-
-## 2.5 설정 구조
-
-### 2.5.1 환경 변수
-
-```bash
-# 프로바이더 선택
-LLM_PROVIDER=gemini|claude|openai
-
-# Gemini
-GEMINI_API_KEY=your-key
-
-# Claude
-ANTHROPIC_API_KEY=your-key
-
-# OpenAI
-OPENAI_API_KEY=your-key
-```
-
-### 2.5.2 설정 파일 (settings.json)
-
-```json
-{
-  "provider": {
-    "default": "gemini",
-    "gemini": {
-      "model": "gemini-2.5-pro",
-      "apiKey": "${GEMINI_API_KEY}"
-    },
-    "claude": {
-      "model": "claude-sonnet-4-20250514",
-      "apiKey": "${ANTHROPIC_API_KEY}"
-    },
-    "openai": {
-      "model": "gpt-4o",
-      "apiKey": "${OPENAI_API_KEY}"
-    }
-  }
-}
-```
-
-## 2.6 에러 처리 전략
-
-### 2.6.1 프로바이더별 에러 매핑
-
-```typescript
-// 공통 에러 타입
-enum LlmErrorType {
-  RATE_LIMIT = 'rate_limit',
-  AUTHENTICATION = 'authentication',
-  INVALID_REQUEST = 'invalid_request',
-  MODEL_OVERLOADED = 'model_overloaded',
-  CONTEXT_LENGTH_EXCEEDED = 'context_length_exceeded',
-  NETWORK = 'network',
-  UNKNOWN = 'unknown'
-}
-
-// 각 어댑터에서 프로바이더별 에러를 공통 타입으로 변환
-class GeminiAdapter {
-  private mapError(error: GoogleError): LlmError {
-    if (error.code === 429) return new LlmError(LlmErrorType.RATE_LIMIT);
-    // ...
-  }
-}
-```
-
-### 2.6.2 폴백 전략
-
-```typescript
-// 프로바이더 장애 시 대체 프로바이더로 자동 전환 (선택적)
-const fallbackConfig = {
-  primary: 'claude',
-  fallback: ['gemini', 'openai'],
-  maxRetries: 2
-};
-```
-
-## 2.7 호환성 고려사항
-
-### 2.7.1 기능 매핑
-
-| 기능 | Gemini | Claude | OpenAI |
-|------|--------|--------|--------|
-| 텍스트 생성 | ✅ | ✅ | ✅ |
-| 스트리밍 | ✅ | ✅ | ✅ |
-| 도구 호출 | ✅ | ✅ | ✅ |
-| 이미지 입력 | ✅ | ✅ | ✅ |
-| 이미지 생성 | ✅ | ❌ | ✅ (DALL-E) |
-| 임베딩 | ✅ | ❌ | ✅ |
-| 토큰 카운트 | ✅ | ⚠️ (추정) | ✅ |
-| 코드 실행 | ✅ | ❌ | ❌ |
-
-### 2.7.2 기능 가용성 확인
-
-```typescript
-interface ProviderCapabilities {
-  supportsStreaming: boolean;
-  supportsToolCalls: boolean;
-  supportsImageInput: boolean;
-  supportsImageGeneration: boolean;
-  supportsEmbedding: boolean;
-  supportsTokenCount: boolean;
-  maxContextLength: number;
-}
-
-// 사용 예
-if (!provider.capabilities.supportsEmbedding) {
-  throw new UnsupportedFeatureError('Embedding not supported by this provider');
-}
-```