Update documentation and version for 1.3.3

2026-10-05 00:22:24 +09:00
parent 889b0e0228
commit 172dccad92
4 changed files with 34 additions and 23 deletions
@@ -5,6 +5,15 @@ All notable changes to ComfyUI-ScriptFlow will be documented in this file.

 ## [Unreleased]

+
+## [1.3.3] - 2026-10-05
+
+- `MultiOutputScript (Jev)` runs local Clef GGUF models, Cloudflare's open-weight decision model
+  - A GGUF whose architecture is `clef` (llama.cpp native format, such as `ggml-org/Clef-Flash-GGUF`) is answered by the model's decision head instead of the lettered-option approximation used for general local models
+  - Every question about one `state` is answered in one forward pass, so batched questions cost one pass per request
+  - Needs the JamePeng fork of llama-cpp-python 0.4.2 or later; other local models keep working with older builds
+  - Text only, with the `state` and all questions of a request limited to 8,192 tokens
+  - Tested with Clef-Flash Q8_0 on Windows (Intel Arc, SYCL build); Linux and macOS are untested
 - Added an application recipe to `README.md` and `README.ja.md` that checks a prompt enhancer's output against its system prompt with `MultiOutputScript (Jev)`
  - The script splits the system prompt into rules, asks Jev whether the output breaks each one in a single request, and reports a score and the rules that are likely broken
  - A second script for long system prompts checks the system prompt in parts of about 1,000 characters, staying under the script step limit
@@ -3,7 +3,7 @@

 ---

-**Version:** 1.3.2
+**Version:** 1.3.3
 **License:** GPL-3.0

 System One の判断モデルを使える、安全な Python 風スクリプトノードです。
@@ -55,6 +55,7 @@ System One モデルはテキストを生成せず、1 回の高速な処理で

 - ComfyUI を実行している Python 環境に [llama-cpp-python](https://github.com/JamePeng/llama-cpp-python) をインストールします。JamePeng 版と、本家の [abetlen/llama-cpp-python](https://github.com/abetlen/llama-cpp-python) 0.3.35 で動作を確認しています。
 - 指示追従型（instruction-tuned）の GGUF モデルを `ComfyUI/models/LLM`（または `models/text_encoders`）に置きます。GGUF にはチャットテンプレート（`tokenizer.chat_template` メタデータ）が含まれている必要があります。ほとんどの指示追従型 GGUF には含まれています。Qwen3.5-9B Q8_0 と Gemma-4-E4B Q8 で動作を確認しています。
+- Cloudflare のオープンウェイトの判断モデル [Clef](https://huggingface.co/Cloudflare/clef-flash) を使う場合は、llama.cpp ネイティブ形式の Clef の GGUF（[ggml-org/Clef-Flash-GGUF](https://huggingface.co/ggml-org/Clef-Flash-GGUF) など）を同じフォルダに置きます。JamePeng 版の llama-cpp-python 0.4.2 以降が必要です。通常のチャットモデルとして変換された Clef の GGUF は汎用モデルとして扱われ、Clef の判断ヘッドは使われません。Windows（Intel Arc、SYCL ビルド）の Clef-Flash Q8_0 で動作を確認しています。Linux と macOS では未確認です。

 ## 主な機能
 - 複数の入力：数値とテキストの入力を自由に組み合わせられます。
@@ -124,8 +125,9 @@ ov1, ov2 = (512, 384) if w >= h else (384, 512)

 - **TypeSafe API**（基本）：質問をインターネット経由で Jev に送ります。
 - **ローカル GGUF モデル**（フォールバック）：Jev API を使えない場合や、テキストを手元のマシンから出したくない場合に使います。汎用の指示追従型モデルで Jev 風の判断を近似するもので、[SemIf (OpenJev)](https://github.com/TheoLeeCJ/SemIf-OpenJev) の方式に従い、文字を割り当てた選択肢の次トークン確率を 1 回の順伝播で読み取ります。テキストは生成せず、ネットワークにも何も送りません。答えや確率は Jev とは異なります。
+- **ローカルの Clef モデル**：[Clef](https://huggingface.co/Cloudflare/clef-flash) は、Jev と同じ種類の質問に答えるオープンウェイトの判断モデルです。GGUF のメタデータ `general.architecture` が `clef` のモデルを、Clef として扱います。Clef の GGUF を選ぶと、上の近似の代わりにモデルの判断ヘッドを使い、同じ `state` についての質問すべてに 1 回の順伝播で答えます。`state` と質問を Clef の入力書式に並べ、判断ヘッドが出す選択肢ごとのスコアを、質問ごとに softmax で確率にします。文章は生成せず、ネットワークにも何も送信しません。答えと確率は Jev とは異なります。

-スクリプトはどちらでも同じです。各バックエンドのセットアップは[インストール](#インストール)を参照してください。
+スクリプトはどれでも同じです。各バックエンドのセットアップは[インストール](#インストール)を参照してください。

 追加の入力：
 - `model`：`TypeSafe API`、またはローカルの GGUF モデル（`mmproj-*` ファイルは表示されません）。
@@ -134,9 +136,9 @@ ov1, ov2 = (512, 384) if w >= h else (384, 512)
 関数（`state` は文字列・辞書・リスト。テキストのみ）：
 - `jev.yes(state, question[, threshold])` → `bool`（Yes の確率が `threshold` 以上か。初期値 `0.5`）
 - `jev.noul(state, question)` → Yes の確率（`0.0`〜`1.0`）。しきい値と比較して使ってください。そのまま条件に使うとエラーになります。
- `jev.choice(state, question, options)` → 最も確からしい選択肢（`str`）。`options` はラベルのリスト、またはラベルから説明への辞書です（ローカルモデルでは 2〜16 個）。
+- `jev.choice(state, question, options)` → 最も確からしい選択肢（`str`）。`options` はラベルのリスト、またはラベルから説明への辞書です（汎用のローカルモデルでは 2〜16 個）。
 - `jev.probabilities(state, question, options)` → 各選択肢とその確率の `dict`（合計 `1.0`）。`options` は `jev.choice` と同じです。同じ引数で両方を呼んでも、問い合わせは 1 回です。
- `jev.score(state, question, levels)` → 順序付きの段階の説明に対する期待値（`float`、`0`〜`len(levels) - 1`）（ローカルモデルでは 2〜16 段階）
+- `jev.score(state, question, levels)` → 順序付きの段階の説明に対する期待値（`float`、`0`〜`len(levels) - 1`）（汎用のローカルモデルでは 2〜16 段階）

 ```python
 # it1: a prompt text
@@ -195,8 +197,9 @@ client.system_one(state=it1, questions={"q0": Noul(instructions="q1"), "q1": Nou

 注意：
 - TypeSafe API は `state` と質問をインターネット経由で送信します。外部に出せないテキストには使わないでください。
- ローカルモデルの質問は 1 回の順伝播で処理されます（GPU 上の 4B〜9B モデルで約 1〜1.5 秒）。モデルは実行ごとに最初の質問で読み込まれ（数秒）、実行が終わるとアンロードされて、ワークフローの残りのために VRAM を解放します。
+- 汎用のローカルモデルは、質問 1 つにつき 1 回の順伝播で処理します（GPU 上の 4B〜9B モデルで約 1〜1.5 秒）。Clef モデルは、1 回のリクエストに含まれる質問すべてを 1 回の順伝播で処理します（Intel Arc の内蔵 GPU 上の Clef-Flash Q8_0 で、300 トークンのリクエストが約 3 秒）。モデルは実行ごとに最初の質問で読み込まれ（数秒）、実行が終わるとアンロードされて、ワークフローの残りのために VRAM を解放します。
 - ローカルモデルの確率は較正されておらず、モデルによって変わります。しきい値は実際の入力で試して決めてください。
+- ローカルモデルのプロンプトは 8,192 トークンまでです。汎用モデルでは `state` と質問 1 つ、Clef では `state` と 1 回のリクエストの質問すべてがこの範囲に収まる必要があります。Clef はテキストのみに対応しています。
 - 実行ごとにコンソールへ `[ComfyUI-ScriptFlow] Jev requests: N, states: S, questions: Q, responses: M` を出力します。送ったリクエスト数、異なる `state` の数、質問数、返信があったリクエスト数です。返信数がリクエスト数より少なければ、途中のリクエストが失敗しています。同じ実行のキャッシュから答えた質問は数えません。
 - `typesafe-sdk` がインストールされていると、`httpx2`（SDK が使う HTTP クライアント）と `typesafe_sdk` のロガーを WARNING に設定するため、リクエストごとの INFO ログは表示されません。
 - `MultiOutputScript` はモデルを読み込まず、ネットワークにもアクセスしません。`jev` は使えません。
@@ -605,6 +608,7 @@ ov2 = len(issues)

 - v1.3.2 以降が必要です。v1.3.2 以降では、同じ `state` についての質問を 1 回のリクエストにまとめて送ります。このスクリプトのリクエストは 2 回なので、`max_jev_calls` は 2 以上にしてください。
 - `p` は、出力がそのルールを破っていると Jev が判断した確率です。確実な検査ではありません。テストでは、守られているルールを違反と判定することも、破られているルールを見逃すこともあり、`THRESHOLD` 付近の値は実行のたびに変わりました。違反と判定されたルールは、確認すべき候補として扱ってください。
+- このレシピは、TypeSafe API の Jev で作成しました。テストでは、ローカルの Clef-Flash モデルは、出力が守っているルールも含めて大半のルールを違反と判定したため、このレシピには向きません。
 - 参照画像のように、スクリプトに渡していない情報が必要なルールは判定できません。ユーザーの依頼文に関するルールを判定するには、依頼文を `in_text_3` につないでください。
 - `in_text_2` には、システムプロンプトのテキストそのもの、または `"system_prompt"` キーを持つ JSON 設定のテキストを渡せます。JSON の `\uXXXX` エスケープは復元しません。
 - `#`、`【`、`[...]` で始まる行は見出しとして扱います。見出しの下では、行頭から始まる行を 1 つのルールとし、字下げされた行は直前のルールに含めます。システムプロンプトがどう分けられたかは `out_text_3` で確認できます。
@@ -751,9 +755,6 @@ You should have received a copy of the GNU General Public License along with thi

 詳しいバージョン履歴は [CHANGELOG.md](CHANGELOG.md) を参照してください。

-### 現在のバージョン：1.3.2
- `MultiOutputScript (Jev)` がスクリプトを変えずに質問をまとめて送るように：同じ `state` の質問は 1 回のリクエストで送り、`state` が違うリクエストは同時に送る
- `max_jev_calls` が質問数ではなくリクエスト数を制限するように
- 実行ごとに Jev のリクエスト数、`state` 数、質問数、返信数をコンソールに出力
- TypeSafe SDK と HTTP クライアントのリクエストごとの INFO ログを非表示に
- `datetime.datetime.now()` と `datetime.date.today()` が実行を開始した時刻を返すように
+### 現在のバージョン：1.3.3
+- `MultiOutputScript (Jev)` が、ローカルの Clef の GGUF モデル（Cloudflare のオープンウェイトの判断モデル）をモデルの判断ヘッドで動かせるように。同じ `state` についての質問すべてに 1 回の順伝播で答える
+- プロンプトエンハンサーの出力をシステムプロンプトと照らし合わせる応用レシピを追加。長いシステムプロンプト用の 2 つめのスクリプトも含む
@@ -1,7 +1,7 @@
 # ComfyUI-ScriptFlow
 [en | [ja](README.ja.md)]

-**Version:** 1.3.2
+**Version:** 1.3.3
 **License:** GPL-3.0

 Safe Python-like script node for ComfyUI with a System One decision model.
@@ -53,6 +53,7 @@ The `MultiOutputScript` and `centi` nodes need no extra packages. `MultiOutputSc

 - Install [llama-cpp-python](https://github.com/JamePeng/llama-cpp-python) in the Python environment that runs ComfyUI. Tested with the JamePeng fork and the upstream [abetlen/llama-cpp-python](https://github.com/abetlen/llama-cpp-python) 0.3.35.
 - Put an instruction-tuned GGUF model in `ComfyUI/models/LLM` (or `models/text_encoders`). The GGUF must include a chat template (`tokenizer.chat_template` metadata), as most instruction-tuned GGUFs do. Tested with Qwen3.5-9B Q8_0 and Gemma-4-E4B Q8.
+- To use [Clef](https://huggingface.co/Cloudflare/clef-flash), Cloudflare's open-weight decision model, put a Clef GGUF in the llama.cpp native format, such as [ggml-org/Clef-Flash-GGUF](https://huggingface.co/ggml-org/Clef-Flash-GGUF), in the same folder. It needs the JamePeng fork of llama-cpp-python 0.4.2 or later. A Clef GGUF converted as an ordinary chat model is treated as a general model and does not use Clef's decision head. Tested with Clef-Flash Q8_0 on Windows (Intel Arc, SYCL build); Linux and macOS are untested.

 ## Key Features
 - Multiple inputs: freely combine numeric and text inputs.
@@ -122,8 +123,9 @@ Same inputs, outputs, and script rules as `MultiOutputScript`, plus a `jev` name

 - **TypeSafe API** (primary): sends the questions to Jev over the internet.
 - **Local GGUF model** (fallback): for when the Jev API is not available, or when text must stay on your machine. It approximates Jev-style decisions with a general instruction-tuned model, reading the answer from next-token probabilities of lettered options in one forward pass, following [SemIf (OpenJev)](https://github.com/TheoLeeCJ/SemIf-OpenJev). No text is generated and nothing is sent over the network. Answers and probabilities differ from Jev's.
+- **Local Clef model**: [Clef](https://huggingface.co/Cloudflare/clef-flash) is an open-weight decision model with the same question types as Jev. A GGUF whose `general.architecture` metadata is `clef` is treated as a Clef model. Selecting one uses the model's decision head instead of the approximation above, and answers every question about one `state` in one forward pass: the `state` and the questions are laid out in Clef's input format, and the score the decision head gives each option is turned into probabilities with a softmax per question. No text is generated and nothing is sent over the network. Answers and probabilities differ from Jev's.

-Scripts are the same for both. See [Installation](#installation) for the setup of each backend.
+Scripts are the same for all of them. See [Installation](#installation) for the setup of each backend.

 Extra inputs:
 - `model`: `TypeSafe API`, or a local GGUF model (`mmproj-*` files are hidden).
@@ -132,9 +134,9 @@ Extra inputs:
 Functions (`state` is a string, dict, or list; text only):
 - `jev.yes(state, question[, threshold])` → `bool` (yes-probability ≥ `threshold`, default `0.5`)
 - `jev.noul(state, question)` → yes-probability (`0.0`–`1.0`). Compare it with a threshold; using it directly as a condition raises an error.
- `jev.choice(state, question, options)` → the most likely option (`str`). `options` is a list of labels, or a dict of labels to descriptions (2–16 options for local models).
+- `jev.choice(state, question, options)` → the most likely option (`str`). `options` is a list of labels, or a dict of labels to descriptions (2–16 options for general local models).
 - `jev.probabilities(state, question, options)` → `dict` of each option to its probability (sums to `1.0`). Same `options` as `jev.choice`; asking both with the same arguments asks the model once.
- `jev.score(state, question, levels)` → expected level (`float`, `0` to `len(levels) - 1`) for ordered level descriptions (2–16 levels for local models)
+- `jev.score(state, question, levels)` → expected level (`float`, `0` to `len(levels) - 1`) for ordered level descriptions (2–16 levels for general local models)

 ```python
 # it1: a prompt text
@@ -193,8 +195,9 @@ client.system_one(state=it1, questions={"q0": Noul(instructions="q1"), "q1": Nou

 Notes:
 - The TypeSafe API sends `state` and questions over the internet. Do not use it with text you cannot share externally.
- A local question takes one forward pass (about 1–1.5 s with a 4B–9B model on GPU). The model is loaded on the first question of each run (several seconds) and unloaded when the run ends to free VRAM for the rest of the workflow.
+- A general local model takes one forward pass per question (about 1–1.5 s with a 4B–9B model on GPU). A Clef model takes one forward pass per request, for all of its questions (about 3 s for a 300-token request with Clef-Flash Q8_0 on an Intel Arc integrated GPU). The model is loaded on the first question of each run (several seconds) and unloaded when the run ends to free VRAM for the rest of the workflow.
 - Local probabilities are uncalibrated and depend on the model; test thresholds on your own inputs.
+- A local prompt is limited to 8,192 tokens: the `state` and one question for a general model, or the `state` and all questions of a request for Clef. Clef is text only.
 - Each run prints `[ComfyUI-ScriptFlow] Jev requests: N, states: S, questions: Q, responses: M` to the console: requests sent, distinct states, questions asked, and requests answered. Fewer responses than requests means a request failed. Questions answered from the run's cache are not counted.
 - When `typesafe-sdk` is installed, the `httpx2` (the SDK's HTTP client) and `typesafe_sdk` loggers are set to WARNING, so per-request INFO lines are not shown.
 - `MultiOutputScript` never loads a model or makes network requests; `jev` is not available there.
@@ -617,6 +620,7 @@ Notes:

 - Requires v1.3.2 or later, where questions about the same `state` share one request. The script makes 2 requests, so set `max_jev_calls` to 2 or more.
 - `p` is Jev's probability that the output breaks the rule. It is a judgment, not a check: in testing it flagged some rules that were followed and missed some that were broken, and values near `THRESHOLD` changed between runs. Treat the flagged rules as candidates to review.
+- The recipe was developed with Jev through the TypeSafe API. In testing, a local Clef-Flash model flagged most rules, including rules the output followed, so it is not recommended for this recipe.
 - A rule that needs something the script does not have, such as a reference image, cannot be judged. Connect the user request to `in_text_3` for rules that refer to it.
 - `in_text_2` takes the system prompt as plain text, or the text of a JSON config with a `"system_prompt"` key. `\uXXXX` escapes in the JSON are not decoded.
 - Lines starting with `#`, `【`, or `[...]` are headings. Under a heading, each line at the left margin is one rule, and indented lines belong to the rule above. Check `out_text_3` to see how your system prompt was split.
@@ -775,9 +779,6 @@ You should have received a copy of the GNU General Public License along with thi

 See [CHANGELOG.md](CHANGELOG.md) for detailed version history.

-### Current Version: 1.3.2
- `MultiOutputScript (Jev)` batches questions without script changes: questions about the same `state` are sent in one request, and requests for different states are sent in parallel
- `max_jev_calls` now limits requests instead of questions
- Added a console summary of Jev requests, states, questions, and responses after each run
- Hid the per-request INFO log lines of the TypeSafe SDK and its HTTP client
- `datetime.datetime.now()` and `datetime.date.today()` return the time the run started
+### Current Version: 1.3.3
+- `MultiOutputScript (Jev)` runs local Clef GGUF models (Cloudflare's open-weight decision model) with the model's decision head, answering every question about one `state` in one forward pass
+- Added an application recipe that checks a prompt enhancer's output against its system prompt, with a second script for long system prompts
@@ -1,7 +1,7 @@
 [project]
 name = "ComfyUI-ScriptFlow"
 description = "Safe Python-like script node with a System One decision model: ask yes/no, choice, and score questions via TypeSafe AI's Jev API, with local GGUF LLMs as a fallback. Multiple inputs and outputs let one node handle math, logic, text editing, conditional routing, resolution selection, filename generation, and more."
-version = "1.3.2"
+version = "1.3.3"
 license = {file = "LICENSE"} 
 # classifiers = [
 #     # For OS-independent nodes (works on all operating systems)