Causal Loop Diagramming With Mermaid JS

Causal Loop Diagram Style Guide for MermaidJS

Table of Contents

• About The Project
• Getting Started
• Organization Rules/ Style Guide
• Why
• Next Steps
• Contribute

About the project

This a project for creating causal loop diagrams that are shareable,iteratively editable, and able to be generated using LLMs using mermaidjs. The goal is to make CLDs more accessible. In addition the goal is to expand the language to support CLDs specifically in token engineering, as well as interactive diagrams that can be generated bidirectionally

The bot

Chat GPT - Casually Looped - [https://chat.openai.com/g/g-OU7Zqt6Lh-casually-looped] simply prompt a system you'd like to genenerate a CLD for. and it will generate a CLD of your choosing, and try to provide context for what that looks like. High Level Curve Defi LP Rewards CLD example

The Spec

Getting Started

To use this simply go to MermaidJS Live and copy the example from the template.mmd file and launch or Use this from your IDE like VS-code or just get started on your own with a blank graph

graph LR

%% class def at the bottom adds a transparecy to the nodes
classDef tr fill:#00000000, stroke:#00000000;

Style Guide

1. Nodes should be initialized at the top of the graph

graph LR
    fooState["foo"]:::tr
    barState["bar"]:::tr
    %% fooState[some label text here] allows us to initialize node with no connections
    %% it allows us to have an easy reference to the label

    %% class def at the bottom adds a transparecy to the nodes
classDef tr fill:#00000000, stroke:#00000000;

2. Nodes names should be camelCased

graph LR
    camelCaseState["camel"]:::tr
    barState["bar"]:::tr
    %% initialized 
    camelCaseState --> |+|barState
    barState --> |-|camelCaseState

%% class def at the bottom adds a transparecy to the nodes
classDef tr fill:#00000000, stroke:#00000000;

3. Outgoing links should be grouped together

graph LR
    fooState["foo"]:::tr
    barState["bar"]:::tr
    bazState["baz"]:::tr
    carState["car"]:::tr

    fooState -->|+| barState 
    fooState -->|-| carState 
    barState -->|+| bazState 
    barState -->|-| carState 
    bazState -->|-| carState 
    carState -->|+| barState 

%% class def at the bottom adds a transparecy to the nodes
classDef tr fill:#00000000, stroke:#00000000;

4. Directions should be normalized to point one way

graph LR
    someState["some"]:::tr
    otherState["other]:::tr
    someState --> otherState
    otherState --> someState
%% class def at the bottom adds a transparecy to the nodes
classDef tr fill:#00000000, stroke:#00000000;

Avoid

graph LR
    someState["some"]:::tr
    otherState["other]:::tr
    someState --> otherState
    someState <-- fooState

%% class def at the bottom adds a transparecy to the nodes
classDef tr fill:#00000000, stroke:#00000000;

5. classDefs go at the bottom of the file '

graph LR 
    someAction["action"]:::tr
    corrAction["correlated action"]:::tr

%% makes the node background transparent and outline transparent
classDef tr fill:#00000000, stroke:#00000000;

6. Delays in the graph are represented by //

graph LR 
    someAction["action"]:::tr
    corrAction["correlated action"]:::tr

    someAction -->|-//| corrAction
    corrAction -->|+| someAction

%% makes the node background transparent and outline transparent
classDef tr fill:#00000000, stroke:#00000000;

Why ?

Diagrams are an essential tool in token engineering. Not having a way to share,reuse, iterate,extend and collaborate on diagrams hurts. Additionnally with the emergence of LLMs, making tools that can interface with them is critical for being able to integrate with future tech and vastly improve accessibiiliity.

Let's start this token diagrams in code movement, with one of the most important diagrams that you encounter in token engineering, the Causal Loop Diagram.

Courtesy of Wikipedia

Causal Loop Diagrams are diagrams that help us visualize the relationships between entities. ‘+’ represent positively correlated relationships and ‘-’ negatively correlated relationships.

Early blog post on Casually Looped

The Bot Dive

Next Steps

• better LLM support
• improved naming convention think char limit
• ability to add notes to diagram
• improved generation for the diagrams
• meta language for describing CLDs including connection weights

Useful Communication Channels

Token Engineering Academy Discord

Token Engineering Commons Discord

Contribute

Create an issue and contribute to making codeable diagrams more widespread in the token engineering community