レポートとテンプレート

保存済みの分析 answer を、再分析なしで決定的な JSON または Markdown レポートに整形します。

このガイドでは、block、column、grouping、sort、JSON mapping を使って、保存済みの分析 answer を report に整形する方法を説明します。

Report template language は表示方法だけを指定します。分析 answer、エビデンス、result state、limitations、provenance は変更しません。保存済み template がこの language を使い、rerender request は inline の表示用 view を指定できます。

この language は analysis answer を表示します。findings を audit view に変換する adapter は planned であり、admitted な kind ではありません。

Answer から report までの lifecycle

profile の instructions と answer_specs が名前付き answer を生成します。answer_specs[].answer_key が answer 1 件の安定した名前です。
answer_specs[].fields が、その名前付き answer 内の typed answer data を定義します。field は semantic data であり、report layout ではありません。
report template が answer_key、field column、label、group、sort、JSON mapping で既存の answer data を選択し、整形します。
rerender は presentation-only です。保存済み answer を読み、新しい view または format を作ります。analysis を再実行せず、answer data、evidence、uncertainty、limitation、provenance を変更しません。

Template を使う場所

次の request で template を指定できます。

保存済み profile_id と report_template_id、必要な immutable version を参照して新しい分析ランを作る POST /api/v1alpha1/runs。ここでは inline profile と template を受け付けません。
再利用する template を保存する POST /api/v1alpha1/report-templates
immutable な version を追加する POST /api/v1alpha1/report-templates/{report_template_id}/versions
再分析なしで保存済み answer から表示を作る POST /api/v1alpha1/runs/{run_id}/reports。inline report_template を受け付けるのはこの endpoint です。

Request では answer_key、group_by、sort_by、sort_direction、field_labels、columns を使います。wire key の field_labels は DTO では fieldLabels と呼ばれることもあります。JSON mapping の answer data path では、result_state や values.0.value のように answer contract の名前を使います。

Template の形

Template は language と 1 つ以上の block を持ちます。各 block は answer_key で名前付き answer を選び、label で出力名を指定します。

{
  "language": "ja",
  "blocks": [
    {
      "type": "timeline",
      "answer_key": "inspection_timeline",
      "label": "点検タイムライン",
      "columns": [
        {"key": "activity", "label": "作業"},
        {"key": "zone", "label": "区域"}
      ]
    },
    {
      "type": "narrative",
      "answer_key": "inspection_summary",
      "label": "概要"
    }
  ]
}

rerender template の id と version は任意の表示用 metadata です。保存済み template には server が resource identity と immutable version を割り当てます。run create はその値を参照し、template body は受け付けません。

answer_key は profile が生成した answer を識別します。activity のような field key は、その answer 内の既存の typed field を識別するもので、別の answer key ではありません。block は既存 field を表示するだけで、semantic field を作りません。

Block Type

timeline は timestamp 付き event を表示します。events と event attribute を持つ answer に使います。

narrative は answer の narrative を文章として表示します。

table は answer の value、enumeration item、series point、comparison point を行として表示します。明示的な列、group、sort が必要な場合に使います。

value は最初の表示可能な value set を compact な field list として表示します。小さな summary に使います。

json は allowlist した answer path から、指定した JSON object を作ります。固定した machine-readable shape が必要な consumer に使います。

対応する block type は timeline、narrative、table、value、json です。未知の block type と未知の block key は HTTP 422 で拒否されます。language は自由な拡張 key を許可せず、任意の template code も実行しません。

Semantic interval と processing chunk

timeline answer では、analysis model が profile instruction と index 済み evidence から semantic interval を選びます。返される start_ms と end_ms は user-facing event を示します。DeepFrame が media を内部 processing chunk で調べても、その implementation window は event ではなく、report block として公開しません。interval が不明確な場合は、精度を作らず uncertain または limitation を保持します。

Column、Group、Sort

columns は {key, label} の順序付き list です。JSON と Markdown の出力順は template の順序になります。columns を省略すると、answer field の source order から列を作ります。

group_by は field を、出力する row または event の group に設定します。sort_by はその field で row または event を並べます。sort_direction は asc または desc です。sort_by がある場合の既定値は昇順です。同じ value の項目は source order を保ちます。

{
  "type": "table",
  "answer_key": "warehouse_metrics",
  "label": "区域別 metrics",
  "group_by": "zone",
  "sort_by": "value",
  "sort_direction": "desc",
  "columns": [
    {"key": "zone", "label": "区域"},
    {"key": "value", "label": "件数"}
  ]
}

古い field_labels（DTO では fieldLabels）は timeline block だけで使用できる、canonical な columns の selecting-and-relabeling fallback です。columns がない場合、各 key は選択した answer に既に存在する timeline attribute と一致し、その label だけを表示用に変更します。semantic field を作ることはできません。1 つの timeline block で field_labels と columns を同時に送らないでください。新しい template と table、value block では columns を使ってください。

JSON Mapping

mapping は、安全な output path から public answer projection の source path への mapping です。mapping key は render 前に sort されるため、同じ answer と template から同じ bytes が生成されます。

{
  "type": "json",
  "answer_key": "warehouse_metrics",
  "label": "Consumer payload",
  "mapping": {
    "status": "result_state",
    "summary": "narrative",
    "first_count": "values.0.value",
    "first_evidence": "values.0.evidence.0.id"
  }
}

JSON projection には answer value、result state、limitations、coverage state、evidence reference が含まれます。model identity、stage identity、execution provenance、signal-manifest identity は公開しません。provenance、stages、stage、signal_manifest_ref を root にする mapping は拒否されます。

Missing Field と Diagnostic

指定した column、group、sort field、JSON source が存在しない場合、renderer は construct を黙って捨てません。report document を保持し、field と path を含む block-level の missing_field diagnostic を追加します。report を complete と扱う前に diagnostic を確認してください。

answer に必要な data、evidence、binding reference がない場合は、problem detail で fail closed します。未知の template construct は template boundary で HTTP 422 になります。

Worked Example

次の request は、すべての表示機能を使う再利用可能な template を保存します。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/report-templates" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: template-create-20260824-01" \
  -d '{
    "name": "Warehouse summary",
    "description": "Compact operational report",
    "language": "ja",
    "blocks": [
      {
        "type": "table",
        "answer_key": "warehouse_metrics",
        "label": "区域別 metrics",
        "group_by": "zone",
        "sort_by": "value",
        "sort_direction": "desc",
        "columns": [
          {"key": "zone", "label": "区域"},
          {"key": "value", "label": "件数"}
        ]
      },
      {
        "type": "json",
        "answer_key": "warehouse_metrics",
        "label": "Machine payload",
        "mapping": {
          "status": "result_state",
          "count": "values.0.value"
        }
      }
    ]
  }'

分析ラン（Run）が完了した後、保存済み answer を別 format または別 view で render できます。この request は分析 engine を再実行しません。

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/runs/$RUN_ID/reports" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: report-rerender-20260824-01" \
  -d '{
    "report_template": {
      "language": "ja",
      "blocks": [
        {
          "type": "json",
          "answer_key": "warehouse_metrics",
          "label": "Export",
          "mapping": {
            "status": "result_state",
            "count": "values.0.value"
          }
        }
      ]
    },
    "formats": ["json", "markdown"]
  }'

出力は保存済み canonical answer の presentation projection です。動画を再分析しません。

このページの内容