vibe.web_core.session_mgmt

Flask Session Management for Interviews.

Handles operations related to the Flask session specific to the interview UI: - Initializing the session state for a new interview (including merging session context). - Updating the session's answer state based on incoming Flask form data, using DataTypeHandlers for coercion and validation.

Runtime type checking is enabled to ensure session operations receive and produce correct types at critical boundaries.

SessionContextValidationError

Raised when session context validation fails.

make_interview_key 

make_interview_key(template_id: str, version_identifier: str) -> str

Build the session dict key for an interview.

get_interview 

get_interview(template_id: str, version_id: str) -> dict[str, Any] | None

Return the interview dict for the given template/version, or None.

get_interview_or_raise 

get_interview_or_raise(template_id: str, version_id: str) -> dict[str, Any]

Return the interview dict or raise InvalidSessionException.

initialize_session 

initialize_session(template_id: str, version_identifier: str, group_id: str | None = None) -> None

Initialize or reset the interview state for a specific template/version.

Auth data (email, grants, user_name, etc.) lives at the session root and is preserved across interview initialisations. Interview-scoped state is stored under session['interviews'][key].

Runtime type checking ensures template_id and version_identifier are strings.

validate_and_coerce_session_context 

validate_and_coerce_session_context(template_data: TemplateData, base_config: dict[str, Any]) -> tuple[dict[str, Any], list[str]]

Validate session context values against template's session_context_definitions.

Coerce string values to proper types based on definitions.

Parameters:
  • template_data (TemplateData) –

    TemplateData with session_context_definitions

  • base_config (dict[str, Any]) –

    Flat dict of session context values (keys are dot-notation paths)
Returns:
  • tuple( tuple[dict[str, Any], list[str]] ) –

    (coerced_config dict, list of error messages)

update_answers_from_form 

update_answers_from_form(form_data: MultiDict[str, Any], question_definitions: dict[str, Any], previous_relevant: set[str], template_data: TemplateData | None = None, debug_context: str = '') -> NestedValue

Update session answers (NestedValue structure) based on incoming FORM data.

Use previous relevance to correctly interpret missing multichoice data. Assume form field names are full dot-notation paths. Use DataTypeHandlers for coercion and validation ONLY for fields present in the form or fields previously in error. Store coerced values in session['current_state'] and validation errors in session['validation_errors'], preserving old errors for untouched fields.

Runtime type checking ensures form_data, question_definitions, and previous_relevant have correct types.

Parameters:
  • form_data (MultiDict[str, Any]) –

    Form data from request

  • question_definitions (dict[str, Any]) –

    Question definitions

  • previous_relevant (set[str]) –

    Set of previously relevant questions

  • template_data (TemplateData | None, default: None ) –

    Template data for definition resolution (optional)

  • debug_context (str, default: '' ) –

    Debug context string for logging
Returns:
  • NestedValue( NestedValue ) –

    The updated answers root object

validate_newly_relevant_fields 

validate_newly_relevant_fields(newly_relevant_fields: set[str], question_definitions: dict[str, Any], current_state: NestedValue, template_data: TemplateData) -> None

Validate newly relevant required fields that may not have been validated.

during form processing because they weren't relevant at the time.

Parameters:
  • newly_relevant_fields (set[str]) –

    Set of field names that became relevant

  • question_definitions (dict[str, Any]) –

    Question definitions

  • current_state (NestedValue) –

    Current NestedValue state

  • template_data (TemplateData) –

    Template data for handler initialization