Semantic Gradient Optimization

SGO パイプラインを実行しています。このパイプラインは、ユーザーが管理するエンティティ(θ)を評価者の集団(x)に対して最適化するもので、LLM ベースのスコアリングと反事実プローブを使用してセマンティック勾配を推定します。

リポジトリ: https://github.com/xuy/sgo

最初に: インストール位置を確認

SGO リポジトリは以下のいずれかの場所にインストールされている可能性があります:

• ~/.claude/skills/sgo/ (スキルとしてインストールされた場合)
• ユーザーがクローンした場所

ls ~/.claude/skills/sgo/scripts/evaluate.py 2>/dev/null を実行して確認してください。見つからない場合は、ユーザーに SGO をクローンした場所を聞くか、クローンを提案してください:

git clone https://github.com/xuy/sgo.git ~/.claude/skills/sgo

このファイルの以降の部分では、$SGO_DIR は SGO のインストール位置を指します。すべてのパスはそれを基準としています。

クイックリファレンス

Pipeline:  Build Entity → Build Cohort → Score f(θ,x) → Probe Counterfactuals → Act & Re-evaluate
Scripts:   $SGO_DIR/scripts/
Templates: $SGO_DIR/templates/
Data:      $SGO_DIR/data/
Results:   $SGO_DIR/results/

---

Phase 0 — セットアップ

1. 依存関係: cd $SGO_DIR && uv sync (または pip install datasets huggingface_hub openai python-dotenv)
2. API キー: $SGO_DIR/.env が存在することを確認してください。存在しない場合は、cp $SGO_DIR/.env.example $SGO_DIR/.env を実行し、ユーザーに LLM API キーを入力してもらってください。.env を読み込まないでください — 設定されていることを確認するだけです。
3. ペルソナデータ: uv run python $SGO_DIR/scripts/setup_data.py を実行します。初回実行時に NVIDIA Nemotron-Personas-USA (~2GB) をダウンロードして $SGO_DIR/data/nemotron/ に保存し、キャッシュがあればスキップします。

---

Phase 1 — エンティティ (θ)

ユーザーに質問してください: 「何を最適化していますか?」

選択肢: 製品、職務経歴書、ピッチ、ポリシー、プロフィール、またはカスタム。

• ドキュメントがあれば $SGO_DIR/entities/<name>.md に保存してください
• なければ $SGO_DIR/templates/ のテンプレートを使用して一緒に記入してください
• 確認: 「これが評価者が見るものです。追加または削除することはありますか?」

---

Phase 2 — コホート ({xᵢ})

質問してください: 「ターゲットオーディエンスは誰ですか?」 そして 「セグメンテーションにはどのような要素が重要ですか?」

2つのパス:

A) Nemotron データセット (推奨 — センサス ベース、100万の US ペルソナ):

cd $SGO_DIR

# フィルタリング
uv run python scripts/persona_loader.py \
  --filters '{"sex": "...", "state": "...", "age_min": N, "age_max": N}' \
  --output data/filtered.json

# 層化サンプリング (--entity は LLM ベースの職業バケッティングを有効化)
uv run python scripts/stratified_sampler.py \
  --input data/filtered.json \
  --entity entities/<entity>.md \
  --total 50 \
  --output data/cohort.json

B) LLM 生成 (フォールバック — モード崩壊のリスクについてユーザーに警告):

uv run python scripts/generate_cohort.py \
  --description "..." \
  --segments '[{"label": "...", "count": N}, ...]' \
  --output data/cohort.json

コホート分布表を表示してください。ユーザーと確認してください。

---

Phase 3 — 評価

cd $SGO_DIR
uv run python scripts/evaluate.py \
  --entity entities/<name>.md \
  --cohort data/cohort.json \
  --tag <run_tag> \
  --parallel 5

バイアスキャリブレーション (フレーミング/権威/順序の人工物を減らし、より現実的なスコアを実現) を有効化するには:

uv run python scripts/evaluate.py \
  --entity entities/<name>.md \
  --cohort data/cohort.json \
  --tag <run_tag> \
  --bias-calibration \
  --parallel 5

以下を提示してください: 平均スコア、セグメント別内訳、トップの魅力、主な懸念、ディールブレーカー、最も/最も受け入れられていない評価者 (引用付き)。

質問してください: 「何か驚いたことはありますか? セグメントを詳しく見たいですか?」

---

Phase 4 — 反事実プローブ

ユーザーに質問してください: 「どのような変更を検討していますか?」 そして 「変更しないものは何ですか?」

不確定な場合、Phase 3 の主な懸念に基づいて変更を提案してください。data/changes.json に保存してください (templates/changes.json 形式については参照)。

uv run python scripts/counterfactual.py \
  --tag <run_tag> \
  --changes data/changes.json \
  --parallel 5

セマンティック勾配を提示してください: 平均 Δ、助けられた %, 害された %、人口統計学的感度でランク付けされた変更。

質問してください: 「最初にどの変更を行いたいですか?」

---

Phase 5 — 繰り返し

1. ユーザーがエンティティを更新 → entities/<name>_v2.md として保存
2. 同じコホートで再評価: --tag <new_tag>
3. 比較: uv run python scripts/compare.py --runs <old> <new>
4. デルタ、新しい魅力、解決された懸念を表示
5. 質問: 「もう1ラウンド行いますか、それともここまでで良いですか?」

---

Phase 6 — バイアス監査 (オプション)

ユーザーがパネルの忠実性を検証したい場合、または「これらの評価はどの程度現実的ですか?」と質問したときに実行してください。これは評価者パイプラインの認知バイアスを測定し、人間のベースラインと比較します (Tversky & Kahneman フレーミング、Milgram 権威)。

cd $SGO_DIR
uv run python scripts/bias_audit.py \
  --entity entities/<name>.md \
  --cohort data/cohort.json \
  --probes framing authority order \
  --sample 10 \
  --parallel 5

• --probes: テストするバイアス (framing、authority、order — またはいずれかのサブセット)
• --sample: 監査する評価者の数 (10 は高速; 徹底的な監査にはコホート全体を使用)

出力: results/bias_audit/report.md (プローブごとの分析と人間のベースラインとのギャップ付き)。

バイアスが検出された場合:

• オーバー バイアス: --bias-calibration フラグで評価を再実行してください
• アンダー バイアス: パネルがドメインに対して理性的すぎるかどうかを検討してください
• 順序効果: エンティティ形式を標準化するか、順序全体で平均を取ってください

質問してください: 「パネルの認知バイアスが人間のベースラインとどのように比較されるかを見たいですか?」

---

重要な原則

• コホートは対照群 — 実行全体で固定のままにしてください
• LLM 生成より Census ベース のペルソナ (README を参照)
• 実行可能な変更のみをプローブしてください — 変更できない、または変更しないものに無駄なトークンを使わないでください
• 勾配はセマンティック — 理由を提示してください、単なるデルタではなく
• 各実行はタグ付き — 結果は時系列で比較可能です

引数

$ARGUMENTS が提供される場合:

• ファイルパスの場合 → エンティティとして使用 (Phase 1 をスキップ)
• 説明の場合 → Phase 1 でエンティティを下書きするために使用
• 実行タグの場合 → 既存の結果を読み込み、中断したところから続行