aimx/

lib.rs

//! # AIM Expressions (AIMX)
//!
//! Agentic Inference Markup Expressions (AIMX) is a high-performance, C-like declarative language
//! for writing formulas to control inference in agentic workflows.
//! 
//! This rust library provides an entry point to the entire Aim workspace. It is can be used by
//! server daemons for workflow deployment, integrated development tools for hand coding agentic
//! workflows, web, desktop and mobile application front ends for both visual design tools and
//! agentic inference applications.  
//!
//! The language was created to improve upon the familiar declarative syntax of spreadsheet formulas
//! by replacing error-prone cell referencing (e.g., `A1`) with a robust, C-style variable naming
//! convention. This enables powerful, readable patterns like multi-part reference chaining
//! (`employee.salary`), array indexing (`matrix[index]`), method calling (`sales.average().round_to(2)`)
//! and functional programming with closures `plan.perform(task => $tool.write_paragraph(task, context))`.
//! By using a subset of C-like syntax, AIMX is immediately familiar to developers who know
//! Javascript, TypeScript, C#, or similar languages. It strikes a balance between simplicity and
//! expressive power, making it effective for a wide range of tasks—from automating business
//! processes to orchestrating complex AI agent pipelines.
//!
//! ## Key Features
//!
//! - **C-like Syntax**: Familiar operators and expressions with simplified syntax
//! - **Rich Type System**: Strong typing with automatic type promotion and casting
//! - **Built-in Functions**: Comprehensive standard library with mathematical, text, date, and collection functions
//! - **Agentic Workflow Integration**: Native support for AI inference calls and task management
//! - **Concurrent Architecture**: Thread-safe evaluation with multi-version concurrency control
//! - **Extensible**: Custom function registration and modular design
//!
//! # Quick Start
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context, Literal, Value};
//!
//! // Parse and evaluate a simple expression
//! let expression = aimx_parse("2 + 3 * 4");
//! let mut context = Context::new();
//! let result = expression.evaluate(&mut context).unwrap();
//! assert_eq!(result.to_string(), "14");
//!
//! // Work with variables and functions
//! let mut context = Context::new()
//!     .with_value("base_price", Value::Literal(Literal::Number(100.0)))
//!     .with_value("tax_rate", Value::Literal(Literal::Number(0.08)));
//! 
//! let expression = aimx_parse("base_price * (1 + tax_rate)");
//! let result = expression.evaluate(&mut context).unwrap();
//! assert_eq!(result.to_string(), "108");
//! ```
//!
//! # Core Concepts
//!
//! ## Expressions and Evaluation
//!
//! AIMX expressions are parsed into an abstract syntax tree (AST) that can be evaluated
//! within a context. The context provides variable values, function implementations, and
//! manages the runtime environment.
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context};
//!
//! // Parse expressions
//! let expr1 = aimx_parse("5 > 3 ? \"yes\" : \"no\"");
//! let expr2 = aimx_parse("sqrt(16) + abs(-5)");
//! 
//! // Evaluate in context
//! let mut context = Context::new();
//! let result1 = expr1.evaluate(&mut context).unwrap();
//! let result2 = expr2.evaluate(&mut context).unwrap();
//! 
//! assert_eq!(result1.to_string(), "yes");
//! assert_eq!(result2.to_string(), "9");
//! ```
//!
//! ## Type System
//!
//! AIMX is a strongly typed language with automatic type promotion. The left operand's type
//! generally dictates the conversion for the right operand.
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context};
//!
//! let mut context = Context::new();
//! 
//! // Type promotion examples
//! let expr1 = aimx_parse("\"Total: \" + 42");     // String promotion → "Total: 42"
//! let expr2 = aimx_parse("2 + \"40\"");           // Number promotion → 42
//! let expr3 = aimx_parse("(Text)96");            // Explicit casting → "96"
//! 
//! // Boolean conversion (any type can be converted to bool)
//! let expr4 = aimx_parse("value ? value : \"default\"");
//! ```
//!
//! ## Grammar Reference
//!
//! ### Operators (in order of precedence, highest to lowest)
//!
//! | Operators | Description | Associativity |
//! |-----------|-------------|---------------|
//! | `()` | Parentheses | Left to right |
//! | `_` | Empty placeholder | Singular |
//! | `=>` | Closure | Left to right |
//! | `.` `()` `[]` `$` | Postfix operations | Left to right |
//! | `!` `+` `-` `(type)` | Unary operators | Right to left |
//! | `*` `/` `%` | Multiplicative | Left to right |
//! | `+` `-` | Additive | Left to right |
//! | `<` `<=` `>` `>=` | Relational | Left to right |
//! | `=` `!=` | Equality | Left to right |
//! | `&` `&&` | Logical AND | Left to right |
//! | `|` `||` | Logical OR | Left to right |
//! | `?` `:` | Conditional (ternary) | Right to left |
//! | `,` | Array separator | Left to right |
//! | `;` | Procedure separator (closures only) | Left to right |
//!
//! ### Data Types
//!
//! - **`Bool`**: Boolean values (`true` or `false`)
//! - **`Number`**: 64-bit floating point numbers
//! - **`Text`**: UTF-8 string values  
//! - **`Date`**: Date and time values
//! - **`Task`**: Task primitives with status and description
//! - **`Array`**: Collections of values (homogeneous or heterogeneous)
//! - **`Closure`**: First-class anonymous functions
//! - **`Node`**: References to workflow files
//!
//! ### Special Syntax
//!
//! **Tasks**: AIMX has dedicated syntax for creating tasks that consumes the `[]` prefix:
//!
//! ```text
//! [x] "A completed task"      // → Boolean true
//! [-] "A failed task"        // → Number -1.0
//! [ ] "A pending task"       // → Text value
//! ```
//!
//! **Arrays**: Because `[]` is used for tasks, arrays use parentheses like argument lists in C:
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context};
//!
//! let mut context = Context::new();
//! 
//! // Array expressions
//! let expr = aimx_parse("(1, 2, 3).sum()");
//! let result = expr.evaluate(&mut context).unwrap();
//! assert_eq!(result.to_string(), "6");
//! ```
//!
//! ## Agentic Workflow Integration
//!
//! AIMX is designed for agentic workflow applications with special conventions for AI inference:
//!
//! - **Assignment Rules** (`_` prefix): Rules prefixed with underscore are meant to be populated by AI inference
//! - **Modifier Rules** (UPPERCASE): All-uppercase identifiers construct prompts for language models
//! - **Inference Calls** (`$` prefix): References starting with `$` trigger inference calls to workflow nodes
//!
//! ```rust
//! # // Note: This example shows the pattern, actual inference integration requires workflow setup
//! # use aimx::{aimx_parse, ExpressionLike, Context};
//! #
//! # let mut context = Context::new();
//! # let expr = aimx_parse("$tool.summarize_email(message_body)");
//! # // The above would trigger inference on the 'summarize_email' workflow node
//! ```
//!
//! # Examples
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context};
//! 
//! let mut context = Context::new();
//! 
//! // Mathematical expressions
//! let expr = aimx_parse("(2 + 3) * 4 / 2");
//! assert_eq!(expr.evaluate(&mut context).unwrap().to_string(), "10");
//! 
//! // Boolean logic
//! let expr = aimx_parse("true & false | !false");
//! assert_eq!(expr.evaluate(&mut context).unwrap().to_string(), "true");
//! 
//! // String operations
//! let expr = aimx_parse("\"hello\".upper() + \" \" + \"WORLD\".lower()");
//! assert_eq!(expr.evaluate(&mut context).unwrap().to_string(), "HELLO world");
//! 
//! // Array operations
//! let expr = aimx_parse("(1, 5, 3).max()");
//! assert_eq!(expr.evaluate(&mut context).unwrap().to_string(), "5");
//! 
//! // Function composition
//! let expr = aimx_parse("sqrt(pow(2, 2) + max((1, 3))).round_to(5)");
//! assert_eq!(expr.evaluate(&mut context).unwrap().to_string(), "2.64575");
//!
//! // Or simpler:
//! let expr = aimx_parse("sqrt(16)");
//! assert_eq!(expr.evaluate(&mut context).unwrap().to_string(), "4");
//! ```
//!
//! # Architecture
//!
//! The crate is organized into several modules that handle different aspects of parsing and evaluation:
//!
//! ## Core Modules
//!
//! - [`parser`] - Main parsing interface [`aimx_parse`] 
//! - [`expression`] - Top-level [`Expression`] AST and parsing
//! - [`evaluate`] - Core evaluation traits [`ExpressionLike`], [`ContextLike`]
//! - [`value`] - Runtime [`Value`] representation
//! - [`context`] - Default [`Context`] implementation
//! - [`literal`] - [`Literal`] value parsing and representation
//!
//! ## Workflow Management
//!
//! - [`workflow`] - [`Workflow`] struct and [`WorkflowLike`] trait
//! - [`workspace`] - Global workspace management
//! - [`rule`] - Workflow [`Rule`] definitions
//! - [`aim`] - Agentic Inference Markup file format handling
//!
//! ## Function System
//!
//! - [`function_registry`] - Function registration and calling
//! - [`functions`] - Built-in function libraries
//! - Mathematical, text, date, business, statistical, and collection functions - Comprehensive standard library
//!
//! ## Expression Grammar
//!
//! - [`expressions`] - Operator-specific expression parsing
//! - [`expressions::primary`], [`expressions::closure`], [`expressions::conditional`], etc.
//! - [`literals`] - Literal value parsing modules
//! - [`values`] - Special value types and utilities
//!
//! ## Inference Integration
//!
//! - [`inference`] - AI provider integration and inference handling
//! - [`inference::provider`], [`inference::prompt`], [`inference::request`], etc.
//!
//! # Concurrency Model
//!
//! AIMX uses a sophisticated multi-version concurrency control (MVCC) model:
//!
//! - **Non-blocking Reads**: Unlimited concurrent readers access consistent snapshots
//! - **Atomic Writes**: Writers operate on isolated copies before publishing changes
//! - **Fine-grained Locking**: Per-workflow locking instead of global workspace locking
//! - **Lazy Loading**: Workflows are loaded on-demand when first accessed
//!
//! This architecture ensures high performance for agentic workflows where many tasks
//! may need to evaluate expressions simultaneously without blocking.
//!
//! # Error Handling
//!
//! The parser and evaluator provide comprehensive error handling:
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context};
//!
//! let mut context = Context::new();
//! 
//! // Parsing errors are captured in the Expression result
//! let expr = aimx_parse("2 + * 3"); // Invalid syntax
//! if expr.has_error() {
//!     println!("Parsing failed: {}", expr);
//! }
//! 
//! // Evaluation errors are returned as Result types
//! let expr = aimx_parse("10 / 0");
//! match expr.evaluate(&mut context) {
//!     Ok(value) => println!("Result: {}", value),
//!     Err(e) => println!("Evaluation error: {}", e),
//! }
//! ```
//!
//! # Performance Considerations
//!
//! - **Static Evaluation**: Use [`statically_evaluate`] for expressions without external dependencies
//! - **Function Registry**: The singleton function registry is thread-safe and efficient
//! - **AST Optimization**: Expressions are flattened for optimal evaluation performance
//! - **Lazy Resolution**: Variable references and function calls are resolved on-demand
//!
//! # Getting Started
//!
//! Add AIMX to your `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! aimx = "0.9.1"
//! ```
//!
//! Then start parsing and evaluating expressions:
//!
//! ```rust
//! use aimx::{aimx_parse, ExpressionLike, Context, Literal, Value};
//!
//! fn main() -> anyhow::Result<()> {
//!     let expression = aimx_parse("(temperature - 32) * 5/9");
//!     let mut context = Context::new()
//!         .with_value("temperature", Value::Literal(Literal::Number(68.0)));
//!     
//!     let result = expression.evaluate(&mut context)?;
//!     println!("Celsius: {}", result);
//!     
//!     Ok(())
//! }
//! ```

// Core parsing and evaluation modules
pub mod context;
pub mod evaluate;
pub mod expression;
pub mod function_registry;
pub mod literal;
pub mod macros;
pub mod parser;
pub mod rule;
pub mod typedef;
pub mod value;
pub mod workflow;
pub mod workspace;
pub mod writer;

// Agentic Inference Markup (AIM) modules
pub mod aim;
// Expression modules
pub mod expressions;
// Function registry and built-in functions
pub mod functions;
// Inference modules
pub mod inference;
// Literal modules
pub mod literals;
// Special value modules
pub mod values;

// Re-export key types for easier access
pub use aim::{AppName, get_config, get_config_mut, get_lock_manager};
pub use context::{ContextLike, Context};
pub use evaluate::{ExpressionLike, evaluate_and_promote, statically_evaluate};
pub use expression::{Expression, parse_argument_list, parse_expression};
pub use expressions::{Primary, Reference};
pub use function_registry::FunctionRegistry;
pub use inference::{Api, Model, Capability, Provider, generate_prompt, send_request, parse_response, validate_responses};
pub use literal::{Literal, parse_bool, parse_literal, parse_task};
pub use parser::aimx_parse;
pub use rule::{Rule, parse_rule};
pub use typedef::{Typedef, parse_literal_type, parse_typedef};
pub use value::{Value, parse_value};
pub use values::Node;
pub use workflow::{WorkflowLike, Workflow};
pub use workspace::{get_workspace, load_workspace, create_path, add_node_rule, rename_node_rule, delete_node_rule};
pub use writer::{Prefix, PrintMode, Writer};