scene_pipelines.ingestion.scene

Write helpers for the scene tables (Subject, Session; admin catalogs in admin).

register_subject and register_session are everyday pipeline writes; subject_key and session_key find a row by its lab code. Lab and Project are admin catalogs: see scene_pipelines.ingestion.scene.admin.

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.

register_subject

register_subject(subject_code: str, subject_kind: DjKey[SubjectKind] | str, *, lab: DjKey[Lab], deployment: DjRow[Deployment] | None = None, if_exists: DuplicatePolicy = VERIFY) -> DjKey[Subject]

Register a subject by its lab code; mint subject_id when new.

The subject is looked up by (lab, subject_code). A new code gets a freshly minted subject_id; an existing code is handled by if_exists against the stored subject. Runs atomically; joins the caller's transaction when one is open.

Parameters:

Name	Type	Description	Default
`subject_code`	`str`	Pseudonymous code, unique within `lab`; see `normalize_code`. Never a real name.	required
`subject_kind`	`DjKey[SubjectKind] \| str`	Existing `SubjectKind` key or its name, e.g. `"mouse"`.	required
`lab`	`DjKey[Lab]`	Existing lab primary key, e.g. `{"lab_id": "mlai"}`.	required
`deployment`	`DjRow[Deployment] \| None`	Optional deployment row. If omitted, built from `SCENE_DEPLOYMENT_ID` / `SCENE_DEPLOYMENT_LABEL`.	`None`
`if_exists`	`DuplicatePolicy`	Policy when `subject_code` is already registered in `lab`; see `DuplicatePolicy`. The default `VERIFY` returns the stored key when the content matches and raises otherwise.	`VERIFY`

Returns:

Type	Description
`DjKey[Subject]`	Subject primary key `{subject_id: ...}`.

Raises:

Type	Description
`ValueError`	If `subject_kind` is `mouse` (use `register_mouse`), `subject_code` is not a valid code, `deployment` is omitted and `SCENE_DEPLOYMENT_ID` is unset, or `if_exists` rejects the existing subject.

subject_key

subject_key(subject_code: str, *, lab: DjKey[Lab] | None = None) -> DjKey[Subject]

Find a subject by its lab code.

Parameters:

Name	Type	Description	Default
`subject_code`	`str`	Lab code, e.g. `"Tick"`.	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[Subject]`	Subject primary key, e.g. for `Mouse & subject_key("Tick", lab=lab)`.

Raises:

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