Skip to content

kyvvu_templates Python API

Behaviour templates — map framework events to Kyvvu atomic behaviors.

Templates are YAML files of first-match-wins rules. Each rule has a match block (conditions) and a behavior block; string values in behavior support {{ path }} and {{ path | default('fallback') }} interpolation against the event context.

This package is the integration-agnostic template system (load, match, interpolate, merge). Its public interface is exactly kyvvu_templates.__all__; the kinds, verbs and configuration error it checks against are the policy engine's, from kyvvu_engine. The YAML templates themselves live with their integration, which advertises each resource through the kyvvu.templates entry-point group. Each integration loads its template by path::

from kyvvu_templates import BehaviorTemplate

tpl = BehaviorTemplate.from_path("/path/to/my_template.yaml")
fields = tpl.match({"event": "on_llm_start", "name": "ChatOpenAI"})

kyvvu_templates.BehaviorTemplate

BehaviorTemplate(data: dict[str, Any]) -> None

A loaded template ready to match events to behavior fields.

Instantiate via from_path (or the load_template alias).

Attributes:

  • name (str) – Template identifier (e.g. "langchain").
  • version (str) – Version string from the YAML file.

Functions:

  • from_path – Load a template from a YAML file.
  • match – Return behavior fields for the first matching rule.

Construct from a parsed YAML dict.

Prefer from_path over calling this directly.

Parameters:

  • data (dict[str, Any]) – Parsed template YAML dict with name, version, and rules keys.

Raises:

  • ValueError – If data is not a dict, is missing rules, or rules is not a list.
  • TemplateError – (a ValueError and a KyvvuConfigError) when a rule is malformed. See validate_rules.

kyvvu_templates.BehaviorTemplate.from_path

from_path(path: str | Path) -> BehaviorTemplate

Load a template from a YAML file.

Parameters:

  • path (str | Path) – Filesystem path to a .yaml template file.

Returns:

Raises:

  • FileNotFoundError – When path does not exist.
  • ImportError – When pyyaml is not installed.
  • ValueError – When the file is malformed.

kyvvu_templates.BehaviorTemplate.match

match(context: dict[str, Any]) -> dict[str, Any] | None

Return behavior fields for the first matching rule.

Evaluation stops at the first rule whose match block fully matches the context (first-match-wins). String values in the returned dict are already interpolated from context.

Parameters:

  • context (dict[str, Any]) – Event or call context dict.

Returns:

  • dict[str, Any] | None – Dict with behavior fields (kind, verb, step_name,
  • dict[str, Any] | None – properties, ...), or None when no rule matches.

kyvvu_templates.BehaviorTemplate.name

name: str = name

kyvvu_templates.BehaviorTemplate.rules

rules: list[dict[str, Any]]

Read-only copy of the rule dicts (without interpolation applied).

kyvvu_templates.BehaviorTemplate.version

version: str = str(data.get('version', ''))

kyvvu_templates.TemplateError

A template file is malformed. The message names the rule and the fix.

Also a ValueError, which is what the loader raised for the structural problems it already caught.

kyvvu_templates.deep_merge

deep_merge(base: dict[str, Any], overlay: dict[str, Any]) -> dict[str, Any]

Return a new dict merging overlay on top of base.

Merge semantics: - Nested dicts merge recursively. - Leaf values: overlay wins. - Lists: overlay replaces base (no extension). - Missing keys on either side fill from the other. - An explicit None in overlay overrides a base value. - A missing key in overlay does not override.

Neither base nor overlay is mutated.

Parameters:

  • base (dict[str, Any]) – The base dict (e.g. from template match).
  • overlay (dict[str, Any]) – The overlay dict (e.g. caller-provided overrides).

Returns:

  • dict[str, Any] – A new merged dict.

Example::

>>> deep_merge({"a": 1, "b": {"x": 10}}, {"b": {"y": 20}, "c": 3})
{'a': 1, 'b': {'x': 10, 'y': 20}, 'c': 3}

kyvvu_templates.discover_templates

discover_templates() -> dict[str, EntryPoint]

Find template resource declarations from installed distributions.

kyvvu_templates.load_template

load_template(path: str | Path) -> BehaviorTemplate

Load a template from a YAML file (alias for from_path).