A compact, TypeScript-first rewrite of the System Dynamics Bot. The tool extracts causal relationships from text and optionally generates causal loop diagram artifacts. This README explains how to install, run, test, and programmatically call the TypeScript API and CLI.
- CLI and programmatic TypeScript API
- Supports local Ollama HTTP backend or OpenAI (remote)
- Choose chat (LLM) and embedding models per-run (flags or programmatic options)
- Unit tests (Vitest) and an opt-in E2E test that calls a local Ollama instance
Node 18+ and npm are recommended.
- Install dependencies:
cd /path/to/System-Dynamics-Bot
npm install
npm run build- Optional: run tests
# unit tests only
npm test
# run opt-in Ollama E2E (set USE_OLLAMA=1, RUN_OLLAMA_E2E=1 and OLLAMA_URL)
USE_OLLAMA=1 OLLAMA_URL=http://localhost:11434 RUN_OLLAMA_E2E=1 npm test- USE_OLLAMA (1/true or empty) — prefer local Ollama HTTP API when truthy
- OLLAMA_URL — default:
http://localhost:11434 - OLLAMA_CHAT_MODEL — default used for Ollama chat if not specified programmatically
- OLLAMA_EMBEDDING_MODEL — default used for Ollama embeddings if not specified programmatically
- OPENAI_API_KEY — required if
USE_OLLAMAis false and you want to use OpenAI
The code will prefer programmatic model names passed to the API. If not provided, it falls back to env vars and then sensible defaults.
After building, the CLI entrypoint is dist/index.js (package.json also provides a sdbot bin). Example:
# interactive (will open an editor to enter the problem description)
npx ts-node src/index.ts
# read input from file and save XMILE + DOT
npx ts-node src/index.ts -i my_text.txt -x -d --llm-model gpt-oss:20b --embedding-model bge-m3:latest
# short flags
npx ts-node src/index.ts --input=my_text.txt --diagram --xmile --llm-model=gpt-oss:20bCLI flags (important ones):
-v, --verbose— enable internal logging-d, --diagram— generate DOT diagram-w, --write-relationships— write relationships.txt-x, --xmile— produce XMILE file-t, --threshold <n>— embedding similarity threshold (default 0.85)--llm-model <model>— override chat/LLM model for this run (preferred)--embedding-model <model>— override embedding model for this run (preferred)-i, --input <file>— read the input text from file
If you omit --llm-model or --embedding-model, the code will try environment variables and then built-in defaults.
Import and call the exported GreatSage class. It returns a structured result (no direct file I/O) so callers can decide what to save.
Example:
import GreatSage from './dist/sage'
const sage = new GreatSage({
verbose: false,
diagram: true,
xmile: true,
write_relationships: true,
threshold: 0.85,
question: 'Engineers compare the work remaining to be done against the time remaining before the deadline...',
// Optional: prefer using local Ollama models for this run
llmModel: 'gpt-oss:20b',
embeddingModel: 'bge-m3:latest'
})
const result = await sage.think()
console.log(result.response) // numbered relationships
console.log(result.lines) // array of individual relationship strings
if (result.xmile) writeFileSync('diagram.xmile', result.xmile)
if (result.dot) writeFileSync('diagram.dot', result.dot)Constructor options (key fields):
question(string) — required text to analyzethreshold(number) — similarity threshold (default 0.85)llmModel(string, optional) — chat model name to use this run (overrides env)embeddingModel(string, optional) — embedding model name to use this run (overrides env)verbose,diagram,xmile,write_relationships— behavior toggles
Return value of think() (object):
response(string) — the numbered relationships outputlines(string[]) — deduplicated relationship stringsxmile(string | undefined) — XMILE XML when requesteddot(string | undefined) — Graphviz DOT diagram when requested
- If
USE_OLLAMAis set, the library will call the local Ollama HTTP API. It tries to be lenient about endpoint shapes and supports both/api/chatand/api/generate(fallback). - When using Ollama, prefer passing model names programmatically or via
OLLAMA_CHAT_MODELandOLLAMA_EMBEDDING_MODELenvironment vars. - If
USE_OLLAMAis not set, the code will use OpenAI viaOPENAI_API_KEY.
- Unit tests:
npm test(Vitest) - Opt-in E2E test that hits a local Ollama instance: set
USE_OLLAMA=1,OLLAMA_URL, andRUN_OLLAMA_E2E=1.
- If the E2E test fails with a 404, ensure your Ollama server is running and that the chosen model supports chat (or pass a chat-capable model with
--llm-model). - If embeddings appear empty from Ollama, set an explicit
--embedding-modelpointing to a model that provides embeddings (for examplebge-m3:latest).
Open issues or PRs for bugs, improvements, or documentation fixes.
If you want, I can also add a short quickstart script that pulls recommended Ollama models and runs the opt-in E2E locally.
This repository includes the code and supplementary materials for the paper: From Text to Map: A System Dynamics Bot for Constructing Causal Loop Diagrams (arXiv link) (Paper)
Abstract: We introduce and test the System Dynamics Bot, a computer program leveraging a large language model to automate the creation of causal loop diagrams from textual data. To evaluate its performance, we ensembled two distinct databases. The first dataset includes 20 causal loop diagrams and associated texts sourced from system dynamics literature. The second dataset comprises responses from 30 participants to the Lake Urmia Vignette, along with causal loop diagrams coded by three system dynamics modelers. The bot uses textual data and successfully identifies approximately sixty percent of the links between variables and feedback loops in both datasets. This paper outlines our approach, provides examples, and presents evaluation results. We discuss encountered challenges and implemented solutions in developing the System Dynamics Bot. The Bot can facilitate extracting mental models from textual data and improve model building processes. Moreover, the two datasets can serve as a testbed for similar programs.
An OpenAI API key is required to use this application. A user can create an account with OpenAI, navigate to the API key page and click on "Create new secret key", optionally naming the key. Make sure that you have GPT-4 access, and save your API key somewhere safe and do not share it with anyone.
Since some people have been having trouble with running the SD Bot, I have created a very simple application to run on Windows. Just download it and double click on the .exe file to get started. If you are a developer wanting to modify this program, you are free to follow the steps I have outlined below.
Ensure that you have Python 3.8+ and C++ installed. If you do not have Python, you can download it from the official website. Make sure Python is added to your PATH.
For C++, I have included the executable file here. These are essential prerequisites, so ensure they are installed before proceeding.
Download and install Graphviz. During installation, ensure the option to add Graphviz to PATH is checked. Verify Graphviz is on PATH by running dot -V in a new terminal. If dot is not recognized, manually add Graphviz to PATH. Typically, the directory is something like C:\Program Files\Graphviz\bin. After adding it, run dot -V again to confirm.
Run the following command to install Pygraphviz:
python -m pip install --use-pep517 --config-setting="--global-option=build_ext" --config-setting="--global-option=-IC:\Program Files\Graphviz\include" --config-setting="--global-option=-LC:\Program Files\Graphviz\lib" pygraphvizPlease verify that the locations C:\Program Files\Graphviz\include and C:\Program Files\Graphviz\lib are correct before you run this code.
Run pip install -r requirements.txt to install the required python packages.
Set your OpenAI API key as your environment variable. You can do this easily by typing set OPENAI_API_KEY=your-api-key or $env:OPENAI_API_KEY = "your-api-key" if you are using Powershell.
Unix based systems already have C++ and Python installed, so you can skip those installation processes. You can install Graphviz by running sudo apt-get install graphviz graphviz-dev. As before, please ensure that Graphviz installation directory is on PATH. In Linux systems, it usually gets added to PATH by default.
The next step is installing the required packages by running pip install -r requirements.txt. Please install pygraphviz separately by running pip install pygraphviz.
Set your OpenAI API key as your environment variable by running export OPENAI_API_KEY="your_api_key". You can verify that you've added the API key by running printenv OPENAI_API_KEY.
Remember that this environment variable exists only during this session so you have to do this every time you want to run the code. I'd recommend not adding the API key permanently due to security concerns.
Minimal steps to get the project running (macOS/Linux):
- Create and activate a virtual environment, then install Python deps:
cd /path/to/System-Dynamics-Bot
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip setuptools wheel
pip install -r requirements.txt- Choose your model backend:
- Use Ollama (local LLM) — recommended if you run
ollamalocally:
export USE_OLLAMA=1
export OLLAMA_URL="http://localhost:11434" # change if your Ollama HTTP port differs- Or use OpenAI (remote API):
export USE_OLLAMA=0
export OPENAI_API_KEY="sk-..."- Run the bot interactively from the
cldfolder:
cd cld
python main.py --verboseTip: If you want the bot to generate a diagram, add --diagram and ensure Graphviz + pygraphviz are installed on your system.
If you prefer an automated helper, run the included setup.sh which creates the venv, installs packages, and can optionally pull the gpt-oss:20b model for Ollama:
./setup.sh --skip-ollama # create venv + install Python deps but don't install/pull Ollama
./setup.sh # attempt to install/pull Ollama (Homebrew on macOS)You can run the System Dynamics Bot by navigating to the cld folder and running python main.py --arg1 --arg2.
The list of arguments are given below:
- --verbose: Specifying this flag allows you to see all the inner workings of the System Dynamics Bot
- --diagram: Specifying this flag tells the System Dynamics Bot to actually create the CLD diagram and saves it in the current working directory.
If you use this code, please cite the following:
Hosseinichimeh, N., Majumdar, A., Williams, R., & Ghaffarzadegan, N. (2024). From Text to Map: A System Dynamics Bot for Constructing Causal Loop Diagrams. ArXiv, abs/2402.11400.
@article{https://doi.org/10.1002/sdr.1782,
author = {Hosseinichimeh, Niyousha and Majumdar, Aritra and Williams, Ross and Ghaffarzadegan, Navid},
title = {From text to map: a system dynamics bot for constructing causal loop diagrams},
journal = {System Dynamics Review},
volume = {n/a},
number = {n/a},
pages = {e1782},
doi = {https://doi.org/10.1002/sdr.1782},
url = {https://onlinelibrary.wiley.com/doi/abs/10.1002/sdr.1782},
eprint = {https://onlinelibrary.wiley.com/doi/pdf/10.1002/sdr.1782},
abstract = {Abstract We introduce and test the System Dynamics Bot, a computer program leveraging a large language model to automate the creation of causal loop diagrams from textual data. To evaluate its performance, we ensembled two distinct databases. The first dataset includes 20 causal loop diagrams and associated texts sourced from the system dynamics literature. The second dataset comprises responses from 30 participants to a vignette, along with causal loop diagrams coded by three system dynamics modelers. The bot uses textual data and successfully identifies approximately 60\% of the links between variables and feedback loops in both datasets. This article outlines our approach, provides examples, and presents evaluation results. We discuss encountered challenges and implemented solutions in developing the System Dynamics Bot. The bot can facilitate extracting mental models from textual data and improve model-building processes. Moreover, the two datasets can serve as a test-bed for similar programs. © 2024 The Author(s). System Dynamics Review published by John Wiley \& Sons Ltd on behalf of System Dynamics Society.}
}If you have any questions about the code, please feel free to open an issue in this repository.
This code is provided for non-commercial use only. You are free to use, modify, and distribute the code for personal or educational purposes. However, any commercial use is strictly prohibited without prior written consent as stated in Attribution-NonCommercial 4.0 International.