mcpField
A
alterlab-hypogenic

alterlab-hypogenic

github.com/alterlab-ieuデータ・データベース7866 回インストール5 週間前に更新
リポジトリ

alterlab-hypogenic について

alterlab-hypogenicは、Hypogenicを利用するためのスキルです。このフレームワークはLLMを用いて、観察データや研究文献から科学的仮説を生成・検証します。データ駆動型、文献とデータの統合型、両者の組み合わせを提供し、実証研究に活用できます。

主な機能

  1. 01観察データから仮説を生成
  2. 02性能に基づく仮説の反復改良
  3. 03文献の知見と経験的なデータパターンの統合
  4. 04複数の競合仮説に対する推論
  5. 05プロンプトと分野別ラベル抽出の設定

活用シーン

  1. 01データセットから検証可能な仮説を生成
  2. 02研究論文をデータに基づく仮説研究に活用
  3. 03テストデータで複数の競合仮説を比較
  4. 04独自の研究タスク向けに仮説ワークフローを構築

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/alterlab-ieu/alterlab-academic-skills --skill alterlab-hypogenic

インストール後、Claude Code で/alterlab-hypogenicを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

evals/
evals.json
references/
config_template.yaml
custom_tasks.md
publications.md
python_api.md
repository_structure.md
workflow_examples.md

詳細

Hypogenic

概要

Hypogenic は、LLM を用いた仮説の自動生成と検証により、科学的発見を加速します。このフレームワークは、HypoGeniC（データ駆動型の仮説生成）、HypoRefine（文献とデータの相乗的な統合）、Union メソッド（文献由来とデータ駆動型の仮説を機構的に組み合わせる手法）の 3 つのアプローチをサポートします。

クイックスタート

数分で Hypogenic を使い始められます。

# Install into its own environment: hypogenic 0.3.5 pins numpy~=1.26, pandas~=2.1,
# torch~=2.4, transformers~=4.45, openai~=1.40 and anthropic~=0.32 (Python 3.10–3.12)
uv venv .venv-hypogenic --python 3.10 && source .venv-hypogenic/bin/activate
uv pip install hypogenic

# Clone example datasets
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# Run data-driven hypothesis generation (model_type: gpt | claude | vllm | huggingface)
hypogenic_generation --task_config_path ./data/your_task/config.yaml \
    --model_type gpt --model_name <provider-model-id> \
    --max_num_hypotheses 20 --output_folder ./outputs/your_task

# Run inference with a saved hypothesis bank
hypogenic_inference --task_config_path ./data/your_task/config.yaml \
    --hypothesis_file ./outputs/your_task/<hypotheses_*.json> \
    --model_type gpt --model_name <provider-model-id>

hypogenic 0.3.5 のコンソールスクリプト（hypogenic_cmd）でフラグを確認しています。CLI はデータ駆動型の HypoGeniC 生成と推論に対応しています。HypoRefine と Union の実行には、 サンプルスクリプト（以下）を使用します。すべてのオプションは --help で確認できます。

またはサンプルスクリプトを使用してください（ライブラリには examples/ に実行可能なスクリプトが含まれています。1 行で呼び出せる流暢な task.generate_hypotheses(...) API はありません。実際のクラスについては、以下の「Python API の使い方」を参照してください）。

python ./examples/generation.py   --help   # HypoGeniC data-driven generation
python ./examples/inference.py     --help   # single-hypothesis inference

このスキルを使う場面

以下の作業を行う場合に、このスキルを使用してください。

  • 観察データセットから科学的仮説を生成する
  • 複数の競合仮説を体系的に検証する
  • 文献から得た知見と経験的なパターンを組み合わせる
  • 仮説の自動発想を通じて研究上の発見を加速する
  • 欺瞞の検出、AI 生成コンテンツの識別、メンタルヘルスの指標、予測モデリング、その他の経験的研究など、仮説に基づく分析が必要な分野
対象外
シナリオ代わりに使用
観察結果から反証可能な仮説と予測を手作業で立てる（LLM パイプラインなし）alterlab-hypothesis-gen
まだデータセットがない段階での自由形式の発想や研究ギャップのブレインストーミングalterlab-scientific-brainstorm
社会科学における測定として、テキストを対象にトピックモデル、辞書、または教師あり分類器を使用するalterlab-text-as-data
事前に設定した 1 つの仮説を従来の統計検定で検証するalterlab-statistical-analysis

主な機能

仮説の自動生成

  • データから検証可能な仮説を 10～20 件以上、数分で生成
  • 検証性能に基づいて反復的に改良
  • API ベース（OpenAI、Anthropic）とローカル LLM の両方に対応

文献の統合

  • PDF 処理を通じて研究論文から知見を抽出
  • 理論的基盤と経験的なパターンを組み合わせる
  • GROBID を用いた、文献から仮説への体系的なパイプライン

性能の最適化

  • Redis キャッシュにより、実験の繰り返しに伴う API コストを削減
  • 大規模な仮説検証に向けた並列処理
  • 難しい事例に焦点を当てる適応的な改良

柔軟な設定

  • 変数を注入できるテンプレートベースのプロンプトエンジニアリング
  • 分野固有のタスク向けのカスタムラベル抽出
  • 拡張しやすいモジュール型アーキテクチャ

報告されている結果（arXiv:2410.17309、『Literature Meets Data』より）

  • 少数ショットを 8.97％上回り、文献のみのベースラインを 15.75％、データ駆動型のみのベースラインを 3.37％上回る
  • 人間の精度が、欺瞞の検出で 7.44％、AI 生成コンテンツの識別で 14.19％向上
  • 冗長性チェッカーが類似した仮説を除外し、最終的な仮説群の多様性を維持

主な機能

1. HypoGeniC：データ駆動型の仮説生成

反復的な改良を通じて、観察データのみから仮説を生成します。

プロセス：

  1. 少量のデータサブセットを使って、候補となる仮説を生成する
  2. 性能に基づいて、仮説を反復的に改良する
  3. 性能の低い仮説を、難しい事例から新たに生成した仮説に置き換える

最適な用途： 既存の文献がない状況での探索的研究、新しいデータセットにおけるパターンの発見

2. HypoRefine：文献とデータの統合

エージェント型フレームワークを通じて、既存の文献と実証データを相乗的に組み合わせます。

プロセス：

  1. 関連する研究論文（通常10本）から知見を抽出します
  2. 文献に基づく理論的な仮説を生成します
  3. 観察されたパターンからデータ駆動型の仮説を生成します
  4. 反復的な改善を通じて、両方の仮説バンクを洗練します

最適な用途： 確立された理論的基盤を持つ研究、既存の理論の検証や拡張

3. 統合手法

文献のみから得られた仮説と、フレームワークの出力を機械的に組み合わせます。

バリエーション：

  • Literature ∪ HypoGeniC：文献の仮説とデータ駆動型の生成を組み合わせます
  • Literature ∪ HypoRefine：文献の仮説と統合アプローチを組み合わせます

最適な用途： 仮説を網羅的にカバーし、多様な視点を維持しながら冗長性を排除する場合

インストール

pip でインストールします：

uv pip install hypogenic

上記の依存関係のバージョンが固定されているため、hypogenic はメインの分析環境にインストールしないでください。

オプションの依存関係：

  • Redis server（ポート6832）：LLM の応答をキャッシュして、反復的な仮説生成にかかる API コストを大幅に削減します
  • s2orc-doc2json：HypoRefine ワークフローで文献 PDF を処理するために必要です
  • GROBID：PDF の前処理に必要です（「文献処理」セクションを参照）

サンプルデータセットをクローンします：

# For HypoGeniC examples
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# For HypoRefine/Union examples
git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

データセット形式

データセットは、特定の命名規則に従った HuggingFace datasets 形式である必要があります。

必須ファイル：

  • <TASK>_train.json：トレーニングデータ
  • <TASK>_val.json：検証データ
  • <TASK>_test.json：テストデータ

JSON の必須キー：

  • text_features_1 から text_features_n：特徴量の値を含む文字列のリスト
  • label：正解ラベルを含む文字列のリスト

例（見出しのクリック予測）：

{
  "headline_1": [
    "What Up, Comet? You Just Got *PROBED*",
    "Scientists Made a Breakthrough in Quantum Computing"
  ],
  "headline_2": [
    "Scientists Everywhere Were Holding Their Breath Today. Here's Why.",
    "New Quantum Computer Achieves Milestone"
  ],
  "label": [
    "Headline 2 has more clicks than Headline 1",
    "Headline 1 has more clicks than Headline 2"
  ]
}

重要な注意事項：

  • すべてのリストの長さは同じである必要があります
  • ラベルの形式は、extract_label() 関数の出力形式と一致している必要があります
  • 特徴量のキーは、分野に合わせてカスタマイズできます（例：review_text、post_content など）

設定

各タスクでは、以下を指定する config.yaml ファイルが必要です。

必須項目：

  • データセットのパス（train/val/test）
  • 以下のプロンプトテンプレート：
    • 観察結果の生成
    • バッチでの仮説生成
    • 仮説の推論
    • 関連性の確認
    • 適応型手法（HypoRefine 用）

テンプレートの機能：

  • 動的な変数の挿入に使うデータセットのプレースホルダー（例：${text_features_1}、${num_hypotheses}）
  • 分野固有の解析に対応するカスタムラベル抽出関数
  • 役割ベースのプロンプト構造（system、user、assistant の各ロール）

設定の構造：

task_name: your_task_name

train_data_path: ./your_task_train.json
val_data_path: ./your_task_val.json
test_data_path: ./your_task_test.json

prompt_templates:
  # Extra keys for reusable prompt components
  observations: |
    Feature 1: ${text_features_1}
    Feature 2: ${text_features_2}
    Observation: ${label}
  
  # Required templates
  batched_generation:
    system: "Your system prompt here"
    user: "Your user prompt with ${num_hypotheses} placeholder"
  
  inference:
    system: "Your inference system prompt"
    user: "Your inference user prompt"
  
  # Optional templates for advanced features
  few_shot_baseline: {...}
  is_relevant: {...}
  adaptive_inference: {...}
  adaptive_selection: {...}

設定の完全な例については、references/config_template.yaml を参照してください。

文献処理（HypoRefine／統合手法）

文献に基づく仮説生成を使用するには、PDF 論文を前処理する必要があります。

ステップ1：GROBID をセットアップする（初回のみ）

bash ./modules/setup_grobid.sh

ステップ2：PDF ファイルを追加する 研究論文を literature/YOUR_TASK_NAME/raw/ に配置します。

ステップ3：PDF を処理する

# Start GROBID service
bash ./modules/run_grobid.sh

# Process PDFs for your task
cd examples
python pdf_preprocess.py --task_name YOUR_TASK_NAME

これにより、仮説抽出用の構造化形式に PDF が変換されます。文献の自動検索は今後のリリースでサポートされる予定です。

CLI の使用方法

仮説生成
hypogenic_generation --help

主なパラメーター：

  • タスク設定ファイルのパス
  • モデルの選択（API ベースまたはローカル）
  • 生成方法（HypoGeniC、HypoRefine、または Union）
  • 生成する仮説の数
  • 仮説バンクの出力ディレクトリ
仮説の推論
hypogenic_inference --help

主なパラメーター：

  • タスク設定ファイルのパス
  • 仮説バンクのファイルパス
  • テストデータセットのパス
  • 推論方法（デフォルトまたは複数仮説）
  • 結果の出力ファイル

Python API の使用方法

このライブラリは、1 回の呼び出しで完結する流暢な API ではありません。生成はアルゴリズムクラス（DefaultGeneration、DefaultInference、DefaultUpdate、DefaultReplace）を使用した明示的な初期化／更新ループとして実行され、推論は inference_register を通じて実行されます。examples/ のスクリプトをコピーして調整してください。HypoRefine／Union については、examples/union_generation.py を調整してください。

インポート一覧、生成／推論ループ、inference_type の戦略オプション、重要な extract_label() の解析契約については、references/python_api.md を参照してください。

ワークフローの例

データ駆動型（HypoGeniC、AI コンテンツ検出）、文献情報を活用したもの（HypoRefine、ホテルのレビューにおける欺瞞）、包括的な網羅を目指すもの（Union、メンタルストレス検出）の 3 つのエンドツーエンドシナリオについて、それぞれのデータセット準備、生成、推論コマンドを紹介しています。references/workflow_examples.md を参照してください。

パフォーマンスの最適化

キャッシュ： Redis キャッシュを有効にすると、繰り返される LLM 呼び出しの API コストと計算時間を削減できます。

並列処理： 大規模な仮説の生成とテストには、複数のワーカーを活用してください。

適応的な改良： 難しい例を使って、仮説の品質を反復的に向上させます。

トラブルシューティング

問題： 生成された仮説が一般的すぎる
解決策： config.yaml のプロンプトテンプレートを調整し、より具体的で検証可能な仮説を求めてください。

問題： 推論のパフォーマンスが低い
解決策： データセットに十分な学習例があることを確認し、仮説生成パラメーターを調整するか、仮説の数を増やしてください。

問題： ラベルの抽出に失敗する
解決策： ドメイン固有の出力解析に対応するカスタム extract_label() 関数を実装してください。

問題： GROBID による PDF 処理が失敗する
解決策： GROBID サービスが実行中であること（bash ./modules/run_grobid.sh）と、PDF が有効な研究論文であることを確認してください。

カスタムタスクの作成

新しいタスクの追加は 5 つの手順で行います。(1) text_features_* キーと label キーを含む train/val/test JSON を準備する、(2) config.yaml を作成する、(3) カスタム extract_label() を実装する、(4) 必要に応じて HypoRefine／Union 用に文献 PDF を処理する、(5) 生成と推論を実行する。

カスタム extract_label の実装と BaseTask の接続方法を含む、手順ごとの詳細ガイドについては、references/custom_tasks.md を参照してください。

リポジトリ構成

コアコードは hypogenic/ に、CLI のエントリーポイントは hypogenic_cmd/ に、HypoRefine エージェントは hypothesis_agent/ に、PDF／文献関連ツールは literature/ と modules/ に、実行可能なスクリプトは examples/ にあります。注釈付きのディレクトリツリー全体については、references/repository_structure.md を参照してください。

関連出版物

このフレームワークの基盤となるのは、ChicagoHAI による 3 本の論文です。HypoBench（2025年、arXiv:2504.11524）、Literature Meets Data（2024年、arXiv:2410.17309、HypoRefine を紹介）、そして初期の論文 Hypothesis Generation with Large Language Models（2024年、EMNLP NLP4Science）です。引用情報、説明、BibTeX エントリの全文については、references/publications.md を参照してください。

その他のリソース

公式リンク
サンプルデータセット

すぐに使える例を入手するには、以下のリポジトリをクローンしてください。

# HypoGeniC examples (data-driven only)
git clone https://github.com/ChicagoHAI/HypoGeniC-datasets.git ./data

# HypoRefine/Union examples (literature + data)
git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

貢献や質問については、GitHub リポジトリにアクセスし、issues ページを確認してください。

ローカルリソース

references/
  • config_template.yaml — 実際の hypogenic スキーマ（task_name、train/val/test_data_path、ロールベースの system/user サブキーと ${...} プレースホルダーを含む prompt_templates）に準拠した、実行可能な形式の config.yaml です。設定を作成する前にお読みください。${...} による置換、再利用可能な「extra key」の仕組み、YAML ではなく CLI フラグで指定する設定について説明しています。
  • python_api.md — 初期化と更新の生成ループ、推論レジストリ、inference_type の戦略オプション、extract_label() の解析仕様について説明しています。
  • workflow_examples.md — エンドツーエンドのシナリオを 3 つ（HypoGeniC、HypoRefine、Union）紹介しています。
  • custom_tasks.md — 新しいタスクまたはデータセットを追加するための 5 ステップガイドです。
  • repository_structure.md — アップストリームリポジトリの注釈付き構成です。
  • publications.md — HypoGeniC／HypoRefine／HypoBench の論文の完全な引用情報と BibTeX です。

AlterLab Academic Skills スイートの一部です。

コメント

Markdown 対応