Skip to content

Commit 9c88519

Browse files
ehddnr301ehddnr301
committed
docs: Revamp README with comprehensive project overview and enhanced documentation
1 parent 877eb31 commit 9c88519

File tree

2 files changed

+257
-63
lines changed

2 files changed

+257
-63
lines changed

‎README.md

Lines changed: 158 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,99 +1,194 @@
1-
# Lang2SQL
1+
<h1 align="center"> Lang2SQL </h1>
22

3-
Lang2SQL은 자연어 입력을 기반으로 SQL을 생성하는 프로젝트입니다. LangGraph, DataHub를 활용하여 데이터를 분석하고 최적의 SQL 쿼리를 생성 및 최적화합니다.
3+
<div align="center">
4+
<a href="https://pseudo-lab.com"><img src="https://img.shields.io/badge/PseudoLab-S10-3776AB" alt="PseudoLab"/></a>
5+
<a href="https://discord.gg/EPurkHVtp2"><img src="https://img.shields.io/badge/Discord-BF40BF" alt="Discord Community"/></a>
6+
<a href="https://github.com/CausalInferenceLab/lang2sql/stargazers"><img src="https://img.shields.io/github/stars/CausalInferenceLab/lang2sql" alt="Stars Badge"/></a>
7+
<a href="https://github.com/CausalInferenceLab/lang2sql/network/members"><img src="https://img.shields.io/github/forks/CausalInferenceLab/lang2sql" alt="Forks Badge"/></a>
8+
<a href="https://github.com/CausalInferenceLab/lang2sql/pulls"><img src="https://img.shields.io/github/issues-pr/CausalInferenceLab/lang2sql" alt="Pull Requests Badge"/></a>
9+
<a href="https://github.com/CausalInferenceLab/lang2sql/issues"><img src="https://img.shields.io/github/issues/CausalInferenceLab/lang2sql" alt="Issues Badge"/></a>
10+
<a href="https://github.com/CausalInferenceLab/lang2sql/graphs/contributors"><img alt="GitHub contributors" src="https://img.shields.io/github/contributors/CausalInferenceLab/lang2sql?color=2b9348"></a>
11+
<a href="https://hits.seeyoufarm.com"><img src="https://hits.seeyoufarm.com/api/count/incr/badge.svg?url=https%3A%2F%2Fgithub.com%2FCausalInferenceLab%2Flang2sql&count_bg=%2379C83D&title_bg=%23555555&icon=&icon_color=%23E7E7E7&title=hits&edge_flat=false"/></a>
12+
</div>
13+
<br>
414

5-
## 📌 프로젝트 목표
6-
1. 자연어 입력을 기반으로 SQL 쿼리를 자동으로 생성
7-
2. DataHub를 활용하여 관련 테이블 및 컬럼 메타데이터 조회
8-
3. Best Practice Query를 참고하여 최적의 SQL 생성
9-
4. SQL 최적화 과정을 거쳐 성능 향상
15+
<!-- sheilds: https://shields.io/ -->
16+
<!-- hits badge: https://hits.seeyoufarm.com/ -->
1017

11-
---
18+
> "우리는 함께 코드와 아이디어를 나누며 더 나은 데이터 환경을 만들기 위한 오픈소스 여정을 떠납니다. 🌍💡"
1219
13-
## 🚀 기술 스택
14-
- **LangGraph**: LLM 기반의 쿼리 생성
15-
- **DataHub**: 테이블 및 컬럼 메타데이터 조회
1620

17-
---
21+
## 프로젝트 개요 (Project Overview)
1822

19-
## 📦 설치 방법
2023

21-
### 1️⃣ 필수 패키지 설치
24+
`🚀 신입이 SQL을 두려워하지 않도록`
2225

23-
```bash
24-
pip install -r requirements.txt
25-
```
26+
🤔 처음 데이터팀에 합류하면 가장 먼저 마주하는 고민들:
27+
- 🤯 "테이블이 너무 많아! 뭐부터 봐야 하지?"
28+
- 🧐 "조인은 이렇게 걸어도 되나?"
29+
- 🐌 "이 SQL, 성능 괜찮을까?"
30+
- 😰 "어떻게 쿼리해야 인사이트를 얻을 수 있을까?"
2631

27-
### 2️⃣ 패키지 설치
32+
💡 Lang2SQL로 해결해 봅시다.
33+
- ✅ 자연어 입력 → 적절한 테이블 추천
34+
- ✅ 올바른 컬럼 조합으로 SQL 자동 생성
35+
- ✅ Best Practice 기반 자동 성능 최적화
2836

29-
`setup.py`를 통해 패키지를 설치할 수 있습니다:
37+
🚀 우리는 SQL을 더 쉽게, 더 빠르게, 더 효율적으로 만들 것입니다.
3038

31-
```bash
32-
python setup.py install
33-
```
39+
🌍 그리고, 우리는 오픈소스라는 무한한 가능성의 바다로 항해합니다.
3440

35-
### 3️⃣ CLI 명령어 사용
41+
## 🌟 프로젝트 목표 (Project Vision)
42+
### _"박치기공룡들의 배포부터 시작하는 프로젝트"_
43+
#### [lang2sql](https://pypi.org/project/lang2sql/) 패키지 1.0.0 달성하기
44+
- 더 이상 실험적인(beta, alpha) 상태가 아니며, 정식 릴리스(Stable Release)임을 뜻합니다.
45+
#### LangGraph 기반 쿼리 생성: 단순한 SQL 생성이 아닌, 최적화된 SQL 제공을 목표로 합니다.
46+
- 자연어(NL) 입력을 기반으로 의미론적으로 최적화된 SQL 생성
47+
- 사내 Best Practice SQL을 통한 성능 향상
48+
#### 오픈소스 협업: 더 많은 사람들이 참여할 수 있도록, 코드와 아이디어를 GitHub으로 공유합니다.
49+
- 이 오픈소스 프로젝트는 전세계 개발자들과 함께 협업하는것을 목표로 합니다.
3650

37-
설치 후, `lang2sql` 명령어를 사용할 수 있습니다. 예를 들어, Streamlit 앱을 실행하려면 다음과 같이 입력합니다:
51+
## 🧑 역동적인 팀 소개 (Dynamic Team)
3852

39-
```bash
40-
lang2sql --run-streamlit
41-
```
53+
| 역할 | 이름 | 기술 스택 배지 | 주요 관심 분야 |
54+
|---------------|------|-----------------------------------------------------------------------|----------------------------------------|
55+
| **Project Manager** | 이동욱 | ![Python](https://img.shields.io/badge/Python-Expert-3776AB) | LLM 오픈소스 인과추론 |
4256

43-
기본 포트는 8501이며, 다른 포트를 사용하려면 `-p` 옵션을 사용하세요:
4457

45-
```bash
46-
lang2sql --run-streamlit -p 8502
47-
```
58+
## 🚀 프로젝트 로드맵 (Project Roadmap)
59+
```mermaid
60+
gantt
61+
title 2025 프로젝트 여정
62+
63+
section 프로젝트 준비
64+
OT - 프로젝트 이해도 Sync-Up / Issue 하나 생성하기 :a1, 2025-03-03, 7d
4865
49-
DataHub GMS 서버 URL을 설정하려면 `--datahub_server` 옵션을 사용하세요. 기본값은 `http://localhost:8080`입니다:
66+
section Table Retrieval 최적화
67+
Table Retrieval 최적화 (1) :a2, 2025-03-10, 7d
68+
Table Retrieval 최적화 (2) :a3, 2025-03-17, 7d
69+
70+
section 휴식 및 리프레시
71+
Magical Week 휴식 (1) :break1, 2025-03-24, 7d
5072
51-
```bash
52-
lang2sql --datahub_server http://your-datahub-server:8080 --run-streamlit
53-
```
73+
section SQL Generation
74+
SQL Generation (1) :a4, 2025-03-31, 7d
75+
SQL Generation (2) :a5, 2025-04-07, 7d
76+
77+
section SQL Optimization
78+
SQL Optimization :a6, 2025-04-14, 7d
5479
55-
### 4️⃣ 환경 변수 설정
80+
section 중간 점검 및 조정
81+
중간점검 :a7, 2025-04-21, 7d
5682
57-
다음 환경 변수들은 설정되어야 합니다. `.env` 파일을 생성하여 다음과 같이 관리할 수 있습니다:
83+
section 휴식 및 리프레시
84+
Magical Week 휴식 (2) :break2, 2025-04-28, 7d
5885
86+
section Dockerization
87+
Dockerize (1) :a8, 2025-05-05, 7d
88+
Dockerize (2) :a9, 2025-05-12, 7d
89+
90+
section 오픈소스화
91+
오픈소스화 작업 (1) :a10, 2025-05-19, 7d
92+
오픈소스화 작업 (2) :a11, 2025-05-26, 7d
5993
```
60-
OPENAI_API_KEY=your-api-key-here
61-
LANGCHAIN_TRACING_V2=true
62-
LANGCHAIN_PROJECT=autosql
63-
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
64-
LANGCHAIN_API_KEY=your-langchain-api-key
65-
DATAHUB_SERVER=http://localhost:8080
94+
95+
96+
## 🛠️ 우리의 개발 문화 (Our Development Culture)
97+
**우리의 개발 문화**
98+
```python
99+
class CollaborationFramework:
100+
def __init__(self):
101+
self.tools = {
102+
'communication': 'Discord',
103+
'version_control': 'GitHub Projects',
104+
'ci/cd': 'GitHub Actions',
105+
'docs': 'Github Wiki'
106+
}
107+
108+
def workflow(self):
109+
return """주간 사이클:
110+
1️⃣ 월요일: 코드 리뷰 세션 & 주간목표 설정 (Live Share)
111+
3️⃣ 금요일: 진행상황 체크 (logging)
66112
```
67113
68-
---
69114
70-
## 🎯 동작
115+
## 📈 성과 지표 (Achievement Metrics)
116+
**2025 주요 KPI**
117+
| 지표 | 목표치 | 현재 달성률 |
118+
|--------------------------|--------|-------------|
119+
| 커밋 수 | 100 | 0% |
120+
| 배포 버전 1.0.0 달성 | 1.0.0 | 16% |
71121
72-
1. **자연어 입력을 기반으로 테이블 조회**
73-
2. **테이블의 스키마 및 컬럼 정보 확인**
74-
3. **최적의 SQL 쿼리 생성**
75-
4. **쿼리 최적화 실행**
76122
77-
---
123+
## 💻 주차별 활동 (Activity History)
78124
79-
## 빌드 및 배포 방법
125+
| 날짜 | 내용 | 발표자 |
126+
| -------- | -------- | ---- |
127+
| 2025/03/03 | OT - 프로젝트 이해도 Sync-Up / Issue 하나 생성하기 | 이동욱 |
128+
| 2025/03/10 | 🔍 Table Retrieval 최적화 🔍 | 미정 |
129+
| 2025/03/17 | 🔍 Table Retrieval 최적화 🔍 | 미정 |
130+
| 2025/03/24 | ✨ Magical Week 휴식 ✨| 미정 |
131+
| 2025/03/29 | ✨ 인과추론팀 행사 참여 ✨| 미정 |
132+
| 2025/03/31 | ✏️ SQL Generation ✏️ | 미정 |
133+
| 2025/04/07 | ✏️ SQL Generation ✏️ | 미정 |
134+
| 2025/04/14 | ⚡ SQL Optimization ⚡ | 미정 |
135+
| 2025/04/21 | ✨ 중간점검 ✨ | 미정 |
136+
| 2025/04/28 | ✨ Magical Week 휴식 ✨ | 미정 |
137+
| 2025/05/05 | 🛠️ Dockerize 🛠️ | 미정 |
138+
| 2025/05/12 | 🛠️ Dockerize 🛠️ | 미정 |
139+
| 2025/05/19 | 📖 오픈소스화 작업 📖 | 미정 |
140+
| 2025/05/26 | 📖 오픈소스화 작업 📖 | 미정 |
80141
81-
### 수동 빌드
142+
_"본 계획표는 예시이며, 프로젝트의 방향성을 유지하면서 자유롭게 기여하는 것을 목표로 합니다."_
82143
83-
```
84-
python setup.py sdist bdist_wheel
85-
twine upload dist/*
86-
```
144+
## 💡 학습 자원 (Learning Resources)
145+
146+
- [모두를 위한 게임 데이터 검색 시스템 / if(kakaoAI)2024](https://www.youtube.com/watch?v=8-GerpWVMis&ab_channel=kakaotech)
147+
- [AI 데이터 분석가 ‘물어보새’ 등장 – 1부. RAG와 Text-To-SQL 활용](https://techblog.woowahan.com/18144/)
148+
- [테디노트 LangGraph](https://wikidocs.net/233785)
149+
- [DataHub 설명](https://datahubproject.io/)
150+
- [vanna.ai](https://github.com/vanna-ai/vanna)
151+
152+
## 🌱 참여 안내 (How to Engage)
153+
154+
### 🎯 우리가 함께 얻어갈 점 (What We’ll Gain)
155+
_"이 스터디에 참여하면서, 여러분이 얻어갈 수 있는 것은 단순한 코드 경험 그 이상입니다."_
156+
157+
- 🔥 오픈소스 기여 경험 – GitHub에서 이슈 관리, PR 작성, 리뷰 등 협업을 경험합니다.
158+
- 🔥 배포 경험 (PyPI & 오픈소스 배포) – lang2sql 패키지를 개발하며 직접 PyPI 패키지를 배포하는 경험을 가질 수 있습니다.
159+
- 🔥 실무 적용 – 본 프로젝트는 완성도를 높여 실무 환경에 적용 예정입니다. ${\textsf{\color{YellowOrange}사이드 프로젝트로 머물지 않습니다.}}$
160+
161+
### 🔍 원하는 팀원 (Who We're Looking For)
162+
_"함께 성장하고, 오픈소스 문화를 즐길 수 있는 팀원을 찾고 있습니다!"_
163+
164+
- **✅ 3개월 동안 꾸준히 참여할 수 있는 의지를 가지신 분**
165+
- ✅ 오픈소스 협업에 관심이 있으신분
166+
- ✅ 최소 주 1회 의미있는 프로젝트 기여 가능하신분 (Issue 생성, 코드기여, 문서화 등등)
167+
168+
### 🤗 비고
169+
170+
**팀원으로 참여하시려면 러너 모집 기간에 신청해주세요.**
171+
- 링크 (준비중)
172+
173+
**누구나 청강을 통해 모임을 참여하실 수 있습니다.**
174+
1. 특별한 신청 없이 정기 모임 시간에 맞추어 디스코드 #Room-GH 채널로 입장
175+
2. Magical Week 중 행사에 참가
176+
3. Pseudo Lab 행사에서 만나기
177+
178+
## Acknowledgement 🙏
87179
88-
### GitHub Actions를 통한 자동 배포
180+
Lang2SQL is developed as part of Pseudo-Lab's Open Research Initiative. Special thanks to our contributors and the open source community for their valuable insights and contributions.
89181
90-
GitHub 저장소에 태그를 `v*` 형식으로 푸시하면, GitHub Actions가 자동으로 PyPI에 패키지를 배포합니다. 이 과정은 `.github/workflows/pypi-release.yml` 파일에 정의되어 있습니다.
182+
## About Pseudo Lab 👋🏼</h2>
91183
92-
- **태그 형식**: `v1.0.0` 등
93-
- **필요한 설정**: GitHub Secrets에 `PYPI_API_TOKEN`을 설정해야 합니다.
184+
[Pseudo-Lab](https://pseudo-lab.com/) is a non-profit organization focused on advancing machine learning and AI technologies. Our core values of Sharing, Motivation, and Collaborative Joy drive us to create impactful open-source projects. With over 5k+ researchers, we are committed to advancing machine learning and AI technologies.
94185
95-
---
186+
<h2>Contributors 😃</h2>
187+
<a href="https://github.com/Pseudo-Lab/lang2sql/graphs/contributors">
188+
<img src="https://contrib.rocks/image?repo=Pseudo-Lab/lang2sql" />
189+
</a>
190+
<br><br>
96191
97-
## 라이선스
98-
MIT License
192+
<h2>License 🗞</h2>
99193
194+
This project is licensed under the [MIT License](https://opensource.org/licenses/MIT).

‎docs/README.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,99 @@
1+
# Lang2SQL
2+
3+
Lang2SQL은 자연어 입력을 기반으로 SQL을 생성하는 프로젝트입니다. LangGraph, DataHub를 활용하여 데이터를 분석하고 최적의 SQL 쿼리를 생성 및 최적화합니다.
4+
5+
## 📌 프로젝트 목표
6+
1. 자연어 입력을 기반으로 SQL 쿼리를 자동으로 생성
7+
2. DataHub를 활용하여 관련 테이블 및 컬럼 메타데이터 조회
8+
3. Best Practice Query를 참고하여 최적의 SQL 생성
9+
4. SQL 최적화 과정을 거쳐 성능 향상
10+
11+
---
12+
13+
## 🚀 기술 스택
14+
- **LangGraph**: LLM 기반의 쿼리 생성
15+
- **DataHub**: 테이블 및 컬럼 메타데이터 조회
16+
17+
---
18+
19+
## 📦 설치 방법
20+
21+
### 1️⃣ 필수 패키지 설치
22+
23+
```bash
24+
pip install -r requirements.txt
25+
```
26+
27+
### 2️⃣ 패키지 설치
28+
29+
`setup.py`를 통해 패키지를 설치할 수 있습니다:
30+
31+
```bash
32+
python setup.py install
33+
```
34+
35+
### 3️⃣ CLI 명령어 사용
36+
37+
설치 후, `lang2sql` 명령어를 사용할 수 있습니다. 예를 들어, Streamlit 앱을 실행하려면 다음과 같이 입력합니다:
38+
39+
```bash
40+
lang2sql --run-streamlit
41+
```
42+
43+
기본 포트는 8501이며, 다른 포트를 사용하려면 `-p` 옵션을 사용하세요:
44+
45+
```bash
46+
lang2sql --run-streamlit -p 8502
47+
```
48+
49+
DataHub GMS 서버 URL을 설정하려면 `--datahub_server` 옵션을 사용하세요. 기본값은 `http://localhost:8080`입니다:
50+
51+
```bash
52+
lang2sql --datahub_server http://your-datahub-server:8080 --run-streamlit
53+
```
54+
55+
### 4️⃣ 환경 변수 설정
56+
57+
다음 환경 변수들은 설정되어야 합니다. `.env` 파일을 생성하여 다음과 같이 관리할 수 있습니다:
58+
59+
```
60+
OPENAI_API_KEY=your-api-key-here
61+
LANGCHAIN_TRACING_V2=true
62+
LANGCHAIN_PROJECT=autosql
63+
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
64+
LANGCHAIN_API_KEY=your-langchain-api-key
65+
DATAHUB_SERVER=http://localhost:8080
66+
```
67+
68+
---
69+
70+
## 🎯 동작
71+
72+
1. **자연어 입력을 기반으로 테이블 조회**
73+
2. **테이블의 스키마 및 컬럼 정보 확인**
74+
3. **최적의 SQL 쿼리 생성**
75+
4. **쿼리 최적화 실행**
76+
77+
---
78+
79+
## 빌드 및 배포 방법
80+
81+
### 수동 빌드
82+
83+
```
84+
python setup.py sdist bdist_wheel
85+
twine upload dist/*
86+
```
87+
88+
### GitHub Actions를 통한 자동 배포
89+
90+
GitHub 저장소에 태그를 `v*` 형식으로 푸시하면, GitHub Actions가 자동으로 PyPI에 패키지를 배포합니다. 이 과정은 `.github/workflows/pypi-release.yml` 파일에 정의되어 있습니다.
91+
92+
- **태그 형식**: `v1.0.0` 등
93+
- **필요한 설정**: GitHub Secrets에 `PYPI_API_TOKEN`을 설정해야 합니다.
94+
95+
---
96+
97+
## 라이선스
98+
MIT License
99+

0 commit comments

Comments
 (0)