Getting Started
===============

Prerequisites
-------------

1. Install `Nix <https://nixos.org/download>`_:

.. code-block:: sh

   curl -L https://nixos.org/nix/install | sh

2. Create the nix-workflow store directory:

.. code-block:: sh

   # 1777: world-writable with sticky bit. Any user can create files,
   # but only the owner of a file can delete or modify it (same as /tmp).
   sudo mkdir -m 1777 -p /nix-workflow

Create a workflow
-----------------

Create an ``experiment.nix``:

.. code-block:: nix

   let
     nw-src = builtins.fetchTarball
       "https://github.com/gzbfgjf2/nix-workflow/archive/main.tar.gz";
     nw = import nw-src;
     output = nw.lib.output;
     pkgs = import (import "${nw-src}/npins")."nixos-25.11" {};

     build_data_bin = import "${nw-src}/example/showcase/build-data" { inherit pkgs; };
     train_bin = import "${nw-src}/example/showcase/train" { inherit pkgs; };
     inference_bin = import "${nw-src}/example/showcase/inference" { inherit pkgs; };
     evaluate_bin = import "${nw-src}/example/showcase/evaluate" { inherit pkgs; };
     compare_bin = import "${nw-src}/example/showcase/compare" { inherit pkgs; };
   in
   rec {
     dataset = output ''
       ${build_data_bin}/bin/build-data --name=demo --samples=500 --seed=42
     '';

     model_small = output ''
       ${train_bin}/bin/train
       --data=${dataset}/data.csv
       --epochs=5 --lr=0.01 --batch-size=128
     '';

     model_base = output ''
       ${train_bin}/bin/train
       --data=${dataset}/data.csv
       --epochs=10 --lr=0.001 --batch-size=32
     '';

     model_large = output ''
       ${train_bin}/bin/train
       --data=${dataset}/data.csv
       --epochs=50 --lr=0.0001 --batch-size=64 --seed=123
     '';

     predict_small = output ''
       ${inference_bin}/bin/inference
       --model=${model_small}/model.json
       --data=${dataset}/data.csv
     '';

     predict_base = output ''
       ${inference_bin}/bin/inference
       --model=${model_base}/model.json
       --data=${dataset}/data.csv
     '';

     predict_large = output ''
       ${inference_bin}/bin/inference
       --model=${model_large}/model.json
       --data=${dataset}/data.csv
     '';

     eval_small = output ''
       ${evaluate_bin}/bin/evaluate
       --predictions=${predict_small}/predictions.csv
       --ground-truth=${dataset}/data.csv
     '';

     eval_base = output ''
       ${evaluate_bin}/bin/evaluate
       --predictions=${predict_base}/predictions.csv
       --ground-truth=${dataset}/data.csv
     '';

     eval_large = output ''
       ${evaluate_bin}/bin/evaluate
       --predictions=${predict_large}/predictions.csv
       --ground-truth=${dataset}/data.csv
     '';

     comparison = output ''
       ${compare_bin}/bin/compare
       --result=${eval_small}
       --result=${eval_base}
       --result=${eval_large}
     '';
   }

Run the pipeline
----------------

.. code-block:: sh

   nix-shell https://github.com/gzbfgjf2/nix-workflow/archive/main.tar.gz \
   -A shell --run "nw run experiment.nix"

Visualize
---------

.. code-block:: sh

   nix-shell https://github.com/gzbfgjf2/nix-workflow/archive/main.tar.gz \
   -A shell --run "nw-visual experiment.nix"