GeniosAI · Tjstretchalot · Aug 13, 2026 · coderabbitai · Aug 13, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added `cel.prepare(value)` and opaque immutable `PreparedValue` handles for one-time Python-to-CEL conversion.
+- Added direct reusable native contexts; prepared values can be shared across contexts and replaced with a cheap shared-handle insertion.
+
+### Changed
+
+- `Context()` now accepts no constructor arguments, and `Context.add_variable()` accepts only `PreparedValue`.
+- `Program.execute(context)` and `evaluate(expression, context)` now require a `Context` and borrow its native CEL environment directly.
+- Prepared values capture a snapshot of mutable Python inputs. Retain prepared objects used for hot-path replacement to avoid final-reference recursive destruction in the hot path.
+
+### Removed
+
+- Removed context constructor mappings, `Context.update()`, raw variable insertion, dictionary execution, and optional/omitted execution contexts.
+
 ## [0.5.6] - 2026-02-07
 
 ### Fixed

diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "cel"
-version = "0.5.6"
+version = "0.6.0"
 edition = "2021"
 
 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
@@ -10,7 +10,7 @@ crate-type = ["cdylib"]
 
 [dependencies]
 pyo3 = { version = "0.27", features = ["chrono", "py-clone"]}
-cel = { git = "https://github.com/GeniosAI/cel-rust.git", rev = "1f35435e5ad3261083cf7f337b922765d01dcb63", package = "cel", features = ["chrono", "json", "regex", "bytes"] }
+cel = { git = "https://github.com/GeniosAI/cel-rust.git", rev = "b9a85818c6f3d2b3098250bab8a3022154485895", package = "cel", 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
@@ -36,21 +36,26 @@ After installation, both the Python library and the `cel` command-line tool will
 
 ### Python API
 
-```python
-from cel import evaluate
+Python values are prepared explicitly and installed into a reusable native context:
 
-# Simple expressions
-result = evaluate("1 + 2")  # 3
-result = evaluate("'Hello ' + 'World'")  # "Hello World"
-result = evaluate("age >= 18", {"age": 25})  # True
+```python
+import cel
 
-# Complex expressions with context
-result = evaluate(
+context = cel.Context()
+context.add_variable("age", cel.prepare(25))
+result = cel.evaluate("age >= 18", context)  # True
+
+context.add_variable(
+    "user",
+    cel.prepare({"role": "admin"}),
+)
+context.add_variable(
+    "permissions",
+    cel.prepare(["read", "write", "delete"]),
+)
+result = cel.evaluate(
     'user.role == "admin" && "write" in permissions',
-    {
-        "user": {"role": "admin"},
-        "permissions": ["read", "write", "delete"]
-    }
+    context,
 )  # True
 ```
 
@@ -67,39 +72,50 @@ cel 'age >= 18' --context '{"age": 25}'  # true
 cel --interactive
 ```
 
-### Pre-compilation for Performance
+### Prepared Values and Reusable Contexts
 
-When evaluating the same expression multiple times with different contexts, use `compile()` for better performance:
+Prepare large values outside the hot path. Prepared values are immutable snapshots and can be shared by multiple contexts. Installing a retained prepared value only clones a shared handle:
 
 ```python
 import cel
 
-# Compile once
-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
-result2 = program.execute({"price": 5, "quantity": 3, "threshold": 20})   # False
+data = {
+    "objects": [
+        {"active": i % 2 == 0, "score": i, "profile": {"enabled": True}}
+        for i in range(500)
+    ]
+}
+prepared = cel.prepare(data)
+context = cel.Context()
+program = cel.compile("data.objects[3].profile.enabled")
+
+for _ in range(100_000):
+    context.add_variable("data", prepared)
+    result = program.execute(context)
 ```
 
+Retain prepared objects used for frequent replacement. If a context owns the final reference to a large prepared value, replacing or dropping it may recursively free the value and therefore take time proportional to its size. Returning a large map/list or passing one to a Python callback is also proportional to that result or argument size.
+
 ### Custom Functions
 
 ```python
+import cel
 from cel import Context, evaluate
 
 def calculate_discount(price, rate):
     return price * rate
 
 context = Context()
 context.add_function("calculate_discount", calculate_discount)
-context.add_variable("price", 100)
+context.add_variable("price", cel.prepare(100))
 
 result = evaluate("price - calculate_discount(price, 0.1)", context)  # 90.0
 ```
 
 ### Real-World Example
 
 ```python
+import cel
 from cel import evaluate, Context
 
 # Access control policy
@@ -109,11 +125,9 @@ user.role == "admin" ||
 """
 
 context = Context()
-context.update({
-    "user": {"id": "alice", "role": "user"},
-    "resource": {"owner": "alice"},
-    "current_hour": 14  # 2 PM
-})
+context.add_variable("user", cel.prepare({"id": "alice", "role": "user"}))
+context.add_variable("resource", cel.prepare({"owner": "alice"}))
+context.add_variable("current_hour", cel.prepare(14))
 
 access_granted = evaluate(policy, context)  # True
 ```

diff --git a/docs/contributing.md b/docs/contributing.md
@@ -14,27 +14,27 @@ flowchart LR
     subgraph Python["&nbsp;&nbsp;🐍 Python Layer&nbsp;&nbsp;"]
         API["&nbsp;&nbsp;cel.evaluate()<br/>&nbsp;&nbsp;Context class<br/>&nbsp;&nbsp;CLI tool&nbsp;&nbsp;"]
     end
-    
+
     subgraph Rust["&nbsp;&nbsp;🦀 Rust Wrapper (PyO3)&nbsp;&nbsp;"]
         Wrapper["&nbsp;&nbsp;Type conversion<br/>&nbsp;&nbsp;Error handling<br/>&nbsp;&nbsp;Function calls&nbsp;&nbsp;"]
     end
-    
+
     subgraph CEL["&nbsp;&nbsp;⚡ CEL Engine (upstream)&nbsp;&nbsp;"]
         Engine["&nbsp;&nbsp;CEL parser<br/>&nbsp;&nbsp;Expression evaluation<br/>&nbsp;&nbsp;Built-in functions&nbsp;&nbsp;"]
     end
-    
+
     Python --> Rust
     Rust --> CEL
-    
+
     style Python fill:#e8f4f8,color:#2c3e50
-    style Rust fill:#fdf2e9,color:#2c3e50  
+    style Rust fill:#fdf2e9,color:#2c3e50
     style CEL fill:#f0f9ff,color:#2c3e50
 ```
 
 **Key Files:**
 
 - `src/lib.rs` - Main evaluation engine and type conversions
-- `src/context.rs` - Context management and Python function integration  
+- `src/context.rs` - Context management and Python function integration
 - `python/cel/` - Python module structure and CLI
 - `tests/` - Comprehensive test suite with 300+ tests
 
@@ -104,7 +104,7 @@ uv run pytest
 uv run pytest tests/test_basics.py        # Core functionality
 # → ========================= 25 passed in 0.12s =========================
 
-uv run pytest tests/test_arithmetic.py    # Math operations  
+uv run pytest tests/test_arithmetic.py    # Math operations
 # → ========================= 42 passed in 0.18s =========================
 
 uv run pytest tests/test_context.py       # Variable handling
@@ -142,20 +142,49 @@ We use a proactive detection system to monitor for upstream improvements:
 2. **Positive Detection**: Expected failures (`@pytest.mark.xfail`) ready to pass when features arrive
 
 ```python
+import cel
+Context = cel.Context
+
+
+def add_variables(context, values):
+    for name, value in values.items():
+        if callable(value):
+            context.add_function(name, value)
+        else:
+            context.add_variable(name, cel.prepare(value))
+    return context
+
+
+def make_context(values=None):
+    context = cel.Context()
+    if values:
+        add_variables(context, values)
+    return context
+
+
+def as_context(value=None):
+    if isinstance(value, cel.Context):
+        return value
+    return make_context(value)
+
+
+def evaluate(expression, context=None):
+    return cel.evaluate(expression, as_context(context))
+
 import pytest
 import cel
 
-# Example: Detecting when string functions become available  
+# Example: Detecting when string functions become available
 def test_lower_ascii_not_implemented(self):
     """When this test starts failing, lowerAscii() has been implemented."""
     with pytest.raises(RuntimeError, match="Undefined variable or function.*lowerAscii"):
-        cel.evaluate('"HELLO".lowerAscii()')
+        evaluate('"HELLO".lowerAscii()', cel.Context())
         # → RuntimeError: Undefined variable or function 'lowerAscii'
 
 @pytest.mark.xfail(reason="String utilities not implemented in cel v0.11.1", strict=False)
 def test_lower_ascii_expected_behavior(self):
     """This test will pass when upstream implements lowerAscii()."""
-    result = cel.evaluate('"HELLO".lowerAscii()')
+    result = evaluate('"HELLO".lowerAscii()', cel.Context())
     # → "hello" (when implemented)
     assert result == "hello"
 ```
@@ -189,7 +218,7 @@ uv run pytest tests/test_upstream_improvements.py -v --tb=no | grep -E "(XPASS|F
 
 **Interpreting Results:**
 - **PASSED** = Limitation still exists (expected)
-- **XFAIL** = Expected failure (ready for when feature arrives)  
+- **XFAIL** = Expected failure (ready for when feature arrives)
 - **XPASS** = 🎉 Feature now available! (remove xfail marker)
 
 ### Dependency Update Process
@@ -199,7 +228,7 @@ When updating the `cel` crate dependency:
 1. **Run detection tests first** to identify new capabilities
 2. **Update Cargo.toml** with new version
 3. **Fix compilation issues** (API changes)
-4. **Remove xfail markers** for now-passing tests  
+4. **Remove xfail markers** for now-passing tests
 5. **Update documentation** to reflect new features
 6. **Test thoroughly** to ensure no regressions
 
@@ -226,22 +255,22 @@ from typing import Optional, Union, Dict, Any, Callable
 import cel
 
 # Type hints for public APIs
-def evaluate(expression: str, context: Optional[Union[Dict[str, Any], 'Context']] = None) -> Any:
-    """Evaluate a CEL expression with optional context."""
+def evaluate(expression: str, context: Context) -> Any:
+    """Evaluate a CEL expression with a required Context."""
     pass
 
-# Comprehensive docstrings  
+# Comprehensive docstrings
 def add_function(self, name: str, func: Callable) -> None:
     """Add a Python function to the CEL evaluation context.
-    
+
     Args:
         name: Function name to use in CEL expressions
         func: Python callable to invoke
-        
+
     Example:
         >>> context = cel.Context()
         >>> context.add_function("double", lambda x: x * 2)
-        >>> cel.evaluate("double(21)", context)
+        >>> evaluate("double(21)", context)
         42
     """
 ```
@@ -291,7 +320,7 @@ uv run pytest tests/test_failing.py -v -s
 uv run pytest tests/test_file.py::test_name --pdb
 # → ========================= test session starts =========================
 # → >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>> PDB set_trace >>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
-# → (Pdb) 
+# → (Pdb)
 ```
 
 **Type Conversion Issues:**