Data Models

Request/response shapes used by the API. Recsys models are detailed in Contracts & models; this page covers the ai_engine.common models the REST layer accepts and returns.

User

Visitor demographics + auth (body of POST /db/user).

Field	Type	Notes
age	int
gender	str
nationality	str
personal_connection	bool	connection to the history
payload	dict	extra, JSON-serialized on write
id	int?	assigned on register
license_plate	str?	auto-generated XX-XXXX
email	str?	unique
password_hash	str?
created_at	datetime?

Event

Interaction event (body of POST /db/events).

Field	Type	Notes
user_id	int
item_id	int
event_type	'start' \| 'end'	dwell is start→end paired in fetch_events
event_payload	dict	JSON-serialized on write
ts	datetime
id	int?
session_id	str?

Item

Collection item (search results).

Field	Type	Notes
id	int
title	str
public_url	str
text	str
creator	str?
locations	lat/lon	geo
geo_metadata / time_metadata	dict
files_url	list

Derived: image_url, text_all (title+text), char_count, word_count.

SearchResult

Uniform wrapper for every search path.

Field	Type	Notes
search_type	'vector' \| 'geo' \| 'hybrid'
query_text	str?
lat / lon / radius_meters	float?	geo params
items	list[dict]	each via hit_to_item (score, highlight)
next_offset	int?	pagination

Narrative models

NarrativeResult ⊃ Segment ⊃ Relationship (Pydantic). A narrative is an ordered list of segments, each holding items and a transition; relationships are typed (chronological, geographical, thematic, causal, contrast).

Model	Key fields
Relationship	typed item-to-item link
Segment	items, transition
NarrativeResult	segments, metadata

Session

Field	Type
user_id	int?
device_token	str
expires_at	datetime

---

Rendered from source

Exact fields, defaults, and validators: Code reference → Core.