概要

External Research と Credits

external research と product credits を、canonical data から分けて説明します。

このページの内容6項目

External research は、canonical company data と分けて保存する補助調査 layer です。Credits は、保存や enrichment によって workspace artifact が作られたことを測る ledger です。

この 2 つを同じページで扱う理由は、どちらも「読むだけ」と「保存・追加すること」を分けるためです。

Data Layers

Layer	Holds	Boundary
Canonical company data	company, identifiers, profile, observations, filings	再利用前提の正本
External research	web search, crawl, PDF extract, manual note	canonical に混ぜない補助情報
Session artifact	agent の一時要約や作業メモ	durable record ではない
List workspace	saved row, column, evidence, run	選択と実行の履歴

External research item は、現行 public contract では company_id に紐付けます。company-less / list-scoped research item は deferred surface です。

External Research Boundary

External research は、最初から canonical observation に昇格しません。

理由:

source quality が一定ではない
crawl / search / manual note は再現性が違う
promotion には review が必要
account-scoped artifact と public canonical data は分ける必要がある

Current public surface:

GET /api/signal-foundry/research/items
POST /api/signal-foundry/research/items
sf research ls
sf research add
/home/research

Deferred / advanced:

automatic canonical promotion
queue / retry / schedule
company-less research workspace

Credit Boundary

Credits は、workspace artifact を作る実行を測ります。

Credit Type	Used By	Charged When
Basic	`source resolve`, `source select`, `list materialize`	company row が resolve / saved された時
Enrichment	`list enrich --execute`	enrichment source が `found` になった時

無料でできること:

capability check
list plan / estimate / candidates
source import / inspect / map
list enrich estimate
saved List export
feedback create

credit を使うこと:

matched source row の resolve
multiple_candidates からの明示 select
saved List materialize
found enrichment row

Balance と Summary

Command / Endpoint	Use For
`sf credits balance --json`	実行前に使える credit と grant breakdown を見る
`GET /credits/balance`	integration から実行可否を判定する
`sf credits summary --json`	直近の usage event を見る
`GET /credits`	ledger summary を読む

balance は「今実行できるか」、summary は「何が起きたか」です。

Failure Boundary

credit 系の失敗は、データなしではありません。

Error	Meaning	Recovery
`max_credits_required`	実行上限が指定されていない	`--max-credits <n>` を付ける
`max_credits_exceeded`	見積もりが上限を超えた	query を絞るか上限を上げる
`credit_balance_insufficient`	利用可能 credit が足りない	`credits balance` で grant を確認

詳しくは credit と maxCredits の失敗を使います。

次に読むページ

external research API: Research Items API
credit balance: Credits Balance API
credit summary: Credits Summary API
saved List loop: List Workspace Loop

概要