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 <https://github.com/lias-laboratory/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