audience-builder

オーディエンスビルダー

目的

主要なエンドツーエンドスキルです。自然言語によるオーディエンスの説明を受け取り、検証・規模算定・確認を経たセグメントを作成します。スキーマ検出、filterql-builder、segment-manager、confirmation-gate を組み合わせます。

環境

認証済みの API アクセスが必要です。認証情報の解決方法については、../references/auth.md を参照してください。

入力

• 対象とするオーディエンスの自然言語による説明
• 任意：セグメント名、テーブル（デフォルト：user）、種類（デフォルト：segment）、タグ

エンドツーエンドのフロー

ステップ 0：アドバイザーの利用が適切か確認する

ユーザーのリクエストが具体的な条件ではなく目標指向の場合（例：「コンバージョンを増やしたい」対「5 回以上訪問した米国のユーザー」）、まず audience-advisor skill から始めるよう提案します。

「ビジネス目標をお持ちのようです。まずデータを分析して、最適なターゲティング戦略を提案しましょうか？ML モデル、フィールドの分布、既存のセグメントを調べ、データに基づいたフィルターをご提案できます。」

ユーザーが具体的なオーディエンスの説明をしている場合は、ステップ 1 に進みます。

ステップ 1：意図を解析する

自然言語による説明から、重要な概念を抽出します。

• 対象の属性（人口統計、行動、プロパティ）
• 含める条件（該当する属性や実行した行動）
• 除外する条件（該当しない属性や実行していない行動）
• 時間的制約（時間に基づく条件）

例：「1 年以上靴下を購入していない米国の顧客」

• 属性：country = US
• 除外：靴下を購入していない
• 時間：1 年以上前

ステップ 2：スキーマ検出

schema-discovery skill を使用して、一致するフィールドを見つけます。

# Get all fields to find candidates
curl -s "${LYTICS_API_URL:-https://api.lytics.io}/v2/schema/user/field" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

フィールド名の一致度、型の互換性、値の分布に基づいて候補フィールドを評価します。上記の例の場合：

• 「米国の顧客」→ 次のフィールドを検索：country、geo_country、country_code（文字列型）
• 「靴下を購入した」→ 次のフィールドを検索：products_purchased（セット）、purchase_categories（セット）、last_purchase_date（日付）

有力候補の値の候補を取得します。q パラメーターは必須です。

curl -s "${LYTICS_API_URL:-https://api.lytics.io}/api/schema/user/fieldsuggest/${FIELD}?q=${QUERY}" \
  -H "Authorization: ${LYTICS_API_TOKEN}"

例：/api/schema/user/fieldsuggest/country?q=US

フィールドの値が一致することを確認します（例：country に「US」が含まれ、products_purchased に「socks」が含まれている）。

ステップ 3：FilterQL を構築する

filterql-builder skill を使用して、フィルター式を作成します。

フィールド型に応じて、各概念を FilterQL 条件に割り当てます（../references/field-types.md を参照）。

• 文字列の等価比較：country = "US"
• セットに含まれない条件：NOT products_purchased INTERSECTS ("socks")
• 日付の比較：last_sock_purchase < "now-1y"

AND/OR で組み合わせます。

FILTER AND (
  country = "US",
  NOT products_purchased INTERSECTS ("socks")
) FROM user ALIAS us_no_socks

ステップ 4：FilterQL を検証する

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/validate" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (country = "US", NOT products_purchased INTERSECTS ("socks")) FROM user ALIAS us_no_socks'

検証に失敗した場合：

1. エラーメッセージを解析する
2. 構文上の問題を特定する
3. FilterQL を修正する
4. 再試行する（最大 3 回）
5. それでも失敗する場合は、エラーを表示してユーザーに対応方法を尋ねる

ステップ 5：規模を見積もる

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/api/segment/size" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: text/plain" \
  -d 'FILTER AND (country = "US", NOT products_purchased INTERSECTS ("socks")) FROM user ALIAS us_no_socks'

ステップ 6：下書きを提示する（確認ゲート）

作成前に、ユーザーに概要をすべて提示します。

## Proposed Audience: US Non-Sock Buyers

**Name**: US Non-Sock Buyers
**Slug**: us_no_socks
**Table**: user
**Kind**: segment

**Description**: US customers who have not purchased socks

**Field Mapping**:
- "US customers" -> `country = "US"` (field type: string, sample values: US, CA, UK)
- "haven't purchased socks" -> `NOT products_purchased INTERSECTS ("socks")` (field type: []string)

**FilterQL**:
FILTER AND (country = "US", NOT products_purchased INTERSECTS ("socks")) FROM user ALIAS us_no_socks

**Estimated Size**: ~45,000 profiles

続けて、未加工の API ペイロードを表示します。

{
  "name": "US Non-Sock Buyers",
  "slug_name": "us_no_socks",
  "description": "US customers who have not purchased socks",
  "segment_ql": "FILTER AND (country = \"US\", NOT products_purchased INTERSECTS (\"socks\")) FROM user ALIAS us_no_socks",
  "kind": "segment",
  "table": "user",
  "is_public": true,
  "save_hist": true,
  "tags": []
}

確認を求めます：「このセグメントを作成しますか？（yes/no）」

ステップ 7：承認後に実行する

curl -s -X POST "${LYTICS_API_URL:-https://api.lytics.io}/v2/segment" \
  -H "Authorization: ${LYTICS_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ ... approved payload ... }'

結果を報告します。

Successfully created segment "US Non-Sock Buyers" (id: abc123)
View at: ${LYTICS_API_URL}/segment/us_no_socks

作成に成功したら、オーディエンススナップショットの利用を提案します。 「セグメントを作成しました。人口統計の内訳とフィールドの分布を示すオーディエンススナップショットを表示しますか？」 「はい」の場合は、新しいセグメント ID を指定して audience-snapshot skill を呼び出します。

曖昧さへの対応

フィールドの割り当てが曖昧な場合（同程度に有力な候補が複数ある場合）：

1. サンプル値とともに有力候補を提示する
2. 文脈に基づいて最適な候補をエージェントに選ばせる。真に曖昧な場合を除き、ユーザーには尋ねない
3. 真に候補が同等の場合、またはフィールドの目的が不明な場合に限り、ユーザーに尋ねる

既存のセグメントの更新

ユーザーが既存のセグメントの更新を希望する場合：

1. 現在のセグメントを取得する：GET /v2/segment/${ID}?inline=true
2. 現在の FilterQL と変更案を表示する
3. POST の代わりに PUT /v2/segment/${ID} を使用する

エラー処理

• 一致するフィールドがない場合：明確に報告し、データの説明方法を変えるよう提案します
• 3 回の再試行後も検証に失敗する場合：FilterQL とエラーを表示し、支援を求めます
• セグメントが空の場合（サイズ 0）：警告し、条件を広げるよう提案します
• セグメントが非常に大きい場合（全体の 90% 超）：その旨を伝え、意図を確認します

依存関係

• 構成要素：schema-discovery skill、filterql-builder skill、segment-manager skill、../references/confirmation-gate.md
• 参照先：../references/auth.md、../references/filterql-grammar.md、../references/field-types.md