langwatch-scenario 0.7.2__py3-none-any.whl → 0.7.7__py3-none-any.whl

scenario/_events/event_reporter.py

@@ -1,8 +1,9 @@
 import logging
-import os
 import httpx
-from typing import Optional
+from typing import Optional, Dict, Any
 from .events import ScenarioEvent
+from .event_alert_message_logger import EventAlertMessageLogger
+from scenario.config import LangWatchSettings
 
 
 class EventReporter:
@@ -13,51 +14,54 @@ class EventReporter:
     with proper authentication and error handling.
 
     Args:
-        endpoint (str, optional): The base URL to post events to. Defaults to LANGWATCH_ENDPOINT env var.
-        api_key (str, optional): The API key for authentication. Defaults to LANGWATCH_API_KEY env var.
+        endpoint (str, optional): Override endpoint URL. If not provided, uses LANGWATCH_ENDPOINT env var.
+        api_key (str, optional): Override API key. If not provided, uses LANGWATCH_API_KEY env var.
 
     Example:
-        event = {
-            "type": "SCENARIO_RUN_STARTED",
-            "batch_run_id": "batch-1",
-            "scenario_id": "scenario-1",
-            "scenario_run_id": "run-1",
-            "metadata": {
-                "name": "test",
-                "description": "test scenario"
-            }
-        }
-
-        reporter = EventReporter(endpoint="https://api.langwatch.ai", api_key="test-api-key")
-        await reporter.post_event(event)
+        # Using environment variables (LANGWATCH_ENDPOINT, LANGWATCH_API_KEY)
+        reporter = EventReporter()
+
+        # Override specific values
+        reporter = EventReporter(endpoint="https://langwatch.yourdomain.com")
+        reporter = EventReporter(api_key="your-api-key")
     """
 
     def __init__(self, endpoint: Optional[str] = None, api_key: Optional[str] = None):
-        self.endpoint = endpoint or os.getenv("LANGWATCH_ENDPOINT")
-        self.api_key = api_key or os.getenv("LANGWATCH_API_KEY", "")
+        # Load settings from environment variables
+        langwatch_settings = LangWatchSettings()
+
+        # Allow constructor parameters to override settings
+        self.endpoint = endpoint or langwatch_settings.endpoint
+        self.api_key = api_key or langwatch_settings.api_key
         self.logger = logging.getLogger(__name__)
+        self.event_alert_message_logger = EventAlertMessageLogger()
+
+        # Show greeting message when reporter is initialized
+        self.event_alert_message_logger.handle_greeting()
 
-    async def post_event(self, event: ScenarioEvent):
+    async def post_event(self, event: ScenarioEvent) -> Dict[str, Any]:
         """
         Posts an event to the configured endpoint.
 
         Args:
-            event: A dictionary containing the event data
+            event: A ScenarioEvent containing the event data
 
         Returns:
-            None - logs success/failure internally
+            Dict containing response data, including setUrl if available
         """
         event_type = event.type_
         self.logger.info(f"[{event_type}] Publishing event ({event.scenario_run_id})")
 
+        result: Dict[str, Any] = {}
+
         if not self.endpoint:
             self.logger.warning(
                 "No LANGWATCH_ENDPOINT configured, skipping event posting"
             )
-            return
+            return result
 
         try:
-            async with httpx.AsyncClient() as client:
+            async with httpx.AsyncClient(follow_redirects=True) as client:
                 response = await client.post(
                     f"{self.endpoint}/api/scenario-events",
                     json=event.to_dict(),
@@ -66,11 +70,19 @@ class EventReporter:
                         "X-Auth-Token": self.api_key,
                     },
                 )
-                self.logger.info(f"[{event_type}] POST response status: {response.status_code} ({event.scenario_run_id})")
-                
+                self.logger.info(
+                    f"[{event_type}] POST response status: {response.status_code} ({event.scenario_run_id})"
+                )
+
                 if response.is_success:
                     data = response.json()
-                    self.logger.info(f"[{event_type}] POST response: {data} ({event.scenario_run_id})")
+                    self.logger.info(
+                        f"[{event_type}] POST response: {data} ({event.scenario_run_id})"
+                    )
+
+                    # Extract setUrl from response if available
+                    if isinstance(data, dict) and "url" in data:
+                        result["setUrl"] = data["url"]
                 else:
                     error_text = response.text
                     self.logger.error(
@@ -80,4 +92,7 @@ class EventReporter:
                     )
         except Exception as error:
             self.logger.error(
-                f"[{event_type}] Event POST error: {error}, event={event}, endpoint={self.endpoint}") 
+                f"[{event_type}] Event POST error: {error}, event={event}, endpoint={self.endpoint}"
+            )
+
+        return result

scenario/_generated/langwatch_api_client/README.md

@@ -1,15 +1,19 @@
 # lang-watch-api-client
+
 **⚠️ AUTO-GENERATED CODE - DO NOT EDIT MANUALLY ⚠️**
 
 This is an auto-generated client library for accessing LangWatch API, created using `openapi-python-client`.
 
 ## Regeneration
+
 To regenerate this client:
+
 ```bash
 make generate-openapi-client
 ```
 
 ## Source
+
 Generated from: `../langwatch-saas/langwatch/langwatch/src/app/api/openapiLangWatch.json`
 
 ---
@@ -17,12 +21,13 @@ Generated from: `../langwatch-saas/langwatch/langwatch/src/app/api/openapiLangWa
 A client library for accessing LangWatch API
 
 ## Usage
+
 First, create a client:
 
 ```python
 from lang_watch_api_client import Client
 
-client = Client(base_url="https://api.langwatch.ai")
+client = Client(base_url="https://app.langwatch.ai")
 ```
 
 If the endpoints you're going to hit require authentication, use `AuthenticatedClient` instead:
@@ -30,7 +35,7 @@ If the endpoints you're going to hit require authentication, use `AuthenticatedC
 ```python
 from lang_watch_api_client import AuthenticatedClient
 
-client = AuthenticatedClient(base_url="https://api.langwatch.ai", token="SuperSecretToken")
+client = AuthenticatedClient(base_url="https://app.langwatch.ai", token="SuperSecretToken")
 ```
 
 Now call your endpoint and use your models:
@@ -62,7 +67,7 @@ By default, when you're calling an HTTPS API it will attempt to verify that SSL
 
 ```python
 client = AuthenticatedClient(
-    base_url="https://internal_api.langwatch.ai", 
+    base_url="https://app.langwatch.ai",
     token="SuperSecretToken",
     verify_ssl="/path/to/certificate_bundle.pem",
 )
@@ -72,18 +77,20 @@ You can also disable certificate validation altogether, but beware that **this i
 
 ```python
 client = AuthenticatedClient(
-    base_url="https://internal_api.langwatch.ai", 
-    token="SuperSecretToken", 
+    base_url="https://app.langwatch.ai",
+    token="SuperSecretToken",
     verify_ssl=False
 )
 ```
 
 Things to know:
+
 1. Every path/method combo becomes a Python module with four functions:
-    1. `sync`: Blocking request that returns parsed data (if successful) or `None`
-    1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.
-    1. `asyncio`: Like `sync` but async instead of blocking
-    1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking
+
+   1. `sync`: Blocking request that returns parsed data (if successful) or `None`
+   1. `sync_detailed`: Blocking request that always returns a `Request`, optionally with `parsed` set if the request was successful.
+   1. `asyncio`: Like `sync` but async instead of blocking
+   1. `asyncio_detailed`: Like `sync_detailed` but async instead of blocking
 
 1. All path/query params, and bodies become method arguments.
 1. If your endpoint had any tags on it, the first tag will be used as a module name for the function (my_tag above)
@@ -104,7 +111,7 @@ def log_response(response):
     print(f"Response event hook: {request.method} {request.url} - Status {response.status_code}")
 
 client = Client(
-    base_url="https://api.langwatch.ai",
+    base_url="https://app.langwatch.ai",
     httpx_args={"event_hooks": {"request": [log_request], "response": [log_response]}},
 )
 
@@ -118,22 +125,25 @@ import httpx
 from lang_watch_api_client import Client
 
 client = Client(
-    base_url="https://api.langwatch.ai",
+    base_url="https://app.langwatch.ai",
 )
 # Note that base_url needs to be re-set, as would any shared cookies, headers, etc.
-client.set_httpx_client(httpx.Client(base_url="https://api.langwatch.ai", proxies="http://localhost:8030"))
+client.set_httpx_client(httpx.Client(base_url="https://app.langwatch.ai", proxies="http://localhost:8030"))
 ```
 
 ## Building / publishing this package
-This project uses [Poetry](https://python-poetry.org/) to manage dependencies  and packaging.  Here are the basics:
+
+This project uses [Poetry](https://python-poetry.org/) to manage dependencies and packaging. Here are the basics:
+
 1. Update the metadata in pyproject.toml (e.g. authors, version)
 1. If you're using a private repository, configure it with Poetry
-    1. `poetry config repositories.<your-repository-name> <url-to-your-repository>`
-    1. `poetry config http-basic.<your-repository-name> <username> <password>`
+   1. `poetry config repositories.<your-repository-name> <url-to-your-repository>`
+   1. `poetry config http-basic.<your-repository-name> <username> <password>`
 1. Publish the client with `poetry publish --build -r <your-repository-name>` or, if for public PyPI, just `poetry publish --build`
 
 If you want to install this client into another project without publishing it (e.g. for development) then:
+
 1. If that project **is using Poetry**, you can simply do `poetry add <path-to-this-client>` from that project
 1. If that project is not using Poetry:
-    1. Build a wheel with `poetry build -f wheel`
-    1. Install that wheel from the other project `pip install <path-to-wheel>`
+   1. Build a wheel with `poetry build -f wheel`
+   1. Install that wheel from the other project `pip install <path-to-wheel>`

scenario/_utils/__init__.py

@@ -7,7 +7,15 @@ 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 .ids import (
+    get_batch_run_id,
+    get_or_create_batch_run_id,  # Backward compatibility
+    generate_scenario_run_id,
+    generate_scenario_id,
+    generate_thread_id,
+    generate_message_id,
+    safe_parse_uuid,
+)
 from .utils import (
     SerializableAndPydanticEncoder,
     SerializableWithStringFallback,
@@ -20,8 +28,13 @@ from .utils import (
 
 __all__ = [
     "convert_agent_return_types_to_openai_messages",
-    "get_or_create_batch_run_id",
+    "get_batch_run_id",
+    "get_or_create_batch_run_id",  # Backward compatibility
     "generate_scenario_run_id",
+    "generate_scenario_id",
+    "generate_thread_id",
+    "generate_message_id",
+    "safe_parse_uuid",
     "SerializableAndPydanticEncoder",
     "SerializableWithStringFallback",
     "print_openai_messages",
@@ -29,4 +42,4 @@ __all__ = [
     "check_valid_return_type",
     "reverse_roles",
     "await_if_awaitable",
-]
+]

scenario/_utils/ids.py

@@ -10,49 +10,87 @@ import os
 import uuid
 
 
-def get_or_create_batch_run_id() -> str:
+def generate_thread_id() -> str:
+    """
+    Generates a new thread ID.
+
+    Returns:
+        str: A new thread ID.
+    """
+    return f"thread_{uuid.uuid4()}"
+
+
+def generate_scenario_run_id() -> str:
+    """
+    Generates a new scenario run ID.
+
+    Returns:
+        str: A new scenario run ID.
+    """
+    return f"scenariorun_{uuid.uuid4()}"
+
+
+def generate_scenario_id() -> str:
+    """
+    Generates a new scenario ID.
+
+    Returns:
+        str: A new scenario ID.
+    """
+    return f"scenario_{uuid.uuid4()}"
+
+
+def get_batch_run_id() -> str:
     """
-    Gets or creates a batch run ID for the current scenario execution.
-    
-    The batch run ID is consistent across all scenarios in the same process
-    execution, allowing grouping of related scenario runs. This is useful
-    for tracking and reporting on batches of scenarios run together.
-    
+    Gets the batch run ID. If it's not set, it will be generated.
+    It can be set via the SCENARIO_BATCH_RUN_ID environment variable.
+
     Returns:
-        str: A unique batch run ID that persists for the process lifetime
-        
-    Example:
-        ```python
-        # All scenarios in same process will share this ID
-        batch_id = get_or_create_batch_run_id()
-        print(f"Running scenario in batch: {batch_id}")
-        ```
-    """
-    
+        str: The batch run ID.
+    """
     # Check if batch ID already exists in environment
-    if not os.environ.get("SCENARIO_BATCH_ID"):
+    batch_run_id = os.environ.get("SCENARIO_BATCH_RUN_ID")
+    if not batch_run_id:
         # Generate new batch ID if not set
-        os.environ["SCENARIO_BATCH_ID"] = f"batch-run-{uuid.uuid4()}"
-    
-    return os.environ["SCENARIO_BATCH_ID"]
+        batch_run_id = f"scenariobatchrun_{uuid.uuid4()}"
+        os.environ["SCENARIO_BATCH_RUN_ID"] = batch_run_id
 
+    return batch_run_id
 
-def generate_scenario_run_id() -> str:
+
+def generate_message_id() -> str:
+    """
+    Generates a new message ID.
+
+    Returns:
+        str: A new message ID.
+    """
+    return f"scenariomsg_{uuid.uuid4()}"
+
+
+def safe_parse_uuid(id_str: str) -> bool:
     """
-    Generates a unique scenario run ID for a single scenario execution.
-    
-    Each scenario run gets a unique identifier that distinguishes it from
-    other runs, even within the same batch. This is used for tracking
-    individual scenario executions and correlating events.
-    
+    Safely parses a UUID string.
+
+    Args:
+        id_str: The UUID string to parse.
+
+    Returns:
+        bool: True if the UUID string is valid, false otherwise.
+    """
+    try:
+        uuid.UUID(id_str)
+        return True
+    except (ValueError, TypeError):
+        return False
+
+
+# Backward compatibility aliases
+def get_or_create_batch_run_id() -> str:
+    """
+    Backward compatibility alias for get_batch_run_id().
+
     Returns:
-        str: A unique scenario run ID
-        
-    Example:
-        ```python
-        # Each scenario gets its own unique ID
-        scenario_id = generate_scenario_run_id()
-        print(f"Running scenario with ID: {scenario_id}")
-        ```
-    """
-    return f"scenario-run-{uuid.uuid4()}" 
+        str: The batch run ID.
+    """
+    return get_batch_run_id()

scenario/config/__init__.py

@@ -0,0 +1,43 @@
+"""
+Configuration module for Scenario.
+
+This module provides all configuration classes for customizing the behavior
+of the Scenario testing framework, including model settings, scenario execution
+parameters, and LangWatch integration.
+
+Classes:
+    ModelConfig: Configuration for LLM model settings
+    ScenarioConfig: Main configuration for scenario execution
+    LangWatchSettings: Configuration for LangWatch API integration
+
+Example:
+    ```
+    from scenario.config import ModelConfig, ScenarioConfig, LangWatchSettings
+
+    # Configure LLM model
+    model_config = ModelConfig(
+        model="openai/gpt-4.1-mini",
+        temperature=0.1
+    )
+
+    # Configure scenario execution
+    scenario_config = ScenarioConfig(
+        default_model=model_config,
+        max_turns=15,
+        verbose=True
+    )
+
+    # Configure LangWatch integration
+    langwatch_settings = LangWatchSettings()  # Reads from environment
+    ```
+"""
+
+from .model import ModelConfig
+from .scenario import ScenarioConfig
+from .langwatch import LangWatchSettings
+
+__all__ = [
+    "ModelConfig",
+    "ScenarioConfig",
+    "LangWatchSettings",
+]

scenario/config/langwatch.py

@@ -0,0 +1,51 @@
+"""
+LangWatch configuration for Scenario.
+
+This module provides configuration for LangWatch API integration,
+including endpoint URLs and authentication credentials.
+"""
+
+from pydantic import Field, HttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class LangWatchSettings(BaseSettings):
+    """
+    Configuration for LangWatch API integration.
+
+    This class handles configuration for connecting to LangWatch services,
+    automatically reading from environment variables with the LANGWATCH_ prefix.
+
+    Attributes:
+        endpoint: LangWatch API endpoint URL
+        api_key: API key for LangWatch authentication
+
+    Environment Variables:
+        LANGWATCH_ENDPOINT: LangWatch API endpoint (defaults to https://app.langwatch.ai)
+        LANGWATCH_API_KEY: API key for authentication (defaults to empty string)
+
+    Example:
+        ```
+        # Using environment variables
+        # export LANGWATCH_ENDPOINT="https://app.langwatch.ai"
+        # export LANGWATCH_API_KEY="your-api-key"
+
+        settings = LangWatchSettings()
+        print(settings.endpoint)  # https://app.langwatch.ai
+        print(settings.api_key)   # your-api-key
+
+        # Or override programmatically
+        settings = LangWatchSettings(
+            endpoint="https://custom.langwatch.ai",
+            api_key="your-api-key"
+        )
+        ```
+    """
+
+    model_config = SettingsConfigDict(env_prefix="LANGWATCH_", case_sensitive=False)
+
+    endpoint: HttpUrl = Field(
+        default=HttpUrl("https://app.langwatch.ai"),
+        description="LangWatch API endpoint URL",
+    )
+    api_key: str = Field(default="", description="API key for LangWatch authentication")

scenario/config/model.py

@@ -0,0 +1,39 @@
+"""
+Model configuration for Scenario.
+
+This module provides configuration classes for LLM model settings used by
+user simulator and judge agents in the Scenario framework.
+"""
+
+from typing import Optional
+from pydantic import BaseModel
+
+
+class ModelConfig(BaseModel):
+    """
+    Configuration for LLM model settings.
+
+    This class encapsulates all the parameters needed to configure an LLM model
+    for use with user simulator and judge agents in the Scenario framework.
+
+    Attributes:
+        model: The model identifier (e.g., "openai/gpt-4.1-mini", "anthropic/claude-3-sonnet")
+        api_key: Optional API key for the model provider
+        temperature: Sampling temperature for response generation (0.0 = deterministic, 1.0 = creative)
+        max_tokens: Maximum number of tokens to generate in responses
+
+    Example:
+        ```
+        model_config = ModelConfig(
+            model="openai/gpt-4.1",
+            api_key="your-api-key",
+            temperature=0.1,
+            max_tokens=1000
+        )
+        ```
+    """
+
+    model: str
+    api_key: Optional[str] = None
+    temperature: float = 0.0
+    max_tokens: Optional[int] = None

scenario/{config.py → config/scenario.py}

@@ -1,43 +1,14 @@
 """
-Configuration module for Scenario.
+Scenario configuration for Scenario.
 
-This module provides configuration classes for customizing the behavior of the
-Scenario testing framework, including LLM model settings, execution parameters,
-and debugging options.
+This module provides the main configuration class for customizing the behavior
+of the Scenario testing framework, including execution parameters and debugging options.
 """
 
 from typing import Optional, Union, ClassVar
 from pydantic import BaseModel
 
-
-class ModelConfig(BaseModel):
-    """
-    Configuration for LLM model settings.
-
-    This class encapsulates all the parameters needed to configure an LLM model
-    for use with user simulator and judge agents in the Scenario framework.
-
-    Attributes:
-        model: The model identifier (e.g., "openai/gpt-4.1-mini", "anthropic/claude-3-sonnet")
-        api_key: Optional API key for the model provider
-        temperature: Sampling temperature for response generation (0.0 = deterministic, 1.0 = creative)
-        max_tokens: Maximum number of tokens to generate in responses
-
-    Example:
-        ```
-        model_config = ModelConfig(
-            model="openai/gpt-4.1-mini",
-            api_key="your-api-key",
-            temperature=0.1,
-            max_tokens=1000
-        )
-        ```
-    """
-
-    model: str
-    api_key: Optional[str] = None
-    temperature: float = 0.0
-    max_tokens: Optional[int] = None
+from .model import ModelConfig
 
 
 class ScenarioConfig(BaseModel):
@@ -69,7 +40,7 @@ class ScenarioConfig(BaseModel):
         # Or create a specific config instance
         config = ScenarioConfig(
             default_model=ModelConfig(
-                model="openai/gpt-4.1-mini",
+                model="openai/gpt-4.1",
                 temperature=0.2
             ),
             max_turns=20

scenario/judge_agent.py

@@ -62,7 +62,7 @@ class JudgeAgent(AgentAdapter):
 
         # Customized judge with specific model and behavior
         strict_judge = scenario.JudgeAgent(
-            model="openai/gpt-4.1-mini",
+            model="openai/gpt-4.1",
             criteria=[
                 "Code examples are syntactically correct",
                 "Explanations are technically accurate",
@@ -120,7 +120,7 @@ class JudgeAgent(AgentAdapter):
             criteria: List of success criteria to evaluate the conversation against.
                      Can include both positive requirements ("Agent provides helpful responses")
                      and negative constraints ("Agent should not provide personal information").
-            model: LLM model identifier (e.g., "openai/gpt-4.1-mini").
+            model: LLM model identifier (e.g., "openai/gpt-4.1").
                    If not provided, uses the default model from global configuration.
             api_key: API key for the model provider. If not provided,
                      uses the key from global configuration or environment.