Context Variables¶

Status¶

This document defines:

• the runtime context variable contract
• how values are actually resolved at load time
• how build context relates to workflow context variables
• the concrete variable-by-variable acquisition logic for first-party factory workflows where that detail matters

Canonical File¶

workflows/{workflow}/context_variables.yaml

Canonical Contract Shape¶

definitions:
  variable_name:
    type: string
    description: Optional description
    source:
      type: state
      default: null

agents:
  AgentName:
    variables:
      - variable_name

Rules:

• definitions is a map (name -> definition).
• agents is a map (agent_name -> {variables: [...]}).
• unknown fields are rejected.

Runtime Resolution Semantics¶

Source types supported by runtime:

• config
• data_reference
• data_entity
• computed
• state
• external
• file
• build_context

config¶

• Reads source.env_var from environment.
• If env var is missing, falls back to source.default.
• If source.required is true and value is still missing, load fails.
• Applies type coercion for booleans and integers.

data_reference¶

• Resolves adapter via get_db_adapter(source).
• Materializes query_template placeholders:
• {{runtime.app_id}} -> current app id
• {{runtime.<key>}} -> context value lookup
• {{some_var.path}} -> context dereference
• Uses fields to build projection.
• If one field is requested, returns that single field value.
• If no matching document:
• returns source.default when provided
• otherwise None

data_entity¶

• Creates a DataEntityManager for workflow-owned writes.
• Injects manager object into context key.

computed¶

• Initializes key to None at load.
• Expected to be populated later by tools/agent execution.

state¶

• Initializes key to source.default at load (with type coercion).
• Trigger metadata is declared in config and used by runtime mechanisms for updates.

external¶

• Initializes key to None at load.
• Intended to be populated by integration tools.

file¶

• Resolves relative paths from repo root.
• Enforces repo-root safety (unless CONTEXT_FILE_ALLOW_OUTSIDE_ROOT=true).
• Denies common secret files (.env, .pem, .key, etc.).
• Parses by format:
• json (default)
• yaml
• text
• Falls back to default if not required and missing/invalid.

build_context¶

• Declares a workflow slot that may be populated from active build_context/{context_name}/context.yaml files at launch time.
• Initializes to None during normal context variable loading.
• Receives projected values only when the launch path enables the build-context provider, typically through:

MOZAIKS_LAUNCH_CONTEXT_PROVIDER=mozaiksai.core.session.build_context:merge_build_context

• The provider discovers contexts from MOZAIKS_BUILD_CONTEXT_PATH, or from MOZAIKS_APP_WORKSPACE_PATH/build_context when an explicit build-context path is not set.
• Explicit launch context values take precedence over build-context projected values.
• Build-context values are accepted only as declared workflow context variables. A build context does not get to add arbitrary runtime state to a workflow.

Use build_context source variables for small, structured launch-time values such as selected pack descriptors, operator capability ids, provider-backed capability lists, or typed operator contracts. Do not put large prompt catalogs or template contents directly in context_variables.yaml.

Build Context vs. Context Variables¶

These are separate contracts with one bridge.

context_variables.yaml is the workflow ABI. It declares the state shape that runtime, tools, transitions, and agents may read or update during a run. It is workflow-owned and should stay stable across OSS, Studio, and hosted-product deployments.

build_context/{context_name}/context.yaml is a build-time input registry. It declares reusable or operator-selected assets such as prompt catalogs, typed contracts, templates, pack descriptors, and provider-backed capability metadata. It can live in the OSS factory or in a hosted/customer workspace beside app/ and workflows/.

The bridge is explicit:

1. A workflow declares a variable with source.type: build_context.
2. A build-context registry declares projections.context_variables.
3. The launch provider projects only those declared values into the workflow context before execution.

Prompt-heavy input follows a different path. Catalog assets are declared in context.yaml assets[] and injected by deterministic prompt middleware. They should not be copied into mutable workflow state unless a small selected value is needed by tools or transitions.

Example:

# workflows/AppGenerator/context_variables.yaml
definitions:
  capability_packs:
    type: array
    source:
      type: build_context
      default: []

# build_context/mozaikspay/context.yaml
context_id: mozaikspay
applies_to_workflows:
  - AppGenerator
assets:
  - path: contract.yaml
    kind: contract
  - path: templates/
    kind: templates
pack:
  id: mozaikspay
  status: active
projections:
  context_variables:
    capability_packs:
      from: capability_packs

Prompt Projection¶

Some build-context assets are not runtime variables at all. They are prompt inputs for specific agents.

Catalog assets can declare prompt projections:

assets:
  - path: ag2_network_patterns.yaml
    kind: catalog
    projections:
      - id: ag2_patternbook_summary_for_decomposition
        records: patterns
        recipients:
          - PatternAgent
        render: summary
        marker: PATTERN_GUIDANCE_AND_EXAMPLES
      - id: ag2_selected_pattern_for_bundle_builder
        records: patterns
        recipients:
          - WorkflowBundleBuilderAgent
        render: selected_record
        selected_by: current_task.pattern_id
        record_id_field: id
        marker: PATTERN_GUIDANCE_AND_EXAMPLES

This lets one agent see a compact catalog summary while a later agent receives only the selected record. The selection key lives in normal workflow state; the large catalog stays in build context.

AgentGenerator Context Variables¶

Source file analyzed:

• factory_app/workflows/AgentGenerator/context_variables.yaml

Resolution Matrix¶

Runtime-Injected Schema Capability Keys¶

These keys are available in context even when not declared in definitions:

• database_schema_available (boolean)
• database_schema_db (string | null)
• schema_overview (string, when schema loading is enabled)
• collections_first_docs_full (object, when schema loading is enabled)

They are injected by core/workflow/context/variables.py when CONTEXT_INCLUDE_SCHEMA=true and a schema DB is configured.

Local Testing Without Seeded DB Data¶

When your data_reference values (for example concept_overview) do not exist yet, runtime can load explicit fallback values from a JSON file.

Environment variable:

• MOZAIKS_CONTEXT_FALLBACKS_FILE

Example:

MOZAIKS_CONTEXT_FALLBACKS_FILE=

Fallback file shape:

{
  "global": {
    "some_data_reference_var": "fallback value"
  },
  "workflows": {
    "AgentGenerator": {
      "concept_overview": "fallback overview",
      "concept_api_endpoints": [],
      "concept_blueprint": {}
    }
  }
}

Resolution order for data_reference variables when DB result is None:

1. workflow-scoped fallback (workflows.<workflow_name>.<variable>)
2. global fallback (global.<variable>)
3. convenience flat root object (<variable>) when no global/workflows wrapper exists

Agent Exposure¶

agents is used to define which variables are exposed to each agent for context injection. Keep this minimal per agent to reduce token load and accidental coupling.

Minimal Valid Example¶

definitions: {}
agents:
  GreeterAgent:
    variables: []