vibe.metadata

Template metadata access system.

Provides a self-documenting namespace for accessing session, template, and assistant metadata from within Jinja2 templates.

Usage in templates

{{meta.session_id}} - Interview session UUID {{meta.now()|strftime('%Y-%m-%d')}} - Current timestamp {{meta.template.name}} - Template identifier {{meta.assistant.kravspec.turns}} - Assistant turn count {{meta.phase}} - Processing phase (PROBING or RENDERING)

Design principles: - Functions (): Compute/generate new values (e.g., now()) - Properties: Access existing data/state (e.g., session_id) - Strict errors: Raise ValueError when metadata unavailable during rendering - Graceful during probing: Return "N/A" when session not available

MetadataNamespace

Root metadata namespace for template access.

Provides access to session, template, and assistant metadata through a self-documenting interface.

Attributes:
  • session_id (str) –

    Interview session UUID

  • template (TemplateMetadata) –

    TemplateMetadata instance

  • assistant (AssistantNamespace) –

    AssistantNamespace instance

  • phase –

    ProcessingPhase enum value

Methods:

  • now –

    Returns current datetime object

session_id 

session_id: str

Interview session UUID.

Returns:
  • str –

    Session UUID string, or "N/A" if session not available during probing.
Raises:
  • KeyError –

    If session_id missing during rendering phase (indicates session corruption).

template 

template: TemplateMetadata

Template information (name, version, mode).

Returns:
  • TemplateMetadata –

    TemplateMetadata instance with access to template properties.

assistant 

assistant: AssistantNamespace

Dynamic namespace for accessing assistant metadata by name.

Usage

{{meta.assistant.kravspec.turns}} {{meta.assistant.legal_review.tokens}}

Returns:
  • AssistantNamespace –

    AssistantNamespace instance that provides dynamic attribute access.

__init__ 

__init__(session_data: Mapping[str, Any] | None, template: TemplateData, phase: ProcessingPhase) -> None

Initialize metadata namespace.

Parameters:
  • session_data (Mapping[str, Any] | None) –

    Flask session dict or SessionMixin, or None during probing without session

  • template (TemplateData) –

    TemplateData instance

  • phase (ProcessingPhase) –

    ProcessingPhase.PROBING or ProcessingPhase.RENDERING

now 

now() -> datetime

Return current timestamp as datetime object.

Use with Jinja filters for formatting

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

Returns:
  • datetime –

    Current datetime object

TemplateMetadata

Template metadata accessor.

Provides access to template properties like name, version, and mode.

Attributes:
  • name (str) –

    Template identifier

  • version (str) –

    Version identifier (Git SHA or WORKING_TREE)

  • mode (str) –

    Interview mode (standard, assistant, or review)

name 

name: str

Template identifier.

Returns:
  • str –

    Template ID string (e.g., 'kravspec', 'employment_contract')

version 

version: str

Version identifier.

Returns:
  • str –

    Git SHA or "WORKING_TREE" for development templates

mode 

mode: str

Interview mode.

Returns:
  • str –

    One of: 'standard', 'assistant', 'review'

__init__ 

__init__(template: TemplateData) -> None

Initialize template metadata.

Parameters:

AssistantNamespace

Dynamic namespace for assistant metadata access.

Supports attribute access by assistant name. Each assistant name accessed returns an AssistantMetadata instance for that assistant.

Usage

meta.assistant.kravspec -> AssistantMetadata('kravspec') meta.assistant.legal_review -> AssistantMetadata('legal_review')

Attributes are resolved dynamically via getattr.

__init__ 

__init__(session_data: Mapping[str, Any] | None, template: TemplateData, phase: ProcessingPhase) -> None

Initialize assistant namespace.

Parameters:
  • session_data (Mapping[str, Any] | None) –

    Flask session dict or SessionMixin containing assistants data

  • template (TemplateData) –

    TemplateData instance

  • phase (ProcessingPhase) –

    Current processing phase (PROBING or RENDERING)

AssistantMetadata

Metadata for a specific assistant instance.

Provides access to assistant-specific data like turn count, token usage, endpoint name, and session ID.

Attributes:
  • turns (int) –

    Number of turns/interactions with this assistant

  • tokens (int) –

    Total tokens consumed by this assistant

  • average_tft (float) –

    Average time-to-first-token in seconds across all turns

  • average_tlt (float) –

    Average time-to-last-token in seconds across all turns

  • endpoint (str) –

    LLM endpoint/provider name

  • session_id (str) –

    Assistant-specific session ID

turns 

turns: int

Number of turns/interactions with this assistant.

Returns:
  • int –

    Turn count (sequence_number from assistant state), or 0 if not yet started

tokens 

tokens: int

Total tokens consumed by this assistant.

Returns:
  • int –

    Cumulative token count across all interactions, or 0 if not yet started

cost 

cost: str

Total cost for this assistant as a formatted string.

Returns:
  • str –

    Formatted cost string (e.g., "$ 0.0455") or "N/A" if cost tracking

  • str –

    is not configured for this endpoint.

average_tft 

average_tft: float

Average time-to-first-token across all turns with this assistant.

Returns:
  • float –

    Average TFT in seconds, or 0.0 if not yet measured

average_tlt 

average_tlt: float

Average time-to-last-token across all turns with this assistant.

Returns:
  • float –

    Average TLT in seconds, or 0.0 if not yet measured

endpoint 

endpoint: str

LLM endpoint/provider name.

First checks for dev override (if in debug mode), then tries session state (runtime value), then falls back to template config (static configuration).

Returns:
  • str –

    Endpoint name (e.g., 'openai_gpt4', 'anthropic_claude')
Raises:
  • ValueError –

    If endpoint not found in session state or template config

session_id 

session_id: str

Assistant-specific session ID.

Note: This is different from the interview session ID. Each assistant has its own session ID for tracking assistant interactions.

Returns:
  • str –

    Assistant session UUID string, or "N/A" if not yet created

__init__ 

__init__(session_data: Mapping[str, Any], assistant_name: str, template: TemplateData, is_placeholder: bool = False) -> None

Initialize assistant metadata.

Parameters:
  • session_data (Mapping[str, Any]) –

    Flask session dict or SessionMixin

  • assistant_name (str) –

    Name of the assistant to access

  • template (TemplateData) –

    TemplateData instance (for accessing config)

  • is_placeholder (bool, default: False ) –

    If True, returns defaults for attributes not yet initialized