Struct Context

pub struct Context { /* private fields */ }

A default context for evaluating expressions within AIM workflows.

The Context struct provides a complete implementation of the ContextLike trait that integrates with the AIM workflow system. It supports:

• Variable resolution across multi-level workflow hierarchies
• Function and method dispatch through the global function registry
• Closure parameter management for functional programming constructs
• Caching of evaluation results within a single evaluation session
• Circular reference detection to prevent infinite loops
• Inference operations for agentic workflow execution

Workflow Integration

The context maintains references to workflows at different levels:

• workflow: The current read-only workflow context
• workflow_mut: A mutable workflow for making changes during inference
• scope: The current reference scope for resolving relative references

When evaluating expressions within workflows, the context automatically handles:

• Multi-part reference resolution (e.g., parent.child.value)
• Type promotion and validation for assignments
• Caching of computed values within a session
• Circular reference detection to prevent stack overflows

Thread Safety

Context instances are not thread-safe and should not be shared between threads. Each evaluation session should use its own context instance.

Examples

Basic usage with predefined values:

use aimx::{Context, Literal, Value};

let context = Context::new()
    .with_value("x", Value::Literal(Literal::Number(42.0)))
    .with_value("name", Value::Literal(Literal::Text("Alice".to_string())));

Evaluating expressions within workflows:

use aimx::{Context, aimx_parse, ExpressionLike};

let mut context = Context::new();
// Expressions are evaluated within the context of the workspace workflows
let expression = aimx_parse("some_workflow_value + 10");
let result = expression.evaluate(&mut context);

Implementations

impl Context

pub fn new() -> Self

pub fn workflow(&self) -> Arc<Workflow>

Gets read-only access to the current workflow.

Returns a clone of the Arc reference to the current workflow, allowing read-only access to workflow data without affecting the context’s ownership.

pub fn workflow_mut(&mut self) -> Option<&mut Workflow>

Gets mutable access to the workflow if available.

Returns a mutable reference to the workflow if one is currently being modified, or None if only read-only access is available.

pub fn set_workflow_mut(&mut self, workflow: Workflow)

Sets mutable access to a workflow.

This method is used to provide a workflow that can be modified during evaluation, typically when performing inference operations that need to update workflow values. Note that this requires appropriate write permissions from the lock manager.

Arguments

• workflow - The workflow to make mutable

pub fn clear_workflow_mut(&mut self)

Clears mutable workflow access.

This method releases the mutable workflow reference, reverting to read-only access for subsequent operations.

pub fn writable_start(&mut self)

Begin a writable session on the current workflow.

This method acquires a write lock on the current workflow scope and prepares the context for making modifications. It’s typically used when an inference operation needs to update workflow values.

pub fn writable_end(&mut self)

End a writable session and commit changes.

This method releases the write lock and commits any changes made to the workflow during the writable session. The modified workflow is atomically replaced with the new version.

pub fn new_session(&mut self)

Start a new evaluation session.

This method clears the visited set and cache, preparing the context for a new evaluation session. It’s important to call this method when starting a new independent evaluation to avoid conflicts with cached values from previous evaluations.

pub fn with_value(self, identifier: &str, value: Value) -> Self

Add a predefined value to the context for testing purposes.

This method creates a rule with the given identifier and value and adds it to the workspace. This is primarily used for testing expressions that reference predefined variables.

Arguments

• identifier - The identifier name for the value
• value - The value to associate with the identifier

Returns

Returns the modified context for method chaining.

Trait Implementations

impl ContextLike for Context

fn start_closure(&mut self) -> [(String, Value); 2]

Start a new closure and save the current parameter stack.

fn set_key(&mut self, index: usize, identifier: &str)

Set the key of the indexed mapped variable used by element-wise functions like map.

Arguments

• index - The index key to set (0 or 1)
• identifier - The key to set

fn set_value(&mut self, index: usize, value: &Value)

Set the value of the index mapped variable used by element-wise functions like map.

Arguments

• index - The index value to set (0 or 1)
• value - The value to set

fn end_closure(&mut self, stack: [(String, Value); 2])

End the closure and restore the previous parameter stack.

fn get_referenced(&mut self, reference: &Reference) -> Result<Value>

Get the value of a referenced variable.

This implementation only supports single-part references (default identifiers). Multi-part references (e.g., object.property) are not supported in this simplified context.

Arguments

• reference - The reference to resolve

Returns

Returns a Result<Value> containing the referenced value or an error if the reference cannot be resolved.

fn set_referenced(&mut self, reference: &Reference, value: Value) -> Result<()>

Set the value of a referenced variable.

Arguments

• reference - The reference to set
• literal - The value to assign

Returns

Returns Ok(()) if the referenced value was set or an error if the reference cannot be resolved.

fn function_call(&mut self, name: &str, arg: Value) -> Result<Value>

Call a standalone function.

Delegates function calls to the singleton function registry.

Arguments

• name - The name of the function to call
• arg - The argument(s) to pass to the function

Returns

Returns a Result<Value> containing the function result or an error if the function is not found or execution fails.

fn method_call(&mut self, name: &str, value: Value, arg: Value) -> Result<Value>

Call a method on a value.

Delegates method calls to the singleton function registry.

Arguments

• name - The name of the method to call
• value - The value on which to call the method
• arg - The argument(s) to pass to the method

Returns

Returns a Result<Value> containing the method result or an error if the method is not found or execution fails.

fn inference_call( &mut self, reference: &Reference, _arg: Value, ) -> Result<Value>

Run inference on a referenced workflow.

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.