shinalok
cd41e9e33e
- **Implement `MlxModelService` for local LLM backend.** - **Introduce `DatabaseService` for MySQL integration.** - **Add `HistoryService` to manage conversation context.** - **Set up CLI interface via `CliUiService`.** - **Establish EventBus for token streaming.** - **Include conversation repository for data persistence.** - **Add environment-based configuration management.** - **Draft IoC architectural plan.**
156 lines
5.7 KiB
Markdown
156 lines
5.7 KiB
Markdown
---
|
|
template: plan
|
|
version: 1.3
|
|
feature: ioc-base-structure
|
|
date: 2026-04-24
|
|
author: sal
|
|
project: youlbot
|
|
status: Draft
|
|
---
|
|
|
|
# ioc-base-structure Planning Document
|
|
|
|
> **Summary**: 절차형 chat.py를 IoC 컨테이너 기반 클래스 구조로 리팩토링하여 재사용성과 확장성을 확보한다.
|
|
>
|
|
> **Project**: youlbot
|
|
> **Author**: sal
|
|
> **Date**: 2026-04-24
|
|
> **Status**: Draft
|
|
|
|
---
|
|
|
|
## Executive Summary
|
|
|
|
| Perspective | Content |
|
|
|-------------|---------|
|
|
| **Problem** | 단일 파일 절차형 스크립트로 서비스 교체·테스트·확장이 어렵다 |
|
|
| **Solution** | dependency-injector 기반 IoC 컨테이너로 서비스 분리 및 DI 적용 |
|
|
| **Function/UX Effect** | LLM 백엔드 교체(MLX↔OpenAI↔Ollama) 및 DB 연동이 코드 변경 없이 가능 |
|
|
| **Core Value** | 재사용 가능한 서비스 계층 + 디자인 패턴 적용으로 장기 유지보수성 확보 |
|
|
|
|
---
|
|
|
|
## Context Anchor
|
|
|
|
| Key | Value |
|
|
|-----|-------|
|
|
| **WHY** | 절차형 코드의 결합도를 낮춰 기능 추가·교체를 안전하게 하기 위함 |
|
|
| **WHO** | 개발자 (sal) — 단독 개발, 추후 팀 확장 가능성 있음 |
|
|
| **RISK** | MLX 모델 로딩이 무거워 Singleton 관리 실수 시 메모리 이슈 |
|
|
| **SUCCESS** | 각 서비스가 독립적으로 교체/테스트 가능하고 Container 설정만으로 행동 변경 |
|
|
| **SCOPE** | Phase 1: 기본 구조 + MLX 서비스 / Phase 2: DB(MySQL) 연동 |
|
|
|
|
---
|
|
|
|
## 1. Overview
|
|
|
|
### 1.1 Purpose
|
|
현재 `chat.py`는 모델 로딩, 히스토리 관리, 스트림 생성, CLI 루프가 한 파일에 혼재한다.
|
|
IoC 컨테이너와 디자인 패턴을 적용해 각 책임을 분리하고, 의존성을 주입으로 연결한다.
|
|
|
|
### 1.2 Background
|
|
- 육아·금융 상담 챗봇 '율봇'의 초기 구조 정립
|
|
- LLM 백엔드를 MLX로 시작하되 OpenAI / Ollama 전환이 설정 변경만으로 가능해야 함
|
|
- MySQL DB 연동이 예정되어 있어 DB 서비스 레이어 선제 설계 필요
|
|
|
|
---
|
|
|
|
## 2. Scope
|
|
|
|
### 2.1 In Scope
|
|
- [ ] IoC Container 설정 (`app/container.py`)
|
|
- [ ] Strategy 패턴으로 LLM 백엔드 추상화 (`AbstractModelService` + `MlxModelService`)
|
|
- [ ] `ChatService` — 대화 오케스트레이션
|
|
- [ ] `HistoryService` — 히스토리 관리 (trim 포함)
|
|
- [ ] `DatabaseService` — MySQL 연결 (mysqlclient)
|
|
- [ ] Observer/EventBus — 스트림 토큰 이벤트 발행
|
|
- [ ] `CliUiService` — CLI 입출력
|
|
- [ ] `main.py` — 컨테이너 부트스트랩 진입점
|
|
- [ ] `config.py` — 환경변수 기반 설정
|
|
|
|
### 2.2 Out of Scope
|
|
- 웹 API (FastAPI 등) 레이어
|
|
- 인증/세션 관리
|
|
- 테스트 코드 (별도 Phase)
|
|
|
|
---
|
|
|
|
## 3. Requirements
|
|
|
|
### 3.1 Functional Requirements
|
|
|
|
| ID | Requirement | Priority |
|
|
|----|-------------|----------|
|
|
| FR-01 | IoC Container에서 모든 서비스를 Singleton/Factory로 등록·해석 | High |
|
|
| FR-02 | LLM 백엔드를 Strategy 인터페이스로 추상화, 구현체 교체 가능 | High |
|
|
| FR-03 | ChatService가 HistoryService·ModelService·EventBus를 주입받아 동작 | High |
|
|
| FR-04 | 스트림 토큰 출력을 Observer 패턴으로 처리 (핸들러 교체 가능) | Medium |
|
|
| FR-05 | DatabaseService가 MySQL 연결을 캡슐화, 다른 서비스에서 주입받아 사용 | Medium |
|
|
| FR-06 | 설정은 환경변수 + config.py에서 중앙 관리 | High |
|
|
|
|
### 3.2 Non-Functional Requirements
|
|
|
|
| Category | Criteria |
|
|
|----------|----------|
|
|
| 확장성 | 새 LLM 백엔드 추가 시 AbstractModelService 구현만으로 완성 |
|
|
| 결합도 | 서비스 간 직접 import 없이 Container 통해서만 의존 |
|
|
| 메모리 | MLX 모델은 Singleton으로 1회만 로딩 |
|
|
|
|
---
|
|
|
|
## 4. Success Criteria
|
|
|
|
- [ ] `python -m app.main` 실행 시 기존 chat.py와 동일하게 동작
|
|
- [ ] `MlxModelService`를 `MockModelService`로 교체해도 나머지 코드 변경 없음
|
|
- [ ] `Container` 설정만 바꿔서 CLI → 다른 UI로 전환 가능한 구조
|
|
|
|
---
|
|
|
|
## 5. Risks
|
|
|
|
| Risk | Impact | Likelihood | Mitigation |
|
|
|------|--------|------------|------------|
|
|
| MLX Singleton 초기화 시간 (~수초) | Medium | High | 로딩 중 진행 표시 유지 |
|
|
| dependency-injector 버전 충돌 | Low | Low | requirements.txt 버전 고정 |
|
|
| MySQL 연결 설정 누락 | Medium | Medium | 미설정 시 graceful skip |
|
|
|
|
---
|
|
|
|
## 6. Architecture Decisions
|
|
|
|
| Decision | Selected | Rationale |
|
|
|----------|----------|-----------|
|
|
| IoC 라이브러리 | dependency-injector | DeclarativeContainer, Singleton/Factory 지원 |
|
|
| LLM 추상화 | Strategy 패턴 | 백엔드 교체 시 코드 변경 최소화 |
|
|
| 스트림 처리 | Observer/EventBus | 출력 핸들러(CLI, 파일, WebSocket)를 분리 |
|
|
| DB | MySQL (mysqlclient) | 단순 Service로 캡슐화, 추후 ORM 추가 가능 |
|
|
|
|
---
|
|
|
|
## 7. Directory Structure
|
|
|
|
```
|
|
youlbot/
|
|
├── app/
|
|
│ ├── __init__.py
|
|
│ ├── config.py # 환경변수 기반 설정
|
|
│ ├── container.py # IoC DeclarativeContainer
|
|
│ ├── main.py # 부트스트랩 진입점
|
|
│ └── services/
|
|
│ ├── model/
|
|
│ │ ├── base.py # AbstractModelService (Strategy 인터페이스)
|
|
│ │ └── mlx_model.py # MlxModelService (Strategy 구현체)
|
|
│ ├── chat/
|
|
│ │ ├── chat_service.py
|
|
│ │ └── history_service.py
|
|
│ ├── db/
|
|
│ │ └── mysql_service.py
|
|
│ ├── ui/
|
|
│ │ └── cli_service.py
|
|
│ └── events/
|
|
│ ├── event_bus.py # Observer EventBus
|
|
│ └── handlers.py # StreamTokenHandler 등
|
|
├── chat.py # 기존 파일 (보존)
|
|
└── requirements.txt
|
|
```
|