Reference
Artifacts
Output kinds, storage classes, contracts, and review.
Artifacts are the durable outputs runs leave behind: datasets, fact sets, predictions, recommendations — each with lineage, storage rules, and review state.
Artifact kinds
| Kind | Holds | Example |
|---|---|---|
| Table / dataset | Structured rows | Forecast scores table |
| Parquet / JSON / file | Serialized payloads | Exported feature file |
| Ontology fact-set manifest | Prediction-ready grouped facts | Account feature manifest |
| Manifest | Pointers over other artifacts | Run output index |
| Recommendations / reviews | Decision-facing outputs | Top-20 risk list with reasons |
Storage classes
| Class | Meaning | Use for |
|---|---|---|
| Ephemeral | May expire; carries an expiry time | Previews, intermediates |
| Persisted | Kept under retention rules | Committed outputs |
| External | Lives outside Semogram, referenced by URI | Warehouse tables, file drops |
Contracts
| Field | Meaning |
|---|---|
| Kind | Rows, fact sets, assertions, signals, features, predictions, recommendations, reviews |
| Fields | Named, typed, nullable/required columns with descriptions |
| Primary key | Row identity for downstream joins |
| Evidence requirements | Whether citations, source artifacts, or source records are mandatory |
{
"kind": "predictions",
"name": "renewal-risk-scores",
"fields": [
{ "name": "account_id", "type": "string", "required": true },
{ "name": "risk", "type": "number", "required": true },
{ "name": "drivers", "type": "string", "nullable": true, "description": "Top reasons cited" }
],
"primaryKey": ["account_id"],
"evidence": { "citations": true, "sourceRecordIds": true }
}Lineage and review
| Field | Meaning |
|---|---|
| Produced by | Run, node, and upstream artifact ids — full parentage |
| Namespace / ontology package | Which model or domain it belongs to |
| Review state | Approved, corrected, or rejected with reasons |
Image: artifact detail with lineage parents, contract fields, and review state.
Choosing well
- Ephemeral for previews, persisted for commitments, external where teams already read.
- Demand evidence requirements on anything feeding decisions.
- Lineage is the audit trail — artifacts without parents are orphans; treat them as suspect.