Browser Service 🤖

AI-powered browser automation made simple. Automatically identify web elements and generate reliable locators for your automation scripts.

✨ What is Browser Service?

Browser Service is an intelligent browser automation library that uses AI to automatically identify and generate reliable selectors for web elements. No more fragile XPath or CSS selectors that break when websites change!

Perfect for:

• 🤖 Automated testing
• 🔄 Web scraping
• 📊 Data extraction
• 🎯 UI automation
• 🚀 Robotic Process Automation (RPA)

🚀 Quick Start

1. Install

pip install browser-service

2. Basic Usage

import asyncio
from browser_service.config import config
from browser_service.tasks import process_workflow_task

async def automate_website():
    # Configure your API key (get from Google AI Studio)
    config.GEMINI_API_KEY = "your-gemini-api-key-here"

    # Define what you want to automate
    workflow = {
        "url": "https://example.com",
        "steps": [
            {"action": "click", "element": "Login button"},
            {"action": "type", "element": "Email field", "text": "user@example.com"},
            {"action": "click", "element": "Submit button"}
        ]
    }

    # Run the automation
    result = await process_workflow_task(workflow)
    print(f"✅ Automation completed: {result}")

# Run it
asyncio.run(automate_website())

That's it! The AI automatically finds the right elements on the page.

🎯 Key Features

🧠 AI-Powered Element Detection

• Natural Language: Describe elements in plain English ("Login button", "Search box")
• Smart Locators: Automatically generates reliable XPath, CSS, and Playwright selectors
• Built for Stability: Candidate locators are stability-scored and validated for uniqueness against the live page, so they keep working across sessions

🔧 Easy Configuration

from browser_service.config import config

# Configure once, use everywhere
config.GEMINI_API_KEY = "your-api-key"
config.HEADLESS = True  # Run without browser window
config.TIMEOUT = 30     # Seconds to wait for elements

🌐 Multiple Browser Support

• Chrome/Chromium
• Firefox
• Safari (macOS)
• Edge

📊 Built-in Monitoring

from browser_service.utils import record_workflow_metrics

# Track your automation performance
metrics = record_workflow_metrics(workflow_result)
print(f"⏱️  Execution time: {metrics['duration']}s")
print(f"🎯 Success rate: {metrics['success_rate']}%")

📚 Usage Examples

Form Filling Automation

workflow = {
    "url": "https://myapp.com/contact",
    "steps": [
        {"action": "type", "element": "Name field", "text": "John Doe"},
        {"action": "type", "element": "Email field", "text": "john@example.com"},
        {"action": "select", "element": "Country dropdown", "value": "United States"},
        {"action": "click", "element": "Submit button"}
    ]
}

Data Extraction

workflow = {
    "url": "https://news-site.com",
    "steps": [
        {"action": "extract", "element": "Article titles", "multiple": True},
        {"action": "extract", "element": "Publication dates", "multiple": True}
    ]
}

E-commerce Automation

workflow = {
    "url": "https://store.com",
    "steps": [
        {"action": "type", "element": "Search box", "text": "wireless headphones"},
        {"action": "click", "element": "Search button"},
        {"action": "click", "element": "First product"},
        {"action": "click", "element": "Add to cart button"}
    ]
}

🔧 Configuration

Required Setup

from browser_service.config import config

# Required: Your Google Gemini API key
config.GEMINI_API_KEY = "your-gemini-api-key-here"

# Optional: Customize behavior
config.HEADLESS = True          # Run without browser UI
config.TIMEOUT = 30             # Element wait timeout (seconds)
config.BROWSER_TYPE = "chrome"  # chrome, firefox, safari, edge

Advanced Configuration

from browser_service.config import BrowserServiceConfig

# Create custom config
custom_config = BrowserServiceConfig(
    gemini_api_key="your-key",
    headless=False,
    timeout=60,
    browser_type="firefox"
)

🎮 Action Types

🏗️ API Reference

Core Functions

from browser_service.tasks import process_workflow_task
from browser_service.browser import BrowserSessionManager

# Process a complete workflow
result = await process_workflow_task(workflow)

# Manage browser sessions
browser = BrowserSessionManager()
await browser.start_session()
# ... use browser ...
await browser.cleanup()

Configuration Classes

from browser_service.config import (
    config,                    # Global config instance
    BrowserServiceConfig,      # Main config class
    BatchConfig,              # Batch processing config
    LocatorConfig,            # Locator generation config
    LLMConfig                 # AI model config
)

🐛 Troubleshooting

Common Issues

❌ "Element not found" errors

# Solution: Make element descriptions more specific
{"action": "click", "element": "Blue Login button on the right"}  # Better
{"action": "click", "element": "Login button"}                   # Worse

❌ "API key invalid" error

# Make sure you set your Gemini API key
config.GEMINI_API_KEY = "your-actual-api-key-from-google-ai-studio"

❌ "Timeout" errors

# Increase timeout for slow pages
config.TIMEOUT = 60  # 60 seconds instead of default 30

Debug Mode

import logging
from browser_service.utils import setup_logging

# Enable detailed logging
setup_logging(level=logging.DEBUG)

# Now you'll see detailed logs about element detection

📋 Requirements

• Python: 3.8 or higher
• API Key: Google Gemini API key (free tier available)
• Browser: Chrome/Chromium recommended (others supported)

🤝 Contributing

Found a bug or want to improve Browser Service?

1. 🐛 Report Issues: GitHub Issues
2. 💡 Feature Requests: Open an issue with "Feature Request" label
3. 🔧 Code Contributions: Fork → Branch → PR

📄 License

MIT License - see LICENSE file for details.

🙋‍♂️ Support

• 📖 Documentation: More examples in /examples folder
• 💬 Questions: GitHub Discussions
• 🐛 Bug Reports: GitHub Issues

Ready to automate? 🚀 Install now and start building intelligent browser automation!

pip install browser-service