kouchou-ai-analysis-core
広聴AIの分析パイプラインコアライブラリ。
概要
このパッケージは、コメントデータを分析し、クラスタリングと要約を行うパイプラインを提供します。
必要条件
- Python 3.12以上
インストール
pip install 'kouchou-ai-analysis-core[embeddings,clustering]'
Geminiサポートを含める場合:
pip install 'kouchou-ai-analysis-core[gemini,embeddings,clustering]'
軽量な base install だけ欲しい場合:
pip install kouchou-ai-analysis-core
この場合でも import analysis_core や dry-run はできますが、local embedding や hierarchical clustering を実行するには対応する extras が必要です。
使用方法
詳細なチュートリアルは以下を参照してください:
- CLIクイックスタート - コマンドラインからの利用
- インポート方法 - Python スクリプトからの利用
CLI
kouchou-analyze --config config.json
CLI の canonical output は hierarchical_result.json です。既定ではローカル確認用の補助 HTML として report.html も生成しますが、これは保存・配信の対象ではありません。
ライブラリとして
from analysis_core import PipelineOrchestrator, PipelineConfig
config = PipelineConfig.from_json("config.json")
orchestrator = PipelineOrchestrator.from_dict(config.to_dict())
result = orchestrator.run_default()
run_default() が current の canonical path です。run() も残っていますが、legacy direct-step 実行経路として deprecated 扱いです。
レポート本文の翻訳(多言語表示)
分析が終わった hierarchical_result.json の本文を LLM で他言語に翻訳し、translations に書き込みます。public-viewer の言語切替(日本語 / English / 한국어)は、表示言語の訳がこのフィールドにあれば本文を差し替え、無ければ元の言語のまま表示します。パイプラインの一部ではなく、分析後に必要な言語だけ追加する後処理です。
# 意見グループ名・説明・概要・問い・イントロを英語と韓国語に翻訳して上書き
kouchou-translate --result outputs/<name>/hierarchical_result.json --languages en,ko
# 元を残して別ファイルへ書き出す / 対象件数だけ確認する
kouchou-translate --result outputs/<name>/hierarchical_result.json --languages en --output translated.json
kouchou-translate --result outputs/<name>/hierarchical_result.json --languages en --dry-run
python -m analysis_core.translate でも同じです。プロバイダーとモデルは結果 JSON の config.provider / config.model を既定にし、--provider --model --local-llm-address で上書きできます(provider=local なら Ollama などの OpenAI 互換 API)。API キーはサーバーの環境変数(OPENAI_API_KEY など)を使います。結果 JSON の config に残った user_api_key は読まず、書き戻すときに config から取り除きます。
- 既定で翻訳するのは意見グループ(label / takeaway)、
overview、config.question、config.introです。意見本文は件数が多く費用がかさむため、--include-argumentsを付けたときだけ翻訳します。意見本文の訳が無い言語では、散布図のホバーや階層リストの意見は元の言語で表示されます。 - 1リクエストに
--batch-size(既定 10)件をまとめて送り、--workers(既定 2)で並列にします。欠けた項目は 1 件ずつ再送し、それでも失敗した項目があれば id と失敗種別だけを示して終了し、ファイルは書き換えません。 - 既に他の言語の訳があればそのまま残し、同じ言語は上書きします。各言語の
metaに使ったモデルと生成日時を記録します。 --resultを上書きするときは、同じディレクトリのtranslations.jsonにも訳を残します。集計(管理画面で意見グループ名・タイトルを編集した後の再集計や、CLI の再実行)はhierarchical_result.jsonを作り直しますが、訳はtranslations.jsonから読み直されるので消えません。ただし、原文(意見グループ名・説明・概要・問い・イントロ・意見)が変わった項目の訳は、古い訳を出さないよう落とします(その項目は元の言語で表示されます)。編集した項目も訳したいときは、もう一度実行してください。--outputで別ファイルに書き出すときはtranslations.jsonを作りません。- 書き込みは一時ファイルから差し替えるので、公開中のレポートが書きかけのファイルを読むことはありません。翻訳の間に結果が作り直された(編集・再集計があった)ときや、分析・再集計の実行中(
hierarchical_status.jsonが running)のときは、何も書き換えずにエラーで終了します。もう一度実行してください。 - 管理画面(API)でストレージ(Azure Blob など)を使って運用しているレポートでは、サーバー上で翻訳しただけではストレージの版は変わりません。ストレージに上がるのは次の再集計などで同期されたときで、それまでにサーバーが再起動すると、ストレージの版(訳の無い版)に戻ります。
- 翻訳の品質は確認してください。意見グループ名は短い見出しとして訳すよう指示していますが、固有名詞や専門用語の訳語は元の言語で確認するのが安全です。
translations の形:
{
"en": {
"clusters": {"1": {"label": "Transport", "takeaway": "..."}},
"overview": "...",
"question": "...",
"intro": "...",
"arguments": {"A1_0": "..."},
"meta": {"provider": "openai", "model": "gpt-4o-mini", "generated_at": "..."}
}
}
プラグインシステム
analysis-core は拡張可能なプラグインアーキテクチャを採用しています。
カスタムプラグインの作成
from analysis_core.plugin import step_plugin, StepContext, StepInputs, StepOutputs
@step_plugin(
id="mycompany.custom_step",
version="1.0.0",
inputs=["arguments"],
outputs=["custom_result"],
)
def custom_step(ctx: StepContext, inputs: StepInputs, config: dict) -> StepOutputs:
# カスタム処理
output_path = ctx.output_dir / "custom_result.csv"
return StepOutputs(artifacts={"custom_result": output_path})
外部プラグインの配置
plugins/analysis/
└── my-plugin/
├── manifest.yaml
└── plugin.py
詳細は プラグイン開発ガイド を参照してください。
開発
# 依存関係のインストール
pip install -e ".[dev,embeddings,clustering]"
# テストの実行
pytest
# リンターの実行
ruff check .
ライセンス
広聴AI本体と同じ GNU Affero General Public License v3 (AGPL-3.0) です。 ライセンス全文は LICENSE を参照してください。
以前のREADMEとパッケージメタデータ(PyPI 0.1.0 / 0.1.2を含む)のMIT表記は誤りです。
analysis-core の独立パッケージ化は、ライセンスをMITへ変更するものではありません。
Metadata
Release files for kouchou-ai-analysis-core 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kouchou_ai_analysis_core-0.2.0.tar.gz | 277.3 kB | Without provenance | Details for kouchou_ai_analysis_core-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kouchou_ai_analysis_core-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for kouchou_ai_analysis_core-0.2.0-py3-none-any.whl |
Total release size: 478.6 kB
Release files / kouchou_ai_analysis_core-0.2.0.tar.gz
| Download URL | kouchou_ai_analysis_core-0.2.0.tar.gz |
|---|---|
| Size | 277.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4a36d0496ef0fd053cecc20b39a235d2c7ab8cc8bfff41ad9ce03102e820ce69
|
|
BLAKE2b-256 checksum How to use checksums |
5c9b3996c1a60ee8e1a48400a077935e64a0ef0654475195008a207cdb25a747
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Release files / kouchou_ai_analysis_core-0.2.0-py3-none-any.whl
| Download URL | kouchou_ai_analysis_core-0.2.0-py3-none-any.whl |
|---|---|
| Size | 201.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d469c6f0bc97e3be22170a3d6fe0d95ce3a998d7336ea3227106299cff9b3e66
|
|
BLAKE2b-256 checksum How to use checksums |
cc985cb0dee332a1edad19cd20bce9f8e49825dc081e254efbbb224dbe9d5394
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Security for kouchou-ai-analysis-core 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.