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キーワードまで一括で返すのが特徴です。

パイプライン

入力テキスト
  └─ 正規化 N1 文字 (NFKC / SNS表現保持) → N2 表記 (normalization.csv)
       ※ 正規化で文字数が変わっても、出力の全 span は原文の位置を指す (位置写像)
       └─ トークナイズ — Karuizawa (外部依存ゼロの内蔵トークナイザー)
          v0.2〜 格子+Viterbi の一発分割 (辞書表層/文法形態素/活用組み立て/
          交ぜ書き複合語をノード提案し、接続コスト付き最良経路探索で確定)
            └─ Core: 文・段落境界 / 節分割・否定スコープ・逆接重み / Entity (辞書+パターン+日時+数量)
                     / 述語項構造 → Relation・Event (v0.5) / 感情・評価語マッチ + 宛先付け / 句チャンク
                 ├─ Emotion   感情検出 + Plutchik 8軸 (holder / about 付き)
                 ├─ Sentiment 評価語のみの極性 (感情語は affect_polarity に分離、target 付き)
                 ├─ Intent    意図分類 (SNS 向け + Query 向け体系)
                 ├─ Topic     主題 (エンティティ + 頻出名詞、v0.5)
                 └─ RAG       キーワード抽出 / Query IR / 文書チャンク / Reranking 特徴量・参照リトリーバ (v0.5)

感情モデル — 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 で計算されます。

N4 語形正規化 (v0.6.3)

[(t.surface, t.dictionary_form, t.conjugation_type, t.conjugation_form) for t in a.tokenize("食べさせられなかったので待っています")]
# [('食べさせられなかったので', '食べる', '一段', '使役-受身-否定-過去-接続-理由'), ('待っています', '待つ', '五段', '進行-丁寧')]
[(t.surface, t.normalized) for t in a.tokenize("申込みと見積と引落")]   # 送り仮名揺れ → 本則形 (okurigana.csv)
# [('申込み', '申し込み'), ('と', 'と'), ('見積', '見積もり'), ('と', 'と'), ('引落', '引き落とし')]

辞書なしの規則で原形・活用型（五段 / 一段 / カ変 / サ変 / 形容詞 / 形容動詞）・活用形を付けます。辞書でしか決まらない曖昧（走った → 走る／走つ／走う）は最頻パターンで解き 五段? と表示します。

Entity / 宛先 / 文書 / Query IR (v0.4)

import datetime
from kotobacore import Analyzer

a = Analyzer(reference_date=datetime.date(2026, 9, 8))
r = a.analyze("株式会社山田商事の佐藤部長は10月5日に45億円の予算を発表した。コーヒーはいまいちだけどケーキは神。")
[(e.surface, e.type, e.value) for e in r.entities]
# [('株式会社山田商事','ORGANIZATION',None), ('佐藤部長','PERSON',None), ('10月5日','DATE','2026-10-05'), ('45億円','MONEY',4500000000.0)]
[(s.text, s.polarity, s.target_text) for s in r.sentiment.expressions]
# [('いまいちだ','negative','コーヒー'), ('神','positive','ケーキ')]

q = a.analyze_query("東京支店の2025年度の売上目標はいくら？")
q.intent, q.answer_type, q.target, q.constraints
# ('search_value', 'MONEY', '売上目標', {'organization': ['東京支店'], 'time': ['FY2025']})

d = a.analyze_document(open("report.md", encoding="utf-8").read())
d.paragraphs, d.sentences, d.document_chunks   # 階層 IR と検索用チャンク

# v0.6.2: 文書内の Entity 共参照 (FR-034) — 田中太郎さん / 田中さん / 田中、株式会社北斗物流 / 北斗物流 / 北斗 / 同社 を同じ canonical_id に
d = a.analyze_document("株式会社北斗物流は新倉庫を開設した。\n北斗は来年も投資する。\n同社の社長は佐藤氏だ。")
[(e.surface, e.source, e.canonical_id) for e in d.entities if e.type == "ORGANIZATION"]
# [('株式会社北斗物流','pattern','e1'), ('北斗','coreference','e1'), ('同社','coreference','e1')]
from kotobacore.core.coreference import coreference_clusters
coreference_clusters(d.entities)   # 代表 (aliases 付き) を先頭にしたクラスタ一覧

# v0.5: 述語項構造 → Event / Relation、Reranking
r = a.analyze("株式会社山田商事は2025年度に大阪支社を設立した。")
r.events[0]      # Event(type='FOUND', agent_text='株式会社山田商事', object_text='大阪支社', time_text='2025年度', ...)
r.relations[0]   # Relation(source_text='株式会社山田商事', relation='FOUND', role='object', target_text='大阪支社', ...)

from kotobacore.rag import ChunkView, rerank, InMemoryRetriever
views = [ChunkView.from_chunk(c, d) for c in d.document_chunks]
rerank(q, views)                       # [(chunk_index, score, {entity_match, keyword_overlap, intent_match, time_match, ...}), ...]
ret = InMemoryRetriever(embed=my_embedding_fn)   # Embedding は外部モデルを注入
ret.index("doc1", d); ret.search(q, k=3)

CLI: kotobacore query "…" / kotobacore chunk report.md --max-chars 400 / kotobacore analyze --document --file report.md

Vocab — 語彙表と Token ID (v0.6、任意モジュール)

日本語 LM を自作するときの語彙。fine 粒度（語幹 / 送り仮名 / 活用語尾）から語彙表を作り、テキストを整数 id 列に符号化・復号します。 語彙データはパッケージに同梱しません。IR は vocab なしで完全です。参照語彙（fine / coarse、kotobacore-vocab-1.0 形式）は別リポジトリ kotobacore-vocab で配布します。

from kotobacore.vocab import build_vocab, extend_vocab, VocabEncoder, vocab_report

vocab = build_vocab(open("corpus.txt", encoding="utf-8"), min_freq=2)   # id 0-9 は <pad> <unk> <bos> <eos> <sep> <mask> <cls> <nl> <sp> <reserved>
vocab.save("vocab.json")                                                 # 以降は頻度降順。コーパスの全文字も語彙に入る（未知語は文字へフォールバック）
enc = VocabEncoder(vocab)
ids = enc.encode("東京に行った。\n私は走った", add_special=True)         # [<bos>, 東京, に, 行, った, 。, <nl>, 私, は, 走, った, <eos>]
enc.decode(ids)                                                          # '東京に行った。\n私は走った'（正規化後テキスト）
extend_vocab(vocab, more_texts)                                          # 追記のみ。既存 id は変わらない
vocab_report(vocab, held_out_texts)                                      # coverage / OOV / <unk> 率 / 頻度分布 / 汚染候補（記号連結・同字反復・半角カナ・異常長…）

CLI: kotobacore vocab build corpus/ --out vocab.json --min-freq 2 / kotobacore vocab encode "…" --vocab vocab.json / kotobacore vocab decode "[2, 15, 7]" --vocab vocab.json / kotobacore vocab report held_out/ --vocab vocab.json --md report.md

HTTP API (v0.6.1、extra api)

pip install "kotobacore[api]"
KOTOBACORE_API_TOKEN=secret kotobacore serve --port 8590 --rate-limit 120   # /docs に OpenAPI
curl -s -X POST http://127.0.0.1:8590/query -H "Authorization: Bearer secret" \
     -H "Content-Type: application/json" -d '{"text":"東京支店の今年度の売上目標はいくら？","reference_date":"2026-09-08"}'

POST /analyze（document / reference_date / semantic_only）・/query・/chunk・/tokenize、GET /health /version。 Bearer トークン認証とクライアント別レート制限は任意（環境変数または --token / --rate-limit）。アクセスログは出さず、エラー応答に入力文を含めません。 エラーは {"error": {"code": "E701 unauthorized", "message": "…"}} の形（E1xx 入力 / E7xx API）。Python からは from kotobacore.api import create_app で FastAPI アプリを組み込めます。

出力 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"]
  },
  "sentiment": {
    "polarity": "negative",
    "affect_polarity": "negative",
    "intensity": 0.7,
    "expressions": [{"text": "高すぎ", "polarity": "negative", "target_text": "課金", "begin": 10, "end": 13, "negated": false}]
  },
  "entities": [
    {"id": "e1", "type": "SERVICE", "surface": "クラウドAPI", "begin": 0, "end": 7, "source": "dictionary"}
  ],
  "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/

他ライブラリとの比較

実測（tools/benchmark/compare_baselines.py、人手アノテーション 100 文の分割境界、速度は 300 文 × 3 周 warm。gold は KotobaCore の意味単位なので短単位の形態素解析器は R が高く P が低く出ます）:

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

ステータス

v1.0.0（2026-09-09、IR schema 1.0 凍結・全構成要素の版を 1.0 に統一。Vocab モジュール・HTTP API・Entity 共参照・N4 語形正規化〈動詞原形＋活用型/活用形、送り仮名揺れ〉・互換性マトリクス／旧 import 非推奨化・感情体系 surprise/trust/disgust と意図 inform/share_experience・括弧内固有名・人手評価セット由来の辞書拡充・§9 エラー処理〈回復可能エラーは IR.errors に積んで継続〉）。人手アノテーション 300 文（確定版 annotated_v1）で Sentiment 83% / Emotion 84% / Intent 70% / Entity F1 0.86。NFR-001: 10 万文 110 秒（908 文/s）、1 文平均 1.1 ms、1 万字文書 0.72 秒。6500例文の品質評価で 極性正確度 97% 台 / 処理エラー 0件。人手アノテーション実文 300 文 (下書き) で Entity F1 0.66・分割境界 F1 0.91・評価極性 63%。RAG 検索評価: 自作 24 文書・200 問 (妨害込み 447 チャンク) で MRR 0.769 → 0.846、実務文書 30 件 (5,174 チャンク・120 問) で 0.570 → 0.720 (コードフェンス・番号リストを壊さないチャンク + 見出しパス/導入文の文脈 + Query IR + 制約フィルタ + 再ランク〈回答の形一致を含む〉)。外部 Embedding (e5-base) とのハイブリッドでは 実務 0.777 / 自作 0.868。処理速度は 1文あたり平均 1〜3ms（外部依存ゼロ）。352 テスト全 PASS。

v0.5 の主な変更: 述語項構造 → Event / Relation（係り受け解析器なし）、Topic モジュール、Reranking 特徴量と参照リトリーバ （インメモリ / pgvector SQL）、動詞否定、評価語のラティス登録。v0.4: Entity 層、宛先付き評価・感情、文書階層、Query IR、Semantic Chunking。

v0.3 の主な変更: パッケージを Core (kotobacore.core) と IR 上のモジュール (kotobacore.modules = emotion / sentiment / intent) に再配置（旧 import パスは維持）、 正規化の位置写像（出力 span は常に原文基準）、Sentiment モジュールの分離と評価語辞書、 否定スコープの Core 移設、同義語辞書、人手アノテーション評価ランナー。

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

ドキュメント

• docs/API.md — Python API / CLI / HTTP API（認証・レート制限・エラー形）
• docs/openapi.json — HTTP API の OpenAPI 3.1（tools/gen_openapi.py で生成、/docs と同じ内容）
• docs/IR_SCHEMA.md — Semantic IR の全フィールド（tools/gen_schema_doc.py で dataclass から生成。schema 1.0）
• docs/TOKENIZATION.md — 分割基準（coarse = 意味単位 / fine = 語幹・送り仮名・活用語尾）と既知の癖
• CHANGELOG.md — 版ごとの変更と計測値

互換性マトリクス (v1.0.0、kotobacore version --matrix の出力)

1.0.0 で全構成要素を 1.0 に統一しました（IR schema は凍結。旧番号の系譜は各モジュールのコメントと resources/dict/versions.json の history に残しています）。

解析結果の meta.components に tokenizer / dictionary_set / modules の版が刻まれます（再現性）。旧 import パスは DeprecationWarning を出しつつ v1.0 まで動作し、v1.1 で削除します。kotobacore.compat（Karuizawa 互換 API）は継続します。

ライセンス

Apache License 2.0