ktmu 0.1.1__tar.gz

ktmu-0.1.1/LICENSE

@@ -0,0 +1,184 @@
+KTMU - Korean Text Mining Utilities
+Copyright (C) 2026 Kilhwan Kim <khkim@smu.ac.kr>
+
+This library is free software; you can redistribute it and/or
+modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either
+version 3 of the License, or (at your option) any later version.
+
+This library is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this library; if not, write to the Free Software
+Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
+
+--------------
+
+GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

ktmu-0.1.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: ktmu
+Version: 0.1.1
+Summary: Korean Text Mining utilities for visualization, NLP, and LLM analysis
+Author-email: Kilhwan Kim <khkim@smu.ac.kr>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: wordcloud
+Requires-Dist: spacy
+Requires-Dist: kiwipiepy
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: google-genai
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Dynamic: license-file
+
+# ktmu: Korean Text Mining Utilities
+
+`ktmu`는 텍스트 데이터의 전처리, 시각화, 언어 모델 연동을 통합적으로 지원하기 위한 파이썬 패키지입니다. 특히 한국어(Kiwi)와 영어(spaCy) 형태소 분석을 일관된 인터페이스로 제공하며, 최신 LLM(Gemini)을 활용한 분석 기능을 포함하고 있습니다.
+
+## 주요 기능
+
+* **다양한 시각화 지원**: 토큰 빈도 막대 그래프, 워드클라우드, 임베딩 차원 축소(PCA/t-SNE), 계층적 군집화 덴드로그램 출력.
+* **통합 형태소 분석 인터페이스**: `SpacyTokenizer`(영어) 및 `KiwiTokenizer`(한국어) 클래스를 통한 손쉬운 토큰화 및 표제어 추출.
+* **Pandas 연동**: 모든 분석 결과(토큰, 형태소 정보 등)를 즉시 DataFrame으로 변환하여 데이터 분석 파이프라인에 활용 가능.
+* **LLM 감성 분석**: Google Gemini API를 활용한 대규모 텍스트 데이터의 배치 감성 분석 기능.
+* **임베딩 분석**: Gensim 모델과 연동하여 단어 간 유사도 비교 및 시각화.
+
+## 설치 방법
+
+패키지는 다음과 같이 설치합니다.
+
+```bash
+pip install ktmu
+```
+
+## 사용 예시
+
+### 1. 한국어 형태소 분석 (Kiwi)
+
+```python
+from ktmu import KiwiTokenizer
+
+tokenizer = KiwiTokenizer()
+text = "텍스트 마이닝은 정말 재밌는 학문입니다."
+
+# 토큰화 및 데이터프레임 변환
+df = tokenizer.get_token_dataframe(text)
+print(df)
+
+# 명사만 추출
+nouns = tokenizer.noun_tokenize(text)
+print(nouns)
+```
+
+### 2. 빈도 시각화
+
+```python
+from ktmu import visualize_tokens
+
+tokens = ["데이터", "분석", "데이터", "AI", "텍스트", "분석", "데이터"]
+visualize_tokens(tokens, top_n=10)
+```
+
+### 3. Gemini를 활용한 감성 분석
+
+```python
+import pandas as pd
+from google import genai
+from ktmu import analyze_sentiment_with_gemini
+
+client = genai.Client(api_key="YOUR_API_KEY")
+reviews = pd.Series(["이 영화 정말 재밌어요!", "시간 아까워요..."], name="review")
+
+# 배치 감성 분석 수행
+results = analyze_sentiment_with_gemini(client, reviews, system_message="감성 분석 전문가로서 응답해줘.")
+print(results)
+```
+
+### 4. 워드 임베딩 시각화
+
+```python
+from ktmu import visualize_embeddings
+
+# gensim의 word vector 객체(wv)가 있다고 가정
+words = ["사과", "바나나", "컴퓨터", "키보드"]
+visualize_embeddings(wv, words, method='pca')
+```
+
+## 의존성
+
+이 패키지는 다음 라이브러리들을 사용합니다:
+* `pandas`, `numpy`, `matplotlib`
+* `spacy`, `kiwipiepy`
+* `scikit-learn`, `scipy`
+* `wordcloud`, `google-genai`
+
+## 라이선스
+
+이 프로젝트는 **LGPL-3.0** 라이선스 하에 배포됩니다. 

ktmu-0.1.1/README.md

@@ -0,0 +1,84 @@
+# ktmu: Korean Text Mining Utilities
+
+`ktmu`는 텍스트 데이터의 전처리, 시각화, 언어 모델 연동을 통합적으로 지원하기 위한 파이썬 패키지입니다. 특히 한국어(Kiwi)와 영어(spaCy) 형태소 분석을 일관된 인터페이스로 제공하며, 최신 LLM(Gemini)을 활용한 분석 기능을 포함하고 있습니다.
+
+## 주요 기능
+
+* **다양한 시각화 지원**: 토큰 빈도 막대 그래프, 워드클라우드, 임베딩 차원 축소(PCA/t-SNE), 계층적 군집화 덴드로그램 출력.
+* **통합 형태소 분석 인터페이스**: `SpacyTokenizer`(영어) 및 `KiwiTokenizer`(한국어) 클래스를 통한 손쉬운 토큰화 및 표제어 추출.
+* **Pandas 연동**: 모든 분석 결과(토큰, 형태소 정보 등)를 즉시 DataFrame으로 변환하여 데이터 분석 파이프라인에 활용 가능.
+* **LLM 감성 분석**: Google Gemini API를 활용한 대규모 텍스트 데이터의 배치 감성 분석 기능.
+* **임베딩 분석**: Gensim 모델과 연동하여 단어 간 유사도 비교 및 시각화.
+
+## 설치 방법
+
+패키지는 다음과 같이 설치합니다.
+
+```bash
+pip install ktmu
+```
+
+## 사용 예시
+
+### 1. 한국어 형태소 분석 (Kiwi)
+
+```python
+from ktmu import KiwiTokenizer
+
+tokenizer = KiwiTokenizer()
+text = "텍스트 마이닝은 정말 재밌는 학문입니다."
+
+# 토큰화 및 데이터프레임 변환
+df = tokenizer.get_token_dataframe(text)
+print(df)
+
+# 명사만 추출
+nouns = tokenizer.noun_tokenize(text)
+print(nouns)
+```
+
+### 2. 빈도 시각화
+
+```python
+from ktmu import visualize_tokens
+
+tokens = ["데이터", "분석", "데이터", "AI", "텍스트", "분석", "데이터"]
+visualize_tokens(tokens, top_n=10)
+```
+
+### 3. Gemini를 활용한 감성 분석
+
+```python
+import pandas as pd
+from google import genai
+from ktmu import analyze_sentiment_with_gemini
+
+client = genai.Client(api_key="YOUR_API_KEY")
+reviews = pd.Series(["이 영화 정말 재밌어요!", "시간 아까워요..."], name="review")
+
+# 배치 감성 분석 수행
+results = analyze_sentiment_with_gemini(client, reviews, system_message="감성 분석 전문가로서 응답해줘.")
+print(results)
+```
+
+### 4. 워드 임베딩 시각화
+
+```python
+from ktmu import visualize_embeddings
+
+# gensim의 word vector 객체(wv)가 있다고 가정
+words = ["사과", "바나나", "컴퓨터", "키보드"]
+visualize_embeddings(wv, words, method='pca')
+```
+
+## 의존성
+
+이 패키지는 다음 라이브러리들을 사용합니다:
+* `pandas`, `numpy`, `matplotlib`
+* `spacy`, `kiwipiepy`
+* `scikit-learn`, `scipy`
+* `wordcloud`, `google-genai`
+
+## 라이선스
+
+이 프로젝트는 **LGPL-3.0** 라이선스 하에 배포됩니다. 

ktmu-0.1.1/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ktmu"
+version = "0.1.1"
+description = "Korean Text Mining utilities for visualization, NLP, and LLM analysis"
+readme = "README.md"
+requires-python = ">=3.9"  # google-genai 및 최신 라이브러리 호환성을 위해 3.9 이상 권장
+authors = [
+    {name = "Kilhwan Kim", email="khkim@smu.ac.kr"}
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)",
+    "Operating System :: OS Independent",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Text Processing :: Linguistic",
+]
+
+# 소스 코드 내에서 import하고 있는 필수 라이브러리들입니다.
+dependencies = [
+    "pandas",
+    "numpy",
+    "matplotlib",
+    "wordcloud",
+    "spacy",
+    "kiwipiepy",
+    "scikit-learn",
+    "scipy",
+    "google-genai",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[project.optional-dependencies]
+# 개발 및 테스트를 위한 선택적 의존성
+dev = [
+    "pytest",
+    "black",
+]

ktmu-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ktmu-0.1.1/src/ktmu/main.py

@@ -0,0 +1,519 @@
+# main.py
+# Copyright (C) 2026 Kilhwan Kim
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+
+import pandas as pd
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib.font_manager as fm
+from wordcloud import WordCloud
+import spacy
+import spacy.cli
+import unicodedata
+from spacy.util import is_package
+from kiwipiepy import Kiwi
+from kiwipiepy.utils import Stopwords
+from sklearn.decomposition import PCA
+from sklearn.manifold import TSNE
+from scipy.cluster.hierarchy import dendrogram, linkage
+from typing import List, Union, Iterable
+from google import genai
+import json
+
+def visualize_tokens(tokens, top_n=20, font_path=None):
+    """토큰 빈도 기반의 막대 그래프와 워드클라우드를 시각화
+
+    Args:
+        tokens (list): 시각화할 텍스트 토큰들의 리스트.
+        top_n (int, optional): 막대 그래프에 표시할 상위 단어의 개수. 기본값은 20.
+        font_path (str, optional): 워드 클라우드에 사용할 폰트 설정
+
+    Returns:
+        None: 결과 그래프를 화면에 출력
+    """
+
+    # 시스템에서 나눔폰트 경로 자동 탐색
+    try:
+        font_path = [f.fname for f in fm.fontManager.ttflist if 'Nanum' in f.name][0]
+    except IndexError:
+        font_path = None  # 폰트를 못 찾을 경우를 대비한 예외 처리
+
+    # 단어별 출현 빈도 계산
+    word_counts = pd.Series(tokens).value_counts() 
+    
+    # 레이아웃 설정 (막대 그래프와 워드클라우드 비율 1:2)
+    fig, axes = plt.subplots(1, 2, figsize=(10, 4), gridspec_kw={"width_ratios": [1, 2]})
+    
+    # 상위 n개 단어 막대 그래프 생성
+    word_counts[:top_n].sort_values().plot(kind="barh", ax=axes[0], title=f"Top {top_n} words")
+    
+    # 워드클라우드 생성
+    wcloud = WordCloud(background_color="white", max_words=100, 
+                width=1000, height=600, font_path=font_path)
+    wcloud.generate_from_frequencies(word_counts)
+    
+    # 워드클라우드 출력 
+    axes[1].axis("off")
+    axes[1].imshow(wcloud, interpolation="bilinear")
+    
+    plt.show()
+
+
+def get_dataframe_from_doc(doc):
+    """spaCy Doc 객체의 토큰별 정보를 추출하여 Pandas DataFrame으로 변환.
+
+    이 함수는 각 토큰의 원문, 소문자, 표제어, 품사 및 속성(문자 여부, 불용어 여부 등)을
+    딕셔너리 리스트로 구성한 후 데이터프레임으로 반환.
+
+    Args:
+        doc (spacy.tokens.doc.Doc): spaCy의 nlp() 파이프라인을 거친 Doc 객체.
+
+    Returns:
+        pd.DataFrame: 토큰별 언어학적 속성을 컬럼으로 가지는 데이터프레임.
+    """
+    # 리스트 컴프리헨션을 사용하여 각 토큰의 속성을 딕셔너리 형태로 추출
+    token_data = [
+        {
+            "token": token.text,        # 토큰 
+            "lower": token.lower_,      # 소문자화된 텍스트
+            "lemma": token.lemma_,      # 단어의 기본형 (표제어)
+            "pos": token.pos_,          # 단순화된 품사 태그 (예: NOUN, VERB)
+            "is_alpha": token.is_alpha, # 알파벳 문자로만 구성되었는지 여부
+            "is_digit": token.is_digit, # 숫자 [0-9]로만 구성되었는지 여부
+            "is_stop": token.is_stop,   # 해당 언어의 불용어 목록에 포함되는지 여부
+            "is_space": token.is_space, # 공백 문자인지 여부
+            "is_punct": token.is_punct, # 문장 부호(구두점)인지 여부
+        } 
+        for token in doc
+    ]
+    
+    return pd.DataFrame(token_data)
+
+
+def strip_accents(text):
+    """엑센트가 포함된 문자에서 엑센터를 제거하는 함수
+    """
+    # NFD로 분해 후 비간격 부호(Mn)를 제거하여 기저 문자만 남김
+    return "".join(c for c in unicodedata.normalize('NFD', text)
+                   if unicodedata.category(c) != 'Mn')
+    
+class SpacyTokenizer:
+    """spaCy를 활용하여 텍스트 토큰화 및 표제어 추출을 수행하는 클래스.
+
+    이 클래스는 기본적으로 영어 모델('en_core_web_sm')을 사용하도록 설정되어 있으며,
+    모델 설치 여부를 자동으로 확인하여 필요 시 다운로드를 수행합니다.
+
+    Attributes:
+        nlp (spacy.lang.en.English): 로드된 spaCy 언어 모델 객체.
+    """
+
+    def __init__(self, model_name: str = "en_core_web_sm"):
+        """SpacyTokenizer를 초기화하고 지정된 언어 모델을 로드함.
+
+        Args:
+            model_name (str): 사용할 spaCy 모델의 이름. 기본값은 "en_core_web_sm".
+
+        Raises:
+            OSError: 모델 다운로드에 실패하거나 로드할 수 없을 때 발생.
+        """
+        try:
+            if not is_package(model_name):
+                print(f"모델 '{model_name}'이 설치되어 있지 않습니다. 다운로드를 시작합니다...")
+                spacy.cli.download(model_name)
+            
+            # 속도 최적화를 위해 구문 분석기(Parser)와 개체명 인식기(NER) 비활성화
+            self.nlp = spacy.load(model_name, disable=["ner", "parser"])
+        except Exception as e:
+            raise OSError(f"모델 로드 실패: {e}\n'python -m spacy download {model_name}' 명령어를 확인하세요.")
+
+    def _process_pipe(self, texts: Union[str, Iterable[str]], attr_name: str, filter_stop: bool, batch_size: int = 1000, n_process: int = -1) -> Union[List[str], List[List[str]]]:
+        """ nlp.pipe을 사용하여 입력을 배치 처리하는 내부 메서드. """
+        
+        # 1. 입력이 단일 문자열인 경우 리스트로 래핑
+        is_single_input = isinstance(texts, str)
+        if is_single_input:
+            texts = [texts]
+        
+        # 2. Pandas Series 대응 및 결측치(NaN) 처리
+        if isinstance(texts, pd.Series):
+            texts = texts.fillna("").astype(str).tolist()
+        
+        # 3. nlp.pipe 실행 (GPU 서버 환경이라면 n_process를 코어 수에 맞춰 조절 가능)
+        # 
+        docs = self.nlp.pipe(texts, batch_size=batch_size, n_process=n_process)
+        
+        results = []
+        for doc in docs:
+            tokens = [
+                getattr(token, attr_name) for token in doc 
+                if not token.is_space and not token.is_punct 
+                and (not (filter_stop and token.is_stop))
+            ]
+            results.append(tokens)
+            
+        # 4. 입력 형식이 단일 문자열이었다면 단일 리스트 반환, 아니면 중첩 리스트 반환
+        return results[0] if is_single_input else results
+
+    def tokenize(self, texts: Union[str, Iterable[str]], filter_stop: bool = True, **kwargs) -> Union[List[str], List[List[str]]]:
+        """ 텍스트(들)를 소문자 토큰 리스트(들)로 반환. """
+        return self._process_pipe(texts, "lower_", filter_stop, **kwargs)
+
+    def lemmatize(self, texts: Union[str, Iterable[str]], filter_stop: bool = True, **kwargs) -> Union[List[str], List[List[str]]]:
+        """ 텍스트(들)에서 표제어(기본형) 리스트(들)를 추출. """
+        return self._process_pipe(texts, "lemma_", filter_stop, **kwargs)
+
+    def get_token_dataframe(self, text):
+        """텍스트를 토큰화한 결과를 데이터프레임으로 반환
+
+        Args:
+            text (str): 입력 텍스트.
+
+        Returns:
+            pd.DataFrame: 토큰별 언어학적 속성을 컬럼으로 가지는 데이터프레임.
+        """
+        doc = self.nlp(text)
+        return get_dataframe_from_doc(doc) 
+
+    def add_stop_words(self, words):
+        """불용어 사전에 단어를 추가합니다.
+
+        Args:
+            words (str list): 제외할 단어의 리스트
+        """
+        for word in words:
+            self.nlp.vocab[word].is_stop = True
+
+        print(f"불용어 추가 완료: {words}")
+
+def get_dataframe_from_kiwi_tokens(tokens):
+    """Kiwi 토큰 리스트를 Pandas DataFrame으로 변환합니다.
+
+    Args:
+        tokens (list[kiwipiepy.Token]): Kiwi 형태소 분석기에서 반환된 토큰 객체 리스트.
+
+    Returns:
+        pd.DataFrame: 'token'(형태), 'pos'(품사), 'lemma'(표제어) 컬럼을 포함하는 데이터프레임.
+    """
+    token_data = [
+        {
+            "token": token.form,
+            "pos": token.tag,
+            "lemma": token.lemma,
+        }
+        for token in tokens
+    ]
+    return pd.DataFrame(token_data)
+
+def filter_tokens_by_tags(tokens, selected_tags=None):
+    """특정 품사 태그를 기준으로 토큰의 표제어 리스트를 반환합니다.
+
+    Args:
+        tokens (list[kiwipiepy.Token]): Kiwi 형태소 분석 결과 토큰 리스트.
+        selected_tags (list[str], optional): 필터링할 품사 태그 리스트. 
+            None일 경우 모든 토큰의 표제어를 반환합니다.
+
+    Returns:
+        list[str]: 필터링된 토큰들의 표제어(lemma) 리스트.
+    """
+    if selected_tags is None:
+        return [token.lemma for token in tokens]
+    
+    tag_set = set(selected_tags)
+    return [token.lemma for token in tokens if token.tag in tag_set]
+
+class KiwiTokenizer:
+    """Kiwi를 활용하여 텍스트를 토큰화하고 필터링하는 기능을 제공하는 클래스.
+
+    Attributes:
+        NOUN_TAGS (list[str]): 일반 명사 및 고유 명사 태그.
+        NOUN_VERB_ADJ_ADV_TAGS (list[str]): 주요 품사(명사, 동사, 형용사, 부사) 태그.
+        kiwi (kiwipiepy.Kiwi): Kiwi 형태소 분석기 인스턴스.
+        stopwords (kiwipiepy.Stopwords, optional): 불용어 관리 객체.
+    """
+    
+    NOUN_TAGS = ["NNG", "NNP"]
+    NOUN_VERB_ADJ_ADV_TAGS = ["NNG", "NNP", "VV", "VV-R", "VV-I", "VA", "VA-R", "VA-I", "MAG"]
+
+    def __init__(self):
+        """KiwiTokenizer 인스턴스를 초기화합니다.
+
+        Args:
+            stop_words (bool): True일 경우 기본 불용어 사전을 로드합니다. 기본값은 True.
+        """
+        self.kiwi = Kiwi()
+        self.stopwords = Stopwords() 
+
+    def get_tokens(self, text, filter_stop=True):
+        """텍스트를 형태소 분석하여 토큰 리스트를 반환합니다.
+
+        Args:
+            text (str): 분석할 입력 문자열.
+            filter_stop (boolean): 불용어를 제거할지 여부
+
+        Returns:
+            list[kiwipiepy.Token]: 분석된 토큰 객체 리스트.
+        """
+        if filter_stop:
+            return self.kiwi.tokenize(text, stopwords=self.stopwords)
+        else:
+            return self.kiwi.tokenize(text)
+
+    def get_token_dataframe(self, text):
+        """텍스트 분석 결과를 데이터프레임으로 반환합니다.
+
+        Args:
+            text (str): 분석할 입력 문자열.
+
+        Returns:
+            pd.DataFrame: 형태소 정보가 담긴 데이터프레임.
+        """
+        tokens = self.get_tokens(text)
+        return get_dataframe_from_kiwi_tokens(tokens)
+
+    def tokenize(self, text, filter_stop=True, tags=NOUN_VERB_ADJ_ADV_TAGS):
+        """설정된 품사 필터에 따라 텍스트를 토큰화하고 표제어 리스트를 반환합니다.
+
+        Args:
+            text (str): 분석할 입력 문자열.
+
+        Returns:
+            list[str]: 필터링된 표제어 리스트.
+        """
+        tokens = self.get_tokens(text, filter_stop)
+        if isinstance(tokens, map):
+            return [filter_tokens_by_tags(tokens_item, tags) for tokens_item in tokens]
+        return filter_tokens_by_tags(tokens, tags)
+
+    def noun_tokenize(self, text, filter_stop=True):
+        """텍스트를 토큰화하여 명사의 표제어 리스트만 반환합니다.
+
+        Args:
+            text (str): 분석할 입력 문자열.
+
+        Returns:
+            list[str]: 필터링된 표제어 리스트.
+        """
+        return self.tokenize(text, filter_stop, self.NOUN_TAGS)
+
+    def add_stop_word(self, word, tag=None):
+            """불용어 사전에 단어를 추가합니다.
+
+            Args:
+                word (str): 제외할 단어 (예: '정말', '것').
+                tag (str, optional): 특정 품사의 단어만 제외하고 싶을 때 지정 (예: 'MAG').
+                    None이면 해당 단어의 모든 품사를 제외합니다.
+            """
+            if tag:
+                self.stopwords.add((word, tag))
+            else:
+                self.stopwords.add(word)
+            print(f"불용어 추가 완료: {word}{f'({tag})' if tag else ''}")
+
+    def add_stop_words(self, stopwords_list):
+        """여러 개의 불용어를 리스트로 받아 한꺼번에 추가합니다."""
+        for word in stopwords_list:
+            self.add_stop_word(word)
+
+def compare_words(wv, words1, words2):
+    # 단어 존재 여부 사전 필터링 (OOV 에러 방지)
+    valid_words1 = [w for w in words1 if w in wv]
+    valid_words2 = [b for b in words2 if b in wv]
+    
+    if not valid_words1 or not valid_words2:
+        print("경고: 모델에 존재하지 않는 단어가 포함되어 있습니다.")
+        return None
+
+    # 데이터 프레임 생성
+    data = []
+    for word1 in valid_words1:
+        row = {word2: wv.similarity(word1, word2) for word2 in valid_words2}
+        data.append(row)
+    
+    df = pd.DataFrame(data, index=valid_words1)
+
+    # 시각화 
+    df.plot(kind="bar")
+    plt.xticks(rotation=0)
+    plt.show()
+
+    return df # 데이터 분석 결과를 리턴하여 재사용 가능하게 함
+
+def compare_brands(wv, brands, attrs):
+    return compare_words(wv, brands, attrs) 
+
+def visualize_embeddings(wv, words, method='pca'):
+    # 1. 시각화할 단어들의 벡터 추출
+    vectors = np.array([wv[w] for w in words if w in wv])
+    labels = [w for w in words if w in wv]
+
+    # 2. 차원 축소 모델 선택
+    if method.lower() == 'pca':
+        reducer = PCA(n_components=2)
+    else:
+        reducer = TSNE(n_components=2, perplexity=min(5, len(labels)-1), random_state=42)
+    
+    result = reducer.fit_transform(vectors)
+
+    # 3. 시각화
+    plt.figure(figsize=(10, 8))
+    plt.scatter(result[:, 0], result[:, 1], edgecolors='k', c='skyblue')
+
+    for i, label in enumerate(labels):
+        plt.annotate(label, xy=(result[i, 0], result[i, 1]), xytext=(5, 2),
+                     textcoords='offset points', ha='right', va='bottom')
+
+    plt.title(f"Word Embedding Visualization ({method.upper()})")
+    plt.grid(True)
+    plt.show()
+
+
+def plot_word_dendrogram(wv, words, method='average', metric='cosine'):
+    """
+    Gensim 단어 임베딩을 사용하여 병합 군집화를 수행하고 덴드로그램을 시각화합니다.
+    
+    Args:
+        wv: 학습된 Gensim Word2Vec/FastText의 wv 객체
+        words: 군집화할 단어 리스트
+        method: 군집 결합 방식 ('ward', 'complete', 'average' 등)
+        metric: 거리 계산 척도 ('euclidean', 'cosine' 등)
+    """
+    
+    # 1. Filter valid words (OOV Handling)
+    valid_words = [w for w in words if w in wv]
+    if len(valid_words) < 2:
+        print("경고: 군집화를 위한 유효 단어가 부족합니다. (최소 2개 필요)")
+        return
+    
+    # 2. Extract vectors
+    word_vectors = np.array([wv[w] for w in valid_words])
+    
+    # 3. Perform Hierarchical Clustering
+    linked = linkage(word_vectors, method=method, metric=metric)
+    
+    # 4. Visualization (Dendrogram)
+    plt.figure(figsize=(12, 7))
+    dendrogram(linked,
+               orientation='top',
+               labels=valid_words,
+               distance_sort='descending',
+               show_leaf_counts=True,
+               leaf_font_size=12)
+    
+    # Titles and Labels
+    plt.title(f"Hierarchical Clustering of Word Embeddings (Method: {method})", fontsize=15)
+    plt.xlabel("Words")
+    plt.ylabel("Distance (Similarity Threshold)")
+    
+    # Cut-off line for visual reference
+    #plt.axhline(y=linked[-3, 2], color='r', linestyle='--') 
+    
+    plt.show()
+
+
+def print_wv_similar_words(wv, words, topn=5):
+    for word in words:
+        similar_words = [similar_word for similar_word, _ 
+            in wv.most_similar(word, topn=topn)]
+        print(f"{word}: {', '.join(similar_words)}")
+
+# 감성분석을 위한 디폴트 시스템 메시지
+DEFALT_SYSTEM_MESSAGE="""
+너는 숙련된 데이터 분석가야. 입력된 영화 리뷰를 분석하여 감성을 분류하는 역할을 수행한다.
+
+[Constrains]
+1. 분류 기준: 긍정적이면 'pos', 부정적이면 'neg'로 분류한다.
+2. 출력 형식: 반드시 'id'와 'sent' 요소를 가진 객체들의 리스트(JSON Array) 형식으로만 응답한다.
+3. 무결성: 입력된 모든 id를 빠짐없이 포함하며, 부연 설명이나 인사말은 생략한다.
+"""
+
+def _analyze_sentiment_with_gemini(client, data, system_message=DEFALT_SYSTEM_MESSAGE):
+    """하나의 미니배치에 대하여 Gemini로 감성분석을 수행하는 함수
+
+    Args: 
+    client: google.genai.Client의 Gemini API의 클라이언트 객체
+    data: pandas.Series 형식의 감성분석할 텍스트 데이터
+    system_message: LLM에 감성분석을 지시하는 시스템 메시지
+
+    Returns: pd.Series 형식의 감성분석 결과
+    """
+
+    # 사용자 메시지를 위한 리뷰 데이터 변환 
+    input_data = [{"id": id, "text": text} for id, text in data.items()]
+
+    # 사용자 메시지
+    user_message = f"""
+    아래 JSON 형식의 데이터를 감성분석해서 JSON 형태로 반환한다.
+    JSON 데이터에서 id는 식별자이고, text는 감성분석을 수행해야 할 텍스트이다.
+
+    데이터:
+
+    {json.dumps(input_data, ensure_ascii=False)}
+    """
+
+    # LLM 호출
+    response = client.models.generate_content(
+        model="gemini-2.5-flash",
+        contents=user_message,               # 사용자 메시지
+        config=genai.types.GenerateContentConfig(
+            system_instruction=system_message,   # 시스템 메시지
+            response_mime_type="application/json"  # 반환 형식 지정
+        )
+    )
+
+    # LLM 결과를 시리즈 형태로 변환 
+    result_df = pd.DataFrame(json.loads(response.text)).set_index("id") 
+    sent_result = result_df["sent"]
+
+    # 원본 인덱스가 결과 인덱스에 모두 있는지 파악
+    check_all_exists = data.index.isin(sent_result.index) 
+    if not check_all_exists.all():
+        missing_indices = data.index[~check_all_exists].tolist()
+        raise ValueError(f"오류: 다음 인덱스가 분석에제 누락되었습니다: {missing_indices}")
+
+    # 리뷰의 인덱스 순서에 맞추어 결과 반환
+    return sent_result.reindex(data.index)
+
+def analyze_sentiment_with_gemini(client, data, system_message, 
+                                  batch_size=10, n_batches=5):
+    """Gemini로 영화평을 미니배치로 감성분석을 수행하는 함수
+    _analyze_sentiment_with_gemini를 미니배치로 반복적으로 호출한다.
+
+    Args: 
+    client: google.genai.Client의 Gemini API의 클라이언트 객체
+    data: pandas.Series 형식의 감성분석할 데이터
+    system_message: LLM에 감성분석을 지시하는 시스템 메시지
+    batch_size: 미니배치의 크기
+    n_batches: 처리할 배치의 수
+
+    Returns: pd.Series 형식의 감성분석 결과
+    """
+    result = []
+    for i in range(n_batches):
+        start = i * batch_size
+        end = (i+1) * batch_size
+        result.append(_analyze_sentiment_with_gemini(client, data[start:end], system_message))
+        if end >= len(data):
+            break
+    return pd.concat(result)
+
+def generate_few_shot_prompt(X_train, y_train, n_shots=10):
+    """
+    훈련 데이터셋에서 n개의 사례를 뽑아 Few-shot 지시문을 생성합니다.
+    """
+    few_shot_text = ""
+    
+    for i in range(n_shots):
+        # 특수문자 및 한국어 처리를 위해 json.dumps 활용 
+        # 문자열 내부에 따옴표나 줄바꿈이 있어도 안전하게 변환
+        id = X_train.index[i]
+        input_json = json.dumps({"id": int(id), "text": X_train[id]}, ensure_ascii=False)
+        output_json = json.dumps({"id": int(id), "sent": y_train[id]}, ensure_ascii=False)
+        
+        few_shot_text += f"[Input]\n{input_json}\n"
+        few_shot_text += f"[Output]\n{output_json}\n\n"
+        
+    return few_shot_text

ktmu-0.1.1/src/ktmu.egg-info/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.4
+Name: ktmu
+Version: 0.1.1
+Summary: Korean Text Mining utilities for visualization, NLP, and LLM analysis
+Author-email: Kilhwan Kim <khkim@smu.ac.kr>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Text Processing :: Linguistic
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: matplotlib
+Requires-Dist: wordcloud
+Requires-Dist: spacy
+Requires-Dist: kiwipiepy
+Requires-Dist: scikit-learn
+Requires-Dist: scipy
+Requires-Dist: google-genai
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+Dynamic: license-file
+
+# ktmu: Korean Text Mining Utilities
+
+`ktmu`는 텍스트 데이터의 전처리, 시각화, 언어 모델 연동을 통합적으로 지원하기 위한 파이썬 패키지입니다. 특히 한국어(Kiwi)와 영어(spaCy) 형태소 분석을 일관된 인터페이스로 제공하며, 최신 LLM(Gemini)을 활용한 분석 기능을 포함하고 있습니다.
+
+## 주요 기능
+
+* **다양한 시각화 지원**: 토큰 빈도 막대 그래프, 워드클라우드, 임베딩 차원 축소(PCA/t-SNE), 계층적 군집화 덴드로그램 출력.
+* **통합 형태소 분석 인터페이스**: `SpacyTokenizer`(영어) 및 `KiwiTokenizer`(한국어) 클래스를 통한 손쉬운 토큰화 및 표제어 추출.
+* **Pandas 연동**: 모든 분석 결과(토큰, 형태소 정보 등)를 즉시 DataFrame으로 변환하여 데이터 분석 파이프라인에 활용 가능.
+* **LLM 감성 분석**: Google Gemini API를 활용한 대규모 텍스트 데이터의 배치 감성 분석 기능.
+* **임베딩 분석**: Gensim 모델과 연동하여 단어 간 유사도 비교 및 시각화.
+
+## 설치 방법
+
+패키지는 다음과 같이 설치합니다.
+
+```bash
+pip install ktmu
+```
+
+## 사용 예시
+
+### 1. 한국어 형태소 분석 (Kiwi)
+
+```python
+from ktmu import KiwiTokenizer
+
+tokenizer = KiwiTokenizer()
+text = "텍스트 마이닝은 정말 재밌는 학문입니다."
+
+# 토큰화 및 데이터프레임 변환
+df = tokenizer.get_token_dataframe(text)
+print(df)
+
+# 명사만 추출
+nouns = tokenizer.noun_tokenize(text)
+print(nouns)
+```
+
+### 2. 빈도 시각화
+
+```python
+from ktmu import visualize_tokens
+
+tokens = ["데이터", "분석", "데이터", "AI", "텍스트", "분석", "데이터"]
+visualize_tokens(tokens, top_n=10)
+```
+
+### 3. Gemini를 활용한 감성 분석
+
+```python
+import pandas as pd
+from google import genai
+from ktmu import analyze_sentiment_with_gemini
+
+client = genai.Client(api_key="YOUR_API_KEY")
+reviews = pd.Series(["이 영화 정말 재밌어요!", "시간 아까워요..."], name="review")
+
+# 배치 감성 분석 수행
+results = analyze_sentiment_with_gemini(client, reviews, system_message="감성 분석 전문가로서 응답해줘.")
+print(results)
+```
+
+### 4. 워드 임베딩 시각화
+
+```python
+from ktmu import visualize_embeddings
+
+# gensim의 word vector 객체(wv)가 있다고 가정
+words = ["사과", "바나나", "컴퓨터", "키보드"]
+visualize_embeddings(wv, words, method='pca')
+```
+
+## 의존성
+
+이 패키지는 다음 라이브러리들을 사용합니다:
+* `pandas`, `numpy`, `matplotlib`
+* `spacy`, `kiwipiepy`
+* `scikit-learn`, `scipy`
+* `wordcloud`, `google-genai`
+
+## 라이선스
+
+이 프로젝트는 **LGPL-3.0** 라이선스 하에 배포됩니다. 

ktmu-0.1.1/src/ktmu.egg-info/SOURCES.txt

@@ -0,0 +1,10 @@
+LICENSE
+README.md
+pyproject.toml
+src/ktmu/__init__.py
+src/ktmu/main.py
+src/ktmu.egg-info/PKG-INFO
+src/ktmu.egg-info/SOURCES.txt
+src/ktmu.egg-info/dependency_links.txt
+src/ktmu.egg-info/requires.txt
+src/ktmu.egg-info/top_level.txt

ktmu-0.1.1/src/ktmu.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ktmu-0.1.1/src/ktmu.egg-info/requires.txt

@@ -0,0 +1,13 @@
+pandas
+numpy
+matplotlib
+wordcloud
+spacy
+kiwipiepy
+scikit-learn
+scipy
+google-genai
+
+[dev]
+pytest
+black

ktmu-0.1.1/src/ktmu.egg-info/top_level.txt

@@ -0,0 +1 @@
+ktmu