review

type CalibrateOptions struct {
	// ContractHash is the active contract hash. Only receipts judged under
	// it are joined, and labels shown in a preview made under another
	// contract are forced to dev.
	ContractHash string
	// Model is the active decision model; only receipts it produced are
	// joined.
	Model string
	// Thresholds are the current thresholds; nil means the defaults merged
	// with topic.yaml `decisions.thresholds`.
	Thresholds decisions.Thresholds
	// Now defaults to time.Now.
	Now func() time.Time
}

type ImportOptions struct {
	// From is the JSONL, JSON (array of objects) or CSV file to import.
	From string
	// IDField is the column holding the source identifier.
	IDField string
	// Match is how IDField is matched to a topic source: url|path|doi|pmcid.
	Match string
	// DecisionField is the column holding the screening decision.
	DecisionField string
	// KeepValues are the decision values meaning keep/relevant
	// (case-insensitive); every other value is a negative label.
	KeepValues []string
	// DecidedByField names the column copied to Label.DecidedBy; when empty
	// `screening_stage` or `decided_by` are used when present.
	DecidedByField string
	// Corpus is the loaded topic; loaded from the topic root when nil.
	Corpus *corpus.Corpus
	// Now defaults to time.Now.
	Now func() time.Time
}

type ImportReport struct {
	// Rows is the number of data rows read.
	Rows int
	// Matched counts rows matched to a topic source.
	Matched int
	// Unmatched counts rows with no matching source.
	Unmatched int
	// UnmatchedIDs lists the identifiers of unmatched rows in file order.
	UnmatchedIDs []string
	// Positive and Negative count the labels written by this import.
	Positive int
	Negative int
	// Duplicates counts matched rows already imported from the same file.
	Duplicates int
	// Origin is the origin recorded on every label.
	Origin string
}

type ImportedPart struct {
	Dev     Metrics `json:"dev"`
	Holdout Metrics `json:"holdout"`
}

type Item struct {
	ID          string         `json:"id"`
	Queue       string         `json:"queue"`
	Purpose     string         `json:"purpose"`
	Subject     string         `json:"subject"`
	Target      string         `json:"target,omitempty"`
	Question    string         `json:"question,omitempty"`
	Probability float64        `json:"probability"`
	ReceiptKey  string         `json:"receipt_key,omitempty"`
	Evidence    string         `json:"evidence,omitempty"`
	Action      map[string]any `json:"action,omitempty"`
	Status      string         `json:"status"`
	Created     string         `json:"created"`
	Resolved    string         `json:"resolved,omitempty"`
}

type Label struct {
	Time       string `json:"time"`
	Subject    string `json:"subject"`
	Purpose    string `json:"purpose"`
	Question   string `json:"question,omitempty"`
	Target     string `json:"target,omitempty"`
	Verdict    string `json:"verdict"` // positive | negative
	ReceiptKey string `json:"receipt_key,omitempty"`
	Origin     string `json:"origin"` // review | import:<file>@<sha256> | import-links
	DecidedBy  string `json:"decided_by,omitempty"`
	ItemID     string `json:"item_id,omitempty"`
}

type ListItem struct {
	Item
	Title string `json:"title,omitempty"`
}

type ListView struct {
	// Counts are the pending items per queue.
	Counts map[string]int `json:"counts"`
	// Items are the pending items shown.
	Items []ListItem `json:"items"`
}

type Metrics struct {
	// Total is the number of labels in the split.
	Total int `json:"total"`
	// N is the number of labels joined to a judged gate quantity.
	N int `json:"n"`
	// Predicted counts joined labels at or above the apply threshold.
	Predicted int `json:"predicted"`
	// TruePositive counts predicted labels whose verdict is the target.
	TruePositive int `json:"true_positive"`
	// Precision = TruePositive / Predicted.
	Precision float64 `json:"precision"`
	// Recall = TruePositive / joined labels whose verdict is the target.
	Recall float64 `json:"recall"`
	// Coverage = N / Total: the share of labels the model judged.
	Coverage float64 `json:"coverage"`
	// ReviewRate = joined labels in [review, apply) / N.
	ReviewRate float64 `json:"review_rate"`
}

type Preview struct {
	Time     string   `json:"time"`
	Contract string   `json:"contract"`
	Subjects []string `json:"subjects"`
}

type PurposeReport struct {
	Purpose  string `json:"purpose"`
	Quantity string `json:"quantity"`
	// Banks maps the built-in bank asking the gate quantity to the version
	// scores were joined under (with Report.Contract and Report.Model, the
	// decision context of this calibration).
	Banks map[string]string `json:"banks"`
	// ApplyName and ReviewName are the threshold names calibrated.
	ApplyName  string  `json:"apply_name"`
	ReviewName string  `json:"review_name"`
	Current    float64 `json:"current"`
	Review     float64 `json:"review"`
	// DevLabels and HoldoutLabels count joined labels per split (imported
	// ones included); ImportedLabels counts the imported ones among them.
	DevLabels      int `json:"dev_labels"`
	HoldoutLabels  int `json:"holdout_labels"`
	ImportedLabels int `json:"imported_labels"`
	// ReviewDevLabels counts the joined dev labels given in `kb review`
	// (not imported); the dev floor must be met by these alone (spec §12.2:
	// imported labels are never the only evidence behind an apply).
	ReviewDevLabels int `json:"review_dev_labels"`
	// ImportedOnly flags a purpose whose dev floor is met only with imported
	// labels: metrics are reported, no threshold is recommended.
	ImportedOnly bool `json:"imported_only,omitempty"`
	// Demoted counts labels forced to dev by a preview under another
	// contract.
	Demoted int `json:"demoted"`
	// Unjoined counts labels with no judged gate quantity.
	Unjoined int `json:"unjoined"`
	// Recommended reports whether Chosen is a recommendation.
	Recommended bool    `json:"recommended"`
	Chosen      float64 `json:"chosen,omitempty"`
	// Note explains a missing recommendation ("not enough labels", ...).
	Note           string       `json:"note,omitempty"`
	DevCurrent     Metrics      `json:"dev_current"`
	HoldoutCurrent Metrics      `json:"holdout_current"`
	DevChosen      Metrics      `json:"dev_chosen"`
	HoldoutChosen  Metrics      `json:"holdout_chosen"`
	Imported       ImportedPart `json:"imported"`
	Sweep          []SweepPoint `json:"sweep"`
}

type Report struct {
	Time     string          `json:"time"`
	Contract string          `json:"contract"`
	Model    string          `json:"model"`
	Purposes []PurposeReport `json:"purposes"`
}

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

type SweepPoint struct {
	Threshold float64 `json:"threshold"`
	Dev       Metrics `json:"dev"`
}