Name the main decision policies FinQ and FinL

Model_Card_EN.md

@@ -0,0 +1,96 @@
+---
+
+license: other
+license_name: s2-mas-controlled-research-v1.2
+license_link: https://huggingface.co/ya9919/FinQ/blob/main/LICENSE
+
+language:
+
+- en
+
+base_model: Qwen/Qwen3.5-4B-Base
+
+tags:
+
+- s2-mas
+
+- financial-qa
+
+- decision-head
+
+- qwen3_5
+
+- peft
+
+- lora
+
+---
+
+# FinQ · Qwen3.5-4B-Base + LoRA + decision head · 200k QA
+
+## Model naming and experiment labels
+
+**FinQ — Qwen3.5-4B-Base + LoRA + learned decision head, 200k distinct QA** names this selected best checkpoint. [**FinL**](https://huggingface.co/ya9919/FinL) is the parallel full English-base six-round encoder route, and [**FinL-mlx**](https://huggingface.co/ya9919/FinL-mlx) is its MLX FP16 runtime. The original upstream model remains **Qwen/Qwen3.5-4B-Base**. Head-only, 50k and 9B Qwen checkpoints retain their explicit comparator names.
+
+Paper: [S²-MAS](https://github.com/KataDavidXD/s2-mas/blob/main/paper/S2_MAS_Paper.pdf). The fixed-budget adaptation results and matched downstream methods define the comparison reported here.
+
+## Project background
+
+S²-MAS is a society-scale multi-agent simulation framework for studying how household decisions affect consumption, cash reserves and payments. The paper connects a constructed resource of **500 million household-persona records**, learned decision policies, reusable financial scenarios and a state-transition engine. Its purchase-funding application evaluates **12 million distinct synthetic household agents** under paired conditions. Full-data FinL supplies the policy for that application; this repository supplies a fixed-budget adaptation checkpoint for the common decision-model comparison. Decision learning uses **real-survey data**. The GENESE/MAS engine implementation remains private.
+
+The benchmark groups twelve systems into six decision-model routes: encoder option scoring; language models with learned decision heads; next-token decision SFT; dynamic-schema classification; multimodal encoder decisions; and provider decision interfaces. All receive text inputs in the common benchmark. The **17 model-repository entries** comprise **10 fixed-budget trained variants**—five native Laya and five Qwen variants—plus **six checkpoint/runtime entries** and **one compatibility alias**.
+
+## This model's role
+
+**FinQ** follows the **language-model plus learned decision-head route**. LoRA adapters and a shared scalar decision head are trained together on Qwen3.5-4B-Base. The 200k head-only counterpart holds the backbone fixed, allowing the comparison to assess representation adaptation. The complete development partition selects this LoRA method before the separate 9B run.
+
+## Training design and checkpoint
+
+- Method: `lora`.
+
+- Distinct downstream training rows: **200,000** from the fixed decision-QA training partition.
+
+- Initialization: [Qwen/Qwen3.5-4B-Base](https://huggingface.co/Qwen/Qwen3.5-4B-Base).
+
+- This stage terminal row exposures: **200,000**; selected checkpoint stage exposures: **200,000**.
+
+- Selected checkpoint cumulative row exposures: **200,000**; selected cumulative distinct rows: **200,000**.
+
+- A fixed 20,000-example development set selects this checkpoint. The complete 412,873-example development partition compares the two 200k Qwen4B adaptation methods.
+
+## Performance and matched comparisons
+
+**Language:** English. **Inference precision:** BF16 Qwen backbone with FP32 candidate scoring.
+
+The common held-out test contains **240,458 QA records**, **119 question versions** and **8,275 respondent/household groups**. The checkpoint is selected using development data before this test.
+
+| Checkpoint / reference | Accuracy (%) | Question-macro F1 (%) | Invalid decisions |
+|---|---:|---:|---:|
+| **FinQ · Qwen3.5-4B-Base + LoRA + head · 200k QA** | **74.1435** | **36.7343** | **0** |
+| Qwen4B head only, same 200k unique QA | 67.2841 | 30.8995 | 0 |
+
+Accuracy weights every test record equally; invalid decisions count as incorrect. Question-macro F1 averages over every defined candidate class within each question version and then weights the 119 versions equally.
+
+The head-only reference uses the same pretrained backbone, unique examples and common test, with its backbone fixed. This checkpoint also adapts the backbone representation through LoRA.
+
+## Package and inference
+
+LoRA adapter plus a shared scalar decision head; obtain the official backbone separately.
+
+The 4B initialization is the official pre-trained-only Base release.
+
+- Model files: `head.pt, adapter/adapter_config.json, adapter/adapter_model.safetensors`.
+
+- Reported common-test compute: BF16 Qwen backbone with FP32 candidate scoring.
+
+- Obtain the official Qwen backbone and tokenizer named in the configuration separately.
+
+- Inference scores the full state, question and complete candidate menu.
+
+The supplied `qwen_decision.py` exposes the candidate-scoring inference interface. Supply the local package and the official backbone and tokenizer named in `decision_config.json`.
+
+## License and access
+
+The project model contribution is offered under the [S²-MAS Controlled Model Research License v1.2](LICENSE): noncommercial scientific use, no redistribution, and no unauthorized reverse engineering, extraction or distillation. Training and evaluation records are not distributed. Source-data access requires the provider's authorization. Permission requests: yli9919@hku.hk.
+
+Project repository: [s2-mas](https://github.com/KataDavidXD/s2-mas).

Model_Card_ZH.md

@@ -0,0 +1,86 @@
+---
+
+license: other
+license_name: s2-mas-controlled-research-v1.2
+license_link: https://huggingface.co/ya9919/FinQ/blob/main/LICENSE
+
+language:
+
+- en
+
+base_model: Qwen/Qwen3.5-4B-Base
+
+tags:
+
+- s2-mas
+
+- financial-qa
+
+- decision-head
+
+- qwen3_5
+
+- peft
+
+- lora
+
+---
+
+# FinQ · Qwen3.5-4B-Base + LoRA + 决策 head · 200k QA
+
+## 模型命名与实验标签
+
+**FinQ——Qwen3.5-4B-Base + LoRA + 决策 head，200,000 条独立 QA** 指本仓库按 development 协议选出的 best checkpoint。[**FinL**](https://huggingface.co/ya9919/FinL) 是并列的英语基座完整六轮 encoder 路线，[**FinL-mlx**](https://huggingface.co/ya9919/FinL-mlx) 是其 MLX FP16 运行格式。上游模型名称保持为 **Qwen/Qwen3.5-4B-Base**；head-only、50k 和 9B Qwen 版本继续使用明确的比较版本名称。
+
+论文：[S²-MAS](https://github.com/KataDavidXD/s2-mas/blob/main/paper/S2_MAS_Paper.pdf)。本卡片的比较口径为固定预算适配结果与相同下游评测方法。
+
+## 项目背景
+
+S²-MAS 是面向社会规模的多智能体仿真框架，用于研究家庭决策对消费、现金储备与支付的影响。论文将 **5 亿条构造家庭 persona 记录**、学习得到的决策策略、可复用金融场景与状态转移引擎连接起来；购置融资应用评估 **1,200 万个独立合成家庭 agent**。完整数据训练的 FinL 为该应用提供策略，本仓库的 FinQ 则是共同决策模型比较中的固定预算适配 checkpoint。决策学习使用 real-survey data；GENESE／MAS 引擎实现保持私有。
+
+共同 benchmark 将十二个系统分为六类决策路线：encoder 选项评分、语言模型与学习得到的决策 head、next-token 决策 SFT、动态 schema 分类、多模态 encoder 决策以及 provider 决策接口。共同 benchmark 均使用文本输入。**17 个模型仓库条目**包括 **10 个固定预算训练版本**（5 个原生 Laya、5 个 Qwen 版本）、**6 个 checkpoint／运行格式条目**及 **1 个兼容入口**。
+
+## 本模型的角色
+
+FinQ 采用**语言模型与学习得到的决策 head 路线**。LoRA adapter 与共享标量决策 head 在 Qwen3.5-4B-Base 上联合训练；相同 200k 预算的 head-only 比较版本保持 backbone 固定，用于衡量表征适配的作用。完整 development 分区先比较两种 200k Qwen4B 适配方法并选出 LoRA 方法，再进行单独的 9B 训练。
+
+## 训练设计与 checkpoint
+
+- 方法：`lora`。
+- 独立下游训练记录：固定决策 QA training 分区中的 **200,000 条**。
+- 初始化：[Qwen/Qwen3.5-4B-Base](https://huggingface.co/Qwen/Qwen3.5-4B-Base)，官方仅预训练 Base 版本。
+- 本阶段终点 row exposures：**200,000**；选中 checkpoint 的本阶段 exposures：**200,000**。
+- 选中 checkpoint 的累计 row exposures：**200,000**；累计独立记录：**200,000**。
+- 固定 **20,000 条** development 样本选择本 checkpoint；完整 **412,873 条** development 分区比较两种 200k Qwen4B 适配方法。
+
+## 性能与相同比较口径
+
+**输入语言：**英语。**推理精度：**BF16 Qwen backbone，FP32 候选评分。
+
+共同 held-out test 包含 **240,458 条 QA**、**119 个问题版本**及 **8,275 个受访者／家庭组**。checkpoint 在读取该测试之前通过 development 数据选定。
+
+| Checkpoint／比较版本 | Accuracy (%) | Question-macro F1 (%) | 无效选择 |
+|---|---:|---:|---:|
+| **FinQ · Qwen3.5-4B-Base + LoRA + head · 200k QA** | **74.1435** | **36.7343** | **0** |
+| Qwen4B head-only，相同 200k 独立 QA | 67.2841 | 30.8995 | 0 |
+
+Accuracy 对每条测试记录等权，无效选择计为错误。Question-macro F1 先在每个问题版本内对完整候选类别的 F1 取平均，再对 119 个版本等权平均。
+
+Head-only 比较版本使用相同预训练 backbone、独立样本与共同测试，保持 backbone 固定；FinQ 同时通过 LoRA 适配 backbone 表征。
+
+## 模型包与推理
+
+本模型包包含 LoRA adapter 与共享标量决策 head；官方 backbone 及 tokenizer 需单独取得。
+
+- 模型文件：`head.pt`、`adapter/adapter_config.json`、`adapter/adapter_model.safetensors`。
+- 共同测试使用 BF16 Qwen backbone 与 FP32 候选评分。
+- 单独取得配置所指定的官方 Qwen backbone 与 tokenizer。
+- 推理对完整状态、问题和全部候选菜单评分。
+
+配套 `qwen_decision.py` 提供候选评分推理接口，传入本地模型包及 `decision_config.json` 指定的官方 backbone 和 tokenizer。
+
+## 许可与访问
+
+项目模型贡献适用 [S²-MAS Controlled Model Research License v1.2](LICENSE)：限非商业科学研究，不得再分发，不得未经授权进行逆向工程、提取或蒸馏。训练与评估记录不随模型分发；来源数据访问须取得 provider 授权。许可申请：yli9919@hku.hk。
+
+项目仓库：[s2-mas](https://github.com/KataDavidXD/s2-mas)。

README.md

@@ -2,7 +2,7 @@
 
 license: other
 license_name: s2-mas-controlled-research-v1.2
-license_link: https://huggingface.co/ya9919/qwen3.5-4b-base-finance-lora-head-200k/blob/main/LICENSE
+license_link: https://huggingface.co/ya9919/FinQ/blob/main/LICENSE
 
 language:
 
@@ -26,19 +26,23 @@ tags:
 
 ---
 
-# qwen3.5-4b-base-finance-lora-head-200k
+# FinQ · Qwen3.5-4B-Base + LoRA + decision head · 200k QA
+
+## Model naming and experiment labels
+
+**FinQ — Qwen3.5-4B-Base + LoRA + learned decision head, 200k distinct QA** names this selected best checkpoint. [**FinL**](https://huggingface.co/ya9919/FinL) is the parallel full English-base six-round encoder route, and [**FinL-mlx**](https://huggingface.co/ya9919/FinL-mlx) is its MLX FP16 runtime. The original upstream model remains **Qwen/Qwen3.5-4B-Base**. Head-only, 50k and 9B Qwen checkpoints retain their explicit comparator names.
 
 Paper: [S²-MAS](https://github.com/KataDavidXD/s2-mas/blob/main/paper/S2_MAS_Paper.pdf). The fixed-budget adaptation results and matched downstream methods define the comparison reported here.
 
 ## Project background
 
-S²-MAS is a society-scale multi-agent simulation framework for studying how household decisions affect consumption, cash reserves and payments. The paper connects a constructed resource of **500 million household-persona records**, learned decision policies, reusable financial scenarios and a state-transition engine. Its purchase-funding application evaluates **12 million distinct synthetic household agents** under paired conditions. Full-data Fin-Laya supplies the policy for that application; this repository supplies a fixed-budget adaptation checkpoint for the common decision-model comparison. Decision learning uses **real-survey data**. The GENESE/MAS engine implementation remains private.
+S²-MAS is a society-scale multi-agent simulation framework for studying how household decisions affect consumption, cash reserves and payments. The paper connects a constructed resource of **500 million household-persona records**, learned decision policies, reusable financial scenarios and a state-transition engine. Its purchase-funding application evaluates **12 million distinct synthetic household agents** under paired conditions. Full-data FinL supplies the policy for that application; this repository supplies a fixed-budget adaptation checkpoint for the common decision-model comparison. Decision learning uses **real-survey data**. The GENESE/MAS engine implementation remains private.
 
 The benchmark groups twelve systems into six decision-model routes: encoder option scoring; language models with learned decision heads; next-token decision SFT; dynamic-schema classification; multimodal encoder decisions; and provider decision interfaces. All receive text inputs in the common benchmark. The **17 model-repository entries** comprise **10 fixed-budget trained variants**—five native Laya and five Qwen variants—plus **six checkpoint/runtime entries** and **one compatibility alias**.
 
 ## This model's role
 
-This checkpoint follows the **language-model plus learned decision-head route**. LoRA adapters and a shared scalar decision head are trained together on Qwen3.5-4B-Base. The 200k head-only counterpart holds the backbone fixed, allowing the comparison to assess representation adaptation. The complete development partition selects this LoRA method before the separate 9B run.
+**FinQ** follows the **language-model plus learned decision-head route**. LoRA adapters and a shared scalar decision head are trained together on Qwen3.5-4B-Base. The 200k head-only counterpart holds the backbone fixed, allowing the comparison to assess representation adaptation. The complete development partition selects this LoRA method before the separate 9B run.
 
 ## Training design and checkpoint
 
@@ -62,7 +66,7 @@ The common held-out test contains **240,458 QA records**, **119 question version
 
 | Checkpoint / reference | Accuracy (%) | Question-macro F1 (%) | Invalid decisions |
 |---|---:|---:|---:|
-| **This checkpoint** | **74.1435** | **36.7343** | **0** |
+| **FinQ · Qwen3.5-4B-Base + LoRA + head · 200k QA** | **74.1435** | **36.7343** | **0** |
 | Qwen4B head only, same 200k unique QA | 67.2841 | 30.8995 | 0 |
 
 Accuracy weights every test record equally; invalid decisions count as incorrect. Question-macro F1 averages over every defined candidate class within each question version and then weights the 119 versions equally.