Hugging Face's logo

Spaces:
build-small-hackathon
/
GAHAKU-EXAM
Paused

App Files Community
GAHAKU-EXAM / docs /specification.md
ino
Update specification.md
6226a25
preview code
|
Raw
History Blame Contribute Delete
7.88 kB

A newer version of the Gradio SDK is available: 6.20.0

Upgrade

GAHAKU EXAM 仕様書（実装準拠 v1.2）

1. 概要

プレーヤーにランダムで1つの英単語（お題）を与え、プレーヤーはPyxelベースのドット絵エディタでその単語を表現する。
描いたドット絵をAIへ入力し、推論結果の上位5件にお題語が含まれていれば成功とする。

ゲームの目的は「できるだけ少ないドット数でAIに正解させること」。

2. 対象プラットフォーム

  • デプロイ先: Hugging Face Spaces
  • SDK: Gradio
  • 描画エンジン: Pyxel（pyxel.js経由でWeb実行）
  • 推論: Hugging Face Inference API（VLM優先 + フォールバック）

3. 用語定義

  • お題: プレーヤーに提示される英単語
  • キャンバス: ドット絵を描く領域（16x16）
  • ドット数: 背景色以外で塗られたセル数
  • 試行: 1回のAI判定リクエスト
  • ラウンド: 1つのお題に対する挑戦単位

4. ゲームルール

  1. ゲーム開始時に英単語を1つランダム出題する。
  2. プレーヤーは24色パレットを使い、マウスまたはタッチでドット絵を描く。
  3. Pyxel内の EXPORT で描画データを window.__PYXEL_PAYLOAD に保存する。
  4. Gradio側の Sync from Pyxel（日本語UIでは Python側へ取り込む）で受信確認できる。
  5. Judge with AI（日本語UIでは AIで判定する）でAI判定を行う。
  6. AI上位5候補にお題語が含まれる場合は成功。
  7. 含まれない場合は失敗カウントを1増やす。
  8. 失敗が3回に達した時点でラウンド失敗（ゲームオーバー）。
  9. Next Round（日本語UIでは 次のラウンド）で次ラウンドへ進む。

5. 機能要件

5.1 お題出題

  • お題辞書（英単語リスト）からランダムに1語を選択。
  • 同一ラウンド中はお題を固定。
  • 前ラウンドと同じ単語は可能な限り連続しないよう回避（候補数が2語以上の場合）。

5.2 ドット絵エディタ

  • キャンバスサイズ: 16x16セル（固定）
  • 画面サイズ: pyxel.init(310, 220)
  • パレット: 論理24色
  • 実行環境が16色のみ対応の場合:
    • 17〜24色相当はディザリングで近似表示
  • 入力方式:
    • マウス: クリック/ドラッグ
    • タッチ: タップ/スワイプ
  • 基本ツール:
    • ペン
    • 消しゴム
    • 全消去
    • EXPORT
  • 画面表示:
    • 使用ドット数（リアルタイム）
    • 操作ガイド（TOUCH/DRAG TO DRAW）

5.3 AI判定

  • 入力: キャンバス画像（PNG, 224x224へ最近傍拡大）
  • 推論フロー（優先順）:
    1. VLMチャット補完（候補モデルを順に試行）
    2. Zero-shot image classification（provider live のみ）
    3. 画像分類モデル（google/vit-base-patch16-224）
  • provider live 判定:
    • Hugging Face model info の inferenceProviderMapping を参照
    • モデル×タスク結果をキャッシュ
  • 出力:
    • 上位5候補（label, score）
    • VLM経路では順位ベース擬似スコアを付与
  • 正誤判定:
    • ラベルとお題語を正規化（小文字化、記号除去、空白正規化）
    • 上位5件内に一致があれば正解

5.4 スコアリング

  • 成功時にラウンドスコアを確定。

  • 計算式:

    score = max(0, BASE_SCORE - DOT_PENALTY * used_dots - MISS_PENALTY * miss_count)

  • 定数:

    • BASE_SCORE = 1000
    • DOT_PENALTY = 8
    • MISS_PENALTY = 120

5.5 失敗条件

  • 不正解が3回でラウンド失敗。
  • 失敗時もAI上位5結果は表示される（取得できた場合）。

5.6 多言語対応（実装済み）

  • UI言語: 日本語 / 英語
  • 言語切替: Gradioのラジオボタン
  • 切替対象:
    • イントロ文
    • ボタンラベル
    • テキスト/JSONのラベル
    • ラウンド情報表示
    • ステータスメッセージ
  • 既定言語: 英語

5.7 判定演出（実装済み）

  • Pyxel側に演出状態を保持（idle / judging / success / fail）。
  • Judge with AI 押下時に judging へ遷移。
  • Next Round 押下時に idle へリセット。
  • Pyxel上に簡易アニメーションと文言を表示:
    • AI JUDGING...
    • CORRECT!
    • NOT YET / TRY AGAIN

6. 画面仕様（現行）

6.1 メイン画面

  • サイドバー（Spaces時のみ）:
    • Loginボタン
  • ヘッダ行:
    • 左: タイトルと手順
    • 右: 言語トグル（日本語/English）
  • エディタ表示:
    • Pyxelキャンバス埋め込み
    • ヘルプ文
  • ラウンド情報:
    • Round / お題(Target) / 状態 / ミス / 使用ドット / ラウンドスコア / 合計スコア
  • 操作行:
    • Sync from Pyxel
    • Judge with AI
    • Next Round
  • 情報表示:
    • Statusテキスト
    • Received JSON（開発表示）
    • AI Top 5

6.2 ボタン活性

  • Next Round は常時押下可能。
  • ラウンドが success または fail のとき、同一ラウンドへの再判定は拒否してメッセージを返す。

7. 状態管理

7.1 ラウンド状態（Gradio State）

  • round_id
  • round_number
  • target_word
  • miss_count
  • round_result（ongoing / success / fail）
  • used_dots
  • round_score
  • total_score
  • last_top5_predictions

7.2 UI補助状態

  • lang_state（ja / en）
  • window.__PYXEL_PAYLOAD（Pyxel→Gradio受け渡し）
  • window.__AI_JUDGE_STATE（演出状態連携）

8. 外部連携仕様

8.1 Inference API

  • 認証:
    • Spaces: OAuthトークン優先
    • ローカル: HF_TOKEN 環境変数
  • 主な利用API:
    • Chat Completions（VLM）
    • Zero-shot image classification
    • Image classification
  • タイムアウト:
    • provider確認: 10秒
  • リトライ:
    • 同一モデルへの自動リトライはなし
    • モデル切替フォールバックで継続

8.2 モデル選定

  • 第一候補VLM: Qwen/Qwen3-VL-8B-Instruct
  • 代替VLM候補あり（provider liveのみ実行）
  • Zero-shot候補:
    • openai/clip-vit-large-patch14
    • openai/clip-vit-base-patch32
  • 最終フォールバック:
    • google/vit-base-patch16-224

9. 非機能要件

  • 操作性:
    • PC/スマートフォン対応
    • Pyxel表示領域は 31:22 の比率で表示
  • セキュリティ:
    • トークンはクライアントへ露出しない
  • ロギング:
    • 判定フローをコンテナログへ出力
    • 例: judge_start, vlm_try, vlm_success, fallback_to_image_classification

10. 受け入れ基準（現行実装）

  1. ラウンド開始時に英単語がランダム表示される。
  2. 24色・16x16のドット絵編集がマウス/タッチで可能。
  3. EXPORT → Sync from Pyxel でJSON受信確認ができる。
  4. Judge with AI 実行でAI上位5ラベルが表示される。
  5. 上位5にお題語が含まれると成功判定になる。
  6. 不正解3回で失敗終了になる。
  7. 成功時スコアがドット数とミス数を反映して算出される。
  8. 第一候補VLMが利用可能な場合はVLM経路で判定できる。
  9. 第一候補VLMが利用不能でもフォールバック経路で継続判定できる。
  10. 日本語/英語UI切替が機能する。
  11. Next Round 押下で判定演出が idle にリセットされる。

11. 既知の制約

  • Received JSON は開発向け表示として常時表示される。
  • 演出の成功/失敗遷移は status_box.change フックに依存するため、接続経路やUI更新順によって見え方が変わる場合がある。

12. 今後拡張候補

  • 難易度別お題セット
  • 制限時間モード
  • ランキング機能
  • お題に対する禁止色/使用色制限
  • 複数ラウンド合計スコア制
  • 開発用表示（Received JSON）の表示切替