Skip to content

Record types

The dataclasses that back every row, plus the schema version constant. Field names are the SQLite column names, and their order is the canonical column order of each table. See runs and evaluations for when each record is created.

Status

Run lifecycle state. Serialized to its name ("RUNNING", "COMPLETED", "FAILED").

research_tracker.trackers.Status

Bases: Enum

Source code in src/research_tracker/trackers.py 
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
class Status(Enum):
    RUNNING = 1
    COMPLETED = 2
    FAILED = 3

    @classmethod
    def from_wandb(cls, run):
        match run.state.lower():
            case "finished":
                return cls.COMPLETED
            case "running" | "pending":
                return cls.RUNNING
            case "crashed" | "failed" | "killed":
                return cls.FAILED
            case _:
                raise ValueError(f"Unknown W&B run state: {run.state}")

Tracker

Base class: to_dict() serializes a record, converting Path to str and Status to its name.

research_tracker.trackers.Tracker

Source code in src/research_tracker/trackers.py 
29
30
31
32
33
34
35
36
37
38
39
40
41
class Tracker:
    @staticmethod
    def serialize(value):
        if isinstance(value, Path):
            return str(value)

        if isinstance(value, Status):
            return value.name

        return value

    def to_dict(self) -> dict[str, Any]:
        return {key: self.serialize(value) for key, value in asdict(self).items()}

Records

research_tracker.trackers.Run dataclass

Bases: Tracker

Source code in src/research_tracker/trackers.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
@dataclass
class Run(Tracker):
    model: str
    model_class: str
    dataset: str

    config: Path
    status: Status
    seed: int | None = None
    checkpoint: Path | None = None

    # other trackers, e.g., wandb
    tracking_backend: str | None = None
    tracking_id: str | None = None
    tracking_project: str | None = None

    run_id: str = field(default_factory=lambda: make_id("run"))
    created_at: datetime = field(default_factory=now_utc)
    updated_at: datetime = field(default_factory=now_utc)

    git_commit: str | None = None
    git_dirty: bool | None = None
    dataset_version: str | None = None
    datamodule_class: str | None = None
    loader: str | None = None

    parent_run_id: str | None = None

    @property
    def external_id(self) -> tuple[str, str | None, str] | None:
        if self.tracking_backend is None or self.tracking_id is None:
            return None
        return (
            self.tracking_backend,
            self.tracking_project,
            self.tracking_id,
        )

research_tracker.trackers.Evaluation dataclass

Bases: Tracker

Source code in src/research_tracker/trackers.py 
91
92
93
94
95
96
97
@dataclass
class Evaluation(Tracker):
    run_id: str
    name: str

    evaluation_id: str = field(default_factory=lambda: make_id("eval"))
    created_at: datetime = field(default_factory=now_utc)

research_tracker.trackers.Condition dataclass

Bases: Tracker

Source code in src/research_tracker/trackers.py 
100
101
102
103
104
105
106
107
@dataclass
class Condition(Tracker):
    evaluation_id: str

    name: str
    value: str | int | float | bool
    unit: str | None = None
    condition_id: str = field(default_factory=lambda: make_id("condition"))

research_tracker.trackers.Metric dataclass

Bases: Tracker

Source code in src/research_tracker/trackers.py 
110
111
112
113
114
115
116
117
118
119
120
121
@dataclass
class Metric(Tracker):
    evaluation_id: str
    metric: str
    value: float

    sample_id: str | None = None
    target: str | None = None
    comparison: str | None = None
    region: str | None = None
    unit: str | None = None
    metric_id: str = field(default_factory=lambda: make_id("metric"))

research_tracker.trackers.Artifact dataclass

Bases: Tracker

Source code in src/research_tracker/trackers.py 
124
125
126
127
128
129
130
@dataclass
class Artifact(Tracker):
    evaluation_id: str
    kind: str
    path: Path
    sample_id: str | None
    artifact_id: str = field(default_factory=lambda: make_id("artifact"))

Helpers

research_tracker.trackers.make_id(prefix)

Source code in src/research_tracker/trackers.py 
44
45
def make_id(prefix: str) -> str:
    return f"{prefix}_{uuid4().hex}"

research_tracker.trackers.now_utc()

Source code in src/research_tracker/trackers.py 
48
49
def now_utc() -> datetime:
    return datetime.now(UTC)

Schema version

research_tracker.trackers.SCHEMA_VERSION = 2 module-attribute