Merge branch 'master' into feature/61-질문-재정의-노드-강화

Author: ehddnr301

.gitignore

@@ -9,4 +9,5 @@ dist/
 test_lhm/
 .cursorignore
 .vscode
-table_info_db
+table_info_db
+ko_reranker_local

Dockerfile

@@ -0,0 +1,32 @@
+# Python 3.10 slim 이미지 기반
+FROM python:3.12-slim
+
+# 시스템 라이브러리 설치
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    software-properties-common \
+    git \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# 작업 디렉토리 설정
+WORKDIR /app
+
+# 의존성 파일 복사 및 설치
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+# 전체 서비스 코드 복사
+COPY . .
+
+# Python 환경 설정
+ENV PYTHONPATH=/app
+ENV PYTHONUNBUFFERED=1
+
+# Streamlit 포트 노출
+EXPOSE 8501
+
+# Streamlit 실행 명령
+CMD ["python", "-c", "from llm_utils.tools import set_gms_server; import os; set_gms_server(os.getenv('DATAHUB_SERVER', 'http://localhost:8080'))"]
+CMD ["streamlit", "run", "./interface/streamlit_app.py", "--server.port=8501"] 

cli/__init__.py

@@ -2,12 +2,21 @@
 Datahub GMS 서버 URL을 설정하고, 필요 시 Streamlit 인터페이스를 실행하는 CLI 프로그램입니다.
 """
 
+import logging
 import subprocess
 
 import click
 
+from llm_utils.check_server import CheckServer
 from llm_utils.tools import set_gms_server
 
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
 
 @click.group()
 @click.version_option(version="0.1.4")
@@ -64,11 +73,20 @@ def cli(
         'set_gms_server' 함수에서 ValueError가 발생할 경우, 프로그램은 비정상 종료(exit code 1)합니다.
     """
 
-    try:
+    logger.info(
+        "Initialization started: GMS server = %s, run_streamlit = %s, port = %d",
+        datahub_server,
+        run_streamlit,
+        port,
+    )
+
+    if CheckServer.is_gms_server_healthy(url=datahub_server):
         set_gms_server(datahub_server)
-    except ValueError as e:
-        click.secho(f"GMS 서버 URL 설정 실패: {str(e)}", fg="red")
+        logger.info("GMS server URL successfully set: %s", datahub_server)
+    else:
+        logger.error("GMS server health check failed. URL: %s", datahub_server)
         ctx.exit(1)
+
     if run_streamlit:
         run_streamlit_command(port)
 
@@ -89,6 +107,8 @@ def run_streamlit_command(port: int) -> None:
         - subprocess 호출 실패 시 예외가 발생할 수 있습니다.
     """
 
+    logger.info("Starting Streamlit application on port %d...", port)
+
     try:
         subprocess.run(
             [
@@ -100,8 +120,9 @@ def run_streamlit_command(port: int) -> None:
             ],
             check=True,
         )
+        logger.info("Streamlit application started successfully.")
     except subprocess.CalledProcessError as e:
-        click.echo(f"Streamlit 실행 실패: {e}")
+        logger.error("Failed to start Streamlit application: %s", e)
         raise
 
 
@@ -132,4 +153,5 @@ def run_streamlit_cli_command(port: int) -> None:
         - Streamlit 실행에 실패할 경우 subprocess 호출에서 예외가 발생할 수 있습니다.
     """
 
+    logger.info("Executing 'run-streamlit' command on port %d...", port)
     run_streamlit_command(port)

data_utils/__init__.py

@@ -1 +0,0 @@
-# data_utils 패키지 초기화 파일

docker-compose.yml

@@ -0,0 +1,28 @@
+services:
+  streamlit:
+    build: .
+    ports:
+      - "8501:8501"
+    volumes:
+      - .:/app
+    env_file:
+      - .env
+    environment:
+      - DATABASE_URL=postgresql://postgres:password@db:5432/streamlit_db
+    depends_on:
+      - db
+
+  db:
+    image: pgvector/pgvector:pg17
+    container_name: pgvector-db
+    environment:
+      POSTGRES_USER: postgres
+      POSTGRES_PASSWORD: password
+      POSTGRES_DB: streamlit_db
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+      - ./postgres/schema.sql:/docker-entrypoint-initdb.d/schema.sql
+volumes:
+  pgdata: 

interface/lang2sql.py

@@ -7,11 +7,13 @@
 
 import streamlit as st
 from langchain.chains.sql_database.prompt import SQL_PROMPTS
-from langchain_core.messages import HumanMessage
+from langchain_core.messages import AIMessage, HumanMessage
 
 from llm_utils.connect_db import ConnectDB
 from llm_utils.graph import builder
 from llm_utils.enriched_graph import builder as enriched_builder
+from llm_utils.display_chart import DisplayChart
+from llm_utils.llm_response_parser import LLMResponseParser
 
 DEFAULT_QUERY = "고객 데이터를 기반으로 유니크한 유저 수를 카운트하는 쿼리"
 SIDEBAR_OPTIONS = {
@@ -52,18 +54,27 @@ def execute_query(
     device: str = "cpu",
 ) -> dict:
     """
-    Lang2SQL 그래프를 실행하여 자연어 쿼리를 SQL 쿼리로 변환하고 결과를 반환합니다.
+    자연어 쿼리를 SQL로 변환하고 실행 결과를 반환하는 Lang2SQL 그래프 인터페이스 함수입니다.
+
+    이 함수는 Lang2SQL 파이프라인(graph)을 세션 상태에서 가져오거나 새로 컴파일한 뒤,
+    사용자의 자연어 질문을 SQL 쿼리로 변환하고 관련 메타데이터와 함께 결과를 반환합니다.
+    내부적으로 LangChain의 `graph.invoke` 메서드를 호출합니다.
 
     Args:
-        query (str): 자연어로 작성된 사용자 쿼리.
-        database_env (str): 사용할 데이터베이스 환경 설정 이름.
-        retriever_name (str): 사용할 검색기 이름.
-        top_n (int): 검색할 테이블 정보의 개수.
+        query (str): 사용자가 입력한 자연어 기반 질문.
+        database_env (str): 사용할 데이터베이스 환경 이름 또는 키 (예: "dev", "prod").
+        retriever_name (str, optional): 테이블 검색기 이름. 기본값은 "기본".
+        top_n (int, optional): 검색된 상위 테이블 수 제한. 기본값은 5.
+        device (str, optional): LLM 실행에 사용할 디바이스 ("cpu" 또는 "cuda"). 기본값은 "cpu".
 
     Returns:
-        dict: 변환된 SQL 쿼리 및 관련 메타데이터를 포함하는 결과 딕셔너리.
+        dict: 다음 정보를 포함한 Lang2SQL 실행 결과 딕셔너리:
+            - "generated_query": 생성된 SQL 쿼리 (`AIMessage`)
+            - "messages": 전체 LLM 응답 메시지 목록
+            - "refined_input": AI가 재구성한 입력 질문
+            - "searched_tables": 참조된 테이블 목록 등 추가 정보
     """
-    # 세션 상태에서 그래프 가져오기
+
     graph = st.session_state.get("graph")
     if graph is None:
         graph_builder = (
@@ -106,22 +117,84 @@ def display_result(
         - 참조된 테이블 목록
         - 쿼리 실행 결과 테이블
     """
-    total_tokens = summarize_total_tokens(res["messages"])
-
-    if st.session_state.get("show_total_token_usage", True):
-        st.write("총 토큰 사용량:", total_tokens)
-    if st.session_state.get("show_sql", True):
-        st.write("결과:", "\n\n```sql\n" + res["generated_query"].content + "\n```")
-    if st.session_state.get("show_result_description", True):
-        st.write("결과 설명:\n\n", res["messages"][-1].content)
-    if st.session_state.get("show_question_reinterpreted_by_ai", True):
-        st.write("AI가 재해석한 사용자 질문:\n", res["refined_input"].content)
-    if st.session_state.get("show_referenced_tables", True):
-        st.write("참고한 테이블 목록:", res["searched_tables"])
-    if st.session_state.get("show_table", True):
-        sql = res["generated_query"]
+
+    def should_show(_key: str) -> bool:
+        st.markdown("---")
+        return st.session_state.get(_key, True)
+
+    if should_show("show_total_token_usage"):
+        total_tokens = summarize_total_tokens(res["messages"])
+        st.write("**총 토큰 사용량:**", total_tokens)
+
+    if should_show("show_sql"):
+        generated_query = res.get("generated_query")
+        query_text = (
+            generated_query.content
+            if isinstance(generated_query, AIMessage)
+            else str(generated_query)
+        )
+
+        try:
+            sql = LLMResponseParser.extract_sql(query_text)
+            st.markdown("**생성된 SQL 쿼리:**")
+            st.code(sql, language="sql")
+        except ValueError:
+            st.warning("SQL 블록을 추출할 수 없습니다.")
+            st.text(query_text)
+
+        interpretation = LLMResponseParser.extract_interpretation(query_text)
+        if interpretation:
+            st.markdown("**결과 해석:**")
+            st.code(interpretation)
+
+    if should_show("show_result_description"):
+        st.markdown("**결과 설명:**")
+        result_message = res["messages"][-1].content
+
+        try:
+            sql = LLMResponseParser.extract_sql(result_message)
+            st.code(sql, language="sql")
+        except ValueError:
+            st.warning("SQL 블록을 추출할 수 없습니다.")
+            st.text(result_message)
+
+        interpretation = LLMResponseParser.extract_interpretation(result_message)
+        if interpretation:
+            st.code(interpretation, language="plaintext")
+
+    if should_show("show_question_reinterpreted_by_ai"):
+        st.markdown("**AI가 재해석한 사용자 질문:**")
+        st.code(res["refined_input"].content)
+
+    if should_show("show_referenced_tables"):
+        st.markdown("**참고한 테이블 목록:**")
+        st.write(res.get("searched_tables", []))
+
+    if should_show("show_table"):
+        try:
+            sql_raw = (
+                res["generated_query"].content
+                if isinstance(res["generated_query"], AIMessage)
+                else str(res["generated_query"])
+            )
+            sql = LLMResponseParser.extract_sql(sql_raw)
+            df = database.run_sql(sql)
+            st.dataframe(df.head(10) if len(df) > 10 else df)
+        except Exception as e:
+            st.error(f"쿼리 실행 중 오류 발생: {e}")
+    if should_show("show_chart"):
         df = database.run_sql(sql)
-        st.dataframe(df.head(10) if len(df) > 10 else df)
+        st.markdown("**쿼리 결과 시각화:**")
+        display_code = DisplayChart(
+            question=res["refined_input"].content,
+            sql=sql,
+            df_metadata=f"Running df.dtypes gives:\n{df.dtypes}",
+        )
+        # plotly_code 변수도 따로 보관할 필요 없이 바로 그려도 됩니다
+        fig = display_code.get_plotly_figure(
+            plotly_code=display_code.generate_plotly_code(), df=df
+        )
+        st.plotly_chart(fig)
 
 
 db = ConnectDB()

llm_utils/check_server.py

@@ -0,0 +1,74 @@
+"""
+서버 상태 확인 및 연결 관련 기능을 제공하는 유틸리티 클래스입니다.
+
+이 모듈은 HTTP 기반의 서버에 대해 다음과 같은 기능을 제공합니다:
+- `/health` 엔드포인트를 통한 서버 헬스 체크
+- 향후 서버 연결 또는 상태 점검과 관련된 기능 추가 예정
+
+각 기능은 요청 실패, 타임아웃, 연결 오류 등의 다양한 예외 상황을 포괄적으로 처리하며,
+로깅을 통해 상세한 실패 원인을 기록하고 결과를 boolean 또는 적절한 형태로 반환합니다.
+"""
+
+import logging
+from urllib.parse import urljoin
+
+import requests
+
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s [%(levelname)s] %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+logger = logging.getLogger(__name__)
+
+
+class CheckServer:
+    """
+    서버의 상태를 확인하거나 연결을 테스트하는 유틸리티 메서드를 제공하는 클래스입니다.
+
+    현재는 GMS 서버의 `/health` 엔드포인트에 대한 헬스 체크 기능을 포함하고 있으며,
+    향후에는 다양한 서버 연결 확인 및 상태 점검 기능이 추가될 수 있도록 확장 가능한 구조로 설계되었습니다.
+    모든 기능은 네트워크 오류 및 서버 응답 상태에 따라 예외를 로깅하며, 호출자가 결과를 판단할 수 있도록 boolean 값을 반환합니다.
+    """
+
+    @staticmethod
+    def is_gms_server_healthy(*, url: str) -> bool:
+        """
+        지정된 GMS 서버의 `/health` 엔드포인트에 요청을 보내 상태를 확인합니다.
+
+        서버가 HTTP 200 응답을 반환하면 True를 반환하며,
+        요청 실패, 타임아웃, 연결 오류 등의 예외 발생 시 False를 반환하고,
+        로깅을 통해 상세한 에러 정보를 출력합니다.
+
+        Args:
+            url (str): 헬스 체크를 수행할 GMS 서버의 기본 URL (예: "http://localhost:8080")
+
+        Returns:
+            bool: 서버가 정상적으로 응답하면 True, 예외 발생 시 False
+        """
+
+        health_url = urljoin(url, "/health")
+
+        try:
+            response = requests.get(
+                health_url,
+                timeout=3,
+            )
+            response.raise_for_status()
+            logger.info("GMS server is healthy: %s", url)
+            return True
+        except (
+            requests.exceptions.ConnectTimeout,
+            requests.exceptions.ReadTimeout,
+        ) as e:
+            logger.error(
+                "Timeout while connecting to GMS server: %s | %s", health_url, e
+            )
+        except requests.exceptions.ConnectionError as e:
+            logger.error("Failed to connect to GMS server: %s | %s", health_url, e)
+        except requests.exceptions.HTTPError as e:
+            logger.error("GMS server returned HTTP error: %s | %s", health_url, e)
+        except requests.exceptions.RequestException as e:
+            logger.exception("Unexpected request error to GMS server: %s", health_url)
+
+        return False