# 📈 PySD Streamlit App with Hugging Face Transformers

This Streamlit app allows you to:
- Upload **System Dynamics** models in `.mdl` (Vensim) or `.xmile` format
- Run simulations using [`PySD`](https://github.com/SDXorg/pysd)
- Visualize time series results
- Ask **LLM-powered questions** about your model using the Hugging Face `mistralai/Mistral-7B-Instruct` model

---

## 🚀 Features

✅ Upload and simulate `.mdl` or `.xmile` models  
✅ Visualize model outputs as time-series plots  
✅ Ask natural language questions about model logic  
✅ Integrates with Hugging Face-hosted Transformer APIs

---

## 🧱 Installation & Usage

### Step 1: Deploy as a Hugging Face Space
- Create a new [Hugging Face Space](https://huggingface.co/spaces) and select:
  - **SDK:** Streamlit
  - **Python version:** 3.8+

### Step 2: Upload Project Files
Upload the following files to the root of your Space:
- `app.py`
- `requirements.txt`
- `README.md`

### Step 3: Set up Hugging Face Token (Optional but Recommended)
To enable transformer-powered Q&A about your model:

#### Option 1: Use Streamlit Secrets
1. Go to your HF Space → **Settings → Secrets**
2. Add the secret key:
   ```
   HF_API_TOKEN = your_hf_token_here
   ```

#### Option 2: Enter Token in App
If no token is saved in secrets, the app will prompt you to enter it interactively.

---

## 💬 Example Questions

- “What causes the temperature to drop?”
- “Which variables form a feedback loop?”
- “Explain the relationship between stock and flow.”

---

## 📦 Dependencies

The app uses:
- `streamlit`
- `pysd`
- `matplotlib`
- `pandas`
- `requests`
- `lxml`

All dependencies are listed in `requirements.txt`.

---

## 🧠 LLM-Powered Q&A

The transformer model is queried through the [Hugging Face Inference API](https://huggingface.co/inference-api):
- Model: `mistralai/Mistral-7B-Instruct-v0.1`
- Input: Parsed model component structure from PySD
- Output: Natural language explanations

---

## 🔒 Notes

- Hugging Face Spaces have limited RAM; large models or simulations may timeout
- The `.mdl` model must follow Vensim conventions compatible with PySD
- Advanced CLD/SFD visualization will be added in future releases

---

## 📞 Questions or Feedback?

Please feel free to fork or raise an issue on the repo or Hugging Face space. Contributions welcome!