logis 0.3.1

Git-based experiment tracking with semantic metadata.

Discord • Website • Installation

Features

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.

Installation

• uv add logis

Usage

• 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

Development

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

Flywheel

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.