calute.cortex.core.string_utils

calute.cortex.core.string_utils#

String utility functions for template interpolation.

This module provides utilities for working with template strings that use simple placeholder syntax (e.g., {variable_name}). It includes: - Template variable interpolation with type-safe value substitution - Template variable extraction for validation - Input validation against template requirements

Unlike the Jinja2-based PromptTemplate class, these utilities use a simpler placeholder syntax that is compatible with Python’s str.format() but with additional type safety and validation features.

Example

>>> from calute.cortex.string_utils import interpolate_inputs
>>> result = interpolate_inputs(
...     "Hello {name}, you have {count} messages.",
...     {"name": "Alice", "count": 5}
... )
>>> print(result)
Hello Alice, you have 5 messages.

>>> from calute.cortex.string_utils import validate_inputs_for_template
>>> is_valid, errors = validate_inputs_for_template(
...     "Hello {name}",
...     {"name": "World"}
... )
>>> print(is_valid)
True
calute.cortex.core.string_utils.extract_template_variables(input_string: str) → set[str][source]#

Extract all template variable names from a string.

Scans the input string for placeholders following the {variable_name} pattern and returns a set of all unique variable names found. Variable names must start with a letter or underscore and contain only alphanumeric characters and underscores.

Parameters

input_string – String potentially containing {variable} placeholders. If None or empty, returns an empty set.

Returns

Set of unique variable name strings found in the template. Returns an empty set if no placeholders are found or input is empty.

Example

>>> extract_template_variables("Hello {name}, year {year}")
{'name', 'year'}
>>> extract_template_variables("No placeholders here")
set()
>>> extract_template_variables("")
set()
calute.cortex.core.string_utils.interpolate_inputs(input_string: str | None, inputs: dict[str, str | int | float | dict[str, Any] | list[Any]]) → str[source]#

Interpolate placeholders (e.g., {key}) in a string with provided values.

Only interpolates placeholders that follow the pattern {variable_name} where variable_name starts with a letter/underscore and contains only letters, numbers, and underscores.

Parameters

  • input_string – The string containing template variables to interpolate. Can be None or empty, in which case an empty string is returned.

  • inputs – Dictionary mapping template variables to their values. Supported value types are strings, integers, floats, and dicts/lists containing only these types and other nested dicts/lists.

Returns

The interpolated string with all template variables replaced with their values. Empty string if input_string is None or empty.

Raises

  • KeyError – If a template variable is missing from inputs

  • ValueError – If a value contains unsupported types

Examples

>>> interpolate_inputs("Hello {name}!", {"name": "World"})
"Hello World!"

>>> interpolate_inputs("Year: {year}, Topic: {topic}", {"year": 2025, "topic": "AI"})
"Year: 2025, Topic: AI"
calute.cortex.core.string_utils.validate_inputs_for_template(template_string: str, inputs: dict[str, Any], allow_extra: bool = True) → tuple[bool, list[str]][source]#

Validate that all required template variables are present in inputs.

Checks whether the provided inputs dictionary contains values for every template variable found in the template string. Optionally validates that no extra (unused) keys exist in the inputs.

Parameters

  • template_string – String containing {variable} template placeholders to validate against.

  • inputs – Dictionary of provided input values. Keys should correspond to template variable names.

  • allow_extra – Whether to allow extra keys in inputs that are not referenced in the template. When False, extra keys generate error messages. Defaults to True.

Returns

  • is_valid: True if all required variables are present and no disallowed extra keys exist.

  • errors: List of error message strings. Empty list if valid. Messages follow the format “Missing required variable: {name}” or “Unexpected variable: {name}”.

Return type

Tuple of (is_valid, errors) where

Example

>>> validate_inputs_for_template("Hello {name}", {"name": "World"})
(True, [])
>>> validate_inputs_for_template("Hello {name}", {})
(False, ["Missing required variable: name"])
>>> validate_inputs_for_template("{x}", {"x": 1, "y": 2}, allow_extra=False)
(False, ["Unexpected variable: y"])
Contents