fix: pr comments and add simpler example

Author: jakelorocco

cli/fix/__init__.py

@@ -1,13 +1,13 @@
 """CLI for fixing async calls after top-level ainstruct, aquery, and aact contract change.."""
 
-from enum import Enum
+from enum import StrEnum
 
 import typer
 
 fix_app = typer.Typer(name="fix", help="Fix code for API changes.")
 
 
-class FixMode(str, Enum):
+class FixMode(StrEnum):
     ADD_AWAIT_RESULT = "add-await-result"
     ADD_STREAM_LOOP = "add-stream-loop"
 

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

@@ -627,12 +627,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
 
 

pyproject.toml

@@ -315,7 +315,7 @@ disable_error_code = [
 # -----------------------------
 
 [tool.codespell]
-ignore-words-list = 'mellea,hashi,noo,Asai,asai,nd,mot,rouge,Rouge,Strat,Wight,Aer,aer,preemptable'
+ignore-words-list = 'mellea,hashi,noo,Asai,asai,nd,mot,rouge,Rouge,Strat,strat,Wight,Aer,aer,preemptable'
 check-filenames = true
 check-hidden = false
 regex = "(?<![a-z])[a-z'`]+|[A-Z][a-z'`]*|[a-z]+'[a-z]*|[a-z]+(?=[_-])|[a-z]+(?=[A-Z])|\\d+"

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)