AIチュートリアル

VerdictでCLIの結果をローカル分類

Verdictのインストール方法、PythonまたはCLIでコマンド出力を分類する方法、4つの結果ラベルの解釈、そして決定論的な検証を置き換えずに、ローカルの197 KBモデルをコーディングエージェントやCIワークフローに統合する方法を学びます。

2026年11月4日約11分で読了

Verdictの概要

Verdictは、コーディングエージェント、CIランナー、その他のツール実行システム向けに、意味的な結果判定レイヤーを検証するリサーチプレビューです。プロセスの終了コードを決定的な証拠として扱うのではなく、コマンド、終了コード、標準出力、標準エラーをまとめて調べます。

モデルは、success、failure、blocked、unknownの4つのラベルのいずれかを返します。この区別が有用なのは、コマンドが終了コード0で終了していても、テストを1件も実行していなかったり、HTTP 500レスポンスを返していたり、ワーカーを待機していたり、不完全な出力を生成していたりする可能性があるためです。同様に、ゼロ以外の終了コードも、アサーションの失敗ではなく、環境上のブロッカーを示している場合があります。

重要: Verdictは助言を行う分類器です。タスクが完了したことや、環境が意図どおりに変更されたことを証明するものではありません。決定的なチェックと、信頼できる状態検証を真実の基準として維持してください。

主な機能

ローカル推論: 入力はネットワーク通信やテレメトリーなしで、ローカルCPU上で処理されます。
小型モデル: 量子化モデルのサイズは約197 KBです。
依存関係ゼロのランタイム: 推論にはPython標準ライブラリを使用し、パッケージ自体以外にトークナイザーファイル、GPU、Pythonランタイム依存関係は必要ありません。
意味的分類: 終了コードだけに依存せず、コマンド、終了コード、標準出力、標準エラーを考慮します。
高速な予測: リポジトリによると、ドキュメントに記載されたWindows 11、AMD64、Python 3.12のベンチマーク環境では、推論時間の中央値は0.54 msです。
PythonおよびCLIインターフェース: アプリケーション内でモデルを使用することも、シェルパイプラインから直接使用することもできます。
ブラウザーでのデモ: プロジェクトページでは、ログをアップロードせずに、同じ量子化済み重みをブラウザー内で実行できます。

Verdictは、ハッシュ化した文字3～5-gramと単語1～3-gramに、多クラスロジスティック回帰を組み合わせて使用します。入力はUTF-8テキストで、各出力ストリームは明示的な先頭・末尾クリッピングにより12,288文字に制限されます。

4つのラベルを理解する

success: 操作が完了したことを示す肯定的な証拠が出力に含まれています。
failure: 操作は実行され、具体的な失敗が報告されました。
blocked: 権限、依存関係、ネットワーク、クォータ制限、または環境によって実行が妨げられました。
unknown: 証拠がない、不完全である、スキップされた、ドライランに限られている、またはその他の理由で結論が出せません。

返される確率は線形多クラスモデルから得られます。安全性が重要な意思決定における、校正済みの信頼度として解釈してはいけません。

Verdictをインストールする

リポジトリをクローンし、そのディレクトリに移動して、pipでパッケージをインストールします。

git clone https://github.com/Balanov/verdict.git
cd verdict
python -m pip install .

これにより、verdict_tiny Pythonパッケージとverdictコマンドラインインターフェースがインストールされます。

最初のPython予測を実行する

Verdictのインスタンスを作成し、ツールランナーが取得したものと同じ証拠を渡します。次の例は、正常終了したものの、実際にはテストを1件も実行していないpytestプロセスを表しています。

from verdict_tiny import Verdict

model = Verdict()
result = model.predict(
    command="pytest tests/",
    exit_code=0,
    stdout="collected 0 items\nno tests ran in 0.01s",
)
print(result)

ドキュメントに記載されたモデル出力では、終了コードが0であるにもかかわらず、この証拠をunknownに分類します。

{
  "label": "unknown",
  "confidence": 0.999981,
  "probabilities": {
    "success": 0.000019,
    "failure": 0.0,
    "blocked": 0.0,
    "unknown": 0.999981
  },
  "advisory": true
}

labelは選択された結果です。probabilitiesオブジェクトにはすべてのクラスのスコアが示され、advisoryは、この予測が権威ある証明ではないことを強調します。

コマンドラインからVerdictを使用する

元のコマンドと終了コードを指定しながら、コマンドの出力をVerdictにパイプできます。

printf 'collected 0 items\nno tests ran\n' | verdict \
  --command 'pytest tests/' --exit-code 0

すでにファイルに保存されている出力には、--stdoutと--stderrを使用します。

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log

特定の場所から重みを読み込むこともできます。

verdict \
  --command 'pytest tests/' \
  --exit-code 0 \
  --stdout output.log \
  --stderr error.log \
  --weights /path/to/verdict-q8.bin

Verdictを安全に統合する

実用的な統合では、Verdictを最終的な判定者ではなく、追加の判断材料として扱う必要があります。コーディングエージェントやCIランナーは、ラベルに基づいて、追加の証拠を調べるか、操作を再試行するか、人による確認を求めるかを判断できます。

元のコマンドを実行し、終了コード、標準出力、標準エラーを保持します。
利用可能なすべての証拠をVerdictに渡します。
予測されたラベルとクラス確率の両方を確認します。
結果に影響する操作を行う前に、アプリケーション固有のしきい値を適用します。
テスト数、生成されたファイル、APIの状態、データベースレコードなどの決定的なチェックで完了を検証します。

たとえば、unknownの結果が出た場合は、通常、完了したと主張するのではなく、さらに調査を行うべきです。blockedの結果が出た場合は、再試行する前に認証情報、依存関係、接続性、権限、クォータを確認するのが適切です。正確性が重要な場合、successの結果でも、信頼できる検証が必要です。

高度なヒント

完全な実行コンテキストを保持する

可能な限り、実際のコマンド、終了コード、標準出力、標準エラー出力を提示してください。ストリームを省略すると、具体的な失敗と環境上のブロッカー、または結論の出ない実行結果を区別する証拠が失われる可能性があります。

入力の切り詰めを考慮する

各出力ストリームは、先頭と末尾を残す切り詰めにより12,288文字に制限されます。ログが非常に大きい場合は、決定的なメッセージが先頭または末尾付近に現れるようにするか、完全なログを追加で決定論的にスキャンしてください。

保守的な判定しきい値を設定する

これらの確率は、安全性が重要な用途における意味で校正された信頼度ではありません。ワークフローに適したしきい値を使用し、不確実なケースや重大な影響を伴うケースは、決定論的なチェックまたは人によるレビューに回してください。

カスタムまたはダウンロードした重みを使用する

公開されている量子化済み重みはweights/verdict-q8.binに保存されており、Hugging Faceからも入手できます。CLIでは--weightsを使って別の重みのパスを指定できます。

ブラウザデモを試す

Verdictのプロジェクトページでは、同じ量子化済み重みをブラウザ上で実行できます。プロジェクトのドキュメントによると、ログはアップロードされません。

学習と評価を再現する

学習用および開発用の追加依存関係をインストールし、合成コーパスを再生成してモデルを学習し、int8重みをエクスポートし、アーティファクトを評価して、テストを実行します。

python -m pip install -e '.[train,dev]'
python training/train.py
pytest -q

公開ベンチマークでは、学習に含まれていない48のCLIファミリーから、192件の合成例を使用します。学習では、異なる60のファミリーから1,440件の合成例を使用します。報告された量子化モデルの正解率は93.2%、マクロF1は93.2%でした。一方、終了コードベースラインの正解率は47.9%、マクロF1は31.9%でした。

コーパスは合成データであり、英語に偏っています。これらの測定値が評価するのは保留されたテンプレートであり、本番環境のエージェントトレースに対する信頼性ではありません。また、レイテンシーの結果は、ハードウェアを問わず保証されるものではありません。

プロジェクトの限界を理解する

Verdictは意図的に対象を絞っています。CLI出力で観測された証拠を分類しますが、より広範なタスクが完了したかどうかを判断するものではありません。また、コードの正しさ、安全性、真実性を立証するものでもありません。

したがって、このプロジェクトは、生のプロセス実行結果とエージェントの次のアクションの間に置く意味解釈レイヤーとして使うのが最適です。終了コードでは捉えられない証拠を特定できますが、テスト、状態の検査、検証ルール、人間の判断を置き換えるのではなく、それらを補完するものとして利用してください。

まとめ

Verdictは、終了コードだけによるチェックよりも慎重にCLIの結果を解釈するための、小さく高速なローカル手段を提供します。Pythonパッケージとしてインストールし、完全な実行コンテキストを渡し、4つのラベルを使ってフォローアップアクションを導いてください。信頼性の高い自動化のため、必ずその助言的な結果を、決定論的で権威のある検証と組み合わせてください。