flywhl/logis: Turn your git commit history into a scientific log

logis turns your commit history into a searchable scientific log.

Every time you run an experiment, your code will be auto-committed with metadata in the commit message.

• Put the @commit decorator on your experiment function.
• logis will store hyperparameters and metrics as metadata in the commit message.
• Query your scientific log, e.g. logis query metrics.accuracy < 0.8.

from logis import commit, Run

@commit
def my_experiment(run: Run) -> Metrics:

    # ... experiment stuff

    run.set_hyperparameters({
        "lr": 0.001,
        "epochs": 100,
    })

    # ... more experiment stuff

    run.set_metrics({
        "accuracy": 0.9,
    })

if __name__ == "__main__":
    my_experiment()

# --- Or use the implicit API

@commit(implicit=True)
def other_experiment(hypers: Hypers) -> Metrics:

    # ... experiment stuff

    metrics = Metrics(accuracy=0.9)
    return metrics

if __name__ == "__main__":
    other_experiment(Hypers(...))

Then run your experiment:

$ python experiment.py

Generating commit with message:

    exp: run my_experiment at 2025-02-10 18:39:18.759230

    ---

    {
      "experiment": "my_experiment",
      "hyperparameters": {
        "lr": 0.001,
        "epochs": 100,
      },
      "metrics": {
        "accuracy": 0.9,
      },
      "uuid": "94871de1-4d6c-4e70-9c9d-60ec11df1159",
      "artifacts": null,
      "annotations": null,
      "timestamp": "2025-02-10T18:39:18.759230"
    }

Finally, query for relevant commits:

$ logis query metrics.accuracy > 0.8

Found 1 commit(s):

    af6cd7

• git clone https://github.com/flywhl/logis.git
• cd logis
• uv sync
• just test

Science needs better software tools. Flywheel is an open source collective building simple tools to preserve scientific momentum, inspired by devtools and devops culture. Join our Discord here.