fix: pr comments and add simpler example

Author: jakelorocco

docs/examples/async/async-simple.py

@@ -0,0 +1,30 @@
+# pytest: ollama, qualitative, llm
+
+"""Example of how to use async with lazy compute and streaming."""
+
+import asyncio
+
+from mellea.backends.model_options import ModelOption
+from mellea.core.base import ModelOutputThunk
+from mellea.stdlib.session import start_session
+
+# Create a regular session. Works with functional interface as well.
+m = start_session()
+
+
+async def main():
+    response: ModelOutputThunk[str] = await m.ainstruct(
+        "Say 'We're Streaming Now!' and then add a fun fact!",
+        strategy=None,  # Cannot perform lazy compute / top level streaming if using a strategy.
+        model_options={
+            ModelOption.STREAM: True  # Set streaming to True for top level streaming.
+        },
+        # await_result=True  # Set await_result to True to prevent lazy compute / top-level streaming.
+    )
+
+    # We can stream the response as it happens.
+    while not response.is_computed():
+        print(await response.astream())
+
+
+asyncio.run(main())

mellea/core/base.py

@@ -594,12 +594,12 @@ def __init__(self, thunk: ModelOutputThunk[S]) -> None:
             raise ValueError("ComputedModelOutputThunk requires a non-None value.")
 
     async def avalue(self) -> str:
-        """Return the value of the thunk. Use .value() instead."""
+        """Return the value of the thunk. Use .value instead."""
         assert self.value is not None, "ComputedModelOutputThunk value cannot be None"
         return self.value
 
     async def astream(self) -> str:
-        """Cannot astream from ComputedModelOutputThunks. Use .value() instead."""
+        """Cannot astream from ComputedModelOutputThunks. Use .value instead."""
         raise RuntimeError(
             "Cannot stream from a ComputedModelOutputThunk. "
             "This thunk is already fully computed and does not support streaming."

mellea/stdlib/functional.py

@@ -113,6 +113,14 @@ def act(
         )  # type: ignore[call-overload]
     )
 
+    computed = False
+    if isinstance(out, SamplingResult):
+        computed = out.result.is_computed()
+    else:
+        mot, _ = out
+        computed = mot.is_computed()
+    assert computed, "Synchronous functions must return a computed result."
+
     return out
 
 

test/core/test_streaming_sync_functions.py

@@ -107,7 +107,7 @@ def test_await_result_false_with_sampling_still_computes():
 
 
 def test_default_behavior_unchanged():
-    """Test that default behavior (await_result=False) returns uncomputed thunk."""
+    """Test that sync functions always return computed thunks, even without explicit await_result."""
     with start_session() as session:
         # Default behavior should return uncomputed thunk for streaming
         result = session.instruct("Say 'hello'", strategy=None)