Feature: Allow for templating of nested objects in instructions

[whoisarpit]

Fixes #575

Summary

Adds support for nested dot-separated references in instruction templates. Users can now access deeply nested values in the state object using a simple dot notation, with optional markers at any level of the path.

This is useful when templating structured data from a previous LlmAgent using output_schema.

Changes

• Enhanced _populate_values function to handle nested dot-separated references
• Supports optional markers at any level with ? suffix (e.g., {user?.profile?.name?})
• Updated existing tests and added new test cases for the nested templating functionality

Examples

Before:

# Only simple values were supported
"{customerId}" -> "1234567890"
"{user:profile}" -> "basic"
"{user.profile.name}" -> "{user.profile.name}"

After:

# Now supports nested references
"{user.profile.name}" -> "John Doe"
"{user.settings.theme}" -> "dark"

# Optional markers at any level
"{user?.profile?.email}" -> "[email protected]"
"{user?.preferences?.theme?}" -> "" (empty if path doesn't exist)

# Invalid paths without optional markers will not be templated instead of throwing an error to avoid breaking changes
"{user.invalid.path}" -> "{user.invalid.path}"

Use Cases

• Accessing complex nested objects in state
• Optional references that gracefully handle missing values
• Better organization of state data with hierarchical structures

This feature enables more flexible template interpolation, allowing for cleaner, more organized state structures while maintaining backward compatibility with the existing flat state model.