CauseNet Graph Generator

This repository contains:

• a FastAPI backend that generates causal DAGs and converts DOT to BIFXML;
• a local web UI served by FastAPI at /;
• a static GitHub Pages frontend in docs/ that calls the hosted Heroku API.

Hosted App

The public frontend is served from docs/ with GitHub Pages:

• GitHub Pages frontend: https://clarg-group.github.io/CauseNet-graph-generator/
• Heroku API backend: https://causenet-generator-62eab5ce6946.herokuapp.com/

The GitHub Pages frontend is static HTML/JavaScript. It calls the Heroku backend for graph generation and BIFXML conversion. If you open the same UI from a local FastAPI server, it calls the local backend instead.

Setup Instructions

Download concept_embeddings.npy from:

• https://drive.google.com/file/d/1DPN7UkeEDDaWbligd0eXDyabAamKXM8Q/view?usp=sharing

The app can also download this file automatically the first time the semantic heuristic is used.

Run Locally

Clone the repository, install dependencies, and run the FastAPI app:

git clone https://github.com/CLArg-group/CauseNet-graph-generator.git
cd CauseNet-graph-generator
pip install -r requirements.txt
uvicorn main:app --host 0.0.0.0 --port 8000

Then open your browser and go to http://localhost:8000.

For local use, degrees and none work without any extra data file. The semantics heuristic uses concept_embeddings.npy from the app directory if present. If it is not present, the app downloads the public Google Drive file into /tmp/concept_embeddings.npy and memory-maps it.

Static Frontend

The static frontend lives at docs/index.html. It is intended for GitHub Pages or any other static host.

By default:

• when served from localhost, 127.0.0.1, or the Heroku app itself, it calls the same origin;
• when served from GitHub Pages, briziorusso.github.io, or another static domain, it calls https://causenet-generator-62eab5ce6946.herokuapp.com.

To point a copied frontend at another backend, set this before the main script:

<script>
  window.CAUSENET_API_BASE_URL = "https://your-backend.example.com";
</script>

To enable GitHub Pages for this repo:

1. Open Settings -> Pages.
2. Under Build and deployment, set Source to Deploy from a branch.
3. Set Branch to main and folder to /docs.
4. Save.

The docs/.nojekyll file tells GitHub Pages to serve the static HTML directly. GitHub documents this /docs publishing-source layout for project Pages sites.

If this repository remains private, GitHub Pages requires a plan that supports Pages for private repositories. On a free organization plan, make the repository public or publish the docs/ folder from a separate public frontend repository.

Deploy on Heroku

This repository includes the files Heroku needs to run the FastAPI app:

• .python-version selects Python 3.12.
• Procfile starts the web process with Uvicorn on Heroku's $PORT.
• requirements.txt lets Heroku detect the Python buildpack.

If your Heroku app is connected to GitHub, commit and push to main; Heroku can auto-deploy the backend from the same repository. If automatic deploys do not start, use the Heroku dashboard's deploy page to deploy the branch:

git add .
git commit -m "Make Heroku deployment runnable"
git push origin main

If Heroku still reports no framework/buildpack, set the Python buildpack:

heroku buildpacks:set heroku/python -a causenet-generator

For Heroku-26, set the stack in the dashboard or with:

heroku stack:set heroku-26 -a causenet-generator

Changing the stack requires a new deploy before it affects the running app.

Semantic Heuristic on Heroku

The semantic heuristic needs concept_embeddings.npy, which is about 235 MB and is intentionally not committed to git. On Heroku, the app downloads the public Google Drive file into /tmp/concept_embeddings.npy and memory-maps it. Heroku dyno storage is ephemeral, so the file is downloaded again after a dyno restart.

By default, Heroku dynos start this download in the background at boot. You can control this with config vars:

heroku config:set WARM_CONCEPT_EMBEDDINGS=1 -a causenet-generator
heroku config:set CONCEPT_EMBEDDINGS_URL="https://example.com/concept_embeddings.npy" -a causenet-generator

CONCEPT_EMBEDDINGS_URL is optional. Use it if you host the file somewhere more reliable than Google Drive, such as S3 or Cloudflare R2.

Notes

• The app runs without concept_embeddings.npy for the degrees and none heuristics. The semantics heuristic uses concept_embeddings.npy from the app directory if present, otherwise it uses the downloaded /tmp cache.
• The maximum number of nodes for the graph is set to 20. You can adjust this in the MAX_NODES variable in main.py.