Add EvaluationMode for flexible type handling in CEL expressions

Author: hardbyte

docs/index.md

@@ -56,6 +56,11 @@ The Common Expression Language (CEL) is a non-Turing complete language designed
     # With context
     cel 'age >= 21' --context '{"age": 25}'  # → true
 
+    # Mixed arithmetic with modes
+    cel '1 + 2.5'                            # → Error (default: strict mode)
+    cel '1 + 2.5' --mode python              # → 3.5 (python-friendly mode)
+    cel '1 + 2.5' --mode strict              # → Error (strict CEL rules)
+    
     # Interactive REPL
     cel --interactive
     ```
@@ -93,6 +98,7 @@ The Common Expression Language (CEL) is a non-Turing complete language designed
 ✅ **Safe by design** (Rust core)  
 ✅ **Ready for production**  
 ✅ **No GIL-blocking, safe concurrent evaluation**  
+✅ **Flexible type handling** (Python-friendly + strict modes)  
 
 ## Why Python CEL?
 

docs/reference/cli-reference.md

@@ -49,6 +49,23 @@ Enable debug mode with detailed error information.
 cel --debug 'user.role == "admin"' --context-file user.json
 ```
 
+#### `--mode`, `-m`
+Set the evaluation mode for type handling.
+
+```bash
+cel '1 + 2.5' --mode python        # → 3.5 (python-friendly type promotions)
+cel '1 + 2.5' --mode strict        # → Error (default: strict CEL type rules)
+cel '1 + 2.5' -m python           # → 3.5 (short form)
+```
+
+**Values**:
+- `python` - Python-friendly type promotions for mixed arithmetic
+- `strict` (default) - Strict CEL type rules with no automatic coercion
+
+**Use Cases**:
+- `python`: Best for JSON APIs, user-friendly applications, Python integration
+- `strict`: Best for CEL spec compliance, type precision, cross-language consistency
+
 ### Context Options
 
 #### `--context`, `-c`
@@ -250,6 +267,10 @@ cel 'expression'
 cel 'expression' --context '{"key": "value"}'
 cel 'expression' --context-file context.json
 
+# With evaluation mode
+cel 'expression' --mode python    # Python-friendly mixed arithmetic
+cel 'expression' --mode strict    # Default: strict CEL type rules
+
 # Interactive mode
 cel --interactive
 ```

docs/reference/python-api.md

@@ -6,6 +6,96 @@ Complete autogenerated reference for the Python CEL library.
 
 ::: cel.evaluate
 
+## Enums
+
+### EvaluationMode
+
+**Controls how CEL expressions handle type compatibility.**
+
+The EvaluationMode enum allows you to choose between Python-friendly type coercion (default) and strict CEL type enforcement:
+
+```python
+from cel import evaluate, EvaluationMode
+
+# Python-friendly mode (default) - allows mixed arithmetic
+result = evaluate("1 + 2.5")  # → 3.5
+result = evaluate("1 + 2.5", mode=EvaluationMode.PYTHON)  # → 3.5
+result = evaluate("1 + 2.5", mode="python")  # → 3.5
+
+# Strict mode - enforces strict CEL type rules
+try:
+    evaluate("1 + 2.5", mode=EvaluationMode.STRICT)  # TypeError
+except TypeError as e:
+    print(f"Strict mode error: {e}")  # → "Unsupported addition operation"
+
+try:
+    evaluate("1 + 2.5", mode="strict")  # TypeError
+except TypeError as e:
+    print(f"Strict mode error: {e}")  # → "Unsupported addition operation"
+```
+
+#### Values
+
+**EvaluationMode.PYTHON** (or `"python"`)  
+*Default mode for Python API.* Enables Python-friendly type promotions for better mixed arithmetic compatibility:
+- Integer literals are automatically promoted to floats when used with floats
+- Context variables are promoted from int to float when mixed arithmetic is detected
+- Expression preprocessing converts `1 + 2.5` to `1.0 + 2.5` for compatibility
+
+**EvaluationMode.STRICT** (or `"strict"`)  
+*Default mode for CLI.* Enforces strict CEL type rules with no automatic coercion:
+- Mixed int/float arithmetic raises TypeError
+- No type promotions or expression rewriting
+- Matches WebAssembly CEL behavior exactly
+
+#### Default Modes
+
+**Note**: The Python API and CLI have different defaults:
+- **Python API**: Defaults to `EvaluationMode.PYTHON` for seamless integration with Python code
+- **CLI**: Defaults to `EvaluationMode.STRICT` for CEL specification compliance and testing
+
+#### When to Use Each Mode
+
+**Use PYTHON mode (Python API default) when:**
+- Integrating with existing Python code that expects mixed numeric types
+- Working with data from JSON APIs (which often mix ints and floats)
+- Building user-friendly applications where type coercion feels natural
+- Migrating from pure Python evaluation logic
+
+**Use STRICT mode (CLI default) when:**
+- Building applications that need to match CEL implementations in other languages
+- Working with systems where type precision is critical
+- Following strict CEL specification compliance
+- Debugging type-related issues in expressions
+
+#### Implementation Details
+
+In PYTHON mode, the library:
+1. Analyzes context for mixed numeric types (int + float)
+2. Promotes integers to floats in both context variables and expression literals
+3. Preprocesses expressions like `1 + 2.5` to become `1.0 + 2.5`
+
+In STRICT mode, the library:
+1. Performs no type promotions or expression rewriting
+2. Passes expressions directly to the CEL evaluator
+3. Raises TypeError for incompatible type operations
+
+**Example with Context:**
+```python
+from cel import evaluate, EvaluationMode
+
+context = {"x": 1, "y": 2.5}  # Mixed int/float in context
+
+# Python mode handles mixed types gracefully
+result = evaluate("x + y", context, mode=EvaluationMode.PYTHON)  # → 3.5
+
+# Strict mode rejects mixed types
+try:
+    evaluate("x + y", context, mode=EvaluationMode.STRICT)  # TypeError
+except TypeError as e:
+    print("Mixed types not allowed in strict mode")
+```
+
 ## Classes  
 
 ### Context
@@ -292,12 +382,45 @@ except TypeError as e:
     assert "Unsupported multiplication operation" in str(e)
 ```
 
+#### EvaluationMode-Specific Errors
+
+**Strict mode can produce additional TypeError exceptions:**
+
+```python
+from cel import evaluate, EvaluationMode
+
+# Mixed numeric types in strict mode
+try:
+    evaluate("1 + 2.5", mode=EvaluationMode.STRICT)
+except TypeError as e:
+    assert "Unsupported addition operation" in str(e)
+    print(f"Strict mode type error: {e}")
+
+# Mixed types from context in strict mode
+context = {"int_val": 10, "float_val": 2.5}
+try:
+    evaluate("int_val * float_val", context, mode=EvaluationMode.STRICT)
+except TypeError as e:
+    assert "Unsupported multiplication operation" in str(e)
+    print(f"Context type mixing error: {e}")
+```
+
+**Invalid mode strings raise TypeError:**
+
+```python
+try:
+    evaluate("1 + 2", mode="invalid_mode")
+except TypeError as e:
+    assert "Invalid EvaluationMode" in str(e)
+    print(f"Invalid mode error: {e}")
+```
+
 ### Production Error Handling
 
 For comprehensive error handling patterns, safety guidelines, and production best practices, see the **[Error Handling How-To Guide](../how-to-guides/error-handling.md)** which covers:
 
 - Safe handling of malformed expressions and untrusted input
-- Safe evaluation wrappers
+- Safe evaluation wrappers with EvaluationMode considerations
 - Context validation patterns
 - Defensive expression techniques
 - Logging and monitoring

python/cel/__init__.py

@@ -19,15 +19,3 @@ class EvaluationMode(str, Enum):
     """
     Enforces strict cel-rust type rules with no automatic coercion to match Wasm behavior.
     """
-
-
-__doc__ = cel.__doc__
-if hasattr(cel, "__all__"):
-    # Ensure EvaluationMode is always exported even if Rust module defines __all__
-    __all__ = list(cel.__all__) + ["EvaluationMode"]
-else:
-    __all__ = [
-        "evaluate",
-        "Context",
-        "EvaluationMode",
-    ]

python/cel/cli.py

@@ -192,7 +192,7 @@ def _get_auto_renderable(result: Any) -> Any:
 class CELEvaluator:
     """Enhanced CEL expression evaluator."""
 
-    def __init__(self, context: Optional[Dict[str, Any]] = None, mode: str = "python"):
+    def __init__(self, context: Optional[Dict[str, Any]] = None, mode: str = "strict"):
         """Initialize evaluator with optional context and mode."""
         self.context = context or {}
         self.mode = mode
@@ -562,7 +562,7 @@ def main(
             "--mode",
             help="Evaluation mode: python (mixed arithmetic) or strict (type matching)",
         ),
-    ] = "python",
+    ] = "strict",
     interactive: Annotated[
         bool, typer.Option("-i", "--interactive", help="Start interactive REPL mode")
     ] = False,