Core concepts
Nevola Engine has four core abstractions: profiles, temporal-contextual signals, templates, and sequences. Together they define how context becomes content.
1. Profiles
A profile is a personalization context handle. It stores the minimum data Nevola needs to generate contextual content: an external user reference, a locale, and customer-defined attributes such as plan, lifecycle stage, audience segment, or content preferences.
A profile is not a user account. It is not a CRM record. Keep authentication, billing, consent records, and account ownership in your own system. Store the Nevola profile ID beside your internal user ID and pass it into personalization requests.
Example: an edtech platform creates prof_01HXY7R4F2M8K6P0QJ9T3V5NWA for an active learner with locale en-GB, plan pro, lifecycle stage activated, and preferred content format course_step. Later, the platform updates only lifecycle_stage to retained without changing the user account.
Common mistake to avoid: putting raw PII or full CRM exports into attributes. Use opaque identifiers and product context only.
2. Temporal-Contextual Signals
Temporal-contextual signals are derived attributes computed from timestamp, locale, and profile context. They are deterministic. The same profile, computation time, locale, and definition version produce the same value.
Signals are versioned because content teams need stable behavior. A template can reference weekday_window or content_cadence_match and know which calculation version produced the value returned in the API response.
Example: a B2B newsletter product requests content at 2025-02-14T10:22:30Z for a profile with locale en-GB and weekday cadence. Nevola returns weekday_window: friday and cadence_fit: weekday, both with calculation version 2025-02-01.
Common mistake to avoid: treating signals as editable profile fields. Update the profile context if needed; let the Signals API compute the derived values.
3. Templates
A template is a versioned prompt and schema artifact in the registry. It defines what kind of content should be generated, which fields must be returned, and which signals or profile attributes are allowed as inputs.
Templates make personalization repeatable. Product teams can publish tmpl_newsletter_retention_v3, keep version 2 available for older flows, and route new requests to version 3 through the API.
Example: a wellness coaching app uses tmpl_checkpoint_v2 to produce a checkpoint payload with title, body, and next_action. The schema keeps the response stable even when the copy changes.
Common mistake to avoid: hard-coding free-form output parsing in your application. Use the template schema as the contract.
4. Sequences
A sequence is an ordered set of personalized content items generated asynchronously. It is used when one request should create multiple pieces of content, such as a course onboarding path, a daily content run, or a multi-step customer education flow.
Sequence runs return 202 Accepted with a sequence_run_id. Your application can poll the run status or receive a webhook event when generation completes or fails.
Example: an edtech platform starts seq_course_onboarding_v2 for prof_01HXY7R4F2M8K6P0QJ9T3V5NWA. Nevola generates a course_step first, then a checkpoint, and sends personalize.sequence.completed to the configured webhook URL.
Common mistake to avoid: using synchronous content generation for a multi-step flow that does not need an immediate response. Start a sequence and handle completion outside the original request path.