Quick Start

Installation

Install from PyPI:

pip install graflag

Or from source:

git clone https://github.com/lias-laboratory/graflag.git
cd graflag
pip install -e .

Shared Storage Setup

GraFlag uses an NFS-mounted shared directory containing methods, datasets, and experiment results. The graflag-shared repository provides this structure.

Clone it on your NFS mount point:

cd /shared  # or your NFS mount point
git clone https://github.com/lias-laboratory/graflag-shared.git .
git lfs pull  # download dataset files

The shared directory contains:

  • methods/ – GAD method implementations (Dockerfiles, configs, scripts)

  • datasets/ – Benchmark datasets (tracked via Git LFS)

  • experiments/ – Experiment results (created at runtime)

  • libs/ – Shared Python libraries (graflag_runner, graflag_evaluator, graflag_bond)

Configuration

Run the interactive setup wizard, which prompts for connection details and stores them in ~/.config/graflag/config.env:

graflag setup

The wizard asks for:

  • Manager IP – address of the Swarm manager node

  • SSH port – SSH port on the manager (default: 22)

  • SSH key – path to your private key (default: ~/.ssh/id_ed25519)

  • Shared directory – NFS-mounted path on the remote (default: /shared)

  • Hosts file – path to hosts.yml containing worker IPs (default: hosts.yml)

To reconfigure later:

graflag setup --reconfigure

Alternatively, place a .env file in the working directory to override the stored configuration.

For local development without a physical cluster, use the built-in devcluster:

graflag devcluster --hosts hosts.yml
graflag setup

Running an Experiment

Build and run a method on a dataset:

graflag run -m bond_dominant -d bond_inj_cora --build

With custom parameters:

graflag run -m taddy -d uci --params MAX_EPOCH=100 LEARNING_RATE=0.001

From a saved config:

graflag run --from-config ./experiments/exp__method__dataset__time/service_config.json

Evaluating Results

Run evaluation on a completed experiment:

graflag evaluate -e exp__bond_dominant__bond_inj_cora__20260309_120000

This computes AUC-ROC, AUC-PR, and generates plots in the experiment’s eval/ directory.

Custom Metrics

Register custom metrics via the Python API:

from graflag import GraFlag

def hits_at_100(scores, ground_truth, **kw):
    top = scores.argsort()[-100:]
    return {"hits@100": ground_truth[top].mean()}

gf = GraFlag()
# Save globally (applied to all future evaluations)
gf.register_metric("EDGE_STREAM_ANOMALY_SCORES", hits_at_100)

# Or scope to a specific experiment
gf.register_metric("EDGE_STREAM_ANOMALY_SCORES", hits_at_100,
                    experiment="exp__taddy__uci__20260309_120000")

This extracts the function source and writes it as a plugin file on the cluster. The evaluator loads plugins automatically before computing metrics.

You can also create plugin files manually. Place a .py file in either:

  • libs/graflag_evaluator/plugins/ – global (all evaluations)

  • experiments/<exp_name>/custom_metrics/ – per-experiment

Each plugin file should import MetricCalculator and call register_metric():

# custom_metrics/hits_at_100.py
from graflag_evaluator import MetricCalculator

def hits_at_100(scores, ground_truth, **kw):
    top = scores.argsort()[-100:]
    return {"hits@100": ground_truth[top].mean()}

MetricCalculator.register_metric("EDGE_STREAM_ANOMALY_SCORES", hits_at_100)

Web Dashboard

Start the GUI:

graflag gui

Open http://localhost:5000 in a browser. Use --port to change the port:

graflag gui --port 8080 --debug