diff --git a/README.md b/README.md
index dc53629..e0e2d00 100644
--- a/README.md
+++ b/README.md
@@ -25,16 +25,16 @@
 
 ## 🚀 Lang2SQL이란?
 
-Lang2SQL은 자연어 쿼리를 최적화된 SQL 문으로 변환하는 오픈소스 도구입니다. LangGraph와 DataHub 통합으로 구축되어, 복잡한 데이터베이스 스키마에 대한 깊은 지식 없이도 데이터 사용자들이 효율적인 SQL 쿼리를 생성할 수 있도록 도와줍니다.
+Lang2SQL은 자연어를 SQL로 변환하는 오픈소스 도구입니다. **define-by-run** 철학에 기반한 모듈러 아키텍처로, 복잡한 데이터베이스 스키마에 대한 깊은 지식 없이도 효율적인 SQL 쿼리를 생성할 수 있도록 도와줍니다.
 
 ### 🎯 주요 기능
 
 - **🗣️ 자연어를 SQL로 변환**: 일상 언어를 정확한 SQL 쿼리로 변환
-- **📊 스마트 테이블 발견**: 의미론적 검색을 사용하여 관련 테이블을 자동으로 찾기
-- **🔍 스키마 인식**: DataHub 메타데이터를 활용한 정확한 컬럼 매핑
-- **🛠️ 웹 인터페이스**: 대화형 Streamlit 앱을 통한 사용
-- **📈 시각화**: 생성된 SQL 쿼리 결과를 다양한 차트와 그래프로 시각화하여 데이터 인사이트를 직관적으로 파악
-- **🗄️ 유연한 VectorDB**: FAISS(로컬)와 pgvector(PostgreSQL) 중 선택 가능한 벡터 데이터베이스 지원
+- **📊 스마트 테이블 발견**: BM25 키워드 검색과 벡터 유사도 검색을 결합한 하이브리드 검색
+- **🔌 Port 기반 확장**: LLM, DB, 임베딩, 벡터스토어를 Protocol 인터페이스로 자유롭게 교체
+- **🛠️ 웹 인터페이스**: Streamlit 기반 대화형 앱 (쿼리 생성 + 챗봇)
+- **📈 시각화**: SQL 쿼리 결과를 차트와 그래프로 시각화
+- **🗄️ 유연한 VectorDB**: InMemory, FAISS(로컬), pgvector(PostgreSQL) 중 선택
 
 ### 🤔 해결하는 문제
 
@@ -59,7 +59,7 @@ Lang2SQL은 자연어 쿼리를 최적화된 SQL 문으로 변환하는 오픈
 # pip
 pip install lang2sql
 
-# uv
+# uv (권장)
 uv venv --python 3.11
 source .venv/bin/activate
 uv add lang2sql
@@ -68,17 +68,15 @@ uv add lang2sql
 ### 소스에서 설치
 
 ```bash
-# 소스 클론
 git clone https://github.com/CausalInferenceLab/lang2sql.git
 cd lang2sql
 
-# (권장) uv 사용
-# uv 설치가 되어 있다면 아래 두 줄로 개발 모드 설치
+# uv (권장)
 uv venv --python 3.11
 source .venv/bin/activate
-uv pip install -e .
+uv sync
 
-# (대안) pip 사용
+# pip
 python -m venv .venv
 source .venv/bin/activate
 pip install -e .
@@ -86,58 +84,97 @@ pip install -e .
 
 ---
 
-## 🛠️ 사용법
+## ⚡ 빠른 시작 (Python API)
+
+```python
+from lang2sql import BaselineNL2SQL
+from lang2sql.integrations.db import SQLAlchemyDB
+from lang2sql.integrations.llm import OpenAILLM
+
+catalog = [
+    {
+        "name": "orders",
+        "description": "고객 주문 정보",
+        "columns": {
+            "order_id": "주문 고유 ID",
+            "customer_id": "고객 ID",
+            "order_date": "주문 일시",
+            "amount": "주문 금액",
+            "status": "주문 상태",
+        },
+    },
+    {
+        "name": "customers",
+        "description": "고객 마스터",
+        "columns": {
+            "customer_id": "고객 ID",
+            "name": "고객 이름",
+            "grade": "고객 등급: bronze / silver / gold",
+        },
+    },
+]
+
+pipeline = BaselineNL2SQL(
+    catalog=catalog,
+    llm=OpenAILLM(model="gpt-4o-mini"),
+    db=SQLAlchemyDB("sqlite:///sample.db"),
+    db_dialect="sqlite",
+)
+
+rows = pipeline.run("지난달 주문 건수를 알려줘")
+print(rows)
+```
 
-### 명령줄 인터페이스
+### 파이프라인 선택 가이드
 
-Streamlit 웹 인터페이스 실행:
+| 파이프라인 | 검색 방식 | 적합한 상황 |
+|---|---|---|
+| `BaselineNL2SQL` | BM25 키워드 | 빠른 시작, 카탈로그 규모 소~중간 |
+| `HybridNL2SQL` | BM25 + Vector | 검색 품질 우선, 비즈니스 문서 활용 |
+| `EnrichedNL2SQL` | BM25 + Vector + Gate | 운영 환경, 부적합 질문 필터링 필요 |
 
-```bash
-lang2sql run-streamlit
-```
+더 자세한 내용은 [튜토리얼](docs/tutorials/01-quickstart.md)을 참고하세요.
 
-사용자 정의 포트로 실행:
+---
 
-```bash
-lang2sql run-streamlit -p 8888
-```
+## 🛠️ 사용법
 
-**참고**: 
-- Streamlit 서버는 `0.0.0.0` 으로 바인딩되어 외부에서 접속 가능합니다.
-- `--datahub_server` 옵션은 더 이상 사용되지 않습니다(deprecated). DataHub 설정은 UI의 설정 > 데이터 소스 탭에서 관리하세요.
+### CLI
 
-### Graph Builder 페이지
+```bash
+# Streamlit 웹 인터페이스 실행
+lang2sql run-streamlit
+lang2sql run-streamlit -p 8888  # 포트 지정
 
-Streamlit 앱은 멀티 페이지 구조입니다. 좌측 네비게이션에서 "Graph Builder" 페이지를 열어 LangGraph 워크플로우를 구성할 수 있습니다.
+# 자연어 쿼리 실행
+lang2sql query "지난달 주문 건수를 집계해줘"
 
-- 프리셋 선택: "기본" 또는 "확장"
-- 커스텀 옵션: `PROFILE_EXTRACTION`, `CONTEXT_ENRICHMENT`, `QUERY_MAKER` 포함 여부 토글
-- 선택이 바뀌면 그래프가 즉시 컴파일되어 세션에 적용됩니다
-- "세션 그래프 새로고침" 버튼으로 수동 재적용 가능
-- `QUERY_MAKER`를 비활성화하면 테이블 검색 정보만 표시됩니다
+# enriched 플로우 (질문 검증 + 프로파일링 + 컨텍스트 보강)
+lang2sql query "이번 달 순매출 합계" --flow enriched --dialect sqlite --top-n 5
 
-### VectorDB 선택
+# QuestionGate 비활성화 (enriched 전용)
+lang2sql query "이번 달 순매출 합계" --flow enriched --no-gate
+```
 
-**참고**: CLI 레벨의 `--vectordb-type` 및 `--vectordb-location` 옵션은 더 이상 사용되지 않습니다(deprecated). Streamlit 실행 시 VectorDB 설정은 UI의 설정 > 데이터 소스 탭에서 관리하세요.
+**CLI 옵션:**
 
-`query` 명령어에서는 VectorDB 옵션을 사용할 수 있습니다:
+| 옵션 | 기본값 | 설명 |
+|------|--------|------|
+| `--flow` | `baseline` | `baseline` 또는 `enriched` |
+| `--dialect` | `None` | SQL 방언 (sqlite, postgresql, mysql, bigquery, duckdb) |
+| `--top-n` | `5` | 검색할 최대 테이블 수 |
+| `--no-gate` | `False` | QuestionGate 비활성화 (enriched 전용) |
 
-```bash
-# FAISS 사용 (기본값)
-lang2sql query "질문" --vectordb-type faiss
+> CLI는 `.env` 파일의 환경변수(`LLM_PROVIDER`, `DB_TYPE` 등)를 읽어 동작합니다. `.env.example`을 참고하세요.
 
-# pgvector 사용
-lang2sql query "질문" --vectordb-type pgvector
+### Streamlit 웹 UI
 
-# 위치 지정 예시
-# FAISS: 인덱스 디렉토리 경로 지정
-lang2sql query "질문" --vectordb-type faiss --vectordb-location ./dev/table_info_db
+Streamlit 앱은 멀티 페이지 구조입니다:
 
-# pgvector: 연결 문자열 지정
-lang2sql query "질문" --vectordb-type pgvector --vectordb-location "postgresql://user:pass@host:5432/db"
-```
-
-참고: DataHub 없이도 미리 준비된 VectorDB(FAISS 파일 혹은 pgvector 컬렉션)를 바로 사용할 수 있습니다. 자세한 준비 방법은 [벡터 검색 튜토리얼](docs/tutorials/03-vector-search.md)을 참고하세요.
+- **🏠 홈** — 프로젝트 소개
+- **🔍 Lang2SQL** — 자연어 쿼리 → SQL 생성 및 실행
+- **🤖 ChatBot** — 멀티턴 대화 기반 SQL 생성
+- **⚙️ 설정** — LLM, DB, 임베딩, 데이터 소스 설정
 
 ### 처음 시작하기
 
@@ -146,120 +183,115 @@ lang2sql query "질문" --vectordb-type pgvector --vectordb-location "postgresql
 | 번호 | 문서 | 내용 |
 |------|------|------|
 | 01 | [빠른 시작](docs/tutorials/01-quickstart.md) | 5분 안에 NL2SQL 실행 |
-| 02 | [Baseline 파이프라인](docs/tutorials/02-baseline.md) | 실제 DB 연결, DB Explorer |
+| 02 | [Baseline 파이프라인](docs/tutorials/02-baseline.md) | 실제 DB 연결, DB Explorer, Factory 함수 |
 | 03 | [벡터 검색](docs/tutorials/03-vector-search.md) | FAISS/pgvector 인덱싱 |
 | 04 | [하이브리드 검색](docs/tutorials/04-hybrid.md) | BM25 + Vector, EnrichedNL2SQL |
-| 05 | [고급](docs/tutorials/05-advanced.md) | 수동 조합, 커스텀 어댑터, Hook |
-
-### 자연어 쿼리 실행
-
-```bash
-# 기본 사용 (FAISS, clickhouse, 기본 검색기)
-lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리"
-
-# 옵션 사용 예시
-lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" \
-  --database-env clickhouse \
-  --retriever-name 기본 \
-  --top-n 5 \
-  --device cpu \
-  --use-enriched-graph \
-  --vectordb-type faiss \
-  --vectordb-location ./dev/table_info_db
-
-# pgvector 사용 예시
-lang2sql query "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리" \
-  --vectordb-type pgvector \
-  --vectordb-location "postgresql://postgres:postgres@localhost:5432/postgres"
-```
-
-**주요 옵션 설명:**
-- `--database-env`: 사용할 데이터베이스 환경 (기본값: clickhouse)
-- `--retriever-name`: 테이블 검색기 이름 (기본값: 기본)
-- `--top-n`: 검색된 상위 테이블 수 제한 (기본값: 5)
-- `--device`: LLM 실행에 사용할 디바이스 (기본값: cpu)
-- `--use-enriched-graph`: 확장된 그래프(프로파일 추출 + 컨텍스트 보강) 사용 여부
-- `--vectordb-type`: 벡터 데이터베이스 타입 ("faiss" 또는 "pgvector", 기본값: faiss)
-- `--vectordb-location`: VectorDB 위치 (FAISS: 디렉토리 경로, pgvector: 연결 문자열)
-
-### 환경 설정
+| 05 | [고급](docs/tutorials/05-advanced.md) | 수동 조합, 커스텀 어댑터, Port 레퍼런스, Hook |
 
-- `.env` 파일을 생성하여 설정을 관리합니다. (예시 파일이 있다면 참조)
-- 또는 CLI 옵션으로 환경을 지정할 수 있습니다:
-  - `--env-file-path`: 환경 변수 파일 경로 지정
-  - `--prompt-dir-path`: 프롬프트 템플릿(.md) 디렉토리 지정
-  - `--datahub_server`: [Deprecated] DataHub GMS 서버 URL 지정. 이제는 UI의 설정 > 데이터 소스 탭에서 관리하세요.
+---
 
 ## 🏗️ 아키텍처
 
-Lang2SQL은 LangGraph를 사용한 다단계 접근 방식을 따릅니다:
-
-1. **📝 자연어 처리**: 사용자 의도 파싱 및 핵심 엔티티 추출
-2. **🔍 테이블 검색**: 의미론적 유사성을 사용한 관련 테이블 찾기 (Vector Search)
-3. **⚙️ SQL 생성**: 최적화된 SQL 쿼리 생성
-4. **🚀 쿼리 시각화**: 쿼리 결과를 시각화 합니다.
+Lang2SQL v2는 **define-by-run** 철학을 따르는 모듈러 아키텍처입니다. 파이프라인 제어는 프레임워크 DSL이 아닌 순수 Python 코드로 작성합니다.
 
----
+```
+src/lang2sql/
+├── core/           # 외부 의존성 0% — 절대 third-party import 금지
+│   ├── base.py     # BaseComponent, BaseFlow
+│   ├── catalog.py  # CatalogEntry, TextDocument, IndexedChunk
+│   ├── ports.py    # LLMPort, DBPort, EmbeddingPort 등 Protocol 인터페이스
+│   ├── hooks.py    # TraceHook, MemoryHook (관측성)
+│   └── exceptions.py
+│
+├── components/     # 재사용 가능한 부품
+│   ├── retrieval/  # KeywordRetriever, VectorRetriever, HybridRetriever
+│   ├── generation/ # SQLGenerator (dialect별 프롬프트)
+│   ├── execution/  # SQLExecutor
+│   ├── gate/       # QuestionGate, TableSuitabilityEvaluator
+│   ├── enrichment/ # QuestionProfiler, ContextEnricher
+│   └── loaders/    # MarkdownLoader, PlainTextLoader, DirectoryLoader
+│
+├── flows/          # 프리셋 파이프라인
+│   ├── nl2sql.py   # BaselineNL2SQL (Keyword → SQL → Execute)
+│   ├── hybrid.py   # HybridNL2SQL (BM25 + Vector)
+│   └── enriched_nl2sql.py  # EnrichedNL2SQL (Gate + Profile + Enrich)
+│
+└── integrations/   # 외부 의존성 구현체
+    ├── llm/        # OpenAI, Anthropic, Azure, Gemini, Bedrock, Ollama, HuggingFace
+    ├── embedding/  # OpenAI, Azure, Gemini, Bedrock, Ollama, HuggingFace
+    ├── db/         # SQLAlchemyDB, SQLAlchemyExplorer
+    ├── vectorstore/ # InMemory, FAISS, pgvector
+    ├── catalog/    # DataHubCatalogLoader
+    ├── loaders/    # PDFLoader
+    └── chunking/   # SemanticChunker
+```
 
-## 🧑‍💻 기술 스택
+### 설계 원칙
 
-- **[LangGraph](https://github.com/langchain-ai/langgraph)**: LLM 워크플로우 오케스트레이션
-- **[DataHub](https://datahubproject.io/)**: 메타데이터 관리 및 활용
-- **[Streamlit](https://streamlit.io/)**: 대화형 웹 인터페이스
+- **`core/`는 외부 의존성 0%**: 모든 third-party 연동은 `integrations/`에서 구현
+- **Port Protocol**: `LLMPort`, `DBPort`, `EmbeddingPort` 등 메서드 시그니처만 맞추면 어떤 구현체든 연결 가능
+- **Hook 기반 관측성**: `MemoryHook`으로 컴포넌트별 실행 시간, 에러를 추적
 
 ---
 
-## 🌟 기여가 필요한 영역 (Help!)
-
-### Containerization
-
-- Docker를 활용하여 프로젝트를 컨테이너화하고, `pip install lang2sql` 설치 후 단일 명령어로 실행 가능하도록 개선합니다.
-- CI/CD 파이프라인 구축 및 자동화된 테스트 환경 구성까지 확장할 수 있는 작업입니다.
+## 🧑‍💻 지원 환경
 
-### Agentic 아키텍처 개발
+### LLM
 
-- 쿼리 생성 과정을 에이전틱하게 개선하여 더욱 지능적이고 자율적인 SQL 생성이 가능하도록 개발합니다.
-- 데이터 디스커버리 기능을 강화하여 사용자가 원하는 데이터를 더 효과적으로 찾을 수 있도록 지원합니다.
+| 프로바이더 | 환경변수 `LLM_PROVIDER` |
+|---|---|
+| OpenAI | `openai` |
+| Anthropic | `anthropic` |
+| Azure OpenAI | `azure` |
+| Google Gemini | `gemini` |
+| AWS Bedrock | `bedrock` |
+| Ollama | `ollama` |
+| HuggingFace | `huggingface` |
 
-### Datahub 통합 강화
+### 데이터베이스
 
-- 현재 Datahub의 Glossary와 쿼리 예시를 코드로 조회하는 기능이 구현되어 있습니다.
-- 이러한 메타데이터를 쿼리 생성 과정에 더욱 긴밀하게 통합하여 컨텍스트 기반의 정확한 SQL 생성을 지원하는 작업입니다.
+SQLite, PostgreSQL, MySQL, MariaDB, DuckDB, ClickHouse, Snowflake, Oracle, BigQuery, Trino, Hive, Crate
 
-### VectorDB 유연성 개선
+### VectorDB
 
-- 현재는 Datahub를 통해 로컬에 FAISS VectorDB를 생성해야만 사용 가능한 구조입니다.
-- 이 결합도를 낮춰서 Datahub 없이도 기존에 준비된 VectorDB만 있으면 바로 활용할 수 있도록 아키텍처를 개선하는 작업입니다.
+| 백엔드 | 영속성 | 권장 규모 |
+|---|---|---|
+| `InMemoryVectorStore` | 없음 | < 50k chunks |
+| `FAISSVectorStore` | 로컬 파일 | < 500k chunks |
+| `PGVectorStore` | PostgreSQL | 500k+ chunks |
 
-### 모니터링 / 로깅 강화
-
-- 프로젝트 사용 패턴과 성능을 모니터링하고, 상세한 로깅 시스템을 구축합니다.
-- 사용자 피드백 수집 및 분석 프로세스를 통해 지속적인 개선이 가능한 기반을 마련하는 작업입니다.
+---
 
-### 문서화 강화
+## 🤝 기여하기
 
-- 프로젝트 기여 장벽을 낮추기 위한 포괄적인 문서화 작업입니다.
-- 개발자 가이드, 튜토리얼 등을 체계적으로 정리하여 새로운 기여자들이 쉽게 참여할 수 있는 환경을 조성합니다.
+커뮤니티의 기여를 환영합니다!
 
-### LLM 프론트에서 분리하기
+### 🔧 개발 환경 설정
 
-프런트에서는 LLM 호출·키를 제거하고 내부 백엔드 API로 위임해 보안·권한·모니터링을 중앙화합니다.
+```bash
+# 1. 저장소 포크 & 클론
+git clone https://github.com/YOUR_USERNAME/lang2sql.git
+cd lang2sql
 
----
+# 2. 의존성 설치
+uv venv --python 3.11
+source .venv/bin/activate
+uv sync --group dev
 
-## 🤝 기여하기
+# 3. 브랜치 생성 (네이밍: feature/이슈번호-작업내용)
+git checkout -b feature/42-amazing-feature
 
-커뮤니티의 기여를 환영합니다! 여러분이 도울 수 있는 방법들:
+# 4. 작업 후 커밋 & PR
+git commit -m "feat: add amazing feature"
+git push origin feature/42-amazing-feature
+```
 
-### 🔧 개발 환경 설정
+### 📋 개발 가이드라인
 
-1. 저장소 포크하기
-2. 포크 클론: `git clone https://github.com/YOUR_USERNAME/lang2sql.git`
-3. 의존성 설치: `pip install -r requirements.txt`
-4. 기능 브랜치 생성: `git checkout -b feature/amazing-feature`
-5. 변경사항 커밋: `git commit -m 'Add amazing feature'`
-6. 브랜치에 푸시: `git push origin feature/amazing-feature`
-7. Pull Request 열기
+- `pre-commit run --all-files`로 포맷팅 확인
+- 새로운 기능에 대한 테스트 작성 (`tests/test_<layer>_<component>.py`)
+- PR은 `master` 브랜치 대상, 최소 2명 리뷰어 승인 필요
+- 커밋 메시지: `feat:`, `fix:`, `docs:`, `refactor:` 등 prefix 사용
 
 ### 🐛 이슈 신고
 
@@ -269,13 +301,6 @@ Lang2SQL은 LangGraph를 사용한 다단계 접근 방식을 따릅니다:
 - 예상 동작 vs 실제 동작
 - 환경 세부사항
 
-### 📋 개발 가이드라인
-
-- pre-commit 활성화
-- 새로운 기능에 대한 테스트 작성
-- 필요시 문서 업데이트
-- 원자적이고 잘 설명된 커밋 유지
-
 ---
 
 ## 🎓 학습 자료
@@ -304,41 +329,30 @@ Lang2SQL은 LangGraph를 사용한 다단계 접근 방식을 따릅니다:
 | **Data Engineer** | 홍지영 | ![Python](https://img.shields.io/badge/Python-Expert-3776AB) | LLM, Data Engineering |
 | **Data Operator** | 이화림 | ![Python](https://img.shields.io/badge/Python-Expert-3776AB) | LLM, Data Engineering |
 
-
-
 ## 🚀 배포 및 릴리스
 
-### 수동 빌드
-
-```bash
-uv build
-UV_PUBLISH_TOKEN=$PYPI_API_TOKEN uv publish --token $UV_PUBLISH_TOKEN
-```
-
 ### 자동 배포(GitHub Actions)
 
-사전 준비: GitHub Secrets에 `PYPI_API_TOKEN` 등록
+`v*` 태그 푸시 시 `.github/workflows/pypi-release.yml`이 실행되어 PyPI에 배포됩니다.
 
 ```bash
-# 1) 버전 업데이트
-#   - 버전 파일: version.py 의 __version__ = "X.Y.Z"
+# 1) 버전 업데이트 (version.py)
 git add version.py
 git commit -m "chore: bump version to X.Y.Z"
 
-# 2) 태그 생성/푸시 (v* 형식이 트리거)
+# 2) 태그 생성/푸시
 git tag vX.Y.Z
 git push origin HEAD
 git push origin vX.Y.Z
 ```
 
-설명: `v*` 태그가 푸시되면 `.github/workflows/pypi-release.yml`이 실행되어 uv로 빌드/배포합니다.
+사전 준비: GitHub Secrets에 `PYPI_API_TOKEN` 등록
 
-### TestPyPI로 사전 검증(선택)
+### 수동 빌드
 
 ```bash
 uv build
-UV_PUBLISH_TOKEN=$TEST_PYPI_API_TOKEN \
-  uv publish --repository-url https://test.pypi.org/legacy/ --token $UV_PUBLISH_TOKEN
+UV_PUBLISH_TOKEN=$PYPI_API_TOKEN uv publish --token $UV_PUBLISH_TOKEN
 ```
 
 ---