Metadata-Version: 2.4
Name: ktmu
Version: 0.1.3
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** 라이선스 하에 배포됩니다. 
