worker

type Capabilities struct {
	Tasks       []string          `json:"tasks"`
	Algorithms  []string          `json:"algorithms"`
	Unavailable map[string]string `json:"unavailable"`
}

type Catalog struct {
	Users int `json:"users"`
	Items int `json:"items"`
}

type CategoryShare struct {
	Value    string  `json:"value"`
	Fraction float64 `json:"fraction"`
}

type CheckWarning struct {
	Code    string `json:"code"`
	Message string `json:"message"`
	Column  string `json:"column,omitempty"`
}

type Client struct {
	// URL is the worker's base URL, without a trailing slash.
	URL string
	// Token, when set, is sent as a bearer token on every call.
	Token string
	// TrainTimeout bounds one training call.
	TrainTimeout time.Duration
	// contains filtered or unexported fields
}

type Column struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

type ColumnCheck struct {
	Name string `json:"name"`
	Type string `json:"type"`
	Role string `json:"role"`
	Note string `json:"note"`
}

type DatasetInfo struct {
	Name      string           `json:"name"`
	Rows      int              `json:"rows"`
	Columns   []Column         `json:"columns"`
	UpdatedAt time.Time        `json:"updated_at"`
	Sample    []map[string]any `json:"sample,omitempty"`
	// Engine holds the dataset: EngineBuiltin (Hermod's metadata store) or
	// EngineWorker, for one only a connected hermod-ml worker has.
	Engine string `json:"engine,omitempty"`
}

type FeatureStats struct {
	Kind string `json:"kind"`
	// Count is the rows measured; NullFraction the share with no usable value.
	Count        int     `json:"count"`
	NullFraction float64 `json:"null_fraction"`

	// Numeric: summary values, absent when every value was missing, and the
	// decile bins. Bin i holds Edges[i-1] < v <= Edges[i]; Fractions has one
	// more entry than Edges, each bin's share of the non-missing values.
	Mean      *float64  `json:"mean,omitempty"`
	Std       *float64  `json:"std,omitempty"`
	Min       *float64  `json:"min,omitempty"`
	Max       *float64  `json:"max,omitempty"`
	Edges     []float64 `json:"edges,omitempty"`
	Fractions []float64 `json:"fractions,omitempty"`

	// Categorical: the most frequent values, and the share of all the others.
	Top           []CategoryShare `json:"top,omitempty"`
	OtherFraction float64         `json:"other_fraction,omitempty"`
}

type FeatureWeight struct {
	Feature string  `json:"feature"`
	Weight  float64 `json:"weight"`
}

type HealthCheck struct {
	Code    string `json:"code"`
	Status  string `json:"status"`
	Message string `json:"message"`
	Fix     string `json:"fix,omitempty"`
}

type LeaderboardEntry struct {
	Algorithm string  `json:"algorithm"`
	Score     float64 `json:"score"`
	Metric    string  `json:"metric"`
	Folds     int     `json:"folds"`
	Seconds   float64 `json:"seconds"`
	Chosen    bool    `json:"chosen"`
}

type Local interface {
	http.Handler
	// Predict scores rows with a version of a model, one prediction per row:
	// {"label", "probability"} for a classifier, {"value"} for a regression,
	// as the worker's serving answers.
	Predict(ctx context.Context, vhost, model, version string, rows []map[string]any) ([]map[string]any, error)
}

type NamedBaseline struct {
	Name    string             `json:"name"`
	Metrics map[string]float64 `json:"metrics"`
}

type ProbeReport struct {
	Result  ProbeResult `json:"result"`
	Message string      `json:"message"`
	// DeepLearning says whether the worker can train a neural network, and
	// Frameworks which ones: the "-dl" image has both.
	DeepLearning bool     `json:"deep_learning"`
	Frameworks   []string `json:"frameworks,omitempty"`
	Algorithms   []string `json:"algorithms,omitempty"`
}

type ProbeResult string

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

type RecommendHealth struct {
	OK     bool           `json:"ok"`
	Checks []HealthCheck  `json:"checks"`
	Stats  map[string]any `json:"stats"`
}

type RecommendSample struct {
	User        string   `json:"user"`
	Recommended []string `json:"recommended"`
	Picked      []string `json:"picked"`
}

type RecommendSpec struct {
	User     string `json:"user"`
	Item     string `json:"item"`
	Strength string `json:"strength,omitempty"`
	Time     string `json:"time,omitempty"`
}

type Script struct {
	Name   string `json:"name"`
	SHA256 string `json:"sha256"`
	Source string `json:"source"`
}

type ScriptRef struct {
	Name   string `json:"name"`
	SHA256 string `json:"sha256"`
}

type Source string

type TrainCheck struct {
	// Task is classification or regression; TargetKind yes_no, category or
	// number. Classes is set for a classification only.
	Task       string         `json:"task"`
	TargetKind string         `json:"target_kind"`
	Classes    *int           `json:"classes,omitempty"`
	Rows       int            `json:"rows"`
	UsableRows int            `json:"usable_rows"`
	Columns    []ColumnCheck  `json:"columns"`
	Warnings   []CheckWarning `json:"warnings"`
	// OK is false when a training would be refused; Warnings say why.
	OK bool `json:"ok"`
}

type TrainParams struct {
	HiddenLayers []int   `json:"hidden_layers,omitempty"`
	Epochs       int     `json:"epochs,omitempty"`
	BatchSize    int     `json:"batch_size,omitempty"`
	LearningRate float64 `json:"learning_rate,omitempty"`
	// Patience is how many epochs without a better validation loss end
	// training early.
	Patience int `json:"patience,omitempty"`
}

type TrainSpec struct {
	Dataset string `json:"dataset"`
	// Target is the column to predict; empty for a recommendation model.
	Target string `json:"target"`
	// Features are the columns the model reads; empty means every column but
	// Target.
	Features []string `json:"features,omitempty"`
	// Task is auto, classification, regression or recommendation.
	Task string `json:"task,omitempty"`
	// Recommend names a recommendation model's columns. The worker refuses
	// it for any other task, and Target, Features and Params for this one.
	Recommend *RecommendSpec `json:"recommend,omitempty"`
	// Algorithm is auto, random_forest, gradient_boosting, linear, mlp (the
	// built-in engine only), xgboost, extra_trees, hist_gradient_boosting,
	// pytorch_mlp or keras_mlp; for a recommendation model, auto, als or
	// item_similarity.
	Algorithm string `json:"algorithm,omitempty"`
	// Preset is how hard auto tries: quick, balanced (the worker's default)
	// or best. Only an auto training takes one.
	Preset   string  `json:"preset,omitempty"`
	TestSize float64 `json:"test_size,omitempty"`
	Seed     *int    `json:"seed,omitempty"`
	// Device is cpu (the default) or gpu. Hermod routes a gpu training to its
	// GPU worker pool; the worker reads it as a hint for its own networks.
	Device string `json:"device,omitempty"`
	// Params tunes pytorch_mlp and keras_mlp (mlp on the built-in engine);
	// the engine refuses it for any other algorithm.
	Params *TrainParams `json:"params,omitempty"`

	// A recommendation scenario's training (ml/worker/hermod_ml/scenarios.py)
	// names Scenario and maps each data role (transactions, customers,
	// products, visits, salesmen) to a dataset and its columns in Data,
	// instead of Recommend. Weights are the visit signals' weights, Rules the
	// business rules every call obeys, and PeriodDays the planning (visits)
	// or evaluation period. NearKm and NearPeers make a customer's peers the
	// NearPeers nearest of its category within NearKm kilometres; 0 for the
	// worker's default (5 km, 20 customers). NewDays makes a product launched
	// within that many days new (products.launch_date); 0 for the worker's
	// default (60).
	Scenario   string                       `json:"scenario,omitempty"`
	Data       map[string]map[string]string `json:"data,omitempty"`
	Weights    map[string]float64           `json:"weights,omitempty"`
	Rules      []recommend.Rule             `json:"rules,omitempty"`
	PeriodDays int                          `json:"period_days,omitempty"`
	NearKm     float64                      `json:"near_km,omitempty"`
	NearPeers  int                          `json:"near_peers,omitempty"`
	NewDays    int                          `json:"new_days,omitempty"`
}

type Version struct {
	Model   string `json:"model"`
	Version string `json:"version"`
	// Engine is the engine that trained it and scores it: EngineBuiltin or
	// EngineWorker (engines.go).
	Engine       string             `json:"engine,omitempty"`
	Task         string             `json:"task"`
	Algorithm    string             `json:"algorithm"`
	Dataset      string             `json:"dataset"`
	Target       string             `json:"target"`
	Features     []string           `json:"features"`
	FeatureTypes map[string]string  `json:"feature_types,omitempty"`
	Labels       []any              `json:"labels,omitempty"`
	Metrics      map[string]float64 `json:"metrics"`
	Rows         struct {
		Train int `json:"train"`
		Test  int `json:"test"`
	} `json:"rows"`
	// FeatureStats describe the rows the version was trained on, per
	// feature. A version trained before the worker recorded them has none.
	FeatureStats map[string]FeatureStats `json:"feature_stats,omitempty"`
	CreatedAt    time.Time               `json:"created_at"`
	// Fill is what a null numeric feature becomes: its training median.
	Fill map[string]float64 `json:"fill,omitempty"`
	// Script is the custom script that trained this version, and Log what
	// it printed; both are empty for a built-in algorithm.
	Script *ScriptRef `json:"script,omitempty"`
	Log    string     `json:"log,omitempty"`

	// A recommendation version's columns, catalogue, a sample of its test,
	// and what auto measured for each algorithm (NDCG@10 on a validation
	// split of the training rows).
	Recommend  *RecommendSpec     `json:"recommend,omitempty"`
	Catalog    *Catalog           `json:"catalog,omitempty"`
	Samples    json.RawMessage    `json:"samples,omitempty"`
	Candidates map[string]float64 `json:"candidates,omitempty"`

	// A scenario's training (see TrainSpec): the scenario, its data roles,
	// the weights asked for and those applied, its default rules, its
	// metrics against named baselines, how it was evaluated, and the data
	// health check it passed.
	Scenario       string                       `json:"scenario,omitempty"`
	Roles          map[string]map[string]string `json:"roles,omitempty"`
	Weights        map[string]float64           `json:"weights,omitempty"`
	AppliedWeights map[string]float64           `json:"applied_weights,omitempty"`
	Rules          []recommend.Rule             `json:"rules,omitempty"`
	BaselinesNamed []NamedBaseline              `json:"baselines_named,omitempty"`
	Evaluation     map[string]any               `json:"evaluation,omitempty"`
	Health         *RecommendHealth             `json:"health,omitempty"`
	// Preset and Leaderboard are an auto training's: how hard it tried, and
	// every candidate it scored, best first.
	Preset      string             `json:"preset,omitempty"`
	Leaderboard []LeaderboardEntry `json:"leaderboard,omitempty"`
	// Importance is each feature's permutation importance on the held-out
	// rows, normalised to sum to 1, heaviest first, at most 20.
	Importance []FeatureWeight `json:"importance,omitempty"`
	// Baseline holds the Metrics keys, scored by a model that always answers
	// the most common class or the mean.
	Baseline map[string]float64 `json:"baseline,omitempty"`
	// Warnings are notes on the data, in words.
	Warnings []string `json:"warnings,omitempty"`
}