Requirements

The system requirements for the Individual Experience AI Engine, written in line with ISO/IEC/IEEE 29148:2018 and traced to visitor user stories.

Requirements are the agreed contract for what the engine must do and how well. They are written so that everyone, from historians and site curators to engineers, reads the same expectation, and so progress can be checked objectively.

Each requirement follows a consistent shape, [Condition] [Subject] [Action] [Object] [Constraint], for example "When signal X is received, the system SHALL store event X within 2 seconds." Mandatory items use SHALL; optional ones use SHOULD or MAY. Every requirement is grounded in a visitor user story (off-site visitor preparing a trip, on-site visitor, remote virtual visitor, organised group), which keeps it traceable from motivation to implementation.

Two categories. Full definitions live in the deliverable's Appendix B; descriptions below. Every row carries its obligation level: SHALL is mandatory, SHOULD is recommended, MAY is optional.

Traceability is carried by the rows themselves: the status icon shows where the requirement stands against the implemented engine, and expanding a row reveals the note (what is missing, for the partials) and the concrete code, section, or endpoint that satisfies it.

met partial designed for not done

Functional, data and storage

WP5-DATA-01SHALLOn consent at registration, store optional visitor info (nationality, place of birth, age range, knowledge level) to a relational DBmet

Note visitor info is captured on consent as survey / identify events and persisted durably, with the Parquet event log (survey_answers) as the store of record rather than a relational table; it is read back for the cold-start bridge. A relational visitor insert also exists, unused by the serving path.

Implementation extract_demographics, normalize_events, DB_Interface register_user (unwired)

WP5-DATA-02SHALLOn interaction with a platform, persist the interaction event to an event storemet

Note events persisted to the Redis buffer and the durable Parquet event log.

Implementation normalize_events, api POST /api/ingest

WP5-DATA-03MAYOn processing text, determine emotional valence via sentiment analysisnot done

Note optional (sentiment / emotional valence); not implemented.

Implementation none yet.

WP5-DATA-04SHALLOn estimating a user state, store the inferred state with contextual metadatamet

Note inferred user state stored as UserSignals with contextual metadata.

Implementation build_user_signals → UserSignals

WP5-DATA-05SHALLOn ingesting content and generating embeddings, persist vectors to a vector DBmet

Note embeddings persisted to Qdrant.

Implementation Vector store (Qdrant)

Functional, behavior

WP5-FR-01SHALLWith no profile data, provide a generic curated experiencemet

Note cold-start never returns an empty list.

Implementation Recommender.recommend

WP5-FR-02SHALLSupport filtering and recommendation by preferred languagenot done

Note no language filtering / recommendation.

Implementation none yet.

WP5-FR-03SHALLCompute similarity between visitor profile and stored prisoner / diary-writer profiles (demographic and knowledge-level)partial

Note demographic similarity yes; knowledge-level similarity no.

Implementation survey_affinity, score_tag

WP5-FR-04SHALLPresent content related to the visitor's live physical location (on-site)met

Note live geo proximity + discrete location filter.

Implementation score_geo, Walkthrough, first recommendations

WP5-FR-05SHALLPresent content matching profile characteristics (nationality, age, gender, visit history)met

Note profile-characteristic matching (nationality, age, gender, visit history).

Implementation score_tag

WP5-FR-06SHALLRetrieve an item's context by querying the KG semantic structurepartial

Note content + tags from Qdrant, semantic + alias fuzzy match; not a true KG traversal.

Implementation Tag system, ContentStore

WP5-FR-07SHALLPerform fuzzy string and semantic matching to connect imprecise inputs to KG entitiespartial

Note semantic + alias fuzzy matching; not full entity-linking to KG entities.

Implementation Tag normalization

WP5-FR-08SHALLEstimate user states (attention, engagement, satisfaction, emotional reaction) in real timepartial

Note engagement, attention, satisfaction estimated; emotional reaction not.

Implementation engagement_strength, classify_outcome

WP5-FR-09SHALLOn focused exploration, offer semantically dissimilar suggestions to encourage discoverymet

Note the distractor (off-profile injection) encourages discovery.

Implementation mmr_rerank + distractor

WP5-FR-10SHALLOn an adaptive action, log the triggering state, affected content, timestamp, and rationalemet

Note durable served log + diagnostics + request_id records the adaptive action.

Implementation api served log, Online serving model

WP5-FR-11MAYProvide KG-based justifications (for example "shared location and event")partial

Note tag-based justifications, not literal KG paths.

Implementation score_tag, Tag system

Non-functional

WP5-NFR-01SHALLDeliver contextual suggestions within 1 second of the triggering interactiondesigned for

Note measurable, not just designed for: every request is timed and GET /api/recommend reports p50 / p95 / p99 against the 1 s budget on /health and /api/metrics. eval/bench_latency.py drives a deployment and exits non-zero if p95 leaves budget. Pending a run against the production stack (Qdrant + Redis); the in-memory dev run is sub-millisecond and is not representative.

Implementation Online serving model, ai_engine.recsys.latency, eval/bench_latency.py, GET /health latency block

WP5-NFR-02SHALLComplete user-state estimation and availability within 1 second of an interactiondesigned for

Note state estimation runs inline in ingest, so the POST /api/ingest round trip is the time until the new state is available; it is timed on the same budget and reported alongside NFR-01. Pending a run against the production stack.

Implementation Online serving model, ai_engine.recsys.latency, eval/bench_latency.py, GET /health latency block

The implemented endpoints and the online serving design that target these latencies are in Online serving model.

FR-06/07 and FR-11 (knowledge graph)

These are partial because recall and justification run over Qdrant content + expert tags + semantic similarity + alias fuzzy matching, which approximates but does not replace a true KG traversal or entity-linking. The explanation cues describe shared tags rather than literal KG paths. See the Tag system.