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.

meta.template.name¶

The template identifier.

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

meta.template.version¶

The version identifier (Git commit SHA or "WORKING_TREE" for development).

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

meta.template.mode¶

The interview mode: standard, assistant, or review (assistant mode requires the Assistant extension).

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

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.

Processing Phase¶

meta.phase¶

Indicates whether the template is being processed for probing (dependency tracking) or rendering (final output). Value is either PROBING or RENDERING.

<!-- This is mainly useful for debugging -->
Processing phase: {{ meta.phase }}

Most template authors won't need this — it's primarily for advanced debugging scenarios.

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, assistant, now(), phase=rendering>

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 }}

❌ Forgetting parentheses on now():

{{ meta.now }}

✅ 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 Authoring Guide for basic Jinja syntax
• Create drafting assistants for setting up AI assistants
• Best Practices for template design patterns