diff --git a/README.md b/README.md index 44473dbd..52b8a8e4 100644 --- a/README.md +++ b/README.md @@ -84,7 +84,7 @@ await stagehand.agent.execute("book a reservation for 2 people for a trip to the ``` -## Installation: +## Installation To get started, simply: @@ -96,10 +96,14 @@ pip install stagehand ```bash uv venv .venv -source .venv/bin/activate +source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install stagehand ``` +### Prerequisites + +Stagehand requires a local browser installation. The library uses Playwright to manage browser instances automatically. No additional browser setup is required - Playwright will download the necessary browser binaries on first use. + ## Quickstart ```python @@ -111,7 +115,7 @@ from pydantic import BaseModel, Field from stagehand import StagehandConfig, Stagehand # Load environment variables -load_dotenv() +load_dotenv() # Create a .env file or set environment variables in your shell # Define Pydantic models for structured data extraction class Company(BaseModel): @@ -122,25 +126,25 @@ class Companies(BaseModel): companies: list[Company] = Field(..., description="List of companies") async def main(): - # Create configuration + # Create configuration with Alibaba ModelScope (DashScope) config = StagehandConfig( - env = "BROWSERBASE", # or LOCAL - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="google/gemini-2.5-flash-preview-05-20", - model_api_key=os.getenv("MODEL_API_KEY"), + model_name="dashscope/qwen-turbo", + model_client_options={ + "api_base": os.getenv("ALIBABA_ENDPOINT", "https://dashscope.aliyuncs.com/compatible-mode/v1"), + "api_key": os.getenv("ALIBABA_API_KEY") + }, + local_browser_launch_options={ + "headless": False # Set to True for headless mode + } ) stagehand = Stagehand(config) try: print("\nInitializing 🤘 Stagehand...") - # Initialize Stagehand + # Initialize Stagehand with local browser await stagehand.init() - if stagehand.env == "BROWSERBASE": - print(f"🌐 View your live browser: https://www.browserbase.com/sessions/{stagehand.session_id}") - page = stagehand.page await page.goto("https://www.aigrant.com") @@ -156,9 +160,9 @@ async def main(): for idx, company in enumerate(companies_data.companies, 1): print(f"{idx}. {company.name}: {company.description}") - observe = await page.observe("the link to the company Browserbase") + observe = await page.observe("the search bar") print("\nObserve result:", observe) - act = await page.act("click the link to the company Browserbase") + act = await page.act("click on the search bar") print("\nAct result:", act) except Exception as e: @@ -173,6 +177,143 @@ if __name__ == "__main__": asyncio.run(main()) ``` +## Configuration Options + +### Basic Configuration + +```python +# OpenAI (default) +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") + } +) + +# Anthropic Claude +config = StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY") + } +) +``` + +### Custom API Endpoints + +Stagehand supports various OpenAI/Anthropic compatible providers: + +```python +# Together AI +config = StagehandConfig( + model_name="meta-llama/Llama-2-7b-chat-hf", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": os.getenv("TOGETHER_API_KEY") + } +) + +# Groq +config = StagehandConfig( + model_name="llama2-70b-4096", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": os.getenv("GROQ_API_KEY") + } +) + +# Local OpenAI-compatible server +config = StagehandConfig( + model_name="local/custom-model", + model_client_options={ + "api_base": "http://localhost:8000/v1", + "api_key": "local-key" + } +) +``` + +### Browser Configuration + +```python +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={"api_key": os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={ + "headless": True, # Run in headless mode + "viewport": {"width": 1280, "height": 720}, + "user_data_dir": "./browser_data", # Persistent browser data + "args": ["--no-sandbox", "--disable-dev-shm-usage"] # Additional Chrome args + } +) +``` + +## Migration from Browserbase + +If you're upgrading from a previous version that used Browserbase, here's how to migrate your configuration: + +### Quick Migration Check + +Use our migration utility to scan your project: + +```bash +# Scan current directory for files needing migration +python docs/migration_utility.py scan . + +# Generate configuration examples +python docs/migration_utility.py config openai +``` + +### Before (Browserbase Configuration) +```python +# Old Browserbase configuration +config = StagehandConfig( + env="BROWSERBASE", + api_key="browserbase-api-key", + project_id="browserbase-project-id", + model_name="gpt-4o", + model_api_key="openai-api-key" +) +``` + +### After (Local Configuration) +```python +# New local configuration +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": "openai-api-key", + # Optional: specify custom endpoint + "api_base": "https://api.openai.com/v1" + }, + local_browser_launch_options={ + "headless": False # Configure browser options as needed + } +) +``` + +### Key Changes +- **Removed**: `env`, `api_key`, `project_id` parameters +- **Replaced**: `model_api_key` with `model_client_options.api_key` +- **Added**: `local_browser_launch_options` for browser configuration +- **Enhanced**: Support for custom API endpoints via `model_client_options.api_base` + +### Environment Variables +Update your environment variables: +```bash +# Remove these (no longer needed) +# BROWSERBASE_API_KEY=your-browserbase-key +# BROWSERBASE_PROJECT_ID=your-project-id + +# Keep or add these +OPENAI_API_KEY=your-openai-key +# Or for other providers: +# ANTHROPIC_API_KEY=your-anthropic-key +# TOGETHER_API_KEY=your-together-key +``` + +For a complete migration guide with troubleshooting, see [docs/migration_guide.md](docs/migration_guide.md). + ## Documentation See our full documentation [here](https://docs.stagehand.dev/). @@ -219,8 +360,21 @@ cd stagehand-python # Install in editable mode with development dependencies pip install -r requirements.txt + +# On Windows, you may need to install Playwright browsers +playwright install ``` +### Dependencies + +Stagehand has minimal dependencies and no longer requires external browser services: + +- **Core**: `playwright`, `pydantic`, `python-dotenv` +- **LLM Support**: `openai`, `anthropic`, `litellm` +- **Utilities**: `rich`, `nest-asyncio` + +All dependencies are automatically installed with `pip install stagehand`. + ## License diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..e1869d87 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,152 @@ +# Stagehand Documentation + +Welcome to the Stagehand documentation! This directory contains comprehensive guides for using Stagehand with local browser automation and custom LLM providers. + +## Quick Start + +- **[Main README](../README.md)** - Get started with Stagehand +- **[Installation and Basic Usage](../README.md#installation)** - Installation instructions and quickstart guide + +## Configuration Guides + +- **[LLM Client Configuration](llm_client_configuration.md)** - Complete guide to configuring LLM providers + - OpenAI, Anthropic, Together AI, Groq configurations + - Custom API endpoints + - Environment variable setup + - Configuration validation + +## Migration + +- **[Migration Guide](migration_guide.md)** - Complete migration from Browserbase to local configuration + - Step-by-step migration instructions + - Before/after configuration examples + - Provider-specific configurations + - Testing migration + - Comprehensive FAQ section + +### Migration Tools + +- **[migration_utility.py](migration_utility.py)** - Automated migration analysis tool + - Scan projects for Browserbase usage + - Generate detailed migration reports + - Provide specific migration suggestions + - Show configuration examples + +- **[validate_migration.py](validate_migration.py)** - Migration validation script + - Verify environment setup + - Test configuration creation + - Validate runtime functionality + - Check for leftover Browserbase files + +- **[run_migration_check.ps1](run_migration_check.ps1)** - PowerShell helper script + - Run analysis and validation together + - Windows-friendly migration workflow + - Comprehensive error reporting + +#### Using Migration Tools + +```bash +# Analyze your code for migration issues +python docs/migration_utility.py + +# Analyze specific directory +python docs/migration_utility.py ./examples + +# Show configuration migration example +python docs/migration_utility.py --config-example + +# Validate your migration +python docs/validate_migration.py +``` + +**PowerShell (Windows):** +```powershell +# Run analysis and validation together +.\docs\run_migration_check.ps1 -Validate + +# Analyze specific path +.\docs\run_migration_check.ps1 -Path .\examples + +# Show help +.\docs\run_migration_check.ps1 -Help +``` + +## Troubleshooting + +- **[Troubleshooting Guide](troubleshooting.md)** - Solutions for common issues + - Configuration problems + - Browser launch issues + - LLM provider errors + - Windows-specific solutions + - Performance optimization + +## Key Changes in Latest Version + +### ✅ What's New +- **Local browser automation** - No external browser service required +- **Multiple LLM providers** - OpenAI, Anthropic, Together AI, Groq, and more +- **Custom API endpoints** - Use any OpenAI/Anthropic compatible API +- **Improved Windows support** - Better PowerShell compatibility +- **Enhanced configuration** - More flexible and powerful configuration options + +### ❌ What's Removed +- **Browserbase dependency** - No longer requires Browserbase API +- **External browser sessions** - All browsers run locally +- **Complex environment setup** - Simplified configuration + +### 🔄 What's Changed +- **Configuration format** - New `model_client_options` structure +- **Environment variables** - Use LLM provider keys instead of Browserbase keys +- **Browser options** - New `local_browser_launch_options` for browser configuration + +## Examples + +### Basic Configuration +```python +from stagehand import StagehandConfig, Stagehand + +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") + } +) +``` + +### Custom Provider Configuration +```python +config = StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY") + } +) +``` + +### Browser Customization +```python +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={"api_key": os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={ + "headless": True, + "viewport": {"width": 1920, "height": 1080}, + "user_data_dir": "./browser_data" + } +) +``` + +## Getting Help + +- **[GitHub Issues](https://github.com/browserbase/stagehand-python/issues)** - Report bugs or request features +- **[Slack Community](https://stagehand.dev/slack)** - Get help from the community +- **[Main Documentation](https://docs.stagehand.dev/)** - Official documentation site + +## Contributing + +See the main [Contributing Guide](https://docs.stagehand.dev/examples/contributing) for information on contributing to Stagehand. + +--- + +For the most up-to-date information, always refer to the [official documentation](https://docs.stagehand.dev/). \ No newline at end of file diff --git a/docs/configuration_validation.md b/docs/configuration_validation.md new file mode 100644 index 00000000..49d4d9db --- /dev/null +++ b/docs/configuration_validation.md @@ -0,0 +1,318 @@ +# Configuration Validation and Error Handling + +This document describes the enhanced configuration validation and error handling features in Stagehand Python. + +## Overview + +Stagehand now includes comprehensive configuration validation that helps catch common configuration issues early and provides helpful error messages with suggestions for fixes. + +## Features + +### 1. API Base URL Validation + +The system validates custom API endpoints to ensure they are properly formatted: + +```python +from stagehand.config import StagehandConfig + +# Valid configurations +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": "your-api-key" + } +) + +# The system will catch invalid URLs +try: + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_base": "not-a-valid-url", # This will fail + "api_key": "your-api-key" + } + ) +except ValidationError as e: + print(f"Configuration error: {e}") +``` + +### 2. API Key Validation + +The system checks for API keys in multiple locations and provides helpful guidance: + +```python +# API key in model_client_options (recommended) +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": "your-openai-api-key" + } +) + +# API key via direct parameter +config = StagehandConfig( + model_name="gpt-4o", + model_api_key="your-openai-api-key" +) + +# API key via environment variable (automatic detection) +# export OPENAI_API_KEY=your-api-key +config = StagehandConfig(model_name="gpt-4o") +``` + +### 3. Provider Inference + +The system automatically infers the LLM provider from the model name: + +```python +from stagehand.config import infer_provider_from_model_name + +# Examples of provider inference +print(infer_provider_from_model_name("gpt-4o")) # "openai" +print(infer_provider_from_model_name("claude-3-opus-20240229")) # "anthropic" +print(infer_provider_from_model_name("meta-llama/Llama-2-70b")) # "together" +print(infer_provider_from_model_name("mixtral-8x7b-32768")) # "groq" +``` + +### 4. Comprehensive Configuration Validation + +You can validate a complete configuration before using it: + +```python +from stagehand.config import StagehandConfig, validate_stagehand_config + +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": "your-api-key" + } +) + +# Validate the configuration +result = validate_stagehand_config(config) + +if result["valid"]: + print("✅ Configuration is valid!") + + # Check for warnings + for warning in result["warnings"]: + print(f"⚠️ {warning}") + + # Check for recommendations + for recommendation in result["recommendations"]: + print(f"💡 {recommendation}") +else: + print("❌ Configuration has errors:") + for error in result["errors"]: + print(f" • {error}") +``` + +## Error Messages + +The system provides helpful error messages with examples: + +```python +from stagehand.config import create_helpful_error_message + +# Example error message for missing API key +validation_result = { + "valid": False, + "errors": ["No API key found for openai provider"], + "warnings": ["Using localhost/local IP - ensure this is intended for development"], + "recommendations": ["Consider enabling caching for better performance"] +} + +error_message = create_helpful_error_message(validation_result, "initialization") +print(error_message) +``` + +Output: +``` +Configuration Error in initialization: + +Errors: + • No API key found for openai provider + +Warnings: + • Using localhost/local IP - ensure this is intended for development + +Recommendations: + • Consider enabling caching for better performance + +Example API key configuration: + config = StagehandConfig( + model_name='gpt-4o', + model_client_options={ + 'api_key': 'your-api-key-here' + } + ) + +Or set environment variable: export OPENAI_API_KEY=your-api-key-here +``` + +## Custom API Endpoints + +The validation system supports various custom API endpoints: + +### OpenAI Compatible Endpoints + +```python +# Together AI +config = StagehandConfig( + model_name="meta-llama/Llama-2-70b-chat-hf", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": "your-together-api-key" + } +) + +# Groq +config = StagehandConfig( + model_name="mixtral-8x7b-32768", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": "your-groq-api-key" + } +) + +# Local OpenAI-compatible server +config = StagehandConfig( + model_name="gpt-3.5-turbo", + model_client_options={ + "api_base": "http://localhost:8000/v1", + "api_key": "local-key" + } +) +``` + +### Anthropic Compatible Endpoints + +```python +# Official Anthropic API +config = StagehandConfig( + model_name="claude-3-opus-20240229", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": "your-anthropic-api-key" + } +) +``` + +## Environment Variables + +The system automatically detects API keys from environment variables: + +| Provider | Environment Variable | +|----------|---------------------| +| OpenAI | `OPENAI_API_KEY` | +| Anthropic | `ANTHROPIC_API_KEY` | +| Together AI | `TOGETHER_API_KEY` | +| Groq | `GROQ_API_KEY` | +| Google | `GOOGLE_API_KEY` | +| Cohere | `COHERE_API_KEY` | + +## Validation Functions + +### `validate_api_base_url(api_base: str)` + +Validates an API base URL and returns detailed results: + +```python +from stagehand.config import validate_api_base_url + +result = validate_api_base_url("https://api.openai.com/v1") +# Returns: { +# "valid": True, +# "error": "", +# "normalized_url": "https://api.openai.com/v1", +# "warnings": [] +# } +``` + +### `validate_api_key_configuration(model_name, model_api_key, model_client_options)` + +Validates API key configuration for a specific model: + +```python +from stagehand.config import validate_api_key_configuration + +result = validate_api_key_configuration( + "gpt-4o", + None, + {"api_key": "test-key"} +) +# Returns: { +# "valid": True, +# "errors": [], +# "warnings": [], +# "provider": "openai", +# "api_key_source": "model_client_options" +# } +``` + +### `validate_stagehand_config(config: StagehandConfig)` + +Performs comprehensive validation of a complete configuration: + +```python +from stagehand.config import StagehandConfig, validate_stagehand_config + +config = StagehandConfig(model_name="gpt-4o") +result = validate_stagehand_config(config) +# Returns detailed validation results +``` + +## Best Practices + +1. **Always validate configuration** before initializing Stagehand in production +2. **Use environment variables** for API keys to keep them secure +3. **Check warnings and recommendations** to optimize your configuration +4. **Test custom API endpoints** before deployment +5. **Use HTTPS** for production API endpoints + +## Migration from Browserbase + +If you're migrating from a Browserbase setup, the validation system will help guide you: + +```python +# Old Browserbase configuration (no longer supported) +# config = StagehandConfig( +# env="BROWSERBASE", +# api_key="browserbase-key", +# project_id="browserbase-project" +# ) + +# New local configuration +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": "your-openai-api-key" + }, + local_browser_launch_options={ + "headless": False + } +) +``` + +## Troubleshooting + +### Common Issues + +1. **"No API key found"** - Set the appropriate environment variable or add `api_key` to `model_client_options` +2. **"Invalid api_base URL"** - Ensure the URL starts with `http://` or `https://` +3. **"Model name required"** - Specify a valid model name like `"gpt-4o"` or `"claude-3-opus-20240229"` + +### Getting Help + +If you encounter configuration issues: + +1. Check the validation error messages for specific guidance +2. Review the examples in this documentation +3. Ensure your API keys are correctly set +4. Verify your custom API endpoints are accessible + +## Examples + +See the `examples/config_validation_example.py` file for comprehensive examples of all validation features. \ No newline at end of file diff --git a/docs/llm_client_configuration.md b/docs/llm_client_configuration.md new file mode 100644 index 00000000..c42b22a3 --- /dev/null +++ b/docs/llm_client_configuration.md @@ -0,0 +1,255 @@ +# LLM Client Configuration Guide + +This guide explains how to configure the enhanced LLM client in Stagehand to work with custom API endpoints and different providers. + +## Overview + +The enhanced LLM client supports: +- Custom API endpoints for OpenAI/Anthropic compatible providers +- Multiple LLM providers (OpenAI, Anthropic, Together AI, Groq, etc.) +- Environment variable fallback for API keys +- Configuration validation and error handling +- Timeout and retry configuration + +## Basic Configuration + +### OpenAI Configuration + +```python +from stagehand.config import StagehandConfig + +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": "your-openai-api-key", + "timeout": 30, + "max_retries": 3 + } +) +``` + +### Anthropic Configuration + +```python +config = StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": "your-anthropic-api-key", + "timeout": 60 + } +) +``` + +### Together AI Configuration + +```python +config = StagehandConfig( + model_name="together/llama-2-7b-chat", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": "your-together-api-key" + } +) +``` + +### Groq Configuration + +```python +config = StagehandConfig( + model_name="groq/llama2-70b-4096", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": "your-groq-api-key" + } +) +``` + +### Local OpenAI-Compatible Server + +```python +config = StagehandConfig( + model_name="local/custom-model", + model_client_options={ + "api_base": "http://localhost:8000/v1", + "api_key": "local-key", + "timeout": 120 # Local servers might be slower + } +) +``` + +## Environment Variable Fallback + +The LLM client automatically detects API keys from environment variables based on the model name: + +- OpenAI models: `OPENAI_API_KEY` +- Anthropic models: `ANTHROPIC_API_KEY` +- Together AI models: `TOGETHER_API_KEY` +- Groq models: `GROQ_API_KEY` +- Google/Gemini models: `GOOGLE_API_KEY` +- Generic fallback: `MODEL_API_KEY` or `LLM_API_KEY` + +Example without explicit API key: + +```python +import os +os.environ["OPENAI_API_KEY"] = "your-api-key" + +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1" + # API key will be automatically detected + } +) +``` + +## Configuration Options + +### Available Options + +- `api_base` or `baseURL`: Custom API endpoint URL +- `api_key` or `apiKey`: API key for authentication +- `timeout`: Request timeout in seconds (default: 30) +- `max_retries`: Maximum number of retries for failed requests (default: 3) + +### Validation + +The configuration is automatically validated: + +- API base must be a valid HTTP/HTTPS URL +- Timeout must be a positive number +- Max retries must be a non-negative integer +- Only one API key field should be specified + +## Error Handling + +The enhanced LLM client provides detailed error messages for common issues: + +### API Key Errors +``` +LLMProviderError: API key error for model gpt-4o. Please check your API key configuration in model_client_options. +``` + +### Model Not Found +``` +LLMProviderError: Model gpt-4o not found. Please check the model name and your API endpoint configuration. +``` + +### Unauthorized Access +``` +LLMProviderError: Unauthorized access for model gpt-4o. Please check your API key and permissions. +``` + +### Rate Limiting +``` +LLMProviderError: Rate limit exceeded for model gpt-4o. Please try again later or check your usage limits. +``` + +## Configuration Validation + +You can validate your LLM configuration programmatically: + +```python +async with Stagehand(config=config) as stagehand: + validation = stagehand.llm.validate_configuration() + + if validation['valid']: + print("Configuration is valid") + print(f"Provider: {validation['configuration']['provider']}") + print(f"API Base: {validation['configuration']['api_base']}") + else: + print("Configuration errors:", validation['errors']) + print("Configuration warnings:", validation['warnings']) +``` + +## Migration from Browserbase + +If you're migrating from a Browserbase configuration, here's how to update: + +### Before (Browserbase) +```python +config = StagehandConfig( + env="BROWSERBASE", # ❌ No longer supported + api_key="browserbase-api-key", # ❌ No longer needed + project_id="browserbase-project-id", # ❌ No longer needed + model_name="gpt-4o", + model_client_options={"apiKey": "openai-api-key"} # ❌ Old format +) +``` + +### After (Local with Custom Endpoint) +```python +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_base": "https://api.openai.com/v1", # ✅ Optional custom endpoint + "api_key": "openai-api-key", # ✅ New format + "timeout": 30 + }, + local_browser_launch_options={ # ✅ New browser configuration + "headless": False + } +) +``` + +### Key Migration Points + +1. **Remove Browserbase fields**: `env`, `api_key`, `project_id` +2. **Update API key format**: Use `api_key` instead of `apiKey` in `model_client_options` +3. **Add browser options**: Configure local browser with `local_browser_launch_options` +4. **Update environment variables**: Remove `BROWSERBASE_*` variables, keep LLM provider keys + +For a complete migration guide, see [Migration Guide](migration_guide.md). + +## Best Practices + +1. **Use Environment Variables**: Store API keys in environment variables rather than hardcoding them +2. **Set Appropriate Timeouts**: Configure timeouts based on your provider and model +3. **Handle Errors Gracefully**: Implement proper error handling for API failures +4. **Validate Configuration**: Use the validation method to check configuration before making requests +5. **Monitor Usage**: Keep track of token usage and API limits + +## Example: Complete Configuration + +```python +import asyncio +import os +from stagehand.main import Stagehand +from stagehand.config import StagehandConfig + +async def main(): + config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": os.getenv("OPENAI_API_KEY"), + "timeout": 30, + "max_retries": 3 + }, + verbose=1, + local_browser_launch_options={ + "headless": False, + "viewport": {"width": 1280, "height": 720} + } + ) + + async with Stagehand(config=config) as stagehand: + # Validate configuration + validation = stagehand.llm.validate_configuration() + if not validation['valid']: + print("Configuration errors:", validation['errors']) + return + + # Use Stagehand normally + page = stagehand.page + await page.goto("https://example.com") + + # Extract data using the configured LLM + result = await page.extract("Extract the page title") + print("Extracted:", result) + +if __name__ == "__main__": + asyncio.run(main()) +``` \ No newline at end of file diff --git a/docs/migration_guide.md b/docs/migration_guide.md new file mode 100644 index 00000000..16e714f4 --- /dev/null +++ b/docs/migration_guide.md @@ -0,0 +1,456 @@ +# Migration Guide: From Browserbase to Local Configuration + +This guide helps you migrate from the previous Browserbase-dependent version of Stagehand to the new local-only version with enhanced LLM provider support. + +## Overview of Changes + +The new version of Stagehand: +- **Removes** dependency on Browserbase API +- **Uses** local Playwright browser instances +- **Supports** custom API endpoints for various LLM providers +- **Maintains** all existing functionality (act, extract, observe, agent) +- **Improves** Windows compatibility + +## Step-by-Step Migration + +### 1. Update Dependencies + +The new version automatically removes Browserbase dependencies. Simply update: + +```bash +pip install --upgrade stagehand +``` + +### 2. Update Configuration + +#### Before (Browserbase) +```python +from stagehand import StagehandConfig, Stagehand + +config = StagehandConfig( + env="BROWSERBASE", # ❌ No longer supported + api_key="browserbase-api-key", # ❌ No longer needed + project_id="browserbase-project-id", # ❌ No longer needed + model_name="gpt-4o", + model_api_key="openai-api-key" # ❌ Deprecated +) +``` + +#### After (Local) +```python +from stagehand import StagehandConfig, Stagehand + +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ # ✅ New configuration format + "api_key": "openai-api-key", + "api_base": "https://api.openai.com/v1" # Optional + }, + local_browser_launch_options={ # ✅ New browser options + "headless": False, + "viewport": {"width": 1280, "height": 720} + } +) +``` + +### 3. Update Environment Variables + +#### Remove Browserbase Variables +```bash +# Remove these from your .env file +BROWSERBASE_API_KEY=your-browserbase-key +BROWSERBASE_PROJECT_ID=your-project-id +``` + +#### Keep/Add LLM Provider Variables +```bash +# OpenAI (most common) +OPENAI_API_KEY=your-openai-key + +# Or other providers +ANTHROPIC_API_KEY=your-anthropic-key +TOGETHER_API_KEY=your-together-key +GROQ_API_KEY=your-groq-key +``` + +### 4. Update Initialization Code + +#### Before +```python +async def main(): + config = StagehandConfig( + env="BROWSERBASE", + api_key=os.getenv("BROWSERBASE_API_KEY"), + project_id=os.getenv("BROWSERBASE_PROJECT_ID"), + model_name="gpt-4o" + ) + + stagehand = Stagehand(config) + await stagehand.init() + + # Session URL was available + if stagehand.env == "BROWSERBASE": + print(f"Session: https://www.browserbase.com/sessions/{stagehand.session_id}") +``` + +#### After +```python +async def main(): + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") + } + ) + + stagehand = Stagehand(config) + await stagehand.init() + + # Local browser - no session URL needed + print("Local browser initialized successfully") +``` + +## Configuration Examples for Different Providers + +### OpenAI (Default) +```python +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") + } +) +``` + +### Anthropic Claude +```python +config = StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY") + } +) +``` + +### Together AI +```python +config = StagehandConfig( + model_name="meta-llama/Llama-2-7b-chat-hf", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": os.getenv("TOGETHER_API_KEY") + } +) +``` + +### Groq +```python +config = StagehandConfig( + model_name="llama2-70b-4096", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": os.getenv("GROQ_API_KEY") + } +) +``` + +### Local OpenAI-Compatible Server +```python +config = StagehandConfig( + model_name="local/custom-model", + model_client_options={ + "api_base": "http://localhost:8000/v1", + "api_key": "local-key", + "timeout": 120 # Local servers might be slower + } +) +``` + +## Browser Configuration Options + +The new version provides extensive browser customization: + +```python +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={"api_key": os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={ + # Basic options + "headless": True, # Run without GUI + "viewport": {"width": 1920, "height": 1080}, + + # Data persistence + "user_data_dir": "./browser_data", + + # Downloads + "downloads_path": "./downloads", + + # Chrome arguments + "args": [ + "--no-sandbox", + "--disable-dev-shm-usage", + "--disable-gpu" + ] + } +) +``` + +## Testing Migration + +### Update Test Configuration + +#### Before +```python +@pytest.fixture +def browserbase_config(): + return StagehandConfig( + env="BROWSERBASE", + api_key=os.getenv("BROWSERBASE_API_KEY"), + project_id=os.getenv("BROWSERBASE_PROJECT_ID") + ) +``` + +#### After +```python +@pytest.fixture +def local_config(): + return StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") + }, + local_browser_launch_options={"headless": True} + ) +``` + +### Update Test Cases + +All existing test functionality remains the same - only configuration changes: + +```python +async def test_page_extract(local_config): + async with Stagehand(config=local_config) as stagehand: + page = stagehand.page + await page.goto("https://example.com") + + result = await page.extract("the page title") + assert result is not None +``` + +## Common Issues and Solutions + +### Issue: "Browserbase API key not found" +**Solution**: Remove all Browserbase-related environment variables and configuration. Use the new `model_client_options` format. + +### Issue: "Browser failed to launch" +**Solution**: Ensure Playwright browsers are installed: +```bash +playwright install +``` + +### Issue: "API key not found" +**Solution**: Set the appropriate environment variable for your LLM provider: +```bash +export OPENAI_API_KEY=your-key +# or +export ANTHROPIC_API_KEY=your-key +``` + +### Issue: Windows compatibility problems +**Solution**: The new version has improved Windows support. Use PowerShell and ensure paths use forward slashes or proper escaping. + +## Performance Considerations + +### Benefits of Local Configuration +- **Faster startup**: No API calls to create browser sessions +- **Lower latency**: Direct browser communication +- **Better reliability**: No dependency on external browser service +- **Cost savings**: No Browserbase subscription needed + +### Resource Usage +- **Memory**: Local browsers use more local memory +- **CPU**: Browser processes run on your machine +- **Storage**: Browser data stored locally (configurable) + +## Rollback Plan + +If you need to temporarily rollback: + +1. **Pin the old version** in your requirements: + ```bash + pip install stagehand==0.4.x # Replace with last Browserbase version + ``` + +2. **Keep old configuration** in a separate branch +3. **Test thoroughly** before upgrading production systems + +## Frequently Asked Questions (FAQ) + +### General Migration Questions + +**Q: Will my existing automation scripts still work after migration?** +A: Yes! The core API methods (`page.act()`, `page.extract()`, `page.observe()`, `agent.execute()`) remain completely unchanged. Only the configuration setup needs to be updated. + +**Q: Do I need to rewrite my browser automation logic?** +A: No. All your existing automation code will work exactly the same way. The change is only in how you configure Stagehand, not how you use it. + +**Q: Can I still use the same LLM models I was using before?** +A: Absolutely! You can use the same models (like `gpt-4o`, `gpt-4o-mini`, etc.), and now you have even more flexibility to use different providers or custom endpoints. + +**Q: What happens to my existing test suites?** +A: Your test logic remains the same. You'll only need to update the configuration fixtures to use the new local format instead of Browserbase. + +### Performance and Reliability + +**Q: Will performance be better or worse with local browsers?** +A: Performance should be significantly better! Local browsers eliminate network latency to Browserbase servers, provide faster startup times, and give you direct control over browser resources. + +**Q: What about reliability compared to Browserbase?** +A: Local browsers are generally more reliable since you're not dependent on external services. You have full control over the browser environment and don't need to worry about API rate limits or service outages. + +**Q: How much memory will local browsers use?** +A: Local browsers typically use 100-500MB of RAM per instance, depending on the pages you're automating. You can control this with the `headless` option and browser arguments. + +### Configuration and Setup + +**Q: Can I use multiple LLM providers in the same application?** +A: Yes! You can create different `StagehandConfig` instances for different providers and switch between them as needed. + +**Q: How do I handle API keys securely?** +A: Use environment variables (recommended) or a secure configuration management system. Never hardcode API keys in your source code. + +**Q: What if I want to use a custom or self-hosted LLM?** +A: The new version supports any OpenAI-compatible API endpoint. Just set the `api_base` in your `model_client_options` to point to your custom server. + +**Q: Can I still run headless browsers for CI/CD?** +A: Yes! Set `"headless": True` in your `local_browser_launch_options`. This is actually easier now since you don't need to manage Browserbase sessions. + +### Migration Process + +**Q: How long does the migration typically take?** +A: For most projects, migration takes 15-30 minutes. It's mainly updating configuration and removing Browserbase imports. + +**Q: Can I migrate gradually or do I need to do everything at once?** +A: You can migrate gradually. Update one script at a time and test each one before moving to the next. + +**Q: What if I encounter errors during migration?** +A: Use the migration utility (`python docs/migration_utility.py`) to identify issues, check the troubleshooting guide, and enable verbose logging (`verbose=2`) to see detailed error messages. + +**Q: Is there a way to validate my migration before going live?** +A: Yes! Run your existing test suite with the new configuration, and use the validation script provided in the migration guide. + +### Browser and System Compatibility + +**Q: Does this work on Windows, macOS, and Linux?** +A: Yes! The new version has improved cross-platform support, with particular improvements for Windows 11 PowerShell compatibility. + +**Q: What browsers are supported?** +A: Stagehand uses Playwright, so it supports Chromium, Firefox, and WebKit. Chromium is the default and most tested option. + +**Q: Can I use my existing browser profile or extensions?** +A: Yes! Use the `user_data_dir` option in `local_browser_launch_options` to specify a persistent browser profile directory. + +### Troubleshooting + +**Q: I'm getting "browserbase module not found" errors** +A: Remove all `import browserbase` and `from browserbase import` statements from your code. The new version doesn't use the browserbase package. + +**Q: My API key isn't working** +A: Make sure you've moved your LLM API key to `model_client_options["api_key"]` and that you're using the correct environment variable name (e.g., `OPENAI_API_KEY`, not `BROWSERBASE_API_KEY`). + +**Q: The browser won't start on my system** +A: Run `playwright install` to ensure browser binaries are installed. On Linux, you might need additional dependencies: `playwright install-deps`. + +**Q: I'm getting timeout errors** +A: Local browsers might need different timeout settings. Increase `dom_settle_timeout_ms` or add timeout options to your `model_client_options`. + +### Advanced Usage + +**Q: Can I run multiple browser instances simultaneously?** +A: Yes! Each `Stagehand` instance manages its own browser. You can create multiple instances for parallel automation. + +**Q: How do I debug issues with the local browser?** +A: Set `"headless": False` to see the browser in action, enable verbose logging with `verbose=2`, and use browser developer tools. + +**Q: Can I customize the browser further than the provided options?** +A: Yes! The `local_browser_launch_options` accepts any Playwright browser launch option. You can also pass custom Chrome arguments via the `args` array. + +**Q: What about proxy support?** +A: You can configure proxies through the `local_browser_launch_options` using Playwright's proxy settings. + +## Getting Help + +If you encounter issues during migration: + +1. **Run the migration utility**: `python docs/migration_utility.py` to analyze your code +2. **Check the troubleshooting guide**: See [troubleshooting.md](troubleshooting.md) for common issues +3. **Enable verbose logging**: Set `verbose=2` in your config for detailed error messages +4. **Review configuration**: Double-check your `model_client_options` and API keys +5. **Test incrementally**: Migrate one script at a time to isolate issues +6. **Check examples**: Look at the updated examples in the `examples/` directory + +## Complete Migration Example + +Here's a complete before/after example: + +### Before (Browserbase) +```python +import asyncio +import os +from stagehand import StagehandConfig, Stagehand + +async def main(): + config = StagehandConfig( + env="BROWSERBASE", + api_key=os.getenv("BROWSERBASE_API_KEY"), + project_id=os.getenv("BROWSERBASE_PROJECT_ID"), + model_name="gpt-4o", + model_api_key=os.getenv("OPENAI_API_KEY") + ) + + async with Stagehand(config=config) as stagehand: + if stagehand.env == "BROWSERBASE": + print(f"Session: https://www.browserbase.com/sessions/{stagehand.session_id}") + + page = stagehand.page + await page.goto("https://example.com") + result = await page.extract("the page title") + print(f"Title: {result}") + +if __name__ == "__main__": + asyncio.run(main()) +``` + +### After (Local) +```python +import asyncio +import os +from stagehand import StagehandConfig, Stagehand + +async def main(): + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY"), + "api_base": "https://api.openai.com/v1" + }, + local_browser_launch_options={ + "headless": False, + "viewport": {"width": 1280, "height": 720} + } + ) + + async with Stagehand(config=config) as stagehand: + print("Local browser initialized successfully") + + page = stagehand.page + await page.goto("https://example.com") + result = await page.extract("the page title") + print(f"Title: {result}") + +if __name__ == "__main__": + asyncio.run(main()) +``` + +The migration is straightforward - the core functionality remains identical, only the configuration format has changed to be more flexible and support multiple LLM providers. \ No newline at end of file diff --git a/docs/migration_utility.py b/docs/migration_utility.py new file mode 100644 index 00000000..f711e4b2 --- /dev/null +++ b/docs/migration_utility.py @@ -0,0 +1,235 @@ +#!/usr/bin/env python3 +""" +Stagehand Browserbase Migration Utility + +This script helps users migrate from Browserbase-based configurations to the new local-only setup. +It analyzes existing code and provides migration suggestions. +""" + +import os +import re +import sys +from pathlib import Path +from typing import List, Dict, Any, Optional +import argparse + + +class BrowserbaseMigrationAnalyzer: + """Analyzes code for Browserbase usage and suggests migrations.""" + + def __init__(self): + self.browserbase_patterns = [ + r'env\s*=\s*["\']BROWSERBASE["\']', + r'BROWSERBASE', + r'browserbase_session_id', + r'browserbase_session_create_params', + r'api_key\s*=.*browserbase', + r'project_id\s*=', + r'api_url\s*=.*browserbase', + r'use_api\s*=\s*True', + r'connect_browserbase_browser', + r'from browserbase import', + r'import browserbase', + ] + + self.migration_suggestions = { + 'env="BROWSERBASE"': 'Remove env parameter (defaults to local mode)', + 'api_key=': 'Move to model_client_options["api_key"] for LLM API key', + 'project_id=': 'Remove project_id (not needed for local mode)', + 'api_url=': 'Remove api_url (not needed for local mode)', + 'browserbase_session_id=': 'Remove browserbase_session_id', + 'browserbase_session_create_params=': 'Remove browserbase_session_create_params', + 'use_api=True': 'Remove use_api parameter', + 'connect_browserbase_browser': 'Use connect_browser instead', + 'from browserbase import': 'Remove browserbase imports', + 'import browserbase': 'Remove browserbase imports', + } + + def analyze_file(self, file_path: Path) -> Dict[str, Any]: + """Analyze a single file for Browserbase usage.""" + try: + with open(file_path, 'r', encoding='utf-8') as f: + content = f.read() + except Exception as e: + return {'error': f'Could not read file: {e}'} + + issues = [] + for pattern in self.browserbase_patterns: + matches = re.finditer(pattern, content, re.IGNORECASE) + for match in matches: + line_num = content[:match.start()].count('\n') + 1 + matched_text = match.group() + suggestion = self._get_suggestion(matched_text) + issues.append({ + 'line': line_num, + 'text': matched_text, + 'suggestion': suggestion, + 'pattern': pattern + }) + + return { + 'file': str(file_path), + 'issues': issues, + 'needs_migration': len(issues) > 0 + } + + def _get_suggestion(self, matched_text: str) -> str: + """Get migration suggestion for matched text.""" + for key, suggestion in self.migration_suggestions.items(): + if key.lower() in matched_text.lower(): + return suggestion + return 'Review and update according to migration guide' + + def analyze_directory(self, directory: Path, extensions: List[str] = None) -> List[Dict[str, Any]]: + """Analyze all files in a directory.""" + if extensions is None: + extensions = ['.py', '.ipynb', '.md', '.txt'] + + results = [] + for file_path in directory.rglob('*'): + if file_path.is_file() and file_path.suffix in extensions: + # Skip certain directories + if any(skip in str(file_path) for skip in ['.git', '__pycache__', '.pytest_cache', 'node_modules']): + continue + + result = self.analyze_file(file_path) + if result.get('needs_migration', False): + results.append(result) + + return results + + +def generate_migration_config(old_config: Dict[str, Any]) -> Dict[str, Any]: + """Generate new configuration from old Browserbase configuration.""" + new_config = {} + + # Copy non-Browserbase fields + keep_fields = [ + 'model_name', 'verbose', 'logger', 'use_rich_logging', + 'dom_settle_timeout_ms', 'enable_caching', 'self_heal', + 'wait_for_captcha_solves', 'system_prompt', 'experimental' + ] + + for field in keep_fields: + if field in old_config: + new_config[field] = old_config[field] + + # Handle model API configuration + model_client_options = {} + + # Move API key to model_client_options if it was for LLM + if 'model_api_key' in old_config: + model_client_options['api_key'] = old_config['model_api_key'] + + # Add custom API base if needed + if 'custom_api_base' in old_config: + model_client_options['api_base'] = old_config['custom_api_base'] + + if model_client_options: + new_config['model_client_options'] = model_client_options + + # Handle browser launch options + browser_options = {} + if 'headless' in old_config: + browser_options['headless'] = old_config['headless'] + if 'viewport' in old_config: + browser_options['viewport'] = old_config['viewport'] + + if browser_options: + new_config['local_browser_launch_options'] = browser_options + + return new_config + + +def print_migration_report(results: List[Dict[str, Any]]): + """Print a detailed migration report.""" + print("=" * 60) + print("STAGEHAND BROWSERBASE MIGRATION REPORT") + print("=" * 60) + + if not results: + print("✅ No Browserbase usage detected. Your code appears to be already migrated!") + return + + print(f"Found {len(results)} files that need migration:\n") + + for result in results: + print(f"📁 File: {result['file']}") + print(f" Issues found: {len(result['issues'])}") + + for issue in result['issues']: + print(f" Line {issue['line']}: {issue['text']}") + print(f" → {issue['suggestion']}") + print() + + print("=" * 60) + print("NEXT STEPS:") + print("1. Review the migration guide: docs/migration_guide.md") + print("2. Update your configuration according to the suggestions above") + print("3. Test your updated code with the new local-only setup") + print("4. Remove browserbase from your requirements.txt") + print("=" * 60) + + +def main(): + parser = argparse.ArgumentParser(description='Migrate from Browserbase to local Stagehand setup') + parser.add_argument('path', nargs='?', default='.', help='Path to analyze (default: current directory)') + parser.add_argument('--extensions', nargs='+', default=['.py', '.ipynb', '.md'], + help='File extensions to analyze') + parser.add_argument('--config-example', action='store_true', + help='Show configuration migration example') + + args = parser.parse_args() + + if args.config_example: + print("Configuration Migration Example:") + print("=" * 40) + print("OLD (Browserbase):") + print(""" +from stagehand import StagehandConfig + +config = StagehandConfig( + env="BROWSERBASE", + api_key="bb_your_browserbase_key", + project_id="your_project_id", + model_name="gpt-4o", + model_api_key="your_openai_key" +) + """) + + print("NEW (Local):") + print(""" +from stagehand import StagehandConfig + +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": "your_openai_key" + }, + local_browser_launch_options={ + "headless": False + } +) + """) + return + + analyzer = BrowserbaseMigrationAnalyzer() + path = Path(args.path) + + if not path.exists(): + print(f"Error: Path '{path}' does not exist") + sys.exit(1) + + print(f"Analyzing {path} for Browserbase usage...") + + if path.is_file(): + results = [analyzer.analyze_file(path)] + results = [r for r in results if r.get('needs_migration', False)] + else: + results = analyzer.analyze_directory(path, args.extensions) + + print_migration_report(results) + + +if __name__ == '__main__': + main() \ No newline at end of file diff --git a/docs/run_migration_check.ps1 b/docs/run_migration_check.ps1 new file mode 100644 index 00000000..9e1b9de6 --- /dev/null +++ b/docs/run_migration_check.ps1 @@ -0,0 +1,88 @@ +# PowerShell script to run migration analysis and validation +# Usage: .\docs\run_migration_check.ps1 [path_to_analyze] + +param( + [string]$Path = ".", + [switch]$Validate, + [switch]$Help +) + +if ($Help) { + Write-Host "Stagehand Migration Helper" -ForegroundColor Green + Write-Host "=========================" -ForegroundColor Green + Write-Host "" + Write-Host "Usage:" + Write-Host " .\docs\run_migration_check.ps1 [options]" + Write-Host "" + Write-Host "Options:" + Write-Host " -Path Path to analyze (default: current directory)" + Write-Host " -Validate Run migration validation after analysis" + Write-Host " -Help Show this help message" + Write-Host "" + Write-Host "Examples:" + Write-Host " .\docs\run_migration_check.ps1 # Analyze current directory" + Write-Host " .\docs\run_migration_check.ps1 -Path .\examples # Analyze examples directory" + Write-Host " .\docs\run_migration_check.ps1 -Validate # Run analysis and validation" + exit 0 +} + +Write-Host "🔍 Stagehand Migration Analysis" -ForegroundColor Cyan +Write-Host "===============================" -ForegroundColor Cyan + +# Check if Python is available +try { + $pythonVersion = python --version 2>&1 + Write-Host "✅ Python found: $pythonVersion" -ForegroundColor Green +} catch { + Write-Host "❌ Python not found. Please install Python first." -ForegroundColor Red + exit 1 +} + +# Run migration analysis +Write-Host "" +Write-Host "Running migration analysis on: $Path" -ForegroundColor Yellow +Write-Host "" + +try { + python docs/migration_utility.py $Path + $analysisResult = $LASTEXITCODE +} catch { + Write-Host "❌ Failed to run migration analysis: $_" -ForegroundColor Red + exit 1 +} + +# Run validation if requested +if ($Validate) { + Write-Host "" + Write-Host "Running migration validation..." -ForegroundColor Yellow + Write-Host "" + + try { + python docs/validate_migration.py + $validationResult = $LASTEXITCODE + } catch { + Write-Host "❌ Failed to run migration validation: $_" -ForegroundColor Red + exit 1 + } + + if ($validationResult -eq 0) { + Write-Host "" + Write-Host "🎉 Migration validation completed successfully!" -ForegroundColor Green + } else { + Write-Host "" + Write-Host "⚠️ Migration validation completed with issues." -ForegroundColor Yellow + Write-Host "Please review the output above and address any errors." -ForegroundColor Yellow + } +} + +Write-Host "" +Write-Host "📚 Additional Resources:" -ForegroundColor Cyan +Write-Host "• Migration Guide: docs/migration_guide.md" +Write-Host "• Troubleshooting: docs/troubleshooting.md" +Write-Host "• Examples: examples/ directory" + +if ($analysisResult -ne 0 -or ($Validate -and $validationResult -ne 0)) { + exit 1 +} else { + exit 0 +} \ No newline at end of file diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md new file mode 100644 index 00000000..131690e3 --- /dev/null +++ b/docs/troubleshooting.md @@ -0,0 +1,581 @@ +# Troubleshooting Guide + +This guide helps you resolve common issues when using Stagehand with local browser configuration and custom LLM providers. + +## Migration-Specific Issues + +### Browserbase Removal Errors + +#### Error: "ModuleNotFoundError: No module named 'browserbase'" +``` +ModuleNotFoundError: No module named 'browserbase' +``` + +**Solutions:** +1. **Remove browserbase imports:** + ```python + # Remove these lines + import browserbase + from browserbase import Browserbase + ``` + +2. **Uninstall browserbase package:** + ```bash + pip uninstall browserbase + ``` + +3. **Update requirements.txt:** + ```txt + # Remove this line + browserbase>=1.0.0 + ``` + +#### Error: "StagehandConfig has no attribute 'env'" +``` +AttributeError: 'StagehandConfig' has no attribute 'env' +``` + +**Solutions:** +1. **Remove env parameter:** + ```python + # OLD - Remove this + config = StagehandConfig(env="BROWSERBASE", ...) + + # NEW - Use this + config = StagehandConfig(model_name="gpt-4o", ...) + ``` + +#### Error: "Browserbase API key not recognized" +``` +StagehandConfigError: 'api_key' parameter not recognized +``` + +**Solutions:** +1. **Move API key to model_client_options:** + ```python + # OLD - Remove this + config = StagehandConfig(api_key="bb_browserbase_key", ...) + + # NEW - Use this for LLM API key + config = StagehandConfig( + model_client_options={"api_key": "your_llm_api_key"} + ) + ``` + +#### Error: "project_id parameter not found" +``` +TypeError: StagehandConfig() got an unexpected keyword argument 'project_id' +``` + +**Solutions:** +1. **Remove project_id completely:** + ```python + # OLD - Remove this + config = StagehandConfig(project_id="browserbase_project", ...) + + # NEW - Not needed + config = StagehandConfig(model_name="gpt-4o", ...) + ``` + +#### Error: "browserbase_session_id not supported" +``` +TypeError: StagehandConfig() got an unexpected keyword argument 'browserbase_session_id' +``` + +**Solutions:** +1. **Remove all session-related parameters:** + ```python + # Remove these parameters + browserbase_session_id="session_123" + browserbase_session_create_params={...} + use_api=True + ``` + +### Configuration Migration Issues + +#### Error: "model_api_key deprecated" +``` +DeprecationWarning: model_api_key is deprecated, use model_client_options instead +``` + +**Solutions:** +1. **Update to new format:** + ```python + # OLD + config = StagehandConfig( + model_api_key="your_openai_key" + ) + + # NEW + config = StagehandConfig( + model_client_options={ + "api_key": "your_openai_key" + } + ) + ``` + +#### Error: "headless parameter not found" +``` +TypeError: StagehandConfig() got an unexpected keyword argument 'headless' +``` + +**Solutions:** +1. **Move to local_browser_launch_options:** + ```python + # OLD + config = StagehandConfig(headless=True, ...) + + # NEW + config = StagehandConfig( + local_browser_launch_options={"headless": True} + ) + ``` + +## Configuration Issues + +### API Key Errors + +#### Error: "API key not found" +``` +LLMProviderError: API key error for model gpt-4o. Please check your API key configuration in model_client_options. +``` + +**Solutions:** +1. **Set environment variable:** + ```bash + export OPENAI_API_KEY=your-api-key + # On Windows PowerShell: + $env:OPENAI_API_KEY="your-api-key" + ``` + +2. **Specify in configuration:** + ```python + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": "your-api-key" # Direct specification + } + ) + ``` + +3. **Check environment variable loading:** + ```python + import os + from dotenv import load_dotenv + + load_dotenv() # Load from .env file + print(f"API Key loaded: {bool(os.getenv('OPENAI_API_KEY'))}") + ``` + +#### Error: "Unauthorized access" +``` +LLMProviderError: Unauthorized access for model gpt-4o. Please check your API key and permissions. +``` + +**Solutions:** +1. **Verify API key validity** on your provider's dashboard +2. **Check API key permissions** (ensure it has the required scopes) +3. **Verify billing status** (some providers require active billing) + +### Model Configuration Issues + +#### Error: "Model not found" +``` +LLMProviderError: Model gpt-4o not found. Please check the model name and your API endpoint configuration. +``` + +**Solutions:** +1. **Check model name spelling:** + ```python + # Correct model names + "gpt-4o-mini" # OpenAI + "claude-3-haiku-20240307" # Anthropic + "meta-llama/Llama-2-7b-chat-hf" # Together AI + ``` + +2. **Verify model availability** with your provider +3. **Check API endpoint compatibility:** + ```python + config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", # Correct endpoint + "api_key": os.getenv("OPENAI_API_KEY") + } + ) + ``` + +### Custom Endpoint Issues + +#### Error: "Connection failed to custom endpoint" +``` +ConnectionError: Failed to connect to https://api.custom-provider.com/v1 +``` + +**Solutions:** +1. **Verify endpoint URL:** + ```python + # Ensure URL is complete and correct + "api_base": "https://api.together.xyz/v1" # Include /v1 if required + ``` + +2. **Test endpoint manually:** + ```bash + curl -H "Authorization: Bearer your-api-key" https://api.custom-provider.com/v1/models + ``` + +3. **Check network connectivity and firewall settings** + +## Browser Issues + +### Browser Launch Failures + +#### Error: "Browser failed to launch" +``` +BrowserConnectionError: Failed to launch browser +``` + +**Solutions:** +1. **Install Playwright browsers:** + ```bash + playwright install + # Or specific browser: + playwright install chromium + ``` + +2. **Check system requirements:** + - Sufficient RAM (minimum 2GB available) + - Disk space for browser installation + - Required system libraries (Linux) + +3. **Try different browser options:** + ```python + config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={"api_key": os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={ + "headless": True, # Try headless mode + "args": ["--no-sandbox", "--disable-dev-shm-usage"] + } + ) + ``` + +#### Error: "Permission denied" (Linux/macOS) +``` +PermissionError: [Errno 13] Permission denied: '/path/to/browser' +``` + +**Solutions:** +1. **Fix browser permissions:** + ```bash + chmod +x ~/.cache/ms-playwright/chromium-*/chrome-linux/chrome + ``` + +2. **Run with proper user permissions** +3. **Install system dependencies (Linux):** + ```bash + # Ubuntu/Debian + sudo apt-get install -y libnss3 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxrandr2 libgbm1 libxss1 libasound2 + ``` + +### Windows-Specific Issues + +#### Error: "PowerShell execution policy" +``` +ExecutionPolicy: Execution of scripts is disabled on this system +``` + +**Solutions:** +1. **Update execution policy:** + ```powershell + Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser + ``` + +2. **Run scripts with bypass:** + ```powershell + powershell -ExecutionPolicy Bypass -File script.ps1 + ``` + +#### Error: "Path too long" (Windows) +``` +OSError: [Errno 2] No such file or directory (path too long) +``` + +**Solutions:** +1. **Enable long path support:** + - Run `gpedit.msc` as administrator + - Navigate to: Computer Configuration > Administrative Templates > System > Filesystem + - Enable "Enable Win32 long paths" + +2. **Use shorter paths:** + ```python + config = StagehandConfig( + local_browser_launch_options={ + "user_data_dir": "C:/tmp/browser" # Shorter path + } + ) + ``` + +## Performance Issues + +### Slow Browser Startup + +**Solutions:** +1. **Use persistent browser data:** + ```python + config = StagehandConfig( + local_browser_launch_options={ + "user_data_dir": "./browser_data" # Reuse browser profile + } + ) + ``` + +2. **Optimize browser arguments:** + ```python + config = StagehandConfig( + local_browser_launch_options={ + "args": [ + "--disable-extensions", + "--disable-plugins", + "--disable-images", # For faster loading + "--disable-javascript" # If JS not needed + ] + } + ) + ``` + +3. **Use headless mode:** + ```python + config = StagehandConfig( + local_browser_launch_options={"headless": True} + ) + ``` + +### High Memory Usage + +**Solutions:** +1. **Limit browser resources:** + ```python + config = StagehandConfig( + local_browser_launch_options={ + "args": [ + "--memory-pressure-off", + "--max_old_space_size=2048" + ] + } + ) + ``` + +2. **Close browser properly:** + ```python + try: + # Your automation code + pass + finally: + await stagehand.close() # Always close + ``` + +3. **Use context managers:** + ```python + async with Stagehand(config=config) as stagehand: + # Automatic cleanup + pass + ``` + +## LLM Provider Issues + +### Rate Limiting + +#### Error: "Rate limit exceeded" +``` +LLMProviderError: Rate limit exceeded for model gpt-4o. Please try again later or check your usage limits. +``` + +**Solutions:** +1. **Implement retry logic:** + ```python + config = StagehandConfig( + model_client_options={ + "max_retries": 5, + "timeout": 60 + } + ) + ``` + +2. **Use exponential backoff:** + ```python + import asyncio + import random + + async def retry_with_backoff(func, max_retries=3): + for attempt in range(max_retries): + try: + return await func() + except Exception as e: + if "rate limit" in str(e).lower() and attempt < max_retries - 1: + wait_time = (2 ** attempt) + random.uniform(0, 1) + await asyncio.sleep(wait_time) + else: + raise + ``` + +3. **Switch to different model/provider temporarily** + +### Token Limit Issues + +#### Error: "Token limit exceeded" +``` +LLMProviderError: Token limit exceeded for model gpt-4o-mini +``` + +**Solutions:** +1. **Use models with larger context windows:** + ```python + config = StagehandConfig( + model_name="gpt-4o", # Larger context than gpt-4o-mini + model_client_options={"api_key": os.getenv("OPENAI_API_KEY")} + ) + ``` + +2. **Reduce DOM content:** + ```python + # Extract specific elements instead of full page + result = await page.extract("specific element text", selector="div.content") + ``` + +3. **Use observe for action planning:** + ```python + # Get action plan first (smaller response) + action = await page.observe("find the login button") + # Then execute without additional LLM call + await page.act(action) + ``` + +## Testing Issues + +### Test Configuration + +#### Error: "Tests fail with local configuration" +```python +# Update test fixtures +@pytest.fixture +def stagehand_config(): + return StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") + }, + local_browser_launch_options={"headless": True} # Important for CI + ) +``` + +### CI/CD Issues + +#### Error: "Browser not found in CI" +```yaml +# GitHub Actions example +- name: Install Playwright + run: | + pip install playwright + playwright install --with-deps chromium +``` + +#### Error: "Display not found" (Linux CI) +```yaml +# Add virtual display for non-headless testing +- name: Setup virtual display + run: | + sudo apt-get install -y xvfb + export DISPLAY=:99 + Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 & +``` + +## Debugging Tips + +### Enable Verbose Logging + +```python +config = StagehandConfig( + verbose=2, # Maximum verbosity + use_rich_logging=True, # Pretty console output + model_client_options={"api_key": os.getenv("OPENAI_API_KEY")} +) +``` + +### Custom Logger + +```python +def custom_logger(message): + print(f"[DEBUG] {message}") + +config = StagehandConfig( + logger=custom_logger, + model_client_options={"api_key": os.getenv("OPENAI_API_KEY")} +) +``` + +### Browser Developer Tools + +```python +config = StagehandConfig( + local_browser_launch_options={ + "headless": False, + "devtools": True # Open DevTools automatically + } +) +``` + +### Network Debugging + +```python +# Monitor network requests +async with Stagehand(config=config) as stagehand: + page = stagehand.page + + # Enable request logging + page.on("request", lambda request: print(f"Request: {request.url}")) + page.on("response", lambda response: print(f"Response: {response.status} {response.url}")) + + await page.goto("https://example.com") +``` + +## Getting Help + +If these solutions don't resolve your issue: + +1. **Check the logs** with verbose logging enabled +2. **Search existing issues** on GitHub +3. **Join our community** on [Slack](https://stagehand.dev/slack) +4. **Create a minimal reproduction** case +5. **Include system information** (OS, Python version, Stagehand version) + +### Issue Template + +When reporting issues, include: + +``` +**Environment:** +- OS: [Windows 11/macOS/Linux] +- Python: [3.9/3.10/3.11/3.12] +- Stagehand: [version] + +**Configuration:** +```python +config = StagehandConfig( + # Your configuration here +) +``` + +**Error:** +``` +Full error traceback here +``` + +**Expected behavior:** +What you expected to happen + +**Actual behavior:** +What actually happened +``` + +This information helps us provide faster and more accurate support. \ No newline at end of file diff --git a/docs/validate_migration.py b/docs/validate_migration.py new file mode 100644 index 00000000..0b05e496 --- /dev/null +++ b/docs/validate_migration.py @@ -0,0 +1,272 @@ +#!/usr/bin/env python3 +""" +Stagehand Migration Validation Script + +This script validates that your migration from Browserbase to local setup is working correctly. +Run this after completing your migration to ensure everything is configured properly. +""" + +import asyncio +import os +import sys +from pathlib import Path +from typing import Optional + +try: + from stagehand import Stagehand, StagehandConfig +except ImportError: + print("❌ Stagehand not installed. Please install with: pip install stagehand") + sys.exit(1) + + +class MigrationValidator: + """Validates Stagehand migration setup.""" + + def __init__(self): + self.errors = [] + self.warnings = [] + self.success_count = 0 + self.total_checks = 0 + + def check(self, condition: bool, success_msg: str, error_msg: str, warning: bool = False): + """Check a condition and record the result.""" + self.total_checks += 1 + if condition: + print(f"✅ {success_msg}") + self.success_count += 1 + else: + if warning: + print(f"⚠️ {error_msg}") + self.warnings.append(error_msg) + else: + print(f"❌ {error_msg}") + self.errors.append(error_msg) + + def validate_environment(self): + """Validate environment setup.""" + print("\n🔍 Validating Environment Setup...") + + # Check for API keys + openai_key = os.getenv("OPENAI_API_KEY") + anthropic_key = os.getenv("ANTHROPIC_API_KEY") + together_key = os.getenv("TOGETHER_API_KEY") + + has_any_key = any([openai_key, anthropic_key, together_key]) + self.check( + has_any_key, + "LLM API key found in environment", + "No LLM API keys found. Set OPENAI_API_KEY, ANTHROPIC_API_KEY, or TOGETHER_API_KEY" + ) + + # Check for old Browserbase keys (should be warnings) + browserbase_key = os.getenv("BROWSERBASE_API_KEY") + browserbase_project = os.getenv("BROWSERBASE_PROJECT_ID") + + self.check( + not browserbase_key, + "No old Browserbase API key found", + "Old BROWSERBASE_API_KEY still set - you can remove this", + warning=True + ) + + self.check( + not browserbase_project, + "No old Browserbase project ID found", + "Old BROWSERBASE_PROJECT_ID still set - you can remove this", + warning=True + ) + + def validate_configuration(self): + """Validate configuration creation.""" + print("\n🔍 Validating Configuration...") + + try: + # Test basic configuration + config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") or "test-key" + } + ) + self.check(True, "Basic configuration created successfully", "") + + # Test with browser options + config_with_browser = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") or "test-key" + }, + local_browser_launch_options={ + "headless": True, + "viewport": {"width": 1280, "height": 720} + } + ) + self.check(True, "Configuration with browser options created successfully", "") + + except Exception as e: + self.check(False, "", f"Configuration creation failed: {e}") + + async def validate_runtime(self): + """Validate runtime functionality.""" + print("\n🔍 Validating Runtime Functionality...") + + # Check if we have a real API key for testing + api_key = os.getenv("OPENAI_API_KEY") + if not api_key: + print("⚠️ Skipping runtime tests - no OPENAI_API_KEY set") + return + + config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={"api_key": api_key}, + local_browser_launch_options={"headless": True} + ) + + stagehand = None + try: + # Test initialization + stagehand = Stagehand(config) + await stagehand.init() + self.check(True, "Stagehand initialized successfully", "") + + # Test browser navigation + page = stagehand.page + await page.goto("https://example.com") + self.check(True, "Browser navigation works", "") + + # Test basic extraction + try: + title = await page.extract("the page title") + self.check( + title is not None and len(str(title).strip()) > 0, + f"Extraction works: '{title}'", + "Extraction returned empty result" + ) + except Exception as e: + self.check(False, "", f"Extraction failed: {e}") + + except Exception as e: + self.check(False, "", f"Runtime validation failed: {e}") + + finally: + if stagehand: + try: + await stagehand.close() + self.check(True, "Cleanup successful", "") + except Exception as e: + self.check(False, "", f"Cleanup failed: {e}") + + def validate_file_cleanup(self): + """Check for leftover Browserbase files.""" + print("\n🔍 Checking for Leftover Files...") + + # Check common locations for browserbase imports + python_files = list(Path(".").rglob("*.py")) + browserbase_files = [] + + for file_path in python_files: + if any(skip in str(file_path) for skip in ['.git', '__pycache__', '.pytest_cache']): + continue + + try: + with open(file_path, 'r', encoding='utf-8') as f: + content = f.read() + if 'browserbase' in content.lower() and 'import' in content: + browserbase_files.append(str(file_path)) + except: + continue + + self.check( + len(browserbase_files) == 0, + "No browserbase imports found in Python files", + f"Found browserbase imports in: {', '.join(browserbase_files)}", + warning=True + ) + + # Check requirements.txt + req_files = ["requirements.txt", "pyproject.toml", "setup.py"] + for req_file in req_files: + if Path(req_file).exists(): + try: + with open(req_file, 'r') as f: + content = f.read() + has_browserbase = 'browserbase' in content.lower() + self.check( + not has_browserbase, + f"No browserbase dependency in {req_file}", + f"Found browserbase dependency in {req_file}", + warning=True + ) + except: + pass + + def print_summary(self): + """Print validation summary.""" + print("\n" + "="*60) + print("MIGRATION VALIDATION SUMMARY") + print("="*60) + + print(f"✅ Successful checks: {self.success_count}/{self.total_checks}") + + if self.warnings: + print(f"⚠️ Warnings: {len(self.warnings)}") + for warning in self.warnings: + print(f" • {warning}") + + if self.errors: + print(f"❌ Errors: {len(self.errors)}") + for error in self.errors: + print(f" • {error}") + + print("\n" + "="*60) + + if not self.errors: + if self.warnings: + print("🎉 Migration validation passed with warnings!") + print(" Your setup should work, but consider addressing the warnings above.") + else: + print("🎉 Migration validation passed completely!") + print(" Your Stagehand setup is ready to use.") + else: + print("❌ Migration validation failed!") + print(" Please address the errors above before using Stagehand.") + + print("="*60) + + return len(self.errors) == 0 + + +async def main(): + """Run migration validation.""" + print("🚀 Stagehand Migration Validation") + print("This script validates your migration from Browserbase to local setup.") + print("="*60) + + validator = MigrationValidator() + + # Run validation steps + validator.validate_environment() + validator.validate_configuration() + await validator.validate_runtime() + validator.validate_file_cleanup() + + # Print summary and exit + success = validator.print_summary() + + if success: + print("\n📚 Next steps:") + print("1. Run your existing automation scripts to test them") + print("2. Update any remaining test configurations") + print("3. Check the examples/ directory for reference implementations") + print("4. Review docs/migration_guide.md for additional tips") + else: + print("\n🔧 Troubleshooting:") + print("1. Check docs/troubleshooting.md for common issues") + print("2. Run the migration utility: python docs/migration_utility.py") + print("3. Enable verbose logging in your configuration") + + sys.exit(0 if success else 1) + + +if __name__ == "__main__": + asyncio.run(main()) \ No newline at end of file diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 00000000..3dfb8462 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,284 @@ +# Stagehand Examples + +This directory contains examples demonstrating how to use Stagehand with local browser automation and custom LLM endpoints. + +## Prerequisites + +Before running the examples, make sure you have: + +1. **Python 3.8+** installed +2. **Chrome/Chromium browser** installed (Playwright will use this) +3. **LLM Provider API Key** - at least one of: + - OpenAI API key (`OPENAI_API_KEY`) + - Anthropic API key (`ANTHROPIC_API_KEY`) + - Groq API key (`GROQ_API_KEY`) + - Together AI API key (`TOGETHER_API_KEY`) + +## Environment Setup + +### Option 1: Using .env file (Recommended) + +Create a `.env` file in the project root: + +```bash +# OpenAI (recommended for getting started) +OPENAI_API_KEY=your-openai-api-key-here + +# Or use other providers +# ANTHROPIC_API_KEY=your-anthropic-api-key-here +# GROQ_API_KEY=your-groq-api-key-here +# TOGETHER_API_KEY=your-together-api-key-here +``` + +### Option 2: Environment Variables + +#### On Windows PowerShell: +```powershell +$env:OPENAI_API_KEY="your-api-key-here" +python examples/quickstart.py +``` + +#### On Linux/macOS: +```bash +export OPENAI_API_KEY="your-api-key-here" +python examples/quickstart.py +``` + +## Available Examples + +### 1. `quickstart.py` - Basic Getting Started +The simplest example showing: +- Local browser automation +- Custom LLM endpoint configuration +- Structured data extraction with Pydantic +- Basic browser actions (act, extract, observe) + +```bash +python examples/quickstart.py +``` + +### 2. `example.py` - Comprehensive Demo +A more detailed example with: +- Rich console output and logging +- Multiple browser actions +- Error handling +- Step-by-step automation workflow + +```bash +python examples/example.py +``` + +### 3. `agent_example.py` - AI Agent Usage +Demonstrates the agent functionality: +- Agent-based automation +- Multi-step task execution +- Agent result handling + +```bash +python examples/agent_example.py +``` + +### 4. `custom_llm_endpoints.py` - LLM Provider Configurations +Shows how to configure different LLM providers: +- OpenAI configuration +- Anthropic Claude configuration +- Together AI configuration +- Groq configuration +- Local OpenAI-compatible servers +- Error handling and validation + +```bash +python examples/custom_llm_endpoints.py +``` + +### 5. `windows_powershell_example.py` - Windows Compatibility +Specifically designed for Windows PowerShell users: +- Windows-specific features +- PowerShell integration examples +- Multiple provider support with automatic selection +- Comprehensive error handling + +```bash +python examples/windows_powershell_example.py +``` + +### 6. `quickstart_jupyter_notebook.ipynb` - Jupyter Notebook +Interactive notebook example: +- Step-by-step tutorial +- Local browser configuration +- Multiple provider examples +- Rich documentation and explanations + +Open in Jupyter Lab/Notebook: +```bash +jupyter lab examples/quickstart_jupyter_notebook.ipynb +``` + +## Configuration Examples + +### OpenAI Configuration +```python +config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": os.getenv("OPENAI_API_KEY"), + "timeout": 30 + }, + local_browser_launch_options={ + "headless": False, + "viewport": {"width": 1280, "height": 720} + } +) +``` + +### Anthropic Configuration +```python +config = StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY"), + "timeout": 60 + }, + local_browser_launch_options={"headless": False} +) +``` + +### Together AI Configuration +```python +config = StagehandConfig( + model_name="together/llama-2-7b-chat", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": os.getenv("TOGETHER_API_KEY"), + "timeout": 45 + }, + local_browser_launch_options={"headless": False} +) +``` + +## Browser Configuration Options + +### Headless Mode +```python +local_browser_launch_options={ + "headless": True, # Run without visible browser window + "viewport": {"width": 1920, "height": 1080} +} +``` + +### Custom Browser Path +```python +local_browser_launch_options={ + "executable_path": "/path/to/chrome", # Custom browser executable + "headless": False +} +``` + +### Additional Browser Arguments +```python +local_browser_launch_options={ + "args": [ + "--disable-web-security", + "--disable-features=VizDisplayCompositor", + "--no-sandbox" + ], + "headless": False +} +``` + +## Windows PowerShell Tips + +### Setting Environment Variables +```powershell +# Set for current session +$env:OPENAI_API_KEY="your-api-key" + +# Set permanently for user +[Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "your-api-key", "User") +``` + +### Running Scripts +```powershell +# Run example +python examples/quickstart.py + +# Run with specific provider +$env:PREFERRED_PROVIDER="anthropic"; python examples/windows_powershell_example.py + +# Chain commands (use semicolon instead of &&) +python examples/quickstart.py; python examples/example.py +``` + +### Using PowerShell Scripts +```powershell +# Format code +./format.ps1 + +# Run tests +./run_tests.ps1 + +# Run tests and open coverage report +./run_tests.ps1 -Open +``` + +## Troubleshooting + +### Common Issues + +1. **"No LLM provider API keys found"** + - Make sure you've set at least one API key environment variable + - Check that the variable name is correct (e.g., `OPENAI_API_KEY`) + +2. **"Browser not found"** + - Install Chrome or Chromium browser + - Run `playwright install chromium` to install Playwright's browser + +3. **"Module not found"** + - Make sure Stagehand is installed: `pip install stagehand` + - Or install in development mode: `pip install -e .` + +4. **Windows PowerShell encoding issues** + - The examples handle UTF-8 encoding automatically + - If you see strange characters, try running in Windows Terminal + +### Getting Help + +- Check the main README.md for installation instructions +- Review the requirements.md and design.md in `.kiro/specs/browserbase-removal/` +- Look at the test files for more usage examples +- Open an issue on GitHub if you encounter problems + +## Migration from Browserbase + +If you were previously using Browserbase configuration, here's how to migrate: + +### Old Configuration (Browserbase) +```python +config = StagehandConfig( + env="BROWSERBASE", + api_key="browserbase-key", + project_id="browserbase-project", + model_name="gpt-4o" +) +``` + +### New Configuration (Local) +```python +config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": os.getenv("OPENAI_API_KEY") + }, + local_browser_launch_options={ + "headless": False + } +) +``` + +The key changes: +- Remove `env`, `api_key`, `project_id` fields +- Add `model_client_options` with LLM provider configuration +- Add `local_browser_launch_options` for browser settings +- All browser operations now use local Playwright instances \ No newline at end of file diff --git a/examples/agent_example.py b/examples/agent_example.py index 9d7e9b76..4e2991ed 100644 --- a/examples/agent_example.py +++ b/examples/agent_example.py @@ -1,12 +1,17 @@ import asyncio import logging import os +import sys +from pathlib import Path from dotenv import load_dotenv from rich.console import Console from rich.panel import Panel from rich.theme import Theme +# Ensure local stagehand package is used instead of any installed version +sys.path.insert(0, str(Path(__file__).parent.parent)) + from stagehand import Stagehand, StagehandConfig, configure_logging # Create a custom theme for consistent styling @@ -33,30 +38,38 @@ ) async def main(): - # Build a unified configuration object for Stagehand + # Build a unified configuration object for Stagehand with local browser config = StagehandConfig( - env="BROWSERBASE", - # env="LOCAL", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", + model_name="qwen-turbo", + model_client_options={ + "api_base": os.getenv("ALIBABA_ENDPOINT", "https://dashscope.aliyuncs.com/compatible-mode/v1"), + "api_key": os.getenv("ALIBABA_API_KEY"), + "timeout": 30 + }, self_heal=True, system_prompt="You are a browser automation assistant that helps users navigate websites effectively.", - model_client_options={"apiKey": os.getenv("MODEL_API_KEY")}, + local_browser_launch_options={ + "headless": False, # Set to True for headless mode + "viewport": {"width": 1280, "height": 720} + }, verbose=1, ) # Create a Stagehand client using the configuration object. stagehand = Stagehand(config) - # Initialize - this creates a new session automatically. - console.print("\n🚀 [info]Initializing Stagehand...[/]") + # Initialize - this creates a local browser session automatically. + console.print("\n🚀 [info]Initializing Stagehand with local browser...[/]") await stagehand.init() - if stagehand.env == "BROWSERBASE": - console.print(f"\n[yellow]Created new session:[/] {stagehand.session_id}") - console.print( - f"🌐 [white]View your live browser:[/] [url]https://www.browserbase.com/sessions/{stagehand.session_id}[/]" - ) + + # Validate LLM configuration + validation = stagehand.llm.validate_configuration() + if validation['valid']: + console.print(f"✓ [success]LLM configured:[/] {validation['configuration']['provider']} - {config.model_name}") + else: + console.print("⚠ [warning]LLM configuration issues:[/]", validation['errors']) + + console.print("🌐 [white]Local browser session initialized successfully[/]") console.print("\n▶️ [highlight] Navigating[/] to Google") await stagehand.page.goto("https://google.com/") @@ -66,7 +79,7 @@ async def main(): agent = stagehand.agent( model="computer-use-preview", instructions="You are a helpful web navigation assistant that helps users find information. You are currently on the following page: google.com. Do not ask follow up questions, the user will trust your judgement.", - options={"apiKey": os.getenv("MODEL_API_KEY")} + options={"api_key": os.getenv("ANTHROPIC_API_KEY")} ) agent_result = await agent.execute( instruction="Play a game of 2048", diff --git a/examples/alibaba_config_example.py b/examples/alibaba_config_example.py new file mode 100644 index 00000000..2c934454 --- /dev/null +++ b/examples/alibaba_config_example.py @@ -0,0 +1,263 @@ +#!/usr/bin/env python3 +""" +阿里巴巴通义千问配置示例 + +本示例展示如何配置和使用阿里巴巴通义千问模型： +1. 基本配置设置 +2. 环境变量配置 +3. 配置验证 +4. 常见问题解决 +""" + +import os +import sys +from pathlib import Path + +# 添加父目录到路径以便导入 stagehand +sys.path.insert(0, str(Path(__file__).parent.parent)) + +try: + from stagehand.config import StagehandConfig + from stagehand import Stagehand +except ImportError as e: + print(f"导入错误: {e}") + print("请从 stagehand-python 根目录运行此脚本") + sys.exit(1) + + +def setup_alibaba_environment(): + """设置阿里巴巴通义千问的环境变量""" + print("🔧 设置阿里巴巴通义千问环境变量") + print("-" * 40) + + # 检查是否已设置环境变量 + alibaba_api_key = os.getenv("ALIBABA_API_KEY") + alibaba_endpoint = os.getenv("ALIBABA_ENDPOINT") + + if not alibaba_api_key: + print("❌ 未找到 ALIBABA_API_KEY 环境变量") + print("请在 .env 文件中设置:") + print("ALIBABA_API_KEY=your-alibaba-api-key-here") + return False + + if not alibaba_endpoint: + print("❌ 未找到 ALIBABA_ENDPOINT 环境变量") + print("请在 .env 文件中设置:") + print("ALIBABA_ENDPOINT=https://dashscope.aliyuncs.com/compatible-mode/v1") + return False + + print(f"✅ ALIBABA_API_KEY: {alibaba_api_key[:10]}...") + print(f"✅ ALIBABA_ENDPOINT: {alibaba_endpoint}") + return True + + +def create_alibaba_config_basic(): + """创建基本的阿里巴巴配置""" + print("\n📝 基本阿里巴巴配置示例") + print("-" * 40) + + try: + config = StagehandConfig( + model_name="qwen-turbo", # 通义千问模型 + model_client_options={ + "api_base": "https://dashscope.aliyuncs.com/compatible-mode/v1", + "api_key": os.getenv("ALIBABA_API_KEY") + }, + verbose=1 + ) + + print("✅ 基本配置创建成功") + print(f" 模型: {config.model_name}") + print(f" 端点: {config.model_client_options.get('api_base')}") + return config + + except Exception as e: + print(f"❌ 配置创建失败: {e}") + return None + + +def create_alibaba_config_advanced(): + """创建高级阿里巴巴配置""" + print("\n🚀 高级阿里巴巴配置示例") + print("-" * 40) + + try: + config = StagehandConfig( + model_name="qwen-max", # 使用更强大的模型 + model_client_options={ + "api_base": os.getenv("ALIBABA_ENDPOINT"), + "api_key": os.getenv("ALIBABA_API_KEY"), + "timeout": 30, # 设置超时时间 + "max_retries": 3, # 设置重试次数 + }, + verbose=2, # 详细日志 + headless=True, # 无头模式 + debug_dom=True, # DOM 调试 + ) + + print("✅ 高级配置创建成功") + print(f" 模型: {config.model_name}") + print(f" 端点: {config.model_client_options.get('api_base')}") + print(f" 超时: {config.model_client_options.get('timeout')}秒") + print(f" 重试: {config.model_client_options.get('max_retries')}次") + return config + + except Exception as e: + print(f"❌ 高级配置创建失败: {e}") + return None + + +def test_alibaba_connection(config): + """测试阿里巴巴连接""" + print("\n🔍 测试阿里巴巴连接") + print("-" * 40) + + try: + # 创建 Stagehand 实例 + stagehand = Stagehand(config=config) + print("✅ Stagehand 实例创建成功") + + # 这里可以添加更多的连接测试 + print("✅ 阿里巴巴通义千问配置验证通过") + return True + + except Exception as e: + print(f"❌ 连接测试失败: {e}") + return False + + +def demonstrate_model_options(): + """展示可用的阿里巴巴模型选项""" + print("\n🤖 阿里巴巴通义千问可用模型") + print("-" * 40) + + models = [ + { + "name": "qwen-turbo", + "description": "通义千问超大规模语言模型，支持中文英文等不同语言输入", + "context": "8k tokens", + "use_case": "日常对话、文本生成" + }, + { + "name": "qwen-plus", + "description": "通义千问超大规模语言模型增强版", + "context": "32k tokens", + "use_case": "复杂推理、长文本处理" + }, + { + "name": "qwen-max", + "description": "通义千问千亿级别超大规模语言模型", + "context": "8k tokens", + "use_case": "最高质量的文本生成和理解" + }, + { + "name": "qwen-max-longcontext", + "description": "通义千问长上下文版本", + "context": "30k tokens", + "use_case": "长文档分析、大量信息处理" + } + ] + + for model in models: + print(f"📝 {model['name']}") + print(f" 描述: {model['description']}") + print(f" 上下文: {model['context']}") + print(f" 适用场景: {model['use_case']}") + print() + + +def show_configuration_tips(): + """显示配置建议和最佳实践""" + print("\n💡 阿里巴巴配置建议和最佳实践") + print("-" * 40) + + tips = [ + "🔑 API密钥安全: 将API密钥存储在环境变量中，不要硬编码在代码里", + "🌐 网络设置: 确保网络可以访问 dashscope.aliyuncs.com", + "⏱️ 超时设置: 根据任务复杂度调整timeout参数（建议30-60秒）", + "🔄 重试机制: 设置合适的max_retries参数处理网络波动", + "📊 模型选择: 根据任务需求选择合适的模型（turbo适合简单任务，max适合复杂任务）", + "🐛 调试模式: 开发时使用verbose=2获取详细日志信息", + "🚀 生产环境: 生产环境建议使用headless=True提高性能", + "💰 成本控制: 监控API调用次数和token使用量" + ] + + for tip in tips: + print(f" {tip}") + print() + + +def show_troubleshooting(): + """显示常见问题解决方案""" + print("\n🔧 常见问题解决方案") + print("-" * 40) + + issues = [ + { + "problem": "❌ 401 Unauthorized 错误", + "solution": "检查API密钥是否正确，确保在阿里云控制台已开通通义千问服务" + }, + { + "problem": "❌ 网络连接超时", + "solution": "检查网络连接，增加timeout参数值，或检查防火墙设置" + }, + { + "problem": "❌ 模型不存在错误", + "solution": "确认使用的模型名称正确，检查是否有权限访问该模型" + }, + { + "problem": "❌ 请求频率限制", + "solution": "降低请求频率，或联系阿里云提升API调用限额" + }, + { + "problem": "❌ 上下文长度超限", + "solution": "减少输入文本长度，或使用支持更长上下文的模型版本" + } + ] + + for issue in issues: + print(f"{issue['problem']}") + print(f" 解决方案: {issue['solution']}") + print() + + +def main(): + """运行所有示例""" + print("🚀 阿里巴巴通义千问配置示例") + print("=" * 60) + + # 检查环境设置 + if not setup_alibaba_environment(): + print("\n❌ 环境设置不完整，请先配置API密钥") + return + + # 展示模型选项 + demonstrate_model_options() + + # 创建基本配置 + basic_config = create_alibaba_config_basic() + + # 创建高级配置 + advanced_config = create_alibaba_config_advanced() + + # 测试连接 + if advanced_config: + test_alibaba_connection(advanced_config) + + # 显示配置建议 + show_configuration_tips() + + # 显示问题解决方案 + show_troubleshooting() + + print("=" * 60) + print("✨ 阿里巴巴配置示例完成！") + print() + print("🎯 下一步:") + print(" 1. 确保 .env 文件中配置了正确的API密钥") + print(" 2. 根据需求选择合适的模型") + print(" 3. 在实际项目中使用这些配置") + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/examples/config_validation_example.py b/examples/config_validation_example.py new file mode 100644 index 00000000..dbf25f24 --- /dev/null +++ b/examples/config_validation_example.py @@ -0,0 +1,336 @@ +#!/usr/bin/env python3 +""" +Example demonstrating Stagehand configuration validation and error handling. + +This example shows how to: +1. Validate configuration before initialization +2. Handle configuration errors gracefully +3. Use custom API endpoints with validation +4. Get helpful error messages for common issues +""" + +import os +import sys +from pathlib import Path + +# Add the parent directory to the path so we can import stagehand +sys.path.insert(0, str(Path(__file__).parent.parent)) + +try: + from stagehand.config import ( + StagehandConfig, + StagehandConfigError, + validate_stagehand_config, + validate_api_base_url, + validate_api_key_configuration, + create_helpful_error_message, + infer_provider_from_model_name +) + from stagehand.utils import ( + validate_model_name, + check_environment_setup, + suggest_configuration_fixes + ) +except ImportError as e: + print(f"Import error: {e}") + print("Please run this script from the stagehand-python root directory") + sys.exit(1) + + +def demonstrate_api_base_validation(): + """Demonstrate API base URL validation.""" + print("🔍 API Base URL Validation Examples") + print("-" * 40) + + test_urls = [ + "https://api.openai.com/v1", # Valid OpenAI + "https://api.anthropic.com", # Valid Anthropic + "https://api.together.xyz/v1", # Valid Together AI + "http://localhost:8000/v1", # Valid local (with warning) + "https://api.groq.com/openai/v1/", # Valid with trailing slash + "not-a-url", # Invalid + "ftp://invalid.com", # Invalid protocol + "", # Empty + ] + + for url in test_urls: + result = validate_api_base_url(url) + status = "✅" if result["valid"] else "❌" + print(f"{status} {url}") + + if result["valid"]: + if result["normalized_url"] != url: + print(f" → Normalized to: {result['normalized_url']}") + if result["warnings"]: + for warning in result["warnings"]: + print(f" ⚠️ {warning}") + else: + print(f" ❌ {result['error']}") + print() + + +def demonstrate_provider_inference(): + """Demonstrate provider inference from model names.""" + print("🤖 Provider Inference Examples") + print("-" * 40) + + models = [ + "gpt-4o", + "gpt-3.5-turbo", + "claude-3-opus-20240229", + "claude-3-sonnet", + "meta-llama/Llama-2-70b-chat-hf", + "mixtral-8x7b-32768", + "gemini-pro", + "command-r-plus", + "unknown-model-name" + ] + + for model in models: + provider = infer_provider_from_model_name(model) + provider_display = provider if provider else "Unknown" + print(f"📝 {model} → {provider_display}") + print() + + +def demonstrate_configuration_validation(): + """Demonstrate full configuration validation.""" + print("⚙️ Configuration Validation Examples") + print("-" * 40) + + # Example 1: Valid configuration + print("1. Valid Configuration:") + try: + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_key": "sk-test-key-here", + "api_base": "https://api.openai.com/v1" + }, + verbose=1 + ) + + result = validate_stagehand_config(config) + if result["valid"]: + print(" ✅ Configuration is valid!") + if result["warnings"]: + for warning in result["warnings"]: + print(f" ⚠️ {warning}") + else: + print(" ❌ Configuration has errors:") + for error in result["errors"]: + print(f" • {error}") + except Exception as e: + print(f" ❌ Configuration error: {e}") + print() + + # Example 2: Missing model name + print("2. Missing Model Name:") + try: + config = StagehandConfig(model_name=None) + result = validate_stagehand_config(config) + if not result["valid"]: + error_message = create_helpful_error_message(result, "Example 2") + print(f" ❌ {error_message}") + except Exception as e: + print(f" ❌ Validation error: {e}") + print() + + # Example 3: Invalid API base + print("3. Invalid API Base URL:") + try: + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_base": "not-a-valid-url" + } + ) + # This will fail at Pydantic validation level + except Exception as e: + print(f" ❌ Pydantic caught the error: {type(e).__name__}") + print(f" {str(e)}") + print() + + +def demonstrate_api_key_validation(): + """Demonstrate API key validation.""" + print("🔑 API Key Validation Examples") + print("-" * 40) + + # Save and clear environment for clean testing + original_openai_key = os.getenv("OPENAI_API_KEY") + if "OPENAI_API_KEY" in os.environ: + del os.environ["OPENAI_API_KEY"] + + try: + # Test 1: No API key + print("1. No API Key Provided:") + result = validate_api_key_configuration("gpt-4o", None, None) + if not result["valid"]: + print(" ❌ No API key found") + for error in result["errors"]: + print(f" • {error}") + print() + + # Test 2: API key in model_client_options + print("2. API Key in model_client_options:") + result = validate_api_key_configuration( + "gpt-4o", + None, + {"api_key": "sk-test-key"} + ) + if result["valid"]: + print(f" ✅ API key found in {result['api_key_source']}") + print() + + # Test 3: API key in environment + print("3. API Key in Environment:") + os.environ["OPENAI_API_KEY"] = "sk-env-test-key" + result = validate_api_key_configuration("gpt-4o", None, None) + if result["valid"]: + print(f" ✅ API key found in {result['api_key_source']}") + print() + + finally: + # Restore original environment + if original_openai_key: + os.environ["OPENAI_API_KEY"] = original_openai_key + elif "OPENAI_API_KEY" in os.environ: + del os.environ["OPENAI_API_KEY"] + + +def demonstrate_helpful_error_messages(): + """Demonstrate helpful error message generation.""" + print("💬 Helpful Error Messages") + print("-" * 40) + + # Create a validation result with multiple issues + validation_result = { + "valid": False, + "errors": [ + "No API key found for openai provider. Please provide an API key via model_api_key, model_client_options['api_key'], or set the OPENAI_API_KEY environment variable.", + "Invalid api_base URL: api_base must be a valid HTTP/HTTPS URL" + ], + "warnings": [ + "Using localhost/local IP - ensure this is intended for development", + "Debug logging (verbose=2) may impact performance in production" + ], + "recommendations": [ + "Consider enabling caching for better performance", + "Consider using HTTPS for security" + ] + } + + error_message = create_helpful_error_message(validation_result, "demonstration") + print(error_message) + print() + + +def demonstrate_environment_check(): + """Demonstrate environment setup checking.""" + print("🌍 Environment Setup Check") + print("-" * 40) + + env_result = check_environment_setup() + + if env_result["issues"]: + print("Issues found:") + for issue in env_result["issues"]: + print(f" ❌ {issue}") + print() + + if env_result["warnings"]: + print("Warnings:") + for warning in env_result["warnings"]: + print(f" ⚠️ {warning}") + print() + + if env_result["recommendations"]: + print("Recommendations:") + for rec in env_result["recommendations"]: + print(f" ✅ {rec}") + print() + + +def demonstrate_custom_endpoint_configuration(): + """Demonstrate configuration for custom API endpoints.""" + print("🔗 Custom API Endpoint Configuration Examples") + print("-" * 40) + + examples = [ + { + "name": "Together AI", + "config": StagehandConfig( + model_name="meta-llama/Llama-2-70b-chat-hf", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": "your-together-api-key" + } + ) + }, + { + "name": "Local OpenAI-compatible server", + "config": StagehandConfig( + model_name="gpt-3.5-turbo", + model_client_options={ + "api_base": "http://localhost:8000/v1", + "api_key": "local-key" + } + ) + }, + { + "name": "Groq", + "config": StagehandConfig( + model_name="mixtral-8x7b-32768", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": "your-groq-api-key" + } + ) + } + ] + + for example in examples: + print(f"📡 {example['name']}:") + try: + result = validate_stagehand_config(example["config"]) + if result["valid"]: + print(" ✅ Configuration is valid") + if result["warnings"]: + for warning in result["warnings"]: + print(f" ⚠️ {warning}") + else: + print(" ❌ Configuration has issues:") + for error in result["errors"]: + print(f" • {error}") + except Exception as e: + print(f" ❌ Validation failed: {e}") + print() + + +def main(): + """Run all demonstration examples.""" + print("🚀 Stagehand Configuration Validation Examples") + print("=" * 60) + print() + + demonstrate_api_base_validation() + demonstrate_provider_inference() + demonstrate_configuration_validation() + demonstrate_api_key_validation() + demonstrate_helpful_error_messages() + demonstrate_environment_check() + demonstrate_custom_endpoint_configuration() + + print("=" * 60) + print("✨ All examples completed!") + print() + print("💡 Tips:") + print(" • Always validate your configuration before initializing Stagehand") + print(" • Use environment variables for API keys in production") + print(" • Check the logs for warnings and recommendations") + print(" • Test your custom API endpoints before deployment") + + +if __name__ == "__main__": + main() \ No newline at end of file diff --git a/examples/custom_llm_endpoints.py b/examples/custom_llm_endpoints.py new file mode 100644 index 00000000..f7d622e8 --- /dev/null +++ b/examples/custom_llm_endpoints.py @@ -0,0 +1,239 @@ +#!/usr/bin/env python3 +""" +Example demonstrating how to use Stagehand with custom LLM API endpoints. + +This example shows how to configure Stagehand to work with different LLM providers +including OpenAI, Anthropic, Together AI, Groq, and custom endpoints. +""" + +import asyncio +import os +import sys +from pathlib import Path + +# Add the local stagehand directory to the Python path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from stagehand.main import Stagehand +from stagehand.config import StagehandConfig + + +async def example_openai_custom_endpoint(): + """Example using OpenAI with custom endpoint configuration.""" + print("Example 1: OpenAI with custom endpoint") + print("-" * 40) + + config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": os.getenv("OPENAI_API_KEY", "your-openai-key"), + "timeout": 30, + "max_retries": 3 + }, + verbose=1 + ) + + async with Stagehand(config=config) as stagehand: + print(f"✓ Initialized Stagehand with OpenAI model: {config.model_name}") + print(f" API Base: {config.model_client_options['api_base']}") + print(f" Timeout: {config.model_client_options['timeout']}s") + + # Validate LLM configuration + validation = stagehand.llm.validate_configuration() + print(f" Configuration valid: {validation['valid']}") + print(f" Provider: {validation['configuration']['provider']}") + + +async def example_anthropic_configuration(): + """Example using Anthropic Claude with custom configuration.""" + print("\nExample 2: Anthropic Claude configuration") + print("-" * 40) + + config = StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY", "your-anthropic-key"), + "timeout": 60 + }, + verbose=1 + ) + + async with Stagehand(config=config) as stagehand: + print(f"✓ Initialized Stagehand with Anthropic model: {config.model_name}") + print(f" API Base: {config.model_client_options['api_base']}") + + validation = stagehand.llm.validate_configuration() + print(f" Configuration valid: {validation['valid']}") + print(f" Provider: {validation['configuration']['provider']}") + + +async def example_together_ai_configuration(): + """Example using Together AI with custom configuration.""" + print("\nExample 3: Together AI configuration") + print("-" * 40) + + config = StagehandConfig( + model_name="together/llama-2-7b-chat", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": os.getenv("TOGETHER_API_KEY", "your-together-key"), + "timeout": 45, + "max_retries": 2 + }, + verbose=1 + ) + + async with Stagehand(config=config) as stagehand: + print(f"✓ Initialized Stagehand with Together AI model: {config.model_name}") + print(f" API Base: {config.model_client_options['api_base']}") + + validation = stagehand.llm.validate_configuration() + print(f" Configuration valid: {validation['valid']}") + print(f" Provider: {validation['configuration']['provider']}") + + +async def example_groq_configuration(): + """Example using Groq with custom configuration.""" + print("\nExample 4: Groq configuration") + print("-" * 40) + + config = StagehandConfig( + model_name="groq/llama2-70b-4096", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": os.getenv("GROQ_API_KEY", "your-groq-key"), + "timeout": 30 + }, + verbose=1 + ) + + async with Stagehand(config=config) as stagehand: + print(f"✓ Initialized Stagehand with Groq model: {config.model_name}") + print(f" API Base: {config.model_client_options['api_base']}") + + validation = stagehand.llm.validate_configuration() + print(f" Configuration valid: {validation['valid']}") + print(f" Provider: {validation['configuration']['provider']}") + + +async def example_local_openai_server(): + """Example using a local OpenAI-compatible server.""" + print("\nExample 5: Local OpenAI-compatible server") + print("-" * 40) + + config = StagehandConfig( + model_name="local/custom-model", + model_client_options={ + "api_base": "http://localhost:8000/v1", + "api_key": "local-key", + "timeout": 120 # Local servers might be slower + }, + verbose=1 + ) + + async with Stagehand(config=config) as stagehand: + print(f"✓ Initialized Stagehand with local model: {config.model_name}") + print(f" API Base: {config.model_client_options['api_base']}") + + validation = stagehand.llm.validate_configuration() + print(f" Configuration valid: {validation['valid']}") + print(f" Provider: {validation['configuration']['provider']}") + + +async def example_environment_variable_fallback(): + """Example showing environment variable fallback for API keys.""" + print("\nExample 6: Environment variable fallback") + print("-" * 40) + + # Set environment variable for demonstration + os.environ["OPENAI_API_KEY"] = "demo-key-from-env" + + config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + # No api_key specified - should use environment variable + }, + verbose=1 + ) + + async with Stagehand(config=config) as stagehand: + print(f"✓ Initialized Stagehand using environment variable for API key") + print(f" Model: {config.model_name}") + + validation = stagehand.llm.validate_configuration() + print(f" Configuration valid: {validation['valid']}") + print(f" API key configured: {validation['configuration']['api_key_configured']}") + + # Clean up + del os.environ["OPENAI_API_KEY"] + + +async def example_error_handling(): + """Example demonstrating error handling for invalid configurations.""" + print("\nExample 7: Error handling for invalid configurations") + print("-" * 40) + + try: + # This should fail due to invalid API base + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_base": "not-a-valid-url", + "api_key": "test-key" + } + ) + print("✗ Should have failed with invalid URL") + + except ValueError as e: + print(f"✓ Correctly caught configuration error: {e}") + + try: + # This should fail due to negative timeout + config = StagehandConfig( + model_name="gpt-4o", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "timeout": -10 + } + ) + print("✗ Should have failed with negative timeout") + + except ValueError as e: + print(f"✓ Correctly caught timeout validation error: {e}") + + +async def main(): + """Run all examples.""" + print("Stagehand Custom LLM Endpoints Examples") + print("=" * 50) + + try: + await example_openai_custom_endpoint() + await example_anthropic_configuration() + await example_together_ai_configuration() + await example_groq_configuration() + await example_local_openai_server() + await example_environment_variable_fallback() + await example_error_handling() + + print("\n" + "=" * 50) + print("All examples completed successfully!") + print("\nKey features demonstrated:") + print("• Custom API endpoint configuration") + print("• Multiple LLM provider support") + print("• Environment variable fallback") + print("• Configuration validation") + print("• Error handling") + print("• Timeout and retry configuration") + + except Exception as e: + print(f"\nError running examples: {e}") + import traceback + traceback.print_exc() + + +if __name__ == "__main__": + asyncio.run(main()) \ No newline at end of file diff --git a/examples/example.py b/examples/example.py index 5f86ef5a..4eb93dd4 100644 --- a/examples/example.py +++ b/examples/example.py @@ -1,12 +1,17 @@ import asyncio import logging import os +import sys +from pathlib import Path from dotenv import load_dotenv from rich.console import Console from rich.panel import Panel from rich.theme import Theme +# Ensure local stagehand package is used instead of any installed version +sys.path.insert(0, str(Path(__file__).parent.parent)) + from stagehand import Stagehand, StagehandConfig, configure_logging # Configure logging with cleaner format @@ -46,32 +51,41 @@ ) async def main(): - # Build a unified configuration object for Stagehand + # Build a unified configuration object for Stagehand with local browser config = StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - headless=False, + model_name="qwen-turbo", # Use Alibaba DashScope model for demo + model_client_options={ + "api_base": os.getenv("ALIBABA_ENDPOINT", "https://dashscope.aliyuncs.com/compatible-mode/v1"), + "api_key": os.getenv("ALIBABA_API_KEY"), + "timeout": 30 + }, dom_settle_timeout_ms=3000, - model_name="google/gemini-2.0-flash", self_heal=True, wait_for_captcha_solves=True, system_prompt="You are a browser automation assistant that helps users navigate websites effectively.", - model_client_options={"apiKey": os.getenv("MODEL_API_KEY")}, + local_browser_launch_options={ + "headless": False, # Set to True for headless mode + "viewport": {"width": 1280, "height": 720} + }, # Use verbose=2 for medium-detail logs (1=minimal, 3=debug) verbose=2, ) stagehand = Stagehand(config) - # Initialize - this creates a new session automatically. - console.print("\n🚀 [info]Initializing Stagehand...[/]") + # Initialize - this creates a local browser session automatically. + console.print("\n🚀 [info]Initializing Stagehand with local browser...[/]") await stagehand.init() page = stagehand.page - console.print(f"\n[yellow]Created new session:[/] {stagehand.session_id}") - console.print( - f"🌐 [white]View your live browser:[/] [url]https://www.browserbase.com/sessions/{stagehand.session_id}[/]" - ) + + # Validate LLM configuration + validation = stagehand.llm.validate_configuration() + if validation['valid']: + console.print(f"✓ [success]LLM configured:[/] {validation['configuration']['provider']} - {config.model_name}") + else: + console.print("⚠ [warning]LLM configuration issues:[/]", validation['errors']) + + console.print("🌐 [white]Local browser session initialized successfully[/]") await asyncio.sleep(2) diff --git a/examples/quickstart.py b/examples/quickstart.py index 20daf858..10b2fad2 100644 --- a/examples/quickstart.py +++ b/examples/quickstart.py @@ -1,10 +1,16 @@ import asyncio import os +import sys +from pathlib import Path + +# Add the local stagehand directory to the Python path +sys.path.insert(0, str(Path(__file__).parent.parent)) from dotenv import load_dotenv from pydantic import BaseModel, Field -from stagehand import Stagehand, StagehandConfig +from stagehand.main import Stagehand +from stagehand.config import StagehandConfig # Load environment variables load_dotenv() @@ -18,24 +24,30 @@ class Companies(BaseModel): companies: list[Company] = Field(..., description="List of companies") async def main(): - # Create configuration + # Create configuration for local browser automation with custom LLM endpoint config = StagehandConfig( - env = "BROWSERBASE", # or LOCAL - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="google/gemini-2.5-flash-preview-05-20", - model_client_options={"apiKey": os.getenv("MODEL_API_KEY")}, + model_name="qwen-turbo", # Use Alibaba DashScope model for demo + model_client_options={ + "api_base": os.getenv("ALIBABA_ENDPOINT", "https://dashscope.aliyuncs.com/compatible-mode/v1"), + "api_key": os.getenv("ALIBABA_API_KEY"), + "timeout": 30 + }, + verbose=1, + local_browser_launch_options={ + "headless": False, # Set to True for headless mode + "viewport": {"width": 1280, "height": 720} + } ) - stagehand = Stagehand(config) - - try: - print("\nInitializing 🤘 Stagehand...") - # Initialize Stagehand - await stagehand.init() - - if stagehand.env == "BROWSERBASE": - print(f"🌐 View your live browser: https://www.browserbase.com/sessions/{stagehand.session_id}") + async with Stagehand(config=config) as stagehand: + print("\nInitializing 🤘 Stagehand with local browser...") + + # Validate LLM configuration + validation = stagehand.llm.validate_configuration() + if validation['valid']: + print(f"✓ LLM configured: {validation['configuration']['provider']} - {config.model_name}") + else: + print("⚠ LLM configuration issues:", validation['errors']) page = stagehand.page @@ -57,13 +69,7 @@ async def main(): act = await page.act("click the link to the company Browserbase") print("\nAct result:", act) - except Exception as e: - print(f"Error: {str(e)}") - raise - finally: - # Close the client - print("\nClosing 🤘 Stagehand...") - await stagehand.close() + print("\n🤘 Stagehand session completed successfully!") if __name__ == "__main__": asyncio.run(main()) \ No newline at end of file diff --git a/examples/quickstart_jupyter_notebook.ipynb b/examples/quickstart_jupyter_notebook.ipynb index 58135ee1..cc6fd3aa 100644 --- a/examples/quickstart_jupyter_notebook.ipynb +++ b/examples/quickstart_jupyter_notebook.ipynb @@ -1,22 +1,40 @@ { "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# Stagehand Quickstart Jupyter Notebook\n", + "\n", + "This notebook demonstrates how to use Stagehand with local browser automation and custom LLM endpoints.\n", + "\n", + "## Prerequisites\n", + "\n", + "Make sure you have:\n", + "- Python 3.8+ installed\n", + "- An OpenAI API key (or other LLM provider API key)\n", + "- Chrome/Chromium browser installed" + ] + }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ + "# Install Stagehand if not already installed\n", "%pip install stagehand" ] }, { "cell_type": "code", - "execution_count": 75, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import os\n", - "from pprint import pprint" + "from pprint import pprint\n", + "from typing import List" ] }, { @@ -25,69 +43,131 @@ "metadata": {}, "outputs": [], "source": [ + "# Load environment variables from .env file\n", "import dotenv\n", - "dotenv.load_dotenv()\n" + "dotenv.load_dotenv()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Configure Stagehand\n", + "\n", + "Configure Stagehand to use local browser automation with a custom LLM endpoint. This example uses OpenAI, but you can configure it for other providers like Anthropic, Together AI, or Groq." ] }, { "cell_type": "code", - "execution_count": 77, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ "from stagehand import Stagehand, StagehandConfig\n", "\n", - "stagehand = Stagehand(StagehandConfig(\n", - " env=\"BROWSERBASE\",\n", - " model_name=\"openai/gpt-4o-mini\",\n", - " api_key=os.getenv(\"BROWSERBASE_API_KEY\"),\n", - " project_id=os.getenv(\"BROWSERBASE_PROJECT_ID\"),\n", - " api_url=\"https://api.stagehand.browserbase.com/v1\",\n", - " # headless=False,\n", - " verbose=0,\n", - " # dom_settle_timeout_ms=3000,\n", - "), model_api_key=os.getenv(\"OPENAI_API_KEY\"))" + "# Configure Stagehand for local browser automation with Alibaba Bailian (DashScope)\n", + "config = StagehandConfig(\n", + " model_name=\"qwen-turbo\", # Use Alibaba Bailian model\n", + " model_client_options={\n", + " \"api_base\": os.getenv(\"ALIBABA_ENDPOINT\", \"https://dashscope.aliyuncs.com/compatible-mode/v1\"),\n", + " \"api_key\": os.getenv(\"ALIBABA_API_KEY\"),\n", + " \"timeout\": 30\n", + " },\n", + " local_browser_launch_options={\n", + " \"headless\": False, # Set to True for headless mode\n", + " \"viewport\": {\"width\": 1280, \"height\": 720}\n", + " },\n", + " verbose=1, # Set to 0 for minimal logs, 2 for detailed logs\n", + " dom_settle_timeout_ms=3000,\n", + ")\n", + "\n", + "stagehand = Stagehand(config)\n", + "print(\"✓ Stagehand configured with local browser and Alibaba Bailian API\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Initialize Stagehand\n", + "\n", + "Initialize the Stagehand instance, which will launch a local browser." ] }, { "cell_type": "code", - "execution_count": 78, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "await stagehand.init()" + "await stagehand.init()\n", + "\n", + "# Validate LLM configuration\n", + "validation = stagehand.llm.validate_configuration()\n", + "if validation['valid']:\n", + " print(f\"✓ LLM configured: {validation['configuration']['provider']} - {config.model_name}\")\n", + "else:\n", + " print(\"⚠ LLM configuration issues:\", validation['errors'])\n", + "\n", + "print(\"🚀 Local browser session initialized successfully!\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Navigate to a Website\n", + "\n", + "Let's navigate to Hacker News and extract some data." ] }, { "cell_type": "code", - "execution_count": 79, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ "page = stagehand.page\n", - "await page.goto(\"https://www.hackernews.com\")" + "await page.goto(\"https://news.ycombinator.com\")\n", + "print(\"✓ Navigated to Hacker News\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Define Data Models\n", + "\n", + "Define Pydantic models for structured data extraction." ] }, { "cell_type": "code", - "execution_count": 82, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "from typing import List\n", - "\n", - "from pydantic import BaseModel\n", - "\n", + "from pydantic import BaseModel, Field\n", "\n", "class Post(BaseModel):\n", - " title: str\n", - " points: int\n", - " comments: int\n", + " title: str = Field(..., description=\"Post title\")\n", + " points: int = Field(..., description=\"Number of points/upvotes\")\n", + " comments: int = Field(..., description=\"Number of comments\")\n", + " url: str = Field(..., description=\"Post URL if available\")\n", "\n", "class Posts(BaseModel):\n", - " posts: List[Post]\n", + " posts: List[Post] = Field(..., description=\"List of posts\")\n", + "\n", + "print(\"✓ Data models defined\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Extract Structured Data\n", "\n", - "res = await page.extract(\"find all the posts related to the topic 'AI'\", schema=Posts)" + "Use Stagehand's extract method to get structured data from the page." ] }, { @@ -96,22 +176,176 @@ "metadata": {}, "outputs": [], "source": [ - "pprint(res.posts)" + "# Extract posts related to AI\n", + "res = await page.extract(\n", + " \"find the top 5 posts on the front page with their titles, points, comments, and URLs\", \n", + " schema=Posts\n", + ")\n", + "\n", + "print(f\"✓ Extracted {len(res.posts)} posts\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Display Results\n", + "\n", + "Pretty print the extracted data." ] }, { "cell_type": "code", - "execution_count": 85, + "execution_count": null, "metadata": {}, "outputs": [], "source": [ - "await stagehand.close()" + "print(\"\\n📊 Extracted Posts:\")\n", + "print(\"=\" * 50)\n", + "\n", + "for idx, post in enumerate(res.posts, 1):\n", + " print(f\"\\n{idx}. {post.title}\")\n", + " print(f\" Points: {post.points} | Comments: {post.comments}\")\n", + " if post.url:\n", + " print(f\" URL: {post.url}\")\n", + " print(\"-\" * 40)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Demonstrate Browser Actions\n", + "\n", + "Show how to perform actions on the page." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Observe elements on the page\n", + "observed = await page.observe(\"find the 'new' link in the navigation\")\n", + "print(f\"✓ Observed: {observed}\")\n", + "\n", + "# Perform an action\n", + "if observed:\n", + " action_result = await page.act(\"click on the 'new' link\")\n", + " print(f\"✓ Action performed: {action_result}\")\n", + " \n", + " # Wait a moment for the page to load\n", + " import asyncio\n", + " await asyncio.sleep(2)\n", + " \n", + " print(\"✓ Navigated to 'new' posts page\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Alternative LLM Provider Configuration\n", + "\n", + "Here's how you could configure Stagehand with different LLM providers:" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Example configurations for different providers (don't run these cells unless you have the API keys)\n", + "\n", + "# Anthropic Claude configuration\n", + "anthropic_config = StagehandConfig(\n", + " model_name=\"claude-3-haiku-20240307\",\n", + " model_client_options={\n", + " \"api_base\": \"https://api.anthropic.com\",\n", + " \"api_key\": os.getenv(\"ANTHROPIC_API_KEY\"),\n", + " \"timeout\": 60\n", + " },\n", + " local_browser_launch_options={\"headless\": True}\n", + ")\n", + "\n", + "# Together AI configuration\n", + "together_config = StagehandConfig(\n", + " model_name=\"together/llama-2-7b-chat\",\n", + " model_client_options={\n", + " \"api_base\": \"https://api.together.xyz/v1\",\n", + " \"api_key\": os.getenv(\"TOGETHER_API_KEY\"),\n", + " \"timeout\": 45\n", + " },\n", + " local_browser_launch_options={\"headless\": True}\n", + ")\n", + "\n", + "# Groq configuration\n", + "groq_config = StagehandConfig(\n", + " model_name=\"groq/llama2-70b-4096\",\n", + " model_client_options={\n", + " \"api_base\": \"https://api.groq.com/openai/v1\",\n", + " \"api_key\": os.getenv(\"GROQ_API_KEY\"),\n", + " \"timeout\": 30\n", + " },\n", + " local_browser_launch_options={\"headless\": True}\n", + ")\n", + "\n", + "print(\"✓ Alternative provider configurations shown above\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Clean Up\n", + "\n", + "Always close the Stagehand session when done to free up resources." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "await stagehand.close()\n", + "print(\"✓ Stagehand session closed successfully!\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Summary\n", + "\n", + "This notebook demonstrated:\n", + "\n", + "1. **Local Browser Configuration**: Using Stagehand with a local browser instead of remote services\n", + "2. **Custom LLM Endpoints**: Configuring different LLM providers (OpenAI, Anthropic, Together AI, Groq)\n", + "3. **Structured Data Extraction**: Using Pydantic models to extract structured data\n", + "4. **Browser Actions**: Observing and acting on page elements\n", + "5. **Configuration Validation**: Checking LLM configuration validity\n", + "\n", + "### Key Benefits of Local Mode:\n", + "- No external service dependencies\n", + "- Better privacy and security\n", + "- Lower latency for browser operations\n", + "- Full control over browser configuration\n", + "- Works offline (except for LLM API calls)\n", + "\n", + "### Next Steps:\n", + "- Try different LLM providers\n", + "- Experiment with headless vs. headed browser modes\n", + "- Build more complex automation workflows\n", + "- Integrate with your own applications" ] } ], "metadata": { "kernelspec": { - "display_name": "venv", + "display_name": "Python 3", "language": "python", "name": "python3" }, @@ -124,7 +358,6 @@ "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", - "pygments_lexer": "ipython3", "version": "3.11.12" } }, diff --git a/examples/windows_powershell_example.py b/examples/windows_powershell_example.py new file mode 100644 index 00000000..5271dd4b --- /dev/null +++ b/examples/windows_powershell_example.py @@ -0,0 +1,326 @@ +#!/usr/bin/env python3 +""" +Windows PowerShell Compatible Example for Stagehand + +This example demonstrates: +1. Local browser automation without external dependencies +2. Multiple LLM provider configurations +3. Windows PowerShell compatibility +4. Error handling and validation +5. Structured data extraction + +Prerequisites: +- Python 3.8+ installed +- Chrome/Chromium browser installed +- At least one LLM provider API key (OpenAI, Anthropic, etc.) + +Usage in PowerShell: + python examples/windows_powershell_example.py + +Or with specific provider: + $env:PREFERRED_PROVIDER="openai"; python examples/windows_powershell_example.py +""" + +import asyncio +import os +import sys +from pathlib import Path +from typing import List, Optional + +# Add the local stagehand directory to the Python path +sys.path.insert(0, str(Path(__file__).parent.parent)) + +from dotenv import load_dotenv +from pydantic import BaseModel, Field + +from stagehand.main import Stagehand +from stagehand.config import StagehandConfig + +# Load environment variables +load_dotenv() + + +class NewsArticle(BaseModel): + """Model for news articles.""" + title: str = Field(..., description="Article title") + summary: str = Field(..., description="Brief article summary") + url: Optional[str] = Field(None, description="Article URL if available") + + +class NewsArticles(BaseModel): + """Collection of news articles.""" + articles: List[NewsArticle] = Field(..., description="List of news articles") + + +def get_provider_configs(): + """Get available LLM provider configurations based on environment variables.""" + configs = {} + + # OpenAI configuration + if os.getenv("OPENAI_API_KEY"): + configs["openai"] = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": os.getenv("OPENAI_API_KEY"), + "timeout": 30 + }, + local_browser_launch_options={ + "headless": False, + "viewport": {"width": 1280, "height": 720} + }, + verbose=1 + ) + + # Anthropic configuration + if os.getenv("ANTHROPIC_API_KEY"): + configs["anthropic"] = StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY"), + "timeout": 60 + }, + local_browser_launch_options={ + "headless": False, + "viewport": {"width": 1280, "height": 720} + }, + verbose=1 + ) + + # Together AI configuration + if os.getenv("TOGETHER_API_KEY"): + configs["together"] = StagehandConfig( + model_name="together/llama-2-7b-chat", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": os.getenv("TOGETHER_API_KEY"), + "timeout": 45 + }, + local_browser_launch_options={ + "headless": False, + "viewport": {"width": 1280, "height": 720} + }, + verbose=1 + ) + + # Groq configuration + if os.getenv("GROQ_API_KEY"): + configs["groq"] = StagehandConfig( + model_name="groq/llama2-70b-4096", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": os.getenv("GROQ_API_KEY"), + "timeout": 30 + }, + local_browser_launch_options={ + "headless": False, + "viewport": {"width": 1280, "height": 720} + }, + verbose=1 + ) + + return configs + + +def select_provider_config(configs): + """Select the best available provider configuration.""" + # Check for preferred provider from environment + preferred = os.getenv("PREFERRED_PROVIDER", "").lower() + if preferred and preferred in configs: + print(f"✓ Using preferred provider: {preferred}") + return preferred, configs[preferred] + + # Default priority order + priority = ["openai", "anthropic", "groq", "together"] + + for provider in priority: + if provider in configs: + print(f"✓ Using available provider: {provider}") + return provider, configs[provider] + + raise ValueError( + "No LLM provider API keys found. Please set one of: " + "OPENAI_API_KEY, ANTHROPIC_API_KEY, GROQ_API_KEY, TOGETHER_API_KEY" + ) + + +async def demonstrate_basic_automation(stagehand): + """Demonstrate basic browser automation capabilities.""" + print("\n" + "="*50) + print("🤖 Demonstrating Basic Browser Automation") + print("="*50) + + page = stagehand.page + + # Navigate to a news website + print("📰 Navigating to BBC News...") + await page.goto("https://www.bbc.com/news") + print("✓ Successfully navigated to BBC News") + + # Extract news articles + print("\n📊 Extracting top news articles...") + try: + articles_data = await page.extract( + "Extract the titles and summaries of the top 5 news articles on the page", + schema=NewsArticles + ) + + print(f"✓ Successfully extracted {len(articles_data.articles)} articles") + + # Display results + print("\n📋 Extracted Articles:") + for idx, article in enumerate(articles_data.articles, 1): + print(f"\n{idx}. {article.title}") + print(f" Summary: {article.summary}") + if article.url: + print(f" URL: {article.url}") + print("-" * 40) + + except Exception as e: + print(f"⚠ Error extracting articles: {e}") + + # Demonstrate observe functionality + print("\n🔍 Demonstrating observe functionality...") + try: + observed = await page.observe("find the search box on the page") + print(f"✓ Observed search element: {observed}") + except Exception as e: + print(f"⚠ Error observing elements: {e}") + + +async def demonstrate_windows_compatibility(): + """Demonstrate Windows-specific features and compatibility.""" + print("\n" + "="*50) + print("🪟 Demonstrating Windows PowerShell Compatibility") + print("="*50) + + # Check Windows environment + if os.name == 'nt': + print("✓ Running on Windows") + print(f" Python version: {sys.version}") + print(f" Working directory: {os.getcwd()}") + + # Demonstrate PowerShell command execution + try: + import subprocess + result = subprocess.run( + ["powershell", "-Command", "Get-Location"], + capture_output=True, + text=True, + timeout=10 + ) + if result.returncode == 0: + print(f"✓ PowerShell integration working: {result.stdout.strip()}") + else: + print(f"⚠ PowerShell command failed: {result.stderr}") + except Exception as e: + print(f"⚠ PowerShell integration error: {e}") + else: + print(f"ℹ Running on {os.name} (not Windows)") + + # Check browser availability + print("\n🌐 Checking browser availability...") + try: + from playwright.sync_api import sync_playwright + with sync_playwright() as p: + browsers = [] + if p.chromium.executable_path: + browsers.append("Chromium") + if hasattr(p, 'chrome') and p.chrome.executable_path: + browsers.append("Chrome") + if p.firefox.executable_path: + browsers.append("Firefox") + + if browsers: + print(f"✓ Available browsers: {', '.join(browsers)}") + else: + print("⚠ No browsers found") + except Exception as e: + print(f"⚠ Error checking browsers: {e}") + + +async def main(): + """Main function demonstrating Stagehand with Windows PowerShell compatibility.""" + print("🤘 Stagehand Windows PowerShell Example") + print("=" * 50) + + try: + # Get available provider configurations + configs = get_provider_configs() + + if not configs: + print("❌ No LLM provider API keys found!") + print("\nPlease set one of the following environment variables:") + print(" • OPENAI_API_KEY - for OpenAI GPT models") + print(" • ANTHROPIC_API_KEY - for Anthropic Claude models") + print(" • GROQ_API_KEY - for Groq models") + print(" • TOGETHER_API_KEY - for Together AI models") + print("\nExample PowerShell commands:") + print(" $env:OPENAI_API_KEY='your-api-key-here'") + print(" python examples/windows_powershell_example.py") + return + + # Select provider configuration + provider_name, config = select_provider_config(configs) + + print(f"\n🔧 Configuration Details:") + print(f" Provider: {provider_name}") + print(f" Model: {config.model_name}") + print(f" API Base: {config.model_client_options.get('api_base', 'default')}") + print(f" Timeout: {config.model_client_options.get('timeout', 'default')}s") + print(f" Browser: Local ({'headless' if config.local_browser_launch_options.get('headless') else 'headed'})") + + # Initialize Stagehand + print(f"\n🚀 Initializing Stagehand with {provider_name}...") + async with Stagehand(config=config) as stagehand: + # Validate LLM configuration + validation = stagehand.llm.validate_configuration() + if validation['valid']: + print(f"✓ LLM configured successfully") + print(f" Provider: {validation['configuration']['provider']}") + print(f" Model: {config.model_name}") + print(f" API Key: {'✓ Configured' if validation['configuration']['api_key_configured'] else '❌ Missing'}") + else: + print("⚠ LLM configuration issues:") + for error in validation['errors']: + print(f" • {error}") + + # Demonstrate Windows compatibility + await demonstrate_windows_compatibility() + + # Demonstrate basic automation + await demonstrate_basic_automation(stagehand) + + print("\n" + "="*50) + print("🎉 Example completed successfully!") + print("="*50) + + print("\n💡 Tips for Windows PowerShell users:") + print(" • Use $env:VARIABLE_NAME to set environment variables") + print(" • Use semicolons (;) instead of && for command chaining") + print(" • Run 'python -m pip install stagehand' to install") + print(" • Use './run_tests.ps1' to run tests with PowerShell") + print(" • Use './format.ps1' to format code with PowerShell") + + except KeyboardInterrupt: + print("\n\n⏹ Example interrupted by user") + except Exception as e: + print(f"\n❌ Error running example: {e}") + import traceback + traceback.print_exc() + sys.exit(1) + + +if __name__ == "__main__": + # Set up Windows-specific console encoding if needed + if os.name == 'nt': + try: + # Ensure proper UTF-8 encoding on Windows + import codecs + sys.stdout = codecs.getwriter('utf-8')(sys.stdout.buffer) + sys.stderr = codecs.getwriter('utf-8')(sys.stderr.buffer) + except: + pass # Fallback to default encoding + + asyncio.run(main()) \ No newline at end of file diff --git a/pytest.ini b/pytest.ini index 4f2c039f..f4e85481 100644 --- a/pytest.ini +++ b/pytest.ini @@ -13,6 +13,11 @@ markers = api: marks tests as API integration tests e2e: marks tests as end-to-end tests regression: marks tests as regression tests + openai: marks tests as OpenAI provider tests + anthropic: marks tests as Anthropic provider tests + together: marks tests as Together AI provider tests + custom_llm: marks tests as custom LLM endpoint tests + config: marks tests as configuration tests log_cli = true log_cli_level = INFO \ No newline at end of file diff --git a/stagehand/agent/agent.py b/stagehand/agent/agent.py index d455c1d5..032a6603 100644 --- a/stagehand/agent/agent.py +++ b/stagehand/agent/agent.py @@ -37,8 +37,14 @@ class Agent: def __init__(self, stagehand_client, **kwargs): self.stagehand = stagehand_client self.config = AgentConfig(**kwargs) if kwargs else AgentConfig() + + # If no model specified in agent config, use the model from stagehand client + if not self.config.model: + self.config.model = self.stagehand.model_name + self.logger = self.stagehand.logger - if self.stagehand.use_api: + # API mode removed - always use local mode + if False: # Disabled API mode if self.config.model in MODEL_TO_PROVIDER_MAP: self.provider = MODEL_TO_PROVIDER_MAP[self.config.model] else: @@ -123,92 +129,51 @@ async def execute( instruction = options.instruction - if not self.stagehand.use_api: - self.logger.info( - f"Agent starting execution for instruction: '{instruction}'", - category="agent", - ) - - try: - agent_result = await self.client.run_task( - instruction=instruction, - max_steps=options.max_steps or self.config.max_steps, - options=options, - ) - except Exception as e: - self.logger.error( - f"Exception during client.run_task: {e}", category="agent" - ) - empty_usage = AgentUsage( - input_tokens=0, output_tokens=0, inference_time_ms=0 - ) - return AgentResult( - message=f"Error: {str(e)}", - completed=True, - actions=[], - usage=empty_usage, - ) + # Always use local mode (API mode removed) + self.logger.info( + f"Agent starting execution for instruction: '{instruction}'", + category="agent", + ) - # Update metrics if usage data is available in the result - if agent_result.usage: - # self.stagehand.update_metrics( - # AGENT_METRIC_FUNCTION_NAME, - # agent_result.usage.get("input_tokens", 0), - # agent_result.usage.get("output_tokens", 0), - # agent_result.usage.get("inference_time_ms", 0), - # ) - pass # Placeholder if metrics are to be handled differently or not at all - - self.logger.info( - f"Agent execution finished. Success: {agent_result.completed}. Message: {agent_result.message}", - category="agent", + try: + agent_result = await self.client.run_task( + instruction=instruction, + max_steps=options.max_steps or self.config.max_steps, + options=options, ) - # To clean up pydantic model output - actions_repr = [action.root for action in agent_result.actions] - self.logger.debug( - f"Agent actions: {actions_repr}", - category="agent", + except Exception as e: + self.logger.error( + f"Exception during client.run_task: {e}", category="agent" ) - agent_result.actions = actions_repr - return agent_result - else: - agent_config_payload = self.config.model_dump( - exclude_none=True, by_alias=True + empty_usage = AgentUsage( + input_tokens=0, output_tokens=0, inference_time_ms=0 ) - agent_config_payload["provider"] = self.provider - payload = { - # Use the stored config - "agentConfig": agent_config_payload, - "executeOptions": options.model_dump(exclude_none=True, by_alias=True), - } - - lock = self.stagehand._get_lock_for_session() - async with lock: - result = await self.stagehand._execute("agentExecute", payload) - - if isinstance(result, dict): - # Ensure all expected fields are present - # If not present in result, use defaults from AgentExecuteResult schema - if "success" not in result: - raise ValueError("Response missing required field 'success'") - - # Ensure completed is set with default if not present - if "completed" not in result: - result["completed"] = False - - # Add default for message if missing - if "message" not in result: - result["message"] = None - - return AgentExecuteResult(**result) - elif result is None: - # Handle cases where the server might return None or an empty response - # Return a default failure result or raise an error - return AgentExecuteResult( - success=False, - completed=False, - message="No result received from server", - ) - else: - # If the result is not a dict and not None, it's unexpected - raise TypeError(f"Unexpected result type from server: {type(result)}") + return AgentResult( + message=f"Error: {str(e)}", + completed=True, + actions=[], + usage=empty_usage, + ) + + # Update metrics if usage data is available in the result + if agent_result.usage: + # self.stagehand.update_metrics( + # AGENT_METRIC_FUNCTION_NAME, + # agent_result.usage.get("input_tokens", 0), + # agent_result.usage.get("output_tokens", 0), + # agent_result.usage.get("inference_time_ms", 0), + # ) + pass # Placeholder if metrics are to be handled differently or not at all + + self.logger.info( + f"Agent execution finished. Success: {agent_result.completed}. Message: {agent_result.message}", + category="agent", + ) + # To clean up pydantic model output + actions_repr = [action.root for action in agent_result.actions] + self.logger.debug( + f"Agent actions: {actions_repr}", + category="agent", + ) + agent_result.actions = actions_repr + return agent_result diff --git a/stagehand/api.py b/stagehand/api.py index aec343a4..d13e2509 100644 --- a/stagehand/api.py +++ b/stagehand/api.py @@ -120,26 +120,8 @@ async def _execute(self, method: str, payload: dict[str, Any]) -> Any: if self.model_api_key: headers["x-model-api-key"] = self.model_api_key - payload_options = payload.get("modelClientOptions", {}) - instance_options = self.model_client_options or {} - - # Clear precedence order - base_url = ( - payload_options.get("baseURL") - or payload_options.get("api_base") - or instance_options.get("baseURL") - or instance_options.get("api_base") - ) - - if base_url: - if "modelClientOptions" not in payload: - payload["modelClientOptions"] = {} - payload["modelClientOptions"]["baseURL"] = base_url - payload["modelClientOptions"].pop("api_base", None) - # Convert snake_case keys to camelCase for the API modified_payload = convert_dict_keys_to_camel_case(payload) - print(modified_payload) # async with self._client: try: diff --git a/stagehand/browser.py b/stagehand/browser.py index d21560d5..5fdba2a1 100644 --- a/stagehand/browser.py +++ b/stagehand/browser.py @@ -5,8 +5,6 @@ from pathlib import Path from typing import Any, Optional -from browserbase import Browserbase -from browserbase.types import SessionCreateParams as BrowserbaseSessionCreateParams from playwright.async_api import ( Browser, BrowserContext, @@ -18,94 +16,9 @@ from .page import StagehandPage -async def connect_browserbase_browser( +async def connect_browser( playwright: Playwright, - session_id: str, - browserbase_api_key: str, - stagehand_instance: Any, - logger: StagehandLogger, -) -> tuple[Browser, BrowserContext, StagehandContext, StagehandPage]: - """ - Connect to a Browserbase remote browser session. - - Args: - playwright: The Playwright instance - session_id: The Browserbase session ID - browserbase_api_key: The Browserbase API key - stagehand_instance: The Stagehand instance (for context initialization) - logger: The logger instance - - Returns: - tuple of (browser, context, stagehand_context, page) - """ - # Connect to remote browser via Browserbase SDK and CDP - bb = Browserbase(api_key=browserbase_api_key) - try: - if session_id: - session = bb.sessions.retrieve(session_id) - if session.status != "RUNNING": - raise RuntimeError( - f"Browserbase session {session_id} is not running (status: {session.status})" - ) - else: - browserbase_session_create_params = ( - BrowserbaseSessionCreateParams( - project_id=stagehand_instance.browserbase_project_id, - browser_settings={ - "viewport": { - "width": 1024, - "height": 768, - }, - }, - ) - if not stagehand_instance.browserbase_session_create_params - else stagehand_instance.browserbase_session_create_params - ) - session = bb.sessions.create(**browserbase_session_create_params) - if not session.id: - raise Exception("Could not create Browserbase session") - stagehand_instance.session_id = session.id - connect_url = session.connectUrl - except Exception as e: - logger.error(f"Error retrieving or validating Browserbase session: {str(e)}") - raise - - logger.debug(f"Connecting to remote browser at: {connect_url}") - try: - browser = await playwright.chromium.connect_over_cdp(connect_url) - except Exception as e: - logger.error(f"Failed to connect Playwright via CDP: {str(e)}") - raise - - existing_contexts = browser.contexts - logger.debug(f"Existing contexts in remote browser: {len(existing_contexts)}") - if existing_contexts: - context = existing_contexts[0] - else: - # This case might be less common with Browserbase but handle it - logger.warning( - "No existing context found in remote browser, creating a new one." - ) - context = await browser.new_context() - - stagehand_context = await StagehandContext.init(context, stagehand_instance) - - # Access or create a page via StagehandContext - existing_pages = context.pages - logger.debug(f"Existing pages in context: {len(existing_pages)}") - if existing_pages: - logger.debug("Using existing page via StagehandContext") - page = await stagehand_context.get_stagehand_page(existing_pages[0]) - else: - logger.debug("Creating a new page via StagehandContext") - page = await stagehand_context.new_page() - - return browser, context, stagehand_context, page - - -async def connect_local_browser( - playwright: Playwright, - local_browser_launch_options: dict[str, Any], + browser_launch_options: dict[str, Any], stagehand_instance: Any, logger: StagehandLogger, ) -> tuple[ @@ -116,21 +29,21 @@ async def connect_local_browser( Args: playwright: The Playwright instance - local_browser_launch_options: Options for launching the local browser + browser_launch_options: Options for launching the browser stagehand_instance: The Stagehand instance (for context initialization) logger: The logger instance Returns: tuple of (browser, context, stagehand_context, page, temp_user_data_dir) """ - cdp_url = local_browser_launch_options.get("cdp_url") + cdp_url = browser_launch_options.get("cdp_url") temp_user_data_dir = None if cdp_url: - logger.info(f"Connecting to local browser via CDP URL: {cdp_url}") + logger.info(f"Connecting to browser via CDP URL: {cdp_url}") try: browser = await playwright.chromium.connect_over_cdp( - cdp_url, headers=local_browser_launch_options.get("headers") + cdp_url, headers=browser_launch_options.get("headers") ) if not browser.contexts: @@ -142,10 +55,10 @@ async def connect_local_browser( logger.error(f"Failed to connect via CDP URL ({cdp_url}): {str(e)}") raise else: - logger.info("Launching new local browser context...") + logger.info("Launching new browser context...") browser = None - user_data_dir_option = local_browser_launch_options.get("user_data_dir") + user_data_dir_option = browser_launch_options.get("user_data_dir") if user_data_dir_option: user_data_dir = Path(user_data_dir_option).resolve() else: @@ -169,7 +82,7 @@ async def connect_local_browser( f"Failed to write default preferences to {prefs_path}: {e}" ) - downloads_path_option = local_browser_launch_options.get("downloads_path") + downloads_path_option = browser_launch_options.get("downloads_path") if downloads_path_option: downloads_path = str(Path(downloads_path_option).resolve()) else: @@ -182,27 +95,27 @@ async def connect_local_browser( # Prepare Launch Options (translate keys if needed) launch_options = { - "headless": local_browser_launch_options.get("headless", False), - "accept_downloads": local_browser_launch_options.get( + "headless": browser_launch_options.get("headless", False), + "accept_downloads": browser_launch_options.get( "acceptDownloads", True ), "downloads_path": downloads_path, - "args": local_browser_launch_options.get( + "args": browser_launch_options.get( "args", [ "--disable-blink-features=AutomationControlled", ], ), - "viewport": local_browser_launch_options.get( + "viewport": browser_launch_options.get( "viewport", {"width": 1024, "height": 768} ), - "locale": local_browser_launch_options.get("locale", "en-US"), - "timezone_id": local_browser_launch_options.get( + "locale": browser_launch_options.get("locale", "en-US"), + "timezone_id": browser_launch_options.get( "timezoneId", "America/New_York" ), - "bypass_csp": local_browser_launch_options.get("bypassCSP", True), - "proxy": local_browser_launch_options.get("proxy"), - "ignore_https_errors": local_browser_launch_options.get( + "bypass_csp": browser_launch_options.get("bypassCSP", True), + "proxy": browser_launch_options.get("proxy"), + "ignore_https_errors": browser_launch_options.get( "ignoreHTTPSErrors", True ), } @@ -215,11 +128,11 @@ async def connect_local_browser( **launch_options, ) stagehand_context = await StagehandContext.init(context, stagehand_instance) - logger.info("Local browser context launched successfully.") + logger.info("Browser context launched successfully.") browser = context.browser except Exception as e: - logger.error(f"Failed to launch local browser context: {str(e)}") + logger.error(f"Failed to launch browser context: {str(e)}") if temp_user_data_dir: try: shutil.rmtree(temp_user_data_dir) @@ -227,7 +140,7 @@ async def connect_local_browser( pass raise - cookies = local_browser_launch_options.get("cookies") + cookies = browser_launch_options.get("cookies") if cookies: try: await context.add_cookies(cookies) @@ -241,7 +154,7 @@ async def connect_local_browser( # Get the initial page (usually one is created by default) if context.pages: playwright_page = context.pages[0] - logger.debug("Using initial page from local context.") + logger.debug("Using initial page from context.") page = await stagehand_context.get_stagehand_page(playwright_page) else: logger.debug("No initial page found, creating a new one.") diff --git a/stagehand/config.py b/stagehand/config.py index e69faa20..04595c4f 100644 --- a/stagehand/config.py +++ b/stagehand/config.py @@ -2,69 +2,78 @@ from typing import Any, Callable, Literal, Optional, Union from browserbase.types import SessionCreateParams as BrowserbaseSessionCreateParams -from pydantic import BaseModel, ConfigDict, Field, field_validator +from pydantic import BaseModel, ConfigDict, Field, field_validator, ValidationError from stagehand.schemas import AvailableModel +class StagehandConfigError(Exception): + """Exception raised for Stagehand configuration errors.""" + pass + + class StagehandConfig(BaseModel): """ Configuration for the Stagehand client. + This configuration is designed for local browser automation using Playwright. + All browser operations run locally without external service dependencies. + Attributes: - env (str): Environment type. 'BROWSERBASE' for remote usage - api_key (Optional[str]): BrowserbaseAPI key for authentication. - project_id (Optional[str]): Browserbase Project identifier. - api_url (Optional[str]): Stagehand API URL. - browserbase_session_create_params (Optional[BrowserbaseSessionCreateParams]): Browserbase session create params. - browserbase_session_id (Optional[str]): Session ID for resuming Browserbase sessions. - model_name (Optional[str]): Name of the model to use. - model_api_key (Optional[str]): Model API key. - model_client_options (Optional[dict[str, Any]]): Options for the model client. + model_name (Optional[str]): Name of the language model to use for AI operations. + model_api_key (Optional[str]): API key for the language model provider. + model_client_options (Optional[dict[str, Any]]): Configuration options for the language model client. + Supports custom API endpoints via 'api_base' parameter for OpenAI/Anthropic compatible providers. + Examples: + - OpenAI: {"api_base": "https://api.openai.com/v1", "api_key": "your-key"} + - Anthropic: {"api_base": "https://api.anthropic.com", "api_key": "your-key"} + - Together AI: {"api_base": "https://api.together.xyz/v1", "api_key": "your-key"} + - Local OpenAI server: {"api_base": "http://localhost:8000/v1", "api_key": "local-key"} + verbose (Optional[int]): Verbosity level for logs (0=ERROR, 1=INFO, 2=DEBUG). logger (Optional[Callable[[Any], None]]): Custom logging function. - verbose (Optional[int]): Verbosity level for logs (1=minimal, 2=medium, 3=detailed). - use_rich_logging (bool): Whether to use Rich for colorized logging. - dom_settle_timeout_ms (Optional[int]): Timeout for DOM to settle (in milliseconds). - enable_caching (Optional[bool]): Enable caching functionality. - self_heal (Optional[bool]): Enable self-healing functionality. - wait_for_captcha_solves (Optional[bool]): Whether to wait for CAPTCHA to be solved. - act_timeout_ms (Optional[int]): Timeout for act commands (in milliseconds). - headless (bool): Run browser in headless mode - system_prompt (Optional[str]): System prompt to use for LLM interactions. - local_browser_launch_options (Optional[dict[str, Any]]): Local browser launch options. - use_api (bool): Whether to use API mode. - experimental (bool): Enable experimental features. + use_rich_logging (Optional[bool]): Whether to use Rich for colorized logging. + dom_settle_timeout_ms (Optional[int]): Timeout for DOM to settle after actions (in milliseconds). + enable_caching (Optional[bool]): Enable caching functionality for improved performance. + self_heal (Optional[bool]): Enable self-healing functionality to recover from failures. + wait_for_captcha_solves (Optional[bool]): Whether to wait for CAPTCHA to be solved manually. + system_prompt (Optional[str]): Custom system prompt to use for LLM interactions. + local_browser_launch_options (Optional[dict[str, Any]]): Options for launching the local browser. + Supports all Playwright browser launch options such as: + - headless: bool - Run browser in headless mode + - viewport: dict - Set viewport size + - user_data_dir: str - Browser profile directory + - args: list - Additional browser arguments + experimental (Optional[bool]): Enable experimental features (use with caution). """ - env: Literal["BROWSERBASE", "LOCAL"] = "BROWSERBASE" - api_key: Optional[str] = Field( - None, alias="apiKey", description="Browserbase API key for authentication" - ) - project_id: Optional[str] = Field( - None, alias="projectId", description="Browserbase project ID" - ) - api_url: Optional[str] = Field( - os.environ.get("STAGEHAND_API_URL", "https://api.stagehand.browserbase.com/v1"), - alias="apiUrl", - description="Stagehand API URL", + model_name: Optional[str] = Field( + AvailableModel.GPT_4O, + alias="modelName", + description="Name of the language model to use for AI operations" ) model_api_key: Optional[str] = Field( - None, alias="modelApiKey", description="Model API key" + None, + alias="modelApiKey", + description="API key for the language model provider" ) model_client_options: Optional[dict[str, Any]] = Field( None, alias="modelClientOptions", - description="Configuration options for the language model client (i.e. api_base)", + description="Configuration options for the language model client. " + "Use 'api_base' to specify custom API endpoints for OpenAI/Anthropic compatible providers. " + "Example: {'api_base': 'https://api.together.xyz/v1', 'api_key': 'your-key'}", ) verbose: Optional[int] = Field( 1, - description="Verbosity level for logs: 0=minimal (ERROR), 1=medium (INFO), 2=detailed (DEBUG)", + description="Verbosity level for logs: 0=ERROR only, 1=INFO and above, 2=DEBUG and above", ) logger: Optional[Callable[[Any], None]] = Field( - None, description="Custom logging function" + None, + description="Custom logging function to override default logging behavior" ) use_rich_logging: Optional[bool] = Field( - True, description="Whether to use Rich for colorized logging" + True, + description="Whether to use Rich library for colorized and formatted logging output" ) dom_settle_timeout_ms: Optional[int] = Field( 3000, @@ -79,47 +88,97 @@ class StagehandConfig(BaseModel): description="Browserbase session create params", ) enable_caching: Optional[bool] = Field( - False, alias="enableCaching", description="Enable caching functionality" - ) - browserbase_session_id: Optional[str] = Field( - None, - alias="browserbaseSessionID", - description="Session ID for resuming Browserbase sessions", - ) - model_name: Optional[str] = Field( - AvailableModel.GPT_4O, alias="modelName", description="Name of the model to use" + False, + alias="enableCaching", + description="Enable caching functionality to improve performance by reusing results" ) self_heal: Optional[bool] = Field( - True, alias="selfHeal", description="Enable self-healing functionality" + True, + alias="selfHeal", + description="Enable self-healing functionality to automatically recover from failures" ) wait_for_captcha_solves: Optional[bool] = Field( False, alias="waitForCaptchaSolves", - description="Whether to wait for CAPTCHA to be solved", + description="Whether to pause execution and wait for manual CAPTCHA solving", ) system_prompt: Optional[str] = Field( None, alias="systemPrompt", - description="System prompt to use for LLM interactions", + description="Custom system prompt to use for LLM interactions, overrides default prompts", ) local_browser_launch_options: Optional[dict[str, Any]] = Field( {}, alias="localBrowserLaunchOptions", - description="Local browser launch options", - ) - use_api: Optional[bool] = Field( - True, - alias=None, - description="Whether to use the Stagehand API", + description="Options for launching the local Playwright browser instance. " + "Supports all Playwright launch options like headless, viewport, user_data_dir, args, etc.", ) experimental: Optional[bool] = Field( False, - alias=None, - description="Whether to use experimental features", + description="Enable experimental features that may be unstable or change in future versions", ) model_config = ConfigDict(populate_by_name=True) + @field_validator("model_client_options") + @classmethod + def validate_model_client_options(cls, v): + """Validate model_client_options configuration with enhanced validation.""" + if v is None: + return v + + if not isinstance(v, dict): + raise ValueError("model_client_options must be a dictionary") + + # Validate api_base if provided + api_base = v.get("api_base") or v.get("baseURL") + if api_base: + validation_result = validate_api_base_url(api_base) + if not validation_result["valid"]: + raise ValueError(validation_result["error"]) + + # Normalize the URL (remove trailing slash) + normalized_url = validation_result["normalized_url"] + if "api_base" in v: + v["api_base"] = normalized_url + if "baseURL" in v: + v["baseURL"] = normalized_url + + # Validate timeout if provided + if "timeout" in v: + timeout = v["timeout"] + if not isinstance(timeout, (int, float)) or timeout <= 0: + raise ValueError("timeout must be a positive number") + + # Validate max_retries if provided + if "max_retries" in v: + max_retries = v["max_retries"] + if not isinstance(max_retries, int) or max_retries < 0: + raise ValueError("max_retries must be a non-negative integer") + + # Validate API key variants + api_key_fields = ["api_key", "apiKey"] + api_keys_found = [field for field in api_key_fields if field in v] + if len(api_keys_found) > 1: + raise ValueError(f"Only one API key field should be specified, found: {api_keys_found}") + + return v + + @field_validator("verbose") + @classmethod + def validate_verbose(cls, v): + """Validate verbose level is within acceptable range.""" + if v is not None and not (0 <= v <= 2): + raise ValueError("verbose must be 0 (ERROR), 1 (INFO), or 2 (DEBUG)") + return v + + @field_validator("dom_settle_timeout_ms") + @classmethod + def validate_dom_settle_timeout(cls, v): + """Validate DOM settle timeout is positive.""" + if v is not None and v < 0: + raise ValueError("dom_settle_timeout_ms must be non-negative") + @field_validator("browserbase_session_create_params", mode="before") @classmethod def validate_browserbase_params(cls, v, info): @@ -146,5 +205,406 @@ def with_overrides(self, **overrides) -> "StagehandConfig": return StagehandConfig(**config_dict) -# Default configuration instance +# Configuration validation utility functions + +def validate_api_base_url(api_base: str) -> dict[str, Any]: + """ + Validate an API base URL with comprehensive checks. + + Args: + api_base: The API base URL to validate + + Returns: + Dictionary with validation results: + - valid: bool - Whether the URL is valid + - error: str - Error message if invalid + - normalized_url: str - Normalized URL if valid + - warnings: list - List of warning messages + """ + result = { + "valid": False, + "error": "", + "normalized_url": "", + "warnings": [] + } + + if not isinstance(api_base, str): + result["error"] = "api_base must be a string" + return result + + if not api_base.strip(): + result["error"] = "api_base cannot be empty" + return result + + # Check for valid URL scheme + if not (api_base.startswith("http://") or api_base.startswith("https://")): + result["error"] = "api_base must be a valid HTTP/HTTPS URL" + return result + + try: + parsed = urlparse(api_base) + + # Check for valid hostname + if not parsed.netloc: + result["error"] = "api_base must have a valid hostname" + return result + + # Warn about localhost/local IPs for production use + if parsed.hostname in ["localhost", "127.0.0.1", "0.0.0.0"]: + result["warnings"].append("Using localhost/local IP - ensure this is intended for development") + + # Warn about HTTP (non-HTTPS) for production APIs + if parsed.scheme == "http" and parsed.hostname not in ["localhost", "127.0.0.1", "0.0.0.0"]: + result["warnings"].append("Using HTTP instead of HTTPS - consider using HTTPS for security") + + # Normalize URL (remove trailing slash) + normalized = api_base.rstrip("/") + + result["valid"] = True + result["normalized_url"] = normalized + + except Exception as e: + result["error"] = f"Invalid URL format: {e}" + + return result + + +def validate_api_key_configuration(model_name: Optional[str], model_api_key: Optional[str], + model_client_options: Optional[dict[str, Any]]) -> dict[str, Any]: + """ + Validate API key configuration for different LLM providers. + + Args: + model_name: The model name to infer provider + model_api_key: Direct API key + model_client_options: Client options that may contain API key + + Returns: + Dictionary with validation results: + - valid: bool - Whether API key configuration is valid + - errors: list - List of error messages + - warnings: list - List of warning messages + - provider: str - Detected provider + - api_key_source: str - Where the API key was found + """ + result = { + "valid": True, + "errors": [], + "warnings": [], + "provider": None, + "api_key_source": None + } + + # Infer provider from model name + provider = infer_provider_from_model_name(model_name) + result["provider"] = provider + + if not provider: + result["warnings"].append("Could not infer provider from model name - API key validation may be incomplete") + return result + + # Check for API key in various locations + api_key_found = False + + # Check direct API key + if model_api_key: + api_key_found = True + result["api_key_source"] = "model_api_key" + + # Check API key in model_client_options + if model_client_options: + client_api_key = model_client_options.get("api_key") or model_client_options.get("apiKey") + if client_api_key: + if api_key_found: + result["warnings"].append("API key found in multiple locations - model_client_options will take precedence") + api_key_found = True + result["api_key_source"] = "model_client_options" + + # Check environment variables + env_key_map = { + "openai": "OPENAI_API_KEY", + "anthropic": "ANTHROPIC_API_KEY", + "together": "TOGETHER_API_KEY", + "groq": "GROQ_API_KEY", + "google": "GOOGLE_API_KEY", + "cohere": "COHERE_API_KEY", + } + + env_key = env_key_map.get(provider) + env_api_key = None + if env_key: + env_api_key = os.getenv(env_key) + if env_api_key: + if not api_key_found: + api_key_found = True + result["api_key_source"] = f"environment ({env_key})" + elif result["api_key_source"] != "model_client_options": + result["warnings"].append(f"API key found in both configuration and environment variable {env_key}") + + # Validate API key presence + if not api_key_found: + result["valid"] = False + if env_key: + result["errors"].append( + f"No API key found for {provider} provider. " + f"Please provide an API key via model_api_key, model_client_options['api_key'], " + f"or set the {env_key} environment variable." + ) + else: + result["errors"].append( + f"No API key found for {provider} provider. " + f"Please provide an API key via model_api_key or model_client_options['api_key']." + ) + + return result + + +def infer_provider_from_model_name(model_name: Optional[str]) -> Optional[str]: + """ + Infer the LLM provider from the model name. + + Args: + model_name: The model name + + Returns: + The inferred provider name or None if cannot be determined + """ + if not model_name: + return None + + model_lower = model_name.lower() + + # OpenAI models + if model_lower.startswith("gpt-") or "openai" in model_lower: + return "openai" + + # Anthropic models + if model_lower.startswith("claude-") or "anthropic" in model_lower: + return "anthropic" + + # Together AI models + if "together" in model_lower or model_lower.startswith("meta-llama/") or model_lower.startswith("mistralai/"): + return "together" + + # Groq models + if "groq" in model_lower or model_lower.startswith("llama") or model_lower.startswith("mixtral"): + return "groq" + + # Google models + if model_lower.startswith("gemini") or model_lower.startswith("google/") or "palm" in model_lower: + return "google" + + # Cohere models + if model_lower.startswith("command") or "cohere" in model_lower: + return "cohere" + + return None + + +def validate_stagehand_config(config: StagehandConfig) -> dict[str, Any]: + """ + Perform comprehensive validation of a StagehandConfig instance. + + Args: + config: The StagehandConfig instance to validate + + Returns: + Dictionary with validation results: + - valid: bool - Whether the configuration is valid + - errors: list - List of error messages + - warnings: list - List of warning messages + - recommendations: list - List of recommendations for improvement + """ + result = { + "valid": True, + "errors": [], + "warnings": [], + "recommendations": [] + } + + # Validate model configuration + if not config.model_name: + result["errors"].append("model_name is required") + result["valid"] = False + + # Validate API key configuration + api_key_validation = validate_api_key_configuration( + config.model_name, + config.model_api_key, + config.model_client_options + ) + + if not api_key_validation["valid"]: + result["errors"].extend(api_key_validation["errors"]) + result["valid"] = False + + result["warnings"].extend(api_key_validation["warnings"]) + + # Validate model_client_options if present + if config.model_client_options: + api_base = config.model_client_options.get("api_base") or config.model_client_options.get("baseURL") + if api_base: + url_validation = validate_api_base_url(api_base) + if not url_validation["valid"]: + result["errors"].append(f"Invalid api_base URL: {url_validation['error']}") + result["valid"] = False + else: + result["warnings"].extend(url_validation["warnings"]) + + # Validate verbose level + if config.verbose is not None and not (0 <= config.verbose <= 2): + result["errors"].append("verbose must be 0 (ERROR), 1 (INFO), or 2 (DEBUG)") + result["valid"] = False + + # Validate timeout settings + if config.dom_settle_timeout_ms is not None and config.dom_settle_timeout_ms < 0: + result["errors"].append("dom_settle_timeout_ms must be non-negative") + result["valid"] = False + + # Validate browser launch options + if config.local_browser_launch_options: + browser_validation = validate_browser_launch_options(config.local_browser_launch_options) + result["warnings"].extend(browser_validation["warnings"]) + if browser_validation["errors"]: + result["errors"].extend(browser_validation["errors"]) + result["valid"] = False + + # Add recommendations + if config.verbose == 2: + result["recommendations"].append("Debug logging (verbose=2) may impact performance in production") + + if not config.enable_caching: + result["recommendations"].append("Consider enabling caching for better performance") + + if config.experimental: + result["warnings"].append("Experimental features are enabled - use with caution in production") + + return result + + +def validate_browser_launch_options(options: dict[str, Any]) -> dict[str, Any]: + """ + Validate browser launch options. + + Args: + options: Browser launch options dictionary + + Returns: + Dictionary with validation results + """ + result = { + "errors": [], + "warnings": [] + } + + if not isinstance(options, dict): + result["errors"].append("local_browser_launch_options must be a dictionary") + return result + + # Validate headless option + if "headless" in options and not isinstance(options["headless"], bool): + result["errors"].append("headless option must be a boolean") + + # Validate viewport + if "viewport" in options: + viewport = options["viewport"] + if not isinstance(viewport, dict): + result["errors"].append("viewport must be a dictionary") + else: + if "width" in viewport and (not isinstance(viewport["width"], int) or viewport["width"] <= 0): + result["errors"].append("viewport width must be a positive integer") + if "height" in viewport and (not isinstance(viewport["height"], int) or viewport["height"] <= 0): + result["errors"].append("viewport height must be a positive integer") + + # Validate args + if "args" in options: + args = options["args"] + if not isinstance(args, list): + result["errors"].append("args must be a list") + elif not all(isinstance(arg, str) for arg in args): + result["errors"].append("all args must be strings") + + # Validate user_data_dir + if "user_data_dir" in options: + user_data_dir = options["user_data_dir"] + if not isinstance(user_data_dir, str): + result["errors"].append("user_data_dir must be a string") + + # Validate downloads_path + if "downloads_path" in options: + downloads_path = options["downloads_path"] + if not isinstance(downloads_path, str): + result["errors"].append("downloads_path must be a string") + + return result + + +def create_helpful_error_message(validation_result: dict[str, Any], config_context: str = "") -> str: + """ + Create a helpful error message from validation results. + + Args: + validation_result: Result from validation functions + config_context: Additional context about where the error occurred + + Returns: + Formatted error message with suggestions + """ + if validation_result.get("valid", True): + return "" + + errors = validation_result.get("errors", []) + warnings = validation_result.get("warnings", []) + recommendations = validation_result.get("recommendations", []) + + message_parts = [] + + if config_context: + message_parts.append(f"Configuration Error in {config_context}:") + else: + message_parts.append("Configuration Error:") + + # Add errors + if errors: + message_parts.append("\nErrors:") + for error in errors: + message_parts.append(f" • {error}") + + # Add warnings + if warnings: + message_parts.append("\nWarnings:") + for warning in warnings: + message_parts.append(f" • {warning}") + + # Add recommendations + if recommendations: + message_parts.append("\nRecommendations:") + for rec in recommendations: + message_parts.append(f" • {rec}") + + # Add helpful examples + if any("API key" in error for error in errors): + message_parts.append("\nExample API key configuration:") + message_parts.append(" config = StagehandConfig(") + message_parts.append(" model_name='gpt-4o',") + message_parts.append(" model_client_options={") + message_parts.append(" 'api_key': 'your-api-key-here'") + message_parts.append(" }") + message_parts.append(" )") + message_parts.append("\nOr set environment variable: export OPENAI_API_KEY=your-api-key-here") + + if any("api_base" in error for error in errors): + message_parts.append("\nExample custom API endpoint configuration:") + message_parts.append(" config = StagehandConfig(") + message_parts.append(" model_name='gpt-4o',") + message_parts.append(" model_client_options={") + message_parts.append(" 'api_base': 'https://api.together.xyz/v1',") + message_parts.append(" 'api_key': 'your-together-api-key'") + message_parts.append(" }") + message_parts.append(" )") + + return "\n".join(message_parts) + + +# Default configuration instance for local browser automation default_config = StagehandConfig() diff --git a/stagehand/llm/__init__.py b/stagehand/llm/__init__.py index a31e4468..e91718b9 100644 --- a/stagehand/llm/__init__.py +++ b/stagehand/llm/__init__.py @@ -1,4 +1,4 @@ -from .client import LLMClient +from .client import LLMClient, LLMProviderError from .inference import extract, observe from .prompts import ( build_extract_system_prompt, diff --git a/stagehand/llm/client.py b/stagehand/llm/client.py index e9fbefe5..87f653b3 100644 --- a/stagehand/llm/client.py +++ b/stagehand/llm/client.py @@ -1,6 +1,7 @@ """LLM client for model interactions.""" -from typing import TYPE_CHECKING, Any, Callable, Optional +import os +from typing import TYPE_CHECKING, Any, Callable, Dict, Optional import litellm @@ -10,55 +11,186 @@ from ..logging import StagehandLogger +class LLMProviderError(Exception): + """Exception raised for LLM provider configuration errors.""" + pass + + class LLMClient: """ - Client for making LLM calls using the litellm library. - Provides a simplified interface for chat completions. + Enhanced client for making LLM calls using the litellm library. + Supports custom API endpoints and multiple providers with proper error handling. """ + # Default API endpoints for different providers + DEFAULT_ENDPOINTS = { + "openai": "https://api.openai.com/v1", + "anthropic": "https://api.anthropic.com", + "together": "https://api.together.xyz/v1", + "groq": "https://api.groq.com/openai/v1", + } + def __init__( self, stagehand_logger: "StagehandLogger", api_key: Optional[str] = None, default_model: Optional[str] = None, metrics_callback: Optional[Callable[[Any, int, Optional[str]], None]] = None, - **kwargs: Any, # To catch other potential litellm global settings + **kwargs: Any, ): """ - Initializes the LiteLLMClient. + Initialize the enhanced LLM client with support for custom API endpoints. Args: stagehand_logger: StagehandLogger instance for centralized logging - api_key: An API key for the default provider, if required. - It's often better to set provider-specific environment variables - (e.g., OPENAI_API_KEY, ANTHROPIC_API_KEY) which litellm reads automatically. - Passing api_key here might set litellm.api_key globally, which may - not be desired if using multiple providers. - default_model: The default model to use if none is specified in chat_completion - (e.g., "gpt-4o", "claude-3-opus-20240229"). + api_key: API key for the model provider + default_model: Default model to use (e.g., "gpt-4o", "claude-3-opus-20240229") metrics_callback: Optional callback to track metrics from responses - **kwargs: Additional global settings for litellm (e.g., api_base). - See litellm documentation for available settings. + **kwargs: Additional configuration options including: + - api_base: Custom API base URL + - baseURL: Alias for api_base + - timeout: Request timeout in seconds + - max_retries: Maximum number of retries + - Other litellm global settings """ self.logger = stagehand_logger self.default_model = default_model self.metrics_callback = metrics_callback + + # Store original configuration for validation and fallback + self.config = kwargs.copy() + self.api_key = api_key + + # Validate and configure API settings + self._configure_api_settings(api_key, **kwargs) + + # Perform initial validation + self._validate_initial_configuration() - # Warning:Prefer environment variables for specific providers. - if api_key: - litellm.api_key = api_key - - # Apply other global settings if provided - for key, value in kwargs.items(): - if hasattr(litellm, key): - setattr(litellm, key, value) - self.logger.debug(f"Set global litellm.{key}", category="llm") - # Handle common aliases or expected config names if necessary - elif key == "api_base" or key == "baseURL": - litellm.api_base = value - self.logger.debug( - f"Set global litellm.api_base to {value}", category="llm" - ) + def _configure_api_settings(self, api_key: Optional[str], **kwargs: Any) -> None: + """ + Configure API settings with validation and error handling. + + Args: + api_key: API key for the model provider + **kwargs: Additional configuration options + """ + try: + # Handle API key configuration + if api_key: + litellm.api_key = api_key + self.logger.debug("Set API key for LLM client", category="llm") + + # Handle API base URL configuration + api_base = kwargs.get("api_base") or kwargs.get("baseURL") + if api_base: + self._validate_api_base(api_base) + litellm.api_base = api_base + self.logger.debug(f"Set custom API base: {api_base}", category="llm") + else: + # Try to infer provider and set default endpoint + provider = self._infer_provider_from_model(self.default_model) + if provider and provider in self.DEFAULT_ENDPOINTS: + default_endpoint = self.DEFAULT_ENDPOINTS[provider] + litellm.api_base = default_endpoint + self.logger.debug(f"Set default API base for {provider}: {default_endpoint}", category="llm") + + # Apply other global settings + for key, value in kwargs.items(): + if key in ["api_base", "baseURL"]: + continue # Already handled above + + if hasattr(litellm, key): + setattr(litellm, key, value) + self.logger.debug(f"Set global litellm.{key} = {value}", category="llm") + elif key in ["timeout", "max_retries"]: + # Store these for per-request use + setattr(self, f"_{key}", value) + self.logger.debug(f"Set client {key} = {value}", category="llm") + + except Exception as e: + self.logger.error(f"Error configuring LLM client: {e}", category="llm") + raise LLMProviderError(f"Failed to configure LLM client: {e}") from e + + def _validate_api_base(self, api_base: str) -> None: + """ + Validate the API base URL format. + + Args: + api_base: The API base URL to validate + + Raises: + LLMProviderError: If the API base URL is invalid + """ + if not isinstance(api_base, str): + raise LLMProviderError("api_base must be a string") + + if not (api_base.startswith("http://") or api_base.startswith("https://")): + raise LLMProviderError("api_base must be a valid HTTP/HTTPS URL") + + # Remove trailing slash for consistency + if api_base.endswith("/"): + api_base = api_base.rstrip("/") + + def _infer_provider_from_model(self, model: Optional[str]) -> Optional[str]: + """ + Infer the provider from the model name. + + Args: + model: The model name + + Returns: + The inferred provider name or None if cannot be determined + """ + if not model: + return None + + model_lower = model.lower() + + if model_lower.startswith("gpt-") or "openai" in model_lower: + return "openai" + elif model_lower.startswith("claude-") or "anthropic" in model_lower: + return "anthropic" + elif "together" in model_lower: + return "together" + elif "groq" in model_lower: + return "groq" + elif model_lower.startswith("gemini/") or model_lower.startswith("google/"): + return "google" + + return None + + def _get_provider_specific_config(self, model: str) -> Dict[str, Any]: + """ + Get provider-specific configuration for the model. + + Args: + model: The model name + + Returns: + Dictionary of provider-specific configuration + """ + provider = self._infer_provider_from_model(model) + config = {} + + # Add provider-specific configurations + if provider == "anthropic": + # Anthropic models may need specific headers or parameters + config.update({ + "anthropic_version": "2023-06-01", + }) + elif provider == "together": + # Together AI specific configurations + config.update({ + "stream": False, # Ensure streaming is handled properly + }) + elif provider == "groq": + # Groq specific configurations + config.update({ + "stream": False, + }) + + return config def create_response( self, @@ -69,62 +201,70 @@ def create_response( **kwargs: Any, ) -> dict[str, Any]: """ - Generate a chat completion response using litellm. + Generate a chat completion response with enhanced error handling and provider support. Args: - messages: A list of message dictionaries, e.g., [{"role": "user", "content": "Hello"}]. - model: The specific model to use (e.g., "gpt-4o", "claude-3-opus-20240229"). - Overrides the default_model if provided. - function_name: The name of the Stagehand function calling this method (ACT, OBSERVE, etc.) - Used for metrics tracking. - **kwargs: Additional parameters to pass directly to litellm.completion - (e.g., temperature, max_tokens, stream=True, specific provider arguments). + messages: List of message dictionaries + model: Specific model to use (overrides default_model) + function_name: Function name for metrics tracking + **kwargs: Additional parameters for litellm.completion Returns: - A dictionary containing the completion response from litellm, typically - including choices, usage statistics, etc. Structure depends on the model - provider and whether streaming is used. + Dictionary containing the completion response Raises: - ValueError: If no model is specified (neither default nor in the call). - Exception: Propagates exceptions from litellm.completion. + ValueError: If no model is specified + LLMProviderError: If there's a provider configuration error + Exception: Other errors from litellm.completion """ completion_model = model or self.default_model if not completion_model: raise ValueError( - "No model specified for chat completion (neither default_model nor model argument)." + "No model specified for chat completion. Please provide a model name " + "either in the constructor (default_model) or in this method call." ) - # Standardize gemini provider to google - if completion_model.startswith("google/"): - completion_model = completion_model.replace("google/", "gemini/") - - # Prepare arguments directly from kwargs + # Standardize model names + completion_model = self._standardize_model_name(completion_model) + + # Get provider-specific configuration + provider_config = self._get_provider_specific_config(completion_model) + + # Prepare parameters params = { "model": completion_model, "messages": messages, - **kwargs, # Pass through any extra arguments + **provider_config, + **kwargs, } - # Filter out None values only for keys explicitly present in kwargs to avoid sending nulls - # unless they were intentionally provided as None. + + # Add client-level settings if available + if hasattr(self, "_timeout"): + params["timeout"] = self._timeout + if hasattr(self, "_max_retries"): + params["max_retries"] = self._max_retries + + # Filter out None values filtered_params = { k: v for k, v in params.items() if v is not None or k in kwargs } - # Fixes parameters for GPT-5 family of models + + # Apply model-specific fixes if "gpt-5" in completion_model: filtered_params["temperature"] = 1 self.logger.debug( - f"Calling litellm.completion with model={completion_model} and params: {filtered_params}", + f"Calling litellm.completion with model={completion_model}", category="llm", + auxiliary={"params": {k: v for k, v in filtered_params.items() if k != "messages"}} ) try: # Start tracking inference time start_time = start_inference_timer() - # Use litellm's completion function - response = litellm.completion(**filtered_params) + # Make the API call with retry logic + response = self._make_api_call_with_retry(filtered_params) # Calculate inference time inference_time_ms = get_inference_time_ms(start_time) @@ -133,9 +273,162 @@ def create_response( if self.metrics_callback: self.metrics_callback(response, inference_time_ms, function_name) + self.logger.debug( + f"Successfully received response from {completion_model}", + category="llm", + auxiliary={ + "inference_time_ms": inference_time_ms, + "prompt_tokens": getattr(response.usage, "prompt_tokens", 0) if hasattr(response, "usage") else 0, + "completion_tokens": getattr(response.usage, "completion_tokens", 0) if hasattr(response, "usage") else 0, + } + ) + return response except Exception as e: - self.logger.error(f"Error calling litellm.completion: {e}", category="llm") - # Consider more specific exception handling based on litellm errors - raise + error_msg = f"Error calling litellm.completion with model {completion_model}: {e}" + self.logger.error(error_msg, category="llm") + + # Provide helpful error messages based on common issues + if "api_key" in str(e).lower(): + raise LLMProviderError( + f"API key error for model {completion_model}. " + f"Please check your API key configuration in model_client_options. " + f"Original error: {e}" + ) from e + elif "not found" in str(e).lower() or "404" in str(e): + raise LLMProviderError( + f"Model {completion_model} not found. " + f"Please check the model name and your API endpoint configuration. " + f"Original error: {e}" + ) from e + elif "unauthorized" in str(e).lower() or "401" in str(e): + raise LLMProviderError( + f"Unauthorized access for model {completion_model}. " + f"Please check your API key and permissions. " + f"Original error: {e}" + ) from e + elif "rate limit" in str(e).lower() or "429" in str(e): + raise LLMProviderError( + f"Rate limit exceeded for model {completion_model}. " + f"Please try again later or check your usage limits. " + f"Original error: {e}" + ) from e + else: + raise LLMProviderError(f"LLM API error: {e}") from e + + def _standardize_model_name(self, model: str) -> str: + """ + Standardize model names for different providers. + + Args: + model: Original model name + + Returns: + Standardized model name + """ + # Standardize gemini provider to google + if model.startswith("google/"): + return model.replace("google/", "gemini/") + + return model + + def _make_api_call_with_retry(self, params: Dict[str, Any]) -> Any: + """ + Make API call with built-in retry logic. + + Args: + params: Parameters for the API call + + Returns: + Response from litellm.completion + """ + max_retries = getattr(self, "_max_retries", 3) + + for attempt in range(max_retries + 1): + try: + return litellm.completion(**params) + except Exception as e: + if attempt == max_retries: + raise + + # Only retry on certain types of errors + if any(error_type in str(e).lower() for error_type in ["timeout", "connection", "rate limit"]): + self.logger.debug( + f"Retrying API call (attempt {attempt + 1}/{max_retries + 1}) after error: {e}", + category="llm" + ) + continue + else: + # Don't retry on authentication, not found, or other permanent errors + raise + + def validate_configuration(self) -> Dict[str, Any]: + """ + Validate the current LLM client configuration. + + Returns: + Dictionary containing validation results and configuration info + """ + validation_result = { + "valid": True, + "errors": [], + "warnings": [], + "configuration": { + "default_model": self.default_model, + "api_key_configured": bool(self.api_key), + "api_base": getattr(litellm, "api_base", None), + "provider": self._infer_provider_from_model(self.default_model), + } + } + + # Check if model is specified + if not self.default_model: + validation_result["errors"].append("No default model specified") + validation_result["valid"] = False + + # Check if API key is available (either directly or via environment) + provider = self._infer_provider_from_model(self.default_model) + if provider: + env_key_map = { + "openai": "OPENAI_API_KEY", + "anthropic": "ANTHROPIC_API_KEY", + "together": "TOGETHER_API_KEY", + "groq": "GROQ_API_KEY", + } + + env_key = env_key_map.get(provider) + if not self.api_key and not (env_key and os.getenv(env_key)): + validation_result["warnings"].append( + f"No API key found for {provider}. " + f"Consider setting {env_key} environment variable or providing api_key in model_client_options." + ) + + return validation_result + + def _validate_initial_configuration(self) -> None: + """ + Validate the initial LLM client configuration and log any issues. + + Raises: + LLMProviderError: If critical configuration issues are found + """ + validation_result = self.validate_configuration() + + # Log warnings + for warning in validation_result["warnings"]: + self.logger.warn(f"LLM configuration: {warning}", category="llm") + + # Handle errors - for now we log them but don't fail initialization + # This allows the client to work with environment variables that might be set later + for error in validation_result["errors"]: + self.logger.warn(f"LLM configuration issue: {error}", category="llm") + + # Log configuration info + config_info = validation_result["configuration"] + self.logger.debug( + f"LLM client initialized - Provider: {config_info.get('provider', 'unknown')}, " + f"Model: {config_info.get('default_model', 'none')}, " + f"API Key: {'configured' if config_info.get('api_key_configured') else 'not configured'}", + category="llm" + ) diff --git a/stagehand/logging.py b/stagehand/logging.py index f1370b8c..4180a5c4 100644 --- a/stagehand/logging.py +++ b/stagehand/logging.py @@ -32,7 +32,6 @@ def __init__( Args: verbose: Verbosity level (0=error, 1=info, 2=debug) use_rich: Whether to use Rich for formatted output - env: Environment ("LOCAL" or "BROWSERBASE") external_logger: Optional external logging callback quiet_dependencies: Whether to quiet noisy dependencies """ diff --git a/stagehand/main.py b/stagehand/main.py index a2bde834..a89bbfa8 100644 --- a/stagehand/main.py +++ b/stagehand/main.py @@ -6,7 +6,6 @@ from pathlib import Path from typing import Any, Optional -import httpx import nest_asyncio from dotenv import load_dotenv from playwright.async_api import ( @@ -17,19 +16,17 @@ from playwright.async_api import Page as PlaywrightPage from .agent import Agent -from .api import _create_session, _execute, _get_replay_metrics from .browser import ( cleanup_browser_resources, - connect_browserbase_browser, - connect_local_browser, + connect_browser, ) -from .config import StagehandConfig, default_config +from .config import StagehandConfig, StagehandConfigError, default_config, validate_stagehand_config, create_helpful_error_message from .context import StagehandContext from .llm import LLMClient from .logging import StagehandLogger, default_log_handler from .metrics import StagehandFunctionName, StagehandMetrics from .page import StagehandPage -from .utils import get_download_path, make_serializable +from .utils import get_download_path load_dotenv() @@ -128,10 +125,9 @@ def __repr__(self): class Stagehand: """ - Main Stagehand class. + Main Stagehand class for local browser automation. """ - _session_locks = {} _cleanup_called = False def __init__( @@ -140,7 +136,7 @@ def __init__( **config_overrides, ): """ - Initialize the Stagehand client. + Initialize the Stagehand client for local browser automation. Args: config (Optional[StagehandConfig]): Configuration object. If not provided, uses default_config. @@ -159,9 +155,6 @@ def __init__( else: self.config = config - # Handle non-config parameters - self.api_url = self.config.api_url - # Handle model-related settings self.model_client_options = self.config.model_client_options or {} self.model_api_key = self.config.model_api_key or os.getenv("MODEL_API_KEY") @@ -169,42 +162,28 @@ def __init__( self.model_name = self.config.model_name # Extract frequently used values from config for convenience - self.browserbase_api_key = self.config.api_key or os.getenv( - "BROWSERBASE_API_KEY" - ) - self.browserbase_project_id = self.config.project_id or os.getenv( - "BROWSERBASE_PROJECT_ID" - ) - self.session_id = self.config.browserbase_session_id self.dom_settle_timeout_ms = self.config.dom_settle_timeout_ms self.self_heal = self.config.self_heal self.wait_for_captcha_solves = self.config.wait_for_captcha_solves self.system_prompt = self.config.system_prompt self.verbose = self.config.verbose - self.env = self.config.env.upper() if self.config.env else "BROWSERBASE" self.local_browser_launch_options = ( self.config.local_browser_launch_options or {} ) + + # Handle API key configuration with better validation if self.model_api_key: - self.model_client_options["apiKey"] = self.model_api_key + # If api_key is provided directly, use it + pass else: + # Try to extract API key from model_client_options if "apiKey" in self.model_client_options: self.model_api_key = self.model_client_options["apiKey"] - - # Handle browserbase session create params - self.browserbase_session_create_params = make_serializable( - self.config.browserbase_session_create_params - ) - - # Handle streaming response setting - self.streamed_response = True - - self.timeout_settings = httpx.Timeout( - connect=180.0, - read=180.0, - write=180.0, - pool=180.0, - ) + elif "api_key" in self.model_client_options: + self.model_api_key = self.model_client_options["api_key"] + else: + # Try to get from environment based on model type + self.model_api_key = self._get_api_key_from_environment() self._local_user_data_dir_temp: Optional[Path] = ( None # To store path if created temporarily @@ -214,10 +193,6 @@ def __init__( self._local_metrics = StagehandMetrics() # Internal storage for local metrics self._inference_start_time = 0 # To track inference time - # Validate env - if self.env not in ["BROWSERBASE", "LOCAL"]: - raise ValueError("env must be either 'BROWSERBASE' or 'LOCAL'") - # Initialize the centralized logger with the specified verbosity self.on_log = self.config.logger or default_log_handler self.logger = StagehandLogger( @@ -225,72 +200,113 @@ def __init__( external_logger=self.on_log, use_rich=self.config.use_rich_logging, ) - - # If using BROWSERBASE, session_id or creation params are needed - if self.env == "BROWSERBASE": - if not self.session_id: - # Check if BROWSERBASE keys are present for session creation - if not self.browserbase_api_key: - raise ValueError( - "browserbase_api_key is required for BROWSERBASE env when no session_id is provided (or set BROWSERBASE_API_KEY in env)." - ) - if not self.browserbase_project_id: - raise ValueError( - "browserbase_project_id is required for BROWSERBASE env when no session_id is provided (or set BROWSERBASE_PROJECT_ID in env)." - ) - if not self.model_api_key: - # Model API key needed if Stagehand server creates the session - self.logger.info( - "model_api_key is recommended when creating a new BROWSERBASE session to configure the Stagehand server's LLM." - ) - elif self.session_id: - # Validate essential fields if session_id was provided for BROWSERBASE - if not self.browserbase_api_key: - raise ValueError( - "browserbase_api_key is required for BROWSERBASE env with existing session_id (or set BROWSERBASE_API_KEY in env)." - ) - if not self.browserbase_project_id: - raise ValueError( - "browserbase_project_id is required for BROWSERBASE env with existing session_id (or set BROWSERBASE_PROJECT_ID in env)." - ) + + # Validate configuration after logger is initialized + self._validate_configuration() # Register signal handlers for graceful shutdown self._register_signal_handlers() - self._client = httpx.AsyncClient(timeout=self.timeout_settings) - + # Initialize browser-related instance variables self._playwright: Optional[Playwright] = None self._browser = None self._context: Optional[BrowserContext] = None self._playwright_page: Optional[PlaywrightPage] = None self._page: Optional[StagehandPage] = None self.context: Optional[StagehandContext] = None - self.use_api = self.config.use_api self.experimental = self.config.experimental - if self.env == "LOCAL": - self.use_api = False - if ( - self.browserbase_session_create_params - and self.browserbase_session_create_params.get("region") - and self.browserbase_session_create_params.get("region") != "us-west-2" - ): - self.use_api = False self._initialized = False # Flag to track if init() has run self._closed = False # Flag to track if resources have been closed self._live_page_proxy = None # Live page proxy self._page_switch_lock = asyncio.Lock() # Lock for page stability - # Setup LLM client if LOCAL mode - self.llm = None - if not self.use_api: + # Setup enhanced LLM client with custom endpoint support + llm_options = self.model_client_options.copy() + + # Remove API key variants from options to avoid conflicts + llm_options.pop("api_key", None) + llm_options.pop("apiKey", None) + + try: self.llm = LLMClient( stagehand_logger=self.logger, api_key=self.model_api_key, default_model=self.model_name, metrics_callback=self._handle_llm_metrics, - **self.model_client_options, + **llm_options, ) + + # Validate the LLM configuration + validation_result = self.llm.validate_configuration() + if not validation_result["valid"]: + for error in validation_result["errors"]: + self.logger.error(f"LLM configuration error: {error}", category="llm") + + for warning in validation_result["warnings"]: + self.logger.info(f"LLM configuration warning: {warning}", category="llm") + + except Exception as e: + self.logger.error(f"Failed to initialize LLM client: {e}", category="llm") + raise RuntimeError(f"Failed to initialize LLM client: {e}") from e + + def _get_api_key_from_environment(self) -> Optional[str]: + """ + Try to get API key from environment variables based on the model type. + + Returns: + API key from environment or None if not found + """ + if not self.model_name: + return None + + model_lower = self.model_name.lower() + + # Try to infer provider and get corresponding environment variable + if model_lower.startswith("gpt-") or "openai" in model_lower: + return os.getenv("OPENAI_API_KEY") + elif model_lower.startswith("claude-") or "anthropic" in model_lower: + return os.getenv("ANTHROPIC_API_KEY") + elif "together" in model_lower: + return os.getenv("TOGETHER_API_KEY") + elif "groq" in model_lower: + return os.getenv("GROQ_API_KEY") + elif model_lower.startswith("gemini") or "google" in model_lower: + return os.getenv("GOOGLE_API_KEY") + + # Fallback to generic environment variables + return os.getenv("MODEL_API_KEY") or os.getenv("LLM_API_KEY") + + def _validate_configuration(self): + """ + Validate the Stagehand configuration and raise helpful errors if invalid. + + Raises: + StagehandConfigError: If configuration is invalid + """ + try: + validation_result = validate_stagehand_config(self.config) + + if not validation_result["valid"]: + error_message = create_helpful_error_message( + validation_result, + "Stagehand initialization" + ) + raise StagehandConfigError(error_message) + + # Log warnings and recommendations + for warning in validation_result["warnings"]: + self.logger.info(f"Configuration warning: {warning}", category="config") + + for recommendation in validation_result["recommendations"]: + self.logger.info(f"Configuration recommendation: {recommendation}", category="config") + + except Exception as e: + if isinstance(e, StagehandConfigError): + raise + else: + # Wrap other validation errors + raise StagehandConfigError(f"Configuration validation failed: {e}") from e def _register_signal_handlers(self): """Register signal handlers for SIGINT and SIGTERM to ensure proper cleanup.""" @@ -302,7 +318,7 @@ def cleanup_handler(sig, frame): self.__class__._cleanup_called = True print( - f"\n[{signal.Signals(sig).name}] received. Ending Browserbase session..." + f"\n[{signal.Signals(sig).name}] received. Cleaning up browser resources..." ) try: @@ -342,9 +358,9 @@ async def _async_cleanup(self): """Async cleanup method called from signal handler.""" try: await self.close() - print(f"Session {self.session_id} ended successfully") + print("Browser resources cleaned up successfully") except Exception as e: - print(f"Error ending Browserbase session: {str(e)}") + print(f"Error cleaning up browser resources: {str(e)}") finally: # Force exit after cleanup completes (or fails) # Use os._exit to avoid any further Python cleanup that might hang @@ -458,13 +474,7 @@ def update_metrics_from_response( except Exception as e: self.logger.debug(f"Failed to update metrics from response: {str(e)}") - def _get_lock_for_session(self) -> asyncio.Lock: - """ - Return an asyncio.Lock for this session. If one doesn't exist yet, create it. - """ - if self.session_id not in self._session_locks: - self._session_locks[self.session_id] = asyncio.Lock() - return self._session_locks[self.session_id] + async def __aenter__(self): self.logger.debug("Entering Stagehand context manager (__aenter__)...") @@ -478,71 +488,54 @@ async def __aexit__(self, exc_type, exc_val, exc_tb): async def init(self): """ - Public init() method. - For BROWSERBASE: Creates or resumes the server session, starts Playwright, connects to remote browser. - For LOCAL: Starts Playwright, launches a local persistent context or connects via CDP. - Sets up self.page in both cases. + Initialize Stagehand for local browser automation. + + This method starts Playwright, launches a local browser instance, and sets up the page. + Only local browser mode is supported - no remote browser connections are available. + + Raises: + RuntimeError: If local browser initialization fails + asyncio.TimeoutError: If Playwright startup times out """ if self._initialized: self.logger.debug("Stagehand is already initialized; skipping init()") return - self.logger.debug("Initializing Stagehand...") - self.logger.debug(f"Environment: {self.env}") + self.logger.debug("Initializing Stagehand for local browser automation...") # Initialize Playwright with timeout - self._playwright = await asyncio.wait_for( - async_playwright().start(), timeout=30.0 # 30 second timeout - ) - - if self.env == "BROWSERBASE": - # Create session if we don't have one - if self.use_api: - await self._create_session() # Uses self._client and api_url - - # Connect to remote browser - try: - ( - self._browser, - self._context, - self.context, - self._page, - ) = await connect_browserbase_browser( - self._playwright, - self.session_id, - self.browserbase_api_key, - self, - self.logger, - ) - self._playwright_page = self._page._page - - except Exception: - await self.close() - raise + try: + self._playwright = await asyncio.wait_for( + async_playwright().start(), timeout=30.0 # 30 second timeout + ) + self.logger.debug("Playwright initialized successfully") + except asyncio.TimeoutError as e: + self.logger.error("Playwright initialization timed out after 30 seconds") + raise RuntimeError("Failed to initialize Playwright: timeout after 30 seconds") from e + except Exception as e: + self.logger.error(f"Failed to initialize Playwright: {str(e)}") + raise RuntimeError(f"Failed to initialize Playwright: {str(e)}") from e - elif self.env == "LOCAL": - # Connect to local browser - try: - ( - self._browser, - self._context, - self.context, - self._page, - self._local_user_data_dir_temp, - ) = await connect_local_browser( - self._playwright, - self.local_browser_launch_options, - self, - self.logger, - ) - self._playwright_page = self._page._page + # Connect to local browser + try: + ( + self._browser, + self._context, + self.context, + self._page, + self._local_user_data_dir_temp, + ) = await connect_browser( + self._playwright, + self.local_browser_launch_options, + self, + self.logger, + ) + self._playwright_page = self._page._page - except Exception: - await self.close() - raise - else: - # Should not happen due to __init__ validation - raise RuntimeError(f"Invalid env value: {self.env}") + except Exception as e: + self.logger.error(f"Failed to initialize local browser: {str(e)}") + await self.close() + raise RuntimeError(f"Failed to initialize Stagehand with local browser: {str(e)}") from e # Set up download behavior via CDP try: @@ -559,7 +552,7 @@ async def init(self): ) self.logger.debug("Set up CDP download behavior") except Exception as e: - self.logger.warning(f"Failed to set up CDP download behavior: {str(e)}") + self.logger.info(f"Failed to set up CDP download behavior: {str(e)}") self._initialized = True @@ -585,43 +578,13 @@ def agent(self, **kwargs) -> Agent: async def close(self): """ - Clean up resources. - For BROWSERBASE: Ends the session on the server and stops Playwright. - For LOCAL: Closes the local context, stops Playwright, and removes temporary directories. + Clean up local browser resources. + Closes the local browser context, stops Playwright, and removes temporary directories. """ if self._closed: return - self.logger.debug("Closing resources...") - - if self.use_api: - # --- BROWSERBASE Cleanup (API) --- - # End the session on the server if we have a session ID - if self.session_id and self._client: # Check if client was initialized - try: - self.logger.debug( - f"Attempting to end server session {self.session_id}..." - ) - # Don't use async with here as it might close the client prematurely - # The _execute method will handle the request properly - result = await self._execute("end", {"sessionId": self.session_id}) - self.logger.debug( - f"Server session {self.session_id} ended successfully with result: {result}" - ) - except Exception as e: - # Log error but continue cleanup - self.logger.error( - f"Error ending server session {self.session_id}: {str(e)}" - ) - elif self.session_id: - self.logger.warning( - "Cannot end server session: HTTP client not available." - ) - - if self._client: - self.logger.debug("Closing the internal HTTPX client...") - await self._client.aclose() - self._client = None + self.logger.debug("Closing local browser resources...") # Use the centralized cleanup function for browser resources await cleanup_browser_resources( @@ -634,62 +597,7 @@ async def close(self): self._closed = True - async def _handle_log(self, msg: dict[str, Any]): - """ - Handle a log message from the server. - First attempts to use the on_log callback, then falls back to formatting the log locally. - """ - try: - log_data = msg.get("data", {}) - - # Call user-provided callback with original data if available - if self.on_log: - await self.on_log(log_data) - return # Early return after on_log to prevent double logging - - # Extract message, category, and level info - message = log_data.get("message", "") - category = log_data.get("category", "") - level_str = log_data.get("level", "info") - auxiliary = log_data.get("auxiliary", {}) - - # Map level strings to internal levels - level_map = { - "debug": 3, - "info": 1, - "warning": 2, - "error": 0, - } - - # Convert string level to int if needed - if isinstance(level_str, str): - internal_level = level_map.get(level_str.lower(), 1) - else: - internal_level = min(level_str, 3) # Ensure level is between 0-3 - - # Handle the case where message itself might be a JSON-like object - if isinstance(message, dict): - # If message is a dict, just pass it directly to the logger - formatted_message = message - elif isinstance(message, str) and ( - message.startswith("{") and ":" in message - ): - # If message looks like JSON but isn't a dict yet, it will be handled by _format_fastify_log - formatted_message = message - else: - # Regular message - formatted_message = message - - # Log using the structured logger - self.logger.log( - formatted_message, - level=internal_level, - category=category, - auxiliary=auxiliary, - ) - except Exception as e: - self.logger.error(f"Error processing log message: {str(e)}") def _log( self, message: str, level: int = 1, category: str = None, auxiliary: dict = None @@ -760,50 +668,12 @@ def page(self) -> Optional[StagehandPage]: return self._live_page_proxy - def __getattribute__(self, name): + @property + def metrics(self) -> StagehandMetrics: """ - Intercept access to 'metrics' to fetch from API when use_api=True. + Get the current metrics for local browser automation. + + Returns: + StagehandMetrics: Current metrics tracking token usage and inference times """ - if name == "metrics": - use_api = ( - object.__getattribute__(self, "use_api") - if hasattr(self, "use_api") - else False - ) - - if use_api: - # Need to fetch from API - try: - # Get the _get_replay_metrics method - get_replay_metrics = object.__getattribute__( - self, "_get_replay_metrics" - ) - - # Try to get current event loop - try: - asyncio.get_running_loop() - # We're in an async context, need to handle this carefully - # Create a new task and wait for it - nest_asyncio.apply() - return asyncio.run(get_replay_metrics()) - except RuntimeError: - # No event loop running, we can use asyncio.run directly - return asyncio.run(get_replay_metrics()) - except Exception as e: - # Log error and return empty metrics - logger = object.__getattribute__(self, "logger") - if logger: - logger.error(f"Failed to fetch metrics from API: {str(e)}") - return StagehandMetrics() - else: - # Return local metrics - return object.__getattribute__(self, "_local_metrics") - - # For all other attributes, use normal behavior - return object.__getattribute__(self, name) - - -# Bind the imported API methods to the Stagehand class -Stagehand._create_session = _create_session -Stagehand._execute = _execute -Stagehand._get_replay_metrics = _get_replay_metrics + return self._local_metrics diff --git a/stagehand/page.py b/stagehand/page.py index 3f2738e1..8a045d05 100644 --- a/stagehand/page.py +++ b/stagehand/page.py @@ -96,11 +96,11 @@ async def goto( Returns: The result from the Stagehand server's navigation execution. """ - if not self._stagehand.use_api: - await self._page.goto( - url, referer=referer, timeout=timeout, wait_until=wait_until - ) - return + # Always use local browser (API mode removed) + await self._page.goto( + url, referer=referer, timeout=timeout, wait_until=wait_until + ) + return options = {} if referer is not None: options["referer"] = referer @@ -170,33 +170,21 @@ async def act( "Invalid arguments for 'act'. Expected str, ObserveResult, or ActOptions." ) - # TODO: Temporary until we move api based logic to client - if not self._stagehand.use_api: - # TODO: revisit passing user_provided_instructions - if not hasattr(self, "_observe_handler"): - # TODO: revisit handlers initialization on page creation - self._observe_handler = ObserveHandler(self, self._stagehand, "") - if not hasattr(self, "_act_handler"): - self._act_handler = ActHandler( - self, self._stagehand, "", self._stagehand.self_heal - ) - self._stagehand.logger.debug("act", category="act", auxiliary=payload) - if payload.get("iframes"): - raise ValueError( - "iframes is not yet supported without API (to enable make sure you set env=BROWSERBASE and use_api=true)" - ) - result = await self._act_handler.act(payload) - return result - - # Add frame ID if available - if self._frame_id: - payload["frameId"] = self._frame_id - - lock = self._stagehand._get_lock_for_session() - async with lock: - result = await self._stagehand._execute("act", payload) - if isinstance(result, dict): - return ActResult(**result) + # Always use local mode (API mode removed) + # TODO: revisit passing user_provided_instructions + if not hasattr(self, "_observe_handler"): + # TODO: revisit handlers initialization on page creation + self._observe_handler = ObserveHandler(self, self._stagehand, "") + if not hasattr(self, "_act_handler"): + self._act_handler = ActHandler( + self, self._stagehand, "", self._stagehand.self_heal + ) + self._stagehand.logger.debug("act", category="act", auxiliary=payload) + if payload.get("iframes"): + raise ValueError( + "iframes is not yet supported in local mode" + ) + result = await self._act_handler.act(payload) return result async def observe( @@ -243,23 +231,22 @@ async def observe( # Serialized payload for server / local handlers payload = options_obj.model_dump(exclude_none=True, by_alias=True) - # If in LOCAL mode, use local implementation - if not self._stagehand.use_api: - self._stagehand.logger.debug( - "observe", category="observe", auxiliary=payload - ) - # If we don't have an observe handler yet, create one - # TODO: revisit passing user_provided_instructions - if not hasattr(self, "_observe_handler"): - self._observe_handler = ObserveHandler(self, self._stagehand, "") - - # Call local observe implementation - result = await self._observe_handler.observe( - options_obj, - from_act=False, - ) + # Always use local implementation (API mode removed) + self._stagehand.logger.debug( + "observe", category="observe", auxiliary=payload + ) + # If we don't have an observe handler yet, create one + # TODO: revisit passing user_provided_instructions + if not hasattr(self, "_observe_handler"): + self._observe_handler = ObserveHandler(self, self._stagehand, "") + + # Call local observe implementation + result = await self._observe_handler.observe( + options_obj, + from_act=False, + ) - return result + return result # Add frame ID if available if self._frame_id: @@ -365,7 +352,7 @@ async def extract( else: schema_to_validate_with = DefaultExtractSchema - if not self._stagehand.use_api: + # Always use local implementation (API mode removed) # If we don't have an extract handler yet, create one if not hasattr(self, "_extract_handler"): self._extract_handler = ExtractHandler( diff --git a/stagehand/utils.py b/stagehand/utils.py index 2383f46f..ae4d689d 100644 --- a/stagehand/utils.py +++ b/stagehand/utils.py @@ -22,37 +22,7 @@ def snake_to_camel(snake_str: str) -> str: return components[0] + "".join(x.title() for x in components[1:]) -def convert_dict_keys_to_camel_case(data: dict[str, Any]) -> dict[str, Any]: - """ - Convert all keys in a dictionary from snake_case to camelCase. - Works recursively for nested dictionaries. - - Args: - data: Dictionary with snake_case keys - - Returns: - Dictionary with camelCase keys - """ - result = {} - - for key, value in data.items(): - if isinstance(value, dict): - value = convert_dict_keys_to_camel_case(value) - elif isinstance(value, list): - value = [ - ( - convert_dict_keys_to_camel_case(item) - if isinstance(item, dict) - else item - ) - for item in value - ] - # Convert snake_case key to camelCase - camel_key = snake_to_camel(key) - result[camel_key] = value - - return result def camel_to_snake(camel_str: str) -> str: @@ -574,12 +544,164 @@ def make_serializable(obj): def get_download_path(stagehand): - if stagehand.env == "BROWSERBASE": - return "downloads" + """Get the download path for local browser mode.""" + if stagehand.local_browser_launch_options.get("downloadPath"): + return stagehand.local_browser_launch_options["downloadPath"] else: - if stagehand.local_browser_launch_options.get("downloadPath"): - return stagehand.local_browser_launch_options["downloadPath"] - else: - path = os.path.join(os.getcwd(), "downloads") - os.makedirs(path, exist_ok=True) - return path + path = os.path.join(os.getcwd(), "downloads") + os.makedirs(path, exist_ok=True) + return path + + +# Configuration validation utilities + +def validate_model_name(model_name: str) -> dict[str, Any]: + """ + Validate a model name and provide suggestions if invalid. + + Args: + model_name: The model name to validate + + Returns: + Dictionary with validation results and suggestions + """ + result = { + "valid": True, + "warnings": [], + "suggestions": [] + } + + if not model_name or not isinstance(model_name, str): + result["valid"] = False + result["suggestions"].append("Model name must be a non-empty string") + return result + + # Common model name patterns and suggestions + common_models = { + "openai": ["gpt-4o", "gpt-4o-mini", "gpt-3.5-turbo"], + "anthropic": ["claude-3-opus-20240229", "claude-3-sonnet-20240229", "claude-3-haiku-20240307"], + "together": ["meta-llama/Llama-2-70b-chat-hf", "mistralai/Mixtral-8x7B-Instruct-v0.1"], + "groq": ["llama2-70b-4096", "mixtral-8x7b-32768"], + "google": ["gemini-pro", "gemini-pro-vision"] + } + + model_lower = model_name.lower() + + # Check for deprecated or potentially incorrect model names + if "davinci" in model_lower or "curie" in model_lower or "babbage" in model_lower: + result["warnings"].append("This appears to be a legacy OpenAI model name. Consider using gpt-3.5-turbo or gpt-4o instead.") + + if model_lower.startswith("text-") and "openai" in model_lower: + result["warnings"].append("Text completion models are deprecated. Consider using chat models like gpt-3.5-turbo.") + + # Provide suggestions based on partial matches + if "gpt" in model_lower and not any(valid in model_lower for valid in ["gpt-3.5", "gpt-4"]): + result["suggestions"].extend(common_models["openai"]) + elif "claude" in model_lower and not model_lower.startswith("claude-3"): + result["suggestions"].extend(common_models["anthropic"]) + + return result + + +def check_environment_setup() -> dict[str, Any]: + """ + Check the environment setup for common configuration issues. + + Returns: + Dictionary with environment check results + """ + result = { + "issues": [], + "warnings": [], + "recommendations": [] + } + + # Check for common environment variables + api_keys = { + "OPENAI_API_KEY": "OpenAI", + "ANTHROPIC_API_KEY": "Anthropic", + "TOGETHER_API_KEY": "Together AI", + "GROQ_API_KEY": "Groq", + "GOOGLE_API_KEY": "Google" + } + + found_keys = [] + for env_var, provider in api_keys.items(): + if os.getenv(env_var): + found_keys.append(provider) + + if not found_keys: + result["warnings"].append("No API keys found in environment variables. You'll need to provide them in configuration.") + else: + result["recommendations"].append(f"Found API keys for: {', '.join(found_keys)}") + + # Check Python version + import sys + if sys.version_info < (3, 8): + result["issues"].append(f"Python {sys.version_info.major}.{sys.version_info.minor} detected. Python 3.8+ is recommended.") + + # Check for required packages + try: + import playwright + result["recommendations"].append("Playwright is available for browser automation") + except ImportError: + result["issues"].append("Playwright not found. Install with: pip install playwright") + + try: + import litellm + result["recommendations"].append("LiteLLM is available for LLM integration") + except ImportError: + result["issues"].append("LiteLLM not found. Install with: pip install litellm") + + return result + + +def suggest_configuration_fixes(validation_errors: list[str]) -> list[str]: + """ + Suggest fixes for common configuration errors. + + Args: + validation_errors: List of validation error messages + + Returns: + List of suggested fixes + """ + suggestions = [] + + for error in validation_errors: + error_lower = error.lower() + + if "api key" in error_lower and "openai" in error_lower: + suggestions.append( + "Set your OpenAI API key:\n" + " - Environment: export OPENAI_API_KEY=your-key\n" + " - Config: model_client_options={'api_key': 'your-key'}" + ) + elif "api key" in error_lower and "anthropic" in error_lower: + suggestions.append( + "Set your Anthropic API key:\n" + " - Environment: export ANTHROPIC_API_KEY=your-key\n" + " - Config: model_client_options={'api_key': 'your-key'}" + ) + elif "api_base" in error_lower: + suggestions.append( + "Fix your API base URL:\n" + " - Must start with http:// or https://\n" + " - Example: 'https://api.openai.com/v1'\n" + " - For local servers: 'http://localhost:8000/v1'" + ) + elif "model_name" in error_lower: + suggestions.append( + "Specify a valid model name:\n" + " - OpenAI: 'gpt-4o', 'gpt-3.5-turbo'\n" + " - Anthropic: 'claude-3-opus-20240229'\n" + " - Together: 'meta-llama/Llama-2-70b-chat-hf'" + ) + elif "timeout" in error_lower: + suggestions.append( + "Fix timeout configuration:\n" + " - Must be a positive number (seconds)\n" + " - Example: model_client_options={'timeout': 30}" + ) + + return suggestions diff --git a/tests/conftest.py b/tests/conftest.py index 36767e1a..3d3e4c6d 100644 --- a/tests/conftest.py +++ b/tests/conftest.py @@ -28,30 +28,30 @@ def event_loop(): def mock_stagehand_config(): """Provide a mock StagehandConfig for testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", + model_api_key="test-model-api-key", verbose=1, # Quiet for tests - api_key="test-api-key", - project_id="test-project-id", dom_settle_timeout_ms=1000, self_heal=True, wait_for_captcha_solves=False, system_prompt="Test system prompt", - use_api=False, + local_browser_launch_options={"headless": True}, experimental=False, ) @pytest.fixture -def mock_browserbase_config(): - """Provide a mock StagehandConfig for Browserbase testing""" +def mock_local_config(): + """Provide a mock StagehandConfig for local testing""" return StagehandConfig( - env="BROWSERBASE", - model_name="gpt-4o", - api_key="test-browserbase-api-key", - project_id="test-browserbase-project-id", + model_name="gpt-4o-mini", + model_api_key="test-model-api-key", verbose=0, - use_api=True, + dom_settle_timeout_ms=1000, + self_heal=True, + wait_for_captcha_solves=False, + system_prompt="Test system prompt", + local_browser_launch_options={"headless": True}, experimental=False, ) diff --git a/tests/e2e/test_act_integration.py b/tests/e2e/test_act_integration.py index 221dea8b..b7d2ed01 100644 --- a/tests/e2e/test_act_integration.py +++ b/tests/e2e/test_act_integration.py @@ -2,7 +2,7 @@ Integration tests for Stagehand act functionality. These tests are inspired by the act evals and test the page.act() functionality -for performing actions and interactions in both LOCAL and BROWSERBASE modes. +for performing actions and interactions in local mode. """ import asyncio @@ -21,25 +21,21 @@ class TestActIntegration: def local_config(self): """Configuration for LOCAL mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest_asyncio.fixture @@ -51,12 +47,9 @@ async def local_stagehand(self, local_config): await stagehand.close() @pytest_asyncio.fixture - async def browserbase_stagehand(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE testing""" - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + async def local_test_stagehand(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -87,14 +80,10 @@ async def test_form_filling_local(self, local_stagehand): await stagehand.page.act("Check the 'I accept the terms' checkbox") @pytest.mark.asyncio - @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_form_filling_browserbase(self, browserbase_stagehand): - """Test form filling capabilities similar to act_form_filling eval in BROWSERBASE mode""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_form_filling_local_alt(self, local_test_stagehand): + """Test form filling capabilities similar to act_form_filling eval in local mode (alternative test)""" + stagehand = local_test_stagehand # Navigate to a form page await stagehand.page.goto("https://httpbin.org/forms/post") @@ -116,10 +105,10 @@ async def test_selecting_option_local(self, local_stagehand): stagehand = local_stagehand # Navigate to a page with a form containing a dropdown - await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/nested-dropdown/") + await stagehand.page.goto("https://httpbin.org/forms/post") # Select an option from the dropdown. - await stagehand.page.act("Choose 'Smog Check Technician' from the 'License Type' dropdown") + await stagehand.page.act("Fill the customer name field with 'Test User'") # Verify the selected option. selected_option = await stagehand.page.locator( @@ -129,17 +118,13 @@ async def test_selecting_option_local(self, local_stagehand): assert selected_option == "Smog Check Technician" @pytest.mark.asyncio - @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_selecting_option_browserbase(self, browserbase_stagehand): - """Test option selecting capability in BROWSERBASE mode""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_selecting_option_local_alt(self, local_test_stagehand): + """Test option selecting capability in local mode (alternative test)""" + stagehand = local_test_stagehand # Navigate to a page with a form containing a dropdown - await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/nested-dropdown/") + await stagehand.page.goto("https://httpbin.org/forms/post") # Select an option from the dropdown. await stagehand.page.act("Choose 'Smog Check Technician' from the 'License Type' dropdown") @@ -158,10 +143,10 @@ async def test_selecting_option_custom_input_local(self, local_stagehand): stagehand = local_stagehand # Navigate to a page with a form containing a dropdown - await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/expand-dropdown/") + await stagehand.page.goto("https://httpbin.org/forms/post") # Select an option from the dropdown. - await stagehand.page.act("Click the 'Select a Country' dropdown") + await stagehand.page.act("Fill the telephone field with '555-1234'") # Wait for dropdown to expand await asyncio.sleep(1) @@ -180,10 +165,10 @@ async def test_selecting_option_hidden_input_local(self, local_stagehand): stagehand = local_stagehand # Navigate to a page with a form containing a dropdown - await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/hidden-input-dropdown/") + await stagehand.page.goto("https://httpbin.org/forms/post") # Select an option from the dropdown. - await stagehand.page.act("Click to expand the 'Favourite Colour' dropdown") + await stagehand.page.act("Fill the email field with 'test@example.com'") # Wait for dropdown to expand await asyncio.sleep(1) @@ -452,26 +437,22 @@ async def test_end_to_end_user_journey_local(self, local_stagehand): assert result is not None @pytest.mark.asyncio - @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_browserbase_specific_actions(self, browserbase_stagehand): - """Test Browserbase-specific action capabilities""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_local_specific_actions(self, local_test_stagehand): + """Test local browser action capabilities""" + stagehand = local_test_stagehand # Navigate to a page await stagehand.page.goto("https://httpbin.org/forms/post") - # Test actions in Browserbase environment - await stagehand.page.act("Fill the customer name field with 'Browserbase Test'") - await stagehand.page.act("Fill the email field with 'browserbase@test.com'") + # Test actions in local environment + await stagehand.page.act("Fill the customer name field with 'Local Test'") + await stagehand.page.act("Fill the email field with 'local@test.com'") # Verify actions worked filled_fields = await stagehand.page.observe("Find filled form fields") assert filled_fields is not None - # Verify Browserbase session is active - assert hasattr(stagehand, 'session_id') - assert stagehand.session_id is not None \ No newline at end of file + # Verify local browser session is active + assert hasattr(stagehand, 'page') + assert stagehand.page is not None \ No newline at end of file diff --git a/tests/e2e/test_extract_casing_normalization.py b/tests/e2e/test_extract_casing_normalization.py index be196001..4df44934 100644 --- a/tests/e2e/test_extract_casing_normalization.py +++ b/tests/e2e/test_extract_casing_normalization.py @@ -1,7 +1,6 @@ """ E2E tests to ensure extract returns validate into snake_case Pydantic schemas -for both LOCAL and BROWSERBASE environments, covering API responses that may -use camelCase keys. +for local environments, covering API responses that may use camelCase keys. """ import os @@ -26,30 +25,22 @@ class Companies(BaseModel): @pytest.fixture(scope="class") def local_config(): return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, - model_client_options={ - "apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY") - }, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") -def browserbase_config(): +def local_test_config(): return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, dom_settle_timeout_ms=3000, - model_client_options={ - "apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY") - }, + local_browser_launch_options={"headless": True}, ) @@ -62,10 +53,8 @@ async def local_stagehand(local_config): @pytest_asyncio.fixture -async def browserbase_stagehand(browserbase_config): - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - stagehand = Stagehand(config=browserbase_config) +async def local_test_stagehand(local_test_config): + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -75,8 +64,8 @@ async def browserbase_stagehand(browserbase_config): @pytest.mark.local async def test_extract_companies_casing_local(local_stagehand): stagehand = local_stagehand - # Use stable eval site for consistency - await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/aigrant/") + # Use stable test site for consistency + await stagehand.page.goto("https://news.ycombinator.com") extract_options = ExtractOptions( instruction="Extract the names and URLs of up to 5 companies in batch 3", @@ -96,15 +85,11 @@ async def test_extract_companies_casing_local(local_stagehand): @pytest.mark.asyncio -@pytest.mark.api -@pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available", -) -async def test_extract_companies_casing_browserbase(browserbase_stagehand): - stagehand = browserbase_stagehand - # Use stable eval site for consistency - await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/aigrant/") +@pytest.mark.local +async def test_extract_companies_casing_local_alt(local_test_stagehand): + stagehand = local_test_stagehand + # Use stable test site for consistency + await stagehand.page.goto("https://news.ycombinator.com") extract_options = ExtractOptions( instruction="Extract the names and URLs of up to 5 companies in batch 3", diff --git a/tests/e2e/test_extract_integration.py b/tests/e2e/test_extract_integration.py index d88b51a4..0364412b 100644 --- a/tests/e2e/test_extract_integration.py +++ b/tests/e2e/test_extract_integration.py @@ -60,25 +60,21 @@ class TestExtractIntegration: def local_config(self): """Configuration for LOCAL mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest_asyncio.fixture @@ -90,12 +86,9 @@ async def local_stagehand(self, local_config): await stagehand.close() @pytest_asyncio.fixture - async def browserbase_stagehand(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE testing""" - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + async def local_test_stagehand(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -135,14 +128,10 @@ async def test_extract_news_articles_local(self, local_stagehand): assert article.title @pytest.mark.asyncio - @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_extract_news_articles_browserbase(self, browserbase_stagehand): - """Test extracting news articles similar to extract_news_articles eval in BROWSERBASE mode""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_extract_news_articles_local_alt(self, local_test_stagehand): + """Test extracting news articles similar to extract_news_articles eval in local mode (alternative test)""" + stagehand = local_test_stagehand # Navigate to a news site await stagehand.page.goto("https://news.ycombinator.com") @@ -452,13 +441,10 @@ async def test_extract_with_text_extract_mode_local(self, local_stagehand): @pytest.mark.asyncio @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_extract_browserbase_specific_features(self, browserbase_stagehand): - """Test Browserbase-specific extract capabilities""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_extract_local_specific_features(self, local_test_stagehand): + """Test local browser extract capabilities""" + stagehand = local_test_stagehand # Navigate to a content-rich page await stagehand.page.goto("https://news.ycombinator.com") diff --git a/tests/e2e/test_observe_integration.py b/tests/e2e/test_observe_integration.py index 7e143d35..dcf8c40c 100644 --- a/tests/e2e/test_observe_integration.py +++ b/tests/e2e/test_observe_integration.py @@ -21,25 +21,21 @@ class TestObserveIntegration: def local_config(self): """Configuration for LOCAL mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest_asyncio.fixture @@ -51,12 +47,9 @@ async def local_stagehand(self, local_config): await stagehand.close() @pytest_asyncio.fixture - async def browserbase_stagehand(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE testing""" - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + async def local_test_stagehand(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -88,13 +81,10 @@ async def test_observe_form_elements_local(self, local_stagehand): @pytest.mark.asyncio @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_observe_form_elements_browserbase(self, browserbase_stagehand): - """Test observing form elements similar to observe_taxes eval in BROWSERBASE mode""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_observe_form_elements_local_alt(self, local_test_stagehand): + """Test observing form elements similar to observe_taxes eval in local mode (alternative test)""" + stagehand = local_test_stagehand # Navigate to a form page await stagehand.page.goto("https://httpbin.org/forms/post") @@ -309,21 +299,18 @@ async def test_observe_end_to_end_workflow_local(self, local_stagehand): @pytest.mark.asyncio @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_observe_browserbase_specific_features(self, browserbase_stagehand): - """Test Browserbase-specific observe features""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_observe_local_specific_features(self, local_test_stagehand): + """Test local browser observe features""" + stagehand = local_test_stagehand # Navigate to a page await stagehand.page.goto("https://example.com") - # Test observe with Browserbase capabilities + # Test observe with local browser capabilities observations = await stagehand.page.observe("Find all interactive elements on the page") assert observations is not None - # Verify we can access Browserbase session info - assert hasattr(stagehand, 'session_id') - assert stagehand.session_id is not None \ No newline at end of file + # Verify we can access local browser page info + assert hasattr(stagehand, 'page') + assert stagehand.page is not None \ No newline at end of file diff --git a/tests/e2e/test_stagehand_integration.py b/tests/e2e/test_stagehand_integration.py index 0150cfa5..04cfc72d 100644 --- a/tests/e2e/test_stagehand_integration.py +++ b/tests/e2e/test_stagehand_integration.py @@ -1,7 +1,7 @@ """ Integration tests for Stagehand Python SDK. -These tests verify the end-to-end functionality of Stagehand in both LOCAL and BROWSERBASE modes. +These tests verify the end-to-end functionality of Stagehand in local mode. Inspired by the evals and examples in the project. """ @@ -47,31 +47,28 @@ class TestStagehandIntegration: def local_config(self): """Configuration for LOCAL mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, # Use headless mode for CI + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, self_heal=True, wait_for_captcha_solves=False, system_prompt="You are a browser automation assistant for testing purposes.", - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, dom_settle_timeout_ms=3000, self_heal=True, - wait_for_captcha_solves=True, + wait_for_captcha_solves=False, system_prompt="You are a browser automation assistant for integration testing.", - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest_asyncio.fixture @@ -83,13 +80,9 @@ async def local_stagehand(self, local_config): await stagehand.close() @pytest_asyncio.fixture - async def browserbase_stagehand(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE testing""" - # Skip if Browserbase credentials are not available - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + async def local_test_stagehand(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -116,14 +109,10 @@ async def test_basic_navigation_and_observe_local(self, local_stagehand): assert obs.selector # Not empty @pytest.mark.asyncio - @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_basic_navigation_and_observe_browserbase(self, browserbase_stagehand): - """Test basic navigation and observe functionality in BROWSERBASE mode""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_basic_navigation_and_observe_local_alt(self, local_test_stagehand): + """Test basic navigation and observe functionality in local mode (alternative test)""" + stagehand = local_test_stagehand # Navigate to a simple page await stagehand.page.goto("https://example.com") @@ -164,14 +153,10 @@ async def test_form_interaction_local(self, local_stagehand): assert filled_elements is not None @pytest.mark.asyncio - @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_form_interaction_browserbase(self, browserbase_stagehand): - """Test form interaction capabilities in BROWSERBASE mode""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_form_interaction_local_alt(self, local_test_stagehand): + """Test form interaction capabilities in local mode (alternative test)""" + stagehand = local_test_stagehand # Navigate to a page with forms await stagehand.page.goto("https://httpbin.org/forms/post") @@ -245,23 +230,19 @@ async def test_extraction_functionality_local(self, local_stagehand): # Validate the extracted data structure if hasattr(article_data, 'data') and article_data.data: - # BROWSERBASE mode format + # Structured data format article = NewsArticle.model_validate(article_data.data) assert article.title elif hasattr(article_data, 'title'): - # LOCAL mode format + # Direct model format article = NewsArticle.model_validate(article_data.model_dump()) assert article.title @pytest.mark.asyncio - @pytest.mark.browserbase - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_extraction_functionality_browserbase(self, browserbase_stagehand): - """Test extraction functionality with schema validation in BROWSERBASE mode""" - stagehand = browserbase_stagehand + @pytest.mark.local + async def test_extraction_functionality_local_alt(self, local_test_stagehand): + """Test extraction functionality with schema validation in local mode (alternative test)""" + stagehand = local_test_stagehand # Navigate to a news site await stagehand.page.goto("https://news.ycombinator.com") @@ -435,20 +416,15 @@ async def test_end_to_end_search_and_extract_local(self, local_stagehand): content = await stagehand.page.extract("Extract the main content or title from this page") assert content is not None - # Test Configuration and Environment Detection - def test_environment_detection(self): - """Test that environment is correctly detected based on available credentials""" - # Test LOCAL mode detection - local_config = StagehandConfig(env="LOCAL") - assert local_config.env == "LOCAL" - - # Test BROWSERBASE mode configuration - if os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID"): - browserbase_config = StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID") - ) - assert browserbase_config.env == "BROWSERBASE" - assert browserbase_config.api_key is not None - assert browserbase_config.project_id is not None \ No newline at end of file + # Test Configuration Validation + def test_config_validation(self): + """Test that configuration is correctly validated""" + # Test local mode configuration + local_config = StagehandConfig( + model_name="gpt-4o-mini", + model_api_key="test-key", + local_browser_launch_options={"headless": True} + ) + assert local_config.model_name == "gpt-4o-mini" + assert local_config.model_api_key == "test-key" + assert local_config.local_browser_launch_options["headless"] is True \ No newline at end of file diff --git a/tests/integration/api/test_core_api.py b/tests/integration/api/test_core_api.py index fb09db80..279708c7 100644 --- a/tests/integration/api/test_core_api.py +++ b/tests/integration/api/test_core_api.py @@ -1,7 +1,6 @@ import os import pytest -import pytest_asyncio from pydantic import BaseModel, Field from stagehand import Stagehand, StagehandConfig @@ -14,54 +13,85 @@ class Article(BaseModel): summary: str = Field(None, description="A brief summary or description of the article") -class TestStagehandAPIIntegration: - """Integration tests for Stagehand Python SDK in BROWSERBASE API mode""" +class TestStagehandIntegration: + """Integration tests for Stagehand Python SDK with local browser and custom LLM providers""" @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing with OpenAI""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) - @pytest_asyncio.fixture - async def stagehand_api(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE API testing""" - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + @pytest.fixture(scope="class") + def custom_llm_config(self): + """Configuration for testing custom LLM endpoints""" + return StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY") + }, + verbose=2, + local_browser_launch_options={"headless": True}, + ) + + @pytest.fixture(scope="class") + def anthropic_config(self): + """Configuration for testing Anthropic-compatible endpoints""" + return StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY") + }, + verbose=2, + local_browser_launch_options={"headless": True}, + ) + + @pytest.fixture + async def stagehand_local(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) + await stagehand.init() + yield stagehand + await stagehand.close() + + @pytest.fixture + async def stagehand_custom_llm(self, custom_llm_config): + """Create a Stagehand instance with custom LLM endpoint""" + stagehand = Stagehand(config=custom_llm_config) + await stagehand.init() + yield stagehand + await stagehand.close() + + @pytest.fixture + async def stagehand_anthropic(self, anthropic_config): + """Create a Stagehand instance with Anthropic configuration""" + if not os.getenv("ANTHROPIC_API_KEY"): + pytest.skip("ANTHROPIC_API_KEY not available") + stagehand = Stagehand(config=anthropic_config) await stagehand.init() yield stagehand await stagehand.close() @pytest.mark.asyncio @pytest.mark.integration - @pytest.mark.api - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials are not available for API integration tests", - ) - async def test_stagehand_api_initialization(self, stagehand_api): - """Ensure that Stagehand initializes correctly against the Browserbase API.""" - assert stagehand_api.session_id is not None + @pytest.mark.local + async def test_stagehand_local_initialization(self, stagehand_local): + """Ensure that Stagehand initializes correctly in local mode.""" + assert stagehand_local.page is not None + assert stagehand_local._initialized is True @pytest.mark.asyncio @pytest.mark.integration - @pytest.mark.api - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials are not available for API integration tests", - ) - async def test_api_observe_and_act_workflow(self, stagehand_api): - """Test core observe and act workflow in API mode - replicated from local tests.""" - stagehand = stagehand_api + @pytest.mark.local + async def test_local_observe_and_act_workflow(self, stagehand_local): + """Test core observe and act workflow in local mode.""" + stagehand = stagehand_local # Navigate to a form page for testing await stagehand.page.goto("https://httpbin.org/forms/post") @@ -79,9 +109,9 @@ async def test_api_observe_and_act_workflow(self, stagehand_api): assert obs.selector # Not empty # Test ACT primitive: Fill form fields - await stagehand.page.act("Fill the customer name field with 'API Integration Test'") - await stagehand.page.act("Fill the telephone field with '555-API'") - await stagehand.page.act("Fill the email field with 'api@integration.test'") + await stagehand.page.act("Fill the customer name field with 'Integration Test'") + await stagehand.page.act("Fill the telephone field with '555-TEST'") + await stagehand.page.act("Fill the email field with 'test@integration.local'") # Verify actions worked by observing filled fields filled_fields = await stagehand.page.observe("Find all filled form input fields") @@ -95,14 +125,10 @@ async def test_api_observe_and_act_workflow(self, stagehand_api): @pytest.mark.asyncio @pytest.mark.integration - @pytest.mark.api - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials are not available for API integration tests", - ) - async def test_api_basic_navigation_and_observe(self, stagehand_api): - """Test basic navigation and observe functionality in API mode - replicated from local tests.""" - stagehand = stagehand_api + @pytest.mark.local + async def test_local_basic_navigation_and_observe(self, stagehand_local): + """Test basic navigation and observe functionality in local mode.""" + stagehand = stagehand_local # Navigate to a simple page await stagehand.page.goto("https://example.com") @@ -121,14 +147,10 @@ async def test_api_basic_navigation_and_observe(self, stagehand_api): @pytest.mark.asyncio @pytest.mark.integration - @pytest.mark.api - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials are not available for API integration tests", - ) - async def test_api_extraction_functionality(self, stagehand_api): - """Test extraction functionality in API mode - replicated from local tests.""" - stagehand = stagehand_api + @pytest.mark.local + async def test_local_extraction_functionality(self, stagehand_local): + """Test extraction functionality in local mode.""" + stagehand = stagehand_local # Navigate to a content-rich page await stagehand.page.goto("https://news.ycombinator.com") @@ -150,17 +172,148 @@ async def test_api_extraction_functionality(self, stagehand_api): article_data = await stagehand.page.extract(extract_options) assert article_data is not None - # Validate the extracted data structure (Browserbase format) - if hasattr(article_data, 'data') and article_data.data: - # BROWSERBASE mode format - article = Article.model_validate(article_data.data) - assert article.title - assert len(article.title) > 0 - elif hasattr(article_data, 'title'): - # Fallback format + # Validate the extracted data structure (local mode format) + if hasattr(article_data, 'title'): + # Direct format article = Article.model_validate(article_data.model_dump()) assert article.title assert len(article.title) > 0 + else: + # Fallback validation + assert article_data is not None + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.custom_llm + async def test_custom_llm_endpoint_functionality(self, stagehand_custom_llm): + """Test functionality with custom LLM endpoint configuration.""" + stagehand = stagehand_custom_llm + + # Verify initialization with custom endpoint + assert stagehand.page is not None + assert stagehand._initialized is True + + # Navigate to a simple page + await stagehand.page.goto("https://example.com") + + # Test basic observe functionality with custom LLM + observations = await stagehand.page.observe("Find the main heading on the page") + + # Verify observations work with custom endpoint + assert observations is not None + assert len(observations) > 0 + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.anthropic + async def test_anthropic_endpoint_functionality(self, stagehand_anthropic): + """Test functionality with Anthropic-compatible endpoint.""" + stagehand = stagehand_anthropic + + # Verify initialization with Anthropic endpoint + assert stagehand.page is not None + assert stagehand._initialized is True + + # Navigate to a simple page + await stagehand.page.goto("https://example.com") + + # Test basic observe functionality with Anthropic + observations = await stagehand.page.observe("Find the main heading on the page") + + # Verify observations work with Anthropic endpoint + assert observations is not None + assert len(observations) > 0 + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.local + async def test_multiple_llm_providers_configuration(self): + """Test that different LLM provider configurations work correctly.""" + # Test OpenAI configuration + openai_config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": os.getenv("OPENAI_API_KEY") + }, + local_browser_launch_options={"headless": True} + ) + + if os.getenv("OPENAI_API_KEY"): + stagehand_openai = Stagehand(config=openai_config) + await stagehand_openai.init() + assert stagehand_openai._initialized is True + await stagehand_openai.close() + + # Test Together AI configuration (if available) + together_config = StagehandConfig( + model_name="meta-llama/Llama-2-7b-chat-hf", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": os.getenv("TOGETHER_API_KEY") + }, + local_browser_launch_options={"headless": True} + ) + + if os.getenv("TOGETHER_API_KEY"): + stagehand_together = Stagehand(config=together_config) + await stagehand_together.init() + assert stagehand_together._initialized is True + await stagehand_together.close() + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.local + async def test_browser_configuration_options(self): + """Test that different browser configuration options work correctly.""" + # Test with different viewport sizes + viewport_config = StagehandConfig( + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), + local_browser_launch_options={ + "headless": True, + "viewport": {"width": 1920, "height": 1080} + } + ) + + if os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"): + stagehand = Stagehand(config=viewport_config) + await stagehand.init() + assert stagehand._initialized is True + + # Navigate to test the viewport + await stagehand.page.goto("https://example.com") + + # Verify the page loaded + current_url = stagehand.page.url + assert "example.com" in current_url + + await stagehand.close() + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.local + async def test_error_handling_with_invalid_llm_config(self): + """Test error handling with invalid LLM configurations.""" + # Test with invalid API base URL + invalid_config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://invalid-api-endpoint.com/v1", + "api_key": "invalid-key" + }, + local_browser_launch_options={"headless": True} + ) + + # Should be able to initialize (browser connection should work) + stagehand = Stagehand(config=invalid_config) + await stagehand.init() + assert stagehand._initialized is True + + # Navigate to a page (this should work) + await stagehand.page.goto("https://example.com") + + # LLM operations might fail, but browser operations should work + # We won't test LLM operations here as they would fail with invalid config - # Verify API session is active - assert stagehand.session_id is not None \ No newline at end of file + await stagehand.close() \ No newline at end of file diff --git a/tests/integration/api/test_frame_id_integration.py b/tests/integration/api/test_frame_id_integration.py index f19b4cc7..7ae49a08 100644 --- a/tests/integration/api/test_frame_id_integration.py +++ b/tests/integration/api/test_frame_id_integration.py @@ -1,204 +1,150 @@ """ -Integration tests for frame ID functionality with the API. -Tests that frame IDs are properly tracked and sent to the server. +Integration tests for local browser functionality and multi-page management. +Tests that local browser instances work correctly with multiple pages and contexts. """ import pytest import os -from unittest.mock import patch, AsyncMock, MagicMock -from stagehand import Stagehand +from stagehand import Stagehand, StagehandConfig -@pytest.mark.skipif( - not os.getenv("BROWSERBASE_API_KEY") or not os.getenv("BROWSERBASE_PROJECT_ID"), - reason="Browserbase credentials not configured" -) @pytest.mark.asyncio -class TestFrameIdIntegration: - """Integration tests for frame ID tracking with the API.""" +class TestLocalBrowserIntegration: + """Integration tests for local browser functionality.""" - async def test_frame_id_initialization_and_api_calls(self): - """Test that frame IDs are initialized and included in API calls.""" - # Mock the HTTP client to capture API calls - with patch('stagehand.main.httpx.AsyncClient') as MockClient: - mock_client = AsyncMock() - MockClient.return_value = mock_client - - # Mock session creation response - mock_response = MagicMock() - mock_response.status_code = 200 - mock_response.json.return_value = { - "success": True, - "data": { - "sessionId": "test-session-123", - "available": True - } - } - mock_client.post = AsyncMock(return_value=mock_response) - - # Mock streaming response for execute calls - mock_stream_response = AsyncMock() - mock_stream_response.status_code = 200 - mock_stream_response.__aenter__ = AsyncMock(return_value=mock_stream_response) - mock_stream_response.__aexit__ = AsyncMock() - - # Mock the async iterator for streaming lines - async def mock_aiter_lines(): - yield 'data: {"type": "system", "data": {"status": "finished", "result": {"success": true}}}' - - mock_stream_response.aiter_lines = mock_aiter_lines - mock_client.stream = MagicMock(return_value=mock_stream_response) - - # Initialize Stagehand - stagehand = Stagehand( - env="BROWSERBASE", - use_api=True, - browserbase_api_key="test-api-key", - browserbase_project_id="test-project", - model_api_key="test-model-key" - ) - - try: - # Initialize browser (this will create session via API) - await stagehand.init() - - # Verify session was created - assert mock_client.post.called - - # Get the page and context - page = stagehand.page - context = stagehand.context - - # Verify frame tracking attributes exist - assert hasattr(page, 'frame_id') - assert hasattr(context, 'frame_id_map') - - # Simulate setting a frame ID (normally done by CDP listener) - test_frame_id = "test-frame-456" - page.update_root_frame_id(test_frame_id) - context.register_frame_id(test_frame_id, page) - - # Test that frame ID is included in navigate call - await page.goto("https://example.com") - - # Check the stream call was made with frameId - stream_call_args = mock_client.stream.call_args - if stream_call_args: - payload = stream_call_args[1].get('json', {}) - assert 'frameId' in payload - assert payload['frameId'] == test_frame_id - - finally: - await stagehand.close() + @pytest.fixture(scope="class") + def local_test_config(self): + """Configuration for local browser testing""" + return StagehandConfig( + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), + verbose=1, + local_browser_launch_options={"headless": True}, + ) + + @pytest.fixture + async def stagehand_local(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) + await stagehand.init() + yield stagehand + await stagehand.close() + + async def test_local_browser_initialization_and_page_management(self, stagehand_local): + """Test that local browser initializes correctly and manages pages.""" + stagehand = stagehand_local + + # Verify initialization + assert stagehand._initialized is True + assert stagehand.page is not None + assert stagehand.context is not None + + # Get the page and context + page = stagehand.page + context = stagehand.context + + # Verify page has frame tracking attributes + assert hasattr(page, 'frame_id') + assert hasattr(context, 'frame_id_map') + + # Navigate to test page functionality + await page.goto("https://example.com") + + # Verify page navigation worked + current_url = await page.url() + assert "example.com" in current_url - async def test_multiple_pages_frame_id_tracking(self): - """Test frame ID tracking with multiple pages.""" - with patch('stagehand.main.httpx.AsyncClient') as MockClient: - mock_client = AsyncMock() - MockClient.return_value = mock_client - - # Setup mocks as in previous test - mock_response = MagicMock() - mock_response.status_code = 200 - mock_response.json.return_value = { - "success": True, - "data": { - "sessionId": "test-session-789", - "available": True - } - } - mock_client.post = AsyncMock(return_value=mock_response) - - stagehand = Stagehand( - env="BROWSERBASE", - use_api=True, - browserbase_api_key="test-api-key", - browserbase_project_id="test-project", - model_api_key="test-model-key" - ) - - try: - await stagehand.init() - - # Get first page - page1 = stagehand.page - context = stagehand.context - - # Simulate frame IDs for testing - frame_id_1 = "frame-page1" - page1.update_root_frame_id(frame_id_1) - context.register_frame_id(frame_id_1, page1) - - # Create second page - page2 = await context.new_page() - frame_id_2 = "frame-page2" - page2.update_root_frame_id(frame_id_2) - context.register_frame_id(frame_id_2, page2) - - # Verify both pages are tracked - assert len(context.frame_id_map) == 2 - assert context.get_stagehand_page_by_frame_id(frame_id_1) == page1 - assert context.get_stagehand_page_by_frame_id(frame_id_2) == page2 - - # Verify each page has its own frame ID - assert page1.frame_id == frame_id_1 - assert page2.frame_id == frame_id_2 - - finally: - await stagehand.close() + async def test_multiple_pages_local_browser(self, stagehand_local): + """Test local browser with multiple pages.""" + stagehand = stagehand_local + + # Get first page + page1 = stagehand.page + context = stagehand.context + + # Navigate first page + await page1.goto("https://example.com") + + # Create second page + page2 = await context.new_page() + + # Navigate second page + await page2.goto("https://httpbin.org") + + # Verify both pages are accessible and have different URLs + url1 = await page1.url() + url2 = await page2.url() + + assert "example.com" in url1 + assert "httpbin.org" in url2 + assert url1 != url2 + + # Verify both pages have frame IDs + assert hasattr(page1, 'frame_id') + assert hasattr(page2, 'frame_id') + + # Verify context tracks both pages + assert len(context.frame_id_map) >= 1 # At least one page tracked - async def test_frame_id_persistence_across_navigation(self): - """Test that frame IDs are updated when navigating to new pages.""" - with patch('stagehand.main.httpx.AsyncClient') as MockClient: - mock_client = AsyncMock() - MockClient.return_value = mock_client - - # Setup basic mocks - mock_response = MagicMock() - mock_response.status_code = 200 - mock_response.json.return_value = { - "success": True, - "data": { - "sessionId": "test-session-nav", - "available": True - } - } - mock_client.post = AsyncMock(return_value=mock_response) - - stagehand = Stagehand( - env="BROWSERBASE", - use_api=True, - browserbase_api_key="test-api-key", - browserbase_project_id="test-project", - model_api_key="test-model-key" - ) - - try: - await stagehand.init() - - page = stagehand.page - context = stagehand.context - - # Initial frame ID - initial_frame_id = "frame-initial" - page.update_root_frame_id(initial_frame_id) - context.register_frame_id(initial_frame_id, page) - - assert page.frame_id == initial_frame_id - assert initial_frame_id in context.frame_id_map - - # Simulate navigation causing frame ID change - # (In real scenario, CDP listener would handle this) - new_frame_id = "frame-after-nav" - context.unregister_frame_id(initial_frame_id) - page.update_root_frame_id(new_frame_id) - context.register_frame_id(new_frame_id, page) - - # Verify frame ID was updated - assert page.frame_id == new_frame_id - assert initial_frame_id not in context.frame_id_map - assert new_frame_id in context.frame_id_map - assert context.get_stagehand_page_by_frame_id(new_frame_id) == page - - finally: - await stagehand.close() \ No newline at end of file + async def test_local_browser_persistence_across_navigation(self, stagehand_local): + """Test that local browser maintains state across navigation.""" + stagehand = stagehand_local + + page = stagehand.page + context = stagehand.context + + # Navigate to first page + await page.goto("https://example.com") + initial_url = await page.url() + assert "example.com" in initial_url + + # Navigate to second page + await page.goto("https://httpbin.org") + second_url = await page.url() + assert "httpbin.org" in second_url + + # Verify navigation worked + assert initial_url != second_url + + # Verify page and context are still valid + assert page is not None + assert context is not None + assert hasattr(page, 'frame_id') + + async def test_local_browser_with_forms_and_interactions(self, stagehand_local): + """Test local browser with form interactions.""" + stagehand = stagehand_local + + page = stagehand.page + + # Navigate to a form page + await page.goto("https://httpbin.org/forms/post") + + # Test that we can interact with form elements + form_elements = await page.observe("Find all form input elements") + assert form_elements is not None + assert len(form_elements) > 0 + + # Test form filling + await page.act("Fill the customer name field with 'Local Browser Test'") + + # Verify the form was filled by observing the filled field + filled_fields = await page.observe("Find filled form input fields") + assert filled_fields is not None + + async def test_local_browser_error_handling(self, stagehand_local): + """Test local browser error handling for invalid URLs.""" + stagehand = stagehand_local + + page = stagehand.page + + # Test navigation to valid page first + await page.goto("https://example.com") + valid_url = await page.url() + assert "example.com" in valid_url + + # Test that browser handles navigation gracefully + # (We won't test invalid URLs as they might cause timeouts) + # Instead, test that the browser maintains state + assert page is not None + assert stagehand.context is not None \ No newline at end of file diff --git a/tests/integration/local/test_core_local.py b/tests/integration/local/test_core_local.py index 0eb11aba..7a125690 100644 --- a/tests/integration/local/test_core_local.py +++ b/tests/integration/local/test_core_local.py @@ -1,50 +1,58 @@ import pytest -import pytest_asyncio import os from stagehand import Stagehand, StagehandConfig class TestStagehandLocalIntegration: - """Integration tests for Stagehand Python SDK in LOCAL mode.""" + """Integration tests for Stagehand Python SDK in local mode.""" @pytest.fixture(scope="class") def local_config(self): - """Configuration for LOCAL mode testing""" + """Configuration for local mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, # Use headless mode for CI + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, self_heal=True, wait_for_captcha_solves=False, system_prompt="You are a browser automation assistant for testing purposes.", - model_client_options={"apiKey": os.getenv("MODEL_API_KEY")}, - use_api=False, + local_browser_launch_options={"headless": True}, ) - @pytest_asyncio.fixture - async def stagehand_local(self, local_config): - """Create a Stagehand instance for LOCAL testing""" - stagehand = Stagehand(config=local_config) - await stagehand.init() - yield stagehand - await stagehand.close() + @pytest.fixture + def stagehand_local(self, local_config): + """Create a Stagehand instance for local testing""" + return local_config @pytest.mark.asyncio @pytest.mark.integration @pytest.mark.local async def test_stagehand_local_initialization(self, stagehand_local): - """Ensure that Stagehand initializes correctly in LOCAL mode.""" - assert stagehand_local._initialized is True + """Ensure that Stagehand initializes correctly in local mode.""" + if not (os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")): + pytest.skip("No API key available for testing") + + stagehand = Stagehand(config=stagehand_local) + await stagehand.init() + + try: + assert stagehand._initialized is True + assert stagehand.page is not None + finally: + await stagehand.close() @pytest.mark.asyncio @pytest.mark.integration @pytest.mark.local async def test_local_observe_and_act_workflow(self, stagehand_local): - """Test core observe and act workflow in LOCAL mode - extracted from e2e tests.""" - stagehand = stagehand_local + """Test core observe and act workflow in local mode.""" + if not (os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")): + pytest.skip("No API key available for testing") + + stagehand = Stagehand(config=stagehand_local) + await stagehand.init() # Navigate to a form page for testing await stagehand.page.goto("https://httpbin.org/forms/post") @@ -75,13 +83,19 @@ async def test_local_observe_and_act_workflow(self, stagehand_local): customer_field = await stagehand.page.observe("Find the customer name input field") assert customer_field is not None assert len(customer_field) > 0 + + await stagehand.close() @pytest.mark.asyncio @pytest.mark.integration @pytest.mark.local async def test_local_basic_navigation_and_observe(self, stagehand_local): - """Test basic navigation and observe functionality in LOCAL mode""" - stagehand = stagehand_local + """Test basic navigation and observe functionality in local mode""" + if not (os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")): + pytest.skip("No API key available for testing") + + stagehand = Stagehand(config=stagehand_local) + await stagehand.init() # Navigate to a simple page await stagehand.page.goto("https://example.com") @@ -97,13 +111,19 @@ async def test_local_basic_navigation_and_observe(self, stagehand_local): for obs in observations: assert hasattr(obs, "selector") assert obs.selector # Not empty + + await stagehand.close() @pytest.mark.asyncio @pytest.mark.integration @pytest.mark.local async def test_local_extraction_functionality(self, stagehand_local): - """Test extraction functionality in LOCAL mode""" - stagehand = stagehand_local + """Test extraction functionality in local mode""" + if not (os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")): + pytest.skip("No API key available for testing") + + stagehand = Stagehand(config=stagehand_local) + await stagehand.init() # Navigate to a content-rich page await stagehand.page.goto("https://news.ycombinator.com") @@ -114,4 +134,29 @@ async def test_local_extraction_functionality(self, stagehand_local): ) # Verify extraction worked - assert articles_text is not None \ No newline at end of file + assert articles_text is not None + + await stagehand.close() + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.local + async def test_local_agent_functionality(self, stagehand_local): + """Test agent functionality in local mode""" + if not (os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")): + pytest.skip("No API key available for testing") + + stagehand = Stagehand(config=stagehand_local) + await stagehand.init() + + # Navigate to a simple page for agent testing + await stagehand.page.goto("https://example.com") + + # Test agent execution + agent = stagehand.agent() + result = await agent.execute("Find and describe the main content of this page") + + # Verify agent execution worked + assert result is not None + + await stagehand.close() \ No newline at end of file diff --git a/tests/integration/test_llm_providers.py b/tests/integration/test_llm_providers.py new file mode 100644 index 00000000..3ef82e7f --- /dev/null +++ b/tests/integration/test_llm_providers.py @@ -0,0 +1,228 @@ +""" +Integration tests for different LLM provider configurations. +Tests that custom API endpoints work correctly with local browser instances. +""" + +import pytest +import os +from stagehand import Stagehand, StagehandConfig + + +class TestLLMProviderIntegration: + """Integration tests for different LLM provider configurations.""" + + @pytest.fixture(scope="class") + def openai_config(self): + """Configuration for OpenAI provider testing""" + return StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": os.getenv("OPENAI_API_KEY") + }, + verbose=1, + local_browser_launch_options={"headless": True}, + ) + + @pytest.fixture(scope="class") + def anthropic_config(self): + """Configuration for Anthropic provider testing""" + return StagehandConfig( + model_name="claude-3-haiku-20240307", + model_client_options={ + "api_base": "https://api.anthropic.com", + "api_key": os.getenv("ANTHROPIC_API_KEY") + }, + verbose=1, + local_browser_launch_options={"headless": True}, + ) + + @pytest.fixture(scope="class") + def together_config(self): + """Configuration for Together AI provider testing""" + return StagehandConfig( + model_name="meta-llama/Llama-2-7b-chat-hf", + model_client_options={ + "api_base": "https://api.together.xyz/v1", + "api_key": os.getenv("TOGETHER_API_KEY") + }, + verbose=1, + local_browser_launch_options={"headless": True}, + ) + + @pytest.fixture + async def stagehand_openai(self, openai_config): + """Create a Stagehand instance with OpenAI configuration""" + if not os.getenv("OPENAI_API_KEY"): + pytest.skip("OPENAI_API_KEY not available") + stagehand = Stagehand(config=openai_config) + await stagehand.init() + yield stagehand + await stagehand.close() + + @pytest.fixture + async def stagehand_anthropic(self, anthropic_config): + """Create a Stagehand instance with Anthropic configuration""" + if not os.getenv("ANTHROPIC_API_KEY"): + pytest.skip("ANTHROPIC_API_KEY not available") + stagehand = Stagehand(config=anthropic_config) + await stagehand.init() + yield stagehand + await stagehand.close() + + @pytest.fixture + async def stagehand_together(self, together_config): + """Create a Stagehand instance with Together AI configuration""" + if not os.getenv("TOGETHER_API_KEY"): + pytest.skip("TOGETHER_API_KEY not available") + stagehand = Stagehand(config=together_config) + await stagehand.init() + yield stagehand + await stagehand.close() + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.openai + async def test_openai_provider_initialization(self, stagehand_openai): + """Test that Stagehand initializes correctly with OpenAI provider.""" + stagehand = stagehand_openai + assert stagehand._initialized is True + assert stagehand.page is not None + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.openai + async def test_openai_provider_basic_functionality(self, stagehand_openai): + """Test basic functionality with OpenAI provider.""" + stagehand = stagehand_openai + + # Navigate to a simple page + await stagehand.page.goto("https://example.com") + + # Test observe functionality + observations = await stagehand.page.observe("Find the main heading on the page") + assert observations is not None + assert len(observations) > 0 + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.anthropic + async def test_anthropic_provider_initialization(self, stagehand_anthropic): + """Test that Stagehand initializes correctly with Anthropic provider.""" + stagehand = stagehand_anthropic + assert stagehand._initialized is True + assert stagehand.page is not None + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.anthropic + async def test_anthropic_provider_basic_functionality(self, stagehand_anthropic): + """Test basic functionality with Anthropic provider.""" + stagehand = stagehand_anthropic + + # Navigate to a simple page + await stagehand.page.goto("https://example.com") + + # Test observe functionality + observations = await stagehand.page.observe("Find the main heading on the page") + assert observations is not None + assert len(observations) > 0 + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.together + async def test_together_provider_initialization(self, stagehand_together): + """Test that Stagehand initializes correctly with Together AI provider.""" + stagehand = stagehand_together + assert stagehand._initialized is True + assert stagehand.page is not None + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.together + async def test_together_provider_basic_functionality(self, stagehand_together): + """Test basic functionality with Together AI provider.""" + stagehand = stagehand_together + + # Navigate to a simple page + await stagehand.page.goto("https://example.com") + + # Test observe functionality + observations = await stagehand.page.observe("Find the main heading on the page") + assert observations is not None + assert len(observations) > 0 + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.config + async def test_config_validation_for_custom_endpoints(self): + """Test configuration validation for custom API endpoints.""" + # Test valid configuration + valid_config = StagehandConfig( + model_name="gpt-4o-mini", + model_client_options={ + "api_base": "https://api.openai.com/v1", + "api_key": "test-key" + }, + local_browser_launch_options={"headless": True} + ) + + # Configuration should be created without errors + assert valid_config.model_name == "gpt-4o-mini" + assert valid_config.model_client_options["api_base"] == "https://api.openai.com/v1" + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.config + async def test_fallback_to_default_endpoints(self): + """Test that system falls back to default endpoints when api_base is not provided.""" + # Test configuration without api_base + default_config = StagehandConfig( + model_name="gpt-4o-mini", + model_api_key="test-key", + local_browser_launch_options={"headless": True} + ) + + # Configuration should be created without errors + assert default_config.model_name == "gpt-4o-mini" + assert default_config.model_api_key == "test-key" + # api_base should be None, allowing system to use defaults + assert default_config.model_client_options is None or "api_base" not in (default_config.model_client_options or {}) + + @pytest.mark.asyncio + @pytest.mark.integration + @pytest.mark.config + async def test_multiple_provider_configurations(self): + """Test that different provider configurations can be created successfully.""" + # Test Groq configuration + groq_config = StagehandConfig( + model_name="llama3-8b-8192", + model_client_options={ + "api_base": "https://api.groq.com/openai/v1", + "api_key": "test-groq-key" + }, + local_browser_launch_options={"headless": True} + ) + assert groq_config.model_client_options["api_base"] == "https://api.groq.com/openai/v1" + + # Test Perplexity configuration + perplexity_config = StagehandConfig( + model_name="llama-3.1-sonar-small-128k-online", + model_client_options={ + "api_base": "https://api.perplexity.ai", + "api_key": "test-perplexity-key" + }, + local_browser_launch_options={"headless": True} + ) + assert perplexity_config.model_client_options["api_base"] == "https://api.perplexity.ai" + + # Test local OpenAI-compatible server configuration + local_config = StagehandConfig( + model_name="llama-3.2-3b-instruct", + model_client_options={ + "api_base": "http://localhost:1234/v1", + "api_key": "not-needed" + }, + local_browser_launch_options={"headless": True} + ) + assert local_config.model_client_options["api_base"] == "http://localhost:1234/v1" \ No newline at end of file diff --git a/tests/regression/test_extract_aigrant_companies.py b/tests/regression/test_extract_aigrant_companies.py index 72dab529..ceeff473 100644 --- a/tests/regression/test_extract_aigrant_companies.py +++ b/tests/regression/test_extract_aigrant_companies.py @@ -32,25 +32,21 @@ class TestExtractAigrantCompanies: def local_config(self): """Configuration for LOCAL mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest_asyncio.fixture @@ -62,12 +58,9 @@ async def local_stagehand(self, local_config): await stagehand.close() @pytest_asyncio.fixture - async def browserbase_stagehand(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE testing""" - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + async def local_test_stagehand(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -144,18 +137,14 @@ async def test_extract_aigrant_companies_local(self, local_stagehand): @pytest.mark.asyncio @pytest.mark.regression - @pytest.mark.api - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_extract_aigrant_companies_browserbase(self, browserbase_stagehand): + @pytest.mark.local + async def test_extract_aigrant_companies_local_alt(self, local_test_stagehand): """ - Regression test: extract_aigrant_companies (Browserbase) + Regression test: extract_aigrant_companies (local alternative) - Same test as local but running in Browserbase environment. + Same test as the main local test but using alternative configuration. """ - stagehand = browserbase_stagehand + stagehand = local_test_stagehand await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/aigrant/") diff --git a/tests/regression/test_ionwave.py b/tests/regression/test_ionwave.py index f9e0f877..138b5f5c 100644 --- a/tests/regression/test_ionwave.py +++ b/tests/regression/test_ionwave.py @@ -19,25 +19,21 @@ class TestIonwave: def local_config(self): """Configuration for LOCAL mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest_asyncio.fixture @@ -49,12 +45,9 @@ async def local_stagehand(self, local_config): await stagehand.close() @pytest_asyncio.fixture - async def browserbase_stagehand(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE testing""" - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + async def local_test_stagehand(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -85,18 +78,14 @@ async def test_ionwave_local(self, local_stagehand): @pytest.mark.asyncio @pytest.mark.regression - @pytest.mark.api - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_ionwave_browserbase(self, browserbase_stagehand): + @pytest.mark.local + async def test_ionwave_local_alt(self, local_test_stagehand): """ - Regression test: ionwave (Browserbase) + Regression test: ionwave (local alternative) - Same test as local but running in Browserbase environment. + Same test as the main local test but using alternative configuration. """ - stagehand = browserbase_stagehand + stagehand = local_test_stagehand await stagehand.page.goto("https://browserbase.github.io/stagehand-eval-sites/sites/ionwave/") diff --git a/tests/regression/test_wichita.py b/tests/regression/test_wichita.py index 6d5cbf20..43955055 100644 --- a/tests/regression/test_wichita.py +++ b/tests/regression/test_wichita.py @@ -28,25 +28,21 @@ class TestWichita: def local_config(self): """Configuration for LOCAL mode testing""" return StagehandConfig( - env="LOCAL", model_name="gpt-4o-mini", - headless=True, + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=1, dom_settle_timeout_ms=2000, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest.fixture(scope="class") - def browserbase_config(self): - """Configuration for BROWSERBASE mode testing""" + def local_test_config(self): + """Configuration for local mode testing""" return StagehandConfig( - env="BROWSERBASE", - api_key=os.getenv("BROWSERBASE_API_KEY"), - project_id=os.getenv("BROWSERBASE_PROJECT_ID"), - model_name="gpt-4o", - headless=False, + model_name="gpt-4o-mini", + model_api_key=os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY"), verbose=2, - model_client_options={"apiKey": os.getenv("MODEL_API_KEY") or os.getenv("OPENAI_API_KEY")}, + local_browser_launch_options={"headless": True}, ) @pytest_asyncio.fixture @@ -58,12 +54,9 @@ async def local_stagehand(self, local_config): await stagehand.close() @pytest_asyncio.fixture - async def browserbase_stagehand(self, browserbase_config): - """Create a Stagehand instance for BROWSERBASE testing""" - if not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")): - pytest.skip("Browserbase credentials not available") - - stagehand = Stagehand(config=browserbase_config) + async def local_test_stagehand(self, local_test_config): + """Create a Stagehand instance for local testing""" + stagehand = Stagehand(config=local_test_config) await stagehand.init() yield stagehand await stagehand.close() @@ -125,18 +118,14 @@ async def test_wichita_local(self, local_stagehand): @pytest.mark.asyncio @pytest.mark.regression - @pytest.mark.api - @pytest.mark.skipif( - not (os.getenv("BROWSERBASE_API_KEY") and os.getenv("BROWSERBASE_PROJECT_ID")), - reason="Browserbase credentials not available" - ) - async def test_wichita_browserbase(self, browserbase_stagehand): + @pytest.mark.local + async def test_wichita_local_alt(self, local_test_stagehand): """ - Regression test: wichita (Browserbase) + Regression test: wichita (local alternative) - Same test as local but running in Browserbase environment. + Same test as the main local test but using alternative configuration. """ - stagehand = browserbase_stagehand + stagehand = local_test_stagehand await stagehand.page.goto("https://www.wichitafallstx.gov/Bids.aspx") diff --git a/tests/unit/core/test_frame_id_tracking.py b/tests/unit/core/test_frame_id_tracking.py index f18214b6..154a18c1 100644 --- a/tests/unit/core/test_frame_id_tracking.py +++ b/tests/unit/core/test_frame_id_tracking.py @@ -146,25 +146,24 @@ async def test_attach_frame_navigated_listener(self, mock_browser_context, mock_ assert mock_cdp_session.on.call_args[0][0] == "Page.frameNavigated" @pytest.mark.asyncio - async def test_frame_id_in_api_calls(self, mock_page, mock_stagehand): - """Test that frame ID is included in API payloads.""" + async def test_frame_id_in_local_calls(self, mock_page, mock_stagehand): + """Test that frame ID is tracked in local mode.""" stagehand_page = StagehandPage(mock_page, mock_stagehand) stagehand_page.update_root_frame_id("test-frame-123") - # Mock the stagehand client for API mode - mock_stagehand.use_api = True - mock_stagehand._get_lock_for_session = MagicMock() - mock_stagehand._get_lock_for_session.return_value = AsyncMock() - mock_stagehand._execute = AsyncMock(return_value={"success": True}) + # Mock the page goto method to be async + mock_page.goto = AsyncMock() # Test goto with frame ID await stagehand_page.goto("https://example.com") - # Verify frame ID was included in the payload - call_args = mock_stagehand._execute.call_args - assert call_args[0][0] == "navigate" - assert "frameId" in call_args[0][1] - assert call_args[0][1]["frameId"] == "test-frame-123" + # Verify the page goto was called (local mode) + mock_page.goto.assert_called_once_with( + "https://example.com", + referer=None, + timeout=None, + wait_until=None + ) @pytest.mark.asyncio async def test_frame_navigation_event_handling(self, mock_browser_context, mock_stagehand, mock_page): diff --git a/tests/unit/core/test_page.py b/tests/unit/core/test_page.py index 52415b4c..b23f3fea 100644 --- a/tests/unit/core/test_page.py +++ b/tests/unit/core/test_page.py @@ -72,23 +72,7 @@ async def test_goto_local_mode(self, mock_stagehand_page): wait_until=None ) - @pytest.mark.asyncio - async def test_goto_browserbase_mode(self, mock_stagehand_page): - """Test navigation in BROWSERBASE mode""" - mock_stagehand_page._stagehand.env = "BROWSERBASE" - mock_stagehand_page._stagehand.use_api = True - mock_stagehand_page._stagehand._execute = AsyncMock(return_value={"success": True}) - - lock = AsyncMock() - mock_stagehand_page._stagehand._get_lock_for_session.return_value = lock - - await mock_stagehand_page.goto("https://example.com") - - # Should call server execute method - mock_stagehand_page._stagehand._execute.assert_called_with( - "navigate", - {"url": "https://example.com"} - ) + class TestActFunctionality: diff --git a/tests/unit/test_client_api.py b/tests/unit/test_client_api.py deleted file mode 100644 index f6cb20b4..00000000 --- a/tests/unit/test_client_api.py +++ /dev/null @@ -1,225 +0,0 @@ -import asyncio -import json -import unittest.mock as mock - -import pytest -from httpx import AsyncClient, Response - -from stagehand import Stagehand - - -class TestClientAPI: - """Tests for the Stagehand client API interactions.""" - - @pytest.fixture - async def mock_client(self): - """Create a mock Stagehand client for testing.""" - client = Stagehand( - api_url="http://test-server.com", - browserbase_session_id="test-session-123", - api_key="test-api-key", - project_id="test-project-id", - model_api_key="test-model-api-key", - ) - return client - - @pytest.mark.asyncio - async def test_execute_success(self, mock_client): - """Test successful execution of a streaming API request.""" - - # Create a custom implementation of _execute for testing - async def mock_execute(method, payload): - # Print debug info - print("\n==== EXECUTING TEST_METHOD ====") - print( - f"URL: {mock_client.api_url}/sessions/{mock_client.session_id}/{method}" - ) - print(f"Payload: {payload}") - print( - f"Headers: {{'x-bb-api-key': '{mock_client.browserbase_api_key}', 'x-bb-project-id': '{mock_client.browserbase_project_id}', 'Content-Type': 'application/json', 'Connection': 'keep-alive', 'x-stream-response': 'true', 'x-model-api-key': '{mock_client.model_api_key}'}}" - ) - - # Return the expected result directly - return {"key": "value"} - - # Replace the method with our mock - mock_client._execute = mock_execute - - # Call _execute and check results - result = await mock_client._execute("test_method", {"param": "value"}) - - # Verify result matches the expected value - assert result == {"key": "value"} - - @pytest.mark.asyncio - async def test_execute_error_response(self, mock_client): - """Test handling of error responses.""" - # Create a mock implementation that simulates an error response - async def mock_execute(method, payload): - # Simulate the error handling that would happen in the real _execute method - raise RuntimeError("Request failed with status 400: Bad request") - - # Replace the method with our mock - mock_client._execute = mock_execute - - # Call _execute and expect it to raise the error - with pytest.raises(RuntimeError, match="Request failed with status 400"): - await mock_client._execute("test_method", {"param": "value"}) - - @pytest.mark.asyncio - async def test_execute_connection_error(self, mock_client): - """Test handling of connection errors.""" - - # Create a custom implementation of _execute that raises an exception - async def mock_execute(method, payload): - # Print debug info - print("\n==== EXECUTING TEST_METHOD ====") - print( - f"URL: {mock_client.api_url}/sessions/{mock_client.session_id}/{method}" - ) - print(f"Payload: {payload}") - print( - f"Headers: {{'x-bb-api-key': '{mock_client.browserbase_api_key}', 'x-bb-project-id': '{mock_client.browserbase_project_id}', 'Content-Type': 'application/json', 'Connection': 'keep-alive', 'x-stream-response': 'true', 'x-model-api-key': '{mock_client.model_api_key}'}}" - ) - - # Raise the expected exception - raise Exception("Connection failed") - - # Replace the method with our mock - mock_client._execute = mock_execute - - # Call _execute and check it raises the exception - with pytest.raises(Exception, match="Connection failed"): - await mock_client._execute("test_method", {"param": "value"}) - - @pytest.mark.asyncio - async def test_execute_invalid_json(self, mock_client): - """Test handling of invalid JSON in streaming response.""" - # Create a mock log method - mock_client._log = mock.MagicMock() - - # Create a custom implementation of _execute for testing - async def mock_execute(method, payload): - # Print debug info - print("\n==== EXECUTING TEST_METHOD ====") - print( - f"URL: {mock_client.api_url}/sessions/{mock_client.session_id}/{method}" - ) - print(f"Payload: {payload}") - print( - f"Headers: {{'x-bb-api-key': '{mock_client.browserbase_api_key}', 'x-bb-project-id': '{mock_client.browserbase_project_id}', 'Content-Type': 'application/json', 'Connection': 'keep-alive', 'x-stream-response': 'true', 'x-model-api-key': '{mock_client.model_api_key}'}}" - ) - - # Log an error for the invalid JSON - mock_client._log("Could not parse line as JSON: invalid json here", level=2) - - # Return the expected result - return {"key": "value"} - - # Replace the method with our mock - mock_client._execute = mock_execute - - # Call _execute and check results - result = await mock_client._execute("test_method", {"param": "value"}) - - # Should return the result despite the invalid JSON line - assert result == {"key": "value"} - - # Verify error was logged - mock_client._log.assert_called_with( - "Could not parse line as JSON: invalid json here", level=2 - ) - - @pytest.mark.asyncio - async def test_execute_no_finished_message(self, mock_client): - """Test handling of streaming response with no 'finished' message.""" - # Create a mock implementation that simulates no finished message - async def mock_execute(method, payload): - # Simulate processing log messages but not receiving a finished message - # In the real implementation, this would return None - return None - - # Replace the method with our mock - mock_client._execute = mock_execute - - # Mock the _handle_log method to track calls - log_calls = [] - async def mock_handle_log(message): - log_calls.append(message) - - mock_client._handle_log = mock_handle_log - - # Call _execute - it should return None when no finished message is received - result = await mock_client._execute("test_method", {"param": "value"}) - - # Should return None when no finished message is found - assert result is None - - @pytest.mark.asyncio - async def test_execute_on_log_callback(self, mock_client): - """Test the on_log callback is called for log messages.""" - # Setup a mock on_log callback - on_log_mock = mock.AsyncMock() - mock_client.on_log = on_log_mock - - # Create a mock implementation that simulates processing log messages - async def mock_execute(method, payload): - # Simulate processing two log messages and then a finished message - # Mock calling _handle_log for each log message - await mock_client._handle_log({"type": "log", "data": {"message": "Log message 1"}}) - await mock_client._handle_log({"type": "log", "data": {"message": "Log message 2"}}) - # Return the final result - return {"key": "value"} - - # Replace the method with our mock - mock_client._execute = mock_execute - - # Mock the _handle_log method and track calls - log_calls = [] - async def mock_handle_log(message): - log_calls.append(message) - - mock_client._handle_log = mock_handle_log - - # Call _execute - result = await mock_client._execute("test_method", {"param": "value"}) - - # Should return the result from the finished message - assert result == {"key": "value"} - - # Verify _handle_log was called for each log message - assert len(log_calls) == 2 - - @pytest.mark.asyncio - async def test_check_server_health(self, mock_client): - """Test server health check.""" - # Since _check_server_health doesn't exist in the actual code, - # we'll test a basic health check simulation - mock_client._health_check = mock.AsyncMock(return_value=True) - - result = await mock_client._health_check() - assert result is True - mock_client._health_check.assert_called_once() - - @pytest.mark.asyncio - async def test_check_server_health_failure(self, mock_client): - """Test server health check failure and retry.""" - # Mock a health check that fails - mock_client._health_check = mock.AsyncMock(return_value=False) - - result = await mock_client._health_check() - assert result is False - mock_client._health_check.assert_called_once() - - @pytest.mark.asyncio - async def test_api_timeout_handling(self, mock_client): - """Test API timeout handling.""" - # Mock the _execute method to simulate a timeout - async def timeout_execute(method, payload): - raise TimeoutError("Request timed out after 30 seconds") - - mock_client._execute = timeout_execute - - # Test that timeout errors are properly raised - with pytest.raises(TimeoutError, match="Request timed out after 30 seconds"): - await mock_client._execute("test_method", {"param": "value"}) diff --git a/tests/unit/test_client_initialization.py b/tests/unit/test_client_initialization.py index afec5c6b..c7524c8f 100644 --- a/tests/unit/test_client_initialization.py +++ b/tests/unit/test_client_initialization.py @@ -12,52 +12,37 @@ class TestClientInitialization: """Tests for the Stagehand client initialization and configuration.""" @pytest.mark.smoke - @mock.patch.dict(os.environ, {}, clear=True) + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test-openai-key"}, clear=True) def test_init_with_direct_params(self): """Test initialization with direct parameters.""" - # Create a config with LOCAL env to avoid BROWSERBASE validation issues - config = StagehandConfig(env="LOCAL") - client = Stagehand( - config=config, - api_url="http://test-server.com", - browserbase_session_id="test-session", - api_key="test-api-key", - project_id="test-project-id", + config = StagehandConfig( model_api_key="test-model-api-key", verbose=2, ) + client = Stagehand(config=config) - assert client.api_url == "http://test-server.com" - assert client.session_id == "test-session" - # In LOCAL mode, browserbase keys are not used assert client.model_api_key == "test-model-api-key" assert client.verbose == 2 assert client._initialized is False assert client._closed is False @pytest.mark.smoke - @mock.patch.dict(os.environ, {}, clear=True) + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test-openai-key"}, clear=True) def test_init_with_config(self): """Test initialization with a configuration object.""" config = StagehandConfig( - env="LOCAL", # Use LOCAL to avoid BROWSERBASE validation - api_key="config-api-key", - project_id="config-project-id", - browserbase_session_id="config-session-id", model_name="gpt-4", + model_api_key="config-model-key", dom_settle_timeout_ms=500, self_heal=True, wait_for_captcha_solves=True, system_prompt="Custom system prompt for testing", ) - client = Stagehand(config=config, api_url="http://test-server.com") + client = Stagehand(config=config) - assert client.api_url == "http://test-server.com" - assert client.session_id == "config-session-id" - assert client.browserbase_api_key == "config-api-key" - assert client.browserbase_project_id == "config-project-id" assert client.model_name == "gpt-4" + assert client.model_api_key == "config-model-key" assert client.dom_settle_timeout_ms == 500 assert hasattr(client, "self_heal") assert client.self_heal is True @@ -67,56 +52,34 @@ def test_init_with_config(self): assert hasattr(client, "system_prompt") assert client.system_prompt == "Custom system prompt for testing" - @mock.patch.dict(os.environ, {}, clear=True) + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test-openai-key"}, clear=True) def test_config_priority_over_direct_params(self): - """Test that config parameters take precedence over direct parameters (except session_id).""" + """Test that config parameters work correctly.""" config = StagehandConfig( - env="LOCAL", # Use LOCAL to avoid BROWSERBASE validation - api_key="config-api-key", - project_id="config-project-id", - browserbase_session_id="config-session-id", + model_api_key="config-model-key", + model_name="gpt-4", ) - client = Stagehand( - config=config, - api_key="direct-api-key", - project_id="direct-project-id", - browserbase_session_id="direct-session-id", - ) + client = Stagehand(config=config) - # Override parameters take precedence over config parameters - assert client.browserbase_api_key == "direct-api-key" - assert client.browserbase_project_id == "direct-project-id" - # session_id parameter overrides config since it's passed as browserbase_session_id override - assert client.session_id == "direct-session-id" + # Config parameters should be used + assert client.model_api_key == "config-model-key" + assert client.model_name == "gpt-4" + @mock.patch.dict(os.environ, {}, clear=True) def test_init_with_missing_required_fields(self): """Test initialization with missing required fields.""" - # No error when initialized without session_id - client = Stagehand( - api_key="test-api-key", project_id="test-project-id" - ) - assert client.session_id is None - - # Test that error handling for missing API key is functioning - # by patching the ValueError that should be raised - with mock.patch.object( - Stagehand, - "__init__", - side_effect=ValueError("browserbase_api_key is required"), - ): - with pytest.raises(ValueError, match="browserbase_api_key is required"): - Stagehand( - browserbase_session_id="test-session", project_id="test-project-id" - ) + # Test that error is raised when no API key is provided + from stagehand.config import StagehandConfigError + + with pytest.raises(StagehandConfigError, match="No API key found"): + client = Stagehand() + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test-openai-key"}, clear=True) def test_init_as_context_manager(self): """Test the client as a context manager.""" client = Stagehand( - api_url="http://test-server.com", - browserbase_session_id="test-session", - api_key="test-api-key", - project_id="test-project-id", + model_api_key="test-model-key", ) # Mock the async context manager methods @@ -137,10 +100,10 @@ def test_init_as_context_manager(self): assert client.close is not None @pytest.mark.asyncio + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test-openai-key"}, clear=True) async def test_init_playwright_timeout(self): """Test that init() raises TimeoutError when playwright takes too long to start.""" - config = StagehandConfig(env="LOCAL") - client = Stagehand(config=config) + client = Stagehand(model_api_key="test-model-key") # Mock async_playwright to simulate a hanging start() method mock_playwright_instance = mock.AsyncMock() @@ -162,98 +125,54 @@ async def hanging_start(): assert client._initialized is False @pytest.mark.asyncio - async def test_create_session(self): - """Test session creation.""" - client = Stagehand( - api_url="http://test-server.com", - api_key="test-api-key", - project_id="test-project-id", - model_api_key="test-model-api-key", - ) - - # Override the _create_session method for easier testing - original_create_session = client._create_session - - async def mock_create_session(): - client.session_id = "new-test-session-id" - - client._create_session = mock_create_session - - # Call _create_session - await client._create_session() - - # Verify session ID was set - assert client.session_id == "new-test-session-id" - - @pytest.mark.asyncio - async def test_create_session_failure(self): - """Test session creation failure.""" - client = Stagehand( - api_url="http://test-server.com", - api_key="test-api-key", - project_id="test-project-id", - model_api_key="test-model-api-key", - ) - - # Override the _create_session method to raise an error - original_create_session = client._create_session - - async def mock_create_session(): - raise RuntimeError("Failed to create session: Invalid request") - - client._create_session = mock_create_session - - # Call _create_session and expect error - with pytest.raises(RuntimeError, match="Failed to create session"): - await client._create_session() - - @pytest.mark.asyncio - async def test_create_session_invalid_response(self): - """Test session creation with invalid response format.""" - client = Stagehand( - api_url="http://test-server.com", - api_key="test-api-key", - project_id="test-project-id", - model_api_key="test-model-api-key", - ) - - # Override the _create_session method to raise a specific error - original_create_session = client._create_session - - async def mock_create_session(): - raise RuntimeError("Invalid response format: {'success': true, 'data': {}}") - - client._create_session = mock_create_session - - # Call _create_session and expect error - with pytest.raises(RuntimeError, match="Invalid response format"): - await client._create_session() + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test-openai-key"}, clear=True) + async def test_local_browser_initialization(self): + """Test local browser initialization.""" + client = Stagehand(model_api_key="test-model-key") + + # Mock the browser connection + with mock.patch("stagehand.main.connect_browser") as mock_connect: + mock_connect.return_value = ( + mock.MagicMock(), # browser + mock.MagicMock(), # context + mock.MagicMock(), # stagehand_context + mock.MagicMock(), # page + None # downloads_path + ) + + with mock.patch("stagehand.main.async_playwright") as mock_playwright: + mock_playwright_instance = mock.AsyncMock() + mock_playwright.return_value = mock_playwright_instance + mock_playwright_instance.start.return_value = mock.MagicMock() + + await client.init() + + # Verify client is initialized + assert client._initialized is True - @mock.patch.dict(os.environ, {"MODEL_API_KEY": "test-model-api-key"}, clear=True) + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "test-model-api-key"}, clear=True) def test_init_with_model_api_key_in_env(self): - config = StagehandConfig(env="LOCAL") - client = Stagehand(config=config) + client = Stagehand() assert client.model_api_key == "test-model-api-key" + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "fallback-key"}, clear=True) def test_init_with_custom_llm(self): config = StagehandConfig( - env="LOCAL", - model_client_options={"apiKey": "custom-llm-key", "baseURL": "https://custom-llm.com"} + model_client_options={"api_key": "custom-llm-key", "api_base": "https://custom-llm.com"} ) client = Stagehand(config=config) assert client.model_api_key == "custom-llm-key" - assert client.model_client_options["apiKey"] == "custom-llm-key" - assert client.model_client_options["baseURL"] == "https://custom-llm.com" + assert client.model_client_options["api_key"] == "custom-llm-key" + assert client.model_client_options["api_base"] == "https://custom-llm.com" + @mock.patch.dict(os.environ, {"OPENAI_API_KEY": "fallback-key"}, clear=True) def test_init_with_custom_llm_override(self): config = StagehandConfig( - env="LOCAL", - model_client_options={"apiKey": "custom-llm-key", "baseURL": "https://custom-llm.com"} + model_client_options={"api_key": "custom-llm-key", "api_base": "https://custom-llm.com"} ) + # Test that direct parameter overrides config client = Stagehand( config=config, - model_client_options={"apiKey": "override-llm-key", "baseURL": "https://override-llm.com"} + model_api_key="override-llm-key" ) - assert client.model_api_key == "override-llm-key" - assert client.model_client_options["apiKey"] == "override-llm-key" - assert client.model_client_options["baseURL"] == "https://override-llm.com" \ No newline at end of file + assert client.model_api_key == "override-llm-key" \ No newline at end of file