Update README.md

README.md

@@ -1,199 +1,141 @@
 ---
+license: apache-2.0
+base_model: Qwen/Qwen2.5-VL-3B-Instruct
+tags:
+  - multimodal
+  - vision-language
+  - visual-reasoning
+  - reinforcement-learning
+  - qwen2.5-vl
+  - math
+  - reasoning
+datasets:
+  - OpenMMReasoner-Data
+language:
+  - en
+pipeline_tag: image-text-to-text
 library_name: transformers
-tags: []
 ---
 
-# Model Card for Model ID
+# Frankenstein-IN
 
-<!-- Provide a quick summary of what the model is/does. -->
+**Frankenstein-IN** is the supervised fine-tuned (cold-start initialization) model from the paper:
 
+> **[What does RL improve for Visual Reasoning? A Frankenstein-Style Analysis](https://arxiv.org/abs/2602.12395)**
+>
+> Xirui Li\*, Ming Li\*, Tianyi Zhou
+>
+> University of Maryland &nbsp;|&nbsp; Mohamed bin Zayed University of Artificial Intelligence
+>
+> *(\* Co-first Authors)*
 
+This model serves as the **IN (Instruction-tuned) checkpoint** before reinforcement learning, built on the [OpenMMReasoner](https://arxiv.org/abs/2511.16334) training recipe with [Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct) as the base model.
 
-## Model Details
+## Overview
+
+Our paper introduces a **Frankenstein-style analysis framework** to understand *what* reinforcement learning (RL) actually improves in vision-language models (VLMs) for visual reasoning. Rather than relying on end-to-end benchmark scores, we decompose VLMs at the granularity of transformer layers and probe their functional roles through:
+
+1. **Functional Localization via Causal Probing** — localizing vision- and reasoning-related computations along transformer depth
+2. **Update Characterization via Parameter Comparison** — showing that IN and RL differ systematically in update magnitude and geometry
+3. **Transferability Test via Model Merging** — transplanting RL-refined regions into IN models to test causal contributions
 
-### Model Description
+### Key Findings
 
-<!-- Provide a longer summary of what this model is. -->
+- RL does **not** uniformly improve visual perception or standalone reasoning
+- RL induces **structured refinements concentrated in mid-to-late layers**, improving vision-to-reasoning alignment
+- These mid-to-late refinements are both **transferable** (via merging) and **necessary** (via freezing) for RL gains
+- Freezing **late layers** during RL training leads to a pronounced drop in reasoning performance
 
-This is the model card of a 🤗 transformers model that has been pushed on the Hub. This model card has been automatically generated.
+## Evaluation Results
 
-- **Developed by:** [More Information Needed]
-- **Funded by [optional]:** [More Information Needed]
-- **Shared by [optional]:** [More Information Needed]
-- **Model type:** [More Information Needed]
-- **Language(s) (NLP):** [More Information Needed]
-- **License:** [More Information Needed]
-- **Finetuned from model [optional]:** [More Information Needed]
+### Fine-grained and Benchmark Metrics
 
-### Model Sources [optional]
+| Model | Vision (M_vis) | Vision-to-Reasoning (M_v2r) | Reasoning (M_rea) | MathVista | MathVision | MathVerse |
+|:---|:---:|:---:|:---:|:---:|:---:|:---:|
+| **Frankenstein-IN** (this model) | 34.0 | 21.0 | 26.0 | 46.5 | 18.4 | 37.0 |
+| Frankenstein-RL | 33.0 | 29.0 | 34.0 | 48.1 | 14.1 | 37.8 |
 
-<!-- Provide the basic links for the model. -->
+### Parameter Freezing Analysis (RL Training)
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+| Model | Vision (M_vis) | Vision-to-Reasoning (M_v2r) | Reasoning (M_rea) | MathVista | MathVision | MathVerse |
+|:---|:---:|:---:|:---:|:---:|:---:|:---:|
+| RL - Frozen **Early** Block | **35.0** | **31.0** | 36.0 | **48.2** | **21.0** | 34.5 |
+| RL - Frozen **Mid** Block | 25.0 | 29.0 | **38.0** | 46.5 | 15.5 | **35.7** |
+| RL - Frozen **Late** Block | 30.0 | 27.0 | 34.0 | 47.9 | 16.8 | 35.0 |
 
-## Uses
+## Quick Start
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+### Installation
 
-### Direct Use
+```bash
+pip install transformers accelerate
+pip install qwen-vl-utils[decord]==0.0.8
+```
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
+### Inference
 
-[More Information Needed]
+```python
+from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor
+from qwen_vl_utils import process_vision_info
 
-### Downstream Use [optional]
+model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
+    "AIcell/Frankenstein-IN",
+    torch_dtype="auto",
+    device_map="auto",
+)
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
+processor = AutoProcessor.from_pretrained("AIcell/Frankenstein-IN")
 
-[More Information Needed]
+messages = [
+    {
+        "role": "user",
+        "content": [
+            {"type": "image", "image": "https://your-image-url.jpg"},
+            {"type": "text", "text": "Please solve this math problem step by step."},
+        ],
+    }
+]
 
-### Out-of-Scope Use
+text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+image_inputs, video_inputs = process_vision_info(messages)
+inputs = processor(
+    text=[text],
+    images=image_inputs,
+    videos=video_inputs,
+    padding=True,
+    return_tensors="pt",
+).to(model.device)
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+generated_ids = model.generate(**inputs, max_new_tokens=2048)
+generated_ids_trimmed = [
+    out_ids[len(in_ids):] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
+]
+output_text = processor.batch_decode(
+    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
+)
+print(output_text[0])
+```
 
-[More Information Needed]
-
-## Bias, Risks, and Limitations
-
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
-
-[More Information Needed]
-
-### Recommendations
-
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
-
-Users (both direct and downstream) should be made aware of the risks, biases and limitations of the model. More information needed for further recommendations.
-
-## How to Get Started with the Model
-
-Use the code below to get started with the model.
-
-[More Information Needed]
-
-## Training Details
-
-### Training Data
-
-<!-- This should link to a Dataset Card, perhaps with a short stub of information on what the training data is all about as well as documentation related to data pre-processing or additional filtering. -->
-
-[More Information Needed]
-
-### Training Procedure
-
-<!-- This relates heavily to the Technical Specifications. Content here should link to that section when it is relevant to the training procedure. -->
-
-#### Preprocessing [optional]
-
-[More Information Needed]
-
-
-#### Training Hyperparameters
-
-- **Training regime:** [More Information Needed] <!--fp32, fp16 mixed precision, bf16 mixed precision, bf16 non-mixed precision, fp16 non-mixed precision, fp8 mixed precision -->
-
-#### Speeds, Sizes, Times [optional]
-
-<!-- This section provides information about throughput, start/end time, checkpoint size if relevant, etc. -->
-
-[More Information Needed]
-
-## Evaluation
-
-<!-- This section describes the evaluation protocols and provides the results. -->
-
-### Testing Data, Factors & Metrics
-
-#### Testing Data
-
-<!-- This should link to a Dataset Card if possible. -->
-
-[More Information Needed]
-
-#### Factors
-
-<!-- These are the things the evaluation is disaggregating by, e.g., subpopulations or domains. -->
-
-[More Information Needed]
-
-#### Metrics
-
-<!-- These are the evaluation metrics being used, ideally with a description of why. -->
-
-[More Information Needed]
-
-### Results
-
-[More Information Needed]
-
-#### Summary
-
-
-
-## Model Examination [optional]
-
-<!-- Relevant interpretability work for the model goes here -->
-
-[More Information Needed]
-
-## Environmental Impact
-
-<!-- Total emissions (in grams of CO2eq) and additional considerations, such as electricity usage, go here. Edit the suggested text below accordingly -->
-
-Carbon emissions can be estimated using the [Machine Learning Impact calculator](https://mlco2.github.io/impact#compute) presented in [Lacoste et al. (2019)](https://arxiv.org/abs/1910.09700).
-
-- **Hardware Type:** [More Information Needed]
-- **Hours used:** [More Information Needed]
-- **Cloud Provider:** [More Information Needed]
-- **Compute Region:** [More Information Needed]
-- **Carbon Emitted:** [More Information Needed]
-
-## Technical Specifications [optional]
-
-### Model Architecture and Objective
-
-[More Information Needed]
-
-### Compute Infrastructure
-
-[More Information Needed]
-
-#### Hardware
-
-[More Information Needed]
-
-#### Software
-
-[More Information Needed]
-
-## Citation [optional]
-
-<!-- If there is a paper or blog post introducing the model, the APA and Bibtex information for that should go in this section. -->
-
-**BibTeX:**
-
-[More Information Needed]
-
-**APA:**
-
-[More Information Needed]
-
-## Glossary [optional]
-
-<!-- If relevant, include terms and calculations in this section that can help readers understand the model or model card. -->
-
-[More Information Needed]
-
-## More Information [optional]
-
-[More Information Needed]
-
-## Model Card Authors [optional]
-
-[More Information Needed]
-
-## Model Card Contact
-
-[More Information Needed]
+## Related Resources
+
+| Resource | Link |
+|:---|:---|
+| Paper | [arXiv:2602.12395](https://arxiv.org/abs/2602.12395) |
+| Frankenstein-RL Model | [AIcell/Frankenstein-RL](https://huggingface.co/AIcell/Frankenstein-RL) |
+| Base Model | [Qwen/Qwen2.5-VL-3B-Instruct](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct) |
+| OpenMMReasoner | [arXiv:2511.16334](https://arxiv.org/abs/2511.16334) |
+
+## Citation
+
+```bibtex
+@article{li2026frankenstein,
+  title={What does RL improve for Visual Reasoning? A Frankenstein-Style Analysis},
+  author={Li, Xirui and Li, Ming and Zhou, Tianyi},
+  journal={arXiv preprint arXiv:2602.12395},
+  year={2026}
+}
+```
+
+## License
+
+This model is released under the [Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).