Source Import Workflow

CSV や外部 source を持ち込み、canonical company に解決して、saved List と enrichment / export まで進めます。

いつ使うか

• 展示会リード、既存顧客、外部調査の CSV を Signal Foundry の workspace に置きたい
• CSV の会社名、法人番号、証券コード、domain を canonical company_id に解決したい
• multiple_candidates を人間が確認してから saved List にしたい
• 保存後に website enrichment を足し、CSV で export したい

自然文から会社群を探す場合は、このページではなく List Workspace Loop を使います。

CSV shape before import

CSV には、会社を識別できる column を少なくとも 1 つ含めます。精度を上げるには、会社名だけでなく法人番号、証券コード、domain を足してください。

会社名,法人番号,証券コード,URL
株式会社サンプル,1234567890123,1234,https://example.com

CSV 例に API key、顧客秘密情報、private URL、raw transcript を入れないでください。agent に渡す sample は匿名化した値にしてください。

Import

まず CSV を source として保存します。

sf source import ./companies.csv --name "展示会リード" --json

見る key:

• source.source_id
• source.row_count
• headers[]
• mapping.status

source.source_id を以後の <sourceId> として使います。import / inspect / map / review は data credit を消費しません。

Inspect

headers、row count、現在の mapping 状態を確認します。

sf source inspect <sourceId> --json

見る key:

• source.source_id
• source.row_count
• headers[]
• mapping.status
• sample_rows[]

ここで必須 column が足りない場合は、CSV を直して import し直します。会社名だけで曖昧になりそうな source は、法人番号、証券コード、domain のどれかを追加してください。

Map

CSV header を company field に対応付けます。

sf source map <sourceId> --entity company --column name=会社名 --column corporate_number=法人番号 --column ticker=証券コード --column domain=URL --json

見る key:

• mapping.status
• mapping.mapped_fields
• mapping.missing_headers
• mapping.unmapped_required_columns

unmapped_required_columns が返る場合は、resolve に進みません。CSV header 名を確認し、--column <field>=<header> を直して再実行します。

対応 field は Source API を確認してください。API の実装詳細はこの workflow では扱いません。

Resolve with credit cap

mapped row を canonical company に解決します。保存系の実行なので、--execute と --max-credits を必ず付けます。

sf source resolve <sourceId> --execute --max-credits 100 --json

API から直接呼ぶ場合も、body では maxCredits を明示します。

見る key:

• run.resolved_count
• run.multiple_candidates_count
• run.not_found_count
• run.review_required_count
• resolution.resolved_count
• resolution.multiple_candidates_count
• resolution.not_found_count
• source.resolve_summary.matched
• source.resolve_summary.multiple_candidates
• billing.credits_used
• billing.max_credits

credit は matched row の Basic credit で発生します。agent は billing から件数を推測せず、run.*_count を読みます。multiple_candidates は勝手に 1 社へ確定しません。

Review and select ambiguous rows

multiple_candidates が 1 件でもある場合は、review で候補を確認します。

sf source review <sourceId> --status multiple_candidates --json

見る key:

• review.total_reviewable_rows
• rows[].source_row_id
• rows[].resolve_status
• rows[].resolve_candidates
• rows[].needs_human

人間が候補を選んだ row だけ select します。

sf source select <sourceId> --row <sourceRowId> --company <companyId> --max-credits 1 --json

見る key:

• selected.source_row_id
• selected.company_id
• billing.credits_used
• review.multiple_candidates_remaining
• next_actions

source select は新しく確定する row にだけ Basic credit を使います。候補に含まれない company_id は指定しないでください。

Create List

resolve 済み rows から saved List を作ります。

sf list create --from-source <sourceId> --name "展示会リード" --json

見る key:

• list.list_id
• list.row_count
• source.source_id
• billing.credits_used

この時点で saved List になり、UI では List / row / evidence / run を確認できます。preview ではないため、次に enrichment と export へ進めます。

Enrich / export

website enrichment は estimate してから実行します。

sf list enrich <listId> --source website --estimate --json
sf list enrich <listId> --source website --execute --max-credits 100 --json
sf list export <listId> --format csv --output ./exports/imported-leads.csv --json

見る key:

• estimate.estimated_max_credits
• run.run_id
• run.found_count
• run.not_found_count
• billing.credits_used
• export.path
• export.row_count
• export.sha256

enrichment は追加 column / evidence / run を作るため、実行時に credit 境界があります。export は saved List から出力します。candidate preview や unresolved rows は export 前に確定してください。

確認する key

この workflow 全体では、次の key を順番に確認します。

• source.source_id
• source.row_count
• headers[]
• mapping.status
• mapping.unmapped_required_columns
• run.resolved_count
• run.multiple_candidates_count
• run.not_found_count
• run.review_required_count
• resolution.resolved_count
• resolution.multiple_candidates_count
• source.resolve_summary.matched
• source.resolve_summary.multiple_candidates
• billing.credits_used
• list.list_id
• run.run_id
• export.sha256

If it fails

unmapped_required_columns が返る場合:

1. sf source inspect <sourceId> --json を実行します。
2. headers[] と mapping.missing_headers を確認します。
3. sf source map <sourceId> --entity company --column name=<header> --json の header 名を直します。

max_credits_exceeded が返る場合:

1. run.resolved_count と billing.max_credits を確認します。
2. row を分割するか、--max-credits <n> を見積もり以上にして再実行します。
3. credit 残量が不明なら sf credits balance --json を実行します。

multiple_candidates が残る場合:

1. sf source review <sourceId> --status multiple_candidates --json を実行します。
2. rows[].resolve_candidates を人間に見せます。
3. 自動確定せず、明示された候補だけ sf source select ... --json で確定します。

not_found が多い場合:

1. 会社名だけでなく、法人番号、証券コード、domain を CSV に追加します。
2. map を更新して resolve を再実行します。
3. それでも候補がない row は company_not_found として扱い、silent 0 件にしないでください。

Next

• source API contract を確認する: Source API
• saved List の標準 loop を確認する: List Workspace Loop
• export まで含めた List API を確認する: リストAPI