Allow FlowOptions to be passed directly to the __call__ function for interactive work (#124)

Signed-off-by: Pascal Tomecek <[email protected]>

Author: ptomecek

ccflow/callable.py

@@ -194,12 +194,17 @@ def get_evaluator(self, model: CallableModelType) -> "EvaluatorBase":
 
     def __call__(self, fn):
         # Used for building a graph of model evaluation contexts without evaluating
-        def get_evaluation_context(model: CallableModelType, context: ContextType, as_dict: bool = False):
+        def get_evaluation_context(model: CallableModelType, context: ContextType, as_dict: bool = False, *, _options: Optional[FlowOptions] = None):
             # Create the evaluation context.
             # Record the options that are used, in case the evaluators want to use it,
             # but exclude the evaluator itself to avoid potential circular dependencies
             # or other difficulties with serialization/caching of the options
-            options = FlowOptionsOverride.get_options(model, self)
+            if _options:
+                if not isinstance(_options, FlowOptions):
+                    _options = FlowOptions.model_validate(_options)
+                options = _options
+            else:
+                options = FlowOptionsOverride.get_options(model, self)
             evaluator = self._get_evaluator_from_options(options)
             options_dict = options.model_dump(mode="python", exclude={"evaluator"}, exclude_unset=True)
             evaluation_context = ModelEvaluationContext(model=model, context=context, fn=fn.__name__, options=options_dict)
@@ -209,7 +214,7 @@ def get_evaluation_context(model: CallableModelType, context: ContextType, as_di
                 return ModelEvaluationContext(model=evaluator, context=evaluation_context)
 
         # The decorator implementation
-        def wrapper(model, context=Signature.empty, **kwargs):
+        def wrapper(model, context=Signature.empty, *, _options: Optional[FlowOptions] = None, **kwargs):
             if not isinstance(model, CallableModel):
                 raise TypeError("Can only decorate methods on CallableModels with the flow decorator")
             if not isclass(model.context_type) or not issubclass(model.context_type, ContextBase):
@@ -239,7 +244,7 @@ def wrapper(model, context=Signature.empty, **kwargs):
                 # In this case, we don't apply the decorator again, we just call the function on the model and context.
                 return fn(model, context)
 
-            evaluation_context = get_evaluation_context(model, context, as_dict=True)
+            evaluation_context = get_evaluation_context(model, context, as_dict=True, _options=_options)
             # Here we call the evaluator directly on the context, instead of calling evaluation_context()
             # to eliminate one level in the call stack when things go wrong/when debugging.
             result = evaluation_context["model"](evaluation_context["context"])

ccflow/tests/test_decorator.py

@@ -3,7 +3,6 @@
 from unittest import TestCase
 
 from ccflow import CallableModel, DateContext, EvaluatorBase, Flow, FlowOptions, FlowOptionsOverride, GenericResult, ModelEvaluationContext
-from ccflow.evaluators import MemoryCacheEvaluator
 
 
 class MyModel(CallableModel):
@@ -56,6 +55,13 @@ def __call__(self, context: DateContext = "0d") -> GenericResult:
         return context.date
 
 
+class DummyEvaluator(EvaluatorBase):
+    return_value: GenericResult = GenericResult(value=date(2020, 1, 1))
+
+    def __call__(self, context: ModelEvaluationContext):
+        return self.return_value
+
+
 class TestModelEvaluationContext(TestCase):
     def test_model_evaluation_context(self):
         model = DefaultModel()
@@ -99,25 +105,33 @@ def test_evaluation_context_options(self):
         model = DefaultModel()
         context = DateContext(date=date.today())
         options = FlowOptions(log_level=0)
+
+        evaluation_context = model.__call__.get_evaluation_context(model, context, _options=options)
+        self.assertEqual(evaluation_context.model.log_level, 0)
+
+        evaluation_context = model.__call__.get_evaluation_context(model, context, _options=dict(log_level=0))
+        self.assertEqual(evaluation_context.model.log_level, 0)
+
         with FlowOptionsOverride(options=options):
             self.assertEqual(model.__call__.get_options(model), options)
             evaluation_context = model.__call__.get_evaluation_context(model, context)
             self.assertEqual(evaluation_context.model.log_level, 0)
 
+            # Make sure passing _options takes precedence over the FlowOptionsOverride context
+            evaluation_context = model.__call__.get_evaluation_context(model, context, _options=dict(log_level=1))
+            self.assertEqual(evaluation_context.model.log_level, 1)
+
     def test_new_evaluator(self):
-        """Test that we can use the decorator to make an evaluation with a new evaluator."""
+        """Test that we can call the model easily with a new evaluator."""
         model = MyModel()
-        new_evaluator = MemoryCacheEvaluator()
-        wrapped_call = Flow.call(evaluator=new_evaluator)(MyModel.__call__)
-        out_evaluator = wrapped_call.get_evaluator(model)
-        self.assertEqual(out_evaluator, new_evaluator)
-
+        new_evaluator = DummyEvaluator()
         context = DateContext(date=date.today())
-        self.assertEqual(wrapped_call(model, context), model(context))
+        self.assertEqual(model(context), GenericResult(value=context.date))
+        self.assertEqual(model(context, _options=dict(evaluator=new_evaluator)), new_evaluator.return_value)
 
         # Now test it on foo
-        wrapped_foo = Flow.call(evaluator=new_evaluator)(MyModel.foo)
-        self.assertEqual(wrapped_foo(model, context), model.foo(context))
+        self.assertEqual(model(context), GenericResult(value=context.date))
+        self.assertEqual(model.foo(context, _options=dict(evaluator=new_evaluator)), new_evaluator.return_value)
 
     def test_coercion(self):
         model = MyModel()

docs/wiki/Workflows.md

@@ -344,12 +344,29 @@ except TypeError as e:
 
 Behind the `@Flow.call` decorator is where all the magic lives, including advanced features which are not yet well tested or have not yet been implemented. However, we walk through some of the more basic functionality to give an idea of how it can be used.
 
-The behavior of the `@Flow.call` decorator can be controlled in two ways:
+The behavior of the `@Flow.call` decorator can be controlled in several ways:
 
-- by using the FlowOptionsOverride context (which allows you to scope changes to specific models, specific model types or all models)
 - by passing arguments to it when defining the CallableModel to customize model-specific behavior
+- by using the FlowOptionsOverride context (which allows you to scope changes to specific models, specific model types or all models)
+- by setting `options` in the `meta` attribute of the CallableModel
+- by passing `_options` directly to the `__call__` method
+
+An example of the first one (model-specific options) is to disable validation of the result type on a particular model
+
+```python
+from ccflow import CallableModel, Flow, GenericResult, GenericContext
+
+class NoValidationModel(CallableModel):
+    @Flow.call(validate_result=False)
+    def __call__(self, context: GenericContext[str]) -> GenericResult[float]:
+        return "foo"
+
+model = NoValidationModel()
+print(model("foo"))
+#> foo
+```
 
-An example of the former is to change the log level for all model evaluations:
+An example of the latter three is to change the log level for all model evaluations (including sub-models):
 
 ```python
 import logging
@@ -369,19 +386,26 @@ with FlowOptionsOverride(options={"log_level": logging.WARN}):
 #> GenericResult[list[Union[int, str]]](value=[1, 2, 'Fizz', 4, 'Buzz', 'Fizz', 7, 8, 'Fizz', 'Buzz', 11, 'Fizz', 13, 14, 'FizzBuzz'])
 ```
 
-An example of the latter (model-specific options) is to disable validation of the result type on a particular model
+If there is only a need to set the options for a specific model (and not any sub-models that it may call), then the `meta` attribute or passing `_options` to the `__call__` method are better options.
+Setting `meta.options` is particularly useful when the model is being loaded from a configuration file, though it can be done interactively as well to persist the options with the model instance.
 
 ```python
-from ccflow import CallableModel, Flow, GenericResult, GenericContext
+model = FizzBuzzModel()
+model.meta.options = {"log_level": logging.WARN}
+_ = model(15)
+#[FizzBuzzModel]: Start evaluation of __call__ on GenericContext[int](value=15).
+#[FizzBuzzModel]: FizzBuzzModel(meta=MetaData(name=''), fizz='Fizz', buzz='Buzz')
+#[FizzBuzzModel]: End evaluation of __call__ on GenericContext[int](value=15) (time elapsed: 0:00:00.000074).
+```
 
-class NoValidationModel(CallableModel):
-    @Flow.call(validate_result=False)
-    def __call__(self, context: GenericContext[str]) -> GenericResult[float]:
-        return "foo"
+Most convenient for interactive work is to pass the options to the `__call__` method directly.
 
-model = NoValidationModel()
-print(model("foo"))
-#> foo
+```python
+model = FizzBuzzModel()
+_ = model(15, _options={"log_level": logging.WARN})
+#[FizzBuzzModel]: Start evaluation of __call__ on GenericContext[int](value=15).
+#[FizzBuzzModel]: FizzBuzzModel(meta=MetaData(name=''), fizz='Fizz', buzz='Buzz')
+#[FizzBuzzModel]: End evaluation of __call__ on GenericContext[int](value=15) (time elapsed: 0:00:00.000072).
 ```
 
 To see a list of all the available options, you can look at the schema definition of the FlowOptions class: