KotobaCore

English | 日本語

日本語テキストの意味を構造化データに変換するセマンティックエンジン。
LLM前処理・RAG・SNS解析・AIエージェント入力に使えます。

何ができるか

from kotobacore import Analyzer

result = Analyzer().analyze("クラウドAPIの課金高すぎてしぬw")

chunks   : ["クラウドAPI", "課金高すぎ", "しぬw"]
emotion  : anger / negative  (Plutchik: anger+disgust)
intent   : pricing_complaint
keywords : ["クラウドAPI", "課金"]

単なるトークナイザーではなく、感情・意図・RAGキーワードまで一括で返すのが特徴です。

パイプライン

入力テキスト
  └─ 正規化 (NFKC / SNS表現保持)
       └─ トークナイズ — Karuizawa (外部依存ゼロの内蔵トークナイザー)
          v0.2〜 格子+Viterbi の一発分割 (辞書表層/文法形態素/活用組み立て/
          交ぜ書き複合語をノード提案し、接続コスト付き最良経路探索で確定)
            └─ セマンティックチャンク生成
                 ├─ 感情検出 (節分割・否定スコープ・逆接考慮) + Plutchik 8軸
                 ├─ 意図分類 (ルール + 文末形式 + 感情連動)
                 └─ RAGキーワード抽出

感情モデル — Plutchik の感情の輪

KotobaCore は心理学者 Robert Plutchik が提唱した 8基本感情モデル をベースにしています。
怒り・恐れ・喜び・悲しみ・信頼・嫌悪・驚き・期待の8軸で感情を分類し、
テキストの感情を primary / polarity / plutchik_axes として構造化して返します。

内蔵辞書

KotobaCore の判定は機械学習モデルではなく、同梱の人手メンテナンス辞書（プレーンな CSV） に基づきます。 モデルのダウンロードや学習は不要で、CSV を編集するだけで語彙・ルールを追加・調整できます（resources/dict/）。

entity.csv の内訳は組織 571（日本の主要企業 400 社超・行政機関・国際機関）/ トピック 363（歴史・宗教・言語・食・祝日等）/ 地名 279（国名 117 含む）/ 人名 272 / ブランド 195 / 作品 59 / サービス 39 ほか。

Japanese-SNS-Emotion-Examples-v1.txt も resources/dict/ に同梱され、デフォルトで読み込まれます（外部辞書なしでも例文マッチが効きます）。 各行の examples（「、」区切りの複数例文）が展開され、入力文との bigram Jaccard 類似度で感情の confidence を補強します。

任意の外部辞書（NRC、非同梱）

唯一の 非同梱 辞書が NRC Emotion Intensity Lexicon（約 9,800 語 / 8 Plutchik 感情の強度辞書）です。 dic/（環境変数 KOTOBACORE_DIC_DIR で指定）に置くと、内部辞書に無い感情語を 検出語彙として追加 します （内部辞書 lex_weight=1.0 に対し外部は 0.5 の低めの重みで、文学的・稀少語を補完）。無くても内蔵辞書だけで動作します。

感情の confidence は lex_weight × 0.5 + ex_sim × 0.3 + intensity × 0.2 で算出され、 NRC は第1項（検出語彙）、同梱の SNS 例文は第2項（類似度）に効きます。

NRC 辞書の入手方法

⚠️ ライセンス注意: NRC Emotion Intensity Lexicon は 再配布が禁止 されているため本リポジトリには含まれません。 各自で公式ページから入手してください。非商用の研究用途は無償ですが、商用利用には NRC の商用ライセンスが別途必要 です。 利用時は下記の引用と帰属表示が求められます。必ず公式ページの利用規約をご自身で確認してください。

1. 公式ページ NRC Emotion/Affect Intensity Lexicon から辞書を入手します（多言語自動翻訳版に日本語が含まれます）。
   • https://saifmohammad.com/WebPages/AffectIntensity.htm
2. 日本語訳データを次の タブ区切り (TSV) 4 列 形式に整え、dic/ に配置します。

   English Word<TAB>Emotion<TAB>Emotion-Intensity-Score<TAB>Japanese Word
   

   • ファイル名: dic/Japanese-NRC-Emotion-Intensity-Lexicon-v1.txt
   • Emotion は 8 軸（anger / anticipation / disgust / fear / joy / sadness / surprise / trust）
3. dic/ の場所は次の順で探索されます: 環境変数 KOTOBACORE_DIC_DIR → <project>/dic → <project>/../dic。

引用（必須）:

@inproceedings{LREC18-AIL,
  author    = {Mohammad, Saif M.},
  title     = {Word Affect Intensities},
  booktitle = {Proceedings of the 11th Edition of the Language Resources
               and Evaluation Conference (LREC-2018)},
  year      = {2018},
  address   = {Miyazaki, Japan}
}

帰属表示の例: "This product makes use of the NRC Emotion Intensity Lexicon, created by Saif M. Mohammad at the National Research Council Canada."

from kotobacore.dictionary import load_user_bundle
bundle = load_user_bundle()   # 内蔵 seed + 同梱 SNS 例文 + (あれば) dic/ の NRC を統合

インストール

git clone https://github.com/ekiyo55/kotobacore.git
cd kotobacore
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .[dev,ui]

Python API

from kotobacore import Analyzer

result = Analyzer().analyze("クラウドAPIの課金高すぎてしぬw")
print(result.to_json())

トークン粒度 (granularity)

既定の coarse は意味単位 (思い出した / 締め切り) を 1 トークンに保ちます。 言語モデルの語彙を作る用途などで細かい表層が欲しい場合は fine を指定すると、 組み立てた動詞・形容詞・交ぜ書き複合語・未知ひらがなランを 語幹 / 送り仮名 / 活用語尾に分解します (辞書エンティティは割りません)。

Analyzer(granularity="fine").tokenize("思い出した")
# 思(動詞-語幹) い(送り仮名) 出(動詞-語幹) した(動詞-活用語尾)

analyze() の chunks / emotion / intent / rag は粒度に関係なく coarse で計算されます。

出力 JSON 構造

{
  "chunks": [
    {"id": 0, "text": "クラウドAPI", "type": "service",      "score": 0.96},
    {"id": 1, "text": "課金高すぎ",  "type": "complaint",    "score": 0.88},
    {"id": 2, "text": "しぬw",       "type": "slang_emotion","score": 0.88}
  ],
  "emotion": {
    "primary": "anger",
    "polarity": "negative",
    "intensity": 0.82,
    "plutchik_axes": ["anger", "disgust"]
  },
  "intent": {"label": "pricing_complaint", "score": 0.85},
  "rag": {
    "keywords": ["クラウドAPI", "課金"],
    "search_query": "クラウドAPI 課金",
    "summary_hint": "pricing complaint about cloud API"
  }
}

CLI

kotobacore analyze "今日のランチが絶品だった" --pretty
kotobacore tokenize "東京都に行った"
kotobacore tokenize "思い出した" --granularity fine
kotobacore version

Demo UI

streamlit run tools/demo_ui/streamlit_app.py
# → http://localhost:8501

公開デモ: https://kotobacore.mooma.style/

他ライブラリとの比較

KotobaCoreが埋めているのは「感情・意図・RAGキーワードを一つのパイプラインで構造化JSON化する」領域です。

ステータス

v0.2.2 pre-alpha。5000例文の品質評価で 感情正確度 95.2% / 極性正確度 96.0% / 意図正確度 68.1% / 意図検出率 70.8%、処理エラー 0件。処理速度はサーバー実機で 1文あたり平均 1.81ms（p99 2.35ms、外部依存ゼロ）。 186 テスト全 PASS（実文ゴールデンセット 36文を含む）。

v0.2 の主な変更: Karuizawa の格子+Viterbi 一発分割（bigram 接続コストで 「すもももももももものうち」も完全解）、否定スコープ処理（好きじゃない → negative）、 節分割による逆接考慮（〜でしたが成功しました → positive）、Aho-Corasick 統一マッチ層。 詳細は CHANGELOG を参照。

ライセンス

Apache License 2.0