Update README.md

README.md

@@ -1,202 +1,137 @@
 ---
-base_model: mistralai/Mistral-7B-v0.1
-library_name: peft
+license: apache-2.0
+base_model:
+- mistralai/Mistral-7B-Instruct-v0.3
 ---
+# Introduction
 
-# Model Card for Model ID
+## Task Description
+This model was fine-tuned to improve its ability to perform spatial
+reasoning tasks. The objective is to enable the model to interpret natural language queries related to
+spatial relationships, directions, and locations and output actionable responses.
+The task addresses limitations in current LLMs, which often fail to perform precise spatial reasoning,
+such as determining relationships between points on a map, planning routes, or identifying locations
+based on bounding boxes. 
 
-<!-- Provide a quick summary of what the model is/does. -->
+## Task Importance
+Spatial reasoning is important for a wide range of applications such as navigation and geospatial
+analysis. Many smaller LLMs, while strong in general reasoning, often lack the ability to interpret
+spatial relationships with precision or utilize real-world geographic data effectively. For example, they
+struggle to answer queries like “What’s between Point A and Point B?” or “Find me the fastest route
+avoiding traffic at 8 AM tomorrow.” I came across this limitation through my work, in which I am
+working on prompt engineering for an LLM project that has agentic behavior in calling a geocoding
+API. Even when the LLM has access to geospatial information, smaller models struggled to correctly
+interpret user questions, so we had to switch to a much newer and larger model. 
 
+## Related Work/Gap Analysis
 
+While there is ongoing research in integrating LLMs with geospatial systems, most existing solutions
+rely on symbolic AI or rule-based systems rather than leveraging the generalization capabilities of
+LLMs. Additionally, the paper “Advancing Spatial Reasoning in Large Language Models: An In-Depth
+Evaluation and Enhancement Using the StepGame Benchmark,” concluded that larger models like
+GPT-4 perform well in mapping natural language descriptions to spatial relations but struggle with
+multi-hop reasoning. This paper used the StepGame as a benchmark for spatial reasoning.
+Fine-tuning a model fills the gap identified in the paper, as the only solutions identified in their
+research was prompt engineering with Chain of Thought.
 
-## Model Details
+Research by organizations like OpenAI and Google has focused on improving contextual reasoning
+through fine-tuning, but there is limited work targeting spatial reasoning.
 
-### Model Description
+## Main Results
 
-<!-- Provide a longer summary of what this model is. -->
 
 
+# Training Data
 
-- **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]
+For this fine-tuning task the step-game dataset was used. This dataset is large and provides multi-step
+reasoning challenges for geospatial reasoning. The train-test split is predefined with 50,000 rows in the train split and 10,000 in the test
+split. It focuses on multi-step problem-solving with
+spatial relationships, such as directional logic, relative positioning, and route-based reasoning. It
+presents text-based tasks that require stepwise deductions, ensuring the model develops strong
+reasoning abilities beyond simple fact recall. This dataset follows the template of story,
+question and answer to assess spatial reasoning as depicted below.
 
-### Model Sources [optional]
+![Description of StepGame Training Data](https://huggingface.co/sareena/spatial_lora_mistral/resolve/main/stepgame.jpg)
 
-<!-- Provide the basic links for the model. -->
 
-- **Repository:** [More Information Needed]
-- **Paper [optional]:** [More Information Needed]
-- **Demo [optional]:** [More Information Needed]
+# Training Method
 
-## Uses
+For this task of spatial reasoning LoRA (Low-Rank Adaptation)  was used as the training method. 
+LoRA allows for efficient fine-tuning of large language models by freezing the majority of the model weights and only updating small, 
+low-rank adapter matrices within attention layers. It significantly reduces the computational cost and memory requirements of full 
+fine-tuning, making it ideal for working with limited GPU resources. LoRA is especially effective for task-specific
+adaptation when the dataset is moderately sized and instruction formatting is consistent as in the case of this dataset of stepGame. 
+In previous experiments with spatial reasoning fine-tuning, LoRA performed better than prompt tuning. While prompt tuning resulted in close to 0% accuracy on both the StepGame and
+MMLU evaluations, LoRA preserved partial task performance (18% accuracy) and retained some general knowledge ability (46% accuracy on 
+MMLU geography vs. 52% before training). I used a learning rate of 2e-4, batch size of 8, and trained for 2 epochs. 
+This setup preserved general reasoning ability while improving spatial accuracy.
 
-<!-- Address questions around how the model is intended to be used, including the foreseeable users of the model and those affected by the model. -->
+# Evaluation
 
-### Direct Use
 
-<!-- This section is for the model use without fine-tuning or plugging into a larger ecosystem/app. -->
 
-[More Information Needed]
+# Usage and Intended Uses
+This model is designed to assist with natural language spatial reasoning, particularly in tasks that involve multi-step relational 
+inference between objects or locations described in text. This could be implemented in agentic spatial systems and/or text-based game bots.
 
-### Downstream Use [optional]
 
-<!-- This section is for the model use when fine-tuned for a task, or when plugged into a larger ecosystem/app -->
 
-[More Information Needed]
+```python
+from transformers import AutoTokenizer, AutoModelForCausalLM
+import torch
 
-### Out-of-Scope Use
+model = AutoModelForCausalLM.from_pretrained("sareena/spatial_lora_mistral")
+tokenizer = AutoTokenizer.from_pretrained("sareena/spatial_lora_mistral")
 
-<!-- This section addresses misuse, malicious use, and uses that the model will not work well for. -->
+inputs = tokenizer("Q: The couch is to the left of the table. The lamp is on the couch. Where is the lamp?", return_tensors="pt")
+outputs = model.generate(**inputs, max_new_tokens=50)
+print(tokenizer.decode(outputs[0], skip_special_tokens=True))
 
-[More Information Needed]
+```
 
-## Bias, Risks, and Limitations
+# Prompt Format
+The model is trained on instruction-style input with a spatial reasoning question:
 
-<!-- This section is meant to convey both technical and sociotechnical limitations. -->
+```text
+Q: The couch is to the left of the table. The lamp is on the couch. Where is the lamp in relation to the table?
+```
 
-[More Information Needed]
+# Expected Output Format
+The output is a short, natural language spatial answer:
 
-### Recommendations
+```text
+A: left 
+```
 
-<!-- This section is meant to convey recommendations with respect to the bias, risk, and technical limitations. -->
+# 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.
+The model is still limited in deep reasoning capabilities and sometimes fails multi-hop spatial tasks. 
+LoRA helps balance this trade-off, but fine-tuning on more diverse spatial tasks could yield stronger generalization. 
+)erformance on the SpatialEval benchmark dropped drastically, due to incompatibility between the prompt style used for training and the
+multiple-choice formatting in SpatialEval. Future work to remediate this would be to test more prompt formats in training or use instruction-tuned datasets
+more similar to the downstream evaluations.m 
 
-## How to Get Started with the Model
+## Citation 
 
-Use the code below to get started with the model.
+1. **Hendrycks, Dan**, Collin Burns, Steven Basart, Andy Zou, Mantas Mazeika, Dawn Song, and Jacob Steinhardt.  
+   *"Measuring Massive Multitask Language Understanding."* arXiv preprint arXiv:2009.03300 (2020).
 
-[More Information Needed]
+2. **Li, Fangjun**, et al.  
+   *“Advancing Spatial Reasoning in Large Language Models: An in-Depth Evaluation and Enhancement Using the StepGame Benchmark.”*  
+   *arXiv.Org*, 8 Jan. 2024. [https://arxiv.org/abs/2401.03991](https://arxiv.org/abs/2401.03991)
 
-## Training Details
+3. **Mirzaee, Roshanak**, Hossein Rajaby Faghihi, Qiang Ning, and Parisa Kordjamshidi.  
+   *"SpartQA: A Textual Question Answering Benchmark for Spatial Reasoning."* arXiv preprint arXiv:2104.05832 (2021).
 
-### Training Data
+4. **Shi, Zhengxiang**, et al.  
+   *“StepGame: A New Benchmark for Robust Multi-Hop Spatial Reasoning in Texts.”*  
+   *arXiv.Org*, 18 Apr. 2022. [https://arxiv.org/abs/2204.08292](https://arxiv.org/abs/2204.08292)
 
-<!-- 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. -->
+5. **Shi, Zhengxiang**, Qiang Zhang, and Aldo Lipani.  
+   *"StepGame: A New Benchmark for Robust Multi-Hop Spatial Reasoning in Texts."* arXiv preprint arXiv:2204.08292 (2022).
 
-[More Information Needed]
+6. **Wang, Mila**, Xiang Lorraine Li, and William Yang Wang.  
+   *"SpatialEval: A Benchmark for Spatial Reasoning Evaluation."* arXiv preprint arXiv:2104.08635 (2021).
 
-### 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]
-### Framework versions
-
-- PEFT 0.15.1
+7. **Weston, Jason**, Antoine Bordes, Sumit Chopra, and Tomas Mikolov.  
+   *"Towards AI-Complete Question Answering: A Set of Prerequisite Toy Tasks."* arXiv preprint arXiv:1502.05698 (2015).