分析ランと status

このガイドでは、run を開始し、terminal state まで polling し、semantic result を検証してから kind ごとの結果を読み取る方法を説明します。

すべての run には kind が必要です。値は workflow または analysis です。両方の kind が同じ top-level status を使います。

queued -> processing -> completed | failed | canceled

kind-specific detail は workflow または analysis にあります。top-level status は polling を停止する時点を判断する唯一の値です。status は run が停止したことを示します。確認済みの answer が返ったことは示しません。completed の analysis run でも、result は uncertain または partial coverage になることがあります。

Workflow run を開始する

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/runs" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: workflow-run-01" \
  -d '{
    "kind": "workflow",
    "workflow_id": "wf_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
    "source_snapshot": {"source_ids":["vid_0190b5d4-7e1f-7a2b-9c3d-1234567890ab"]},
    "execute_now": true
  }'

202 response は受付を示します。完了は示しません。ワークフロー run は検出結果を作り、kind detail にワークフロー id と source snapshot を記録します。

Analysis run を開始する

保存済みの profile_id と report_template_id reference を使い、必要に応じて profile_version と report_template_version を指定します。Analysis で説明する方法です。POST /api/v1alpha1/runs では inline profile と report template body を拒否します。formats と admitted な execution_profile_ref も送ります。

Run を polling する

curl --fail-with-body "$BASE_URL/api/v1alpha1/runs/$RUN_ID" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY"

type ResultState = 'found' | 'not_found' | 'uncertain' | 'not_checked' | 'error';

type Run = {
  kind: 'workflow' | 'analysis';
  status: 'queued' | 'processing' | 'completed' | 'failed' | 'canceled';
  analysis?: {
    result_state?: ResultState;
    reason_code?: string;
  };
};

const terminal = new Set(['completed', 'failed', 'canceled']);

async function waitForRun(run_id: string): Promise<Run> {
  while (true) {
    const response = await fetch(`${baseUrl}/api/v1alpha1/runs/${run_id}`, {
      headers: { Authorization: `Bearer ${apiKey}` },
    });
    if (!response.ok) throw new Error(`run read failed: ${response.status}`);
    const run = await response.json() as Run;
    if (terminal.has(run.status)) return run;
    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }
}

const run = await waitForRun(RUN_ID);
if (run.status !== 'completed') throw new Error(`run did not complete: ${run.status}`);
if (run.kind === 'analysis' && run.analysis?.result_state !== 'found') {
  throw new Error(
    `run is not a successful checked result: ${run.analysis?.reason_code ?? 'result state is not found'}`,
  );
}

analysis run の processing 中の進捗は analysis.sub_state で確認します。workflow run は status より細かい進捗を報告しません。内部の処理段階は公開 contract の一部ではないためです。field がないことから terminal state を推測しないでください。

terminal response の後に、analysis answer を使う前に analysis.result_state と analysis.reason_code を確認してください。status: completed は execution が停止したことを示すだけで、semantic success を示しません。evidence-backed な positive result には analysis.result_state: found が必要です。uncertain、not_checked、error は success state ではありません。not_found は確認済みの negative にはなれますが、positive pass ではありません。各 answer の result_state、coverage、limitations、evidence も確認してから value を使ってください。

完了した analysis run に、確認済みの answer が 1 つもない場合があります。必要な evidence が利用できないか不完全な場合、または answer を確認する前に分析予算を使い切った場合に起きます。動画が長いと分析予算を使い切ることがあります。この場合、run は completed でも analysis.result_state は not_checked になり、1 つ以上の answer が result_state: not_checked になることがあります。reason_code と limitations を確認してから対応を決めてください。completed と uncertain または partial は success ではありません。

Answer の semantic result を検証する

report を作成または使用する前に、answer の full projection を読み取ります。次の expand[] は event 単位の evidence と、詳細な coverage と limitation を含む answer payload を返します。

ANSWERS="$(curl --fail-with-body --get "$BASE_URL/api/v1alpha1/runs/$RUN_ID/answers" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  --data-urlencode "expand[]=events" \
  --data-urlencode "expand[]=events.evidence")"

if ! jq -e '
  (.data | length > 0)
  and all(.data[];
    .result_state == "found"
    and .coverage.state == "complete"
    and ((.answer_payload.coverage.gaps // []) | length == 0)
    and ((.answer_payload.limitations // []) | length == 0)
    and (.evidence_count > 0)
  )
' <<<"$ANSWERS" >/dev/null; then
  echo "The run is not a clean, complete, evidence-backed result." >&2
  exit 1
fi

これは full-scope の strict gate です。空でない limitations は隠さず確認してください。coverage.state が complete 以外の場合、または coverage.gaps が空でない場合は partial または limited であり、full-video の success ではありません。timeline answer では、すべての answer_payload.events[] と必須 attribute も確認してください。report が使う各 claim には result_state と timestamp 付きで review 可能な evidence reference が必要です。aggregate の evidence_count が 0 より大きいだけでは十分ではありません。

Result States

answer-level semantic result は 4 つの result state を使います。run-level の analysis.result_state には、trustworthy な result が得られる前に execution が失敗した場合の error も含まれます。下の presentation table は answer-level state にだけ適用され、言い換えるだけで reclassify しません。

JSON の answer、report、manifest には machine state、reason code、limitation code を保持します。reader には平易な presentation を使い、code-level の詳細が必要な場合は JSON artifact を参照してください。

Reason Code を読む

reason_code は result_state の理由を示します。次の値が DeepFrame API の reason code です。

未知の reason code は fatal として扱わず、result_state と limitations を読み取って対応してください。

Run を cancel する

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/runs/$RUN_ID/cancel" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Idempotency-Key: run-cancel-01"

cancel は非同期です。top-level status が canceled になるまで polling してください。

Result を読む

• ワークフロー run: GET /api/v1alpha1/findings?run_id={run_id}。VIEW_INSIGHTS を使います。
• analysis run: GET /api/v1alpha1/runs/{run_id}/answers。VIEW_INSIGHTS を使います。
• presentation: 完了後に自動生成された artifact を読み取ります。別の presentation が必要な場合だけ POST /api/v1alpha1/runs/{run_id}/reports で明示的に rerender し、分析ガイド で persisted artifact を一覧して取得します。

analysis run では、answer の value を使う前に result_state、reason_code、coverage、limitations、evidence を確認してください。uncertain、not_checked、または partial coverage の answer は success ではありません。not_found は確認済みの negative にはなれますが、positive pass ではありません。

list operation は {data, next_cursor, has_more} envelope を使います。規約 を参照してください。