Template Metadata Reference¶

Sometimes you need to include diagnostic or tracking information in your generated documents — things like when the document was created, which version of the template was used, or details about AI assistant usage. VIBE provides a special meta object that gives you access to this information.

What is Metadata?¶

Metadata is "data about data" — information about your interview session, the template being used, and any AI assistants involved. You can use this to:

• Add timestamps to documents for audit trails
• Track which template version generated a document
• Record AI assistant usage for billing or compliance
• Include session identifiers for troubleshooting
• Show processing information for transparency

Basic Usage: The meta Object¶

The meta object is automatically available in all templates. You access its properties using dot notation:

This document was generated on {{ meta.now()|strftime('%B %d, %Y at %I:%M %p') }}.

Session ID: {{ meta.session_id }}
Template: {{ meta.template.name }} (version {{ meta.template.version }})

Output example:

This document was generated on November 17, 2025 at 02:30 PM.

Session ID: 8b08afe1-2667-4d8a-8bbd-0d1d988f1606
Template: employment_contract (version a3f9c21)

Session Information¶

meta.session_id¶

The unique identifier for this interview session.

For support inquiries, reference session: {{ meta.session_id }}

Use cases:

• Troubleshooting support requests
• Linking documents to interview sessions
• Audit trail requirements

Current Timestamp¶

meta.now()¶

Returns the current date and time as a Python datetime object. Use Jinja's strftime filter to format it.

Generated: {{ meta.now()|strftime('%Y-%m-%d %H:%M') }}

Common date formats:

• '%Y-%m-%d' → 2025-11-17
• '%B %d, %Y' → November 17, 2025
• '%Y-%m-%d %H:%M' → 2025-11-17 14:30
• '%I:%M %p' → 02:30 PM

Note: meta.now() is a function (notice the parentheses), not a property.

Template Information¶

The meta.template object provides details about the template being used. Each property maps to a specific source:

meta.template.title¶

The human-readable display name, from the top-level name key in config.yml:

# config.yml
name: Förnyad konkurrensutsättning

Falls back to the template ID (directory name) when name is not configured.

Document: {{ meta.template.title }}

meta.template.name¶

The template identifier — the directory name of the template bundle (e.g., kravspec, employment_contract). This is stable and unique, unlike title which is a display string.

Document generated using template: {{ meta.template.name }}

meta.template.version¶

The version identifier. For git-managed template sources this is the resolved commit SHA or tag; for local filesystem sources it is WORKING_TREE.

Template version: {{ meta.template.version }}

meta.template.mode¶

The interview mode, from the interview_mode key in config.yml. Defaults to standard when not set. Other modes (assistant, review) require their respective extensions.

{% if meta.template.mode == 'assistant' %}
This document was drafted with AI assistance.
{% endif %}

Interview Progress¶

The meta.progress object provides real-time completion counts based on the probing system. Progress tracks required questions only.

meta.progress.answered¶

Number of required questions that have been answered.

meta.progress.total¶

Total number of required questions currently relevant (this changes as answers make questions appear or disappear).

meta.progress.percent¶

Completion percentage (0–100), computed as answered / total.

meta.progress.state¶

One of "empty" (no required questions), "pending" (in progress), or "complete" (all required questions answered).

{% if meta.progress.state == 'complete' %}
All questions answered.
{% else %}
Progress: {{ meta.progress.answered }}/{{ meta.progress.total }} ({{ meta.progress.percent }}%)
{% endif %}

Note: meta.progress is primarily useful in ui.browser_title for dynamic tab titles. In document templates, progress is always "complete" at render time since rendering only happens when the interview is finished.

AI Assistant Metadata¶

Extension note: Assistant metadata is only available when the Assistant extension is enabled and your template uses assistants or interview_mode: assistant.

If your template uses AI assistants, you can access detailed usage information. The meta.assistant object uses dynamic attribute access — you specify the assistant name directly.

Accessing Assistant Data¶

For an assistant named kravspec:

AI Assistant Usage:
- Endpoint: {{ meta.assistant.kravspec.endpoint }}
- Interactions: {{ meta.assistant.kravspec.turns }}
- Tokens consumed: {{ meta.assistant.kravspec.tokens }}
- Assistant session: {{ meta.assistant.kravspec.session_id }}

meta.assistant.<name>.endpoint¶

The AI model/provider being used (e.g., openai_gpt4, anthropic_claude).

meta.assistant.<name>.turns¶

The number of back-and-forth interactions with the assistant during this session.

meta.assistant.<name>.tokens¶

The total number of tokens consumed by this assistant across all interactions.

meta.assistant.<name>.session_id¶

The assistant-specific session identifier (different from the main interview session ID).

Important: Replace <name> with your actual assistant name as defined in your template's config.yml.

Practical Examples¶

Document Footer with Full Metadata¶

---

**Document Metadata**

- Generated: {{ meta.now()|strftime('%B %d, %Y at %I:%M %p') }}
- Template: {{ meta.template.name }} v{{ meta.template.version }}
- Session: {{ meta.session_id }}
- Mode: {{ meta.template.mode }}

AI Usage Disclosure¶

{% if meta.template.mode == 'assistant' %}
## AI Assistance Disclosure

This document was prepared with assistance from an AI drafting assistant.

**Technical Details:**
- Model: {{ meta.assistant.drafter.endpoint }}
- Interactions: {{ meta.assistant.drafter.turns }}
- Total tokens: {{ meta.assistant.drafter.tokens }}
- Processing session: {{ meta.assistant.drafter.session_id }}

All AI-generated content was reviewed and approved by the user.
{% endif %}

Timestamped Audit Trail¶

**Audit Information**

| Field | Value |
|-------|-------|
| Document Date | {{ meta.now()|strftime('%Y-%m-%d') }} |
| Document Time | {{ meta.now()|strftime('%H:%M:%S') }} |
| Session ID | {{ meta.session_id }} |
| Template | {{ meta.template.name }} |
| Version | {{ meta.template.version }} |

Conditional Assistant Cost Tracking¶

{% if meta.template.mode == 'assistant' %}
<!-- Only show if significant token usage -->
{% if meta.assistant.legal_review.tokens > 10000 %}
**Note:** This document required {{ meta.assistant.legal_review.tokens }} tokens
across {{ meta.assistant.legal_review.turns }} interactions with the AI assistant.
{% endif %}
{% endif %}

Discovering Available Metadata¶

You can see what metadata is available by printing the meta object itself (useful during development):

{{ meta }}

This will show something like:

<MetadataNamespace: session_id, template, progress, assistant, now()>

To see available assistants:

{{ meta.assistant }}

Shows:

<AssistantNamespace: kravspec, legal_review>

Error Handling¶

If you try to access metadata that doesn't exist, VIBE will raise an error during rendering:

Common errors:

❌ Accessing a non-existent assistant:

{{ meta.assistant.undefined_assistant.turns }}

Error: ValueError: Assistant 'undefined_assistant' not found. Available assistants: ['kravspec']

❌ Forgetting parentheses on now():

{{ meta.now }}

Shows: <bound method MetadataNamespace.now of ...> (probably not what you want!)

✅ Correct:

{{ meta.now() }}

Use Cases by Document Type¶

Legal Documents¶

• Timestamp when document was generated
• Track template version for compliance
• Record AI assistant usage for ethical disclosures

Contracts & Agreements¶

• Audit trail with session IDs
• Template version tracking for policy compliance
• Generation timestamp for effective dates

Technical Documentation¶

• Build metadata (template version, generation time)
• Troubleshooting references (session ID)
• Processing information for transparency

Internal Reports¶

• AI usage tracking for budget allocation
• Session tracking for quality control
• Template version for process auditing

Best Practices¶

Do:

• Use meta.now() for human-readable timestamps in documents
• Include session IDs in document footers for support purposes
• Disclose AI assistant usage when relevant
• Use strftime to format dates appropriately for your locale

Don't:

• Expose metadata in user-facing sections unless it adds value
• Forget the parentheses on meta.now()
• Assume all metadata is always available (use conditionals for optional data)
• Mix up interview session ID with assistant session ID

Metadata in Components¶

The meta object is automatically passed to components when you use {{ insert() }} or {{ appendix() }}. This means components can access the same metadata as the main template:

<!-- In a component template -->
Component rendered at {{ meta.now()|strftime('%H:%M') }}
as part of session {{ meta.session_id }}

No special configuration needed — metadata access just works in components.

Quick Reference¶

See Also:

• Template Functions, Filters & Metadata for meta object overview
• Template Authoring Guide for basic Jinja syntax
• Create drafting assistants for setting up AI assistants
• Best Practices for template design patterns