| # 📈 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! |