initial commit

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+dataset/** filter=lfs diff=lfs merge=lfs -text
+CKIP/** filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,74 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual Environment
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+dealer/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+*/.ipynb_checkpoints/*
+*.ipynb_checkpoints
+
+# CKIP Files (auto download from Hugging Face)
+CKIP/
+
+# Data folder
+data/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Windows
+Thumbs.db
+ehthumbs.db
+Desktop.ini
+
+# Gradio
+.gradio/
+*.db
+flagged/
+gradio_cached_examples/
+
+# Logs
+*.log
+
+# Environment variables
+.env
+.env.local
+
+# Temporary files
+*.tmp
+*.temp
+*.bak
+

app.ipynb

@@ -0,0 +1,757 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "341f0828",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "D:\\anaconda3\\envs\\study_prompt\\lib\\site-packages\\tqdm\\auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
+      "  from .autonotebook import tqdm as notebook_tqdm\n"
+     ]
+    },
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "WARNING:tensorflow:From D:\\anaconda3\\envs\\study_prompt\\lib\\site-packages\\keras\\src\\losses.py:2976: The name tf.losses.sparse_softmax_cross_entropy is deprecated. Please use tf.compat.v1.losses.sparse_softmax_cross_entropy instead.\n",
+      "\n",
+      "WARNING:tensorflow:From D:\\anaconda3\\envs\\study_prompt\\lib\\site-packages\\ckiptagger\\api.py:8: The name tf.logging.set_verbosity is deprecated. Please use tf.compat.v1.logging.set_verbosity instead.\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "import re\n",
+    "import gradio as gr\n",
+    "import json, random\n",
+    "from util.reading_constants import READING_LEVEL_CONFIG, FIX_PREFERENCE_PROMPT, FIX_HIGH_LEVEL_PROMPT, FIX_LOW_LEVEL_PROMPT\n",
+    "from util.cloze_constants import CLOZE_LEVEL_CONFIG, CLOZE_FIX_PREFERENCE_PROMPT, CLOZE_FIX_HIGH_LEVEL_PROMPT, CLOZE_FIX_LOW_LEVEL_PROMPT\n",
+    "from util.sentence_dealer import Sentence_Dealer\n",
+    "from util.judgement import READING_JUDGE_PROMPTS, CLOZE_JUDGE_PROMPTS, QUALIFICATION_SCHEMA\n",
+    "\n",
+    "def load_json(data_path:str):\n",
+    "    with open(data_path, \"r\", encoding=\"utf-8\") as f:\n",
+    "        result = json.load(f)\n",
+    "    return result"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "bb187536",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "D:\\anaconda3\\envs\\study_prompt\\lib\\site-packages\\ckiptagger\\model_ws.py:106: UserWarning: `tf.nn.rnn_cell.LSTMCell` is deprecated and will be removed in a future version. This class is equivalent as `tf.keras.layers.LSTMCell`, and will be replaced by that in Tensorflow 2.0.\n",
+      "  cell = tf.compat.v1.nn.rnn_cell.LSTMCell(hidden_d, name=name)\n",
+      "D:\\anaconda3\\envs\\study_prompt\\lib\\site-packages\\ckiptagger\\model_pos.py:56: UserWarning: `tf.nn.rnn_cell.LSTMCell` is deprecated and will be removed in a future version. This class is equivalent as `tf.keras.layers.LSTMCell`, and will be replaced by that in Tensorflow 2.0.\n",
+      "  cell = tf.compat.v1.nn.rnn_cell.LSTMCell(hidden_d, name=name)\n",
+      "D:\\anaconda3\\envs\\study_prompt\\lib\\site-packages\\ckiptagger\\model_ner.py:57: UserWarning: `tf.nn.rnn_cell.LSTMCell` is deprecated and will be removed in a future version. This class is equivalent as `tf.keras.layers.LSTMCell`, and will be replaced by that in Tensorflow 2.0.\n",
+      "  cell = tf.compat.v1.nn.rnn_cell.LSTMCell(hidden_d, name=name)\n"
+     ]
+    }
+   ],
+   "source": [
+    "data_folder_path = \"./dataset/\"\n",
+    "CHOICE_LABELS = ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H', 'I', 'J', 'K', 'L', 'M', 'N', 'O', 'P', 'Q', 'R', 'S', 'T', 'U', 'V', 'W', 'X', 'Y', 'Z', 'AA', 'AB', 'AC', 'AD', 'AE', 'AF', 'AG', 'AI', 'AK', 'AL', 'AM', 'AN', 'AP', 'AR', 'AS', 'AT', 'AU', 'AV', 'AW', 'AX', 'BA', 'BB', 'BC', 'BD', 'BE', 'BF', 'BI', 'BL', 'BO', 'BR', 'BS', 'BU', 'BY', 'CA', 'CB', 'CC', 'CD', 'CE', 'CF', 'CG', 'CH', 'CI', 'CK', 'CL', 'CM', 'CN', 'CO', 'CP', 'CR', 'CS', 'CT', 'CV', 'DA', 'DB', 'DC', 'DD', 'DE', 'DF', 'DI', 'DK', 'DL', 'DM', 'DN', 'DO', 'DP', 'DR', 'DS', 'DT', 'DU', 'EB', 'EC', 'ED', 'EE', 'EF', 'EG', 'EL', 'EM', 'EN', 'EP', 'EQ', 'ER', 'ES', 'ET', 'EV', 'EX', 'EY', 'FA', 'FB', 'FC', 'FD', 'FE', 'FF', 'FI', 'FL', 'FM', 'FO', 'FP', 'FR', 'FS', 'FT', 'FX', 'GA', 'GB', 'GC', 'GE', 'GG', 'GL', 'GM', 'GN', 'GO', 'GP', 'GR', 'GS', 'GT', 'GV', 'HA', 'HC', 'HD', 'HE', 'HH', 'HI', 'HL', 'HO', 'HP', 'HR', 'HS', 'HT', 'IA', 'IB', 'IC', 'ID', 'IE', 'IF', 'IG', 'II', 'IK', 'IL', 'IM', 'IN', 'IO', 'IP', 'IR', 'IS', 'IT', 'IV', 'IX', 'IZ', 'JB', 'JS', 'KB', 'KE', 'KS', 'LA', 'LC', 'LD', 'LE', 'LI', 'LL', 'LM', 'LO', 'LP', 'LR', 'LS', 'LT', 'LY', 'MA', 'MB', 'MC', 'MD', 'ME', 'MI', 'ML', 'MM', 'MO', 'MP', 'MQ', 'MR', 'MS', 'MT', 'MW', 'MY', 'NA', 'NB', 'NC', 'ND', 'NE', 'NF', 'NG', 'NI', 'NL', 'NN', 'NO', 'NP', 'NR', 'NS', 'NT', 'NU', 'OB', 'OC', 'OD', 'OF', 'OH', 'OK', 'OL', 'OM', 'ON', 'OP', 'OR', 'OS', 'OT', 'OU', 'OW', 'PA', 'PC', 'PD', 'PE', 'PF', 'PG', 'PH', 'PI', 'PK', 'PL', 'PM', 'PN', 'PO', 'PP', 'PR', 'PS', 'PT', 'PU', 'PY', 'QL', 'QU', 'RA', 'RC', 'RE', 'RI', 'RL', 'RO', 'RS', 'RT', 'RU', 'RY', 'SA', 'SB', 'SC', 'SD', 'SE', 'SF', 'SG', 'SH', 'SI', 'SK', 'SL', 'SM', 'SN', 'SO', 'SP', 'SR', 'SS', 'ST', 'SU', 'SV', 'SW', 'SY', 'TA', 'TB', 'TC', 'TD', 'TE', 'TF', 'TH', 'TI', 'TL', 'TM', 'TO', 'TP', 'TR', 'TS', 'TT', 'TV', 'TW', 'TX', 'TY', 'UB', 'UC', 'UD', 'UE', 'UG', 'UI', 'UK', 'UL', 'UM', 'UN', 'UP', 'UR', 'US', 'UT', 'VA', 'VB', 'VC', 'VD', 'VE', 'VF', 'VI', 'VM', 'VO', 'VP', 'VS', 'WA', 'WD', 'WE', 'WF', 'WH', 'WI', 'WM', 'WN', 'WP', 'WR', 'WS', 'WT', 'XT', 'XV', 'XX', 'XY', 'YS', 'YY', 'ZE', 'ABC', 'ACE', 'ACK', 'ACT', 'ADD', 'AGE', 'ALL', 'AME', 'AML', 'AMP', 'AND', 'ANG', 'ANT', 'API', 'APP', 'ARD', 'ARN', 'ART', 'ARY', 'ASC', 'ASE', 'ASH', 'ASS', 'AST', 'ATA', 'ATE', 'ATH', 'AUT', 'AVA', 'AXI', 'BER', 'BIT', 'BUG', 'CAA', 'CAT', 'CCE', 'CCN', 'CES', 'CLA', 'CLC', 'CLI', 'COL', 'COM', 'CON', 'CRE', 'CSS', 'CUR', 'DAT', 'DAY', 'DBC', 'DEF', 'DER', 'DEX', 'DIR', 'DIS', 'DOC', 'DOM', 'EAR', 'ECK', 'ECT', 'ELD', 'EMA', 'END', 'ENT', 'ENV', 'ERE', 'ERR', 'ERS', 'ERT', 'ERY', 'EXT', 'FIG', 'FIX', 'FLA', 'FOR', 'GEN', 'GER', 'GET', 'HER', 'IAB', 'IAL', 'ICE', 'IDE', 'IES', 'IGN', 'III', 'ILL', 'IMA', 'IME', 'IND', 'INE', 'INF', 'ING', 'INT', 'ION', 'IOS', 'ISO', 'IST', 'ITE', 'ITH', 'ITY', 'IVE', 'JAX', 'KEY', 'LAB', 'LAY', 'LED', 'LES', 'LIC', 'LIN', 'LOB', 'LOC', 'LOG', 'LOW', 'MAN', 'MAP', 'MAX', 'MIN', 'MIT', 'MON', 'NER', 'NET', 'NEW', 'NOT', 'NUM', 'OFF', 'OIN', 'ONE', 'ONG', 'OPT', 'ORD', 'ORM', 'ORS', 'ORT', 'ORY', 'OST', 'OUR', 'OUT', 'PAR', 'PDF', 'PER', 'PHP', 'POS', 'PRE', 'PRI', 'PRO', 'PUT', 'QUE', 'RAM', 'RAY', 'RED', 'REE', 'REF', 'REG', 'RES', 'RGB', 'RIG', 'ROM', 'ROP', 'ROR', 'ROW', 'SBN', 'SDK', 'SEE', 'SER', 'SET', 'SHA', 'SON', 'SQL', 'SSL', 'SSN', 'STR', 'SUB', 'SUM', 'TAC', 'TAG', 'TER', 'THE', 'UES', 'UID', 'ULL', 'ULT', 'UMN', 'UND', 'UNT', 'URE', 'URI', 'URL', 'URN', 'USA', 'USE', 'UST', 'UTC', 'UTE', 'UTF', 'VAL', 'VAR', 'VER', 'VID', 'VIS', 'WID', 'WIN', 'WOR', 'XML', 'XXX', 'YES', 'YPE']\n",
+    "with open(data_folder_path + 'grammars.jsonl', 'r', encoding='utf-8') as f:\n",
+    "    GRAMMAR_ID2INFO = {item['grammar_id']: item for item in [json.loads(line) for line in f]}\n",
+    "\n",
+    "word2explanation_infos = load_json(data_folder_path + \"MOE_word2explanations_8.json\")\n",
+    "word2explanation_infos.update(load_json(data_folder_path + \"TMLD_word2explanations_3.json\"))\n",
+    "\n",
+    "# 載入主題和副主題對應\n",
+    "subtopic_map = load_json(data_folder_path + \"subtopic_map20251002v2.json\")\n",
+    "\n",
+    "dealer = Sentence_Dealer(ckiptagger_path=\"./CKIP/\")"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "64d44fce",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "#Modify the ckiptagger_path if you want\n",
+    "\n",
+    "sample_sentence = \"\"\"朝聞道夕死可矣\"\"\"\n",
+    "\n",
+    "grammar_ids, grammar_range = dealer.list_all_grammars(sentence=sample_sentence)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "a18b23ad",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[([242, 243, 244, 309], 5)]\n"
+     ]
+    }
+   ],
+   "source": [
+    "grammar_starts = [x[0] for x in grammar_range]\n",
+    "grammar_id2range = [(x,y) for x, y in sorted(zip(grammar_ids, grammar_starts), key=lambda p: p[1])]\n",
+    "print(grammar_id2range)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "id": "a377fe5e",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "\n",
+    "\n",
+    "def remove_example(text):\n",
+    "        #return text.replace('「', '『').replace('」', '』')\n",
+    "        if text.startswith('《'):\n",
+    "            # 如果第一個字是《，保留直到第二次出現《之前的文字\n",
+    "            tmp_str = re.sub(r'(《.*?《).*', r'\\1', text).rstrip('《')\n",
+    "        else:\n",
+    "            # 否則，保留《之前的文字\n",
+    "            tmp_str = re.sub(r'(.*?)《.*', r'\\1', text)\n",
+    "        tmp_str = tmp_str.split(\"如：\")[0] #去除\"如：\"以後的字\n",
+    "        index = tmp_str.find('。')\n",
+    "        return tmp_str[:index + 1] if index != -1 else text #去除\"。\"以後的字\n",
+    "\n",
+    "def sentence_segmentation(text):\n",
+    "    sentence_list = text.split('。')\n",
+    "    sentence_list = [sen.strip() + '。' for sen in sentence_list if sen.strip() != '']\n",
+    "    return sentence_list"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "id": "b53b89ce",
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "['朝聞道夕死可矣。']"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "sentence_segmentation(sample_sentence)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "id": "8273fac9",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "## 為了方便理解，我們對任務做了簡化"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "462508ee",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# =========================\n",
+    "# 1. 函式定義區（先留空給你實作）\n",
+    "# =========================\n",
+    "\n",
+    "def gen_textbook_prompt(\n",
+    "    tbcl_level: str,\n",
+    "    main_topic: str,\n",
+    "    sub_topic: str,\n",
+    "    extra_content: str,\n",
+    "    article_type: str,\n",
+    ") -> str:\n",
+    "    \"\"\"\n",
+    "    課文生成 prompt 產生器\n",
+    "    根據 TBCL 等級、主題、副主題、額外內容和文章類型生成適合的課文生成 Prompt\n",
+    "    \"\"\"\n",
+    "    \n",
+    "    # Prompt 模板庫（參考 inference_codes/extras/prompts.py）\n",
+    "    PURE_TEMPLATES = [\n",
+    "        \"請以「{topics}」為主題，撰寫一篇 TBCL {level} 級的華語{textbook_type}課文。\",\n",
+    "        \"請完成一篇有關「{topics}」且 TBCL 分級為 {level} 級的華語課文，課文形式為{textbook_type}。\",\n",
+    "        \"以「{topics}」為題，編寫一篇華語課文。\\nTBCL 分級為 {level} 級，要求格式為{textbook_type}\",\n",
+    "        \"請提供一篇關於「{topics}」的課文。\\n課文形式為{textbook_type}，TBCL 分級為 {level} 級。\",\n",
+    "        \"生成一篇難度為 TBCL {level} 級的{textbook_type}華語課文，內容需與「{topics}」相關\",\n",
+    "        \"請針對「{topics}」寫出一篇華語{textbook_type}課文，難度必須符合 TBCL {level} 級。\",\n",
+    "        \"請撰寫一篇華語課文。\\n類型：{textbook_type}\\n主題：{topics}\\nTBCL 分級：{level}\",\n",
+    "        \"請根據「{topics}」主題，撰寫一篇符合 TBCL {level} 級標準的華語{textbook_type}課文。\",\n",
+    "    ]\n",
+    "    \n",
+    "    SUBTOPIC_TEMPLATES = [\n",
+    "        \"請以「{topics}」為主題，選擇一至多個邏輯相關的子主題(如：{subtopics})，撰寫一篇TBCL {level}級的華語{textbook_type}課文。請確保選擇的面向能自然地融入內容中。\",\n",
+    "        \"以「{topics}」為主軸，從此主題的相關面向中選擇一至多個相互關聯的元素，編寫一篇TBCL {level}級的{textbook_type}課文。內容須流暢地整合這些面向。\",\n",
+    "        \"撰寫一篇TBCL {level}級的華語{textbook_type}課文。主題為「{topics}」，請自由選擇一至多個相關子主題(參考但不限於：{subtopics})。所選面向須具邏輯關聯，並在課文中自然呈現。\",\n",
+    "        \"請以「{topics}」為核心主題，從相關子主題(如{subtopics})中挑選一至多個具關聯性的元素，編寫一篇TBCL {level}級的{textbook_type}課文。要求各面向之間的過渡自然，內容連貫。\",\n",
+    "        \"以「{topics}」為主題創作一篇TBCL {level}級華語{textbook_type}課文。請自選一至多個相關連的子主題(可參考：{subtopics})，並設計合適的情境來呈現這些面向。\",\n",
+    "    ]\n",
+    "    \n",
+    "    # 參數驗證\n",
+    "    valid_levels = [\"第一級\", \"第二級\", \"第三級\", \"第四級\", \"第五級\", \"第六級\"]\n",
+    "    valid_topics = list(subtopic_map.keys())\n",
+    "    valid_article_types = [\"短文\", \"對話\"]\n",
+    "    \n",
+    "    if tbcl_level not in valid_levels:\n",
+    "        return f\"❌ 錯誤：TBCL 等級必須是以下之一：{', '.join(valid_levels)}\"\n",
+    "    \n",
+    "    if main_topic not in valid_topics:\n",
+    "        return f\"❌ 錯誤：主題必須是以下之一：{', '.join(valid_topics)}\"\n",
+    "    \n",
+    "    if article_type not in valid_article_types:\n",
+    "        return f\"❌ 錯誤：文章類型必須是以下之一：{', '.join(valid_article_types)}\"\n",
+    "    \n",
+    "    # 判斷使用哪種模式\n",
+    "    # 如果有選擇副主題，使用 subtopic 模式；否則使用 pure 模式\n",
+    "    if sub_topic and sub_topic in subtopic_map.get(main_topic, []):\n",
+    "        # 使用副主題模式\n",
+    "        template = random.choice(SUBTOPIC_TEMPLATES)\n",
+    "        # 從該主題的副主題列表中隨機選擇幾個作為參考\n",
+    "        all_subtopics = subtopic_map[main_topic]\n",
+    "        # 確保選中的副主題在列表中，並添加其他幾個作為參考\n",
+    "        sample_subtopics = [sub_topic]\n",
+    "        other_subtopics = [s for s in all_subtopics if s != sub_topic]\n",
+    "        sample_subtopics.extend(random.sample(other_subtopics, min(4, len(other_subtopics))))\n",
+    "        subtopics_text = \"、\".join(sample_subtopics)\n",
+    "        \n",
+    "        prompt = template.format(\n",
+    "            topics=main_topic,\n",
+    "            level=tbcl_level,\n",
+    "            textbook_type=article_type,\n",
+    "            subtopics=subtopics_text\n",
+    "        )\n",
+    "    else:\n",
+    "        # 使用純主題模式\n",
+    "        template = random.choice(PURE_TEMPLATES)\n",
+    "        prompt = template.format(\n",
+    "            topics=main_topic,\n",
+    "            level=tbcl_level,\n",
+    "            textbook_type=article_type\n",
+    "        )\n",
+    "    \n",
+    "    # 如果有額外內容，附加到 prompt 後面\n",
+    "    if extra_content and extra_content.strip():\n",
+    "        prompt += f\"\\n\\n【額外要求】\\n{extra_content.strip()}\"\n",
+    "    \n",
+    "    return prompt\n",
+    "\n",
+    "\n",
+    "def gen_word_sense_prompt(\n",
+    "    sentence: str,\n",
+    "    target_word: str,\n",
+    ") -> str:\n",
+    "    \"\"\"\n",
+    "    詞意消歧 prompt 產生器\n",
+    "    \"\"\"\n",
+    "    chat_template = \"請判斷「%s」在以下句子中為何種解釋，並直接輸出正確的選項代號。\\n%s\\n\\n%s\"\n",
+    "\n",
+    "    if target_word not in sentence:\n",
+    "        return \"此詞彙未出現在句子中。\"\n",
+    "    elif target_word not in word2explanation_infos.keys():\n",
+    "        return \"此詞彙未出現在字典。\"\n",
+    "    else:\n",
+    "        split_idx = sentence.index(target_word)\n",
+    "        sentence = sentence[:split_idx]+'「'+target_word+'」'+sentence[split_idx+len(target_word):]\n",
+    "    classfication_table = \"\"\n",
+    "    for i, explaination_info in enumerate(word2explanation_infos[target_word]):\n",
+    "            classfication_table +=  CHOICE_LABELS[i] + \". \" + remove_example(explaination_info[0]) + \"\\n\"\n",
+    "    prompt = chat_template % (target_word, sentence, classfication_table[:-1])\n",
+    "    return prompt\n",
+    "\n",
+    "def  gen_word_info(sentence:str, target_word:str,  target_choice:str):\n",
+    "    columns = [\"釋義\", \"TBCL等級\", \"注音\", \"漢語拼音\", \"詞性\", \"英文翻譯\", \"例句\", \"例句漢語拼音\", \"例句翻譯\"]\n",
+    "    if target_word not in sentence:\n",
+    "        return \"此詞彙未出現在句子中。\"\n",
+    "    elif target_word not in word2explanation_infos.keys():\n",
+    "        return \"此詞彙未出現在字典。\"\n",
+    "    elif target_choice not in CHOICE_LABELS:\n",
+    "        return \"請填寫純英文代號。\"\n",
+    "    ans_id = CHOICE_LABELS.index(target_choice)\n",
+    "    explanations = word2explanation_infos[target_word]\n",
+    "    explanation_ans = explanations[ans_id][:6]+explanations[ans_id][6][0]\n",
+    "    response_str = \"\"\n",
+    "    for column, explanation_info in zip(columns, explanation_ans):\n",
+    "        response_str += \"%s: %s\\n\" %(column, explanation_info)\n",
+    "    return response_str[:-1]\n",
+    "\n",
+    "def gen_grammar_analysis_prompt(\n",
+    "    textbook: str,\n",
+    ") -> str:\n",
+    "    \"\"\"\n",
+    "    課文語法分析 prompt 產生器\n",
+    "    \"\"\"\n",
+    "    chat_template = \"請閱讀以下句子並根據解釋選出句子中有使用到的語法，請直接輸出選項代號，若有多個答案則使用頓號（、）分隔。\\n%s\\n\\n\"\n",
+    "    prompt = chat_template % (textbook)\n",
+    "    possible_grammars_list = []\n",
+    "    for sentence in sentence_segmentation(textbook):\n",
+    "        grammar_ids, grammar_starts = dealer.list_all_grammars(sentence)\n",
+    "        grammar_starts = [x[0] for x in grammar_range]\n",
+    "        grammar_ids_sorted = [x for x, _ in sorted(zip(grammar_ids, grammar_starts), key=lambda p: p[1])]\n",
+    "        for grammar_id in grammar_ids_sorted:\n",
+    "            if isinstance(grammar_id, list):\n",
+    "                for id in grammar_id:\n",
+    "                    possible_grammars_list.append(id)\n",
+    "            else:\n",
+    "                possible_grammars_list.append(grammar_id)\n",
+    "    already_have = []\n",
+    "    for i, id in enumerate(possible_grammars_list):\n",
+    "        if id not in already_have:\n",
+    "            detail = GRAMMAR_ID2INFO[id]\n",
+    "            prompt += f\"{CHOICE_LABELS[i]}. {detail['grammar_name']}: \\n{detail['way_to_use_zh']}\\n\\n\"\n",
+    "            already_have.append(id)\n",
+    "    return prompt[:-1]\n",
+    "\n",
+    "\n",
+    "def gen_reading_test_prompt(\n",
+    "    pre_text: str,\n",
+    "    tocfl_level: str,\n",
+    "    style: str,\n",
+    ") -> str:\n",
+    "    \"\"\"\n",
+    "    閱讀測驗生成 prompt 產生器\n",
+    "    \"\"\"\n",
+    "    \n",
+    "    level_map = {\"入門基礎\":\"A-入門基礎\", \"進階高階\":\"B-進階高階\", \"流利精通\":\"C-流利精通\"}\n",
+    "    level = level_map[tocfl_level]\n",
+    "    level_config = READING_LEVEL_CONFIG[level]\n",
+    "    system_prompt = level_config[\"system_prompt\"]\n",
+    "    definition_prompt = level_config[\"definition_prompt\"]\n",
+    "    asking_prompt_templates = level_config[\"asking_prompt_templates\"]\n",
+    "    reference_asking_prompt_template = level_config[\"reference_asking_prompt_template\"]\n",
+    "    topic_classes = level_config[\"topic_classes\"]\n",
+    "    style_distribution = level_config[\"style_distribution\"]\n",
+    "    #conversation_distribution = level_config[\"conversation_distribution\"]\n",
+    "    question_type_distribution = level_config[\"question_type_distribution\"]\n",
+    "    json_schema = level_config[\"json_schema\"]\n",
+    "    prompt = system_prompt + \"\\n\"\n",
+    "    \n",
+    "    question_type = None\n",
+    "    # --- 抽 topic（等機率） ---\n",
+    "    topic_class = random.choice(topic_classes)\n",
+    "\n",
+    "    # --- 按機率抽 style ---\n",
+    "    #styles, style_probs = zip(*style_distribution.items())\n",
+    "    #style = random.choices(styles, weights=style_probs, k=1)[0]\n",
+    "\n",
+    "    #conversation_types, conversation_types = zip(*conversation_distribution.items())\n",
+    "    #conversation = random.choices(conversation_types, weights=conversation_types, k=1)[0]\n",
+    "    #if conversation == \"含對話\":\n",
+    "    #    style = style + (\"(含對話)\")\n",
+    "    #else:\n",
+    "    #    style = style + (\"(純敘述)\")\n",
+    "    \n",
+    "    # --- 按機率抽 question_type ---\n",
+    "    if question_type_distribution is not None:\n",
+    "        qtypes, q_probs = zip(*question_type_distribution.items())\n",
+    "        question_type = random.choices(qtypes, weights=q_probs, k=1)[0]\n",
+    "    if question_type:\n",
+    "        reference_asking_prompt = reference_asking_prompt_template.safe_substitute(style=style, question_type=question_type, content=pre_text)\n",
+    "    else:\n",
+    "        reference_asking_prompt = reference_asking_prompt_template.safe_substitute(style=style, content=pre_text)\n",
+    "    response_rule = \"【json_schema 輸出格式】\"+\"\\n\"+ str(json_schema)\n",
+    "    return prompt+definition_prompt+reference_asking_prompt+\"\\n\\n\"+response_rule\n",
+    "\n",
+    "def gen_cloze_prompts(\n",
+    "    pre_text: str,\n",
+    "    tocfl_level: str,\n",
+    ") -> str:\n",
+    "    \"\"\"\n",
+    "    選詞填空生成 prompt 產生器\n",
+    "    \"\"\"\n",
+    "    level_map = {\"入門基礎\":\"A-入門基礎\", \"進階高階\":\"B-進階高階\", \"流利精通\":\"C-流利精通\"}\n",
+    "    level = level_map[tocfl_level]\n",
+    "    level_config = CLOZE_LEVEL_CONFIG[level]\n",
+    "    word_list = level_config[\"word_list\"]\n",
+    "    grammar_list = level_config[\"grammar_list\"]\n",
+    "    all_patterns = level_config[\"all_patterns\"]\n",
+    "    examples = level_config[\"examples\"]\n",
+    "    system_prompt = level_config[\"system_prompt\"]\n",
+    "    prompt_definition_template = level_config[\"prompt_definition_template\"]\n",
+    "    asking_prompt_1 = level_config[\"asking_prompt_1\"]\n",
+    "    reference_asking_prompt_1_template = level_config[\"reference_asking_prompt_1_template\"]\n",
+    "    perference_prompts = level_config[\"perference_prompts\"]\n",
+    "    asking_prompt_2_template = level_config[\"asking_prompt_2_template\"]\n",
+    "    json_schema = level_config[\"json_schema\"]\n",
+    "\n",
+    "    word_text = \"、\".join(random.sample(word_list, min(30, len(word_list))))\n",
+    "    grammar_text = \"、\".join(random.sample(grammar_list, min(10, len(grammar_list))))\n",
+    "    pattern_text = \"、\".join(random.sample(all_patterns, min(9, len(all_patterns))))\n",
+    "    prompt_definition = prompt_definition_template.safe_substitute(level_word_list=word_text, level_grammar_list=grammar_text, level_pattern_list=pattern_text, level_examples=examples)\n",
+    "    pre_text_prompt = \"【前置課文】\" + \"\\n\" + pre_text\n",
+    "    asking_prompt = \"請思考讀者學習完【前置課文】後的克漏字填空出題方向，其中克漏字填空裡的[完整文章]是【前置課文】的延伸，兩者需保持一定的相關性，但不需重複。請先根據【要求】的規範生成不帶任何空格的[完整文章]。\"\n",
+    "    chat_prompt1 = system_prompt + \"\\n\" + prompt_definition + pre_text_prompt + '\\n' + asking_prompt\n",
+    "    chat_prompt2 = asking_prompt_2_template.safe_substitute(level_preference1=perference_prompts[0], level_preference2=perference_prompts[1], patterns_text=pattern_text)\n",
+    "    return chat_prompt1, chat_prompt2\n",
+    "    "
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "cd6eda82",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# =========================\n",
+    "# 2. Gradio UI 定義\n",
+    "# =========================\n",
+    "\n",
+    "TBCL_LEVELS = [\"第一級\", \"第二級\", \"第三級\", \"第四級\", \"第五級\", \"第六級\"]\n",
+    "TOCFL_LEVELS = [\"入門基礎\", \"進階高階\", \"流利精通\"]\n",
+    "ARTICLE_STYLES = [\"記敘文\", \"議論文\", \"説明文\", \"抒情文\"]\n",
+    "ARTICLE_TYPES = [\"短文\", \"對話\"]\n",
+    "MAIN_TOPICS = list(subtopic_map.keys())  # 從 subtopic_map 取得主題列表\n",
+    "NEED_FIX_STATUS = [\"生成題目TOCFL等級過高\", \"生成題目TOCFL等級過低\", \"生成題目品質不過關\"]\n",
+    "\n",
+    "\n",
+    "with gr.Blocks(title=\"教育任務 Prompt 產生器\") as demo:\n",
+    "    gr.Markdown(\"# 🧩 教育任務 Prompt 產生器\")\n",
+    "\n",
+    "    with gr.Tab(\"課文生成\"):\n",
+    "        tbcl_level_in = gr.Dropdown(\n",
+    "            choices=TBCL_LEVELS,\n",
+    "            value=\"第一級\",\n",
+    "            label=\"TBCL 等級\",\n",
+    "        )\n",
+    "        main_topic_in = gr.Dropdown(\n",
+    "            choices=MAIN_TOPICS,\n",
+    "            value=MAIN_TOPICS[0],\n",
+    "            label=\"主題\",\n",
+    "        )\n",
+    "        sub_topic_in = gr.Dropdown(\n",
+    "            choices=[],\n",
+    "            value=None,\n",
+    "            label=\"副主題（選填）\",\n",
+    "            interactive=True,\n",
+    "        )\n",
+    "        extra_content_in = gr.Textbox(\n",
+    "            lines=5,\n",
+    "            label=\"額外內容\",\n",
+    "            placeholder=\"可填寫想加入的設定、情境說明等（選填）\",\n",
+    "        )\n",
+    "        article_type_in = gr.Dropdown(\n",
+    "            choices=ARTICLE_TYPES,\n",
+    "            value=\"短文\",\n",
+    "            label=\"文章類型\",\n",
+    "        )\n",
+    "\n",
+    "        gen_button_1 = gr.Button(\"產生課文生成 Prompt\")\n",
+    "        output_1 = gr.Textbox(\n",
+    "            lines=10,\n",
+    "            label=\"課文生成 Prompt（string）\",\n",
+    "        )\n",
+    "\n",
+    "        def _update_subtopics(main_topic):\n",
+    "            \"\"\"當主題改變時，更新副主題選項\"\"\"\n",
+    "            if main_topic in subtopic_map:\n",
+    "                subtopics = subtopic_map[main_topic]\n",
+    "                return gr.Dropdown(choices=subtopics, value=None)\n",
+    "            return gr.Dropdown(choices=[], value=None)\n",
+    "\n",
+    "        def _on_gen_textbook(tbcl_level, main_topic, sub_topic, extra_content, article_type):\n",
+    "            return gen_textbook_prompt(\n",
+    "                tbcl_level=tbcl_level,\n",
+    "                main_topic=main_topic,\n",
+    "                sub_topic=sub_topic,\n",
+    "                extra_content=extra_content,\n",
+    "                article_type=article_type,\n",
+    "            )\n",
+    "\n",
+    "        # 當主題改變時，更新副主題選項\n",
+    "        main_topic_in.change(\n",
+    "            _update_subtopics,\n",
+    "            inputs=[main_topic_in],\n",
+    "            outputs=[sub_topic_in],\n",
+    "        )\n",
+    "\n",
+    "        gen_button_1.click(\n",
+    "            _on_gen_textbook,\n",
+    "            inputs=[tbcl_level_in, main_topic_in, sub_topic_in, extra_content_in, article_type_in],\n",
+    "            outputs=output_1,\n",
+    "        )\n",
+    "\n",
+    "    with gr.Tab(\"詞意消歧\"):\n",
+    "        sentence_in = gr.Textbox(\n",
+    "            lines=5,\n",
+    "            label=\"句子\",\n",
+    "            placeholder=\"請輸入包含目標詞彙的完整句子\",\n",
+    "        )\n",
+    "        target_word_in = gr.Textbox(\n",
+    "            lines=1,\n",
+    "            label=\"詞彙\",\n",
+    "            placeholder=\"請輸入要進行詞意消歧的詞彙\",\n",
+    "        )\n",
+    "\n",
+    "        gen_button_2 = gr.Button(\"產生詞意消歧 Prompt\")\n",
+    "        output_2 = gr.Textbox(\n",
+    "            lines=8,\n",
+    "            label=\"詞意消歧 Prompt（string）\",\n",
+    "        )\n",
+    "        target_choice_in = gr.Textbox(\n",
+    "            lines=1,\n",
+    "            label=\"選項\",\n",
+    "            placeholder=\"請輸入正確的選項\",\n",
+    "        )\n",
+    "        gen_button_2_2 = gr.Button(\"產生詞彙釋義相關資訊\")\n",
+    "        output_3 = gr.Textbox(\n",
+    "            lines=10,\n",
+    "            label=\"詞彙釋義資訊\",\n",
+    "        )\n",
+    "\n",
+    "        def _on_gen_word_sense(sentence, target_word):\n",
+    "            return gen_word_sense_prompt(sentence=sentence, target_word=target_word)\n",
+    "\n",
+    "        gen_button_2.click(\n",
+    "            _on_gen_word_sense,\n",
+    "            inputs=[sentence_in, target_word_in],\n",
+    "            outputs=output_2,\n",
+    "        )\n",
+    "\n",
+    "        def _on_gen_word_info(sentence, target_word, target_choice):\n",
+    "            return gen_word_info(sentence=sentence, target_word=target_word,  target_choice=target_choice)\n",
+    "\n",
+    "        gen_button_2_2.click(\n",
+    "            _on_gen_word_info,\n",
+    "            inputs=[sentence_in, target_word_in, target_choice_in],\n",
+    "            outputs=output_3,\n",
+    "        )\n",
+    "\n",
+    "    with gr.Tab(\"課文語法分析\"):\n",
+    "        textbook_in = gr.Textbox(\n",
+    "            lines=10,\n",
+    "            label=\"課文\",\n",
+    "            placeholder=\"請貼上完整課文內容\",\n",
+    "        )\n",
+    "\n",
+    "        gen_button_3 = gr.Button(\"產生課文語法分析 Prompt\")\n",
+    "        output_3 = gr.Textbox(\n",
+    "            lines=8,\n",
+    "            label=\"課文語法分析 Prompt（string）\",\n",
+    "        )\n",
+    "\n",
+    "        def _on_gen_grammar(textbook):\n",
+    "            return gen_grammar_analysis_prompt(textbook=textbook)\n",
+    "\n",
+    "        gen_button_3.click(\n",
+    "            _on_gen_grammar,\n",
+    "            inputs=[textbook_in],\n",
+    "            outputs=output_3,\n",
+    "        )\n",
+    "\n",
+    "    with gr.Tab(\"閱讀測驗生成\"):\n",
+    "        pre_text_in = gr.Textbox(\n",
+    "            lines=10,\n",
+    "            label=\"前置課文\",\n",
+    "            placeholder=\"請貼上作為閱讀測驗基礎的課文\",\n",
+    "        )\n",
+    "        tocfl_level_in_1 = gr.Dropdown(\n",
+    "            choices=TOCFL_LEVELS,\n",
+    "            value=\"入門基礎\",\n",
+    "            label=\"TOCFL 等級\",\n",
+    "        )\n",
+    "        article_style_in = gr.Dropdown(\n",
+    "            choices=ARTICLE_STYLES,\n",
+    "            value=\"記敘文\",\n",
+    "            label=\"題目文章文體\",\n",
+    "        )\n",
+    "\n",
+    "        gen_button_4 = gr.Button(\"產生閱讀測驗 Prompt\")\n",
+    "        output_4 = gr.Textbox(\n",
+    "            lines=8,\n",
+    "            label=\"閱讀測驗生成 Prompt（string）\",\n",
+    "        )\n",
+    "\n",
+    "        judgement_level_status_in = gr.Dropdown(\n",
+    "            choices=NEED_FIX_STATUS,\n",
+    "            value=\"題目等級過高\",\n",
+    "            label=\"遇到需要修正的評估結果\",\n",
+    "        )\n",
+    "\n",
+    "        gen_button_4_2 = gr.Button(\"產生修正等級的 Prompt\")\n",
+    "        output_4_2 = gr.Textbox(\n",
+    "            lines=1,\n",
+    "            label=\"修正Prompt生成\",\n",
+    "        )\n",
+    "\n",
+    "        def _on_gen_reading_test(pre_text, tocfl_level, style):\n",
+    "            return gen_reading_test_prompt(\n",
+    "                pre_text=pre_text,\n",
+    "                tocfl_level=tocfl_level,\n",
+    "                style=style,\n",
+    "            )\n",
+    "\n",
+    "        gen_button_4.click(\n",
+    "            _on_gen_reading_test,\n",
+    "            inputs=[pre_text_in, tocfl_level_in_1, article_style_in],\n",
+    "            outputs=output_4,\n",
+    "        )\n",
+    "        gr.Markdown(\"## 品質評估用的prompt_1\\n\" + READING_JUDGE_PROMPTS.system + \"\\n\\n[待評估之課文]\")\n",
+    "        gr.Markdown(\"## 品質評估用的prompt_2\\n\" + READING_JUDGE_PROMPTS.additional_check)\n",
+    "        gr.Markdown(\"## 品質評估用的prompt_3 (格式化輸出)\\n\" +\"【json_schema 輸出格式】\\n\\n\"+ str(READING_JUDGE_PROMPTS.json_schema))\n",
+    "        \n",
+    "        def _on_gen_reading_test(judgement_level_status):\n",
+    "            if judgement_level_status == \"生成題目TOCFL等級過高\":\n",
+    "                return FIX_HIGH_LEVEL_PROMPT\n",
+    "            elif judgement_level_status == \"生成題目TOCFL等級過低\":\n",
+    "                return FIX_LOW_LEVEL_PROMPT\n",
+    "            elif judgement_level_status == \"生成題目品質不過關\":\n",
+    "                return FIX_PREFERENCE_PROMPT\n",
+    "        \n",
+    "        gen_button_4_2.click(\n",
+    "            _on_gen_reading_test,\n",
+    "            inputs=[judgement_level_status_in],\n",
+    "            outputs=output_4_2,\n",
+    "        )\n",
+    "\n",
+    "    with gr.Tab(\"選詞填空生成\"):\n",
+    "        pre_text_in_2 = gr.Textbox(\n",
+    "            lines=10,\n",
+    "            label=\"前置課文\",\n",
+    "            placeholder=\"請貼上作為選詞填空基礎的課文\",\n",
+    "        )\n",
+    "        tocfl_level_in_2 = gr.Dropdown(\n",
+    "            choices=TOCFL_LEVELS[1:],\n",
+    "            value=\"進階高階\",\n",
+    "            label=\"TOCFL 等級\",\n",
+    "        )\n",
+    "\n",
+    "        gen_button_5 = gr.Button(\"產生完整文章生成 Prompt\")\n",
+    "        output_5 = gr.Textbox(\n",
+    "            lines=8,\n",
+    "            label=\"選詞填空完整文章生成 Prompt（string）\",\n",
+    "        )\n",
+    "        \n",
+    "        gen_button_5_2 = gr.Button(\"產生選詞填空出題 Prompt\")\n",
+    "        output_5_2 = gr.Textbox(\n",
+    "            lines=8,\n",
+    "            label=\"選詞填空題目生成 Prompt（string）\",\n",
+    "        )\n",
+    "        gr.Markdown(\"## 品質評估用的prompt_1\\n\" + CLOZE_JUDGE_PROMPTS.system + \"\\n\\n[待評估之課文]\")\n",
+    "        gr.Markdown(\"## 品質評估用的prompt_2\\n\" + CLOZE_JUDGE_PROMPTS.additional_check)\n",
+    "        gr.Markdown(\"## 品質評估用的prompt_3 (格式化輸出)\\n\" +\"【json_schema 輸出格式】\\n\\n\"+ str(CLOZE_JUDGE_PROMPTS.json_schema))\n",
+    "\n",
+    "        def _on_gen_cloze_complete_text(pre_text, tocfl_level):\n",
+    "            return gen_cloze_prompts(\n",
+    "                pre_text=pre_text,\n",
+    "                tocfl_level=tocfl_level,\n",
+    "            )[0]\n",
+    "\n",
+    "        gen_button_5.click(\n",
+    "            _on_gen_cloze_complete_text,\n",
+    "            inputs=[pre_text_in_2, tocfl_level_in_2],\n",
+    "            outputs=output_5,\n",
+    "        )\n",
+    "        \n",
+    "        def _on_gen_cloze_text(pre_text, tocfl_level):\n",
+    "            return gen_cloze_prompts(\n",
+    "                pre_text=pre_text,\n",
+    "                tocfl_level=tocfl_level,\n",
+    "            )[1]\n",
+    "\n",
+    "        gen_button_5.click(\n",
+    "            _on_gen_cloze_text,\n",
+    "            inputs=[pre_text_in_2, tocfl_level_in_2],\n",
+    "            outputs=output_5_2,\n",
+    "        )"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "id": "04ca8272",
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Running on local URL:  http://127.0.0.1:7860\n",
+      "IMPORTANT: You are using gradio version 3.41.2, however version 4.44.1 is available, please upgrade.\n",
+      "--------\n",
+      "\n",
+      "Could not create share link. Please check your internet connection or our status page: https://status.gradio.app.\n"
+     ]
+    },
+    {
+     "data": {
+      "text/html": [
+       "<div><iframe src=\"http://127.0.0.1:7860/\" width=\"100%\" height=\"500\" allow=\"autoplay; camera; microphone; clipboard-read; clipboard-write;\" frameborder=\"0\" allowfullscreen></iframe></div>"
+      ],
+      "text/plain": [
+       "<IPython.core.display.HTML object>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "# 直接執行：python this_file.py 後 demo.launch()\n",
+    "if __name__ == \"__main__\":\n",
+    "    demo.launch(share=True)\n",
+    "    #demo.launch(share=True)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "id": "8f3b4413",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "WORD_LIST_COLUMN_NAMES = [\"繁體中文\", \"TBCL等級\", \"注音\", \"漢語拼音\", \"詞性\", \"英文翻譯\", \"例句\", \"例句漢語拼音\", \"例句翻譯\", \"位置\", \"釋義\", \"釋義ID\"]\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "73d4d38b",
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python (study_prompt)",
+   "language": "python",
+   "name": "study_prompt"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.19"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}

dataset/MOE_word2explanations_8.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fefe39650697542809f27992c2a41f24c6d8969c7337edc37b21b0e865e6b7ca
+size 21537358

dataset/TMLD_word2explanations_3.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c28ac7148e35ca173ad415c9395963443d6cae2c3913c8d34f4201bbd40e791a
+size 3092273

dataset/cloze_exampleB.txt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d0218024f0f1ac12c09bce0222680390584e3444f89a9c1d19e950a43942ba41
+size 7526

dataset/cloze_exampleC.txt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6981c03016abd3a125e788f61c2ab374b62a84900f3c7160676e430f5cd2821b
+size 8146

dataset/grammars.jsonl

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4098c0cd08e469eda96b1ac06e59ed9c7e9dc5de2459267a9cec0bd6ebe396b5
+size 479986

dataset/sentencepattern.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7c4082daa6c1d27758e2f665bb1c4a88c1c6da632933bdbcbc3c65356979b33a
+size 3819

dataset/subtopic_map20251002v2.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c6f168c516543b721782a136c7fd0571a21f166fd09cce45690133954138ca40
+size 10921

dataset/word2TBCL.json

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a46c135ce1590659694dc135eed3d957daaca9032e8d9f696e46523982de7e71
+size 295094

fileio/jsonio.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+import io
+import json
+import os
+import gzip
+import tempfile
+from pathlib import Path
+from typing import Any, Iterable, Iterator, Union, Optional, overload, List, Dict
+
+PathLike = Union[str, Path]
+
+class FileIOError(Exception):
+    """基底例外：涵蓋讀寫與解析錯誤。"""
+
+class JSONDecodeError(FileIOError):
+    """JSON 解析失敗。"""
+
+class AtomicWriter:
+    """
+    以原子方式寫檔：先寫到同目錄暫存檔，再 os.replace()。
+    可搭配 gzip_mode=True 自動用 gzip 包裝。
+    """
+    def __init__(self, target: Path, gzip_mode: bool = False, encoding: str = "utf-8", newline: str = "\n"):
+        self.target = target
+        self.dir = target.parent
+        self.encoding = encoding
+        self.newline = newline
+        self.gzip_mode = gzip_mode
+        self._tmp_path: Optional[Path] = None
+        self._fh: Optional[io.TextIOBase] = None
+
+    def __enter__(self) -> io.TextIOBase:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(prefix=f".{self.target.name}.", dir=str(self.dir))
+        os.close(fd)  # 我們會用高階 file object 重新開
+        self._tmp_path = Path(tmp_name)
+
+        if self.gzip_mode:
+            f = gzip.open(self._tmp_path, mode="wt", encoding=self.encoding, newline=self.newline)
+        else:
+            f = open(self._tmp_path, mode="w", encoding=self.encoding, newline=self.newline)
+        self._fh = f
+        return f
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._fh:
+            self._fh.close()
+        if exc_type is None:
+            assert self._tmp_path is not None
+            os.replace(self._tmp_path, self.target)
+        else:
+            # 發生錯誤就清掉暫存檔
+            if self._tmp_path and self._tmp_path.exists():
+                try:
+                    self._tmp_path.unlink()
+                except Exception:
+                    pass  # 忽略清理失敗
+
+def _open_read(path: Path, encoding: str = "utf-8") -> io.TextIOBase:
+    if path.suffix == ".gz":
+        return gzip.open(path, mode="rt", encoding=encoding)
+    return open(path, mode="r", encoding=encoding)
+
+def _needs_gzip(path: Path) -> bool:
+    return path.suffix == ".gz"
+
+class JsonIO:
+    """
+    JSON 單檔存取。
+    - 保留中文 ensure_ascii=False
+    - 預設縮排 indent=2（可改）
+    - 自動支援 .gz 讀/寫
+    """
+    def __init__(self, path: PathLike, encoding: str = "utf-8"):
+        self.path = Path(path)
+        self.encoding = encoding
+
+    def load(self) -> Any:
+        try:
+            with _open_read(self.path, encoding=self.encoding) as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            raise JSONDecodeError(f"JSON decode failed at {self.path}: {e}") from e
+        except Exception as e:
+            raise FileIOError(f"Failed to read {self.path}: {e}") from e
+
+    def save(self, obj: Any, indent: int = 2, ensure_ascii: bool = False) -> None:
+        gzip_mode = _needs_gzip(self.path)
+        try:
+            with AtomicWriter(self.path, gzip_mode=gzip_mode, encoding=self.encoding) as f:
+                json.dump(obj, f, ensure_ascii=ensure_ascii, indent=indent)
+                f.write("\n")
+        except Exception as e:
+            raise FileIOError(f"Failed to write {self.path}: {e}") from e
+
+class JsonlIO:
+    """
+    JSONL（NDJSON）逐行存取。
+    - 迭代讀（省記憶體）
+    - 覆寫寫入（原子）
+    - append 寫入
+    - 自動支援 .gz
+    """
+    def __init__(self, path: PathLike, encoding: str = "utf-8"):
+        self.path = Path(path)
+        self.encoding = encoding
+
+    def iter_load(self) -> Iterator[Dict[str, Any]]:
+        """逐行解析，遇到空白行自動略過。"""
+        try:
+            with _open_read(self.path, encoding=self.encoding) as f:
+                for i, line in enumerate(f, start=1):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        yield json.loads(line)
+                    except json.JSONDecodeError as e:
+                        raise JSONDecodeError(f"JSONL decode failed at line {i} in {self.path}: {e}") from e
+        except Exception as e:
+            raise FileIOError(f"Failed to read {self.path}: {e}") from e
+
+    def load_all(self) -> List[Dict[str, Any]]:
+        """一次載入全部（小檔方便用）。"""
+        return list(self.iter_load())
+
+    def save_all(self, rows: Iterable[Dict[str, Any]], ensure_ascii: bool = False) -> None:
+        """覆寫寫入（原子）。"""
+        gzip_mode = _needs_gzip(self.path)
+        try:
+            with AtomicWriter(self.path, gzip_mode=gzip_mode, encoding=self.encoding) as f:
+                for row in rows:
+                    f.write(json.dumps(row, ensure_ascii=ensure_ascii))
+                    f.write("\n")
+        except Exception as e:
+            raise FileIOError(f"Failed to write {self.path}: {e}") from e
+
+    def append(self, rows: Iterable[Dict[str, Any]], ensure_ascii: bool = False) -> None:
+        """附加寫入（非原子；適合持續追加的 log 類資料）。"""
+        try:
+            if _needs_gzip(self.path):
+                # gzip 不支援原地 append 的隨機存取，這裡採「串流追加」
+                with gzip.open(self.path, mode="at", encoding=self.encoding, newline="\n") as f:
+                    for row in rows:
+                        f.write(json.dumps(row, ensure_ascii=ensure_ascii))
+                        f.write("\n")
+            else:
+                self.path.parent.mkdir(parents=True, exist_ok=True)
+                with open(self.path, mode="a", encoding=self.encoding, newline="\n") as f:
+                    for row in rows:
+                        f.write(json.dumps(row, ensure_ascii=ensure_ascii))
+                        f.write("\n")
+        except Exception as e:
+            raise FileIOError(f"Failed to append {self.path}: {e}") from e

requirements.txt

@@ -0,0 +1,29 @@
+# Gradio UI
+gradio==6.2.0
+
+# Sentence Dealer and dependencies
+# Install sentence_dealer package first: pip install -e util/sentence_dealer
+# Or uncomment below to install dependencies directly:
+
+# CKIP and NLP
+ckiptagger==0.2.1
+OpenCC==1.1.9
+deep-translator==1.11.4
+
+# TensorFlow and ML
+tensorflow==2.15.0
+keras==2.15.0
+numpy==1.26.4
+pandas==2.2.3
+
+# Hugging Face
+huggingface_hub==1.2.3
+
+# OpenAI / Azure OpenAI
+openai==2.14.0
+
+# Utilities
+requests==2.32.3
+tqdm==4.66.6
+typing-extensions==4.15.0
+

util/cloze_constants.py

@@ -0,0 +1,253 @@
+import json
+from string import Template
+from types import MappingProxyType
+def load_text(text_path:str, strip=True):
+    text_str = ""
+    with open(text_path, "r", encoding="utf-8") as f:
+        text_str = f.read()
+        if strip: text_str = text_str.strip()
+    return text_str
+
+def load_json(json_path:str):
+    data_list = []
+    with open(json_path, "r", encoding="utf-8") as f:
+        data_list = json.load(f)
+    return data_list
+    
+def load_jsonl(jsonl_path:str, chinese_only=False):
+    data_list = []
+    with open(jsonl_path, "r", encoding="utf-8") as f:
+        for line in f:
+            item = json.loads(line)
+            if chinese_only:
+                # 僅保留中文語法名稱
+                if all('\u4e00' <= ch <= '\u9fff' or ch == '.' for ch in item["grammar_name"]):
+                    data_list.append(item)
+            else: data_list.append(item)
+    return data_list
+
+example_B_path = "./dataset/cloze_exampleB.txt"
+example_C_path = "./dataset/cloze_exampleC.txt"
+word_definition_path = "./dataset/word2TBCL.json"
+grammars_path = "./dataset/grammars.jsonl"
+patterns_path = "./dataset/sentencepattern.json"
+
+example_B = load_text(example_B_path)
+example_C = load_text(example_C_path)
+word2TBCL = load_json(word_definition_path)
+grammar_json = load_jsonl(grammars_path, chinese_only=True)
+pattern_json = load_json(patterns_path)
+
+SYSTEM_PROMPT = "你是一位在台灣從事國文教育多年有趣的華語老師，這次負責出克漏字填空(cloze)的題目。"
+CLOZE_TASK_DEFINITION = "每個克漏字填空由[完整文章]、[挖空後的文章]和[題目]所組成。[完整文章]由一連串文字組成，與學校的課文相似；[挖空後的文章]由[完整文章]挖空後取得，空格由底線+數字組成，像是(__1__, __2__, ...)或是(__1__⋯⋯__1__, __2__⋯⋯__2__, ...)；[題目]為單選題，共6題，選項為空格內可能可以填入的詞彙或片語，有(A)、(B)、(C)、(D)四個選項供選擇。"
+CLOZE_PROMPT_DEFINITION_TEMPLATE = Template("""【題型說明】
+%s
+【參考資料】
+[詞彙清單]: ${level_word_list}
+[語法結構清單]: ${level_grammar_list}
+[句型結構清單]: ${level_pattern_list}
+
+【要求】
+文章長度150～300字，語言難度相當於國中水準，可出現書面詞、抽象概念，難度盡量與後續的【範例】保持一致。
+生成[完整文章]時必須使用3 個[詞彙清單]中的詞彙，需自然嵌入文章中。
+生成[完整文章]時必須使用1~2 個[語法結構清單]中的語法結構，需自然嵌入文章中。
+生成[完整文章]時必須使用1~2 種[句型結構清單]中的句型結構，需自然嵌入文章中。
+預期讀者為學習繁體中文的外國成年人，可以以較為國際化或本土化的文章內容出題。
+為確保題目的多樣性，挖空位置可使用不同詞性（名詞、動詞、形容詞、副詞等）。
+[完整文章]不可出現「.」或「_」這兩種字元。
+                                                                                               
+【範例】
+${level_examples}
+
+                                            
+""" %(CLOZE_TASK_DEFINITION)) 
+"""
+【克漏字填空生產流程】
+1. 閱讀完【題型說明】、【參考資料】、【要求】、【範例】裡的內容，依據【要求】裡生成文章的規範生成沒有空格的[完整文章]。
+2. 參考【參考資料】、【要求】、【範例】裡的資訊，尋找[完整文章]裡適合挖空的位置，必需挖出6個題目的位置，每個位址以__1__, __2__, ...來表示，若挖空位址並非詞彙則以__1__⋯⋯__1__, __2__⋯⋯__2__, ...來表示，其中⋯⋯為[完整文章]裡的部分內容，此階段之結果為[挖空後的文章]。
+3. 參考[完整文章]、[挖空後的文章]、【參考資料】、【要求】、【範例】裡的資訊，設計6題具多樣性及誘答性的題目。
+4. 確認[完整文章]內容自然通順且不含簡體字，確認每題題目只有一個正確答案。
+"""
+level_B_perferences = ["","「挖空位置」偏好選擇日常生活情境相關的詞彙或語法點（如家庭、購物、交通、學習、健康、寵物等），挖空重點放在 「基礎語法、常用詞搭配、生活詞彙」。"]
+level_C_perferences = ["(可出現成語)","「挖空位置」偏好選擇較正式或書面化的文章，挖空重點放在 「成語、書面連接詞、文學修辭、抽象概念詞」，以檢測高階語感與閱讀理解。"]
+ASKING_PROMPT_2_TEMPLATE = Template("""請閱讀上述的[完整文章]，依照下列規範設計填空題，讓題組中同時包含詞彙題與語法題（每題為一個詞彙或一組語法結構、副詞、固定詞組或片語填空）:
+【要求】
+	[完整文章]請務必完全保留原文，不需任何空格、_、⋯。  
+  [挖空後的文章]必需挖出6個選擇題填空對應的位置，每個位置以__1__, __2__, ..., __6__來表示，若挖空位址並非詞彙則以__1__⋯⋯__1__, __2__���⋯__2__, ..., __6__⋯⋯__6__來表示，其中⋯⋯為[完整文章]裡的部分內容
+	[挖空後的文章]除挖空位置外不得新增、刪減、替換或改寫任何[完整文章]裡的內容，必須與原文一字不差。
+  「⋯⋯」僅允許作為選項中的示意，不計入字數；[完整文章]、[挖空後的文章]皆不得出現「⋯⋯」。
+	挖空位置是題目的正確答案，其必須完整取自[完整文章]，不能創造[完整文章]中不存在的詞彙或語法結構。
+	請從原文中選出六個適合挖空的位置，其中可分為:
+  	詞彙${level_preference1}
+  	副詞搭配
+  	虛詞
+    量詞
+    語法結構（如複句）
+    固定詞組或片語
+  ${level_preference2}
+  「挖空位置」禁止挖空專有名詞（如人名、地名、組織名）、數字（如「三」「五」）或其他不適合設計選項的詞彙。
+
+【挖空標記】
+	將被選的詞彙／連詞／副詞／片語在原文中「就地」替換為 __1__、__2__…。
+  - 複句連詞採「雙空同號」：同一題出現兩次相同標記（如：__1__⋯⋯__1__⋯⋯）。
+  - 除被替換的目標詞外，[完整文章]其他內容不得增刪或改寫（包含標點與空白）。
+ 
+【複句連詞對挖空規則】
+  定義: [複句連詞對]是由兩個(以上)句子依特定語法關係組合而成，類似於國文課中照樣造句的形式。
+  複句類型：{patterns_text}
+  連詞對必須來自[完整文章]的實際用詞，一字不差；不可用語義相近或結構相似詞替代。
+  不得將單一詞或固定片語（如「非但如此」「因此」「不過」）誤判為連詞對。若句中沒有真正的連詞對，則不得設計成複句題，請改為詞彙、副詞挖空。
+  「標點不構成阻斷」:逗號、頓號、分號等標點不影響配對，兩部分仍視為同一句內的「連詞對」。
+  挖空時必須同時替換該[複句連詞對]中的兩個詞（雙空同號），不得只替換其中一個。
+  兩個空必須在同一句內；每題恰好出現同號標記兩次（例如：__2__ 與 __2__）。
+  【示例1】
+		- 原句: 「非但氣氛熱烈，而且售票情況也非常理想。」
+    - 正確: 「__3__氣氛熱烈，__3__售票情況也非常理想。」
+    - 錯誤（禁止）: 「__3__⋯⋯__3__⋯⋯售票情況也非常理想。」
+  【示例2】
+    - 原句: 最後他們班不但贏得了比賽，也獲得了老師的讚賞。
+    - 正確: 最後他們班__6__贏得了比賽，__6__獲得了老師的讚賞。
+    - 錯誤（禁止）: 最後他們班__6__贏得了比賽，也獲得了老師的讚賞。（少挖後半）
+
+【選擇題設計】
+  每題需提供四個選項 (A~D)，且只有一個正確答案。
+  正確答案必須取自[完整文章]，與原文一字不差。
+  四個選項的字數盡量一致**（連詞對以「前半+後半」的總字數為準）。
+    - 若為[複句連詞對]，四個選項都必須是[複句連詞對]，刪節號使用「⋯⋯」。
+    - 不得出現單側連詞（如「不如果決」）或「連詞＋詞彙」的混種格式。
+  至少一個錯誤選項必須設計為「誘答選項」（plausible distractor），不可與正解等義或可替代；錯誤選項不得與原文任一詞語完全一致。
+  6題選擇題選項之間，正確答案選項與候選選項必須避免重複或高度近似的詞彙。  
+    - 不得在不同選項中重複出現同義詞（如「十分」「非常」「極度」）。  
+    - 6題[題目]盡量涵蓋不同詞類（動詞、副詞、連詞、名詞、片語([複句連詞對])、量詞），確保多樣性。 
+
+【誘答選項定義與規則】
+  - 定義: 在選擇題或選詞填空題中，除了唯一正確答案之外，其餘錯誤但看似合理的選項，稱為「誘答選項」。
+  - 規則:
+    1. 正確答案只有一個。
+    2. 誘答選項必須是「錯誤答案」，不可與正確答案等義或合理替代。
+    3. 誘答選項應具備迷惑性，常見設計方式：
+        - 語義相反（如「不開心」 vs. 正確答案「開心」）。
+        - 搭配錯誤（詞性或語境不合）。
+        - 同類詞但不符合上下文（如形近詞、同字根詞，但意思放不進去）。
+    4. 不要產生與正確答案意義相近、且同樣合理的詞（例如正解「有趣」，不可出現「有意思」）。
+    5. 錯誤選項必須保證不與原文的任何詞語完全一致。
+
+【克漏字填空生產流程】
+1. 按照【要求】的內容從[完整文章]裡挖出6個挖空位置產出[挖空後的文章]，格式請注意【挖空標記】、【複句連詞對挖空規則】裡的內容。
+2. 將挖空的區域列為之後選擇題的正確答案
+3. 按照【選擇題設計】的內容設計6題具多樣性及誘答性的6題選擇題，誘答性定義請參考【誘答選項定義與規則】，正確答案不藥都是A選項，請平均分配。
+4. 務必確認每題選擇題的每一個選項代入句子中的正確性，每題選擇題正確答案只能有一個，不能有兩個選項帶入句子皆合理的情況。
+                                    
+請根據【克漏字填空生產流程】的內容一步一步生成克漏字填空。
+""")
+
+
+ASKING_PROMPT_1 = "請先根據【要求】的規範生成不帶任何空格的[完整文章]"
+#ASKING_PROMPT = "請根據【克漏字填空生產流程】產出克漏字填空。"
+REFERENCE_ASKING_PROMPT_1_TEMPLATE = Template("""【前置課文資訊】
+[主題] ${topic}
+[副主題] ${subtopic} 
+[前置課文標題] ${title}
+[前置課文內容] ${pre_context}
+請思考讀者學習完【前置課文資訊】後的克漏字填空出題方向，其中克漏字填空裡的[完整文章]是【課文】的延伸，兩者需保持一定的相關性，但不需重複。請先根據【要求】的規範生成不帶任何空格的[完整文章]。
+""")
+
+CLOZE_FIX_PREFERENCE_PROMPT = "請根據上述審核結果，包含之前的簡短說明，及詳細不合格的理由，修改克漏字填空的內容。"
+CLOZE_FIX_HIGH_LEVEL_PROMPT = "文章難度過高，請重新閱讀【要求】、【範例】的內容後，降低閱讀測驗的難度。"
+CLOZE_FIX_LOW_LEVEL_PROMPT = "文章難度過低，請重新閱讀【要求】、【範例】的內容後，增加閱讀測驗的難度。"
+# 請先根據【要求】的規範生成不帶任何空格的「完整文章」。
+
+level2examples = {"B":example_B, "C":example_C}
+level_B_words = [word for word, level in word2TBCL.items() if 4 <= level <= 5]
+level_C_words = [word for word, level in word2TBCL.items() if 6 <= level <= 7]
+level_B_grammars = [g["grammar_name"] for g in grammar_json if 1 <= g["level"] <= 3]
+level_C_grammars = [g["grammar_name"] for g in grammar_json if 4 <= g["level"] <= 5]
+all_patterns = []
+for group in pattern_json["patterns"]:
+  all_patterns.extend(group["patterns"])
+
+CLOZE_SCHEMA = MappingProxyType({
+    "name": "cloze_output",
+    "strict": True,
+    "schema": {
+        "type": "object",
+        "properties": {
+            "完整文章": {
+                "type": "string",
+                "description": "克漏字填空的完整文章，不含任何_或⋯。"
+            },
+            "挖空後的文章": {
+                "type": "string",
+                "description": "克漏字填空挖空後的文章。"
+            },
+            "題目列表": {
+                "type": "array",
+                "description": "本篇文章對應的選擇題列表（1~6題）。",
+                "minItems": 6,
+                "maxItems": 6,
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "題號": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 6,
+                            "description": "說明是哪個挖空位置的選擇題。"
+                        },
+                        "題目句": {
+                            "type": "string",
+                            "description": "挖空後文章的斷句，用來描述此挖空題的準確位置。",
+                            "minLength": 1
+                        },
+                        "A": {"type": "string", "description": "選項 A", "minLength": 1},
+                        "B": {"type": "string", "description": "選項 B", "minLength": 1},
+                        "C": {"type": "string", "description": "選項 C", "minLength": 1},
+                        "D": {"type": "string", "description": "選項 D", "minLength": 1},
+                        "答案": {
+                            "type": "string",
+                            "description": "正確選項。",
+                            "enum": ["A", "B", "C", "D"]
+                        },
+                        "解析": {
+                            "type": "string",
+                            "description": "挖空理由。"
+                        }
+                    },
+                    "required": ["題號", "題目句", "A", "B", "C", "D", "答案", "解析"],
+                    "additionalProperties": False
+                }
+            },
+        },
+        "required": ["完整文章", "挖空後的文章", "題目列表"],
+        "additionalProperties": False
+    }
+})
+
+CLOZE_LEVEL_CONFIG =  {
+    "B-進階高階": {
+    	"word_list":level_B_words,
+    	"grammar_list":level_B_grammars,
+			"all_patterns":all_patterns,
+			"examples":level2examples["B"],
+    	"system_prompt":SYSTEM_PROMPT,
+    	"prompt_definition_template":CLOZE_PROMPT_DEFINITION_TEMPLATE,
+			"asking_prompt_1":ASKING_PROMPT_1,
+      "perference_prompts":level_B_perferences,
+      "asking_prompt_2_template":ASKING_PROMPT_2_TEMPLATE,
+			"reference_asking_prompt_1_template":REFERENCE_ASKING_PROMPT_1_TEMPLATE,
+      "json_schema": CLOZE_SCHEMA
+		},
+    "C-流利精通": {
+    	"word_list":level_C_words,
+    	"grammar_list":level_C_grammars,
+			"all_patterns":all_patterns,
+			"examples":level2examples["C"],
+    	"system_prompt":SYSTEM_PROMPT,
+    	"prompt_definition_template":CLOZE_PROMPT_DEFINITION_TEMPLATE,
+			"asking_prompt_1":ASKING_PROMPT_1,
+      "perference_prompts":level_C_perferences,
+      "asking_prompt_2_template":ASKING_PROMPT_2_TEMPLATE,
+			"reference_asking_prompt_1_template":REFERENCE_ASKING_PROMPT_1_TEMPLATE,
+      "json_schema": CLOZE_SCHEMA
+		}
+}

util/fileio/jsonio.py

@@ -0,0 +1,154 @@
+from __future__ import annotations
+import io
+import json
+import os
+import gzip
+import tempfile
+from pathlib import Path
+from typing import Any, Iterable, Iterator, Union, Optional, overload, List, Dict
+
+PathLike = Union[str, Path]
+
+class FileIOError(Exception):
+    """基底例外：涵蓋讀寫與解析錯誤。"""
+
+class JSONDecodeError(FileIOError):
+    """JSON 解析失敗。"""
+
+class AtomicWriter:
+    """
+    以原子方式寫檔：先寫到同目錄暫存檔，再 os.replace()。
+    可搭配 gzip_mode=True 自動用 gzip 包裝。
+    """
+    def __init__(self, target: Path, gzip_mode: bool = False, encoding: str = "utf-8", newline: str = "\n"):
+        self.target = target
+        self.dir = target.parent
+        self.encoding = encoding
+        self.newline = newline
+        self.gzip_mode = gzip_mode
+        self._tmp_path: Optional[Path] = None
+        self._fh: Optional[io.TextIOBase] = None
+
+    def __enter__(self) -> io.TextIOBase:
+        self.dir.mkdir(parents=True, exist_ok=True)
+        fd, tmp_name = tempfile.mkstemp(prefix=f".{self.target.name}.", dir=str(self.dir))
+        os.close(fd)  # 我們會用高階 file object 重新開
+        self._tmp_path = Path(tmp_name)
+
+        if self.gzip_mode:
+            f = gzip.open(self._tmp_path, mode="wt", encoding=self.encoding, newline=self.newline)
+        else:
+            f = open(self._tmp_path, mode="w", encoding=self.encoding, newline=self.newline)
+        self._fh = f
+        return f
+
+    def __exit__(self, exc_type, exc, tb) -> None:
+        if self._fh:
+            self._fh.close()
+        if exc_type is None:
+            assert self._tmp_path is not None
+            os.replace(self._tmp_path, self.target)
+        else:
+            # 發生錯誤就清掉暫存檔
+            if self._tmp_path and self._tmp_path.exists():
+                try:
+                    self._tmp_path.unlink()
+                except Exception:
+                    pass  # 忽略清理失敗
+
+def _open_read(path: Path, encoding: str = "utf-8") -> io.TextIOBase:
+    if path.suffix == ".gz":
+        return gzip.open(path, mode="rt", encoding=encoding)
+    return open(path, mode="r", encoding=encoding)
+
+def _needs_gzip(path: Path) -> bool:
+    return path.suffix == ".gz"
+
+class JsonIO:
+    """
+    JSON 單檔存取。
+    - 保留中文 ensure_ascii=False
+    - 預設縮排 indent=2（可改）
+    - 自動支援 .gz 讀/寫
+    """
+    def __init__(self, path: PathLike, encoding: str = "utf-8"):
+        self.path = Path(path)
+        self.encoding = encoding
+
+    def load(self) -> Any:
+        try:
+            with _open_read(self.path, encoding=self.encoding) as f:
+                return json.load(f)
+        except json.JSONDecodeError as e:
+            raise JSONDecodeError(f"JSON decode failed at {self.path}: {e}") from e
+        except Exception as e:
+            raise FileIOError(f"Failed to read {self.path}: {e}") from e
+
+    def save(self, obj: Any, indent: int = 2, ensure_ascii: bool = False) -> None:
+        gzip_mode = _needs_gzip(self.path)
+        try:
+            with AtomicWriter(self.path, gzip_mode=gzip_mode, encoding=self.encoding) as f:
+                json.dump(obj, f, ensure_ascii=ensure_ascii, indent=indent)
+                f.write("\n")
+        except Exception as e:
+            raise FileIOError(f"Failed to write {self.path}: {e}") from e
+
+class JsonlIO:
+    """
+    JSONL（NDJSON）逐行存取。
+    - 迭代讀（省記憶體）
+    - 覆寫寫入（原子）
+    - append 寫入
+    - 自動支援 .gz
+    """
+    def __init__(self, path: PathLike, encoding: str = "utf-8"):
+        self.path = Path(path)
+        self.encoding = encoding
+
+    def iter_load(self) -> Iterator[Dict[str, Any]]:
+        """逐行解析，遇到空白行自動略過。"""
+        try:
+            with _open_read(self.path, encoding=self.encoding) as f:
+                for i, line in enumerate(f, start=1):
+                    line = line.strip()
+                    if not line:
+                        continue
+                    try:
+                        yield json.loads(line)
+                    except json.JSONDecodeError as e:
+                        raise JSONDecodeError(f"JSONL decode failed at line {i} in {self.path}: {e}") from e
+        except Exception as e:
+            raise FileIOError(f"Failed to read {self.path}: {e}") from e
+
+    def load_all(self) -> List[Dict[str, Any]]:
+        """一次載入全部（小檔方便用）。"""
+        return list(self.iter_load())
+
+    def save_all(self, rows: Iterable[Dict[str, Any]], ensure_ascii: bool = False) -> None:
+        """覆寫寫入（原子）。"""
+        gzip_mode = _needs_gzip(self.path)
+        try:
+            with AtomicWriter(self.path, gzip_mode=gzip_mode, encoding=self.encoding) as f:
+                for row in rows:
+                    f.write(json.dumps(row, ensure_ascii=ensure_ascii))
+                    f.write("\n")
+        except Exception as e:
+            raise FileIOError(f"Failed to write {self.path}: {e}") from e
+
+    def append(self, rows: Iterable[Dict[str, Any]], ensure_ascii: bool = False) -> None:
+        """附加寫入（非原子；適合持續追加的 log 類資料）。"""
+        try:
+            if _needs_gzip(self.path):
+                # gzip 不支援原地 append 的隨機存取，這裡採「串流追加」
+                with gzip.open(self.path, mode="at", encoding=self.encoding, newline="\n") as f:
+                    for row in rows:
+                        f.write(json.dumps(row, ensure_ascii=ensure_ascii))
+                        f.write("\n")
+            else:
+                self.path.parent.mkdir(parents=True, exist_ok=True)
+                with open(self.path, mode="a", encoding=self.encoding, newline="\n") as f:
+                    for row in rows:
+                        f.write(json.dumps(row, ensure_ascii=ensure_ascii))
+                        f.write("\n")
+        except Exception as e:
+            raise FileIOError(f"Failed to append {self.path}: {e}") from e

util/judgement.py

@@ -0,0 +1,469 @@
+import json, time, re, opencc, math
+# region agent log
+import os as _os, sys as _sys
+def _agent_log(_hypothesisId: str, _location: str, _message: str, _data: dict):
+    try:
+        _p = r"c:\Users\tom1030507\Desktop\Programming\study_prompt_UI\.cursor\debug.log"
+        _payload = {
+            "sessionId": "debug-session",
+            "runId": _os.environ.get("AGENT_RUN_ID", "pre-fix"),
+            "hypothesisId": _hypothesisId,
+            "location": _location,
+            "message": _message,
+            "data": _data,
+            "timestamp": int(time.time() * 1000),
+        }
+        with open(_p, "a", encoding="utf-8") as _f:
+            _f.write(json.dumps(_payload, ensure_ascii=False) + "\n")
+    except Exception:
+        pass
+
+_agent_log(
+    "H_PATH",
+    "util/judgement.py:module_import",
+    "judgement module import start",
+    {
+        "__file__": __file__,
+        "cwd": _os.getcwd(),
+        "sys.executable": _sys.executable,
+        "sys.path_head": _sys.path[:5],
+    },
+)
+# endregion
+#from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Dict, List, Tuple, Optional, Literal
+from openai import AzureOpenAI
+from openai._exceptions import APIError, RateLimitError, APITimeoutError
+from typing import Any, Mapping
+from types import MappingProxyType
+
+# Optional heavy deps (allow importing prompt constants without installing ML stack)
+try:
+    import torch  # type: ignore
+    import torch.nn as nn  # type: ignore
+except ModuleNotFoundError:  # pragma: no cover
+    torch = None  # type: ignore
+    nn = None  # type: ignore
+
+try:
+    from transformers import AutoModel, AutoTokenizer  # type: ignore
+except ModuleNotFoundError:  # pragma: no cover
+    AutoModel = None  # type: ignore
+    AutoTokenizer = None  # type: ignore
+
+# region agent log
+_agent_log(
+    "H_DEPS",
+    "util/judgement.py:optional_deps",
+    "optional deps availability",
+    {
+        "torch_available": torch is not None,
+        "transformers_available": AutoModel is not None and AutoTokenizer is not None,
+    },
+)
+# endregion
+
+# ---------- Utilities ----------
+
+class OpenCCChecker:
+    _cc_s2t = None
+    _cc_s2twp = None
+
+    @classmethod
+    def ensure_init(cls):
+        if cls._cc_s2t is None:
+            cls._cc_s2t = opencc.OpenCC('s2t.json')
+        if cls._cc_s2twp is None:
+            cls._cc_s2twp = opencc.OpenCC('s2twp.json')
+
+    @classmethod
+    def has_simplified(cls, text: str, prefer_general_word_check: bool = False) -> bool:
+        cls.ensure_init()
+        cc = cls._cc_s2twp if prefer_general_word_check else cls._cc_s2t
+        return text != cc.convert(text)
+
+@dataclass(frozen=True, slots=True)
+class PromptSet:
+    system: str
+    additional_check: str
+    json_schema: Mapping[str, Any]
+
+QUALIFICATION_SCHEMA = MappingProxyType({
+    "name": "qualification_check",
+    "strict": True,
+    "schema": {
+        "type": "object",
+        "properties": {
+            "合格/不合格": {
+                "type": "string",
+                "description": "根據歷史紀錄判定結果為『合格』或『不合格』，必須為這兩個之一。",
+                "enum": ["合格", "不合格"]
+            },
+            "簡短說明": {
+                "type": "string",
+                "description": "針對檢查結果簡要說明原因或依據，不得為空。",
+                "minLength": 1
+            }
+        },
+        "required": ["合格/不合格", "簡短說明"],
+        "additionalProperties": False
+    }
+})
+
+READING_JUDGE_PROMPTS = PromptSet(
+    system=(
+        "你是一位專業的華語審題老師，長期負責《閱讀測驗》的審核工作。\n"
+        "請嚴格依據以下【審題標準】進行判斷:\n"
+        "【題目說明】\n"
+        "每個閱讀測驗由「文章」和「題目」所組成，「文章」由一連串文字組成，與學校的課文相似；"
+        "「題目」為選擇題，提出一個問題後給予(A)、(B)、(C)、(D)四個可能的答案供選擇。\n"
+        "【審題標準】\n"
+        "1. 「文章」和「題目」不可以出現簡體字。\n"
+        "2. 「文章」和「題目」中不能出現明顯的負面用語，需要用較為客觀的用詞取代。例如：「奧客」應改為「惡劣的顧客」。若有此情況視為不合格。\n"
+        "3. 「文章」和「題目」語意需清楚，不能出現模稜兩可或不合時宜的病句或詞彙。舉例：「平時我們也常從新聞看到有人因為隨手滑手機而被車撞。」"
+        "應改為「平時我們也常從新聞看到有人因為一邊走路一邊滑手機，而被車撞。」……（略）\n"
+        "4. 每一個「題目」必須且只能有一個標準答案(唯一性)。\n"
+        "5. 「文章」不得有邏輯衝突（身份衝突、視角矛盾等）。"
+    ),
+    additional_check=(
+        "在不考慮「文章」只看「題目」(包含選項)的情況下，確認每一個「題目」裡的每一個選項是否也有很高的機率選出正確答案，只要有一個這種「明顯錯誤」的選項，一律視為「整題不合格」，請嚴格執行此項判斷，以下是一些「選項明顯錯誤」的案例:\n"
+        " 6.1 選項中出現明顯錯誤、負面詞語(如「只有」、「只」、「僅以」)或「過度絕對化」的敘述(如「只會增加困難與挫折」、「認為文學只適合考試使用」)。\n"
+        " 6.2 選項答案長度差異過大，使正確選項顯而易見。\n"
+        " 6.3 選項描述內容高度雷同，使正確答案突出。\n"
+        "  例如：根據文章內容，作者如何總結經濟發展與環境保護之間的關係？\n"
+        "    (A) 經濟發展必然以環境犧牲為代價\n"
+        "    (B) 兩者本質上無法兼容，須取捨其一\n"
+        "    (C) 若結合在地經濟行動與濕地復育，反而有助於生態與地方發展\n"
+        "    (D) 經濟行動與環境保護之間缺乏交集，各自為政"
+    ),
+    json_schema=QUALIFICATION_SCHEMA
+)
+
+CLOZE_JUDGE_PROMPTS = PromptSet(
+    system=(
+        "你是一位專業的華語審題老師，長期負責《填空題》的審核工作。\n"
+        "請嚴格依據以下【審題標準】進行判斷:\n"
+        "【題目說明】\n"
+        "每個填空題由「挖空後的文章」和「題目」所組成:\n"
+        "「挖空後的文章」中的挖空位置以「__(題號)__」或「__(題號)__⋯⋯__(題號)__」表示，像是「__1__」或「__1__⋯⋯__1__」為給題目1的挖空位置，後者為片語形式。;"
+        "「題目」為選擇題，每題對應到一個位置，會有(A)、(B)、(C)、(D)四個詞彙、語法或成語供選擇。\n\n"
+        "【審題標準】\n"
+        "1. 「挖空後的文章」和「題目」不可以出現簡體字。\n"
+        "2. 「挖空後的文章」和「題目」中不能出現明顯的負面用語，需要用較為客觀的用詞取代。例如：「奧客」應改為「惡劣的顧客」。若有此情況視為不合格。\n"
+        "3. 每一個「題目」必須且只能有一個標準答案(唯一性)，因此請確定每一個題目每一個選項代入句子後的合理性，每一題只能有一個選項合理。\n"
+        "4. 挖控的位置是否正確。\n"
+        "請根據上述標準，逐一檢查每一個項目，並提供最終評判。"
+    ),
+    additional_check=(
+        "除了原先的【審題標準】，請逐一檢查連續兩題的答案是否能合併為一個片語，若能合併則此填空題應判定為不合格，舉例來說:\n"
+        "如果「雖然」是第一題的答案，「但是」是第二題的答案，這兩題又在同一句話中出現且可以合併為「雖然⋯⋯但是」，那應該將這兩題合併為第一題，因此此填空題應判定為不合格。"
+    ),
+    json_schema=QUALIFICATION_SCHEMA
+)
+
+PROMPT_REGISTRY: dict[str, PromptSet] = {
+    "reading": READING_JUDGE_PROMPTS,
+    "cloze": CLOZE_JUDGE_PROMPTS,
+}
+
+Mode = Literal["reading", "cloze"]
+
+if nn is not None and AutoModel is not None:
+    class LevelJudgementModel(nn.Module):
+        def __init__(self, model_name: str, num_labels: int = 3):
+            super().__init__()
+            self.bert = AutoModel.from_pretrained(model_name)
+            hidden = self.bert.config.hidden_size  # 不要寫死 1024
+            self.classifier = nn.Linear(hidden, num_labels) #huggingface BertForSequenceClassification 的預設名稱
+            self.save_hyperparams = {"model_name": model_name, "num_labels": num_labels}
+
+        def forward(self, input_ids, attention_mask):
+            """
+            與 huggingface 的 BertForSequenceClassification 略有不同，少了tanh作為activation fuction。
+            """
+            last_hidden = self.bert(input_ids=input_ids, attention_mask=attention_mask)["last_hidden_state"]
+            logits = self.classifier(last_hidden[:, 0, :])  # [CLS] 位置
+            return logits
+else:
+    LevelJudgementModel = None  # type: ignore
+
+class PreprocessTool():
+    question_keys = ["題目1", "題目2", "題目3", "題目4", "題目5", "題目6"]
+    @classmethod
+    def make_reading_prompt(cls, sample_data:dict) -> list:
+        """
+            Minimum required fields for sample_data:
+            ['文章', '題目1', '題目2', '題目3', '題目4', '題目5', '題目6', '通過/不通過']
+        """
+        prompt = "文章:\n" + sample_data["文章"] + "\n\n" + "題目:"+ "\n"
+        for question_key in cls.question_keys:
+            question_str = sample_data[question_key]
+            question_str = re.sub("【.*】\n|[\(（]*(考點類型|事實理解|歸納分析|推論判斷|批判評析).*\n", "", question_str)
+            question_str = re.sub("參考答案: .", "", question_str)
+            prompt = prompt + question_str.strip() + "\n"
+            prompt = prompt.replace("？", "?")
+            prompt = prompt.replace("（", "(")
+            prompt = prompt.replace("）", ")")
+            prompt = prompt.replace(" ", "")
+        return prompt.strip(), sample_data["通過/不通過"]
+    
+    @classmethod
+    def make_cloze_prompt(cls, sample_data:dict) -> list:
+        """
+            Minimum required fields for sample_data:
+            ['挖空後文章', '題目1', '題目2', '題目3', '題目4', '題目5', '題目6', '通過/不通過']
+        """
+        prompt = sample_data["挖空後文章"] + "\n"
+        for question_key in cls.question_keys:
+            question_str = sample_data[question_key]
+            question_str = re.sub("參考答案:.", "", question_str)
+            prompt = prompt + question_str.strip() + "\n"
+            prompt = prompt.replace("？", "?")
+            prompt = prompt.replace("（", "(")
+            prompt = prompt.replace("）", ")")
+            prompt = prompt.replace(" ", "")
+        return prompt.strip(), sample_data["通過/不通過"]
+
+# ---------- Core client wrapper ----------
+
+class LLMClient:
+    def __init__(self, client: AzureOpenAI, model: str, temperature: float = 0, max_tokens: Optional[int] = None):
+        self.client = client
+        self.model = model
+        self.temperature = float(temperature)
+        self.max_tokens = max_tokens
+        self.chat_rerank_log = []
+    def _call_chat(self, **kwargs):
+        # 共同呼叫點，做指數退避
+        backoff = 0.5
+        for _ in range(4):
+            try:
+                return self.client.chat.completions.create(**kwargs)
+            except (RateLimitError, APITimeoutError, APIError):
+                time.sleep(backoff); backoff *= 2
+        # 最後再嘗試一次，把例外拋出
+        return self.client.chat.completions.create(**kwargs)
+
+    def chat(
+        self,
+        messages: List[Dict[str, str]],
+        response_format: Optional[Dict[str, Any]] = None
+    ) -> str:
+        kwargs = dict(model=self.model, messages=messages, temperature=self.temperature)
+        if self.max_tokens is not None:
+            kwargs["max_tokens"] = self.max_tokens
+        if response_format:
+            kwargs["response_format"] = response_format
+        resp = self._call_chat(**kwargs)
+        return resp.choices[0].message.content or ""
+    
+    # ===== 新增：多候選 + logprobs rerank =====
+    def chat_rerank(
+        self,
+        messages: List[Dict[str, str]],
+        n: int = 2,
+        temperature: Optional[float] = None,
+        response_format: Optional[Dict[str, Any]] = None,
+        top_logprobs: int = 1,   # 
+        length_norm: bool = True # True=平均logprob；False=總logprob
+    ) -> Dict[str, Any]:
+        """
+        回傳：
+        {
+          "best_text": str,
+          "best_index": int,
+          "best_score": float,
+          "candidates": [
+            {"index": i, "text": "...", "score": float, "token_logprobs": [..]},
+            ...
+          ]
+        }
+        """
+        t = self.temperature if temperature is None else float(temperature)
+
+        base_kwargs = dict(
+            model=self.model,
+            messages=messages,
+            n=int(n),
+            temperature=t
+        )
+        if self.max_tokens is not None:
+            base_kwargs["max_tokens"] = self.max_tokens
+        if response_format:
+            base_kwargs["response_format"] = response_format
+
+        # --- 相容處理：先用 OpenAI 風格（logprobs=True + top_logprobs=int）
+        kwargs = dict(base_kwargs)
+        kwargs["logprobs"] = True
+        kwargs["top_logprobs"] = int(top_logprobs)
+
+        try:
+            resp = self._call_chat(**kwargs)
+        except APIError as e:
+            # 若是 Azure 端驗證失敗（常見於有的版本把 logprobs 視為 int）
+            # 改成 Azure 風格：logprobs=int(top_k)，不帶 top_logprobs
+            kwargs = dict(base_kwargs)
+            # 至少要 1，才能回傳 chosen token 的 logprob 與若干 top 候選
+            kwargs["logprobs"] = max(1, int(top_logprobs)) if top_logprobs > 0 else 1
+            resp = self._call_chat(**kwargs)
+
+        def extract_token_logprobs(choice) -> List[float]:
+            """從 choice.logprobs 取出每個輸出 token 的 logprob；不同佈署格式略有差異，做穩健解析。"""
+            lp = getattr(choice, "logprobs", None)
+            if not lp:
+                return []
+            # OpenAI Chat 回傳：choice.logprobs.content -> List[ { token, logprob, top_logprobs? } ]
+            content = getattr(lp, "content", None)
+            if isinstance(content, list) and content:
+                vals = []
+                for item in content:
+                    val = getattr(item, "logprob", None)
+                    if val is not None:
+                        vals.append(float(val))
+                return vals
+            # 有些佈署可能直接給 tokens/logprobs 串列
+            tokens = getattr(lp, "tokens", None)
+            logps = getattr(lp, "token_logprobs", None) or getattr(lp, "logprobs", None)
+            if isinstance(logps, list):
+                return [float(x) for x in logps]
+            return []
+
+        def score_of(logps: List[float]) -> float:
+            if not logps:
+                return float("-inf")
+            return (sum(logps) / len(logps)) if length_norm else sum(logps)
+
+        # 整理所有候選並計分
+        scored = []
+        for i, ch in enumerate(resp.choices):
+            text = (ch.message.content or "")
+            token_logps = extract_token_logprobs(ch)
+            scored.append({
+                "index": i,
+                "text": text,
+                "score": math.e ** score_of(token_logps),
+                "token_logprobs": token_logps
+            })
+
+        scored.sort(key=lambda x: x["score"], reverse=True)
+        best = scored[0] if scored else {"index": -1, "text": "", "score": float("-inf"), "token_logprobs": []}
+        self.chat_rerank_log = scored
+        
+        return {
+            "best_text": best["text"],
+            "best_index": best["index"],
+            "best_score": best["score"],
+            "log": scored
+        }
+
+# ---------- Orchestrator ----------
+
+class PreferenceJudge:
+    def __init__(
+        self,
+        llm: LLMClient,
+        mode: Mode = "reading",
+        prompts: Optional[PromptSet] = None,            # 顯式注入時會覆蓋 mode
+        json_schema_override: Optional[Mapping[str, Any]] = None,
+    ):
+        self.llm = llm
+
+        if prompts is None:
+            key = mode.casefold()
+            try:
+                self.prompts = PROMPT_REGISTRY[key]
+            except KeyError as e:
+                valid = ", ".join(sorted(PROMPT_REGISTRY.keys()))
+                raise ValueError(f"Invalid mode '{mode}'. Valid modes: {valid}") from e
+            self.mode = key
+        else:
+            self.prompts = prompts
+            self.mode = "custom"
+
+        # 以 prompts 的 schema 為主，必要時允許覆寫
+        base_schema = json_schema_override if json_schema_override is not None else self.prompts.json_schema
+        # 包成唯讀，避免執行期被改動
+        self.json_schema = base_schema if isinstance(base_schema, MappingProxyType) else MappingProxyType(dict(base_schema))
+
+    @classmethod
+    def register_mode(cls, name: str, prompts: PromptSet) -> None:
+        """外部可擴充新模式"""
+        PROMPT_REGISTRY[name.casefold()] = prompts
+
+    @staticmethod
+    def contains_simplified(text: str, enable_general_word_check: bool = False) -> bool:
+        return OpenCCChecker.has_simplified(text, prefer_general_word_check=enable_general_word_check)
+
+    def judge(self, reading_task_prompt: str, run_additional_check: bool = True, run_json_schema: bool = True) -> Tuple[List[Dict[str, str]], Dict[str, Any]]:
+        msgs: List[Dict[str, str]] = [
+            {"role": "developer", "content": self.prompts.system},
+            {"role": "user", "content": reading_task_prompt},
+        ]
+
+        # 回合1：基礎審核
+        resp1 = self.llm.chat(msgs)
+        msgs.append({"role": "assistant", "content": resp1})
+
+        # 回合2：只看題目之選項檢查（可關閉）
+        if run_additional_check:
+            msgs.append({"role": "user", "content": self.prompts.additional_check})
+            resp2 = self.llm.chat(msgs)
+            msgs.append({"role": "assistant", "content": resp2})
+
+        # 回合3：JSON Schema 輸出（若提供）
+        if run_json_schema:
+            resp3 = self.llm.chat(
+                msgs,
+                response_format={"type": "json_schema", "json_schema": self.prompts.json_schema}
+            )
+            msgs.append({"role": "assistant", "content": resp3})
+            try:
+                parsed = json.loads(resp3)
+            except json.JSONDecodeError:
+                parsed = {"error": "model did not return valid JSON", "raw": resp3}
+        else:
+            parsed = {"raw": msgs[-1]["content"]}
+        return msgs, parsed
+
+class LevelJudge:
+    def __init__(self, model_path: str, device: str = "cuda"):
+        if torch is None or AutoTokenizer is None or LevelJudgementModel is None:
+            # region agent log
+            _agent_log(
+                "H_DEPS",
+                "util/judgement.py:LevelJudge.__init__",
+                "LevelJudge missing optional deps",
+                {
+                    "torch_available": torch is not None,
+                    "transformers_available": AutoTokenizer is not None,
+                    "LevelJudgementModel_available": LevelJudgementModel is not None,
+                    "model_path": model_path,
+                    "device": device,
+                },
+            )
+            # endregion
+            raise ModuleNotFoundError(
+                "LevelJudge requires optional dependencies. Install 'torch' and 'transformers' to use it."
+            )
+
+        ckpt = torch.load(model_path, map_location=device)  # PyTorch 2.6 預設 weights_only=True，讀 state_dict 沒問題
+        hparams = ckpt["hparams"]
+
+        self.model = LevelJudgementModel(**hparams).to(device)
+        self.model.load_state_dict(ckpt["model_state_dict"], strict=True)
+        self.tonkenizer = AutoTokenizer.from_pretrained(hparams["model_name"])
+        self.model.eval()
+        self.device = device
+
+    def judge(self, text):
+        """Predicts level probabilities."""
+        batch_x = self.tonkenizer(text, max_length=512, padding=True, truncation=True, return_tensors="pt").to(self.device)
+
+        with torch.no_grad():
+            output = self.model(batch_x["input_ids"], batch_x["attention_mask"])
+            probs = torch.nn.functional.softmax(output, dim=1).squeeze().tolist()
+
+        id2label = {0:'入門基礎', 1:'進階高階', 2:'流利精通'}
+        predictions = {id2label[i]: round(probs[i], 3) for i in range(len(probs))}
+        return predictions

util/reading_constants.py

@@ -0,0 +1,450 @@
+import json
+from string import Template
+from types import MappingProxyType
+SYSTEM_PROMPT = "你是一位在台灣從事國文教育多年有趣的華語老師，這次負責出閱讀測驗的題目。"
+READING_TASK_DEFINITION = "每個閱讀測驗由「文章」和「題目」所組成，「文章」由一連串文字組成，與學校的課文相似；「題目」為選擇題，提出一個問題後給予(A)、(B)、(C)、(D)四個可能的答案供選擇。"
+
+BAND_A_DEFINITION_PROMPT = """【題型說明】
+%s
+
+【要求】
+每篇文章只出一題題目。
+文章長度80~150字，語言難度相當於國小中高年級水準，盡量不要出現書面語。
+文章多為日常情境、簡短故事的記敘文，富含一些道理。
+預期讀者為學習繁體中文的外國成年人，可以以較為國際化或本土化的文章內容出題。
+文章文體分為四種:
+    [記敘文]: 敘寫人、事、時、地、物。 包含，形塑人物、記述事件、描繪空間、摹寫物品。
+    [抒情文]: 抒發對人、事、物、景的情感。包含，因人抒情、藉事抒情、因地抒情、詠物抒情、藉景抒情。
+    [説明文]: 說明事理或事物。包含，解釋事理、說明事物、解決問題、說明手法、說明輔助。
+    [議論文]: 表達對人、事、物的看法。包含，建立論點、提出論據、因果論證、歸納論證、演繹論證。
+    *若文中含有對話則在文題後方標明(含對話)。
+題目類型分為[直接提取]、[主旨判斷]、[直接推論]:
+    [直接提取]: 要求讀者直接從文本中找到明確訊息，通常答案在文中有清楚線索。
+    [主旨判斷]: 考驗讀者能否掌握文章的核心重點或整體意圖，而不是某一句的資訊。
+    [直接推論]: 著重於從上下文推敲作者舉例、用語或段落背後的用意，重點在「為什麼要這樣說／這個例子是要說明什麼」。
+
+【閱讀測驗生產流程】
+閱讀完相關要求後，決定一個80~150的數字做為文章長度參考，並依照給定的文體產出文章。
+閱讀完文章內容後，從給定的題型，產出題目問句。
+產出適當的三個誘答選項及標準答案，誘答選項不可以是「只看選項就可以判斷答案的『明顯錯誤答案』」，常見的情況有「強烈的否定用語」或「與常理不符」。
+
+【範例】
+文章([記敘文](純敘述)):
+我最近學會一道臺灣菜，叫做「鹹蛋苦瓜」，這道菜是房東陳媽媽教我做的。以前，我覺得苦瓜吃起來和藥一樣苦，一直不喜歡吃。 可是陳媽媽教我做的苦瓜一點都不苦，吃起來又香又甜。而且陳媽媽說，吃沒煮過的苦瓜對身體更好，還說下一次要教我用沒煮過的苦瓜做好喝的果汁，我學會以後，要先做給我的好朋友玉芳喝，希望她和我一樣愛上苦瓜。
+
+題目:
+1.寫這段話的人說了什麼？
+（A）他一道臺灣菜也不會做
+（B）陳媽媽和他一樣不吃苦瓜
+（C）他發現苦瓜在臺灣是一種藥
+（D）他的好朋友玉芳也不喜歡苦瓜
+[直接推論]
+
+文章([説明文](純敘述)):
+你怎麼處理那些已經不再看的書呢？直接丟掉？送給別人？還是賣給書店？現代網路的進步，使賣書變得更容易。於是有些人就利用網路開店賣舊書，把賺來的錢分給需要的人，有時也將舊書送到鄉下或山裡的學校，這樣的話，不但可以保護環境，還可以讓更多的人有機會讀書。
+
+題目:
+1.這篇文章在談什麼？
+（A）用家中舊書換新書的方法
+（B）上網看書才不會用太多紙
+（C）學會賣書可以賺更多的錢
+（D）把不要的書變成有用的書
+[主旨判斷]
+
+文章([抒情文](含對話)):
+明麗的朋友都覺得明麗總是開心地過生活，大家從來沒有看過她傷心或生氣。有一次，我問她是怎麼辦到的，她回答我：「每天一早醒來，我都有兩個選擇，可以選擇壞心情，討厭自己的生活；也可以選擇好心情，喜愛自己的生活。如果是你，不會選第二個嗎？」
+
+題目:
+1.明麗最後要說的意思是什麼？
+（A）想太多事情對自己沒用
+（B）心情好壞可以自己決定
+（C）早睡早起的人一定快樂
+（D）生活進步的方法有很多
+[直接推論]
+
+文章([記敘文](純敘述)):
+有一對夫婦開了一家賣蛋的小店，又高又壯的先生賣的蛋總是比又瘦又矮的太太少得多。他覺得很奇怪，想了又想，原來是因為他的手比較大，當他用手拿著蛋時，客人會覺得蛋變小了。太太用她的小手拿蛋給客人時，蛋看起來居然大一些。之後，先生把蛋放在很小的盤子裡賣，大家就覺得這間店的蛋特別大，先生也就成功賣出了更多蛋。
+
+題目:
+1.為什麼太太賣蛋賣得比先生好？ 
+（A）太太賣的蛋比較便宜 
+（B）先生賣蛋的樣子很奇怪 
+（C）太太賣的蛋看起來比較大 
+（D）先生把蛋放在小盤子裡賣
+[直接提取]
+
+""" %(READING_TASK_DEFINITION)
+
+BAND_B_DEFINITION_PROMPT = """【題型說明】
+%s
+
+【要求】
+每篇文章出2~4題題目。
+文章多樣，富含哲理。
+文章長度150~400字，語言難度相當於國中水準，可出現少量書面語。
+預期讀者為學習繁體中文的外國成年人，因此可考慮使用一些「台灣文化」。
+文章文體分為四種:
+    [記敘文]: 敘寫人、事、時、地、物。 包含，形塑人物、記述事件、描繪空間、摹寫物品。
+    [抒情文]: 抒發對人、事、物、景的情感。包含，因人抒情、藉事抒情、因地抒情、詠物抒情、藉景抒情。
+    [説明文]: 說明事理或事物。包含，解釋事理、說明事物、解決問題、說明手法、說明輔助。
+    [議論文]: 表達對人、事、物的看法。包含，建立論點、提出論據、因果論證、歸納論證、演繹論證。
+    *若文中含有對話則在文題後方標明(含對話)。
+題目類型分為[直接提取]、[主旨判斷]、[詞語句意]、[直接推論]:
+    [直接提取]：要求讀者直接從文本中找到明確訊息，通常答案在文中有清楚線索。
+	[主旨判斷]：考驗讀者能否掌握文章的核心重點或整體意圖，而不是某一句的資訊。
+	[詞語句意]：針對文中某個詞語、句子或段落的字面意義進行釐清，重點在「它是什麼意思」。
+	[直接推論]：著重於從上下文推敲作者舉例、用語或段落背後的用意，重點在「為什麼要這樣說／這個例子是要說明什麼」。
+
+【閱讀測驗生產流程】
+閱讀完相關要求後，決定一個150-400的數字做為文章長度參考，並依照給定的文體產出文章。
+閱讀完文章內容後，隨機選取題型，產出2~4個題目問句。
+產出適當的三個誘答選項及標準答案，誘答選項不可以是「只看選項就可以判斷答案的『明顯錯誤答案』」，常見的情況有「強烈的否定用語」或「與常理不符」。
+
+【範例】
+文章([議論文](純敘述)):
+在某些社會文化中，由於「一個人吃飯」通常與被孤立、沒朋友、不懂社交等負面印象聯繫在一起，所以一個人走進餐廳就成了許多人害怕的事。但，獨自吃飯真是一件那麼糟糕的事嗎？事實上，一個人並不意味著寂寞，與此相反，更可以將注意力放在享受餐盤上的美食。當然，與他人分享、交流時能帶給人們滿足與快樂，而當你已經在人際相處上付出了許多時間後，更應該為自己保留一些獨處的空間；當你因為獨自吃飯而害怕被貼上「人際障礙」的標籤時，也許根本沒有人注意到你，或是覺得你性格古怪。忙碌的生活常常讓我們忽略與自己獨處的重要性，哪怕是一頓飯、一部電影的時間，都是面對自己的好機會。久而久之，你將發現，那些異樣眼光只是一種自我限制，而能一個人吃飯，竟然是那麼寶貴。
+
+題目:
+1. 作者認為有些人害怕一個人吃飯的原因是什麼？
+（A）不敢違反社交規定
+（B）太在意別人的想法
+（C）不能分享最新的消息
+（D）擔心錯過朋友的邀請
+[直接提取]
+2. 關於「害怕一個人吃飯」，下面哪句話可以用來說明作者的觀點？
+（A）無疑是自己嚇自己
+（B）反而更不顧別人感受
+（C）負面評價自有他的道理
+（D）每個人都得面對生活的寂寞
+[直接推論]
+3. 根據本文，作者認為「一個人」的優點是什麼？
+（A）不必擔心事情被中途打斷
+（B）能消除人與人之間的防備
+（C）對所做的事情能更加投入
+（D）能建立起獨立自主的形象
+[直接提取]
+         
+文章([記敘文](純敘述)):
+我們都知道，小時候大人說給我們聽的故事，大部分都不是真的。即使早就知道這個事實，但長大以後，當我們有了自己的小孩，還是會把聽過的故事重新說一遍，就這樣一代一代，讓故事繼續下去。這種對幻想世界的好奇心，是每個小孩最珍貴的精神財富。而一個大人在經歷無數人生中的現實之後，如果還能保留住這份天真，該是多麼難得。 電影《大魚》，正是在探討這樣的主題。電影描述一位非常有想像力的父親，總是告訴小兒子一些以自己為主角的神奇故事，然而隨著年齡增長，小兒子從原本對父親的敬愛和崇拜，逐漸轉變成忽視。 他不喜歡父親仍然把他當小孩一樣，繼續說著那些聽起來很「誇張」的故事。父子間的關係因此越來越差，彼此甚至不再說話。直到父親去世後，在父親的葬禮上，小兒子看見父親故事裡的那些人物竟然都出席了，他才明白，父親只是希望，他始終能擁有兒時的天真。最後，他也把父親的故事，分享給了自己的孩子。
+
+題目:
+1. 這篇短文主要想傳達什麼思想？
+（A）看電影和聽故事都不必太認���
+（B）人們應該完全像小孩一樣活著
+（C）成長過程中要保持單純不容易
+（D）既然長大就應該提早面對現實
+[主旨判斷]
+2. 請問下面哪一段文字最符合第二段中所說的「主題」？
+（A）睡前聽故事
+（B）孝順父母親
+（C）失去的童心
+（D）哲學的智慧
+[詞語句意]
+3. 根據短文，為什麼小兒子後來和父親的關係不好？
+（A）他一直都誤會父親
+（B）他覺得父親不關心他
+（C）他父親很少再和他講故事
+（D）他父親是個不切實際的人
+[直接推論]
+
+文章([抒情文](純敘述)):
+孩子，這是你改搭校車回家的第一天。媽媽沒忘記你早上出門前，不停地告訴我搭校車是件很恐怖的事，那語氣裡充滿了面對不確定的不安，更讓媽媽覺得不忍心。然而我只是笑著看你，聽你把所有預期中可怕的後果全部說完，然後篤定地告訴你：「這是你人生的另一個開始，你要學著去面對你自己的人生！」
+
+題目:
+1.在這段短文裡，母親面對孩子的不安時，態度怎麼樣？ 
+（A）既害怕又不忍心 
+（B）不知道該怎麼辦 
+（C）覺得孩子很可憐 
+（D）鼓勵孩子自己解決
+[直接推論]
+
+""" %(READING_TASK_DEFINITION)
+
+BAND_C_DEFINITION_PROMPT = """【題型說明】
+%s
+
+【要求】
+每篇文章出4~6題題目。
+文章多為説明文或議論文，富含哲理、情感、經驗。
+文章長度250~500字，語言難度相當於高中水準，可出現書面詞、抽象概念。
+預期讀者為學習繁體中文的外國成年人，因此可考慮使用一些「台灣文化」。
+文章文體分為四種:
+    [記敘文]: 敘寫人、事、時、地、物。 包含，形塑人物、記述事件、描繪空間、摹寫物品。
+    [抒情文]: 抒發對人、事、物、景的情感。包含，因人抒情、藉事抒情、因地抒情、詠物抒情、藉景抒情。
+    [説明文]: 說明事理或事物。包含，解釋事理、說明事物、解決問題、說明手法、說明輔助。
+    [議論文]: 表達對人、事、物的看法。包含，建立論點、提出論據、因果論證、歸納論證、演繹論證。
+    *若文中含有對話則在文題後方標明(含對話)。
+題目類型分為[直接提取]、[主旨判斷]、[詞語句意]、[直接推論]:
+    [直接提取]：要求讀者直接從文本中找到明確訊息，通常答案在文中有清楚線索。
+	[主旨判斷]：考驗讀者能否掌握文章的核心重點或整體意圖，而不是某一句的資訊。
+	[詞語句意]：針對文中某個詞語、句子或段落的字面意義進行釐清，重點在「它是什麼意思」。
+	[直接推論]：著重於從上下文推敲作者舉例、用語或段落背後的用意，重點在「為什麼要這樣說／這個例子是要說明什麼」。
+
+【閱讀測驗生產流程】
+閱讀完相關要求後，決定一個250-500的數字做為文章長度參考，並依照給定的文體產出文章。
+閱讀完文章內容後，隨機選取題型，產出題目問句。
+產出適當的三個誘答選項及標準答案，誘答選項不可以是「只看選項就可以判斷答案的『明顯錯誤答案』」，常見的情況有「強烈的否定用語」或「與常理不符」。
+
+【範例】
+文章([抒情文](純敘述)):
+    「花間一壺酒，獨酌無相親」，這兩句詩表達出李白的心情。他在奼紫嫣紅的花叢間，擺上一壺酒。在醺然的狀態下，邀了天上的明月一起對飲。這樣的良辰美景，應該是三五好友，知心共享的時刻，李白卻只能喟嘆。月亮、李白與李白的影子，對影成三人。
+    月亮不會飲酒，和自己的影子飲酒更是平添寂寞。但是，李白終究灑脫。趁著春光正盛，恣意歌詠，至歡快處，手舞足蹈不也酣暢淋漓、大快人心。
+    李白就這樣從最初的落寞，到任著自己的心情，在月下舞著、蹈著、唱著，還和白玉盤有了天際渺渺之約。李白不需要走到人生的困境，才懂得駐足欣賞眼前的風景，他總是隨走隨看隨領略。即便孤身一人，總有艱辛，他也能將之轉化與天地同歡，而這番了悟，妙筆一揮，遂成詩裡行間的風景。
+    在我看來，人生泰半是挫折與苦難。但是，若偕李白同行，每每到水窮處時，必定聽見李白放聲大歌。伴著歌聲，試著將挫折烹調成一盤下酒菜。咀嚼於舌尖的況味，終將消化於人生的坦然。
+
+題目:
+1.「花間一壺酒，獨酌無相親」表達出李白的心情怎麼樣？
+（A）漠然
+（B）舒暢
+（C）孤寂
+（D）哀痛
+[詞語句意]
+2. 根據本文第二段描述，讓李白手舞足蹈的原因是什麼？
+（A）因為他自在的個性
+（B）因為他和月亮的約定
+（C）因為他醉後就想跳舞
+（D）因為他想看影子的流動
+[直接提取]
+3. 本文第三段提到，「詩裡行間的風景」，作者指的是什麼？
+（A）李白對���然的讚嘆
+（B）李白對官場的感慨
+（C）李白對人生的領悟
+（D）李白對詩詞的看法
+[直接推論]
+4. 根據文本，作者咀嚼於舌尖的「況味」，是一種什麼味道？
+（A）甘味
+（B）鮮味
+（C）辛味
+（D）苦味
+[主旨判斷]
+
+文章([記敘文](純敘述)):
+    她獨行於瞎燈黑火的林道上，僅有些微月光從葉隙中透出。臨下山前，家中長輩再三囑咐，此去求援，不可妄生事端，她的拳腳功夫僅能自保，若不是族中男子皆已上戰場廝殺，萬萬是不能讓她一個女子孤身上路。是以一切只求護得自身周全，快去快回即可。
+    一路行來，她不僅低調，且不停地變換交通工具，先是乘舟走水十來天，接著易舟為馬，在馬上又折騰了十來天。就剩最後這幾里路時，她才改由步行。原以為安全的地兒，眼下卻讓她有不寒而慄之感。
+    前方突地傳來沙沙聲，她下意識退後兩步，卻見林中飛鳥穿過樹梢，她有些「惱怒」，暗啐膽小。驀地，身後傳來虛空劃破之聲。她略側頭回看，眼角已閃過一道疾光。堪堪轉身之際，就見劍尖在眼前一晃，幸得她偏頭一閃，並朝對方腰處撞去。她也不知道這一招是否有效，只是拼盡全身的力氣，狠地一撞。這一來一往，間刻不能容髮之際，她都沒察覺自己一顆心已經提到了嗓子眼兒，堵得呼吸都倍顯艱難。
+    幸得這一撞，教來者失了準頭，削掉她幾縷青絲。但這一撞，也叫她看清來者何人，一聲驚呼幾乎要從喉間溢出，今天真是給阿爹應了「養虎為患」這句話啊！來人穩住身形，又是一連串凌厲攻勢，她左支右絀閃躲地甚是狼狽。反射性地憶起了與這人無猜的歲月，心下淒苦。喉頭一甜、滿嘴鹹腥。眼下任務不僅完成不了，想她不過一十八歲的年華或許也將了結在此。
+
+題目:
+1.關於文章中的主角，下面哪一個是對的？
+（A）她找好救兵準備上戰場
+（B）她跟著一大隊人馬求援
+（C）她的武功已是出神入化
+（D）她的狀態現是生死未卜
+[直接提取]
+2. 文章中的主角與攻擊她的人，以前是什麼關係？
+（A）舊識
+（B）親家
+（C）陌路
+（D）對頭
+[直接提取]
+3. 文章第三段提及主角有些惱怒，她在惱怒什麼？
+（A）她覺得自己的能力不如男子
+（B）她害怕自己無法完成此趟任務
+（C）她覺得長途跋涉的旅程太過疲憊
+（D）她覺得自己不該被一些聲響嚇到
+[直接推論]
+4. 文中，心「提到了嗓子眼兒，堵得呼吸都倍顯艱難」，是怎樣的情緒？
+（A）氣憤
+（B）尷尬
+（C）緊張
+（D）鬱鬱
+[詞語句意]
+5. 文章最後一段提及，主角和敵人對戰的情況怎麼樣？
+（A）她落於下風
+（B）她最終反敗為勝
+（C）她將對方手到擒來
+（D）她與對方勢均力敵
+[直接提取]
+6. 下面哪一個句子可以用來描述攻擊的人？
+（A）相貌玉樹臨風
+（B）出手趕盡殺絕
+（C）招式拖泥帶水
+（D）神色恍恍惚惚
+[直接提取]
+
+文章([説明文](純敘述)):
+    多數人以為，超大質量黑洞應存在於巨大星系的中心位置。但日前，已有天文學家在銀河系邊緣，發現了幾十個超大質量黑洞。這些黑洞在環繞銀河系主體，由恆星和氣體構成近似於球形的「恆星暈」區域中閒逛著。
+    天文學家認為，黑洞之所以存在於宿主星系邊緣的現象，是來自星系合併的結果，這現象經常發生在一個不斷膨脹的宇宙中。當一個較小的星系融入一個更大的主星系時，它會把自己中央的超大質量黑洞置於新的宿主星系上。《天體物理學雜誌快報》刊發的研究報告進一步預測，與銀河系具有相近質量的星系，應該包含著不只一個超大質量的黑洞。
+    該報告的研究員表示，由於工具的限制，想直接論斷黑洞的存在是不可能的。即使想間接推斷它們是否存在，也必須要有更好的方法與手段才行。因為，每1000億年左右，才能與影響太陽系的漫遊黑洞近距離接觸，從人類角度來看，其發生頻率極低；再加上，因為預測漫遊的超大質量黑洞位於離星系中心很遠且處於星系盤之外的地方，所以它們不太可能吸收增加更多的氣體，來膨脹規模，讓人類發現它們。
+
+題目:
+1.根據本文，關於「超大質量黑洞」描述，下列何者正確？
+（A）在宿主星系遊蕩
+（B）只存在於已經死亡的星系裡
+（C）天文學家預測僅存在銀河系中
+（D）天文學家無法證實其存在星系邊緣
+[直接提取]
+2. 天文學家為什麼提到「星系合併」？
+（A）主要說明黑洞的位置
+（B）解釋超大黑洞發生的時間
+（C）強調太陽系仍在膨脹壯大中
+（D）從合併過程說明宇宙氣體的重要性
+[直接推論]
+3. 關於超大質量黑洞，《��體物理學雜誌快報》預測了什麼？
+（A）黑洞影響太陽星系的時間
+（B）超大質量黑洞運行的軌跡
+（C）數個超大質量黑洞的存在
+（D）「恆星暈」形成的可能因素
+[直接提取]
+4. 根據本文，研究員認為間接推斷其他星系黑洞存在的限制是什麼？
+（A）超大質量黑洞無法靠近「恆星暈」
+（B）觀測工具無法觀測那麼遠的距離
+（C）無法證明銀河系邊緣存在著黑洞
+（D）宇宙時間無垠，而人類時間有限
+[直接提取]
+
+文章([議論文](純敘述)):
+    在美國，有不少長年戰績不佳的球隊。最經典的，當然是快要一百年沒拿過世界大賽冠軍的芝加哥小熊隊，他們不只打不到冠軍，而且戰績常常落得難看，球季中就失去了爭冠的機會。但小熊隊從來不缺球迷支持者，他們的球迷甚至練就一身自我解嘲、自我安慰的本事，例如在球季開賽的第一場比賽，就高舉牌子，上面寫著：「別擔心，還有明年！」
+    近來台灣有不少運動員在國際體壇表現卓越，無論媒體或輿論都以「台灣之光」來稱呼這些為國爭光的運動員，一般民眾也與有榮焉，追著觀看這些台灣之光的各項賽事。不過，這些因運動員知名度提昇而追星的民眾，恐怕很難理解小熊隊球迷的忠誠，更難體會這種忠誠的價值，因為王建民、曾雅妮沒贏球，我們根本就不會注意到他們。我們從這些球星身上得到的，是贏的快感，是沾染贏的光榮；我們選擇的，不是特定的球員，也不是他們所屬的哪一支球隊，而是贏的事實。一旦失去了贏的因素，我們也就毫不客氣地失去對他們的興趣，轉而尋找實力更強的球隊來支持了。
+
+題目:
+1.小熊隊球迷舉的牌子，向球隊傳達了什麼訊息？
+（A）我們今年一定贏
+（B）今年別輸得太難看
+（C）今年輸了也沒關係
+（D）明年會和今年一樣好
+[直接提取]
+2. 第二段提到的「他們」指的是誰？
+（A）對小熊隊忠誠的球迷
+（B）注意到明星球員的民眾
+（C）表現優異的台灣運動員
+（D）台灣運動員所屬的球隊
+[詞語句意]
+3. 作者說，台灣民眾觀看運動員和球賽的心態是什麼？
+（A）有贏有輸比賽才好看
+（B）因為球員贏了才支持
+（C）即使球員贏了也沒什麼
+（D）就算球員輸了也依舊支持
+[直接推論]
+4. 本文從哪個角度來比較台灣和美國的球迷？
+（A）球迷如何幫球隊宣傳
+（B）球迷如何選出明星球員
+（C）球迷是否注意媒體報導
+（D）球迷是否在乎球賽輸贏
+[主旨判斷]
+""" %(READING_TASK_DEFINITION)
+
+BAND_A_ASKING_PROMPTS = [Template("你覺得在「${topic_class}」這個類別底下適合給成年人看的${style}主題有哪些?"), Template("從這些「${topic_class}」的主題中選擇一個最特別的、最能引起讀者共鳴的，並依照原本的【閱讀測驗生產流程】產出閱讀測驗，文章文體使用${style}，題目類型使用${question_type}。")]
+BAND_A_REFERENCE_ASKING_PROMPT = Template("請思考讀者學習完【課文】後的閱讀測驗方向，其中閱讀測驗裡的文章是【課文】的延伸，兩者需保持一定的相關性，但不需重複。請依照原本的【閱讀測驗生產流程】產出閱讀測驗，文章文體使用${style}，題目類型使用${question_type}。\n【課文】\n${content}")
+ASKING_PROMPTS = [Template("你覺得在「${topic_class}」這個類別底下適合給成年人看的${style}主題有哪些?"), Template("從這些「${topic_class}」的主題中選擇一個最特別的、最能引起讀者共鳴的，並依照原本的【閱讀測驗生產流程】產出閱讀測驗，文章文體使用${style}")]
+REFERENCE_ASKING_PROMPT = Template("請思考讀者學習完【課文】後的閱讀測驗方向，其中閱讀測驗裡的文章是【課文】的延伸，兩者需保持一定的相關性，但不需重複。請依照原本的【閱讀測驗生產流程】產出閱讀測驗，文章文體使用${style}。\n【課文】\n${content}")
+FIX_PREFERENCE_PROMPT = "請根據上述審核結果，包含之前的簡短說明，及詳細不合格的理由，修改閱讀測驗的內容。"
+FIX_HIGH_LEVEL_PROMPT = "文章難度過高，請重新閱讀【要求】、【範例】的內容後，降低閱讀測驗的難度。"
+FIX_LOW_LEVEL_PROMPT = "文章難度過低，請重新閱讀【要求】、【範例】的內容後，增加閱讀測驗的難度。"
+
+#計畫助理們(華語老師)確認中
+subtopic_map_path = "./dataset/subtopic_map20251002v2.json"
+with open(subtopic_map_path, "r", encoding="utf-8") as f:
+    SUBTOPIC_MAP = json.load(f)
+
+SUBTOPIC_CLASS_LIST = []
+for class_name, sub_class in SUBTOPIC_MAP.items():
+    SUBTOPIC_CLASS_LIST.extend(sub_class)
+
+READING_TEST_SCHEMA = MappingProxyType({
+    "name": "reading_test_output",
+    "strict": True,
+    "schema": {
+        "type": "object",
+        "properties": {
+            "文章文體": {
+                "type": "string",
+                "description": "閱讀測驗的文體。"
+            },
+            "文章主題": {
+                "type": "string",
+                "description": "閱讀測驗的文章主題。"
+            },
+            "文章主題類別": {
+                "type": "string",
+                "description": "閱讀測驗的文章主題類別。"
+            },
+            "文章": {
+                "type": "string",
+                "description": "閱讀測驗的文章內容。"
+            },
+            "題目列表": {
+                "type": "array",
+                "description": "本篇文章對應的選擇題列表（1~6題）。",
+                "minItems": 1,
+                "maxItems": 6,
+                "items": {
+                    "type": "object",
+                    "properties": {
+                        "題號": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 6,
+                            "description": "可選；不提供則以陣列順序視為題號。"
+                        },
+                        "題目類別": {
+                            "type": "string",
+                            "description": "如：直接提取／主旨判斷／直接推論……"
+                        },
+                        "題目描述": {
+                            "type": "string",
+                            "description": "題目問句。",
+                            "minLength": 1
+                        },
+                        "A": {"type": "string", "description": "選項 A", "minLength": 1},
+                        "B": {"type": "string", "description": "選項 B", "minLength": 1},
+                        "C": {"type": "string", "description": "選項 C", "minLength": 1},
+                        "D": {"type": "string", "description": "選項 D", "minLength": 1},
+                        "答案": {
+                            "type": "string",
+                            "description": "正確選項。",
+                            "enum": ["A", "B", "C", "D"]
+                        },
+                        "解析": {
+                            "type": "string",
+                            "description": "可選；作答理由、關鍵句或提示。"
+                        }
+                    },
+                    "required": ["題號", "題目類別", "題目描述", "A", "B", "C", "D", "答案", "解析"],
+                    "additionalProperties": False
+                }
+            },
+        },
+        "required": ["文章文體", "文章主題", "文章主題類別", "文章", "題目列表"],
+        "additionalProperties": False
+    }
+})
+
+TEMPERATURE = 0.5
+BEAM_NUM = 2
+
+READING_LEVEL_CONFIG = {
+    "A-入門基礎": {
+        "system_prompt": SYSTEM_PROMPT, #確定
+        "definition_prompt": BAND_A_DEFINITION_PROMPT, 
+        "asking_prompt_templates": BAND_A_ASKING_PROMPTS,
+        "reference_asking_prompt_template": BAND_A_REFERENCE_ASKING_PROMPT,
+        "style_distribution":{'[記敘文](含對話)': 0.206, '[記敘文](純敘述)': 0.529, '[議論文](純敘述)': 0.059, '[説明文](純敘述)': 0.118, '[抒情文](純敘述)': 0.059, '[議論文](含對話)': 0.029}, 
+        #"conversation_distribution":{"純敘述":0.9,"含對話":0.1},
+        "topic_classes": SUBTOPIC_CLASS_LIST,
+        "question_type_distribution":{"[直接提取]":float(12/33),"[主旨判斷]":float(7/33),"[直接推論]":float(14/33)},
+        "json_schema": READING_TEST_SCHEMA, #確定
+    },
+    "B-進階高階": {
+        "system_prompt": SYSTEM_PROMPT, #確定
+        "definition_prompt": BAND_B_DEFINITION_PROMPT,
+        "asking_prompt_templates": ASKING_PROMPTS,
+        "reference_asking_prompt_template": REFERENCE_ASKING_PROMPT,
+        "style_distribution":{'[記敘文](純敘述)': 0.22, '[議論文](純敘述)': 0.26, '[説明文](純敘述)': 0.34, '[記敘文](含對話)': 0.1, '[抒情文](純敘述)': 0.06, '[説明文](含對話)': 0.02},
+        #"conversation_distribution":{"純敘述":0.93,"含對話":0.07},
+        "topic_classes": SUBTOPIC_CLASS_LIST,
+        "question_type_distribution":None,
+        "json_schema": READING_TEST_SCHEMA, #確定
+    },
+    "C-流利精通": {
+        "system_prompt": SYSTEM_PROMPT, #確定
+        "definition_prompt": BAND_C_DEFINITION_PROMPT,
+        "asking_prompt_templates": ASKING_PROMPTS,
+        "reference_asking_prompt_template": REFERENCE_ASKING_PROMPT,
+        "style_distribution":{'[説明文](純敘述)': 0.516, '[議論文](純敘述)': 0.419, '[抒情文](純敘述)': 0.032, '[記敘文](純敘述)': 0.032},
+        #"conversation_distribution":{"純敘述":0.93,"含對話":0.07},
+        "topic_classes": SUBTOPIC_CLASS_LIST,
+        "question_type_distribution":None,
+        "json_schema": READING_TEST_SCHEMA, #確定
+    }
+}

util/sentence_dealer/.gitignore

@@ -0,0 +1,165 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+CKIP/
+*.zip
+*test*

util/sentence_dealer/README.md

@@ -0,0 +1,28 @@
+# Sentence_Dealer
+
+## Install the package
+* 下載可能會花5分鐘左右
+```
+conda create -n dealer python=3.10 -y
+conda activate dealer
+cd sentence_dealer
+
+#Install the Sentence_Dealer
+pip install .
+```
+
+##Login Huggingface_hub
+```
+huggingface-cli login
+```
+
+## Quick Start
+```
+from sentence_dealer import Sentence_Dealer
+
+#Modify the ckiptagger_path if you want
+dealer = Sentence_Dealer(ckiptagger_path="./CKIP/")
+sample_sentence = "李相赫是我永遠的神。"
+
+grammar_ids, grammar_range = dealer.list_all_grammars(sentence=sample_sentence)
+```

util/sentence_dealer/__init__.py

@@ -0,0 +1,7 @@
+# sentence_judgement/__init__.py
+
+# 導入 Sentence_Dealer 類別
+from .sentence_dealer import Sentence_Dealer
+
+# 定義 package 的公開介面
+__all__ = ["Sentence_Dealer"]

util/sentence_dealer/requirements.txt

@@ -0,0 +1,74 @@
+absl-py==2.1.0
+asttokens==2.4.1
+astunparse==1.6.3
+beautifulsoup4==4.12.3
+cachetools==5.5.0
+certifi==2024.8.30
+charset-normalizer==3.4.0
+ckiptagger==0.2.1
+decorator==5.1.1
+deep-translator==1.11.4
+exceptiongroup==1.2.2
+executing==2.1.0
+filelock==3.16.1
+flatbuffers==24.3.25
+gast==0.6.0
+gdown==5.2.0
+google-auth==2.35.0
+google-auth-oauthlib==1.2.1
+google-pasta==0.2.0
+grpcio==1.67.1
+h5py==3.12.1
+idna==3.10
+ipython==8.29.0
+jedi==0.19.1
+keras==2.15.0
+libclang==18.1.1
+Markdown==3.7
+markdown-it-py==3.0.0
+MarkupSafe==3.0.2
+matplotlib-inline==0.1.7
+mdurl==0.1.2
+ml-dtypes==0.2.0
+namex==0.0.8
+numpy==1.26.4
+oauthlib==3.2.2
+OpenCC==1.1.9
+opt_einsum==3.4.0
+optree==0.13.0
+packaging==24.1
+pandas==2.2.3
+parso==0.8.4
+pexpect==4.9.0
+prompt_toolkit==3.0.48
+protobuf==4.25.5
+ptyprocess==0.7.0
+pure_eval==0.2.3
+pyasn1==0.6.1
+pyasn1_modules==0.4.1
+Pygments==2.18.0
+PySocks==1.7.1
+python-dateutil==2.9.0.post0
+pytz==2024.2
+requests==2.32.3
+requests-oauthlib==2.0.0
+rich==13.9.3
+rsa==4.9
+six==1.16.0
+soupsieve==2.6
+stack-data==0.6.3
+tensorboard==2.15.2
+tensorboard-data-server==0.7.2
+tensorflow==2.15.0
+tensorflow-estimator==2.15.0
+tensorflow-io-gcs-filesystem==0.31.0
+termcolor==2.5.0
+tqdm==4.66.6
+traitlets==5.14.3
+typing_extensions==4.15.0
+tzdata==2024.2
+urllib3==2.2.3
+wcwidth==0.2.13
+Werkzeug==3.1.0
+wrapt==1.14.1
+huggingface_hub==1.2.3

util/sentence_dealer/sample.py

@@ -0,0 +1,6 @@
+from sentence_dealer import Sentence_Dealer
+
+dealer = Sentence_Dealer(ckiptagger_path="./CKIP/")
+sample_sentence = "李相赫是我永遠的神。"
+
+grammar_ids, grammar_range = dealer.list_all_grammars(sentence=sample_sentence)

util/sentence_dealer/sentence_dealer.py

@@ -0,0 +1,400 @@
+import os, opencc, json, re, sys, zipfile
+import pandas as pd
+import numpy as np
+from ckiptagger import WS, POS, NER, data_utils
+from deep_translator import GoogleTranslator
+from IPython.display import display, HTML
+from importlib import resources
+from huggingface_hub import hf_hub_download
+
+class Sentence_Dealer():
+    def __init__(self, GPU=True, GPU_Num="0", ckiptagger_path="./CKIP/"):
+        #site_packages_path = next(p for p in sys.path if 'site-packages' in p)
+
+        # 拼接 package 中的 CKIP 和 data 路徑
+        data_path = os.path.join("./util/sentence_dealer/data")
+
+        if not os.path.exists(ckiptagger_path):
+            # Download CKIP.zip from Huggingface if it doesn't exist
+            self._download_ckip(ckiptagger_path)
+            
+        if GPU:
+            os.environ["CUDA_VISIBLE_DEVICES"] = GPU_Num
+            self.ws = WS(ckiptagger_path, disable_cuda=False)
+            self.pos = POS(ckiptagger_path, disable_cuda=False)
+            self.ner = NER(ckiptagger_path, disable_cuda=False)
+        else:   
+            self.ws = WS(ckiptagger_path)
+            self.pos = POS(ckiptagger_path)
+            self.ner = NER(ckiptagger_path)
+        self._init_load_data(data_path)
+        self._init_load_grammar_data(data_path+"/grammar")
+        self.converter = opencc.OpenCC('t2s.json')
+
+    def _download_ckip(self, ckip_path):
+        print("Downloading CKIP.zip from Huggingface...")
+        try:
+            hf_hub_download(
+                repo_id="TAIDE-EDU/CKIP-Tagger", 
+                filename="CKIP.zip",
+                local_dir=ckip_path,
+                local_dir_use_symlinks=False
+            )
+        except Exception as e:
+            raise FileNotFoundError(f"Failed to download CKIP.zip from Huggingface: {e}. Please download the CKIP.zip file manually.")
+        with zipfile.ZipFile(f"{ckip_path}/CKIP.zip", 'r') as zip_ref:
+            zip_ref.extractall(f"{ckip_path}")
+        os.remove(f"{ckip_path}/CKIP.zip")
+
+        print("CKIP Tagger downloaded successfully.")
+
+    def _load_json(self, data_path):
+        with open(data_path, "r", encoding="utf-8") as f:
+            result = json.load(f)
+        return result
+    
+    def _init_load_data(self, data_path):
+        self.sim_affixes = self._load_json(data_path + "/sim_affix2.json")
+        self.word2TBCL = self._load_json(data_path + "/word2TBCL.json")
+        self.word2id = self._load_json(data_path + "/word2id.json")
+        self.id2info = self._load_json(data_path + "/id2info.json")
+        self.sim_affix_coerce_dictionary = self._load_json(data_path + "/sim_affix_coerce_dict.json")
+        self.word_coerce_dictionary = self._load_json(data_path + "/word_coerce_dict.json")
+    
+    def _init_load_grammar_data(self, data_path):
+        self.if_else_grammar = self._load_json(data_path + "/if_else.json")
+        self.re_grammar = self._load_json(data_path + "/re.json")
+        self.pos_grammar = self._load_json(data_path + "/pos.json")
+        self.grammar_point = self._load_json(data_path + "/grammar_point.json")
+        self.grammar_id2info = {grammar_sample["id"]:(grammar_sample["grammar_point"],grammar_sample["example"]) for grammar_sample in self.grammar_point}
+
+    def _sentence2words_TBCL_by_words(self, sentence, coerce_dictionary, debug= False):
+        """輸入句子，輸出句子中每個詞彙TBCL的等級 (僅參考詞彙檔)"""
+        words_seg = self.ws([sentence], coerce_dictionary=coerce_dictionary)[0]
+        words_level = []
+        for word in words_seg:
+            if word in self.word2TBCL.keys():
+                words_level.append(self.word2TBCL[word])
+            else:
+                words_level.append("X")
+        if debug:
+            assert len(words_seg) == len(words_level)
+            for word, level in zip(words_seg, words_level):
+                print(f"{word}({level})", end="\u3000")
+            print()
+        return words_seg, words_level
+    
+    def sim_affix2TBCL(self, word, reason=False):
+        for sim_affix in self.sim_affixes:
+            if "pattern" not in sim_affix.keys():
+                continue
+            result = re.search(sim_affix["pattern"], word)
+            if result !=None:
+                sim_affix_level = float(re.search("\d+",sim_affix["ji"]).group())
+                if "*" in sim_affix["ji"]: sim_affix_level +=0.5
+
+                start, end = result.span()
+                #print(start, end)
+                sep_word_level = {word[0:start]:"X", word[start:end]:sim_affix_level, word[end:len(word)]:"X"}
+                word_list = {seperate_word:level for seperate_word, level in sep_word_level.items() if seperate_word!=""}
+                if reason:
+                    print("偵測到\"%s\"系列詞，其含義為\"%s\"。" %(sim_affix["sim_affix"], sim_affix["desc"]))
+                return list(word_list.keys()), list(word_list.values())
+        return [word], ["X"]
+
+    def sentence2words_TBCL(self, sentence, debug= False):
+        """輸入句子，��出句子中每個詞彙TBCL的等級 (有參考詞彙檔&類詞墜檔)"""
+        words_seg, words_level = self._sentence2words_TBCL_by_words(sentence, self.sim_affix_coerce_dictionary)
+        
+        words_seg_2 = []
+        words_level_2 = []
+        for word_seg, word_level in zip(words_seg, words_level):
+            if word_level!="X": words_seg_2.append(word_seg), words_level_2.append(word_level)
+            else:
+                cut_words, levels = self._sentence2words_TBCL_by_words(word_seg, self.word_coerce_dictionary)
+                words_seg_2.extend(cut_words), words_level_2.extend(levels)
+
+        words_seg_3 = []
+        words_level_3 = []
+        for word_seg, word_level in zip(words_seg_2, words_level_2):
+            if word_level!="X": words_seg_3.append(word_seg), words_level_3.append(word_level)
+            else:
+                cut_words, levels = self.sim_affix2TBCL(word_seg, reason=debug)
+                for cut_word, level in zip(cut_words, levels):
+                    if level != "X": words_seg_3.append(cut_word), words_level_3.append(level)
+                    else:
+                        cut_word_seg, cut_word_seg_level = self._sentence2words_TBCL_by_words(cut_word, self.word_coerce_dictionary)
+                        words_seg_3.extend(cut_word_seg), words_level_3.extend(cut_word_seg_level)
+        if debug:
+            assert len(words_seg_3) == len(words_level_3)
+            for word, level in zip(words_seg_3, words_level_3):
+                print(f"{word}({level})", end="")
+            print()
+        return words_seg_3, words_level_3
+    
+    def sentence2TBCL_by_words(self, sentence, reason = False, debug= False):
+        
+        TBCL_1_3_threshold = 0.2
+        TBCL_4_6_threshold = 0.25
+        _, words_level = self.sentence2words_TBCL(sentence, debug=reason)
+        level_list = [word for word in words_level if word!="X"]
+        sorted_levels = sorted(level_list, reverse=True)
+        if sorted_levels == []:
+            if reason: print("未偵測到任何詞彙")
+            return "X"
+        
+        if debug:
+            print("sorted levels:", sorted_levels)
+            print("tack the index %d for TBCL_1_3_threshold." %(int(len(sorted_levels)*TBCL_1_3_threshold)))
+            print("tack the index %d for TBCL_4_6_threshold." %(int(len(sorted_levels)*TBCL_4_6_threshold)))
+        
+        # TBCL 1~3級允許20%超等詞，TBCL 4~6級允許25%超等詞
+        tmp_level = sorted_levels[ int(len(sorted_levels)*TBCL_1_3_threshold) ]
+        if tmp_level <= 3:
+            sentence_level = tmp_level
+        else:
+            tmp_level = sorted_levels[ int(len(sorted_levels)*TBCL_4_6_threshold) ]
+            if tmp_level < 4:
+                sentence_level = 4
+            else:
+                sentence_level = tmp_level
+        if reason:
+            print("偵測到%.1f%%超等詞。" %((len([word_level for word_level in sorted_levels if word_level > sentence_level])/len(sorted_levels))*100))
+        return sentence_level
+    
+    def list_all_grammars(self, sentence, debug = False):
+        words_seg, _ = self.sentence2words_TBCL(sentence)
+        pos_list = self.sentence_pos(words_seg)
+        pos_sentence = ""
+        for word, pos in zip(words_seg, pos_list):
+            if pos in ['VH', 'VHC', 'VI', 'VJ', 'VK', 'VL']:
+                pos = 'Vs'
+            pos_sentence += word + ""
+            pos_sentence += "[" + pos + "]"
+        pos_sentence = pos_sentence.strip()
+        find_garmmars_id = []
+        find_garmmars_range = []
+        #if_else 一個字要跟斷詞後結果比對，兩個字(含)以上不用(直接看句子是否包含)
+        for grammar_name, [level, id] in self.if_else_grammar.items():
+            if len(grammar_name)==1:
+                if grammar_name in words_seg:
+                    find_garmmars_id.append(id)
+                    #find grammar range
+                    index_number = words_seg.index(grammar_name)
+                    range_start = len("".join(words_seg[:index_number]))
+                    range_end = range_start + len(words_seg[index_number])
+                    find_garmmars_range.append((range_start, range_end))
+            elif grammar_name in sentence:
+                find_garmmars_id.append(id)
+                #find grammar range
+                range_start = sentence.index(grammar_name)
+                range_end = range_start + len(grammar_name)
+                find_garmmars_range.append((range_start, range_end))
+        #detect_list = []
+        pattern_list = []
+        for grammar_pattern, [level, id] in self.re_grammar.items():
+            detect = re.search(grammar_pattern, sentence)
+            if detect:
+                find_garmmars_id.append(id)
+                find_garmmars_range.append(detect.span())
+                pattern_list.append(grammar_pattern)
+                #detect_list.append(detect.group())
+        for grammar_pattern, [level, id] in self.pos_grammar.items():
+            # print(pos_sentence)
+
+            detect = re.search(grammar_pattern, pos_sentence)
+            if detect:
+                find_garmmars_id.append(id)
+                pattern_list.append(grammar_pattern)
+                detect_spen = detect.span()
+                #print(re.sub("\[([a-zA-Z_1-9])+?\]", "", pos_sentence[:detect_spen[0]]))
+                range_start = len(re.sub("\[([a-zA-Z_1-9])+?\]", "", pos_sentence[:detect_spen[0]]))
+                range_end = len(re.sub("\[([a-zA-Z_1-9])+?\]", "", pos_sentence[:detect_spen[1]]))
+                find_garmmars_range.append((range_start, range_end))
+
+        if debug:
+            return find_garmmars_id, find_garmmars_range, pos_sentence
+        else:
+            return find_garmmars_id, find_garmmars_range
+
+    def sentence2TBCL_by_grammar(self, sentence, level_lower_bound = 0, reason = False, debug = False):
+        words_seg, _ = self.sentence2words_TBCL(sentence)
+        pos_list = self.sentence_pos(words_seg)
+        pos_sentence = ""
+        for word, pos in zip(words_seg, pos_list):
+            pos_sentence += word + ""
+            pos_sentence += "[" + pos + "]"
+        pos_sentence = pos_sentence.strip()
+        find_garmmars_id = []
+        find_garmmars_level = []
+        find_garmmars_range = []
+        print('pos_sentence')
+        print(pos_sentence) # TODO remove
+        #if_else 一個字要跟斷詞後結果比對，兩個字(含)以上不用(直接看句子是否包含)
+        for grammar_name, [level, id] in self.if_else_grammar.items():
+            if len(grammar_name)==1:
+                if grammar_name in words_seg:
+                    find_garmmars_id.append(id)
+                    find_garmmars_level.append(level)
+                    #find grammar range
+                    index_number = words_seg.index(grammar_name)
+                    range_start = len("".join(words_seg[:index_number]))
+                    range_end = range_start + len(words_seg[index_number])
+                    find_garmmars_range.append((range_start, range_end))
+            elif grammar_name in sentence:
+                find_garmmars_id.append(id)
+                find_garmmars_level.append(level)
+                #find grammar range
+                range_start = sentence.index(grammar_name)
+                range_end = range_start + len(grammar_name)
+                find_garmmars_range.append((range_start, range_end))
+        #detect_list = []
+        pattern_list = []
+        for grammar_pattern, [level, id] in self.re_grammar.items():
+            detect = re.search(grammar_pattern, sentence)
+            if detect:
+                find_garmmars_id.append(id)
+                find_garmmars_level.append(level)
+                find_garmmars_range.append(detect.span())
+                pattern_list.append(grammar_pattern)
+                #detect_list.append(detect.group())
+        for grammar_pattern, [level, id] in self.pos_grammar.items():
+            detect = re.search(grammar_pattern, pos_sentence)
+            if detect:
+                find_garmmars_id.append(id)
+                find_garmmars_level.append(level)
+                pattern_list.append(grammar_pattern)
+                detect_spen = detect.span()
+                #print(re.sub("\[([a-zA-Z_1-9])+?\]", "", pos_sentence[:detect_spen[0]]))
+                range_start = len(re.sub("\[([a-zA-Z_1-9])+?\]", "", pos_sentence[:detect_spen[0]]))
+                range_end = len(re.sub("\[([a-zA-Z_1-9])+?\]", "", pos_sentence[:detect_spen[1]]))
+                find_garmmars_range.append((range_start, range_end))
+                #detect_list.append(detect.group())
+        if find_garmmars_level == []:
+            if reason: print("未偵測到任何文法")
+            return "X"
+        
+        if reason:
+            print("找出大於level_lower_bound的語法位置: (預設0級)")
+            color_style = ["<span style=\"color: #B22222;\";>", "</span>"]
+            color_style_len = len(color_style[0])+len(color_style[1])
+            #統計每個語法的範圍
+            sentence_words_status = np.zeros(len(sentence))
+            for garmmar_level, grammar_range in zip(find_garmmars_level, find_garmmars_range):
+                if garmmar_level > level_lower_bound:
+                    start = grammar_range[0]
+                    end = grammar_range[1]
+                    sentence_words_status[start:end] = 1
+            final_ranges = []
+            start = 0
+            for i in range(1, len(sentence_words_status)):
+                if sentence_words_status[i] == sentence_words_status[start]:
+                    continue
+                else:
+                    if sentence_words_status[start]==1: final_ranges.append((start, i))
+                    start = i
+            if sentence_words_status[start]==1: final_ranges.append((start, i))
+            
+            show_sentence = sentence
+            for i, final_range in enumerate(final_ranges):
+                start = final_range[0] + (i*color_style_len)
+                end = final_range[1] + (i*color_style_len)
+                show_sentence = show_sentence[:start] + color_style[0] + show_sentence[start:end] + color_style[1] + show_sentence[end:]
+            display(HTML(show_sentence))
+
+            print("HTML原始版本:/n")
+            print(show_sentence)
+
+            print("印出大於level_lower_bound的語法表格: (預設0級)")
+            show_dict = {"grammar_id":[], "grammar_name":[], "grammar_level":[], "example":[]}
+            for garmmars_id , garmmars_level in zip(find_garmmars_id, find_garmmars_level):
+                if garmmars_id in show_dict["grammar_id"]:
+                    continue
+                elif type(garmmars_id) == list:
+                    show_dict["grammar_id"].extend(garmmars_id)
+                    show_dict["grammar_level"].extend([garmmars_level for i in range(len(garmmars_id))])
+                else:
+                    show_dict["grammar_id"].append(garmmars_id)
+                    show_dict["grammar_level"].append(garmmars_level)
+                
+            for grammar_id in show_dict["grammar_id"]:
+                    grammar_name, example = self.grammar_id2info[grammar_id]
+                    show_dict["grammar_name"].append(grammar_name)
+                    example = re.sub("<.*?>", "", example)
+                    show_dict["example"].append(example)
+            #print(show_dict)
+            show_dataframe = pd.DataFrame.from_dict(show_dict)
+            show_dataframe = show_dataframe[show_dataframe["grammar_level"] > level_lower_bound]
+            display(HTML(show_dataframe.to_html()))
+
+        if debug:
+            print(find_garmmars_id)
+            print(find_garmmars_level)
+            print(pos_sentence)
+            print(pattern_list)
+            print(find_garmmars_range)
+            #print(show_sentence)
+        
+        #
+        TBCL_threshold = [1.5, 1.5, 2, 3, 4]
+        tmp_grammars_level = max(find_garmmars_level)
+        if (tmp_grammars_level-0.5) in find_garmmars_level:
+            return tmp_grammars_level-0.5
+        else:
+            return tmp_grammars_level
+    
+    def sentence_pos(self, words_seg, debug= False):
+        words_pos = self.pos([words_seg])[0]
+        if debug:
+            assert len(words_seg) == len(words_pos)
+            for word, token in zip(words_seg, words_pos):
+                print(f"{word}({token})", end="\u3000")
+            print()
+        return words_pos
+    
+    def ids2pndas(self, pos_list, ids):
+        
+        #['id', 'word', 'deng', 'ji', 'situation', 'wfreq', 'sfreq', 'newlink', 'bopomofo', 'pinyin']
+        keys = ["序號", "繁體中文", "簡體中文", "注音", "拼音", "詞性", "例句"]
+        result_df = pd.DataFrame(columns=keys)
+        for i, (index, pos) in enumerate(zip(ids, pos_list)):
+            word_result = {"序號":[i]}
+            info = self.id2info[str(index)]
+            word_result["繁體中文"] = [info["word"]]
+            word_result["簡體中文"] = [GoogleTranslator(source='zh-TW', target='zh-CN').translate(info["word"]) ]
+            word_result["注音"] = [info["bopomofo"]]
+            word_result["拼音"] = [info["pinyin"]]
+            word_result["詞性"] = [pos]
+            word_result["例句"] = ["X"]
+            word_result_df = pd.DataFrame.from_dict(word_result)
+            result_df = pd.concat([result_df, word_result_df], ignore_index=True)
+        return result_df
+    
+    def sentence2word_list(self, sentence:str, need_level:int, sim_affix=False, debug=True):
+        words, levels = self.sentence2words_TBCL(sentence)
+        pos_list = self.sentence_pos(words, debug=True)
+        word_id_list = []
+        words_result = []
+        pos_result = []
+        for word, level, pos in zip(words, levels, pos_list):
+            if need_level == level and word in self.word2id.keys() and word not in words_result:
+                word_id = self.word2id[word]
+                word_id_list.append(word_id)
+                words_result.append(word)
+                pos_result.append(pos)
+        result_df = self.ids2pndas(pos_result, word_id_list)
+        return result_df
+
+    def label_sentence(self, sentence, grammar_range):
+        color_style = ["<b style='color:blue;'>", "</b>"]
+        color_style_len = len(color_style[0])+len(color_style[1])
+        #統計每個語法的範圍
+        sentence_words_status = np.zeros(len(sentence))
+        start = grammar_range[0]
+        end = grammar_range[1]
+        sentence_words_status[start:end] = 1
+        
+        show_sentence = sentence
+        labeled_sentence = show_sentence[:start] + color_style[0] + show_sentence[start:end] + color_style[1] + show_sentence[end:]
+
+        return labeled_sentence

util/sentence_dealer/setup.py

@@ -0,0 +1,30 @@
+import os
+import zipfile
+from setuptools import setup, find_packages
+
+# 從 requirements.txt 讀取相依套件
+def parse_requirements(filename):
+    with open(filename, 'r') as file:
+        return [line.strip() for line in file if line.strip() and not line.startswith('#')]
+
+# 套用相依套件列表
+requirements = parse_requirements('requirements.txt')
+
+setup(
+    name="sentence_dealer",
+    version="1.0.0",
+    description="A sentence segmentation and POS tagging package",
+    author="BCC",
+    packages=['sentence_dealer'],
+    package_dir={'sentence_dealer': './'},
+    install_requires=requirements,
+    include_package_data=True,
+    package_data={
+        "sentence_dealer": ["./data/**/*", "./CKIP/**/*"],
+    },
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "Operating System :: OS Independent",
+    ],
+    python_requires=">=3.6",
+)