text2sql-eval 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. text2sql_eval-0.1.0/LICENSE +25 -0
  2. text2sql_eval-0.1.0/PKG-INFO +176 -0
  3. text2sql_eval-0.1.0/README.md +148 -0
  4. text2sql_eval-0.1.0/pyproject.toml +82 -0
  5. text2sql_eval-0.1.0/pyproject.toml.orig +70 -0
  6. text2sql_eval-0.1.0/src/text2sql_eval/__init__.py +101 -0
  7. text2sql_eval-0.1.0/src/text2sql_eval/cli/__init__.py +1 -0
  8. text2sql_eval-0.1.0/src/text2sql_eval/cli/main.py +482 -0
  9. text2sql_eval-0.1.0/src/text2sql_eval/compare/__init__.py +1 -0
  10. text2sql_eval-0.1.0/src/text2sql_eval/compare/runs.py +205 -0
  11. text2sql_eval-0.1.0/src/text2sql_eval/csv_safety.py +32 -0
  12. text2sql_eval-0.1.0/src/text2sql_eval/datasets/__init__.py +5 -0
  13. text2sql_eval-0.1.0/src/text2sql_eval/datasets/_json.py +73 -0
  14. text2sql_eval-0.1.0/src/text2sql_eval/datasets/bird.py +187 -0
  15. text2sql_eval-0.1.0/src/text2sql_eval/datasets/predictions.py +187 -0
  16. text2sql_eval-0.1.0/src/text2sql_eval/errors.py +43 -0
  17. text2sql_eval-0.1.0/src/text2sql_eval/evaluate.py +268 -0
  18. text2sql_eval-0.1.0/src/text2sql_eval/execution/__init__.py +5 -0
  19. text2sql_eval-0.1.0/src/text2sql_eval/execution/executor.py +162 -0
  20. text2sql_eval-0.1.0/src/text2sql_eval/facts/__init__.py +24 -0
  21. text2sql_eval-0.1.0/src/text2sql_eval/facts/output.py +204 -0
  22. text2sql_eval-0.1.0/src/text2sql_eval/facts/structure.py +299 -0
  23. text2sql_eval-0.1.0/src/text2sql_eval/judge/__init__.py +5 -0
  24. text2sql_eval-0.1.0/src/text2sql_eval/judge/ex.py +179 -0
  25. text2sql_eval-0.1.0/src/text2sql_eval/py.typed +0 -0
  26. text2sql_eval-0.1.0/src/text2sql_eval/report/__init__.py +4 -0
  27. text2sql_eval-0.1.0/src/text2sql_eval/report/csv_report.py +81 -0
  28. text2sql_eval-0.1.0/src/text2sql_eval/report/highlight.py +238 -0
  29. text2sql_eval-0.1.0/src/text2sql_eval/report/html_report.py +595 -0
  30. text2sql_eval-0.1.0/src/text2sql_eval/report/templates/report.html.j2 +284 -0
  31. text2sql_eval-0.1.0/src/text2sql_eval/runfile.py +585 -0
@@ -0,0 +1,25 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 cheolkim02
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
23
+ The example data under examples/bird-mini/ is not covered by this license.
24
+ It is a subset of the BIRD benchmark, distributed under CC BY-SA 4.0;
25
+ see examples/bird-mini/LICENSE.
@@ -0,0 +1,176 @@
1
+ Metadata-Version: 2.4
2
+ Name: text2sql-eval
3
+ Version: 0.1.0
4
+ Summary: Deterministic, evidence-backed error analysis and run comparison for text-to-SQL experiments
5
+ Keywords: text-to-sql,nl2sql,evaluation,error-analysis,bird
6
+ Author: cheolkim02
7
+ License-Expression: MIT
8
+ License-File: LICENSE
9
+ Classifier: Development Status :: 3 - Alpha
10
+ Classifier: Intended Audience :: Science/Research
11
+ Classifier: Programming Language :: Python :: 3
12
+ Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Programming Language :: Python :: 3.11
14
+ Classifier: Programming Language :: Python :: 3.12
15
+ Classifier: Programming Language :: Python :: 3.13
16
+ Classifier: Programming Language :: Python :: 3.14
17
+ Classifier: Programming Language :: Python :: 3.15
18
+ Classifier: Topic :: Database
19
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
20
+ Classifier: Typing :: Typed
21
+ Requires-Dist: jinja2>=3.1.6
22
+ Requires-Dist: sqlglot>=30.31.0
23
+ Requires-Python: >=3.11
24
+ Project-URL: Repository, https://github.com/cheolkim02/text2sql-eval
25
+ Project-URL: Documentation, https://github.com/cheolkim02/text2sql-eval/tree/main/docs
26
+ Project-URL: Issues, https://github.com/cheolkim02/text2sql-eval/issues
27
+ Description-Content-Type: text/markdown
28
+
29
+ # text2sql-eval
30
+
31
+ [![CI](https://github.com/cheolkim02/text2sql-eval/actions/workflows/ci.yml/badge.svg)](https://github.com/cheolkim02/text2sql-eval/actions/workflows/ci.yml)
32
+
33
+ **English summary.** `text2sql-eval` is a Python library and CLI for the error analysis of text-to-SQL experiments. Given a BIRD-style dataset, SQLite databases and a file of predicted SQL, it judges execution accuracy (EX) exactly like BIRD's official script; on the bundled example its numbers match the official script to two decimals. It then explains every wrong case without using an LLM: how the executed results differ, and where the SQL differs, with evidence. It flags verdicts that the official rule may get wrong, such as an answer that returns every gold row plus an extra column. It also compares two runs case by case and writes an offline HTML report and an Excel-ready CSV. Everything is deterministic: the same inputs give the same output. Documentation is in Korean.
34
+
35
+ text-to-SQL 실험의 예측 파일을 받아 **EX(실행 정확도)를 판정하고, 오답이 정답과 무엇이 다른지를 AI 없이 근거와 함께 보여 주는** Python 라이브러리이자 CLI다.
36
+
37
+ ## 왜 만들었나
38
+
39
+ text-to-SQL 연구를 하면서 실험을 돌리는 것보다 결과를 판단하는 데 시간이 더 오래 걸렸다.
40
+
41
+ - **오답 분석을 손으로 했다.** 틀린 케이스마다 정답과 예측 SQL을 읽고, 다른 곳을 찾아 엑셀에 적고, 카테고리를 붙였다. 질문이나 SQL이 길면 읽기조차 힘들었다.
42
+ - **분류를 AI에게 맡길 수 없었다.** 평가 결과를 LLM이 분류하면 그 분류에도 오류가 섞여, 평가를 믿을 수 없게 된다.
43
+ - **EX 판정 자체가 틀린다.** 정답 결과가 비어 있으면 빈 결과를 내는 아무 SQL이나 정답이 된다. 사람 이름을 물었을 때 이름과 성을 한 컬럼으로 이어 붙여 내면, 내용이 맞아도 오답이 된다.
44
+ - **실험 비교도 손으로 했다.** 두 설정에서 둘 다 틀린 문제, 한쪽만 틀린 문제를 스크립트로 뽑아 눈으로 봤다.
45
+
46
+ 그래서 "무엇이 다른가"는 도구가 규칙으로 보고하고, "왜 틀렸나"는 사람이 판단하도록 나눴다.
47
+
48
+ ## 무엇을 하나
49
+
50
+ - **EX 판정:** BIRD 공식 스크립트와 같은 규칙(행 집합 비교)으로 판정한다. 같은 예측을 공식 스크립트로도 채점해 숫자가 같음을 확인했다.
51
+ - **오답의 차이:** 오답마다 두 가지를 근거와 함께 붙인다. 한 오답에 여러 개가 붙을 수 있다.
52
+ - 출력 차이 6종: 빈 결과, 컬럼 수, 행 수, 값 하나, 행 내용, 실행 실패
53
+ - SQL 구조 차이 5종: WHERE 값, 테이블·JOIN, 컬럼, 집계, ORDER BY/LIMIT
54
+ - **판정 신뢰도 플래그:** 공식 규칙이 놓쳤을 수 있는 판정 6가지를 표시한다(거짓 정답 의심, 거짓 오답 의심). 판정 자체는 바꾸지 않는다.
55
+ - **두 실행 비교:** 케이스 단위 분할표(고쳐짐, 나빠짐), 난이도별·DB별 EX, 차이 분포의 변화를 보여 준다. 기준보다 나빠지면 실패하게 해서 CI에서도 쓸 수 있다.
56
+ - **리포트:** 인터넷 없이 열리는 HTML 한 파일과, 엑셀에서 한글이 깨지지 않는 CSV를 만든다. HTML은 정답·예측 SQL을 절마다 줄을 나눠 나란히 보여 주고, 다른 절과 다른 행을 색칠한다.
57
+
58
+ 판정과 분석에 LLM, 무작위, 시간에 따라 달라지는 값을 쓰지 않는다. 같은 입력이면 같은 결과가 나온다.
59
+
60
+ ![HTML 리포트에서 #247 케이스를 펼친 화면. 정답·예측 SQL이 절마다 줄을 나눠 나란히 보이고, 서로 다른 WHERE 절과 정답에 없는 예측 결과 행 cl, h가 노랗게 칠해져 있다](docs/images/report-case.png)
61
+
62
+ HTML 리포트에서 오답 하나(#247)를 펼친 화면이다. 정답과 예측 SQL에서 다른 절(WHERE)과, 정답에 없는 예측 결과 행(`cl`, `h`)을 칠한다. 출력 차이(`row_count_differs`, `row_set_differs`)와 SQL 구조 차이(`tables_joins`)를 근거와 함께 보여 준다. 리포트 전체는 [examples/results/report.html](examples/results/report.html)이다. 내려받아 브라우저로 열면 된다.
63
+
64
+ ## 3분 사용법
65
+
66
+ Python 3.11 이상이 필요하다. 저장소에 BIRD dev의 DB 3개와 문제 432개, gpt-4o-mini의 예측 두 벌이 들어 있어서 받자마자 돌려 볼 수 있다.
67
+
68
+ ```sh
69
+ git clone https://github.com/cheolkim02/text2sql-eval.git
70
+ cd text2sql-eval
71
+ python -m venv .venv && . .venv/bin/activate
72
+ pip install .
73
+ ```
74
+
75
+ 판정하기(30초쯤 걸린다):
76
+
77
+ ```sh
78
+ text2sql-eval eval \
79
+ --dataset examples/bird-mini/dev.json \
80
+ --db-dir examples/bird-mini/dev_databases \
81
+ --pred examples/results/gpt-4o-mini-evidence.jsonl \
82
+ --tied examples/bird-mini/dev_tied_append.json \
83
+ --out runs/evidence.json
84
+ ```
85
+
86
+ ```text
87
+ Evaluated 432 cases: EX 61.8% (267 correct, 161 incorrect, 4 errors)
88
+ Output difference: 62 column_mismatch, 58 row_set_differs, 44 single_value_differs, 34 empty_result, 31 row_count_differs, 4 execution_failed
89
+ SQL structure difference: 79 columns, 72 tables_joins, 66 aggregation, 25 where_value, 23 order_limit
90
+ Flags: 8 gold_columns_concatenated, 25 gold_rows_with_extra_columns, 5 matches_tied_alternative_only, 13 tied_alternative_exists
91
+ Run file: runs/evidence.json
92
+ ```
93
+
94
+ 리포트 만들기(`runs/evidence.html`을 브라우저로 연다):
95
+
96
+ ```sh
97
+ text2sql-eval report runs/evidence.json --html runs/evidence.html --csv runs/evidence.csv
98
+ ```
99
+
100
+ evidence를 뺀 실행과 비교하기:
101
+
102
+ ```sh
103
+ text2sql-eval compare examples/results/gpt-4o-mini-no-evidence.run.json runs/evidence.json
104
+ ```
105
+
106
+ uv를 쓰면 `pip install .` 대신 `uv sync`를 하고, 명령 앞에 `uv run`을 붙인다. 자세한 안내는 [시작하기](docs/guides/getting-started.md)에 있다.
107
+
108
+ 내 실험의 결과를 넣으려면 예측을 한 줄에 SQL 하나인 텍스트나 JSONL로 쓰면 된다([예측 파일 만들기](docs/guides/prediction-format.md)). 같은 일을 Python에서 하려면 `text2sql_eval.evaluate_files`를 쓴다([API](docs/reference/api.md)).
109
+
110
+ ## 실측 결과
111
+
112
+ 저장소에 커밋된 baseline이다. `examples/bird-mini`(BIRD dev, 432문제)에서 gpt-4o-mini로 같은 프롬프트를 두 번 돌렸고, 다른 점은 BIRD의 `evidence`(힌트)를 넣었는지 하나다.
113
+
114
+ | 설정 | EX | simple | moderate | challenging | BIRD 공식 스크립트 |
115
+ | --- | --- | --- | --- | --- | --- |
116
+ | evidence 있음 | **61.81%** | 68.22% | 54.62% | 47.27% | 61.81% (일치) |
117
+ | evidence 없음 | **37.50%** | 43.80% | 27.73% | 29.09% | 37.50% (일치) |
118
+
119
+ - **공식 스크립트와 일치:** 공식 평가 스크립트를 수정하지 않고 같은 예측을 채점했다. 난이도별 숫자까지 8개가 모두 소수점 둘째 자리까지 같다.
120
+ - **거짓 오답 의심:** evidence 있음 실행의 오답 161개 중 38개(24%)에 플래그가 붙었다. 공식 규칙으로는 오답이지만 사람이 보면 맞다고 할 만한 답이다. 예를 들어 #1445는 이름과 성을 한 컬럼으로 이어 붙였고, #300은 원자 id에 원소 컬럼을 덧붙였다.
121
+ - **두 실행 비교:** evidence를 넣자 123개가 맞게 바뀌고 18개가 틀리게 바뀌었다(+24.3%p). `where_value` 차이가 132개에서 25개로 가장 많이 줄었다. evidence가 주로 WHERE에 들어갈 값(철자, 대소문자, 코드값)을 알려 주기 때문이다.
122
+
123
+ 생성 조건, 비용, 시간 제한에 민감한 케이스는 [examples/results](examples/results/README.md)에 있다.
124
+
125
+ ## 문서
126
+
127
+ | 문서 | 내용 |
128
+ | --- | --- |
129
+ | [시작하기](docs/guides/getting-started.md) | 설치부터 예제로 `eval → report → compare`까지 |
130
+ | [예측 파일 만들기](docs/guides/prediction-format.md) | 내 파이프라인의 결과를 넣는 법 |
131
+ | [결과 읽기](docs/guides/reading-results.md) | 판정 규칙, 차이와 플래그의 뜻, HTML 리포트, CSV로 손 분류하기 |
132
+ | [실행 비교하기](docs/guides/comparing-runs.md) | 비교 결과 해석, CI에서 쓰기 |
133
+ | [CLI 레퍼런스](docs/reference/cli.md) | 명령과 옵션, 종료 코드, 출력 형식 |
134
+ | [API 레퍼런스](docs/reference/api.md) | 공개 Python API 38개 |
135
+ | [실행 파일 형식](docs/reference/run-file.md) | `eval`이 쓰는 JSON |
136
+ | [아키텍처](docs/architecture.md) | 모듈 경계, 의존 방향, 설계 원칙 |
137
+ | [기여 안내](CONTRIBUTING.md) | 개발 환경, 검사, 커밋 규칙 |
138
+
139
+ ## 품질
140
+
141
+ - **타입:** pyright strict에서 오류가 0개다. 공개 API에 `Any`가 없고, 타입 정보(`py.typed`)를 함께 배포한다.
142
+ - **CI:** GitHub Actions에서 다음을 돌린다.
143
+ - Ruff 린트와 포맷 검사, pyright
144
+ - Python 3.11~3.15 테스트
145
+ - 빌드한 wheel을 개발 도구 없는 새 환경에 설치해 CLI를 실제로 돌려 보기
146
+ - **테스트:** 단위 테스트, Hypothesis 속성 기반 테스트, 실제 프로세스로 돌리는 e2e 테스트가 있다. 그 밖에 이런 것을 지킨다.
147
+ - 커밋된 baseline이 예측 파일에서 그대로 다시 나오는지
148
+ - 문서가 코드와 어긋나지 않는지
149
+
150
+ ## AI와 함께 만든 방식
151
+
152
+ 이 저장소는 Claude Code와 함께 만들었다. 역할은 [AGENTS.md](AGENTS.md)에 정해 두었다. 사람이 설계를 결정하고 리뷰하며, 에이전트는 선택지를 제시하고 구현·테스트·문서 초안을 맡는다.
153
+
154
+ - **설계 결정은 모두 사람이 했다.** 공개 API, 의존성, 파일 형식, 판정·차이·플래그 규칙, 도구 선택이 결정 대상이다. 에이전트가 선택지와 장단점을 표로 제시하고, 사람이 고르면 그 자리에서 결정 기록(ADR)을 남긴다. [결정 기록 45개](docs/decisions/README.md)는 모두 결정자가 사람이고, 사람이 한 말을 그대로 인용한다. 에이전트의 추천을 고르지 않은 결정도 그대로 적었다. 예를 들어 Ruff 규칙 세트, baseline 모델, 통계 검정을 넣지 않기로 한 것이 그렇다.
155
+ - **작게 나눠 검토했다.** 기능마다 순서를 지켰다.
156
+ 1. 계획 승인
157
+ 2. 테스트와 구현
158
+ 3. 자가 검토 체크리스트
159
+ 4. 사람의 diff 검토
160
+ 5. PR, CI 통과 후 merge
161
+ - **기록:** AI가 함께 쓴 커밋에는 `Co-Authored-By`를 붙였다.
162
+
163
+ 역할 분담, 사람이 기각한 추천, AI가 틀린 대표 사례와 그것을 잡은 방법은 [AI와 함께 개발한 방식](docs/ai-workflow.md)에 정리했다.
164
+
165
+ ## 한계와 로드맵
166
+
167
+ - **실행 엔진:** SQLite만 실행한다. PostgreSQL·MySQL은 로드맵이다.
168
+ - **판정:** BIRD 공식 규칙 하나로만 판정한다. 행 순서와 중복까지 따지는 엄격 모드는 로드맵이다.
169
+ - **정규화:** SQL 구조 차이의 정규화는 최소한이다. 조건 순서, `IN`과 `EXISTS`, 서브쿼리와 JOIN처럼 뜻은 같고 모양이 다른 SQL은 다르게 본다.
170
+ - **카테고리 매핑:** 사용자가 정한 카테고리를 파일로 자동으로 붙이는 기능은 로드맵이다. 지금은 CSV의 `my_category` 열에 손으로 적는다.
171
+ - **설치:** PyPI에는 아직 배포하지 않았다. 저장소에서 설치한다.
172
+
173
+ ## 라이선스
174
+
175
+ - 코드: [MIT](LICENSE)
176
+ - 예제 데이터 `examples/bird-mini`: [BIRD](https://bird-bench.github.io/) dev의 일부, [CC BY-SA 4.0](examples/bird-mini/LICENSE)(출처와 바꾼 점은 [SOURCE.md](examples/bird-mini/SOURCE.md))
@@ -0,0 +1,148 @@
1
+ # text2sql-eval
2
+
3
+ [![CI](https://github.com/cheolkim02/text2sql-eval/actions/workflows/ci.yml/badge.svg)](https://github.com/cheolkim02/text2sql-eval/actions/workflows/ci.yml)
4
+
5
+ **English summary.** `text2sql-eval` is a Python library and CLI for the error analysis of text-to-SQL experiments. Given a BIRD-style dataset, SQLite databases and a file of predicted SQL, it judges execution accuracy (EX) exactly like BIRD's official script; on the bundled example its numbers match the official script to two decimals. It then explains every wrong case without using an LLM: how the executed results differ, and where the SQL differs, with evidence. It flags verdicts that the official rule may get wrong, such as an answer that returns every gold row plus an extra column. It also compares two runs case by case and writes an offline HTML report and an Excel-ready CSV. Everything is deterministic: the same inputs give the same output. Documentation is in Korean.
6
+
7
+ text-to-SQL 실험의 예측 파일을 받아 **EX(실행 정확도)를 판정하고, 오답이 정답과 무엇이 다른지를 AI 없이 근거와 함께 보여 주는** Python 라이브러리이자 CLI다.
8
+
9
+ ## 왜 만들었나
10
+
11
+ text-to-SQL 연구를 하면서 실험을 돌리는 것보다 결과를 판단하는 데 시간이 더 오래 걸렸다.
12
+
13
+ - **오답 분석을 손으로 했다.** 틀린 케이스마다 정답과 예측 SQL을 읽고, 다른 곳을 찾아 엑셀에 적고, 카테고리를 붙였다. 질문이나 SQL이 길면 읽기조차 힘들었다.
14
+ - **분류를 AI에게 맡길 수 없었다.** 평가 결과를 LLM이 분류하면 그 분류에도 오류가 섞여, 평가를 믿을 수 없게 된다.
15
+ - **EX 판정 자체가 틀린다.** 정답 결과가 비어 있으면 빈 결과를 내는 아무 SQL이나 정답이 된다. 사람 이름을 물었을 때 이름과 성을 한 컬럼으로 이어 붙여 내면, 내용이 맞아도 오답이 된다.
16
+ - **실험 비교도 손으로 했다.** 두 설정에서 둘 다 틀린 문제, 한쪽만 틀린 문제를 스크립트로 뽑아 눈으로 봤다.
17
+
18
+ 그래서 "무엇이 다른가"는 도구가 규칙으로 보고하고, "왜 틀렸나"는 사람이 판단하도록 나눴다.
19
+
20
+ ## 무엇을 하나
21
+
22
+ - **EX 판정:** BIRD 공식 스크립트와 같은 규칙(행 집합 비교)으로 판정한다. 같은 예측을 공식 스크립트로도 채점해 숫자가 같음을 확인했다.
23
+ - **오답의 차이:** 오답마다 두 가지를 근거와 함께 붙인다. 한 오답에 여러 개가 붙을 수 있다.
24
+ - 출력 차이 6종: 빈 결과, 컬럼 수, 행 수, 값 하나, 행 내용, 실행 실패
25
+ - SQL 구조 차이 5종: WHERE 값, 테이블·JOIN, 컬럼, 집계, ORDER BY/LIMIT
26
+ - **판정 신뢰도 플래그:** 공식 규칙이 놓쳤을 수 있는 판정 6가지를 표시한다(거짓 정답 의심, 거짓 오답 의심). 판정 자체는 바꾸지 않는다.
27
+ - **두 실행 비교:** 케이스 단위 분할표(고쳐짐, 나빠짐), 난이도별·DB별 EX, 차이 분포의 변화를 보여 준다. 기준보다 나빠지면 실패하게 해서 CI에서도 쓸 수 있다.
28
+ - **리포트:** 인터넷 없이 열리는 HTML 한 파일과, 엑셀에서 한글이 깨지지 않는 CSV를 만든다. HTML은 정답·예측 SQL을 절마다 줄을 나눠 나란히 보여 주고, 다른 절과 다른 행을 색칠한다.
29
+
30
+ 판정과 분석에 LLM, 무작위, 시간에 따라 달라지는 값을 쓰지 않는다. 같은 입력이면 같은 결과가 나온다.
31
+
32
+ ![HTML 리포트에서 #247 케이스를 펼친 화면. 정답·예측 SQL이 절마다 줄을 나눠 나란히 보이고, 서로 다른 WHERE 절과 정답에 없는 예측 결과 행 cl, h가 노랗게 칠해져 있다](docs/images/report-case.png)
33
+
34
+ HTML 리포트에서 오답 하나(#247)를 펼친 화면이다. 정답과 예측 SQL에서 다른 절(WHERE)과, 정답에 없는 예측 결과 행(`cl`, `h`)을 칠한다. 출력 차이(`row_count_differs`, `row_set_differs`)와 SQL 구조 차이(`tables_joins`)를 근거와 함께 보여 준다. 리포트 전체는 [examples/results/report.html](examples/results/report.html)이다. 내려받아 브라우저로 열면 된다.
35
+
36
+ ## 3분 사용법
37
+
38
+ Python 3.11 이상이 필요하다. 저장소에 BIRD dev의 DB 3개와 문제 432개, gpt-4o-mini의 예측 두 벌이 들어 있어서 받자마자 돌려 볼 수 있다.
39
+
40
+ ```sh
41
+ git clone https://github.com/cheolkim02/text2sql-eval.git
42
+ cd text2sql-eval
43
+ python -m venv .venv && . .venv/bin/activate
44
+ pip install .
45
+ ```
46
+
47
+ 판정하기(30초쯤 걸린다):
48
+
49
+ ```sh
50
+ text2sql-eval eval \
51
+ --dataset examples/bird-mini/dev.json \
52
+ --db-dir examples/bird-mini/dev_databases \
53
+ --pred examples/results/gpt-4o-mini-evidence.jsonl \
54
+ --tied examples/bird-mini/dev_tied_append.json \
55
+ --out runs/evidence.json
56
+ ```
57
+
58
+ ```text
59
+ Evaluated 432 cases: EX 61.8% (267 correct, 161 incorrect, 4 errors)
60
+ Output difference: 62 column_mismatch, 58 row_set_differs, 44 single_value_differs, 34 empty_result, 31 row_count_differs, 4 execution_failed
61
+ SQL structure difference: 79 columns, 72 tables_joins, 66 aggregation, 25 where_value, 23 order_limit
62
+ Flags: 8 gold_columns_concatenated, 25 gold_rows_with_extra_columns, 5 matches_tied_alternative_only, 13 tied_alternative_exists
63
+ Run file: runs/evidence.json
64
+ ```
65
+
66
+ 리포트 만들기(`runs/evidence.html`을 브라우저로 연다):
67
+
68
+ ```sh
69
+ text2sql-eval report runs/evidence.json --html runs/evidence.html --csv runs/evidence.csv
70
+ ```
71
+
72
+ evidence를 뺀 실행과 비교하기:
73
+
74
+ ```sh
75
+ text2sql-eval compare examples/results/gpt-4o-mini-no-evidence.run.json runs/evidence.json
76
+ ```
77
+
78
+ uv를 쓰면 `pip install .` 대신 `uv sync`를 하고, 명령 앞에 `uv run`을 붙인다. 자세한 안내는 [시작하기](docs/guides/getting-started.md)에 있다.
79
+
80
+ 내 실험의 결과를 넣으려면 예측을 한 줄에 SQL 하나인 텍스트나 JSONL로 쓰면 된다([예측 파일 만들기](docs/guides/prediction-format.md)). 같은 일을 Python에서 하려면 `text2sql_eval.evaluate_files`를 쓴다([API](docs/reference/api.md)).
81
+
82
+ ## 실측 결과
83
+
84
+ 저장소에 커밋된 baseline이다. `examples/bird-mini`(BIRD dev, 432문제)에서 gpt-4o-mini로 같은 프롬프트를 두 번 돌렸고, 다른 점은 BIRD의 `evidence`(힌트)를 넣었는지 하나다.
85
+
86
+ | 설정 | EX | simple | moderate | challenging | BIRD 공식 스크립트 |
87
+ | --- | --- | --- | --- | --- | --- |
88
+ | evidence 있음 | **61.81%** | 68.22% | 54.62% | 47.27% | 61.81% (일치) |
89
+ | evidence 없음 | **37.50%** | 43.80% | 27.73% | 29.09% | 37.50% (일치) |
90
+
91
+ - **공식 스크립트와 일치:** 공식 평가 스크립트를 수정하지 않고 같은 예측을 채점했다. 난이도별 숫자까지 8개가 모두 소수점 둘째 자리까지 같다.
92
+ - **거짓 오답 의심:** evidence 있음 실행의 오답 161개 중 38개(24%)에 플래그가 붙었다. 공식 규칙으로는 오답이지만 사람이 보면 맞다고 할 만한 답이다. 예를 들어 #1445는 이름과 성을 한 컬럼으로 이어 붙였고, #300은 원자 id에 원소 컬럼을 덧붙였다.
93
+ - **두 실행 비교:** evidence를 넣자 123개가 맞게 바뀌고 18개가 틀리게 바뀌었다(+24.3%p). `where_value` 차이가 132개에서 25개로 가장 많이 줄었다. evidence가 주로 WHERE에 들어갈 값(철자, 대소문자, 코드값)을 알려 주기 때문이다.
94
+
95
+ 생성 조건, 비용, 시간 제한에 민감한 케이스는 [examples/results](examples/results/README.md)에 있다.
96
+
97
+ ## 문서
98
+
99
+ | 문서 | 내용 |
100
+ | --- | --- |
101
+ | [시작하기](docs/guides/getting-started.md) | 설치부터 예제로 `eval → report → compare`까지 |
102
+ | [예측 파일 만들기](docs/guides/prediction-format.md) | 내 파이프라인의 결과를 넣는 법 |
103
+ | [결과 읽기](docs/guides/reading-results.md) | 판정 규칙, 차이와 플래그의 뜻, HTML 리포트, CSV로 손 분류하기 |
104
+ | [실행 비교하기](docs/guides/comparing-runs.md) | 비교 결과 해석, CI에서 쓰기 |
105
+ | [CLI 레퍼런스](docs/reference/cli.md) | 명령과 옵션, 종료 코드, 출력 형식 |
106
+ | [API 레퍼런스](docs/reference/api.md) | 공개 Python API 38개 |
107
+ | [실행 파일 형식](docs/reference/run-file.md) | `eval`이 쓰는 JSON |
108
+ | [아키텍처](docs/architecture.md) | 모듈 경계, 의존 방향, 설계 원칙 |
109
+ | [기여 안내](CONTRIBUTING.md) | 개발 환경, 검사, 커밋 규칙 |
110
+
111
+ ## 품질
112
+
113
+ - **타입:** pyright strict에서 오류가 0개다. 공개 API에 `Any`가 없고, 타입 정보(`py.typed`)를 함께 배포한다.
114
+ - **CI:** GitHub Actions에서 다음을 돌린다.
115
+ - Ruff 린트와 포맷 검사, pyright
116
+ - Python 3.11~3.15 테스트
117
+ - 빌드한 wheel을 개발 도구 없는 새 환경에 설치해 CLI를 실제로 돌려 보기
118
+ - **테스트:** 단위 테스트, Hypothesis 속성 기반 테스트, 실제 프로세스로 돌리는 e2e 테스트가 있다. 그 밖에 이런 것을 지킨다.
119
+ - 커밋된 baseline이 예측 파일에서 그대로 다시 나오는지
120
+ - 문서가 코드와 어긋나지 않는지
121
+
122
+ ## AI와 함께 만든 방식
123
+
124
+ 이 저장소는 Claude Code와 함께 만들었다. 역할은 [AGENTS.md](AGENTS.md)에 정해 두었다. 사람이 설계를 결정하고 리뷰하며, 에이전트는 선택지를 제시하고 구현·테스트·문서 초안을 맡는다.
125
+
126
+ - **설계 결정은 모두 사람이 했다.** 공개 API, 의존성, 파일 형식, 판정·차이·플래그 규칙, 도구 선택이 결정 대상이다. 에이전트가 선택지와 장단점을 표로 제시하고, 사람이 고르면 그 자리에서 결정 기록(ADR)을 남긴다. [결정 기록 45개](docs/decisions/README.md)는 모두 결정자가 사람이고, 사람이 한 말을 그대로 인용한다. 에이전트의 추천을 고르지 않은 결정도 그대로 적었다. 예를 들어 Ruff 규칙 세트, baseline 모델, 통계 검정을 넣지 않기로 한 것이 그렇다.
127
+ - **작게 나눠 검토했다.** 기능마다 순서를 지켰다.
128
+ 1. 계획 승인
129
+ 2. 테스트와 구현
130
+ 3. 자가 검토 체크리스트
131
+ 4. 사람의 diff 검토
132
+ 5. PR, CI 통과 후 merge
133
+ - **기록:** AI가 함께 쓴 커밋에는 `Co-Authored-By`를 붙였다.
134
+
135
+ 역할 분담, 사람이 기각한 추천, AI가 틀린 대표 사례와 그것을 잡은 방법은 [AI와 함께 개발한 방식](docs/ai-workflow.md)에 정리했다.
136
+
137
+ ## 한계와 로드맵
138
+
139
+ - **실행 엔진:** SQLite만 실행한다. PostgreSQL·MySQL은 로드맵이다.
140
+ - **판정:** BIRD 공식 규칙 하나로만 판정한다. 행 순서와 중복까지 따지는 엄격 모드는 로드맵이다.
141
+ - **정규화:** SQL 구조 차이의 정규화는 최소한이다. 조건 순서, `IN`과 `EXISTS`, 서브쿼리와 JOIN처럼 뜻은 같고 모양이 다른 SQL은 다르게 본다.
142
+ - **카테고리 매핑:** 사용자가 정한 카테고리를 파일로 자동으로 붙이는 기능은 로드맵이다. 지금은 CSV의 `my_category` 열에 손으로 적는다.
143
+ - **설치:** PyPI에는 아직 배포하지 않았다. 저장소에서 설치한다.
144
+
145
+ ## 라이선스
146
+
147
+ - 코드: [MIT](LICENSE)
148
+ - 예제 데이터 `examples/bird-mini`: [BIRD](https://bird-bench.github.io/) dev의 일부, [CC BY-SA 4.0](examples/bird-mini/LICENSE)(출처와 바꾼 점은 [SOURCE.md](examples/bird-mini/SOURCE.md))
@@ -0,0 +1,82 @@
1
+ [project]
2
+ name = "text2sql-eval"
3
+ version = "0.1.0"
4
+ description = "Deterministic, evidence-backed error analysis and run comparison for text-to-SQL experiments"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.11"
9
+ keywords = [
10
+ "text-to-sql",
11
+ "nl2sql",
12
+ "evaluation",
13
+ "error-analysis",
14
+ "bird",
15
+ ]
16
+ classifiers = [
17
+ "Development Status :: 3 - Alpha",
18
+ "Intended Audience :: Science/Research",
19
+ "Programming Language :: Python :: 3",
20
+ "Programming Language :: Python :: 3 :: Only",
21
+ "Programming Language :: Python :: 3.11",
22
+ "Programming Language :: Python :: 3.12",
23
+ "Programming Language :: Python :: 3.13",
24
+ "Programming Language :: Python :: 3.14",
25
+ "Programming Language :: Python :: 3.15",
26
+ "Topic :: Database",
27
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
28
+ "Typing :: Typed",
29
+ ]
30
+ dependencies = [
31
+ "jinja2>=3.1.6",
32
+ "sqlglot>=30.31.0",
33
+ ]
34
+
35
+ [[project.authors]]
36
+ name = "cheolkim02"
37
+
38
+ [project.scripts]
39
+ text2sql-eval = "text2sql_eval.cli.main:main"
40
+
41
+ [project.urls]
42
+ Repository = "https://github.com/cheolkim02/text2sql-eval"
43
+ Documentation = "https://github.com/cheolkim02/text2sql-eval/tree/main/docs"
44
+ Issues = "https://github.com/cheolkim02/text2sql-eval/issues"
45
+
46
+ [build-system]
47
+ requires = ["uv_build>=0.13.7,<0.14.0"]
48
+ build-backend = "uv_build"
49
+
50
+ [dependency-groups]
51
+ dev = [
52
+ "hypothesis>=6.170.15",
53
+ "pyright>=1.1.414",
54
+ "pytest>=9.2.0",
55
+ "ruff>=0.17.4",
56
+ "syrupy>=6.1.1",
57
+ ]
58
+ examples = ["openai>=3.46.0"]
59
+
60
+ [tool.ruff]
61
+ line-length = 88
62
+
63
+ [tool.pyright]
64
+ include = [
65
+ "src",
66
+ "tests",
67
+ "examples",
68
+ ]
69
+ pythonVersion = "3.11"
70
+ typeCheckingMode = "strict"
71
+ reportUnnecessaryTypeIgnoreComment = "error"
72
+ venvPath = "."
73
+ venv = ".venv"
74
+
75
+ [tool.pytest.ini_options]
76
+ testpaths = ["tests"]
77
+ addopts = [
78
+ "-ra",
79
+ "--strict-markers",
80
+ "--strict-config",
81
+ ]
82
+ xfail_strict = true
@@ -0,0 +1,70 @@
1
+ [project]
2
+ name = "text2sql-eval"
3
+ version = "0.1.0"
4
+ description = "Deterministic, evidence-backed error analysis and run comparison for text-to-SQL experiments"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ authors = [{ name = "cheolkim02" }]
9
+ requires-python = ">=3.11"
10
+ keywords = ["text-to-sql", "nl2sql", "evaluation", "error-analysis", "bird"]
11
+ classifiers = [
12
+ "Development Status :: 3 - Alpha",
13
+ "Intended Audience :: Science/Research",
14
+ "Programming Language :: Python :: 3",
15
+ "Programming Language :: Python :: 3 :: Only",
16
+ "Programming Language :: Python :: 3.11",
17
+ "Programming Language :: Python :: 3.12",
18
+ "Programming Language :: Python :: 3.13",
19
+ "Programming Language :: Python :: 3.14",
20
+ "Programming Language :: Python :: 3.15",
21
+ "Topic :: Database",
22
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
23
+ "Typing :: Typed",
24
+ ]
25
+ dependencies = [
26
+ "jinja2>=3.1.6",
27
+ "sqlglot>=30.31.0",
28
+ ]
29
+
30
+ [project.scripts]
31
+ text2sql-eval = "text2sql_eval.cli.main:main"
32
+
33
+ [project.urls]
34
+ Repository = "https://github.com/cheolkim02/text2sql-eval"
35
+ Documentation = "https://github.com/cheolkim02/text2sql-eval/tree/main/docs"
36
+ Issues = "https://github.com/cheolkim02/text2sql-eval/issues"
37
+
38
+ [build-system]
39
+ requires = ["uv_build>=0.13.7,<0.14.0"]
40
+ build-backend = "uv_build"
41
+
42
+ [dependency-groups]
43
+ dev = [
44
+ "hypothesis>=6.170.15",
45
+ "pyright>=1.1.414",
46
+ "pytest>=9.2.0",
47
+ "ruff>=0.17.4",
48
+ "syrupy>=6.1.1",
49
+ ]
50
+ examples = [
51
+ "openai>=3.46.0",
52
+ ]
53
+
54
+ [tool.ruff]
55
+ # ADR 0015: default rule set (syntax errors and obvious mistakes only).
56
+ line-length = 88
57
+
58
+ [tool.pyright]
59
+ # ADR 0013: strict mode plus one rule that strict leaves off.
60
+ include = ["src", "tests", "examples"]
61
+ pythonVersion = "3.11"
62
+ typeCheckingMode = "strict"
63
+ reportUnnecessaryTypeIgnoreComment = "error"
64
+ venvPath = "."
65
+ venv = ".venv"
66
+
67
+ [tool.pytest.ini_options]
68
+ testpaths = ["tests"]
69
+ addopts = ["-ra", "--strict-markers", "--strict-config"]
70
+ xfail_strict = true
@@ -0,0 +1,101 @@
1
+ """Deterministic, evidence-backed error analysis for text-to-SQL experiments.
2
+
3
+ The public API is exactly what ``__all__`` lists (ADR 0043). Anything else,
4
+ including the submodules, may change without notice.
5
+
6
+ Example:
7
+ The same steps as ``text2sql-eval eval`` and ``text2sql-eval report``:
8
+
9
+ >>> from pathlib import Path
10
+ >>> import text2sql_eval as t2s
11
+ >>> run = t2s.evaluate_files(
12
+ ... Path("dev.json"), Path("predictions.jsonl"), db_dir=Path("dev_databases")
13
+ ... )
14
+ >>> t2s.write_run(run, Path("runs/v3.json"))
15
+ >>> t2s.write_html_report(run, Path("runs/v3.html"), run_name="v3")
16
+ """
17
+
18
+ from importlib.metadata import version
19
+
20
+ from text2sql_eval.compare.runs import (
21
+ CaseChange,
22
+ Change,
23
+ Comparison,
24
+ GroupEx,
25
+ compare_runs,
26
+ write_comparison_csv,
27
+ )
28
+ from text2sql_eval.errors import InputError
29
+ from text2sql_eval.evaluate import evaluate_files
30
+ from text2sql_eval.execution.executor import QueryFailure, SqlValue
31
+ from text2sql_eval.facts import CaseDiff
32
+ from text2sql_eval.facts.output import OutputDiff, OutputDifference, Relation
33
+ from text2sql_eval.facts.structure import Fact, FactKind, StructureReport
34
+ from text2sql_eval.judge.ex import (
35
+ Correct,
36
+ ExecError,
37
+ Flag,
38
+ FlagKind,
39
+ Incorrect,
40
+ Verdict,
41
+ status_of,
42
+ )
43
+ from text2sql_eval.report.csv_report import write_report_csv
44
+ from text2sql_eval.report.html_report import write_html_report
45
+ from text2sql_eval.runfile import (
46
+ CaseRecord,
47
+ FileRef,
48
+ PredictionFormat,
49
+ PredictionState,
50
+ QuerySummary,
51
+ ResultSample,
52
+ Run,
53
+ RunSettings,
54
+ Summary,
55
+ read_run,
56
+ write_run,
57
+ )
58
+
59
+ __version__ = version("text2sql-eval")
60
+
61
+ # Sorted as Ruff requires; docs/reference/api.md groups them by purpose.
62
+ __all__ = [
63
+ "CaseChange",
64
+ "CaseDiff",
65
+ "CaseRecord",
66
+ "Change",
67
+ "Comparison",
68
+ "Correct",
69
+ "ExecError",
70
+ "Fact",
71
+ "FactKind",
72
+ "FileRef",
73
+ "Flag",
74
+ "FlagKind",
75
+ "GroupEx",
76
+ "Incorrect",
77
+ "InputError",
78
+ "OutputDiff",
79
+ "OutputDifference",
80
+ "PredictionFormat",
81
+ "PredictionState",
82
+ "QueryFailure",
83
+ "QuerySummary",
84
+ "Relation",
85
+ "ResultSample",
86
+ "Run",
87
+ "RunSettings",
88
+ "SqlValue",
89
+ "StructureReport",
90
+ "Summary",
91
+ "Verdict",
92
+ "__version__",
93
+ "compare_runs",
94
+ "evaluate_files",
95
+ "read_run",
96
+ "status_of",
97
+ "write_comparison_csv",
98
+ "write_html_report",
99
+ "write_report_csv",
100
+ "write_run",
101
+ ]
@@ -0,0 +1 @@
1
+ """Command-line interface. The entry point is ``text2sql_eval.cli.main:main``."""