hypogenic

Hypogenic

概要

Hypogenic は、大規模言語モデルを用いた仮説の自動生成と検証を提供し、科学的発見を加速させます。このフレームワークは3つのアプローチをサポートしています。HypoGeniC（データ駆動型の仮説生成）、HypoRefine（文献とデータの相乗的統合）、Union 手法（文献とデータ駆動型仮説の機構的な組み合わせ）です。

クイックスタート

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

# Install the package
uv pip install hypogenic

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

# Run basic hypothesis generation
hypogenic_generation --config ./data/your_task/config.yaml --method hypogenic --num_hypotheses 20

# Run inference on generated hypotheses
hypogenic_inference --config ./data/your_task/config.yaml --hypotheses output/hypotheses.json

または Python API を使用する場合:

from hypogenic import BaseTask

# Create task with your configuration
task = BaseTask(config_path="./data/your_task/config.yaml")

# Generate hypotheses
task.generate_hypotheses(method="hypogenic", num_hypotheses=20)

# Run inference
results = task.inference(hypothesis_bank="./output/hypotheses.json")

このスキルを使用するタイミング

以下の作業でこのスキルを使用してください。

• 観測データセットから科学的な仮説を生成する
• 競合する複数の仮説を体系的に検証する
• 文献からの知見と経験的パターンを組み合わせる
• 自動化された仮説立案によって研究発見を加速させる
• 欺瞞検出、AI 生成コンテンツの識別、メンタルヘルス指標、予測モデリング, その他の経験的研究など、仮説駆動型の分析が必要な分野

主な機能

自動仮説生成

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

文献統合

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

パフォーマンス最適化

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

柔軟な構成

• 変数注入を伴うテンプレートベースのプロンプトエンジニアリング
• ドメイン固有のタスク向けのカスタムラベル抽出
• 容易に拡張できるモジュール式アーキテクチャ

実証された成果

• 少数ショットのベースラインに対して 8.97% の改善
• 文献のみのアプローチに対して 15.75% の改善
• 80～84% の仮説多様性（冗長でない知見）
• 人間の評価者が意思決定の大幅な改善を報告

中核的な機能

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

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

プロセス:

1. 小規模なデータのサブセットで初期化し、候補仮説を生成する
2. 性能に基づいて仮説を反復的に改良する
3. 難しい事例から得られた新しい仮説で、性能の低い仮説を置き換える

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

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

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

プロセス:

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

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

3. Union 手法

文献のみに基づく仮説とフレームワークの出力を機構的に組み合わせます。

バリアント:

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

最適な用途: 包括的な仮説のカバレッジ、多様な視点を維持しつつ冗長性を排除すること

インストール

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

uv pip install hypogenic

オプションの依存関係:

• Redis サーバー（ポート 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/Union 手法）

文献ベースの仮説生成を使用するには、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

主なパラメーター:

• タスク設定ファイルのパス
• 仮説バンクファイルのパス
• テストデータセットのパス
• 推論手法（default または multi-hypothesis）
• 結果の出力ファイル

Python API の使い方

プログラムによる制御やカスタムワークフローのためには、Python コードで Hypogenic を直接使用してください。

基本的な HypoGeniC による生成

from hypogenic import BaseTask

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

# Load your task with custom extract_label function
task = BaseTask(
    config_path="./data/your_task/config.yaml",
    extract_label=lambda text: extract_your_label(text)
)

# Generate hypotheses
task.generate_hypotheses(
    method="hypogenic",
    num_hypotheses=20,
    output_path="./output/hypotheses.json"
)

# Run inference
results = task.inference(
    hypothesis_bank="./output/hypotheses.json",
    test_data="./data/your_task/your_task_test.json"
)

HypoRefine/Union 手法

# For literature-integrated approaches
# git clone https://github.com/ChicagoHAI/Hypothesis-agent-datasets.git ./data

# Generate with HypoRefine
task.generate_hypotheses(
    method="hyporefine",
    num_hypotheses=15,
    literature_path="./literature/your_task/",
    output_path="./output/"
)
# This generates 3 hypothesis banks:
# - HypoRefine (integrated approach)
# - Literature-only hypotheses
# - Literature∪HypoRefine (union)

複数仮説による推論

from examples.multi_hyp_inference import run_multi_hypothesis_inference

# Test multiple hypotheses simultaneously
results = run_multi_hypothesis_inference(
    config_path="./data/your_task/config.yaml",
    hypothesis_bank="./output/hypotheses.json",
    test_data="./data/your_task/your_task_test.json"
)

カスタムラベル抽出

extract_label() 関数は、LLM の出力を解析する上で重要です。タスクに応じて実装してください。

def extract_label(llm_output: str) -> str:
    """Extract predicted label from LLM inference text.
    
    Default behavior: searches for 'final answer:\s+(.*)' pattern.
    Customize for your domain-specific output format.
    """
    import re
    match = re.search(r'final answer:\s+(.*)', llm_output, re.IGNORECASE)
    if match:
        return match.group(1).strip()
    return llm_output.strip()

重要: 正しい精度計算のためには、抽出されたラベルがデータセットの label 値の形式と一致している必要があります。

ワークフローの例

例 1: データ駆動型の仮説生成（HypoGeniC）

シナリオ: 事前の理論的枠組みなしに、AI 生成コンテンツを検出する

手順:

1. テキストサンプルとラベル（人間による文章か AI 生成か）を含むデータセットを準備する
2. 適切なプロンプトテンプレートを用いて config.yaml を作成する
3. 仮説生成を実行する:

   hypogenic_generation --config config.yaml --method hypogenic --num_hypotheses 20
   

4. テストセットで推論を実行する:

   hypogenic_inference --config config.yaml --hypotheses output/hypotheses.json --test_data data/test.json
   

5. 形式性、文法的な精密さ、トーンの違いなどのパターンについて結果を分析する

例 2: 文献に基づく仮説検証（HypoRefine）

シナリオ: 既存研究を基にした、ホテルレビューにおける欺瞞の検出

手順:

1. 言語的な欺瞞の手がかりに関する関連論文を 10 本収集する
2. 本物のレビューと虚偽のレビューを含むデータセットを準備する
3. 文献処理とデータ生成のテンプレートを用いて config.yaml を設定する
4. HypoRefine を実行する:

   hypogenic_generation --config config.yaml --method hyporefine --papers papers/ --num_hypotheses 15
   

5. 代名詞の頻度、詳細さの具体性、その他の言語的パターンを検討する仮説を検証する
6. 文献ベースの仮説とデータ駆動型の仮説の性能を比較する

例 3：仮説の包括的なカバレッジ（Union 手法）

シナリオ： 仮説の多様性を最大化したメンタルストレス検出

手順：

1. メンタルヘルス研究論文から文献ベースの仮説を生成する
2. SNS 投稿からデータ駆動型の仮説を生成する
3. Union 手法を実行して、仮説を統合し重複を除去する：

   hypogenic_generation --config config.yaml --method union --literature_hypotheses lit_hyp.json
   

4. 推論では、理論的な構成概念（投稿行動の変化）とデータパターン（感情的な言語の変化）の両方が捉えられます

パフォーマンスの最適化

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

並列処理： 複数のワーカーを活用して、大規模な仮説の生成とテストを行います

適応的な改良： 難易度の高い例を使用して、仮説の品質を反復的に改善します

期待される成果

hypogenic を用いた研究では、以下が示されています。

• AI 生成コンテンツの検出タスクで正解率が 14.19% 向上
• 欺瞞検出タスクで正解率が 7.44% 向上
• 仮説のペアの 80〜84% が、互いに重複しない独自の知見を提供
• 複数の研究分野において、人間の評価者から高い有用性の評価を獲得

トラブルシューティング

問題： 生成された仮説が一般的すぎる 解決策： config.yaml のプロンプトテンプレートを改良し、より具体的で検証可能な仮説を生成するよう指定します

問題： 推論の性能が低い 解決策： データセットに十分な学習例があることを確認するか、仮説生成のパラメータを調整するか、仮説の数を増やします

問題： ラベルの抽出に失敗する 解決策： ドメイン固有の出力解析のために、カスタムの extract_label() 関数を実装します

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

カスタムタスクの作成

Hypogenic に新しいタスクまたはデータセットを追加するには、次の手順に従います。

ステップ 1：データセットを準備する

必要な形式に従って、3 つの JSON ファイルを作成します。

• your_task_train.json
• your_task_val.json
• your_task_test.json

各ファイルには、テキスト特徴量（text_features_1 など）と label のキーが必要です。

ステップ 2：config.yaml を作成する

次の内容でタスクの設定を定義します。

• タスク名とデータセットのパス
• 観察、生成、推論のためのプロンプトテンプレート
• 再利用可能なプロンプト部品のための追加のキー
• プレースホルダー変数（例：${text_features_1}、${num_hypotheses}）

ステップ 3：extract_label 関数を実装する

ドメインに合わせて LLM の出力を解析する、カスタムのラベル抽出関数を作成します。

from hypogenic import BaseTask

def extract_my_label(llm_output: str) -> str:
    """Custom label extraction for your task.
    
    Must return labels in same format as dataset 'label' field.
    """
    # Example: Extract from specific format
    if "Final prediction:" in llm_output:
        return llm_output.split("Final prediction:")[-1].strip()
    
    # Fallback to default pattern
    import re
    match = re.search(r'final answer:\s+(.*)', llm_output, re.IGNORECASE)
    return match.group(1).strip() if match else llm_output.strip()

# Use your custom task
task = BaseTask(
    config_path="./your_task/config.yaml",
    extract_label=extract_my_label
)

ステップ 4：（任意）文献を処理する

HypoRefine / Union 手法を使用する場合：

1. literature/your_task_name/raw/ ディレクトリを作成します
2. 関連する研究論文の PDF を追加します
3. GROBID による前処理を実行します
4. pdf_preprocess.py で処理します

ステップ 5：生成とテストを実行する

コマンドラインまたは Python API を使用して、仮説の生成と推論を実行します。

# CLI approach
hypogenic_generation --config your_task/config.yaml --method hypogenic --num_hypotheses 20
hypogenic_inference --config your_task/config.yaml --hypotheses output/hypotheses.json

# Or use Python API (see Python API Usage section)

リポジトリの構成

リポジトリのレイアウトは次のとおりです。

hypothesis-generation/
├── hypogenic/              # Core package code
├── hypogenic_cmd/          # CLI entry points
├── hypothesis_agent/       # HypoRefine agent framework
├── literature/            # Literature processing utilities
├── modules/               # GROBID and preprocessing modules
├── examples/              # Example scripts
│   ├── generation.py      # Basic HypoGeniC generation
│   ├── union_generation.py # HypoRefine/Union generation
│   ├── inference.py       # Single hypothesis inference
│   ├── multi_hyp_inference.py # Multiple hypothesis inference
│   └── pdf_preprocess.py  # Literature PDF processing
├── data/                  # Example datasets (clone separately)
├── tests/                 # Unit tests
└── IO_prompting/          # Prompt templates and experiments

主要なディレクトリ：

• hypogenic/：BaseTask と生成ロジックを含むメインパッケージ
• examples/：一般的なワークフローの参照実装
• literature/：PDF 処理と文献抽出のためのツール
• modules/：外部ツールとの統合（GROBID など）

関連する論文

HypoBench（2025）

Liu, H., Huang, S., Hu, J., Zhou, Y., & Tan, C. (2025). HypoBench: Towards Systematic and Principled Benchmarking for Hypothesis Generation. arXiv preprint arXiv:2504.11524.

• 論文： https://arxiv.org/abs/2504.11524
• 説明： 仮説生成手法を体系的に評価するためのベンチマークフレームワーク

BibTeX：

@misc{liu2025hypobenchsystematicprincipledbenchmarking,
      title={HypoBench: Towards Systematic and Principled Benchmarking for Hypothesis Generation}, 
      author={Haokun Liu and Sicong Huang and Jingyu Hu and Yangqiaoyu Zhou and Chenhao Tan},
      year={2025},
      eprint={2504.11524},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2504.11524}, 
}

Literature Meets Data (2024)

Liu, H., Zhou, Y., Li, M., Yuan, C., & Tan, C. (2024). Literature Meets Data: A Synergistic Approach to Hypothesis Generation. arXiv preprint arXiv:2410.17309.

• 論文: https://arxiv.org/abs/2410.17309
• コード: https://github.com/ChicagoHAI/hypothesis-generation
• 概要: HypoRefine を紹介し、文献ベースとデータ駆動型の仮説生成を組み合わせる相乗的アプローチを示します

BibTeX:

@misc{liu2024literaturemeetsdatasynergistic,
      title={Literature Meets Data: A Synergistic Approach to Hypothesis Generation}, 
      author={Haokun Liu and Yangqiaoyu Zhou and Mingxuan Li and Chenfei Yuan and Chenhao Tan},
      year={2024},
      eprint={2410.17309},
      archivePrefix={arXiv},
      primaryClass={cs.AI},
      url={https://arxiv.org/abs/2410.17309}, 
}

Hypothesis Generation with Large Language Models (2024)

Zhou, Y., Liu, H., Srivastava, T., Mei, H., & Tan, C. (2024). Hypothesis Generation with Large Language Models. In Proceedings of EMNLP Workshop of NLP for Science.

• 論文: https://aclanthology.org/2024.nlp4science-1.10/
• 概要: データ駆動型の仮説生成のための元の HypoGeniC フレームワーク

BibTeX:

@inproceedings{zhou2024hypothesisgenerationlargelanguage,
      title={Hypothesis Generation with Large Language Models}, 
      author={Yangqiaoyu Zhou and Haokun Liu and Tejes Srivastava and Hongyuan Mei and Chenhao Tan},
      booktitle = {Proceedings of EMNLP Workshop of NLP for Science},
      year={2024},
      url={https://aclanthology.org/2024.nlp4science-1.10/},
}

Additional Resources

Official Links

• GitHub リポジトリ: https://github.com/ChicagoHAI/hypothesis-generation
• PyPI パッケージ: https://pypi.org/project/hypogenic/
• ライセンス: MIT License
• Issues & サポート: https://github.com/ChicagoHAI/hypothesis-generation/issues

Example Datasets

すぐに使えるサンプルとして、以下のリポジトリをクローンしてください:

# 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

Community & Contributions

• コントリビューター: 7 名以上のアクティブなコントリビューター
• Stars: GitHub で 89 以上
• トピック: research-tool, interpretability, hypothesis-generation, scientific-discovery, llm-application

コントリビューションや質問については、GitHub リポジトリを確認し、Issues ページをご覧ください。

Local Resources

references/

config_template.yaml - 必要なすべてのプロンプトテンプレートとパラメーターを含む、完全な設定ファイルのサンプルです。内容は以下のとおりです:

• タスク設定の完全な YAML 構造
• すべての手法向けのプロンプトテンプレートの例
• プレースホルダー変数のドキュメント
• ロールベースのプロンプトの例

scripts/

scripts ディレクトリは以下の用途で利用できます:

• カスタムのデータ準備ユーティリティ
• 形式変換ツール
• 分析および評価スクリプト
• 外部ツールとの連携

assets/

assets ディレクトリは以下の用途で利用できます:

• サンプルデータセットとテンプレート
• サンプルの仮説バンク
• 可視化の出力
• ドキュメントの補足資料