scene_pipelines.ingestion.scene.session

Register a Session by lab code (+ Deployment + SessionRowMeta).

session_meta_payload

session_meta_payload(session: dict[str, Any], subject_ids: Sequence[UUID] = ()) -> dict[str, Any]

Non-key session fields + subjects that should affect content_hash.

register_session

register_session(session_code: str, session_date: date, *, lab: DjKey[Lab], subjects: Sequence[DjKey[Subject]] = (), project: DjKey[Project] | None = None, experimenter: DjKey[Experimenter] | None = None, deployment: DjRow[Deployment] | None = None, if_exists: DuplicatePolicy = VERIFY) -> DjKey[Session]

Register a session by its lab code; mint session_id when new.

The session is looked up by (lab, session_code). A new code gets a freshly minted session_id; an existing code is handled by if_exists against the stored session (its hash covers the linked subjects). Catalog keys (lab, subjects, project, experimenter) must already exist. Runs atomically; joins the caller's transaction when one is open.

Parameters:

Name	Type	Description	Default
`session_code`	`str`	Pseudonymous code, unique within `lab`; see `normalize_code`. Never a real name.	required
`session_date`	`date`	Calendar date of the session.	required
`lab`	`DjKey[Lab]`	Existing lab primary key, e.g. `{"lab_id": "mlai"}`.	required
`subjects`	`Sequence[DjKey[Subject]]`	Existing subject keys (may be empty).	`()`
`project`	`DjKey[Project] \| None`	Optional existing project key.	`None`
`experimenter`	`DjKey[Experimenter] \| None`	Optional existing experimenter key; must be of `lab`.	`None`
`deployment`	`DjRow[Deployment] \| None`	Optional deployment row to stamp with. If omitted, built from `SCENE_DEPLOYMENT_ID` / `SCENE_DEPLOYMENT_LABEL`.	`None`
`if_exists`	`DuplicatePolicy`	Policy when `session_code` is already registered in `lab`; see `DuplicatePolicy`. `OVERWRITE` also replaces the subject links.	`VERIFY`

Returns:

Type	Description
`DjKey[Session]`	Session primary key `{session_id: ...}`.

Raises:

Type	Description
`ValueError`	If `session_code` is not a valid code, a subject key has no valid `subject_id` or is listed twice, `experimenter` is of another lab, `deployment` is omitted and `SCENE_DEPLOYMENT_ID` is unset, or `if_exists` rejects the existing session.

session_key

session_key(session_code: str, *, lab: DjKey[Lab] | None = None) -> DjKey[Session]

Find a session by its lab code.

Parameters:

Name	Type	Description	Default
`session_code`	`str`	Lab code, e.g. `"Tick_2026-02-11_1"`.	required
`lab`	`DjKey[Lab] \| None`	Lab primary key, e.g. `{"lab_id": "mlai"}`. If omitted, built from `SCENE_LAB_ID`.	`None`

Returns:

Type	Description
`DjKey[Session]`	Session primary key.

Raises:

Type	Description
`ValueError`	If the code is invalid or not registered in `lab`, or `lab` is omitted and `SCENE_LAB_ID` is unset.