aimx/values/
mod.rs

1//! Special value types for AIMX expressions.
2//!
3//! This module provides specialized value types that extend the core [`crate::value::Value`] enum
4//! with domain-specific functionality for agentic workflow applications. These types
5//! represent runtime values with specific semantics beyond basic literals and arrays.
6//!
7//! # Overview
8//!
9//! The values module contains:
10//!
11//! - [`Errata`] - Error representation with diagnostic information
12//! - [`Eval`] - Evaluation scoring and statistics
13//! - [`Format`] - Output formatting instructions
14//! - [`Node`] - Workflow node references with lazy loading
15//!
16//! These types are integrated into the AIMX expression system and can be used
17//! alongside standard literals and arrays in expressions and workflow rules.
18//!
19//! # Usage
20//!
21//! ```rust
22//! use aimx::values::*;
23//! use aimx::Reference;
24//!
25//! // Create error values with diagnostic information
26//! let error = Errata::new_reason_formula(
27//!     "Division by zero".to_string(),
28//!     "10 / 0".to_string()
29//! );
30//!
31//! // Create evaluation scoring values
32//! let eval = Eval::new(5, 10); // 5 successes out of 10 attempts
33//!
34//! // Create formatting instructions
35//! let format = Format::new(
36//!     "Display as currency".to_string(),
37//!     "$0.00".to_string(),
38//!     vec!["$42.00".to_string(), "$123.45".to_string()]
39//! );
40//!
41//! // Create workflow node references
42//! let node = Node::new(Reference::new("workflow/path"));
43//! ```
44//!
45//! # Integration with Core Types
46//!
47//! These value types are wrapped in the main [`crate::value::Value`] enum variants:
48//!
49//! - `Value::Errata(Errata)` - Error values
50//! - `Value::Eval(Eval)` - Evaluation statistics
51//! - `Value::Format(Format)` - Formatting instructions
52//! - `Value::Node(Node)` - Workflow node references
53//!
54//! They implement the [`crate::evaluate::ExpressionLike`] trait and can be evaluated, written,
55//! and formatted like any other AIMX value.
56//!
57//! # Error Handling
58//!
59//! The [`Errata`] type provides comprehensive error reporting with three levels
60//! of detail:
61//!
62//! - **Level 1**: Basic error reason only
63//! - **Level 2**: Error reason and problematic formula
64//! - **Level 3**: Full diagnostic with reason, formula, and location
65//!
66//! This enables detailed error reporting throughout the expression evaluation pipeline.
67//!
68//! # Workflow Integration
69//!
70//! The [`Node`] type provides lazy-loaded workflow references that support
71//! concurrent access patterns. Nodes can be in one of two states:
72//!
73//! - **Unloaded**: Contains only the reference path, loads on first access
74//! - **Loaded**: Contains the actual workflow as an immutable snapshot
75//!
76//! This architecture supports the MVCC (Multi-Version Concurrency Control)
77//! model used throughout the AIMX system.
78//!
79//! # Examples
80//!
81//! ## Error Handling
82//!
83//! ```rust
84//! use aimx::{values::Errata, evaluate::ExpressionLike, context::Context};
85//!
86//! let error = Errata::new_reason_formula_location(
87//!     "Syntax error".to_string(),
88//!     "1 + * 2".to_string(),
89//!     "* 2".to_string()
90//! );
91//!
92//! let mut context = Context::new();
93//! let result = error.evaluate(&mut context).unwrap();
94//! assert!(result.has_error());
95//! ```
96//!
97//! ## Evaluation Scoring
98//!
99//! ```rust
100//! use aimx::{values::Eval, evaluate::ExpressionLike, context::Context};
101//!
102//! let eval = Eval::new(3, 5); // 3 successes out of 5 attempts
103//! let mut context = Context::new();
104//! let result = eval.evaluate(&mut context).unwrap();
105//! assert!(result.is_eval());
106//! ```
107//!
108//! ## Formatting Instructions
109//!
110//! ```rust
111//! use aimx::{values::Format, evaluate::ExpressionLike, context::Context};
112//!
113//! let format = Format::new(
114//!     "Format as percentage".to_string(),
115//!     "0.0%".to_string(),
116//!     vec!["42.5%".to_string(), "99.9%".to_string()]
117//! );
118//!
119//! let mut context = Context::new();
120//! let result = format.evaluate(&mut context).unwrap();
121//! assert!(result.is_format());
122//! ```
123//!
124
125pub mod errata;
126pub mod eval;
127pub mod format;
128pub mod node;
129
130pub use errata::{Errata};
131pub use eval::{Eval, parse_eval};
132pub use format::{Format, parse_format};
133pub use node::Node;
aimx/values/mod.rs

aimx/values/
mod.rs
