Merge v0.7.2: recipe hints (model-name guidance in hints), GUI Samples menu

レシピの案内（hints:）と、GUI の［サンプル］メニューを追加。 既存の使い方は変わりません（変換の結果も同じで、新しい表示とボタンの追加・位置調整のみ）。

追加

• レシピの hints:：レシピの説明のファイル（.recipe.yaml）に、変換のあとに添える案内を書けるようになりました。案内は、変換結果が目標スキーマに合わないとき、または特定の項目を落としたときに、報告の最後へ hint:（--report では Hint:）として出ます。標準エラー出力に出るだけで、変換結果は変わりません
  • text（必須）：案内の文。{recipe}（レシピの名前）{input}（入力の名前）{path}（該当する項目のパス）が使えます
  • when（省略可）：いつ出すか。issue（missing extra type value range size）と path（.messages[].role のような形）で目標スキーマの食い違いに、dropped（drops に書いたパス）で落とした項目に結びつけます
  • 自作のレシピにも同じように書けます（案内は Python のコードには埋め込んでいません）。書き間違い（知らないキー・text がない・種類や path の形の違い・dropped と issue/path の併用）はエラーです
• 同梱の 6 レシピすべてに、model の案内を書きました：モデル名は API ごとに違うので、レシピはこれまでどおりモデル名を選びません。そのかわり、次のことを案内します
  • 変換先が OpenAI・Anthropic のもの（4 レシピ）：model が結果になければ、足し方を示します。例：yaqpy --recipe gemini-to-openai request.json | yaqpy '.model = "gpt-4o"'（入力のファイル名と、変換先に合うモデル名の例が入ります。Anthropic は claude-opus-5-5）
  • 変換先が Gemini のもの（2 レシピ）：入力の model を落としたときに、「Gemini はモデルを本文ではなく URL で指定する」ことを https://generativelanguage.googleapis.com/v1beta/models/<model>:generateContent の形で示します
• GUI の［サンプル］ボタン：ファイル名の右のボタンを押すと、examples/ のデータ（各形式のサンプルと、OpenAI・Gemini・Anthropic のリクエストボディ）の一覧がプルダウンで開き、選ぶと入力になります。[＋ファイルを追加] と同じ規則（何も開いていなければ最初の文書に、開いていれば追加）で、入力形式は auto になります。デスクトップ版・Web 版のどちらでも使えます。データは wheel に同梱しています（src/yaqpy/gui/assets/examples/。選べるのは一覧にある名前だけで、パスは受け付けません）

変更

• 式欄のボタンの並びを、意図で左右に分けました：貼り付け・式ファイル（.yaqpy）の読み込みを欄の左に、コピー・クリア・式ファイルへの保存を欄の右に置きます（左は式を用意する操作、右はいまの式を扱う操作。読み込みはこれまで右にありました）。ボタンの機能・ショートカットは変わりません
• README・USAGE-GUI.ja.md の GUI のスクリーンショットを、この並びに更新した画面のものに差し替えました

文書

• USAGE.ja.md のレシピの節を、examples/ の新しいサンプル（api-openai-request.json など）で実際に実行し直して書き換えました（旧 openai-request.json は無くなっています）。報告の読み方に hint: を、レシピの作り方に「案内を付ける：hints」を加えました
• USAGE-GUI.ja.md に［サンプル］を、README（英語・日本語）・DEVELOPMENT.md にも追記しました。DEVELOPMENT.md の docs/ の説明と、テスト件数を直しました。--print-spec の説明にも hints を加えました
• USAGE-GUI.ja.md の「2. 画面の見取り図」と 8-4 節を、式欄のボタンの新しい並びに合わせて書き直しました
• 紹介スライド（16 枚目）のレシピの実行結果を、新しいサンプルの出力に合わせました
• docs/ の設計書・計画書は、リポジトリから外れました。docs/flet-1.0-api-notes.md に、その旨を書きました

ライブラリ・開発者向けの変更

• recipes/hints.py（案内の選択）と Recipe.hints / HintRule（recipes/model.py）を追加し、recipes/loader.py が hints: を読みます。gui/samples.py（［サンプル］の一覧と読み込み。Flet 非依存）と presenter.open_sample も追加しました
• テスト：tests/unit/test_recipes_hints.py（案内の書式・条件・自作レシピ）、tests/unit/test_gui_samples.py（assets/examples/ が examples/ と同じ内容であること、サンプルの開き方、名前の検査、メニュー）を追加しました。examples/ を直したら、コピーも直します（DEVELOPMENT.md）
• tests/acceptance/test_examples.py：openai-request.json の改名で落ちていたテストを直し、3 つのサンプルを他の 2 社へ変換する 6 通りのテストを足しました
• tests/unit/test_gui_main_page_tools.py・test_gui_expression_file.py：式欄のボタンが左右どちらのグループにあるかを検査するよう更新しました
• 公開する API（yaqpy.evaluate など）に変更はありません

確認したこと

• 全テスト：ユニット 1,786 件・受け入れ 109 件など、合計 1,900 件が合格（Python 3.13）
• 3 つの版（3.11・3.12・3.13）：tools/check_pythons.py で、下限の検査（vermin）と全テストが、いずれも合格しました
• GUI は、Web 版を起動してブラウザで［サンプル］を開き、選んだサンプルが左に出て、右に変換結果が出るところまで確認しました。式欄のボタンの並びも、同じくブラウザで確認しました
• 未確認：Python 3.14 以降

v0.7.1: Python 3.11+ support, install block in README, multi-version check

Python 3.11 と 3.12 でも使えるようになった版です。 必要な Python が「3.13 以上」から「3.11 以上」になりました（3.11・3.12・3.13 で動作確認）。機能の追加・変更はありません。PyPI のページの先頭に、インストールのコマンド（pip install yaqpy と pip install "yaqpy[gui]"）も載せました。

変更

• requires-python を >=3.13 から >=3.11 に下げました。 3.12 以降でしか書けない type X = ... 文が 3 か所（core/engine/helpers.py、core/lang/ast.py、core/lang/lex_rules.py）にあったので、X: TypeAlias = ... に書き換えました（動作は同じ）。PyPI の分類（classifiers）に 3.11・3.12 を追加し、ruff の対象版を py311 にしました
• README（英語・日本語）の先頭に、pip install yaqpy と pip install "yaqpy[gui]" を並べた 1 つのコードブロックを置きました。PyPI のページの pip install の枠は PyPI が自動で作る固定表示で変えられないため、その下の説明（README）に載せています。バッジも「Python 3.11+」にしました

ライブラリ・開発者向けの変更

• 3 つの版でのテスト：tools/check_pythons.py を追加（下限の検査 vermin ＋ 3.11・3.12・3.13 で全テスト。版ごとに別の環境を作るので、開発用の .venv は変わりません）。使い方と、3.12 以降の機能を使わない決まりは DEVELOPMENT.md の「対応する Python の版」
• examples/ の実変換のテスト：tests/acceptance/test_examples.py を追加（YAML・JSON・CSV・XML・properties・TOML の読み取り・変換・更新、--schema、--recipe。CLI 受け入れテスト 87 → 103）
• uv.lock を作り直しました（対応する版が広がったため）。.gitignore に .venv-*/ を追加

確認したこと

• Python 3.11.15・3.12.13・3.13.12 のそれぞれで、全テストが通ります（1,817 件合格・62 件スキップ。スキップは、Go 版に由来する既知の非互換と、[web] の extra が要るテスト）
• Web 版（[web] の extra）のテストは、3.11 で走らせて通りました（3.12・3.13 の通常の実行では、extra が無いので skip）
• 未確認：Python 3.14 以降

v0.7.0: GUI improvements (Ask AI, .yaqpy, run log, web drop)

GUI を使いやすくする版です。 AI に式を書かせる文面を組み立てる「AIに相談」タブ、式のファイル（.yaqpy）の保存・読み込み、成功した変換を記録して見返し・再実行できるログ画面（デスクトップ版のみ）、Web 版でのファイルのドラッグ＆ドロップが入りました。出力形式の既定は YAML になり、整形（-P）のスイッチは画面から外れました。使い方は USAGE-GUI.ja.md（新しい 8-4 節・16 章）にあります。

新しくできること

分類	機能
「AIに相談」タブ	左に「あなたの入力（データ例・やりたい変換）」、右に「AIへの相談文」（yaqpy --guide-prompt と同じ内容が土台）。[＋プロンプトに反映] を押したときだけ、相談文の「## 依頼」の案内の一文を左の入力で置き換える（2 回目以降は末尾に追記）。[貼り付け] [クリア] [初期状態に戻す] [コピー]。クリップボードが許可されないときは案内が出る。式バーの [🤖] のダイアログは、このタブに置き換わった
式のファイル .yaqpy	式欄の右の 2 つのアイコンで、式だけを .yaqpy（UTF-8・LF・式のテキストそのもの）に保存し、.yaqpy / .yq を読み込める（Web 版はダウンロード／アップロード）。読み込んだ式に誤りがあっても読み込み、式欄の赤枠で知らせる。実行はしない。文書を開く前に読み込んだ式は、その後で文書を開いても残る
コマンドでも .yaqpy	yaqpy sample.yaqpy data.json（先頭の引数が実在する .yaqpy / .yq）や --from-file sample.yaqpy で、そのまま式として読む。.yq の挙動は変わらない。存在しない .yaqpy は、これまでどおり式または入力として扱う。同梱のレシピ（--recipe）の式ファイルと同じ拡張子
実行ログ（デスクトップ版）	[実行]（式欄の Enter を含む）で変換に成功したときだけ、1 回につき 1 ファイルを記録する。形式・インデント・設定の変更やプロパティ選択による自動の再実行、失敗した実行、直前と同じ内容の実行、ログ画面からの再実行は記録しない。保存先は OS ごとの既定（Windows は %LOCALAPPDATA%\yaqpy\logs）で、設定で変えられる。YAML の複数文書（--- 区切り）で、概要・式・オリジナル（入力）・結果（出力）の 4 つ（入力と結果は YAML に変換して記録。式は 1 行の "…"）。書く前に読み戻して確かめ、元の形式に戻せない項目は原文（text:）も併記する。件数の上限（既定 500）と 1 件の本文の上限（既定 1 MiB）がある
ログ画面（デスクトップ版）	4 つ目のタブ [ログ]。ファイル名から作った一覧（新しい順）、日時・形式・式・入力ファイル名での絞り込み、選んだログの入力・式・全文、[再実行]（記録した入力を元の形式へ戻して新しい文書として追加し、式・入力形式・出力形式・インデントを戻してすぐ実行。eval_all で記録したものだけは、確認のうえで開いている文書を置き換える）、[式を .yaqpy に保存]、削除（1 件・すべて）、保存先を開く
設定：実行ログ（デスクトップ版）	記録のオン／オフ（既定オン）、保存先（直接入力か [参照…]。空なら既定）、保存する件数の上限、1 件あたりの本文の上限。ログには入力と結果が平文で残る旨の注意書き
Web 版：ファイルのドロップ	ページのどこにでもファイルをドロップして開ける。Flet 1.0 にはドロップの部品が無いので、配る index.html にスクリプトを足し、ドロップをルートの変更として Python 側へ知らせ、既存のアップロード（サイズの事前確認・上限）に合流させる（実測は docs/flet-1.0-api-notes.md の 8 章）
[+ パイプを追加]	プロパティの選択とは独立に、式の末尾へ `
式バーの貼り付け・コピー・クリア	式欄の右の 3 つのアイコン。貼り付けは式の全体を置き換え、検証もし直す
未読込の画面のボタン	[ファイルを開く] と [貼り付け]（クリップボードの内容を 1 つの文書として開く）。枠全体のクリックも従来どおり
ファイルのチップの折りたたみ	チップは先頭の 2 件だけ。3 件目以降は [＋ファイル N件] のメニューにまとまり、選択・1 件だけ閉じる、ができる。並びは開いた順のままで、隠れた文書を選んでもチップ側へは繰り上げない（ボタンの色とメニューのチェックで示す）
設定画面の説明	env / strenv と load / loadstr を別々に許可する理由と、load は未実装なので切り替えても動作に影響しない旨を追記（検査つき）

変更（挙動が変わるもの）

• GUI の出力形式の既定が yaml になりました（以前は auto ＝入力と同じ）。JSON・XML などを開いても、最初から YAML で表示されます。出力形式のプルダウンの auto は「auto（入力と同じ）」と表示され、選べば入力と同じ形式で出せます。GUI の表示の既定だけの変更で、コマンド・ライブラリ（共有の YqService の「出力 auto は入力と同じ」の規則）は変えていません。入力形式の auto（中身から判定）も同じ意味のままです
• 整形（-P）のスイッチを画面から外しました。 1 行の書き方を 1 項目 1 行にしたいときは、式 .. style="" を使うか、コマンドの -P を使ってください
• 「式に追加」は「+ パイプを追加」になり、役割が変わりました。 以前は選んでいたプロパティを | でつなげましたが、今は式の末尾に | を足すだけです（プロパティのプルダウンを選ぶと式が置き換わる動作は同じです）
• 式バーの [🤖] とそのダイアログは、「AIに相談」タブに置き換わりました
• 何も開いていない状態から文書を開くとき、式欄の式を「.」に戻さなくなりました（先に .yaqpy を読み込んだ式・打っておいた式が消えないように）。すべて閉じたときと、開いている文書を置き換えるときは、これまでどおり「.」に戻ります
• YAML の書き出しで、リストの要素のブロックスカラー（|）の本文の字下げが、「ダッシュの桁＋インデント」になりました（以前は、さらに 2 桁深かった。既定のインデント 2 では - |- の次の行が a から a になり、Go 版の出力と同じ形です。インデントを 2 以外にしたときは、Go 版はダッシュの桁＋2 のままですが、yaqpy は桁の指定（|4 など）と本文の桁をそろえるため、＋インデントです。読み戻した値は同じです）
• ナビゲーションバーが 3 タブ（メイン・設定・AIに相談）になり、デスクトップ版ではさらに [ログ] が付きます

ライブラリ・開発者向けの変更

• 新しいモジュール（yaqpy.gui）：run_log（実行ログの組み立て・読み戻し・保存先の整理。Flet 非依存）、log_presenter（ログ画面のロジック）、expression_file（.yaqpy の規則）、ask_ai（相談文への反映）、web_assets（Web 版の index.html の組み立て）、pages/ask_ai_page・pages/log_page・pages/clipboard。アーキテクチャ検査に、Flet を import してはいけないモジュールと外部パッケージ（flet_web）の許可を追加
• _run.py のタブは pages / nav_labels から作る形にし、番号は MAIN, SETTINGS, ASK_AI, LOG の定数にしました（LOG はデスクトップ版だけ）
• QueryState.pretty_print を削除（build_options は pretty_print=False 固定）。SettingsState に log_enabled log_dir log_max_files log_max_entry_mib を追加（永続化。危険な許可は従来どおり持ち越さない）
• MainPresenter：last_source（実行した時点の要求と入力）・record_run・apply_rerun・append_pipe・load_expression_file / save_expression_file / expression_download を追加。apply_candidate の append 引数は削除
• WebUploader.pick に dialog_title allow_multiple allowed_extensions を追加（式ファイルの受け取り）。yaqpy.app.selfdoc.GUIDE_PROMPT_PLACEHOLDER を公開（案内の一文を GUI と共有）
• 単体テスト 1,287 → 1,722、CLI 受け入れテスト 86 → 87（.yaqpy を式ファイルとして読む）

修正

• YAML のブロックスカラー（|）が、書いて読み戻すと値が変わる不具合を直しました（v0.3.0 から残っていたもの）。空白（スペース・タブ）だけの行・行頭がタブの行・制御文字を含む文字列と、リストの要素で先頭が改行・空白の複数行の文字列は、"..." で書くようになります（go-yaml も、行末の空白や「空白＋改行」を含む文字列はブロックにしません）。記号と空白・改行の組み合わせ 209,712 通りで確かめ、値が変わるものは 2,981 通りから 0 になりました。互換テストの結果は変わりません
• 実行ログの記録で、同じキーが 2 度出てくる YAML の出力（.items[] の結果を YAML で出したときなど）や、複数のスカラーが並ぶ結果は、YAML に変換すると別の値になるので、原文（text:）で記録するようにしました（書く前の読み戻しで見つかります）

互換性の見える化

互換テストの結果は v0.6.0 から変わりません（演算子 1,091 件のうち 1,047 件一致、形式 154 件のうち 149 件一致。テストの実行で確認）。この版の変更は GUI・式ファイル・YAML のブロックスカラーの書き出しで、演算子・形式の読み書きの規則には触れていません。

既知の制限

• デスクトップ版の窓の実機確認は、この版の開発環境ではできませんでした。 開発中の Windows 環境では、最小の Flet アプリ（文字を 1 つ出すだけ）でも窓の中が真っ白のまま描画されず、画面の撮影ができませんでした。代わりに、同じ画面（メイン・設定・AIに相談・ログ）を Web の経路でブラウザに出し、実際のクリックで確認しました（組み込みブラウザ。式の実行→ログの記録→ログ画面での選択→[再実行]→新しい文書として追加・式と形式の復元→設定画面の実行ログの節）。デスクトップの窓そのもの（OS のフォルダ選択ダイアログ・保存ダイアログ・窓を閉じる操作など）は未確認です。get_directory_path（保存先の [参照…]）も未確認のため、保存先は直接入力もできるようにしてあります
• Web 版のドロップは、ブラウザ内で作った合成のドロップイベントで確かめました。ファイルマネージャーからの実際のドラッグと、Chrome・Edge・Firefox・Safari ごとの違いは未確認です。デスクトップ版のドロップは、これまでどおり対応していません
• 実行ログの既定の保存先のうち、macOS と Linux は実機未確認です（Windows の %LOCALAPPDATA% は環境変数から作る部分をテストで確認）。「保存先を開く」の open / xdg-open も同様です
• 実行ログには入力データと変換結果が平文で残ります（env の値もマスキングできません）。機密情報を扱うときは、設定で記録をオフにしてください
• ログの入力を元の形式へ戻して再実行するとき、整形は yaqpy の出力になります（データの中身は同じ）。本文を省いたログ（上限超え）・未知の版のログ・壊れたログは再実行できません
• load / loadstr は、この版でも未実装です（設定画面にも書きました）

v0.6.0: GUI web version (yaqpy-web/yaqpy --web), logo, English README, PyPI metadata

GUI をブラウザで使える版です。 yaqpy-web（または yaqpy --web）で、デスクトップ版と同じ画面を自分の PC の小さな Web サーバーから配り、ブラウザで開けます。ファイルはブラウザからアップロードし、変換結果はダウンロードで受け取ります。既定ではこの PC からしか開けず（127.0.0.1）、環境変数・ファイルを読む演算子は常に無効で、評価はサーバーのファイル・環境変数に届かない仕組みの上で動きます。入れ方は yaqpy[web]、使い方は USAGE-GUI.ja.md の 15 章にあります。

この版から PyPI でも公開します（pip install yaqpy ／ uv tool install yaqpy）。README は英語版（README.md。PyPI のページにも出ます）と日本語版（README.ja.md）に分かれました。

新しくできること

分類	機能
Web 版の起動	yaqpy-web または yaqpy --web（既定は http://127.0.0.1:8550/、起動したら既定のブラウザを開く）。ポート番号は --port（yaqpy-web --port 9000 ／ yaqpy --web --port 9000）。ほかに --host --lang ja|en（表示言語。すべてのブラウザで共通）--no-browser --no-cdn --max-input-mib（既定 10）--timeout（既定 10 秒）--max-concurrent-runs（既定 2）。止めるのは起動した端末で Ctrl + C
開く（アップロード）	[＋ファイルを追加] でブラウザからアップロード（複数選択も可）。上限を超えるファイルは送る前に断る。サーバー側にも同じ上限（超えたら 413）があり、受け取ったファイルは読んだ直後に消す
保存（ダウンロード）	右上のボタンが [ダウンロード] になり、変換結果の全量をブラウザのダウンロードで受け取る。サーバーのディスクには書かない（上書き保存は Web 版にはない）
安全のための決まり	① 既定はこの PC からのみ（127.0.0.1）。それ以外の --host は認証が無いことの警告を出す ② env / strenv・load / loadstr・system は常に無効で、設定画面に許可のスイッチも出さない。評価は SandboxFileSystem（ファイルはすべて拒否）と空の環境変数の上で動く ③ 入力の大きさ・実行時間・同時実行数の上限（上限を超えた実行は「サーバーが混み合っています」） ④ 式や文書の中身をログに残さない（uvicorn のアクセスログも切る）
複数のブラウザ・タブ	タブごとに別の画面（セッション）になり、開いたファイルや式は混ざらない。設定（タイムアウト・最大入力・表示行数・ダークテーマ）はブラウザ側に保存される
yaqpy-gui ファイル	デスクトップ版も、yaqpy-gui a.yaml でファイルを開いた状態で起動できる（yaqpy --gui a.yaml と同じ）
ヘルプ	yaqpy-gui --help（デスクトップ版）と yaqpy-web --help（Web 版）は、それぞれ自分の使い方とオプションだけを出す。yaqpy --help に --gui と --web の説明を加え、詳しいオプションは各コマンドのヘルプを見るよう案内する（yaqpy --web --help は yaqpy-web --help と同じ内容）
PyPI	pip install yaqpy（"yaqpy[gui]" "yaqpy[web]"）、uv tool install yaqpy、uvx yaqpy、uv add yaqpy で入れられる。GitHub のリリースからの入れ方も引き続き使える
ロゴ	デスクトップ版の窓のアイコン（Windows）と、Web 版のブラウザのタブのアイコン・読み込み中の画面が、Flet のロゴから yaqpy のロゴ（リポジトリの assets/images/）に変わった

• Web 版のために、[web] extra（flet[web]：flet と flet-web。flet-web が FastAPI・uvicorn を連れてくる）を追加しました。本体（pip install yaqpy）の依存は増えません。デスクトップ版だけなら今までどおり [gui] で足ります
• Web 版の設定画面には、サーバーの上限（最大入力・タイムアウト）が表示されます。ブラウザに保存された値が上限より大きければ、上限まで下げて表示します（効くのは常に小さい方）
• 画面の描画部品と日本語のフォントは、既定では CDN（インターネット）から読み込みます（Flet の既定）。--no-cdn で CDN を使わずに動かせますが、日本語の文字が「□」になります（実機で確認。--lang en と使ってください）

変更（挙動が変わるもの）

• yaqpy-gui が引数を解釈するようになりました。 以前は何を渡しても無視して窓を開いていました。今は、ファイル名を 1 つだけ受け付け、知らないオプション・存在しないファイルはエラー（終了コード 1）になります。yaqpy --gui の挙動は変わりません
• yaqpy の引数に --web があると、ほかの引数はすべて yaqpy-web のオプションとして扱います（yaqpy --web --port 9000）。式・ファイル・yaqpy 自身のオプションとは一緒に使えません。--gui と --web を同時に付けるとエラーです
• yaqpy --help のオプションの一覧で、--gui が「misc」から新しい「GUI」の区分に移りました
• README.md が英語版になりました。 これまでの日本語の README は README.ja.md です（git log --follow で履歴をたどれます）。USAGE・USAGE-GUI・DEVELOPMENT・CHANGELOG は日本語のままで、各文書の先頭のリンクと「README のインストール」へのリンクは README.ja.md を指します
• インストールの案内（README・USAGE-GUI、GUI／Web 版の部品が無いときの案内）は、PyPI から入れる手順が先になりました（GitHub のリリースから入れる方法は README に残しています）
• クリップボードへのコピーが失敗したとき（ブラウザや OS が許可しないとき）、画面が例外で止まらず「コピーできませんでした。欄の文字を選択してコピーしてください」と案内するようになりました（デスクトップ版も同じ）

ライブラリ・開発者向けの変更

• pyproject.toml の yaqpy-gui の行き先を yaqpy.gui.app:main_entry から yaqpy.gui.app:cli_entry に変え（引数の解釈のため）、**yaqpy-web（yaqpy.gui.app:web_cli_entry）**を加えました。main_entry は今までどおり残り、yaqpy --gui から呼ばれます。yaqpy --web は web_cli_entry を prog="yaqpy --web" で呼びます
• pyproject.toml に、PyPI のページ用の情報を足しました：説明文（正式名称「YAML and more—Query editor in Python」を含む）、authors、keywords、classifiers、[project.urls]。uv build と twine check が通り、LICENSE と NOTICE が wheel に入ることを確かめています
• ロゴ：gui/logo.py（置き場所の定義。Flet 非依存）と gui/assets/（yaqpy-logo.ico、Web 用の web/favicon.png と web/icons/loading-animation.png）。原本はリポジトリの assets/images/ で、wheel に入れるためにコピーしています（内容が同じことを tests/unit/test_gui_logo.py が確かめます。原本を差し替えたらコピーも差し替えてください）
• 新しいモジュール：gui/web_config.py（Web 版の設定・上限・同時実行の関門。Flet 非依存）、gui/_web.py（flet.fastapi.app を uvicorn で起動する。uvicorn を import してよいのはここだけとアーキテクチャ検査に追加）、gui/_upload.py（Web 版のアップロード受け取り）
• ft.run(view=WEB_BROWSER) は使っていません。 Flet 1.0 の ft.run は host を省くと全インターフェース（0.0.0.0 と ::）で待ち受け、アップロードに要る設定（upload_endpoint_path・secret_key）も渡せないためです（docs/flet-1.0-api-notes.md 7 章。W0 の実測）
• GuiState.web（WebLimits）、clamp_settings_to_web_limits、build_options の Web 版での強制無効、MainPresenter の open_upload / add_upload / check_upload_size / prepare_download と run_gate、intake.from_bytes / ensure_size、_di.make_web_service を追加しました
• 単体テスト 1,168 → 1,287（Web 版のサーバーを実際に起動して、127.0.0.1 だけで待ち受けること・署名の無いアップロードを断ることを確かめるテストを含む。[web] extra が無い環境では飛ばします）。CLI 受け入れテスト 84 → 86（yaqpy --help の --web、yaqpy --web の引数の受け渡し）

修正

• コピー（変換結果・AI への相談文）で、クリップボードへの書き込みが拒否されると、ボタンの処理が例外で終わっていたのを修正（上の「変更」を参照）。Web 版の調査（W0）で見つかりました

互換性の見える化

互換テストの結果は v0.5.0 から変わりません（この版は GUI の配り方の追加で、演算子・形式には触れていません）。

既知の制限

• ブラウザでの動作は、Claude Code デスクトップアプリの組み込みブラウザ（Windows）でだけ確認しました。 一般のブラウザ（Chrome・Edge・Firefox）と macOS / Linux では未確認です。また、組み込みブラウザは OS のファイル選択ダイアログを出さないため、アップロードはページ内でファイルの選択を模した操作で確かめました（ブラウザ → サーバーの受け渡しは本物の経路）。Ctrl + C での停止と一時フォルダの削除は、単体テスト（偽のサーバー）で確かめています
• ブラウザにアプリとして追加（PWA）したときのアイコン（192・512 px）は Flet のままです（ロゴの原本が 200 px の PNG だけのため）。窓のアイコンの変更は Flet 1.0 の仕様で Windows だけに効きます
• 認証はありません。 ほかの PC に公開するなら、認証つきのリバースプロキシの後ろに置いてください。Dockerfile は用意していません（自分の PC で使う前提）
• http:// のまま別の PC から開くと、ブラウザの決まりでクリップボードへのコピーが使えないことがあります
• 表示言語はサーバーごとに 1 つ（--lang）です。エラーの詳しい内容は、これまでどおり日本語のままです
• 貼り付け・原文の追加編集は WebSocket で届くため、上限（--max-input-mib）より少し大きい 1 通まで受け付けるよう uvicorn の ws_max_size を設定しています。それを超える貼り付けは接続が切れ、ページの再読み込みが要ります
• タブごとのアップロード用のフォルダ（中身は読んだ直後に消えて空）は、セッションが破棄されるとき（Flet の既定で、タブを閉じてから約 1 時間後）に消えます。強制終了したサーバーの一時フォルダ（yaqpy-web-*）は残ります

v0.5.0: GUI limits removed (settings persist, decode cancel, overwrite+backup, multi-file, English UI, usability fixes)

GUI の制限を減らす版です。 設定（タイムアウト・最大入力・表示行数の上限・ダークテーマ・表示言語）が次回の起動でも引き継がれるようになりました。巨大なファイルの読み込み中でも中止・タイムアウトが効くようになりました（今までは書き出し中だけでした）。保存は今までどおり別名保存が既定ですが、開いているファイルへの上書きも確認のうえでできるようになり、上書きの直前には自動でバックアップを作ります。yaqpy --gui a.yaml で、起動時にファイルを指定して開けます。複数のファイルを同時に開いて、チップで切り替えられます。読み込んだあとの原文もそのまま編集できるようになりました。式が難しいときは、AI への相談文をワンクリックで出せます。インデントは ± ボタンでも操作でき、アプリの終了ボタンも付きました。設定画面から英語 UIにも切り替えられます。使い方は USAGE-GUI.ja.md にあります。

新しくできること

分類	機能
設定の保存	タイムアウト・最大入力（MiB）・表示行数の上限・ダークテーマ・表示言語は、次回の起動でも引き継がれる。env / load の許可だけは、危険な許可を持ち越さないため毎回既定（不許可）に戻る
デコード中の中止	YAML・JSON・XML・CSV/TSV・TOML・properties・TOON のすべてで、読み込み（デコード）の途中でも中止・タイムアウトが効くようになった（各デコーダの主要な走査ループに StepBudget を渡すコア改修。設計書のリスク R4 の解消）
上書き保存	開いているファイルと同じ場所・同じ名前への保存は、確認のうえで上書きできる。上書きの直前に、元の内容を {path}.bak へ自動でバックアップする（バックアップが作れなければ上書きしない）。この確認は、開いているどのファイルと同じパスでも働く（アクティブでない方でも）
起動時にファイルを指定	yaqpy --gui a.yaml のように、実在するファイルを 1 つだけ続けて渡すと、そのファイルを開いた状態で起動する。式や存在しないパス、2 つ以上のファイルは今までどおり「一緒には使えません」と断る
複数ファイル	[＋ファイルを追加]（旧「ファイルを開く」と統合。最初から押せる）で、開いているものを閉じずにもう 1 件（複数選択も可）を追加できる。チップで文書を切り替えると、いまの式がそのままその文書に対して実行される。× で個別に閉じられる
原文の追加編集	読み込んだあとも左の窓（オリジナル）を書き換えられる。打ち終わって 0.5 秒で自動的に取り込んで再実行し、見出しに赤字で「追加編集」と出る。開いたファイルそのもの（ディスク上）は変わらない：上書き保存はその時点のディスク上の内容をバックアップしてから書く
AI への相談文	式欄の [🤖] で、CLI の --guide-prompt と同じ内容をダイアログに出す。末尾の「## 依頼」を書き換えてから [プロンプトをコピー] でコピーできる（MD Slide Studio の「AI プロンプト」を参考にした UI）
インデントの ± 操作	数字欄への直接入力に加えて、両脇の －/＋ ボタンで 1 ずつ増減できる
終了ボタン	メイン／設定の切り替えバーに [⏻] を追加。押すと「アプリを閉じますか？」の確認が出て、既定は「やめる」。[閉じる] を選ぶと窓の × と同じ手順（評価を止めてから終了）で終了する
英語 UI	[設定]画面の「表示言語」で日本語／英語を切り替えられる（次回の起動から反映）。対象は画面の文言（ボタン・ラベル・案内・エラーの見出し）で、エラーの詳しい内容（式の構文エラーの位置、YAML エラーの行・列など）は今のところ日本語のまま

• 上書き保存は、開いているどれかのファイルと同じパスを指したときだけ確認ダイアログが出る。既定のボタンは「やめる」で、Enter では上書きされない
• 複数の文書を CLI の eval-all と同じように1 回の評価にまとめる機能は、開発中に画面のトグルとして一度実装しましたが、入力形式が異なる文書を混ぜると変換に失敗するなどユースケースを詰め切れていないため、このリリースでは画面から外しました（MainPresenter 側のロジックとテストは残っており、fi / filename でのまとめ評価は API としては動きます。GUI での提供方法は今後の課題）。コマンドの yaqpy eval-all はこれまでどおり使えます
• macOS / Linux 向けに、窓を閉じたときの後始末（評価の中止 → 終了）を Windows 専用の仕組みから、Flet の共通 API（page.window.on_event）を使う形に改めた。ただし実機（macOS / Linux）ではまだ確認できていない
• 未読込の画面（案内・貼り付け欄）と窓の既定の大きさを見直し、標準的な解像度では窓のサイズを変えなくても全部の部品が収まるようにした
• [＋ファイルを追加] はファイル名の右に配置。インデントの数字欄は「インデント」のラベルが折り返さない幅に広げた

変更（挙動が変わるもの）

• --gui に、実在するファイルを 1 つだけ渡せるようになった（以前はどんな引数を渡しても「一緒には使えません」と拒否していた）
• 「ファイルを開く」と「＋ファイルを追加」が 1 つのボタンに統合された。 見た目や配置に依存したスクリプト・スクリーンショットは影響を受けうる
• 左の窓（オリジナル）が読み取り専用ではなくなった。 「原文は絶対に書き換わりません」という以前の説明は「開いたファイルそのもの（ディスク上）は書き換わりません」に改めた（画面上の入力は編集できる）
• 保存の上書き確認ダイアログの文言が、自動バックアップに触れる内容に変わった
• 中止した直後の状態バーの文言から「読み込み」の言及を外した（読み込み中も中止が効くようになったため）
• 窓の既定の大きさが 1180×820 から 1180×880 に、最小の高さが 560 から 620 に変わった

既知の制限

• macOS / Linux の実機での動作は未確認（コードは移植性に配慮したが、このリリース作業ではWindows でしか確認できていない）
• AI への相談文のダイアログでの「コピーしました」表示や、[⏻] での終了は、実機（デスクトップ版）での目視確認ができていない（クリップボード操作・実際の窓の終了は自動テストの対象外）
• 英語 UI は画面の文言だけが対象。例外の詳しい内容（gui/errors_ja.py）は日本語のまま（将来の課題）

v0.4.0: recipes, self-description, pytest migration, content-based format detection

スキーマ変換の支援と、コマンド自身による説明の版です。 OpenAI・Gemini・Anthropic の**リクエストボディを相互に変換する「レシピ」**と、その結果を確かめる仕組み（落とした項目の報告・変換先スキーマとの照合・ドライラン）を加えました。あわせて、--print-spec --example --guide-prompt --skill-md で、yaqpy が自分の使い方（AI に式を書かせるお願い文、Claude Code のスキル）を出力できるようになりました。本体は引き続き Python の標準ライブラリだけで動きます。使い方は USAGE.ja.md にあります。

新しくできること

分類	機能
変換レシピ	--recipe 名前 で、同梱の 6 つ（openai-to-gemini gemini-to-openai openai-to-anthropic anthropic-to-openai gemini-to-anthropic anthropic-to-gemini）か、自作のレシピ（--recipe ./my.yaqpy）を使う。--list-recipes --recipe-test
確かめる仕組み	結果は標準出力へ、**落とした項目（dropped）・レシピが知らない項目（NOT HANDLED）・補った項目（added）・変換先スキーマに合わない箇所（target schema）**は標準エラー出力へ。--report で詳細（変更のパス単位の差分つき）。既定ではファイルを書かず、--apply --out-dir DIR のときだけ書く（元のファイルは書き換えない）。複数ファイルは表で報告
整える	prune_null prune_empty（演算子と --prune-null --prune-empty）：変換で残った null や空の入れ物を取り除く
入力形式の自動判定	-p auto（既定）で、拡張子で決まらないとき（標準入力、拡張子なし・未知の拡張子のファイル、GUI の貼り付け・見覚えのない拡張子のファイル）は、中身を見て json xml toml props csv tsv を見分ける。見分けられなければ、これまでどおり yaml。拡張子が分かるときの挙動は変わりません。ライブラリでは yaqpy.detect_format(text)
自己説明	--print-spec（式の記法・使える／使えない演算子の一覧・形式・レシピ・やってはいけない書き方）、--example（別名 --sample。実行済みの例）、--guide-prompt（別名 --prompts。AI へのお願い文）、--skill-md（Claude Code のスキル）
ライブラリ	yaqpy.apply_recipe(名前 or Recipe, text)、yaqpy.list_recipes()、yaqpy.build_recipe(...)、yaqpy.detect_format(text)、RecipeError

• **レシピは式のファイル（.yaqpy）＋説明のファイル（.recipe.yaml）**です。説明には、運ぶ項目（carries）・落とす項目と理由（drops）・補う項目（adds）・目標スキーマ（target_schema）・テストケース（tests）を書けます。書き間違いのキーはエラーにします
• 変換するのは、テキストのメッセージ・system の指示・サンプリング設定（temperature top_p top_k 最大トークン数 stop n seed ペナルティ）・関数ツール・tool_choice・JSON 出力の指定（OpenAI ⇄ Gemini）です。変換しないもの（model・画像などテキスト以外・ツール呼び出しの履歴・変換先にない設定）は、落として報告します
• model はすべての変換で落とします（モデル名はベンダーをまたいで通用しません）。変換先で必須なら、目標スキーマとの照合が「不足」と知らせます
• 補うものは 3 つだけです：Anthropic の max_tokens（必須のため、入力になければ 4096。レシピの既定値であって入力の値ではありません）と、Gemini → OpenAI の response_format.json_schema.name（response）は報告します。parameters のない関数の空の input_schema は、「引数なし」と同じ意味なので報告しません
• 目標スキーマは各社の公式の定義から書いています（OpenAI の OpenAPI 定義、Gemini の Discovery ドキュメント、Anthropic のドキュメントと SDK）。参照元は各スキーマファイルの $comment にあります。実際の API は呼びません
• レシピは、ファイル・環境変数・外部コマンドに触れません（同梱のものも、自作のものも。--security-* に関係なく常に無効）。説明ファイルの target_schema expression_file が指せるのも、レシピと同じフォルダのファイルだけです
• 実行例と出力は、実際に実行して確かめたものです。変換の往復（例：OpenAI → Gemini → OpenAI）で、会話・ツール・サンプリング設定が元に戻ることをテストで確かめています
• **自動判定は、読むのは先頭のごく一部（コメントを除いた最初の 10 行程度）**で、判定できなければ yaml にします（エラーにしません）。JSON だけは全体を厳密に解析して確かめます（大きすぎるときは形だけで判定）。判定の内容が読み込む内容そのものなので、同じ入力を 2 回読むことはありません（標準入力は 1 回しか読めないため重要）

変更（挙動が変わるもの）

• ascii_upcase と ascii_downcase が使えるようになりました（後述の「修正」）
• --help の末尾に、schema・レシピ・自己説明の使用例を加えました
• **-p auto（既定）が、拡張子で決まらないとき（標準入力、拡張子なし・未知の拡張子のファイル）に中身を見るようになりました。**拡張子が分かるときは、これまでどおり拡張子だけで決まります（振る舞いは変わりません）。判定できない中身は、これまでどおり yaml として読みます
• 新しい引数（--recipe など）は、追加だけです。既存の式・フラグの挙動は変わりません

ライブラリ・開発者向けの変更

• 新しい層 yaqpy.recipes（データと、プレーンな Python の値への検査。app cli gui api を import しない。アーキテクチャ検査に追加）。レシピの実行は yaqpy.app.recipe_service.RecipeService（SecurityPolicy.strict() で固定）
• FormatRegistry.guess_from_filename(name) を追加（拡張子から形式を求め、なければ None。from_filename はこれを使い、なければ YAML）
• FormatRegistry.guess(filename, text) を追加（拡張子 → 中身 → yaml の順で決める、yaqpy 独自）。新しいモジュール yaqpy.formats.sniff（detect_format(text) -> str | None）が中身だけを見る側
• YqService._resolve_formats が、内容判定で読んだテキストを EvaluateRequest に差し戻すようになりました（同じ入力を 2 回読まないため）。戻り値は 3 要素から 4 要素のタプルに変わりました（内部専用のメソッドです）
• EvalEnv などの既存の型は変えていません。FileSystemPort も変えていません
• 同梱データ：yaqpy/recipes/builtin/（*.yaqpy *.recipe.yaml *.schema.json）は wheel に含まれます
• テストを unittest から pytest（＋ pytest-cov・pytest-xdist・pytest-timeout。dev 依存に追加）へ移行しました。テストクラスは unittest.TestCase の継承を外し、subTest は pytest.mark.parametrize に、assertXxx は assert に書き換えています。カバレッジは計測のみ（下限は設けていません）
• 単体テスト 749 → 1,064、CLI 受け入れテスト 63 → 83（stdout/stderr の分離、パイプでの連鎖、--apply が入力に触れないこと、SKILL.md を置いて例を実行すること、自動判定が拡張子より優先されないことを含む）

修正

• ascii_upcase と ascii_downcase が、変数束縛の as の先頭 2 文字として読まれていたのを修正（字句解析は最長一致ではなく最初に合った規則を取るため）。as と ref は、後ろに英数字・_ が続くときは規則にしません。字句解析の全規則の綴りが、その規則で最後まで読まれることを確かめるテストを加えました
• -p／-o に知らない形式名を渡すと、Error: ... ではなく Python のトレースバックが出て終了していたのを修正（resolve_invocation が投げる UnknownFormatError を CLI がキャッチしていなかった、既存の不具合）。今回の作業中に見つけました

互換性の見える化

互換テストの結果は v0.3.0 から変わりません（この版は Go 版にない機能の追加が中心で、演算子・形式の互換テストへの影響はありません）。

	v0.3.0	v0.4.0
演算子シナリオ（1,091 件）で一致	1,047	1,047（完全一致 1,016 ＋ 意味的に一致 31）
未実装の演算子に当たるもの	28	28（load envsubst eval）
既知の差異	4（shuffle の並び）	4
形式シナリオ（154 件）で一致	149	149

• prune_null prune_empty schema と、レシピ、入力形式の自動判定、自己説明は Go 版にないため、互換テストの対象外です

既知の制限（この版のもの）

• レシピはリクエストのみです（レスポンスの変換はありません）。会話の中のツール呼び出しの履歴（tool_calls tool_use functionCall など）と、画像・音声・ファイルは変換せず、落として報告します
• 目標スキーマとの照合は、JSON Schema の完全な検証ではありません（type enum const required properties additionalProperties items minItems maxItems minimum maximum anyOf oneOf allOf、ローカルの $ref だけ）。完全な検証は、のちの版の予定です
• Anthropic のドキュメントは、新しいモデルでは temperature が非推奨（1.0 のみ受け付ける）としています。Anthropic 向けの変換結果は、使うモデルで確かめてください
• 自動判定は「推測」です。TOML と properties は、どちらも素の key = value の並びで書けるため、型付きの値（引用符・配列・日付）が無いと properties 側に倒します。単一列の CSV/TSV や、値だけの文書などは見分けられず yaml になります。判定に自信が持てないときは、-p で明示してください
• 自己説明（--guide-prompt --skill-md など）の文章は日本語です。GUI はレシピに対応していません
• prune_null は配列の要素を消しません（del(.. | select(. == null)) とは違います）
• v0.3.0 までの制限（load などの未実装、TOML のコメントは保持されない、など）は変わりません

v0.3.0: string, array, encode/decode and date-time operators, -s split output

演算子の拡充の版です。 v0.2.0 までは、join や unique など多くの演算子を実行すると unknown operator になりました。この版で、ファイル・環境変数・外部コマンドに触れるもの（load load_str eval envsubst system）と error を除く、Go 版 yq のすべての演算子が使えます。本体は引き続き Python の標準ライブラリだけで動きます。各演算子の使い方は USAGE.ja.md にあります。

新しくできること

分類	演算子・機能
文字列	join split sub match capture test trim upcase downcase to_string to_number、文字列補間 "…\(式)…"（--string-interpolation=false で無効に）
配列・マップ	reverse shuffle first filter unique unique_by group_by flatten pivot pick omit sort_keys with reduce array_to_map contains
encode / decode	to_json to_yaml to_xml to_props to_csv to_tsv、対応する from_*、@json @yaml @xml @props @csv @tsv（と …d）、@base64 @base64d @uri @urid @sh
日時	now tz from_unix to_unix format_datetime with_dtf。Go の時間の書式（Monday, 02-Jan-06 at 3:04PM MST など）を読み書きし、+= -= < sort_by も with_dtf の書式で動きます
文書の分割	split_doc、-s / --split-exp / --split-exp-file（結果ごとに、式で名付けた別のファイルへ書く。$index が使えます）

• 正規表現は Go（RE2）に近づけています：$ は文字列の終わりだけに一致（YAML の複数行文字列の末尾の改行に一致しません）、(?<名前>…)、[[:alpha:]]、置換の $1 ${名前}、match の offset は UTF-8 のバイト数。\pL などの Unicode クラスと (?U) は、エラーで知らせます
• tz("Asia/Tokyo") のような IANA 名には、OS の時間帯データが要ります。Windows では pip install tzdata を実行してください（UTC と Local は不要）。実行時の依存が増えるわけではありません
• -s は安全のため、名前に .. を含むものを書きません（Go 版にない制限。名前はデータから決まるため）。--security-disable-file-ops を付けると使えず、ライブラリの既定（SecurityPolicy.strict()）でも拒否されます
• 空の文字列を from_yaml などで読むと null になります（Go 版は形式によって EOF エラー）
• from_yaml | … | to_yaml の往復で、元の文字列に末尾の改行がなければ付けません（Go 版と同じ）
• first は、Go 版と同じく、マップに使うと最初のキーを返します

ライブラリ・開発者向けの変更

• Yq(clock=...)、YqService(clock=...)：now と shuffle が読む時計を差し替えられます（テスト用）
• Options.string_interpolation、EvaluateRequest.split_expression
• FileSystemPort に write_file(path, text) が加わりました（-s がファイルとディレクトリを作るため）。自作のポート実装は、このメソッドを足してください
• 互換テストのハーネスは、Go のテストと同じく時計を固定して now の結果を比べます。形式に依存するシナリオ（requiresFormat）も実行します
• tzdata を開発用の依存グループ（dev）に加えました（IANA 名のテスト用）

修正

• test 演算子が、test(正規表現; "g") のように 2 つ目の引数を受け取れなかったのを修正

互換性の見える化

	v0.2.0	v0.3.0
演算子シナリオ（1,091 件）で一致	837	1,047
未実装の演算子に当たるもの	228	28（load envsubst eval）
既知の差異	4（文字列補間）	4（shuffle の並び）
環境や外部コマンドに依存して比べられない	22	12
形式シナリオ（154 件）で一致	146	149（不一致 5 件は TOML のコメント保持）

• shuffle の並びが Go 版と違うのは、Go の乱数列（math/rand）を再現しないためです（並べ替えとしては正しい）
• 演算子シナリオの合格率は 99.6%（比べられる 1,051 件のうち 1,047 件）、XML・CSV/TSV・properties の形式シナリオは全件が一致します

既知の制限（この版で変わったもの）

• 使えない演算子：load load_str eval envsubst system error（実行すると Error: unknown operator ...）。安全性の設計をしてから入れる予定です
• 未対応のオプション：-f（--front-matter）、-C（色付き出力）
• 時刻の精度はマイクロ秒（Go はナノ秒）、年は 1〜9999 です
• v0.2.0 までの制限（TOML のコメントは保持されない、CSV の文字コードは UTF-8 のみ、など）は変わりません

v0.2.0: XML, CSV/TSV, TOML, properties input, schema operator, GUI format badges

形式の拡充とスキーマ出力の版です。 XML・CSV / TSV・TOML を読み書きでき、properties も読めるようになりました。あわせて、データから JSON Schema を作る schema を加えました。本体は引き続き Python の標準ライブラリだけで動きます。

新しくできること

形式の追加（詳しい規則は USAGE.ja.md の各節）

形式	入力	出力	拡張子・名前
XML	○	○	.xml / -p xml -o xml（別名 x）
CSV / TSV	○	○	.csv .tsv / csv tsv（別名 c t）
TOML	○	○	.toml / toml
properties	○（新）	○	.properties / props

• XML：Go 版 yq と同じ変換規則（属性 +@名前、本文 +content、コメント・処理命令・<!DOCTYPE> を保持）。宣言された実体は展開しないので、外部実体や Billion laughs の危険がありません。入れ子は 200 段まで。本文と子要素が交互に並ぶ文書は、書き戻すと本文を要素の前にまとめます（単語は残り、前後関係は保たれません。Go 版は本文を落とします）。実在の XML 498 ファイルを往復して、要素・属性・単語が変わらないことを確認しました
• CSV / TSV：1 行目がヘッダ、セルは YAML の値として読みます（数値・真偽値・null、cool: true のような構造も）。--csv-auto-parse=false --csv-separator --tsv-auto-parse=false
• TOML：自前のパーサ（CPython の TOML 適合テスト 62 ファイルを全件クリア）で、数値の元の書き方（0xFF）とインラインテーブル／[table] の区別を保ったまま読み書きします（pyproject.toml の値を書き換えても見た目が変わりません）。コメントは保持されません。そのため -i は既定で拒否します（--toml-allow-lossy で許可）
• properties の入力：a.b.c = x を階層に、pets.0 / pets[0]（--properties-array-brackets）を配列にします。項目の直前のコメントは項目のコメントになります
• XML・CSV・TOML・properties の Go 版フラグ（--xml-* --csv-* --tsv-auto-parse）は Go 版と同じ名前・既定値です
• 形式は登録するだけで、-p auto の拡張子判定と GUI の形式の選択肢・「開く」ダイアログにも自動で出ます

スキーマの出力：schema（Go 版にない拡張）

• yaqpy --schema data.yaml、または式の中で schema（.items[] | schema）。データから JSON Schema（Draft 2020-12） を作り、JSON でも YAML でも出せます
• type・properties・required（全サンプルにあるキーだけ）・items・format（日付・日時）を推論します。--schema-strict（additionalProperties: false）、--schema-enum-max N（enum の推定）、--schema-per-doc（文書ごと）はオプションです
• 生成したスキーマは元のデータを必ず通します

GUI の見た目

• 見出し「オリジナル」「変換結果」の横に、いま採用している形式（xml・toon など）を札で表示します。形式バーが auto でも指定でも、実際に使う形式名が出ます（エラーのときも消えません）
• 開いたファイルの名前（と「貼り付けたテキスト」）を、ボタンと同じ大きさの太字にしました
• 「プロパティ」の行と「式」の行の間を広げました（ラベルが重なって見えないように）

修正

• JSON の {}（空のオブジェクト）が []（空の配列）になるバグを修正しました。{"a": {}} が a: [] になっていました（v0.1.0 からの不具合）
• YAML の出力を go-yaml に合わせました：cool: true のような、プレーンにできない文字列は '...'（従来は "..."）、複数行の行コメントの 2 行目以降と、フットコメントのあとの空行を落とさない
• properties の出力：コメント付きの項目の前に空行を入れる（Go 版と同じ）。-r=false では空白を含む値を "..." で囲む

互換性の見える化

Go 版の形式のシナリオ 154 件（tests/golden/formats/）を互換テストに加えました。実行できるもののうち合格したのは次のとおりです（演算子のシナリオ 1,091 件は従来どおり 837 件が一致）。

形式	シナリオ	合格	内訳・不一致の理由
XML	52	51	残り 1 件は from_yaml 演算子が未実装（v0.3.0 の予定）。書式だけが違うもの 2 件を含みます
CSV / TSV	18	18	すべて完全一致
TOML	62	57	残り 5 件はコメントを保持するもの（今の版は保持しない）
properties	22	20	残り 2 件は from_yaml・array_to_map が未実装

python tools/golden_report.py --formats で一覧を確認できます。

既知の制限（この版で変わったもの）

• 未対応のフォーマット：INI・HCL・Lua・shell 変数・base64・URI など（CSV / TSV / XML / TOML / properties の入力は使えるようになりました）
• TOML のコメントは保持されません（-i は既定で拒否）。XML は文字コード宣言（encoding="ISO-8859-1" など）があっても UTF-8 として読みます。CSV の文字コードは UTF-8 のみです
• 演算子の未実装は、この版では変わりません（from_yaml・join・split など。v0.3.0 で拡充する予定です）

initial release

[0.1.0] - 2026-09-20

初版です。 YAML / JSON をコマンドや Python から、式で取り出し・更新・変換できます。Go 版 yq（v4.53.6）の式を手本にし、Python の標準ライブラリだけで実装しています。

インストール方法は README を参照してください（PyPI には公開していません。GitHub のリリースから入れます）。

できること

コマンド（yaqpy）

• 式で値を取り出す：yaqpy '.server.port' config.yaml
• 条件で絞り込む：yaqpy '.items[] | select(.price > 500) | .name' config.yaml
• 値を更新する（-i でファイルをその場で書き換え）：yaqpy -i '.server.port = 9090' config.yaml
• 形式を変換する：YAML ⇔ JSON ⇔ TOON、properties への出力（-o json など）
• 標準入力・複数ファイル・複数ドキュメントに対応

書式を壊さない

更新しても、コメント、キーの並び順、アンカー（& / *）、数値やクォートの元の書き方（0x1F、1.50、'yes'）がそのまま残ります。-i は一時ファイルを経由して置き換えるので、途中で失敗しても元のファイルは壊れません。

Python ライブラリ

import yaqpy で、evaluate / query / update などが使えます。

import yaqpy
yaqpy.evaluate(".server.port", "server:\n  port: 8080\n")   # '8080\n'

デスクトップ GUI（yaqpy-gui または yaqpy --gui）

コマンドが苦手でも、画面で試せます。

• ファイルを開く（または貼り付け）と、左に原文そのまま、右に変換結果が出ます
• プロパティのプルダウンから選ぶだけで式が入ります。文字を打つと候補が絞り込まれます
• 式を直接書くこともできます。書き間違いは、赤枠と位置の表示でその場で分かります
• 出力形式（YAML / JSON / properties / TOON）、字下げ、整形を選べます
• 結果を別名で保存、またはクリップボードにコピーできます。開いたファイルは、確認なしには上書きしません
• 重い処理でも画面は固まらず、[中止] で止められます
• 初心者向けの手引き USAGE-GUI.ja.md を用意しています（式の書き方を含みます）