Core Concepts¶

Every VIBE project is built on a few core concepts that work together. Understanding their roles is key to becoming a successful template author.

The Questions File (`config.yml`)¶

This file is the brain of your interview. It's a master list of every possible question you could ask and every piece of information you might need.

Role: Defines the "what"—what information can be gathered.
Contents: The questions block, definitions for reusable data, and other advanced settings.
Key Idea: Think of it as your inventory of all possible data points for a specific template.

The Template File (`template.md` or `template.docx`)¶

This file is the body of your document. It contains the final text, formatting, and layout, along with special placeholders and logic that tell VIBE where to put the answers.

Role: Defines the "how"—how the collected information is used.
Contents: Your standard document text, placeholders like {{ client_name }}, and conditional logic like {% if ... %}.
Key Idea: It's the blueprint for the final output.

Session Context (Pre-filled Data)¶

Sometimes, an interview needs information that the user doesn't provide directly. This data might be specific to the user's company, department, or access level. This is handled by Session Context.

Role: To inject pre-filled, non-editable data into the interview.
How it works: Session context data is typically provided through the authentication system (e.g., in a PASETO token) or through administrator configuration. When a user starts an interview, these variables are automatically loaded and available for use in templates.
Author Impact: As a template author, you declare which session context your template needs in config.yml. You can then use variables like {{ organization.name }} in your template. If the session context defines this variable, its value will be available automatically.

(See: Session Context for complete documentation on declaring session context requirements, creating definition-only components, and configuring session context for development and production.)

Advanced Template Settings in `config.yml`¶

Beyond questions, you can add these top-level keys to config.yml to customize your template's environment.

locale: Sets a specific language for this template, overriding the system default. This affects built-in translations for things like "Yes" and "No" buttons.
```
# Use Swedish for this template
locale: sv
```
filters: Add custom filters to your template's environment. The value should be a path to a Python function.
```
filters:
  euros: shared_filters.format_euros
```
In your template, you could then use {{ amount | euros }}.
imports: Add custom functions or global variables to your template's environment.
```
imports:
  get_signer_title: my_helpers.get_title_for_signer
  current_year: 2024
```
In your template, you could then use {{ get_signer_title(signer_name) }} or just {{ current_year }}.

The VIBE Engine¶

The VIBE Engine is the smart connector that brings the Questions and the Template together. You don't edit the engine directly, but you control it through your files.

Role: To create a dynamic interview and generate the final document.
What it does:
1. Probes the Template: It reads your template file to see which variables are currently needed.
2. Asks Relevant Questions: Based on the probe, it presents only the necessary questions to the user.
3. Generates the Final Document: Once all required questions are answered, it renders the complete, personalized document.

Data Flow and Completion (Short Version)¶

Session context and defaults load first. Pre-filled values are available immediately.
User answers update the session state.
Computables derive values from answered inputs.
Probing re-runs to decide what is relevant.
Completion happens when all relevant required questions are answered. Questions with a default do not block completion. Required validation typically appears after a field is submitted or has a prior answer, to avoid noisy errors during auto-submit.