langwatch-scenario 0.3.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

langwatch_scenario-0.6.0.dist-info/METADATA

@@ -0,0 +1,385 @@
+Metadata-Version: 2.4
+Name: langwatch-scenario
+Version: 0.6.0
+Summary: The end-to-end agent testing library
+Author-email: LangWatch Team <support@langwatch.ai>
+License: MIT
+Project-URL: Homepage, https://github.com/langwatch/scenario
+Project-URL: Bug Tracker, https://github.com/langwatch/scenario/issues
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pytest>=8.1.1
+Requires-Dist: litellm>=1.49.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: termcolor>=2.4.0
+Requires-Dist: pydantic>=2.7.0
+Requires-Dist: joblib>=1.4.2
+Requires-Dist: wrapt>=1.17.2
+Requires-Dist: pytest-asyncio>=0.26.0
+Requires-Dist: rich<15.0.0,>=13.3.3
+Requires-Dist: pksuid>=1.1.2
+Requires-Dist: pdoc3>=0.11.6
+Requires-Dist: ag-ui-protocol>=0.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: rx>=3.2.0
+Requires-Dist: respx>=0.22.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: commitizen; extra == "dev"
+Requires-Dist: pyright; extra == "dev"
+Requires-Dist: pydantic-ai; extra == "dev"
+Requires-Dist: function-schema; extra == "dev"
+
+![scenario](https://github.com/langwatch/scenario/raw/main/assets/scenario-wide.webp)
+
+<div align="center">
+<!-- Discord, PyPI, Docs, etc links -->
+</div>
+
+# Scenario
+
+Scenario is an Agent Testing Framework based on simulations, it can:
+
+- Test real agent behavior by simulating users in different scenarios and edge cases
+- Evaluate and judge at any point of the conversation, powerful multi-turn control
+- Combine it with any LLM eval framework or custom evals, agnostic by design
+- Integrate your Agent by implementing just one `call()` method
+- Available in Python, TypeScript and Go
+
+[📺 Video Tutorial](https://www.youtube.com/watch?v=f8NLpkY0Av4)
+
+### In other languages
+
+- [Scenario TypeScript](https://github.com/langwatch/scenario-ts/)
+- [Scenario Go](https://github.com/langwatch/scenario-go/)
+
+## Example
+
+This is how a simple simulation with tool check looks like with Scenario:
+
+```python
+# Define any custom assertions
+def check_for_weather_tool_call(state: scenario.ScenarioState):
+    assert state.has_tool_call("get_current_weather")
+
+result = await scenario.run(
+    name="checking the weather",
+
+    # Define the prompt to guide the simulation
+    description="""
+        The user is planning a boat trip from Barcelona to Rome,
+        and is wondering what the weather will be like.
+    """,
+
+    # Define the agents that will play this simulation
+    agents=[
+        WeatherAgent(),
+        scenario.UserSimulatorAgent(model="openai/gpt-4.1-mini"),
+    ],
+
+    # (Optional) Control the simulation
+    script=[
+        scenario.user(), # let the user simulator generate a user message
+        scenario.agent(), # agent responds
+        check_for_weather_tool_call, # check for tool call after the first agent response
+        scenario.succeed(), # simulation ends successfully
+    ],
+)
+
+assert result.success
+```
+
+> [!NOTE]
+> Check out full examples in the [examples folder](./examples/).
+
+## Getting Started
+
+Install pytest and scenario:
+
+```bash
+pip install pytest langwatch-scenario
+```
+
+Now create your first scenario and save it as `tests/test_vegetarian_recipe_agent.py`, copy the full working example below:
+
+```python
+import pytest
+import scenario
+import litellm
+
+scenario.configure(default_model="openai/gpt-4.1-mini")
+
+
+@pytest.mark.agent_test
+@pytest.mark.asyncio
+async def test_vegetarian_recipe_agent():
+    class Agent(scenario.AgentAdapter):
+        async def call(self, input: scenario.AgentInput) -> scenario.AgentReturnTypes:
+            return vegetarian_recipe_agent(input.messages)
+
+    # Run a simulation scenario
+    result = await scenario.run(
+        name="dinner idea",
+        description="""
+            It's saturday evening, the user is very hungry and tired,
+            but have no money to order out, so they are looking for a recipe.
+        """,
+        agents=[
+            Agent(),
+            scenario.UserSimulatorAgent(),
+            scenario.JudgeAgent(
+                criteria=[
+                    "Agent should not ask more than two follow-up questions",
+                    "Agent should generate a recipe",
+                    "Recipe should include a list of ingredients",
+                    "Recipe should include step-by-step cooking instructions",
+                    "Recipe should be vegetarian and not include any sort of meat",
+                ]
+            ),
+        ],
+    )
+
+    # Assert for pytest to know whether the test passed
+    assert result.success
+
+
+# Example agent implementation
+import litellm
+
+
+@scenario.cache()
+def vegetarian_recipe_agent(messages) -> scenario.AgentReturnTypes:
+    response = litellm.completion(
+        model="openai/gpt-4.1-mini",
+        messages=[
+            {
+                "role": "system",
+                "content": """
+                    You are a vegetarian recipe agent.
+                    Given the user request, ask AT MOST ONE follow-up question,
+                    then provide a complete recipe. Keep your responses concise and focused.
+                """,
+            },
+            *messages,
+        ],
+    )
+
+    return response.choices[0].message  # type: ignore
+```
+
+Create a `.env` file and put your OpenAI API key in it:
+
+```bash
+OPENAI_API_KEY=<your-api-key>
+```
+
+Now run it with pytest:
+
+```bash
+pytest -s tests/test_vegetarian_recipe_agent.py
+```
+
+This is how it will look like:
+
+[![asciicast](./assets/ascii-cinema.svg)](https://asciinema.org/a/nvO5GWGzqKTTCd8gtNSezQw11)
+
+You can find the same code example in [examples/test_vegetarian_recipe_agent.py](examples/test_vegetarian_recipe_agent.py).
+
+## Simulation on Autopilot
+
+By providing a User Simulator Agent and a description of the Scenario without a script, the simulated user will automatically generate messages to the agent until the scenario is successful or the maximum number of turns is reached.
+
+You can then use a Judge Agent to evaluate the scenario in real-time given certain criteria, at every turn, the Judge Agent will decide if it should let the simulation proceed or end it with a verdict.
+
+For example, here is a scenario that tests a vibe coding assistant:
+
+```python
+result = await scenario.run(
+    name="dog walking startup landing page",
+    description="""
+        the user wants to create a new landing page for their dog walking startup
+
+        send the first message to generate the landing page, then a single follow up request to extend it, then give your final verdict
+    """,
+    agents=[
+        LovableAgentAdapter(template_path=template_path),
+        scenario.UserSimulatorAgent(),
+        scenario.JudgeAgent(
+            criteria=[
+                "agent reads the files before go and making changes",
+                "agent modified the index.css file, not only the Index.tsx file",
+                "agent created a comprehensive landing page",
+                "agent extended the landing page with a new section",
+                "agent should NOT say it can't read the file",
+                "agent should NOT produce incomplete code or be too lazy to finish",
+            ],
+        ),
+    ],
+    max_turns=5, # optional
+)
+```
+
+Check out the fully working Lovable Clone example in [examples/test_lovable_clone.py](examples/test_lovable_clone.py).
+
+You can also combine it with a partial script too! By for example controlling only the beginning of the conversation, and let the rest proceed on autopilot, see the next section.
+
+## Full Control of the Conversation
+
+You can specify a script for guiding the scenario by passing a list of steps to the `script` field, those steps are simply arbitrary functions that take the current state of the scenario as an argument, so you can do things like:
+
+- Control what the user says, or let it be generated automatically
+- Control what the agent says, or let it be generated automatically
+- Add custom assertions, for example making sure a tool was called
+- Add a custom evaluation, from an external library
+- Let the simulation proceed for a certain number of turns, and evaluate at each new turn
+- Trigger the judge agent to decide on a verdict
+- Add arbitrary messages like mock tool calls in the middle of the conversation
+
+Everything is possible, using the same simple structure:
+
+```python
+@pytest.mark.agent_test
+@pytest.mark.asyncio
+async def test_early_assumption_bias():
+    result = await scenario.run(
+        name="early assumption bias",
+        description="""
+            The agent makes false assumption that the user is talking about an ATM bank, and user corrects it that they actually mean river banks
+        """,
+        agents=[
+            Agent(),
+            scenario.UserSimulatorAgent(),
+            scenario.JudgeAgent(
+                criteria=[
+                    "user should get good recommendations on river crossing",
+                    "agent should NOT keep following up about ATM recommendation after user has corrected them that they are actually just hiking",
+                ],
+            ),
+        ],
+        max_turns=10,
+        script=[
+            # Define hardcoded messages
+            scenario.agent("Hello, how can I help you today?"),
+            scenario.user("how do I safely approach a bank?"),
+
+            # Or let it be generated automatically
+            scenario.agent(),
+
+            # Add custom assertions, for example making sure a tool was called
+            check_if_tool_was_called,
+
+            # Generate a user follow-up message
+            scenario.user(),
+
+            # Let the simulation proceed for 2 more turns, print at every turn
+            scenario.proceed(
+                turns=2,
+                on_turn=lambda state: print(f"Turn {state.current_turn}: {state.messages}"),
+            ),
+
+            # Time to make a judgment call
+            scenario.judge(),
+        ],
+    )
+
+    assert result.success
+```
+
+## Debug mode
+
+You can enable debug mode by setting the `debug` field to `True` in the `Scenario.configure` method or in the specific scenario you are running, or by passing the `--debug` flag to pytest.
+
+Debug mode allows you to see the messages in slow motion step by step, and intervene with your own inputs to debug your agent from the middle of the conversation.
+
+```python
+scenario.configure(default_model="openai/gpt-4.1-mini", debug=True)
+```
+
+or
+
+```bash
+pytest -s tests/test_vegetarian_recipe_agent.py --debug
+```
+
+## Cache
+
+Each time the scenario runs, the testing agent might chose a different input to start, this is good to make sure it covers the variance of real users as well, however we understand that the non-deterministic nature of it might make it less repeatable, costly and harder to debug. To solve for it, you can use the `cache_key` field in the `Scenario.configure` method or in the specific scenario you are running, this will make the testing agent give the same input for given the same scenario:
+
+```python
+scenario.configure(default_model="openai/gpt-4.1-mini", cache_key="42")
+```
+
+To bust the cache, you can simply pass a different `cache_key`, disable it, or delete the cache files located at `~/.scenario/cache`.
+
+To go a step further and fully cache the test end-to-end, you can also wrap the LLM calls or any other non-deterministic functions in your application side with the `@scenario.cache` decorator:
+
+```python
+# Inside your actual agent implementation
+class MyAgent:
+    @scenario.cache()
+    def invoke(self, message, context):
+        return client.chat.completions.create(
+            # ...
+        )
+```
+
+This will cache any function call you decorate when running the tests and make them repeatable, hashed by the function arguments, the scenario being executed, and the `cache_key` you provided. You can exclude arguments that should not be hashed for the cache key by naming them in the `ignore` argument.
+
+## Disable Output
+
+You can remove the `-s` flag from pytest to hide the output during test, which will only show up if the test fails. Alternatively, you can set `verbose=False` in the `Scenario.configure` method or in the specific scenario you are running.
+
+## Running in parallel
+
+As the number of your scenarios grows, you might want to run them in parallel to speed up your whole test suite. We suggest you to use the [pytest-asyncio-concurrent](https://pypi.org/project/pytest-asyncio-concurrent/) plugin to do so.
+
+Simply install the plugin from the link above, then replace the `@pytest.mark.asyncio` annotation in the tests with `@pytest.mark.asyncio_concurrent`, adding a group name to it to mark the group of scenarions that should be run in parallel together, e.g.:
+
+```python
+@pytest.mark.agent_test
+@pytest.mark.asyncio_concurrent(group="vegetarian_recipe_agent")
+async def test_vegetarian_recipe_agent():
+    # ...
+
+@pytest.mark.agent_test
+@pytest.mark.asyncio_concurrent(group="vegetarian_recipe_agent")
+async def test_user_is_very_hungry():
+    # ...
+```
+
+Those two scenarios should now run in parallel.
+
+## Events System
+
+Scenario automatically publishes events during execution for monitoring and observability. You can enable event reporting by setting environment variables:
+
+```bash
+# Enable automatic event reporting
+export LANGWATCH_ENDPOINT="https://api.langwatch.ai"
+export LANGWATCH_API_KEY="your-api-key"
+```
+
+With these variables set, Scenario will automatically:
+
+- Publish events when scenarios start, finish, and when messages are added
+- Handle retries and error handling automatically
+- Process events asynchronously without blocking your tests
+
+The events include timing information, conversation history, and success/failure metrics for analysis.
+
+For advanced customization, see the event classes in the codebase for detailed documentation.
+
+## License
+
+MIT License

langwatch_scenario-0.6.0.dist-info/RECORD

@@ -0,0 +1,27 @@
+scenario/__init__.py,sha256=UJ5l-sG4TMG0wR8Ba-dxdDW36m3apTvawP-lNvk7Jm0,4293
+scenario/_error_messages.py,sha256=6lEx3jBGMbPx0kG0eX5zoZE-ENVM3O_ZkIbVMlnidYs,3892
+scenario/agent_adapter.py,sha256=PoY2KQqYuqzIIb3-nhIU-MPXwHJc1vmwdweMy7ut-hk,4255
+scenario/cache.py,sha256=J6s6Sia_Ce6TrnsInlhfxm6SF8tygo3sH-_cQCRX1WA,6213
+scenario/config.py,sha256=xhUuXH-sThwPTmJNSuajKxX-WC_tcFwJ1jZc119DswA,6093
+scenario/judge_agent.py,sha256=9CCO699qoWqXvWdQ73Yc3dqPOwaJdJ-zqxVaLaKi_cA,16161
+scenario/pytest_plugin.py,sha256=f2ETBpATz80k7K87M6046ZIFiQpHEvDN7dxakd3y2wk,11321
+scenario/scenario_executor.py,sha256=nkSIuIlwPHfr6pueSBbARrgiqPtW0SxajV3PFypAnJ4,34508
+scenario/scenario_state.py,sha256=dQDjazem-dn1c5mw6TwngEu6Tv_cHwEzemepsPBy2f0,7039
+scenario/script.py,sha256=A0N5pP0l4FFn1xdKc78U_wkwWhEWH3EFeU_LRDtNyEI,12241
+scenario/types.py,sha256=BhXcTEMGyGg_1QysN-GXVjm8DP2VH3UEzj_qvoglp2k,9466
+scenario/user_simulator_agent.py,sha256=fhwi8W44s343BGrjJXSJw960wcK7MgwTg-epxR1bqHo,9088
+scenario/_utils/__init__.py,sha256=wNX9hU8vzYlyLDwjkt7JUW3IPo2DhME6UIt_zvLM3B0,1000
+scenario/_utils/ids.py,sha256=K1iPuJgPh3gX9HCrDZGqK5lDgdwZXfOBF1YXVOWNHRg,1843
+scenario/_utils/message_conversion.py,sha256=AM9DLyWpy97CrAH8RmId9Mv2rmLquQhFoUpRyp-jVeY,3622
+scenario/_utils/utils.py,sha256=msQgUWaLh3U9jIIHmxkEbOaklga63AF0KJzsaKa_mZc,14008
+scenario/events/__init__.py,sha256=_autF1cMZYpNXE-kJNvvRb-H_hYqy4gOSSp2fT3Wi9k,1533
+scenario/events/event_bus.py,sha256=MThIMIaI2nj2CoegZazTNxeHbtl4_M7bW3vEAHz6R8g,7102
+scenario/events/event_reporter.py,sha256=cMh_5jA5hG3Q9IsoAgPJhxnIVs_M1Q0e2lgLTEK4oPc,3100
+scenario/events/events.py,sha256=jPXylwiADb0Bdk7u1YkAaU_jLebH7NW8J7SZI9JDTxw,6750
+scenario/events/messages.py,sha256=1QAkwDExdF6AHgXdEFhHwmCv3Mxu3j0AXIptMekc_bg,3299
+scenario/events/utils.py,sha256=yrTUTByeb0eAAQniQH7EyKs-usgGti8f17IemUyBZBw,3357
+langwatch_scenario-0.6.0.dist-info/METADATA,sha256=IvD9on4tP57ldmizFzfGQBtiCT6Z7yoz0trlCSPSW9M,14227
+langwatch_scenario-0.6.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+langwatch_scenario-0.6.0.dist-info/entry_points.txt,sha256=WlEnJ_gku0i18bIa3DSuGqXRX-QDQLe_s0YmRzK45TI,45
+langwatch_scenario-0.6.0.dist-info/top_level.txt,sha256=45Mn28aedJsetnBMB5xSmrJ-yo701QLH89Zlz4r1clE,9
+langwatch_scenario-0.6.0.dist-info/RECORD,,

scenario/__init__.py

@@ -1,36 +1,147 @@
 """
-Scenario: A testing library for conversational agents.
+Scenario: Agent Testing Framework through Simulation Testing
+
+Scenario is a comprehensive testing framework for AI agents that uses simulation testing
+to validate agent behavior through realistic conversations. It enables testing of both
+happy paths and edge cases by simulating user interactions and evaluating agent responses
+against configurable success criteria.
+
+Key Features:
+
+- End-to-end conversation testing with specified scenarios
+
+- Flexible control from fully scripted to completely automated simulations
+
+- Multi-turn evaluation designed for complex conversational agents
+
+- Works with any testing framework (pytest, unittest, etc.)
+
+- Framework-agnostic integration with any LLM or agent architecture
+
+- Built-in caching for deterministic and faster test execution
+
+Basic Usage:
+
+    import scenario
+
+    # Configure global settings
+    scenario.configure(default_model="openai/gpt-4.1-mini")
+
+    # Create your agent adapter
+    class MyAgent(scenario.AgentAdapter):
+        async def call(self, input: scenario.AgentInput) -> scenario.AgentReturnTypes:
+            return my_agent_function(input.last_new_user_message_str())
+
+    # Run a scenario test
+    result = await scenario.run(
+        name="customer service test",
+        description="Customer asks about billing, agent should help politely",
+        agents=[
+            MyAgent(),
+            scenario.UserSimulatorAgent(),
+            scenario.JudgeAgent(criteria=[
+                "Agent is polite and professional",
+                "Agent addresses the billing question",
+                "Agent provides clear next steps"
+            ])
+        ]
+    )
+
+    assert result.success
+
+Advanced Usage:
+
+    # Script-controlled scenario with custom evaluations
+    def check_tool_usage(state: scenario.ScenarioState) -> None:
+        assert state.has_tool_call("get_customer_info")
+
+    result = await scenario.run(
+        name="scripted interaction",
+        description="Test specific conversation flow",
+        agents=[
+            MyAgent(),
+            scenario.UserSimulatorAgent(),
+            scenario.JudgeAgent(criteria=["Agent provides helpful response"])
+        ],
+        script=[
+            scenario.user("I have a billing question"),
+            scenario.agent(),
+            check_tool_usage,  # Custom assertion
+            scenario.proceed(turns=2),  # Let it continue automatically
+            scenario.succeed("All requirements met")
+        ]
+    )
+
+Integration with Testing Frameworks:
+
+    import pytest
+
+    @pytest.mark.agent_test
+    @pytest.mark.asyncio
+    async def test_weather_agent():
+        result = await scenario.run(
+            name="weather query",
+            description="User asks about weather in a specific city",
+            agents=[
+                WeatherAgent(),
+                scenario.UserSimulatorAgent(),
+                scenario.JudgeAgent(criteria=["Provides accurate weather information"])
+            ]
+        )
+        assert result.success
+
+For more examples and detailed documentation, visit: https://github.com/langwatch/scenario
 """
 
 # First import non-dependent modules
-from .types import ScenarioResult, AgentInput, ScenarioAgentRole, AgentReturnTypes
+from .types import ScenarioResult, AgentInput, AgentRole, AgentReturnTypes
 from .config import ScenarioConfig
 
 # Then import modules with dependencies
-from .scenario_agent_adapter import ScenarioAgentAdapter
-from .testing_agent import TestingAgent
-from .scenario import Scenario
+from .scenario_executor import ScenarioExecutor
+from .scenario_state import ScenarioState
+from .agent_adapter import AgentAdapter
+from .judge_agent import JudgeAgent
+from .user_simulator_agent import UserSimulatorAgent
 from .cache import scenario_cache
+from .script import message, user, agent, judge, proceed, succeed, fail
 
 # Import pytest plugin components
-from .pytest_plugin import pytest_configure, scenario_reporter
+# from .pytest_plugin import pytest_configure, scenario_reporter
+
+run = ScenarioExecutor.run
+
+configure = ScenarioConfig.configure
+
+default_config = ScenarioConfig.default_config
+
+cache = scenario_cache
 
 __all__ = [
+    # Functions
+    "run",
+    "configure",
+    "default_config",
+    "cache",
+    # Script
+    "message",
+    "proceed",
+    "succeed",
+    "fail",
+    "judge",
+    "agent",
+    "user",
     # Types
     "ScenarioResult",
     "AgentInput",
-    "ScenarioAgentRole",
+    "AgentRole",
     "ScenarioConfig",
     "AgentReturnTypes",
-
     # Classes
-    "Scenario",
-    "ScenarioAgentAdapter",
-    "TestingAgent",
-
-    # Plugins
-    "pytest_configure",
-    "scenario_reporter",
-    "scenario_cache",
+    "ScenarioExecutor",
+    "ScenarioState",
+    "AgentAdapter",
+    "UserSimulatorAgent",
+    "JudgeAgent",
 ]
-__version__ = "0.1.0"
+__version__ = "0.1.0"

scenario/{error_messages.py → _error_messages.py}

@@ -3,48 +3,18 @@ from typing import Any
 import termcolor
 
 
-default_config_error_message = f"""
-
- {termcolor.colored("->", "cyan")} Please set a default config with at least a testing_agent model for running your scenarios at the top of your test file, for example:
-
-    from scenario import Scenario, TestingAgent
-
-    Scenario.configure(testing_agent=TestingAgent(model="openai/gpt-4o-mini"))
-    {termcolor.colored("^" * 74, "green")}
-
-    @pytest.mark.agent_test
-    def test_vegetarian_recipe_agent():
-        scenario = Scenario(
-            # ...
-        )
-        result = scenario.run()
-
-        assert result.success
-
-
- {termcolor.colored("->", "cyan")} Alternatively, you can set the config specifically for this scenario:
-
-    from scenario import Scenario, TestingAgent
-
-    @pytest.mark.agent_test
-    def test_vegetarian_recipe_agent():
-        scenario = Scenario(
-            # ...
-            testing_agent=TestingAgent(model="openai/gpt-4o-mini")
-            {termcolor.colored("^" * 54, "green")}
-        )
-        result = scenario.run()
-
-        assert result.success
-"""
+def agent_not_configured_error_message(class_name: str):
+    return f"""
 
+ {termcolor.colored("->", "cyan")} {class_name} was initialized without a model, please set the model when defining the testing agent, for example:
 
-testing_agent_not_configured_error_message = f"""
+    {class_name}(model="openai/gpt-4.1-mini")
+    {termcolor.colored("^" * (29 + len(class_name)), "green")}
 
- {termcolor.colored("->", "cyan")} Testing agent was initialized without a model, please set the model when defining the testing agent, for example:
+ {termcolor.colored("->", "cyan")} Alternatively, you can set the default model globally, for example:
 
-    TestingAgent.with_config(model="openai/gpt-4.1-mini")
-    {termcolor.colored("^" * 53, "green")}
+    scenario.configure(default_model="openai/gpt-4.1-mini")
+    {termcolor.colored("^" * 55, "green")}
 """
 
 

scenario/_utils/__init__.py

@@ -0,0 +1,32 @@
+"""
+Utility functions for scenario execution and message handling.
+
+This module provides various utility functions used throughout the Scenario framework,
+including message formatting, validation, role reversal, and UI components like spinners
+for better user experience during scenario execution.
+"""
+
+from .message_conversion import convert_agent_return_types_to_openai_messages
+from .ids import get_or_create_batch_run_id, generate_scenario_run_id
+from .utils import (
+    SerializableAndPydanticEncoder,
+    SerializableWithStringFallback,
+    print_openai_messages,
+    show_spinner,
+    check_valid_return_type,
+    reverse_roles,
+    await_if_awaitable,
+)
+
+__all__ = [
+    "convert_agent_return_types_to_openai_messages",
+    "get_or_create_batch_run_id",
+    "generate_scenario_run_id",
+    "SerializableAndPydanticEncoder",
+    "SerializableWithStringFallback",
+    "print_openai_messages",
+    "show_spinner",
+    "check_valid_return_type",
+    "reverse_roles",
+    "await_if_awaitable",
+]