From 0dd6dc03471b41c16a5e18837c7ea0dc03d425f6 Mon Sep 17 00:00:00 2001
From: m24130 <m24130@local.host>
Date: Thu, 4 Dec 2025 07:56:07 +0100
Subject: [PATCH 1/6] feat: add compile() function and Program class for
 pre-compilation

Add ability to compile CEL expressions once and execute them multiple times
with different contexts. This provides ~12x speedup over evaluate() when
reusing the same expression.

New API:
- compile(expression) -> Program
- Program.execute(context) -> result

Example:
    program = compile('x + y')
    program.execute({'x': 1, 'y': 2})  # 3
    program.execute({'x': 10, 'y': 20})  # 30
---
 src/lib.rs | 208 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 208 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index a5c92b2..e1adc53 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -16,6 +16,88 @@ use std::error::Error;
 use std::fmt;
 use std::sync::Arc;
 
+/// A compiled CEL program that can be executed multiple times with different contexts.
+///
+/// This is useful when you need to evaluate the same expression many times with different
+/// variable bindings. Compiling once and executing multiple times is significantly faster
+/// than calling `evaluate()` repeatedly.
+///
+/// # Example
+///
+/// ```python
+/// from cel import compile
+///
+/// # Compile once
+/// program = compile("price * quantity > 100")
+///
+/// # Execute many times with different contexts
+/// result1 = program.execute({"price": 10, "quantity": 20})  # True
+/// result2 = program.execute({"price": 5, "quantity": 10})   # False
+/// ```
+#[pyclass(name = "Program")]
+struct PyProgram {
+    program: Program,
+    source: String,
+}
+
+#[pymethods]
+impl PyProgram {
+    /// Execute the compiled program with the given context.
+    ///
+    /// Args:
+    ///     context: Optional evaluation context (dict or Context object)
+    ///
+    /// Returns:
+    ///     The result of the expression evaluation
+    #[pyo3(signature = (context=None))]
+    fn execute(&self, context: Option<&Bound<'_, PyAny>>) -> PyResult<Py<PyAny>> {
+        execute_compiled_program(&self.program, &self.source, context)
+    }
+
+    fn __repr__(&self) -> String {
+        format!("Program({:?})", self.source)
+    }
+}
+
+/// Compile a CEL expression into a reusable Program object.
+///
+/// This function parses and compiles a CEL expression, returning a Program object
+/// that can be executed multiple times with different contexts. This is more efficient
+/// than calling `evaluate()` repeatedly with the same expression.
+///
+/// Args:
+///     expression: The CEL expression to compile
+///
+/// Returns:
+///     A compiled Program object
+///
+/// Raises:
+///     ValueError: If the expression has syntax errors or is malformed
+///
+/// Example:
+///     >>> from cel import compile
+///     >>> program = compile("x + y")
+///     >>> program.execute({"x": 1, "y": 2})
+///     3
+///     >>> program.execute({"x": 10, "y": 20})
+///     30
+#[pyfunction]
+fn compile(expression: String) -> PyResult<PyProgram> {
+    let program = panic::catch_unwind(|| Program::compile(&expression))
+        .map_err(|_| {
+            warn!("CEL parser panic for expression: '{}'", expression);
+            PyValueError::new_err(format!(
+                "Failed to parse expression '{expression}': Invalid syntax or malformed string"
+            ))
+        })?
+        .map_err(|e| PyValueError::new_err(format!("Failed to parse expression '{expression}': {e}")))?;
+
+    Ok(PyProgram {
+        program,
+        source: expression,
+    })
+}
+
 #[derive(Debug)]
 struct RustyCelType(Value);
 
@@ -516,11 +598,137 @@ fn evaluate(src: String, evaluation_context: Option<&Bound<'_, PyAny>>) -> PyRes
     }
 }
 
+/// Internal helper to execute a pre-compiled program with the given context.
+/// Used by both `evaluate()` (after compiling) and `PyProgram.execute()`.
+fn execute_compiled_program(
+    program: &Program,
+    src: &str,
+    evaluation_context: Option<&Bound<'_, PyAny>>,
+) -> PyResult<Py<PyAny>> {
+    let mut environment = CelContext::default();
+    let mut ctx = context::Context::new(None, None)?;
+    let mut variables_for_env = HashMap::new();
+
+    // Process the evaluation context if provided
+    if let Some(evaluation_context) = evaluation_context {
+        // Attempt to extract directly as a Context object
+        if let Ok(py_context_ref) = evaluation_context.extract::<PyRef<context::Context>>() {
+            // Clone variables and functions into our local Context
+            ctx.variables = py_context_ref.variables.clone();
+            ctx.functions = py_context_ref.functions.clone();
+        } else if let Ok(py_dict) = evaluation_context.cast::<PyDict>() {
+            // User passed in a dict - let's process variables and functions from the dict
+            ctx.update(py_dict)?;
+        } else {
+            return Err(PyValueError::new_err(
+                "evaluation_context must be a Context object or a dict",
+            ));
+        };
+
+        variables_for_env = ctx.variables.clone();
+    }
+
+    // Add variables and functions if we have a context
+    if evaluation_context.is_some() {
+        // Add any variables from the processed context
+        for (name, value) in &variables_for_env {
+            environment
+                .add_variable(name.clone(), value.clone())
+                .map_err(|e| {
+                    PyValueError::new_err(format!("Failed to add variable '{name}': {e}"))
+                })?;
+        }
+
+        // Register Python functions
+        for (function_name, py_function) in ctx.functions.iter() {
+            // Create a wrapper function
+            let py_func_clone = Python::attach(|py| py_function.clone_ref(py));
+            let func_name_clone = function_name.clone();
+
+            // Register a function that takes Arguments (variadic) and returns a Value
+            environment.add_function(
+                function_name,
+                move |args: ::cel::extractors::Arguments| -> Result<Value, ExecutionError> {
+                    let py_func = py_func_clone.clone();
+                    let func_name = func_name_clone.clone();
+
+                    Python::attach(|py| {
+                        // Convert CEL arguments to Python objects
+                        let mut py_args = Vec::new();
+                        for cel_value in args.0.iter() {
+                            let py_arg = RustyCelType(cel_value.clone())
+                                .into_pyobject(py)
+                                .map_err(|e| ExecutionError::FunctionError {
+                                    function: func_name.clone(),
+                                    message: format!("Failed to convert argument to Python: {e}"),
+                                })?
+                                .into_any()
+                                .unbind();
+                            py_args.push(py_arg);
+                        }
+
+                        let py_args_tuple = PyTuple::new(py, py_args).map_err(|e| {
+                            ExecutionError::FunctionError {
+                                function: func_name.clone(),
+                                message: format!("Failed to create arguments tuple: {e}"),
+                            }
+                        })?;
+
+                        // Call the Python function
+                        let py_result = py_func.call1(py, py_args_tuple).map_err(|e| {
+                            warn!("Python function '{}' failed: {}", func_name, e);
+                            ExecutionError::FunctionError {
+                                function: func_name.clone(),
+                                message: format!("Python function call failed: {e}"),
+                            }
+                        })?;
+
+                        // Convert the result back to CEL Value
+                        let py_result_ref = py_result.bind(py);
+                        let cel_value =
+                            RustyPyType(py_result_ref).try_into_value().map_err(|e| {
+                                ExecutionError::FunctionError {
+                                    function: func_name.clone(),
+                                    message: format!(
+                                        "Failed to convert Python result to CEL value: {e}"
+                                    ),
+                                }
+                            })?;
+
+                        Ok(cel_value)
+                    })
+                },
+            );
+        }
+    }
+
+    // Use panic::catch_unwind to handle execution panics gracefully
+    // AssertUnwindSafe is needed because the environment contains function closures
+    let result =
+        panic::catch_unwind(AssertUnwindSafe(|| program.execute(&environment))).map_err(|_| {
+            warn!("CEL execution panic for expression: '{}'", src);
+            PyValueError::new_err(format!(
+                "Failed to execute expression '{src}': Internal parser error"
+            ))
+        })?;
+
+    match result {
+        Err(error) => Err(map_execution_error_to_python(&error)),
+        Ok(value) => Python::attach(|py| {
+            RustyCelType(value)
+                .into_pyobject(py)
+                .map(|obj| obj.unbind())
+        }),
+    }
+}
+
 #[pymodule]
 fn cel(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     pyo3_log::init();
 
     m.add_function(wrap_pyfunction!(evaluate, m)?)?;
+    m.add_function(wrap_pyfunction!(compile, m)?)?;
     m.add_class::<context::Context>()?;
+    m.add_class::<PyProgram>()?;
     Ok(())
 }

From 2b11caa4764af222895619458182d37aa29bbed5 Mon Sep 17 00:00:00 2001
From: m24130 <m24130@local.host>
Date: Fri, 5 Dec 2025 08:19:12 +0100
Subject: [PATCH 2/6] docs: add pre-compilation examples to documentation

Add examples demonstrating compile() and Program.execute() usage to README, quick-start guide, and Python API reference. Show performance pattern of compiling once and executing multiple times with different contexts.
---
 README.md                           |  15 ++
 docs/getting-started/quick-start.md |  19 ++
 docs/reference/python-api.md        | 119 ++++++++++-
 tests/test_compile.py               | 309 ++++++++++++++++++++++++++++
 4 files changed, 461 insertions(+), 1 deletion(-)
 create mode 100644 tests/test_compile.py

diff --git a/README.md b/README.md
index 5b71f9e..7166c1c 100644
--- a/README.md
+++ b/README.md
@@ -67,6 +67,21 @@ cel 'age >= 18' --context '{"age": 25}'  # true
 cel --interactive
 ```
 
+### Pre-compilation for Performance
+
+When evaluating the same expression multiple times with different contexts, use `compile()` for better performance:
+
+```python
+from cel import compile
+
+# Compile once
+program = compile("price * quantity > threshold")
+
+# Execute many times - much faster than repeated evaluate() calls
+result1 = program.execute({"price": 10, "quantity": 5, "threshold": 40})  # True
+result2 = program.execute({"price": 5, "quantity": 3, "threshold": 20})   # False
+```
+
 ### Custom Functions
 
 ```python
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index f36c304..ce531f0 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -90,6 +90,25 @@ assert result == "No phone"  # → "No phone" (safe field checking prevents erro
 print("✓ Context variables working correctly")
 ```
 
+## Pre-compilation for Performance
+
+Use `compile()` when evaluating the same expression many times with different contexts:
+
+```python
+from cel import compile
+
+# Compile once, execute many times
+program = compile("price * quantity > threshold")
+
+result1 = program.execute({"price": 10, "quantity": 5, "threshold": 40})
+assert result1 == True  # → True (50 > 40)
+
+result2 = program.execute({"price": 5, "quantity": 3, "threshold": 20})
+assert result2 == False  # → False (15 > 20)
+
+print("Pre-compilation working correctly")
+```
+
 ## Ready for More?
 
 You've mastered the basics of CEL evaluation with dictionary context! For advanced features like custom Python functions, context objects, and production patterns, continue to the next guide.
diff --git a/docs/reference/python-api.md b/docs/reference/python-api.md
index 39a680d..674c0d1 100644
--- a/docs/reference/python-api.md
+++ b/docs/reference/python-api.md
@@ -6,8 +6,125 @@ Complete autogenerated reference for the Python CEL library.
 
 ::: cel.evaluate
 
+### compile(expression: str) -> Program
 
-## Classes  
+Compile a CEL expression into a reusable Program object.
+
+This function parses and compiles a CEL expression, returning a Program object that can be executed multiple times with different contexts. This is more efficient than calling `evaluate()` repeatedly with the same expression.
+
+**Parameters:**
+- `expression`: The CEL expression to compile
+
+**Returns:**
+- A compiled `Program` object
+
+**Raises:**
+- `ValueError`: If the expression has syntax errors or is malformed
+
+**Example:**
+```python
+from cel import compile
+
+# Compile once
+program = compile("x + y")
+
+# Execute many times with different contexts
+result1 = program.execute({"x": 1, "y": 2})
+assert result1 == 3  # → 3
+
+result2 = program.execute({"x": 10, "y": 20})
+assert result2 == 30  # → 30
+```
+
+**When to use `compile()` vs `evaluate()`:**
+
+- Use `evaluate()` for one-time evaluation or interactive/REPL usage
+- Use `compile()` + `execute()` when evaluating the same expression with many different contexts or in performance-critical loops
+
+## Classes
+
+### Program
+
+**A compiled CEL program that can be executed multiple times with different contexts.**
+
+The Program class represents a pre-compiled CEL expression. Use this when you need to evaluate the same expression many times with different variable bindings. Compiling once and executing multiple times is significantly faster than calling `evaluate()` repeatedly.
+
+```python
+from cel import compile
+
+# Compile the expression once
+program = compile("price * quantity > 100")
+
+# Execute many times with different contexts
+result1 = program.execute({"price": 10, "quantity": 20})
+assert result1 == True  # → True (200 > 100)
+
+result2 = program.execute({"price": 5, "quantity": 10})
+assert result2 == False  # → False (50 > 100)
+```
+
+#### Methods
+
+##### execute(context=None) -> Any
+
+Execute the compiled program with the given context.
+
+**Parameters:**
+- `context`: Optional evaluation context (dict or Context object)
+
+**Returns:**
+- The result of the expression evaluation
+
+**Raises:**
+- `RuntimeError`: If a variable or function is undefined
+- `TypeError`: If there's a type mismatch during execution
+- `ValueError`: If the context is an invalid type
+
+**Example with dict context:**
+```python
+from cel import compile
+
+program = compile("user.name + ' is ' + user.role")
+result = program.execute({
+    "user": {"name": "Alice", "role": "admin"}
+})
+assert result == "Alice is admin"
+```
+
+**Example with Context object:**
+```python
+from cel import compile, Context
+
+program = compile("greet(name)")
+
+ctx = Context()
+ctx.add_variable("name", "World")
+ctx.add_function("greet", lambda x: f"Hello, {x}!")
+
+result = program.execute(ctx)
+assert result == "Hello, World!"
+```
+
+**Performance pattern - compile once, execute many:**
+```python
+from cel import compile
+
+# Access control policy - compiled once at startup
+policy = compile(
+    'user.role == "admin" || resource.owner == user.id'
+)
+
+# Evaluated many times per request
+def check_access(user, resource):
+    return policy.execute({"user": user, "resource": resource})
+
+# Fast repeated evaluation
+assert check_access({"id": "alice", "role": "admin"}, {"owner": "bob"}) == True
+assert check_access({"id": "bob", "role": "user"}, {"owner": "bob"}) == True
+assert check_access({"id": "charlie", "role": "user"}, {"owner": "bob"}) == False
+```
+
+---  
 
 ### Context
 
diff --git a/tests/test_compile.py b/tests/test_compile.py
new file mode 100644
index 0000000..6d5c8c2
--- /dev/null
+++ b/tests/test_compile.py
@@ -0,0 +1,309 @@
+"""Tests for the compile() function and Program class.
+
+The compile() function pre-compiles a CEL expression into a Program object
+that can be executed multiple times with different contexts, providing
+significant performance benefits for repeated evaluation of the same expression.
+"""
+
+import datetime
+
+import cel
+from cel import Context
+import pytest
+
+
+class TestCompileBasics:
+    """Basic compilation and execution tests."""
+
+    def test_compile_simple_expression(self):
+        """Test compiling a simple arithmetic expression."""
+        program = cel.compile("1 + 2")
+        result = program.execute()
+        assert result == 3
+
+    def test_compile_returns_program(self):
+        """Test that compile() returns a Program object."""
+        program = cel.compile("true")
+        assert hasattr(program, "execute")
+
+    def test_program_repr(self):
+        """Test Program __repr__ method."""
+        program = cel.compile("x + y")
+        repr_str = repr(program)
+        assert "Program" in repr_str
+        assert "x + y" in repr_str
+
+    def test_execute_without_context(self):
+        """Test executing a program without context."""
+        program = cel.compile("42")
+        assert program.execute() == 42
+
+    def test_execute_with_none_context(self):
+        """Test executing with explicit None context."""
+        program = cel.compile("true && false")
+        assert program.execute(None) is False
+
+
+class TestCompileWithContext:
+    """Tests for compile/execute with various context types."""
+
+    def test_execute_with_dict_context(self):
+        """Test executing with a dictionary context."""
+        program = cel.compile("x + y")
+        result = program.execute({"x": 10, "y": 20})
+        assert result == 30
+
+    def test_execute_with_context_object(self):
+        """Test executing with a Context object."""
+        program = cel.compile("name + ' is ' + string(age)")
+        ctx = Context()
+        ctx.add_variable("name", "Alice")
+        ctx.add_variable("age", 30)
+        result = program.execute(ctx)
+        assert result == "Alice is 30"
+
+    def test_execute_same_program_different_contexts(self):
+        """Test executing the same program with different contexts."""
+        program = cel.compile("price * quantity")
+        
+        result1 = program.execute({"price": 10, "quantity": 5})
+        assert result1 == 50
+        
+        result2 = program.execute({"price": 25, "quantity": 4})
+        assert result2 == 100
+        
+        result3 = program.execute({"price": 100, "quantity": 1})
+        assert result3 == 100
+
+    def test_execute_with_nested_context(self):
+        """Test executing with nested dictionary context."""
+        program = cel.compile("user.name + ' (' + user.role + ')'")
+        result = program.execute({
+            "user": {"name": "Bob", "role": "admin"}
+        })
+        assert result == "Bob (admin)"
+
+    def test_execute_with_list_context(self):
+        """Test executing with list in context."""
+        program = cel.compile("items[0] + items[1]")
+        result = program.execute({"items": [10, 20, 30]})
+        assert result == 30
+
+
+class TestCompileWithFunctions:
+    """Tests for compile/execute with custom functions."""
+
+    def test_execute_with_custom_function(self):
+        """Test executing with a custom Python function."""
+        program = cel.compile("double(x)")
+        ctx = Context()
+        ctx.add_function("double", lambda x: x * 2)
+        ctx.add_variable("x", 21)
+        result = program.execute(ctx)
+        assert result == 42
+
+    def test_execute_with_multiple_custom_functions(self):
+        """Test executing with multiple custom functions."""
+        program = cel.compile("add(x, y) + multiply(x, y)")
+        ctx = Context()
+        ctx.add_function("add", lambda a, b: a + b)
+        ctx.add_function("multiply", lambda a, b: a * b)
+        ctx.add_variable("x", 3)
+        ctx.add_variable("y", 4)
+        result = program.execute(ctx)
+        assert result == 19  # (3+4) + (3*4) = 7 + 12 = 19
+
+
+class TestCompileTypes:
+    """Tests for various CEL types with compile/execute."""
+
+    def test_compile_boolean(self):
+        """Test compiling boolean expressions."""
+        program = cel.compile("a > b && c")
+        result = program.execute({"a": 10, "b": 5, "c": True})
+        assert result is True
+
+    def test_compile_string(self):
+        """Test compiling string expressions."""
+        program = cel.compile("greeting + ' ' + name")
+        result = program.execute({"greeting": "Hello", "name": "World"})
+        assert result == "Hello World"
+
+    def test_compile_list(self):
+        """Test compiling list expressions."""
+        program = cel.compile("[a, b, c]")
+        result = program.execute({"a": 1, "b": 2, "c": 3})
+        assert result == [1, 2, 3]
+
+    def test_compile_map(self):
+        """Test compiling map expressions."""
+        program = cel.compile("{'name': name, 'age': age}")
+        result = program.execute({"name": "Alice", "age": 30})
+        assert result == {"name": "Alice", "age": 30}
+
+    def test_compile_null(self):
+        """Test compiling null expressions."""
+        program = cel.compile("null")
+        result = program.execute()
+        assert result is None
+
+    def test_compile_bytes(self):
+        """Test compiling bytes expressions."""
+        program = cel.compile("b'hello'")
+        result = program.execute()
+        assert result == b"hello"
+
+    def test_compile_timestamp(self):
+        """Test compiling timestamp expressions."""
+        program = cel.compile("timestamp('2024-01-01T00:00:00Z')")
+        result = program.execute()
+        assert isinstance(result, datetime.datetime)
+        assert result.year == 2024
+
+    def test_compile_duration(self):
+        """Test compiling duration expressions."""
+        program = cel.compile("duration('1h30m')")
+        result = program.execute()
+        assert isinstance(result, datetime.timedelta)
+        assert result.total_seconds() == 5400
+
+
+class TestCompileErrors:
+    """Tests for error handling in compile/execute."""
+
+    def test_compile_invalid_syntax(self):
+        """Test that invalid syntax raises ValueError."""
+        with pytest.raises(ValueError, match="Failed to parse"):
+            cel.compile("1 + + 2")
+
+    def test_compile_empty_expression(self):
+        """Test that empty expression raises ValueError."""
+        with pytest.raises(ValueError, match="Failed to parse"):
+            cel.compile("")
+
+    def test_execute_undefined_variable(self):
+        """Test that undefined variable raises RuntimeError."""
+        program = cel.compile("undefined_var + 1")
+        with pytest.raises(RuntimeError):
+            program.execute({})
+
+    def test_execute_type_error(self):
+        """Test that type errors are properly raised."""
+        program = cel.compile("x + y")
+        with pytest.raises(TypeError):
+            # String + int should fail
+            program.execute({"x": "hello", "y": 42})
+
+    def test_execute_invalid_context_type(self):
+        """Test that invalid context type raises ValueError."""
+        program = cel.compile("x + 1")
+        with pytest.raises(ValueError, match="must be a Context object or a dict"):
+            program.execute("invalid context")
+
+
+class TestCompileRealWorldExamples:
+    """Real-world usage examples for compile/execute."""
+
+    def test_access_control_policy(self):
+        """Test access control policy evaluation."""
+        policy = cel.compile(
+            'user.role == "admin" || (resource.owner == user.id && action == "read")'
+        )
+        
+        # Admin can do anything
+        assert policy.execute({
+            "user": {"id": "alice", "role": "admin"},
+            "resource": {"owner": "bob"},
+            "action": "delete"
+        }) is True
+        
+        # Owner can read their own resource
+        assert policy.execute({
+            "user": {"id": "bob", "role": "user"},
+            "resource": {"owner": "bob"},
+            "action": "read"
+        }) is True
+        
+        # Non-owner cannot read others' resources
+        assert policy.execute({
+            "user": {"id": "charlie", "role": "user"},
+            "resource": {"owner": "bob"},
+            "action": "read"
+        }) is False
+
+    def test_pricing_calculation(self):
+        """Test pricing calculation with discounts."""
+        pricing = cel.compile(
+            "price * quantity * (1.0 - discount)"
+        )
+        
+        # No discount
+        assert pricing.execute({
+            "price": 100.0, "quantity": 2.0, "discount": 0.0
+        }) == 200.0
+        
+        # 10% discount
+        result = pricing.execute({
+            "price": 100.0, "quantity": 2.0, "discount": 0.1
+        })
+        assert abs(result - 180.0) < 0.001
+
+    def test_validation_rules(self):
+        """Test validation rules."""
+        age_check = cel.compile("age >= 18 && age <= 120")
+        
+        assert age_check.execute({"age": 25}) is True
+        assert age_check.execute({"age": 17}) is False
+        assert age_check.execute({"age": 121}) is False
+
+    def test_data_filtering(self):
+        """Test data filtering expression."""
+        filter_expr = cel.compile(
+            'status == "active" && score >= min_score'
+        )
+        
+        items = [
+            {"status": "active", "score": 85},
+            {"status": "inactive", "score": 90},
+            {"status": "active", "score": 70},
+            {"status": "active", "score": 95},
+        ]
+        
+        filtered = [
+            item for item in items
+            if filter_expr.execute({**item, "min_score": 80})
+        ]
+        
+        assert len(filtered) == 2
+        assert filtered[0]["score"] == 85
+        assert filtered[1]["score"] == 95
+
+
+class TestCompilePerformancePattern:
+    """Tests demonstrating the performance benefit pattern."""
+
+    def test_compile_once_execute_many(self):
+        """Demonstrate compile-once-execute-many pattern."""
+        # Compile the expression once
+        expr = cel.compile("x * x + y * y")
+        
+        # Execute many times with different values
+        results = []
+        for i in range(100):
+            result = expr.execute({"x": i, "y": i + 1})
+            results.append(result)
+        
+        # Verify some results
+        assert results[0] == 0 * 0 + 1 * 1  # 1
+        assert results[1] == 1 * 1 + 2 * 2  # 5
+        assert results[10] == 10 * 10 + 11 * 11  # 221
+
+    def test_reuse_compiled_program(self):
+        """Test that compiled programs can be reused safely."""
+        program = cel.compile("value > threshold")
+        
+        # Multiple sequential executions
+        assert program.execute({"value": 10, "threshold": 5}) is True
+        assert program.execute({"value": 3, "threshold": 5}) is False
+        assert program.execute({"value": 100, "threshold": 50}) is True
+        assert program.execute({"value": 0, "threshold": 0}) is False

From dadb50a490d4b5b8c93b5cb775f629f0278ba70e Mon Sep 17 00:00:00 2001
From: Brian Thorne <brian@thorne.link>
Date: Sat, 7 Feb 2026 19:57:09 +1300
Subject: [PATCH 3/6] Upgrade cel crate to 0.12.0 and add optional wrapper

---
 Cargo.lock                          |  17 +-
 Cargo.toml                          |   2 +-
 README.md                           |   6 +-
 docs/getting-started/quick-start.md |   6 +-
 docs/reference/python-api.md        |  93 ++++++-
 python/cel/cel.pyi                  |  25 ++
 src/lib.rs                          | 402 ++++++++++++++--------------
 tests/test_functions.py             |   8 +-
 tests/test_optional_values.py       |  39 +++
 tests/test_upstream_improvements.py |  20 +-
 10 files changed, 383 insertions(+), 235 deletions(-)
 create mode 100644 tests/test_optional_values.py

diff --git a/Cargo.lock b/Cargo.lock
index 2daa189..5eda493 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -22,9 +22,9 @@ dependencies = [
 
 [[package]]
 name = "antlr4rust"
-version = "0.5.1"
+version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "855de4069e655d114ee7a7e003b8c96f623671532da2f8bb46d25dfd6a16abd9"
+checksum = "093d520274bfff7278d776f7ea12981a0a0a6f96db90964658e0f38fc6e9a6a6"
 dependencies = [
  "better_any",
  "bit-set",
@@ -94,6 +94,12 @@ version = "1.5.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
 
+[[package]]
+name = "bytes"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33"
+
 [[package]]
 name = "cc"
 version = "1.2.41"
@@ -108,7 +114,7 @@ dependencies = [
 name = "cel"
 version = "0.5.4"
 dependencies = [
- "cel 0.11.6",
+ "cel 0.12.0",
  "chrono",
  "log",
  "pyo3",
@@ -117,12 +123,13 @@ dependencies = [
 
 [[package]]
 name = "cel"
-version = "0.11.6"
+version = "0.12.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8edeb3d082fb4f559d994ed50338e924b0b0bc74f855d7fcf49c980cb4c2d95f"
+checksum = "ca1e5eda1b0f8476181bed1bfc9232a91d62ff0b9f1bc0e48afff3cbcb5b0b5c"
 dependencies = [
  "antlr4rust",
  "base64",
+ "bytes",
  "chrono",
  "lazy_static",
  "nom",
diff --git a/Cargo.toml b/Cargo.toml
index 30e57cf..0bc827e 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -10,7 +10,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 pyo3 = { version = "0.27", features = ["chrono", "py-clone"]}
-cel = { version = "0.11.6", features = ["chrono", "json", "regex"] }
+cel = { version = "0.12.0", features = ["chrono", "json", "regex", "bytes"] }
 log = "0.4.27"
 pyo3-log = { git = "https://github.com/a1phyr/pyo3-log.git", branch = "pyo3_0.27" }
 chrono = { version = "0.4.42", features = ["serde"] }
diff --git a/README.md b/README.md
index 7166c1c..c2837f4 100644
--- a/README.md
+++ b/README.md
@@ -72,10 +72,10 @@ cel --interactive
 When evaluating the same expression multiple times with different contexts, use `compile()` for better performance:
 
 ```python
-from cel import compile
+import cel
 
 # Compile once
-program = compile("price * quantity > threshold")
+program = cel.compile("price * quantity > threshold")
 
 # Execute many times - much faster than repeated evaluate() calls
 result1 = program.execute({"price": 10, "quantity": 5, "threshold": 40})  # True
@@ -192,4 +192,4 @@ This project is licensed under the same terms as the original cel-interpreter cr
 - [📖 **Documentation**](https://python-common-expression-language.readthedocs.io/)
 - [🌐 **CEL Homepage**](https://cel.dev/)
 - [📋 **CEL Specification**](https://github.com/google/cel-spec)
-- [⚙️ **cel-interpreter Rust crate**](https://crates.io/crates/cel-interpreter)
\ No newline at end of file
+- [⚙️ **cel-interpreter Rust crate**](https://crates.io/crates/cel-interpreter)
diff --git a/docs/getting-started/quick-start.md b/docs/getting-started/quick-start.md
index ce531f0..6ff84e2 100644
--- a/docs/getting-started/quick-start.md
+++ b/docs/getting-started/quick-start.md
@@ -95,10 +95,10 @@ print("✓ Context variables working correctly")
 Use `compile()` when evaluating the same expression many times with different contexts:
 
 ```python
-from cel import compile
+import cel
 
 # Compile once, execute many times
-program = compile("price * quantity > threshold")
+program = cel.compile("price * quantity > threshold")
 
 result1 = program.execute({"price": 10, "quantity": 5, "threshold": 40})
 assert result1 == True  # → True (50 > 40)
@@ -450,4 +450,4 @@ Congratulations! You've mastered basic CEL evaluation with dictionary context. N
 
 **Quick Start → [Your First Integration](../tutorials/your-first-integration.md) → [Access Control Policies](../how-to-guides/access-control-policies.md)**
 
-This path takes you from basics to production-ready applications in the most efficient way.
\ No newline at end of file
+This path takes you from basics to production-ready applications in the most efficient way.
diff --git a/docs/reference/python-api.md b/docs/reference/python-api.md
index 674c0d1..aa03439 100644
--- a/docs/reference/python-api.md
+++ b/docs/reference/python-api.md
@@ -23,10 +23,10 @@ This function parses and compiles a CEL expression, returning a Program object t
 
 **Example:**
 ```python
-from cel import compile
+import cel
 
 # Compile once
-program = compile("x + y")
+program = cel.compile("x + y")
 
 # Execute many times with different contexts
 result1 = program.execute({"x": 1, "y": 2})
@@ -50,10 +50,10 @@ assert result2 == 30  # → 30
 The Program class represents a pre-compiled CEL expression. Use this when you need to evaluate the same expression many times with different variable bindings. Compiling once and executing multiple times is significantly faster than calling `evaluate()` repeatedly.
 
 ```python
-from cel import compile
+import cel
 
 # Compile the expression once
-program = compile("price * quantity > 100")
+program = cel.compile("price * quantity > 100")
 
 # Execute many times with different contexts
 result1 = program.execute({"price": 10, "quantity": 20})
@@ -82,9 +82,9 @@ Execute the compiled program with the given context.
 
 **Example with dict context:**
 ```python
-from cel import compile
+import cel
 
-program = compile("user.name + ' is ' + user.role")
+program = cel.compile("user.name + ' is ' + user.role")
 result = program.execute({
     "user": {"name": "Alice", "role": "admin"}
 })
@@ -93,9 +93,10 @@ assert result == "Alice is admin"
 
 **Example with Context object:**
 ```python
-from cel import compile, Context
+import cel
+from cel import Context
 
-program = compile("greet(name)")
+program = cel.compile("greet(name)")
 
 ctx = Context()
 ctx.add_variable("name", "World")
@@ -107,10 +108,10 @@ assert result == "Hello, World!"
 
 **Performance pattern - compile once, execute many:**
 ```python
-from cel import compile
+import cel
 
 # Access control policy - compiled once at startup
-policy = compile(
+policy = cel.compile(
     'user.role == "admin" || resource.owner == user.id'
 )
 
@@ -124,6 +125,76 @@ assert check_access({"id": "bob", "role": "user"}, {"owner": "bob"}) == True
 assert check_access({"id": "charlie", "role": "user"}, {"owner": "bob"}) == False
 ```
 
+### OptionalValue
+
+**Wrapper for CEL optional values.**
+
+CEL optional values preserve the distinction between "no value" and "a value that is null".
+The Python wrapper keeps that distinction intact.
+
+```python
+import cel
+
+opt = cel.evaluate("optional.of(42)")
+assert isinstance(opt, cel.OptionalValue)
+assert opt.has_value() is True
+assert opt.value() == 42
+assert opt.or_value(0) == 42
+
+none_opt = cel.evaluate("optional.none()")
+assert none_opt.has_value() is False
+assert none_opt.or_value("default") == "default"
+```
+
+**Distinguishing `optional.none()` from `optional.of(null)`:**
+```python
+import cel
+
+opt_null = cel.evaluate("optional.of(null)")
+assert opt_null.has_value() is True
+assert opt_null.value() is None
+
+opt_none = cel.evaluate("optional.none()")
+assert opt_none.has_value() is False
+```
+
+**Passing OptionalValue into evaluation contexts:**
+```python
+import cel
+
+opt = cel.OptionalValue.of(123)
+assert cel.evaluate("opt.orValue(0)", {"opt": opt}) == 123
+
+opt_none = cel.OptionalValue.none()
+assert cel.evaluate("opt.orValue(7)", {"opt": opt_none}) == 7
+```
+
+#### Methods
+
+##### of(value) -> OptionalValue
+
+Create an optional value containing `value`.
+
+##### none() -> OptionalValue
+
+Create an empty optional value.
+
+##### has_value() -> bool
+
+Return `True` when the optional contains a value.
+
+##### value() -> Any
+
+Return the contained value or raise `ValueError` for `optional.none()`.
+
+##### or_value(default) -> Any
+
+Return the contained value if present, otherwise `default`.
+
+##### or_optional(other) -> OptionalValue
+
+Return `self` if it has a value, otherwise return `other`.
+
 ---  
 
 ### Context
@@ -446,4 +517,4 @@ For comprehensive error handling patterns, safety guidelines, and production bes
 - Context validation patterns
 - Defensive expression techniques
 - Logging and monitoring
-- Testing error scenarios
\ No newline at end of file
+- Testing error scenarios
diff --git a/python/cel/cel.pyi b/python/cel/cel.pyi
index c426a70..b23daf7 100644
--- a/python/cel/cel.pyi
+++ b/python/cel/cel.pyi
@@ -32,6 +32,31 @@ class Context:
         """Update context with variables from a dictionary."""
         ...
 
+class Program:
+    """Compiled CEL program that can be executed multiple times."""
+
+    def execute(self, context: Optional[Union[Dict[str, Any], Context]] = None) -> Any:
+        """Execute the compiled program with an optional context."""
+        ...
+
+def compile(expression: str) -> Program:
+    """Compile a CEL expression into a reusable Program object."""
+    ...
+
+class OptionalValue:
+    """Wrapper for CEL optional values."""
+
+    @classmethod
+    def of(cls, value: Any) -> OptionalValue: ...
+
+    @classmethod
+    def none(cls) -> OptionalValue: ...
+
+    def has_value(self) -> bool: ...
+    def value(self) -> Any: ...
+    def or_value(self, default: Any) -> Any: ...
+    def or_optional(self, other: OptionalValue) -> OptionalValue: ...
+
 def evaluate(
     expression: str,
     context: Optional[Union[Dict[str, Any], Context]] = None,
diff --git a/src/lib.rs b/src/lib.rs
index e1adc53..71da8f5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,6 +1,6 @@
 mod context;
 
-use ::cel::objects::{Key, TryIntoValue};
+use ::cel::objects::{Key, OptionalValue, TryIntoValue};
 use ::cel::{Context as CelContext, ExecutionError, Program, Value};
 use log::warn;
 use pyo3::exceptions::{PyRuntimeError, PyTypeError, PyValueError};
@@ -9,7 +9,7 @@ use pyo3::BoundObject;
 use std::panic::{self, AssertUnwindSafe};
 
 use chrono::{DateTime, Duration as ChronoDuration, Offset, TimeZone};
-use pyo3::types::{PyBool, PyBytes, PyDict, PyList, PyTuple};
+use pyo3::types::{PyBool, PyBytes, PyDict, PyList, PyTuple, PyType};
 
 use std::collections::HashMap;
 use std::error::Error;
@@ -59,6 +59,82 @@ impl PyProgram {
     }
 }
 
+/// A CEL optional value wrapper for Python.
+#[pyclass(name = "OptionalValue")]
+struct PyOptionalValue {
+    value: Option<Value>,
+}
+
+impl PyOptionalValue {
+    fn to_cel_value(&self) -> Value {
+        match &self.value {
+            Some(value) => Value::Opaque(Arc::new(OptionalValue::of(value.clone()))),
+            None => Value::Opaque(Arc::new(OptionalValue::none())),
+        }
+    }
+}
+
+#[pymethods]
+impl PyOptionalValue {
+    #[classmethod]
+    fn of(_cls: &Bound<'_, PyType>, value: &Bound<'_, PyAny>) -> PyResult<Self> {
+        let value = RustyPyType(value)
+            .try_into_value()
+            .map_err(|e| PyValueError::new_err(e.to_string()))?;
+        Ok(Self { value: Some(value) })
+    }
+
+    #[classmethod]
+    fn none(_cls: &Bound<'_, PyType>) -> Self {
+        Self { value: None }
+    }
+
+    fn has_value(&self) -> bool {
+        self.value.is_some()
+    }
+
+    fn value(&self, py: Python<'_>) -> PyResult<Py<PyAny>> {
+        match &self.value {
+            Some(value) => RustyCelType(value.clone())
+                .into_pyobject(py)
+                .map(|obj| obj.unbind()),
+            None => Err(PyValueError::new_err("optional.none() dereference")),
+        }
+    }
+
+    fn or_value(&self, default: &Bound<'_, PyAny>, py: Python<'_>) -> PyResult<Py<PyAny>> {
+        match &self.value {
+            Some(value) => RustyCelType(value.clone())
+                .into_pyobject(py)
+                .map(|obj| obj.unbind()),
+            None => Ok(default.clone().unbind()),
+        }
+    }
+
+    fn or_optional(&self, other: PyRef<'_, PyOptionalValue>) -> PyOptionalValue {
+        if self.value.is_some() {
+            PyOptionalValue {
+                value: self.value.clone(),
+            }
+        } else {
+            PyOptionalValue {
+                value: other.value.clone(),
+            }
+        }
+    }
+
+    fn __bool__(&self) -> bool {
+        self.value.is_some()
+    }
+
+    fn __repr__(&self) -> String {
+        match &self.value {
+            Some(value) => format!("OptionalValue({value:?})"),
+            None => "OptionalValue.none()".to_string(),
+        }
+    }
+}
+
 /// Compile a CEL expression into a reusable Program object.
 ///
 /// This function parses and compiles a CEL expression, returning a Program object
@@ -146,6 +222,29 @@ impl<'py> IntoPyObject<'py> for RustyCelType {
                 python_dict.into_any()
             }
 
+            RustyCelType(Value::Opaque(opaque)) => {
+                if opaque.runtime_type_name() == "optional_type" {
+                    if let Some(optional) = opaque.downcast_ref::<OptionalValue>() {
+                        Py::new(
+                            py,
+                            PyOptionalValue {
+                                value: optional.value().cloned(),
+                            },
+                        )?
+                        .into_bound(py)
+                        .into_any()
+                    } else {
+                        format!("{:?}", Value::Opaque(opaque.clone()))
+                            .into_pyobject(py)?
+                            .into_any()
+                    }
+                } else {
+                    format!("{:?}", Value::Opaque(opaque.clone()))
+                        .into_pyobject(py)?
+                        .into_any()
+                }
+            }
+
             // Turn everything else into a String:
             nonprimitive => format!("{nonprimitive:?}").into_pyobject(py)?.into_any(),
         };
@@ -170,6 +269,105 @@ impl fmt::Display for CelError {
 }
 impl Error for CelError {}
 
+/// Build a CEL execution environment from an optional evaluation context.
+///
+/// This consolidates the shared logic used by `evaluate()` and `Program.execute()`
+/// to keep behavior consistent between the two entrypoints.
+fn build_environment(
+    evaluation_context: Option<&Bound<'_, PyAny>>,
+    environment: &mut CelContext<'_>,
+) -> PyResult<()> {
+    let mut ctx = context::Context::new(None, None)?;
+
+    // Process the evaluation context if provided
+    if let Some(evaluation_context) = evaluation_context {
+        // Attempt to extract directly as a Context object
+        if let Ok(py_context_ref) = evaluation_context.extract::<PyRef<context::Context>>() {
+            // Clone variables and functions into our local Context
+            ctx.variables = py_context_ref.variables.clone();
+            ctx.functions = py_context_ref.functions.clone();
+        } else if let Ok(py_dict) = evaluation_context.cast::<PyDict>() {
+            // User passed in a dict - let's process variables and functions from the dict
+            ctx.update(py_dict)?;
+        } else {
+            return Err(PyValueError::new_err(
+                "evaluation_context must be a Context object or a dict",
+            ));
+        };
+
+        // Add any variables from the processed context
+        for (name, value) in &ctx.variables {
+            environment
+                .add_variable(name.clone(), value.clone())
+                .map_err(|e| PyValueError::new_err(format!("Failed to add variable '{name}': {e}")))?;
+        }
+
+        // Register Python functions
+        for (function_name, py_function) in ctx.functions.iter() {
+            // Create a wrapper function
+            let py_func_clone = Python::attach(|py| py_function.clone_ref(py));
+            let func_name_clone = function_name.clone();
+
+            // Register a function that takes Arguments (variadic) and returns a Value
+            environment.add_function(
+                function_name,
+                move |args: ::cel::extractors::Arguments| -> Result<Value, ExecutionError> {
+                    let py_func = py_func_clone.clone();
+                    let func_name = func_name_clone.clone();
+
+                    Python::attach(|py| {
+                        // Convert CEL arguments to Python objects
+                        let mut py_args = Vec::new();
+                        for cel_value in args.0.iter() {
+                            let py_arg = RustyCelType(cel_value.clone())
+                                .into_pyobject(py)
+                                .map_err(|e| ExecutionError::FunctionError {
+                                    function: func_name.clone(),
+                                    message: format!("Failed to convert argument to Python: {e}"),
+                                })?
+                                .into_any()
+                                .unbind();
+                            py_args.push(py_arg);
+                        }
+
+                        let py_args_tuple = PyTuple::new(py, py_args).map_err(|e| {
+                            ExecutionError::FunctionError {
+                                function: func_name.clone(),
+                                message: format!("Failed to create arguments tuple: {e}"),
+                            }
+                        })?;
+
+                        // Call the Python function
+                        let py_result = py_func.call1(py, py_args_tuple).map_err(|e| {
+                            warn!("Python function '{}' failed: {}", func_name, e);
+                            ExecutionError::FunctionError {
+                                function: func_name.clone(),
+                                message: format!("Python function call failed: {e}"),
+                            }
+                        })?;
+
+                        // Convert the result back to CEL Value
+                        let py_result_ref = py_result.bind(py);
+                        let cel_value =
+                            RustyPyType(py_result_ref).try_into_value().map_err(|e| {
+                                ExecutionError::FunctionError {
+                                    function: func_name.clone(),
+                                    message: format!(
+                                        "Failed to convert Python result to CEL value: {e}"
+                                    ),
+                                }
+                            })?;
+
+                        Ok(cel_value)
+                    })
+                },
+            );
+        }
+    }
+
+    Ok(())
+}
+
 /// Enhanced error handling that maps CEL execution errors to appropriate Python exceptions
 fn map_execution_error_to_python(error: &ExecutionError) -> PyErr {
     match error {
@@ -248,7 +446,9 @@ impl TryIntoValue for RustyPyType<'_> {
     fn try_into_value(self) -> Result<Value, Self::Error> {
         let val = match self {
             RustyPyType(pyobject) => {
-                if pyobject.is_none() {
+                if let Ok(py_optional) = pyobject.extract::<PyRef<PyOptionalValue>>() {
+                    Ok(py_optional.to_cel_value())
+                } else if pyobject.is_none() {
                     Ok(Value::Null)
                 } else if let Ok(value) = pyobject.extract::<bool>() {
                     Ok(Value::Bool(value))
@@ -473,30 +673,7 @@ impl TryIntoValue for RustyPyType<'_> {
 #[pyfunction(signature = (src, evaluation_context=None))]
 fn evaluate(src: String, evaluation_context: Option<&Bound<'_, PyAny>>) -> PyResult<RustyCelType> {
     let mut environment = CelContext::default();
-    let mut ctx = context::Context::new(None, None)?;
-    let mut variables_for_env = HashMap::new();
-
-    // Custom Rust functions can also be added to the environment...
-    //environment.add_function("add", |a: i64, b: i64| a + b);
-
-    // Process the evaluation context if provided
-    if let Some(evaluation_context) = evaluation_context {
-        // Attempt to extract directly as a Context object
-        if let Ok(py_context_ref) = evaluation_context.extract::<PyRef<context::Context>>() {
-            // Clone variables and functions into our local Context
-            ctx.variables = py_context_ref.variables.clone();
-            ctx.functions = py_context_ref.functions.clone();
-        } else if let Ok(py_dict) = evaluation_context.cast::<PyDict>() {
-            // User passed in a dict - let's process variables and functions from the dict
-            ctx.update(py_dict)?;
-        } else {
-            return Err(PyValueError::new_err(
-                "evaluation_context must be a Context object or a dict",
-            ));
-        };
-
-        variables_for_env = ctx.variables.clone();
-    }
+    build_environment(evaluation_context, &mut environment)?;
 
     // Use panic::catch_unwind to handle parser panics gracefully
     let program = panic::catch_unwind(|| Program::compile(&src))
@@ -508,80 +685,6 @@ fn evaluate(src: String, evaluation_context: Option<&Bound<'_, PyAny>>) -> PyRes
         })?
         .map_err(|e| PyValueError::new_err(format!("Failed to parse expression '{src}': {e}")))?;
 
-    // Add variables and functions if we have a context
-    if evaluation_context.is_some() {
-        // Add any variables from the processed context
-        for (name, value) in &variables_for_env {
-            environment
-                .add_variable(name.clone(), value.clone())
-                .map_err(|e| {
-                    PyValueError::new_err(format!("Failed to add variable '{name}': {e}"))
-                })?;
-        }
-
-        // Register Python functions
-        for (function_name, py_function) in ctx.functions.iter() {
-            // Create a wrapper function
-            let py_func_clone = Python::attach(|py| py_function.clone_ref(py));
-            let func_name_clone = function_name.clone();
-
-            // Register a function that takes Arguments (variadic) and returns a Value
-            environment.add_function(
-                function_name,
-                move |args: ::cel::extractors::Arguments| -> Result<Value, ExecutionError> {
-                    let py_func = py_func_clone.clone();
-                    let func_name = func_name_clone.clone();
-
-                    Python::attach(|py| {
-                        // Convert CEL arguments to Python objects
-                        let mut py_args = Vec::new();
-                        for cel_value in args.0.iter() {
-                            let py_arg = RustyCelType(cel_value.clone())
-                                .into_pyobject(py)
-                                .map_err(|e| ExecutionError::FunctionError {
-                                    function: func_name.clone(),
-                                    message: format!("Failed to convert argument to Python: {e}"),
-                                })?
-                                .into_any()
-                                .unbind();
-                            py_args.push(py_arg);
-                        }
-
-                        let py_args_tuple = PyTuple::new(py, py_args).map_err(|e| {
-                            ExecutionError::FunctionError {
-                                function: func_name.clone(),
-                                message: format!("Failed to create arguments tuple: {e}"),
-                            }
-                        })?;
-
-                        // Call the Python function
-                        let py_result = py_func.call1(py, py_args_tuple).map_err(|e| {
-                            warn!("Python function '{}' failed: {}", func_name, e);
-                            ExecutionError::FunctionError {
-                                function: func_name.clone(),
-                                message: format!("Python function call failed: {e}"),
-                            }
-                        })?;
-
-                        // Convert the result back to CEL Value
-                        let py_result_ref = py_result.bind(py);
-                        let cel_value =
-                            RustyPyType(py_result_ref).try_into_value().map_err(|e| {
-                                ExecutionError::FunctionError {
-                                    function: func_name.clone(),
-                                    message: format!(
-                                        "Failed to convert Python result to CEL value: {e}"
-                                    ),
-                                }
-                            })?;
-
-                        Ok(cel_value)
-                    })
-                },
-            );
-        }
-    }
-
     // Use panic::catch_unwind to handle execution panics gracefully
     // AssertUnwindSafe is needed because the environment contains function closures
     let result =
@@ -606,101 +709,7 @@ fn execute_compiled_program(
     evaluation_context: Option<&Bound<'_, PyAny>>,
 ) -> PyResult<Py<PyAny>> {
     let mut environment = CelContext::default();
-    let mut ctx = context::Context::new(None, None)?;
-    let mut variables_for_env = HashMap::new();
-
-    // Process the evaluation context if provided
-    if let Some(evaluation_context) = evaluation_context {
-        // Attempt to extract directly as a Context object
-        if let Ok(py_context_ref) = evaluation_context.extract::<PyRef<context::Context>>() {
-            // Clone variables and functions into our local Context
-            ctx.variables = py_context_ref.variables.clone();
-            ctx.functions = py_context_ref.functions.clone();
-        } else if let Ok(py_dict) = evaluation_context.cast::<PyDict>() {
-            // User passed in a dict - let's process variables and functions from the dict
-            ctx.update(py_dict)?;
-        } else {
-            return Err(PyValueError::new_err(
-                "evaluation_context must be a Context object or a dict",
-            ));
-        };
-
-        variables_for_env = ctx.variables.clone();
-    }
-
-    // Add variables and functions if we have a context
-    if evaluation_context.is_some() {
-        // Add any variables from the processed context
-        for (name, value) in &variables_for_env {
-            environment
-                .add_variable(name.clone(), value.clone())
-                .map_err(|e| {
-                    PyValueError::new_err(format!("Failed to add variable '{name}': {e}"))
-                })?;
-        }
-
-        // Register Python functions
-        for (function_name, py_function) in ctx.functions.iter() {
-            // Create a wrapper function
-            let py_func_clone = Python::attach(|py| py_function.clone_ref(py));
-            let func_name_clone = function_name.clone();
-
-            // Register a function that takes Arguments (variadic) and returns a Value
-            environment.add_function(
-                function_name,
-                move |args: ::cel::extractors::Arguments| -> Result<Value, ExecutionError> {
-                    let py_func = py_func_clone.clone();
-                    let func_name = func_name_clone.clone();
-
-                    Python::attach(|py| {
-                        // Convert CEL arguments to Python objects
-                        let mut py_args = Vec::new();
-                        for cel_value in args.0.iter() {
-                            let py_arg = RustyCelType(cel_value.clone())
-                                .into_pyobject(py)
-                                .map_err(|e| ExecutionError::FunctionError {
-                                    function: func_name.clone(),
-                                    message: format!("Failed to convert argument to Python: {e}"),
-                                })?
-                                .into_any()
-                                .unbind();
-                            py_args.push(py_arg);
-                        }
-
-                        let py_args_tuple = PyTuple::new(py, py_args).map_err(|e| {
-                            ExecutionError::FunctionError {
-                                function: func_name.clone(),
-                                message: format!("Failed to create arguments tuple: {e}"),
-                            }
-                        })?;
-
-                        // Call the Python function
-                        let py_result = py_func.call1(py, py_args_tuple).map_err(|e| {
-                            warn!("Python function '{}' failed: {}", func_name, e);
-                            ExecutionError::FunctionError {
-                                function: func_name.clone(),
-                                message: format!("Python function call failed: {e}"),
-                            }
-                        })?;
-
-                        // Convert the result back to CEL Value
-                        let py_result_ref = py_result.bind(py);
-                        let cel_value =
-                            RustyPyType(py_result_ref).try_into_value().map_err(|e| {
-                                ExecutionError::FunctionError {
-                                    function: func_name.clone(),
-                                    message: format!(
-                                        "Failed to convert Python result to CEL value: {e}"
-                                    ),
-                                }
-                            })?;
-
-                        Ok(cel_value)
-                    })
-                },
-            );
-        }
-    }
+    build_environment(evaluation_context, &mut environment)?;
 
     // Use panic::catch_unwind to handle execution panics gracefully
     // AssertUnwindSafe is needed because the environment contains function closures
@@ -730,5 +739,6 @@ fn cel(_py: Python<'_>, m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(compile, m)?)?;
     m.add_class::<context::Context>()?;
     m.add_class::<PyProgram>()?;
+    m.add_class::<PyOptionalValue>()?;
     Ok(())
 }
diff --git a/tests/test_functions.py b/tests/test_functions.py
index 6c136a1..39e1bff 100644
--- a/tests/test_functions.py
+++ b/tests/test_functions.py
@@ -421,8 +421,8 @@ def complex_calculation(data):
         end_time = time.perf_counter()
         avg_time = (end_time - start_time) / iterations
 
-        # Should complete within reasonable time (under 1ms per call)
-        assert avg_time < 0.001, (
+        # Should complete within reasonable time (under 1.5ms per call)
+        assert avg_time < 0.0015, (
             f"Complex function call too slow: {avg_time * 1000:.1f} ms per call"
         )
 
@@ -446,9 +446,9 @@ def process_large_list(items):
         # Verify correctness
         assert result == 5000  # Half the numbers are even
 
-        # Should complete within reasonable time (under 10ms)
+        # Should complete within reasonable time (under 20ms)
         execution_time = end_time - start_time
-        assert execution_time < 0.01, (
+        assert execution_time < 0.02, (
             f"Large data processing too slow: {execution_time * 1000:.1f} ms"
         )
 
diff --git a/tests/test_optional_values.py b/tests/test_optional_values.py
new file mode 100644
index 0000000..6d4b47f
--- /dev/null
+++ b/tests/test_optional_values.py
@@ -0,0 +1,39 @@
+import cel
+import pytest
+
+
+def test_optional_of_wrapper():
+    opt = cel.evaluate("optional.of(42)")
+    assert isinstance(opt, cel.OptionalValue)
+    assert opt.has_value() is True
+    assert opt.value() == 42
+    assert opt.or_value(0) == 42
+    assert bool(opt) is True
+
+
+def test_optional_none_wrapper():
+    opt = cel.evaluate("optional.none()")
+    assert isinstance(opt, cel.OptionalValue)
+    assert opt.has_value() is False
+    assert opt.or_value("default") == "default"
+    assert bool(opt) is False
+    with pytest.raises(ValueError, match="optional.none"):
+        opt.value()
+
+
+def test_optional_of_null_distinct():
+    opt = cel.evaluate("optional.of(null)")
+    assert isinstance(opt, cel.OptionalValue)
+    assert opt.has_value() is True
+    assert opt.value() is None
+    assert opt.or_value("default") is None
+
+
+def test_optional_in_context():
+    opt = cel.OptionalValue.of(123)
+    assert cel.evaluate("opt.orValue(0)", {"opt": opt}) == 123
+    assert cel.evaluate("opt.hasValue()", {"opt": opt}) is True
+
+    none_opt = cel.OptionalValue.none()
+    assert cel.evaluate("opt.orValue(7)", {"opt": none_opt}) == 7
+    assert cel.evaluate("opt.hasValue()", {"opt": none_opt}) is False
diff --git a/tests/test_upstream_improvements.py b/tests/test_upstream_improvements.py
index 059cb97..c1eadb6 100644
--- a/tests/test_upstream_improvements.py
+++ b/tests/test_upstream_improvements.py
@@ -119,14 +119,11 @@ def test_mixed_arithmetic_expected_behavior(self):
 class TestOptionalValues:
     """Test optional value functionality that may be implemented in future."""
 
-    def test_optional_of_not_implemented(self):
-        """
-        Test that optional.of() is not implemented.
-
-        When this test starts failing, optional values have been implemented.
-        """
-        with pytest.raises(RuntimeError, match="Undefined variable or function.*of"):
-            cel.evaluate("optional.of(42)")
+    def test_optional_of_implemented(self):
+        """Test optional.of() and optional.none() behavior."""
+        assert cel.evaluate("optional.of(42).orValue(0)") == 42
+        assert cel.evaluate("optional.of(null).orValue('default')") is None
+        assert cel.evaluate("optional.none().orValue('default')") == "default"
 
     def test_optional_chaining_not_implemented(self):
         """
@@ -139,16 +136,15 @@ def test_optional_chaining_not_implemented(self):
         with pytest.raises((ValueError, RuntimeError)):
             cel.evaluate("user?.profile?.name", {"user": {"profile": {"name": "Alice"}}})
 
-    @pytest.mark.xfail(reason="Optional values not implemented in cel v0.11.0", strict=False)
     def test_optional_expected_behavior(self):
         """
         Test expected optional value behavior when implemented.
 
-        This test will pass when upstream implements optional values.
+        This test verifies the CEL spec for optional values.
         """
-        # These are expectations based on CEL spec
         assert cel.evaluate("optional.of(42).orValue(0)") == 42
-        assert cel.evaluate('optional.of(null).orValue("default")') == "default"
+        assert cel.evaluate("optional.of(null).orValue('default')") is None
+        assert cel.evaluate("optional.none().orValue('default')") == "default"
 
 
 class TestMapFunctionImprovements:

From e341e783a1dc004ffec8315380200dfb6659ef83 Mon Sep 17 00:00:00 2001
From: Brian Thorne <brian@thorne.link>
Date: Sat, 7 Feb 2026 20:18:48 +1300
Subject: [PATCH 4/6] Add compile/execute benchmark and fix mypy

---
 .../performance/compile_execute_benchmark.py  |  90 ++++++++++++++++
 pyproject.toml                                |  10 ++
 python/cel/cel.pyi                            |   2 -
 python/cel/evaluation_modes.py                |  11 ++
 python/cel/stdlib.py                          |   4 +-
 src/lib.rs                                    |   8 +-
 tests/test_compile.py                         | 100 +++++++++---------
 7 files changed, 171 insertions(+), 54 deletions(-)
 create mode 100644 examples/performance/compile_execute_benchmark.py
 create mode 100644 python/cel/evaluation_modes.py

diff --git a/examples/performance/compile_execute_benchmark.py b/examples/performance/compile_execute_benchmark.py
new file mode 100644
index 0000000..ba3d576
--- /dev/null
+++ b/examples/performance/compile_execute_benchmark.py
@@ -0,0 +1,90 @@
+"""Compare evaluate() vs compile()+execute() performance.
+
+Run:
+  uv run python examples/performance/compile_execute_benchmark.py
+"""
+
+import json
+import statistics
+import time
+from typing import Any, Callable
+
+import cel
+
+
+def bench_case(
+    func: Callable[[], Any], iterations: int = 5000, repeats: int = 3
+) -> dict[str, float | int]:
+    times = []
+    for _ in range(repeats):
+        func()
+        start = time.perf_counter()
+        for _i in range(iterations):
+            func()
+        end = time.perf_counter()
+        times.append((end - start) / iterations * 1_000_000)  # us
+    avg = statistics.mean(times)
+    stdev = statistics.stdev(times) if len(times) > 1 else 0.0
+    return {
+        "avg_us": avg,
+        "stdev_us": stdev,
+        "min_us": min(times),
+        "max_us": max(times),
+        "iterations": iterations,
+        "repeats": repeats,
+    }
+
+
+def measure_compile(expr: str) -> tuple[cel.Program, float]:
+    start = time.perf_counter()
+    program = cel.compile(expr)
+    end = time.perf_counter()
+    return program, (end - start) * 1_000_000
+
+
+def main() -> None:
+    results: dict[str, dict[str, Any]] = {}
+
+    cases: list[tuple[str, str, Any]] = []
+
+    ctx_simple: dict[str, Any] = {"x": 10, "y": 20}
+    ctx_str: dict[str, Any] = {"greet": "hello", "name": "world"}
+    ctx_list: dict[str, Any] = {"items": list(range(1000))}
+    ctx_map: dict[str, Any] = {"user": {"role": "admin", "active": True}}
+
+    cases.append(("simple_arithmetic", "x + y * 2", ctx_simple))
+    cases.append(("string_concat", "greet + ' ' + name", ctx_str))
+    cases.append(("list_size", "size(items)", ctx_list))
+    cases.append(
+        (
+            "map_lookup_bool",
+            "user.role == 'admin' && user.active",
+            ctx_map,
+        )
+    )
+
+    ctx_func = cel.Context()
+    ctx_func.add_function("double", lambda x: x * 2)
+    ctx_func.add_variable("x", 21)
+    cases.append(("python_function", "double(x)", ctx_func))
+
+    for name, expr, ctx in cases:
+        program, compile_us = measure_compile(expr)
+
+        eval_bench = bench_case(lambda: cel.evaluate(expr, ctx))
+        exec_bench = bench_case(lambda: program.execute(ctx))
+
+        speedup = eval_bench["avg_us"] / exec_bench["avg_us"] if exec_bench["avg_us"] > 0 else None
+
+        results[name] = {
+            "compile_time_us": compile_us,
+            "evaluate": eval_bench,
+            "compiled_execute": exec_bench,
+            "speedup_eval_over_execute": speedup,
+        }
+
+    print(json.dumps(results, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/pyproject.toml b/pyproject.toml
index bb4b82b..e4cbd81 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -98,8 +98,18 @@ exclude = [
     "tests/",
     ".venv/",
     "target/",
+    "shell/",
+    "test_tui_complete.py",
 ]
 
+[[tool.mypy.overrides]]
+module = ["cel.cli"]
+ignore_errors = true
+
+[[tool.mypy.overrides]]
+module = ["pygments", "pygments.lexer"]
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 python_files = ["test_*.py"]
diff --git a/python/cel/cel.pyi b/python/cel/cel.pyi
index b23daf7..32b3edd 100644
--- a/python/cel/cel.pyi
+++ b/python/cel/cel.pyi
@@ -48,10 +48,8 @@ class OptionalValue:
 
     @classmethod
     def of(cls, value: Any) -> OptionalValue: ...
-
     @classmethod
     def none(cls) -> OptionalValue: ...
-
     def has_value(self) -> bool: ...
     def value(self) -> Any: ...
     def or_value(self, default: Any) -> Any: ...
diff --git a/python/cel/evaluation_modes.py b/python/cel/evaluation_modes.py
new file mode 100644
index 0000000..3dd5c1b
--- /dev/null
+++ b/python/cel/evaluation_modes.py
@@ -0,0 +1,11 @@
+"""Evaluation mode enum for CEL.
+
+Kept for typing compatibility with cel.pyi.
+"""
+
+from enum import Enum
+
+
+class EvaluationMode(str, Enum):
+    PYTHON = "python"
+    STRICT = "strict"
diff --git a/python/cel/stdlib.py b/python/cel/stdlib.py
index 9957814..85ec5fa 100644
--- a/python/cel/stdlib.py
+++ b/python/cel/stdlib.py
@@ -5,6 +5,8 @@
 that are missing from the upstream cel-rust implementation.
 """
 
+from typing import Any
+
 
 def substring(s: str, start: int, end: int | None = None) -> str:
     """
@@ -42,7 +44,7 @@ def substring(s: str, start: int, end: int | None = None) -> str:
 }
 
 
-def add_stdlib_to_context(context):
+def add_stdlib_to_context(context: Any) -> None:
     """
     Add all stdlib functions to a CEL Context.
 
diff --git a/src/lib.rs b/src/lib.rs
index 71da8f5..504833b 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -166,7 +166,9 @@ fn compile(expression: String) -> PyResult<PyProgram> {
                 "Failed to parse expression '{expression}': Invalid syntax or malformed string"
             ))
         })?
-        .map_err(|e| PyValueError::new_err(format!("Failed to parse expression '{expression}': {e}")))?;
+        .map_err(|e| {
+            PyValueError::new_err(format!("Failed to parse expression '{expression}': {e}"))
+        })?;
 
     Ok(PyProgram {
         program,
@@ -299,7 +301,9 @@ fn build_environment(
         for (name, value) in &ctx.variables {
             environment
                 .add_variable(name.clone(), value.clone())
-                .map_err(|e| PyValueError::new_err(format!("Failed to add variable '{name}': {e}")))?;
+                .map_err(|e| {
+                    PyValueError::new_err(format!("Failed to add variable '{name}': {e}"))
+                })?;
         }
 
         // Register Python functions
diff --git a/tests/test_compile.py b/tests/test_compile.py
index 6d5c8c2..9c1cf59 100644
--- a/tests/test_compile.py
+++ b/tests/test_compile.py
@@ -65,22 +65,20 @@ def test_execute_with_context_object(self):
     def test_execute_same_program_different_contexts(self):
         """Test executing the same program with different contexts."""
         program = cel.compile("price * quantity")
-        
+
         result1 = program.execute({"price": 10, "quantity": 5})
         assert result1 == 50
-        
+
         result2 = program.execute({"price": 25, "quantity": 4})
         assert result2 == 100
-        
+
         result3 = program.execute({"price": 100, "quantity": 1})
         assert result3 == 100
 
     def test_execute_with_nested_context(self):
         """Test executing with nested dictionary context."""
         program = cel.compile("user.name + ' (' + user.role + ')'")
-        result = program.execute({
-            "user": {"name": "Bob", "role": "admin"}
-        })
+        result = program.execute({"user": {"name": "Bob", "role": "admin"}})
         assert result == "Bob (admin)"
 
     def test_execute_with_list_context(self):
@@ -209,71 +207,75 @@ def test_access_control_policy(self):
         policy = cel.compile(
             'user.role == "admin" || (resource.owner == user.id && action == "read")'
         )
-        
+
         # Admin can do anything
-        assert policy.execute({
-            "user": {"id": "alice", "role": "admin"},
-            "resource": {"owner": "bob"},
-            "action": "delete"
-        }) is True
-        
+        assert (
+            policy.execute(
+                {
+                    "user": {"id": "alice", "role": "admin"},
+                    "resource": {"owner": "bob"},
+                    "action": "delete",
+                }
+            )
+            is True
+        )
+
         # Owner can read their own resource
-        assert policy.execute({
-            "user": {"id": "bob", "role": "user"},
-            "resource": {"owner": "bob"},
-            "action": "read"
-        }) is True
-        
+        assert (
+            policy.execute(
+                {
+                    "user": {"id": "bob", "role": "user"},
+                    "resource": {"owner": "bob"},
+                    "action": "read",
+                }
+            )
+            is True
+        )
+
         # Non-owner cannot read others' resources
-        assert policy.execute({
-            "user": {"id": "charlie", "role": "user"},
-            "resource": {"owner": "bob"},
-            "action": "read"
-        }) is False
+        assert (
+            policy.execute(
+                {
+                    "user": {"id": "charlie", "role": "user"},
+                    "resource": {"owner": "bob"},
+                    "action": "read",
+                }
+            )
+            is False
+        )
 
     def test_pricing_calculation(self):
         """Test pricing calculation with discounts."""
-        pricing = cel.compile(
-            "price * quantity * (1.0 - discount)"
-        )
-        
+        pricing = cel.compile("price * quantity * (1.0 - discount)")
+
         # No discount
-        assert pricing.execute({
-            "price": 100.0, "quantity": 2.0, "discount": 0.0
-        }) == 200.0
-        
+        assert pricing.execute({"price": 100.0, "quantity": 2.0, "discount": 0.0}) == 200.0
+
         # 10% discount
-        result = pricing.execute({
-            "price": 100.0, "quantity": 2.0, "discount": 0.1
-        })
+        result = pricing.execute({"price": 100.0, "quantity": 2.0, "discount": 0.1})
         assert abs(result - 180.0) < 0.001
 
     def test_validation_rules(self):
         """Test validation rules."""
         age_check = cel.compile("age >= 18 && age <= 120")
-        
+
         assert age_check.execute({"age": 25}) is True
         assert age_check.execute({"age": 17}) is False
         assert age_check.execute({"age": 121}) is False
 
     def test_data_filtering(self):
         """Test data filtering expression."""
-        filter_expr = cel.compile(
-            'status == "active" && score >= min_score'
-        )
-        
+        filter_expr = cel.compile('status == "active" && score >= min_score')
+
         items = [
             {"status": "active", "score": 85},
             {"status": "inactive", "score": 90},
             {"status": "active", "score": 70},
             {"status": "active", "score": 95},
         ]
-        
-        filtered = [
-            item for item in items
-            if filter_expr.execute({**item, "min_score": 80})
-        ]
-        
+
+        filtered = [item for item in items if filter_expr.execute({**item, "min_score": 80})]
+
         assert len(filtered) == 2
         assert filtered[0]["score"] == 85
         assert filtered[1]["score"] == 95
@@ -286,13 +288,13 @@ def test_compile_once_execute_many(self):
         """Demonstrate compile-once-execute-many pattern."""
         # Compile the expression once
         expr = cel.compile("x * x + y * y")
-        
+
         # Execute many times with different values
         results = []
         for i in range(100):
             result = expr.execute({"x": i, "y": i + 1})
             results.append(result)
-        
+
         # Verify some results
         assert results[0] == 0 * 0 + 1 * 1  # 1
         assert results[1] == 1 * 1 + 2 * 2  # 5
@@ -301,7 +303,7 @@ def test_compile_once_execute_many(self):
     def test_reuse_compiled_program(self):
         """Test that compiled programs can be reused safely."""
         program = cel.compile("value > threshold")
-        
+
         # Multiple sequential executions
         assert program.execute({"value": 10, "threshold": 5}) is True
         assert program.execute({"value": 3, "threshold": 5}) is False

From 8337f44e85bfa62e7d1072695728cc93d4db2419 Mon Sep 17 00:00:00 2001
From: Brian Thorne <brian@thorne.link>
Date: Sat, 7 Feb 2026 20:23:22 +1300
Subject: [PATCH 5/6] Fix ruff lint in benchmark and tests

---
 examples/performance/compile_execute_benchmark.py | 6 ++++--
 tests/test_compile.py                             | 2 +-
 2 files changed, 5 insertions(+), 3 deletions(-)

diff --git a/examples/performance/compile_execute_benchmark.py b/examples/performance/compile_execute_benchmark.py
index ba3d576..d8380ef 100644
--- a/examples/performance/compile_execute_benchmark.py
+++ b/examples/performance/compile_execute_benchmark.py
@@ -71,8 +71,10 @@ def main() -> None:
     for name, expr, ctx in cases:
         program, compile_us = measure_compile(expr)
 
-        eval_bench = bench_case(lambda: cel.evaluate(expr, ctx))
-        exec_bench = bench_case(lambda: program.execute(ctx))
+        eval_bench = bench_case(lambda expr=expr, ctx=ctx: cel.evaluate(expr, ctx))
+        exec_bench = bench_case(
+            lambda program=program, ctx=ctx: program.execute(ctx)
+        )
 
         speedup = eval_bench["avg_us"] / exec_bench["avg_us"] if exec_bench["avg_us"] > 0 else None
 
diff --git a/tests/test_compile.py b/tests/test_compile.py
index 9c1cf59..a5be111 100644
--- a/tests/test_compile.py
+++ b/tests/test_compile.py
@@ -8,8 +8,8 @@
 import datetime
 
 import cel
-from cel import Context
 import pytest
+from cel import Context
 
 
 class TestCompileBasics:

From 1a172c8cae8749f22d2431ece81282ef167511ba Mon Sep 17 00:00:00 2001
From: Brian Thorne <brian@thorne.link>
Date: Sat, 7 Feb 2026 20:33:33 +1300
Subject: [PATCH 6/6] Format compile/execute benchmark

---
 examples/performance/compile_execute_benchmark.py | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/examples/performance/compile_execute_benchmark.py b/examples/performance/compile_execute_benchmark.py
index d8380ef..f8a2f12 100644
--- a/examples/performance/compile_execute_benchmark.py
+++ b/examples/performance/compile_execute_benchmark.py
@@ -72,9 +72,7 @@ def main() -> None:
         program, compile_us = measure_compile(expr)
 
         eval_bench = bench_case(lambda expr=expr, ctx=ctx: cel.evaluate(expr, ctx))
-        exec_bench = bench_case(
-            lambda program=program, ctx=ctx: program.execute(ctx)
-        )
+        exec_bench = bench_case(lambda program=program, ctx=ctx: program.execute(ctx))
 
         speedup = eval_bench["avg_us"] / exec_bench["avg_us"] if exec_bench["avg_us"] > 0 else None