provenance

Documentation

Overview

Experimental — this package is not yet wired into the main framework.

Package provenance provides cryptographic model lifecycle tracking.

A Tracker maintains a hash chain of model lifecycle events — training runs, datasets, hyperparameters, evaluations, and predictions. Each event is assigned a SHA-256 hash that incorporates the hash of its parent event(s), forming a directed acyclic graph (DAG) that can be traversed to trace any prediction back to the training data and configuration that produced it.

The hash chain provides tamper-evident audit trails: if any event in the chain is modified, all downstream hashes become invalid.

t := provenance.NewTracker()

trainHash, _ := t.RecordTraining(provenance.TrainingRecord{
    RunID:           "run-001",
    ModelName:       "llama-3-8b",
    ModelVersion:    "v1.0.0",
    Hyperparameters: map[string]string{"lr": "3e-4", "epochs": "3"},
})

dataHash, _ := t.RecordDataset(provenance.DatasetRecord{
    Name:     "wiki-en",
    Version:  "2024-03",
    ParentID: trainHash,
})

evalHash, _ := t.RecordEvaluation(provenance.EvaluationRecord{
    ParentID: trainHash,
    Metrics:  map[string]float64{"loss": 0.42, "accuracy": 0.91},
})

// Trace from evaluation back to training data.
events, _ := t.Trace(evalHash)

// Verify hash chain integrity.
ok, _ := t.Verify(evalHash)

(Stability: alpha)

Index

• type DatasetRecord
• type EvaluationRecord
• type Event
• type EventType
• type Tracker
  • func NewTracker() *Tracker
  • func (t *Tracker) Events() []Event
  • func (t *Tracker) RecordDataset(rec DatasetRecord) (string, error)
  • func (t *Tracker) RecordEvaluation(rec EvaluationRecord) (string, error)
  • func (t *Tracker) RecordTraining(rec TrainingRecord) (string, error)
  • func (t *Tracker) Trace(hash string) ([]Event, error)
  • func (t *Tracker) Verify(hash string) (bool, error)
• type TrainingRecord

Types

type DatasetRecord

type DatasetRecord struct {
	Name     string
	Version  string
	Checksum string
	NumRows  int
	ParentID string
}

DatasetRecord captures dataset provenance.

type EvaluationRecord

type EvaluationRecord struct {
	ParentID string
	Metrics  map[string]float64
	Dataset  string
	Split    string
}

EvaluationRecord captures evaluation results.

type Event

type Event struct {
	Hash      string
	ParentID  string
	Type      EventType
	Timestamp time.Time
	Payload   any
}

Event is a single node in the provenance DAG.

type EventType

type EventType string

EventType identifies the kind of lifecycle event.

const (
	EventTraining   EventType = "training"
	EventDataset    EventType = "dataset"
	EventEvaluation EventType = "evaluation"
)

type Tracker

type Tracker struct {
	// contains filtered or unexported fields
}

Tracker maintains a cryptographic hash chain of model lifecycle events.

func NewTracker

func NewTracker() *Tracker

NewTracker creates a new provenance tracker.

func (*Tracker) Events

func (t *Tracker) Events() []Event

Events returns all tracked events. The caller must not modify the returned slice.

func (*Tracker) RecordDataset

func (t *Tracker) RecordDataset(rec DatasetRecord) (string, error)

RecordDataset records a dataset event and returns its hash.

func (*Tracker) RecordEvaluation

func (t *Tracker) RecordEvaluation(rec EvaluationRecord) (string, error)

RecordEvaluation records an evaluation event and returns its hash.

func (*Tracker) RecordTraining

func (t *Tracker) RecordTraining(rec TrainingRecord) (string, error)

RecordTraining records a training run event and returns its hash.

func (*Tracker) Trace

func (t *Tracker) Trace(hash string) ([]Event, error)

Trace traverses the DAG from the given hash back to the root(s), returning events in reverse chronological order (leaf first).

func (*Tracker) Verify

func (t *Tracker) Verify(hash string) (bool, error)

Verify checks that the hash chain from the given event back to the root is intact. It recomputes each event's hash and compares it to the stored value.

type TrainingRecord

type TrainingRecord struct {
	RunID           string
	ModelName       string
	ModelVersion    string
	Hyperparameters map[string]string
	StartedAt       time.Time
	FinishedAt      time.Time
	ParentID        string
}

TrainingRecord captures a training run.