Label-free quickstart

The eight-step quickstart defines its label from an uploaded file of outcomes. If you do not have such a file, you can derive the label from the event stream itself: the entity's own future events become the supervision, so no label rows are uploaded.

Every sample on this page is a real file, executed against a seeded test project in CI on every change. The data is the same sample dataset as the main quickstart (tessera-sample-v1.zip); the numbers you see come from that sample, not from real customers. The samples read the same environment variables as the main quickstart (TESSERA_API_BASE, TESSERA_INGEST_BASE, TESSERA_API_KEY).

1. Connect data (unchanged)

Project, first events, upload and contract approval are the main quickstart's steps 1 to 3. Nothing label-free changes ingestion, so this sample simply runs those three.

01-connect-data.sh
#!/usr/bin/env bash
# Label-free quickstart step 1 — connect data. Steps 1-3 of the main
# quickstart are identical (events, upload, contract); nothing label-free
# changes ingestion, so this runs those three samples unchanged.
set -euo pipefail

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
for step in 01-first-events 02-upload-events 03-approve-contract; do
  (cd "$HERE/.." && bash -euo pipefail "$step.sh")
done

Download quickstart/label-free/01-connect-data.sh — this exact file runs in CI on every change (hosts shown are for this environment).

2. Preview a derived label

A derived label turns the entity's own future events into supervision. This rule asks, for each anchor moment: "did the user place no order in the following 30 days?" Before creating anything, dry-run it with POST /labels:preview. The preview samples your latest committed events and reports anchor counts, censoring, the positive rate and examples. Nothing is persisted.

02-preview-derived-label.sh
#!/usr/bin/env bash
# Label-free quickstart step 2 — dry-run a derived label rule on your own events.
set -euo pipefail

: "${TESSERA_API_BASE:?e.g. https://api.staging.tessera.zone/v1}"
: "${TESSERA_API_KEY:?your tsk_test_… key}"
AUTH=(-H "Authorization: Bearer $TESSERA_API_KEY")

# "For each anchor moment, did the user place NO order in the following
# 30 days?" Nothing is persisted: the preview samples your latest committed
# events and reports anchor counts, censoring, the positive rate and examples.
PREVIEW="$(curl -sS -X POST "$TESSERA_API_BASE/labels:preview" "${AUTH[@]}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: label-free-preview" \
  -d '{
    "entity_type": "user",
    "task": "binary",
    "source": {
      "kind": "derived",
      "rule": {
        "template": "churn",
        "horizon_days": 30,
        "predicate": {"event_type_pattern": "order.*", "min_count": 1},
        "outcome": "absence",
        "anchor_cadence": "daily_last_event"
      }
    }
  }')"
printf '%s' "$PREVIEW" | python3 -m json.tool
printf '%s' "$PREVIEW" | python3 -c '
import json, sys
preview = json.load(sys.stdin)
print("sampled entities:", preview["sampled_entities"])
print("observations:", preview["observations"])
print("warnings:", preview["warnings"])
'

Download quickstart/label-free/02-preview-derived-label.sh — this exact file runs in CI on every change (hosts shown are for this environment).

The rule, as a schema-validated configuration:

{
  "name": "churn_30d",
  "entity_type": "user",
  "task": "binary",
  "source": {
    "kind": "derived",
    "rule": {
      "template": "churn",
      "horizon_days": 30,
      "predicate": { "event_type_pattern": "order.*", "min_count": 1 },
      "outcome": "absence",
      "anchor_cadence": "daily_last_event"
    }
  }
}

3. Create the label

maturation_days may be omitted: derived labels bind it to the rule's horizon_days, because the outcome is known exactly when the horizon closes.

03-create-derived-label.sh
#!/usr/bin/env bash
# Label-free quickstart step 3 — create the derived label. No label file is
# uploaded: the supervision comes from the entities' own future events.
set -euo pipefail

: "${TESSERA_API_BASE:?e.g. https://api.staging.tessera.zone/v1}"
: "${TESSERA_API_KEY:?your tsk_test_… key}"
: "${TESSERA_STATE_DIR:=.}"
AUTH=(-H "Authorization: Bearer $TESSERA_API_KEY")

LABEL="$(curl -sS -X POST "$TESSERA_API_BASE/labels" "${AUTH[@]}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: label-free-label" \
  -d '{
    "name": "churn_30d",
    "entity_type": "user",
    "task": "binary",
    "source": {
      "kind": "derived",
      "rule": {
        "template": "churn",
        "horizon_days": 30,
        "predicate": {"event_type_pattern": "order.*", "min_count": 1},
        "outcome": "absence",
        "anchor_cadence": "daily_last_event"
      }
    }
  }')"
printf '%s' "$LABEL" | python3 -c '
import json, sys
label = json.load(sys.stdin)
print(json.dumps({
    "label_id": label["label_id"],
    "name": label["name"],
    "task": label["task"],
    "source_kind": label["source"]["kind"],
    "maturation_days": label["maturation_days"],
}, indent=2))
'
printf '%s' "$LABEL" | python3 -c 'import json,sys; print(json.load(sys.stdin)["label_id"], end="")' \
  > "$TESSERA_STATE_DIR/label_id"

Download quickstart/label-free/03-create-derived-label.sh — this exact file runs in CI on every change (hosts shown are for this environment).

Derived observations are materialized by the dataset builder into the same point-in-time label store as uploaded labels. They are deterministic given the event snapshot, so they fingerprint and reproduce like everything else. Anchors whose 30-day horizon has not elapsed yet are censored (masked, reason horizon_open), never assumed negative.

4. Build, train, activate

From here the flow is the main quickstart's steps 5 to 7, unchanged: build the leakage-gated dataset, train and evaluate, then bundle, activate a slot and batch score. The samples run those files, so they keep the main quickstart's names: the slot is called quickstart and the user read in the next step is u_00001. The slot name is fixed by the shared sample, so run this flow in a fresh project rather than after the labelled one.

04-build-dataset.sh
#!/usr/bin/env bash
# Label-free quickstart step 4 — build the leakage-gated dataset. Identical
# to step 5 of the main quickstart: the builder materializes the derived
# observations into the same point-in-time label store as uploaded labels.
set -euo pipefail

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
(cd "$HERE/.." && bash -euo pipefail 05-build-dataset.sh)

Download quickstart/label-free/04-build-dataset.sh — this exact file runs in CI on every change (hosts shown are for this environment).

05-train.sh
#!/usr/bin/env bash
# Label-free quickstart step 5 — train and evaluate. Identical to step 6 of
# the main quickstart.
set -euo pipefail

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
(cd "$HERE/.." && bash -euo pipefail 06-train.sh)

Download quickstart/label-free/05-train.sh — this exact file runs in CI on every change (hosts shown are for this environment).

06-activate-and-score.sh
#!/usr/bin/env bash
# Label-free quickstart step 6 — bundle, activate a slot, batch score.
# Identical to step 7 of the main quickstart.
set -euo pipefail

HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
(cd "$HERE/.." && bash -euo pipefail 07-activate-and-score.sh)

Download quickstart/label-free/06-activate-and-score.sh — this exact file runs in CI on every change (hosts shown are for this environment).

5. Read the state

The slot now serves a score for churn_30d, with the same embedding, freshness block and fingerprint trail as the labelled flow.

07-read-state.sh
#!/usr/bin/env bash
# Label-free quickstart step 7 — read a user's state: the embedding and the
# score of the DERIVED label, with the same freshness and fingerprint trail.
set -euo pipefail

: "${TESSERA_API_BASE:?e.g. https://api.staging.tessera.zone/v1}"
: "${TESSERA_API_KEY:?your tsk_test_… key}"

STATE="$(curl -sS "$TESSERA_API_BASE/slots/quickstart/entities/user/u_00001/state" \
  -H "Authorization: Bearer $TESSERA_API_KEY")"
echo "$STATE" | python3 -m json.tool

printf '%s' "$STATE" | python3 -c '
import json, sys
state = json.load(sys.stdin)
print("embedding_dimension:", len(state["embedding"]))
print("score churn_30d present:", "churn_30d" in state["scores"])
print("model_fingerprint:", state["freshness"]["model_fingerprint"])
'

Download quickstart/label-free/07-read-state.sh — this exact file runs in CI on every change (hosts shown are for this environment).

Signals and segments

Two further label-free outputs are available once a slot has scored states. They are documented with their own reference pages rather than exercised by this suite:

Behavioral signals. With signals enabled in the bundle, every state read carries a signals block (behavior_surprise, propensities) alongside embedding and scores. See behavioral signals.
Behavioral segments. POST /slots/{slot}/segments:rebuild clusters the embedding space; GET /slots/{slot}/segments lists the segments with sizes and KPI summaries, and GET /slots/{slot}/segments/{id}/members pages the entities. Each segment carries an explanation that is explained when an audited explanation exists for the slot's current segment registry, and fallback (the Segment #N name) otherwise. Explanations are produced offline and audited before they are published; reading segments never calls a model.

1. Connect data (unchanged)​

2. Preview a derived label​

3. Create the label​

4. Build, train, activate​

5. Read the state​

Signals and segments​