Codexの結果をJSONで受け取る

Codexの結果を次のプログラムへ渡すとき、自由な文章では項目を取り出しにくいことがあります。JSONは、項目名と値を対応させて表すデータ形式です。Codex CLIでは、出力の形をJSON Schemaで指定する方法があります。

この記事では、メモから題名と公開状態を取り出す例で、形式と内容を別々に確認する方法を説明します。先にexecの一回実行を利用できる状態にしてください。

JSONLと最終回答のJSONを分ける

進捗ログが欲しいのか、最後のデータだけが欲しいのかで使い分けます。この例では最終回答をJSONとして保存します。

取り出す項目を二つに絞る

練習用リポジトリに memo.txt を作り、次の内容を保存します。

題名：春の読書会
公開状態：下書き
参加方法はこれから確認する。

取り出す項目は title と status です。状態は draft・published・unknown にそろえます。これは練習用の取り決めで、「下書き」は draft、公開済みは published、判断できない状態は unknown と対応付けます。

Schemaで形を指定する

同じフォルダーの schema.json に次を保存します。

{
  "type": "object",
  "properties": {
    "title": { "type": "string" },
    "status": { "type": "string", "enum": ["draft", "published", "unknown"] }
  },
  "required": ["title", "status"],
  "additionalProperties": false
}

required は必要な項目、additionalProperties: false は指定外の項目を認めない条件です。enum は選べる値の一覧です。

各段階で確認してから、次の操作へ進みます。

1. 1項目を決める題名と状態。不明な状態も表せる形にします。
2. 2Schemaを指定必要なキーと許可する値を定義します。
3. 3二段階で確認JSONの形を確認した後、元のメモと値を照合します。

具体的な依頼と、結果の確かめ方は本文にあります。

形が合っていても、題名や公開状態の読み取りが正しいとは限りません。最後に元のメモと照合します。

最終回答をファイルへ保存する

二つのファイルがあるフォルダーで、次を実行します。既存の result.json があれば別の出力名を選びます。

codex exec --sandbox read-only --output-schema schema.json -o result.json "memo.txtから題名と公開状態を取り出してください。下書きはdraft、公開済みはpublished、不明はunknownです。題名がなければ空文字にし、推測しないでください。元ファイルは変更しないでください。"

このメモから期待する結果は、次の内容です。キーの並びや空白が異なっても、値が同じならこの例の意味は同じです。

{
  "title": "春の読書会",
  "status": "draft"
}

これは期待する結果の見本であり、モデルの実行ログではありません。

分からない場合の設計も必要

この練習では公開状態が明記されています。不明な状態も表せるよう unknown を認めています。後続の処理では unknown や空の題名を検出したら、人が確認する経路へ分けるなどの扱いを決めます。

必ず二択を選ばせる形式のままでは、不明でもどちらかを埋める原因になります。形式の制約と、業務上の判断条件を合わせて設計します。

次の処理へ渡す前に確認する

1. コマンドが成功して結果ファイルを取得できたか。
2. JSONとして読み取れるか。
3. 必要なキーと型、許可した状態に合っているか。
4. 題名と状態が元のメモに一致するか。

4番目まで確認してから後続へ渡します。特に公開や送信を伴う処理では、JSONの published という文字だけを無条件の実行指示にしないようにします。

続けて使うとき

入力例をいくつか作り、欠落、別表記、不明な状態もテストへ含めます。複数回使うなら、失敗時に既存の結果ファイルを誤って再利用しない仕組みも必要です。

オプションは公式の非対話実行資料とCLIヘルプで照合しています。この記事ではモデルによる抽出の成功を実測していません。実際の利用では結果の形と内容をそれぞれ確かめてください。

既存の表を渡す場合は、CSVからJSONへの変換で型と空欄の扱いを決めます。