Skip to main content

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

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.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for kouchou-ai-analysis-core 0.3.0
File Size Uploaded Provenance Actions
kouchou_ai_analysis_core-0.3.0.tar.gz 291.5 kB Without provenance Details for kouchou_ai_analysis_core-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for kouchou-ai-analysis-core 0.3.0
File Interpreter ABI Platform Actions
kouchou_ai_analysis_core-0.3.0-py3-none-any.whl Python 3 none any Details for kouchou_ai_analysis_core-0.3.0-py3-none-any.whl

Total release size: 500.2 kB

Release files / kouchou_ai_analysis_core-0.3.0.tar.gz

Download URL kouchou_ai_analysis_core-0.3.0.tar.gz
Size 291.5 kB
Tags Source
SHA-256 checksum
How to use checksums
e49d4de1fd0f649b4b428e3bb7cb90afd6080d4a4d97dbdbbd28cbeb2c33dade
BLAKE2b-256 checksum
How to use checksums
5f59bc85c56a372e649b414dc1588f1a93e968d84f7781d3be1e37a5be24a357
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.3.0-py3-none-any.whl

Download URL kouchou_ai_analysis_core-0.3.0-py3-none-any.whl
Size 208.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0617e26b1da16c04d373976c0b8de5f6c05d529d0ca3bbb675aa4b97946775e8
BLAKE2b-256 checksum
How to use checksums
cc2f8cacc4db85e898d7e17c5e3e6f15fbe8a3ea3e50b72b838eb032fd81feb8
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.3.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.

Release history Release notifications | RSS feed

This release

0.3.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page