# Browser Service 🤖
**AI-powered browser automation made simple.** Automatically identify web elements and generate reliable locators for your automation scripts.
[](https://pypi.org/project/browser-service/)
[](https://www.python.org/downloads/)
## ✨ 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
```bash
pip install browser-service
```
### 2. Basic Usage
```python
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
- **Self-Healing**: Adapts when websites change their structure
### 🔧 Easy Configuration
```python
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
```python
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
```python
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
```python
workflow = {
"url": "https://news-site.com",
"steps": [
{"action": "extract", "element": "Article titles", "multiple": True},
{"action": "extract", "element": "Publication dates", "multiple": True}
]
}
```
### E-commerce Automation
```python
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
```python
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
```python
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
| Action | Description | Example |
|--------|-------------|---------|
| `click` | Click an element | `{"action": "click", "element": "Submit button"}` |
| `type` | Type text into field | `{"action": "type", "element": "Email field", "text": "user@email.com"}` |
| `select` | Select dropdown option | `{"action": "select", "element": "Country", "value": "USA"}` |
| `extract` | Get element text | `{"action": "extract", "element": "Price"}` |
| `wait` | Wait for element | `{"action": "wait", "element": "Loading spinner"}` |
| `scroll` | Scroll to element | `{"action": "scroll", "element": "Bottom of page"}` |
## 🏗️ API Reference
### Core Functions
```python
from browser_service.tasks import process_workflow_task
from browser_service.locators import generate_locators_from_attributes
from browser_service.browser import BrowserSessionManager
# Process a complete workflow
result = await process_workflow_task(workflow)
# Generate locators for an element
locators = generate_locators_from_attributes(element_attributes)
# Manage browser sessions
browser = BrowserSessionManager()
await browser.start_session()
# ... use browser ...
await browser.cleanup()
```
### Configuration Classes
```python
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**
```python
# 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**
```python
# Make sure you set your Gemini API key
config.GEMINI_API_KEY = "your-actual-api-key-from-google-ai-studio"
```
**❌ "Timeout" errors**
```python
# Increase timeout for slow pages
config.TIMEOUT = 60 # 60 seconds instead of default 30
```
### Debug Mode
```python
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](https://github.com/monkscode/browser-service/issues)
2. **💡 Feature Requests**: Open an issue with "Feature Request" label
3. **🔧 Code Contributions**: Fork → Branch → PR
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙋♂️ Support
- **📖 Documentation**: More examples in `/examples` folder
- **💬 Questions**: [GitHub Discussions](https://github.com/monkscode/browser-service/discussions)
- **🐛 Bug Reports**: [GitHub Issues](https://github.com/monkscode/browser-service/issues)
---
**Ready to automate?** 🚀 Install now and start building intelligent browser automation!
```bash
pip install browser-service
```
Raw data
{
"_id": null,
"home_page": "https://github.com/monkscode/browser-service",
"name": "browser-service",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "browser-service <1dhruvilvyas@gmail.com>, browser-service <patel.devasy.23@gmail.com>",
"keywords": "browser, automation, testing, locators, selenium, playwright, robot-framework, ai",
"author": "monkscode",
"author_email": "browser-service <1dhruvilvyas@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/c3/3b/c80ed9b6ba47e425a2df9e5b57c697a3806b5fd1309dabfe4d8827d76cb9/browser_service-1.0.1.tar.gz",
"platform": null,
"description": "# Browser Service \ud83e\udd16\n\n**AI-powered browser automation made simple.** Automatically identify web elements and generate reliable locators for your automation scripts.\n\n[](https://pypi.org/project/browser-service/)\n[](https://www.python.org/downloads/)\n\n## \u2728 What is Browser Service?\n\nBrowser 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!\n\n**Perfect for:**\n- \ud83e\udd16 Automated testing\n- \ud83d\udd04 Web scraping\n- \ud83d\udcca Data extraction\n- \ud83c\udfaf UI automation\n- \ud83d\ude80 Robotic Process Automation (RPA)\n\n## \ud83d\ude80 Quick Start\n\n### 1. Install\n\n```bash\npip install browser-service\n```\n\n### 2. Basic Usage\n\n```python\nimport asyncio\nfrom browser_service.config import config\nfrom browser_service.tasks import process_workflow_task\n\nasync def automate_website():\n # Configure your API key (get from Google AI Studio)\n config.GEMINI_API_KEY = \"your-gemini-api-key-here\"\n\n # Define what you want to automate\n workflow = {\n \"url\": \"https://example.com\",\n \"steps\": [\n {\"action\": \"click\", \"element\": \"Login button\"},\n {\"action\": \"type\", \"element\": \"Email field\", \"text\": \"user@example.com\"},\n {\"action\": \"click\", \"element\": \"Submit button\"}\n ]\n }\n\n # Run the automation\n result = await process_workflow_task(workflow)\n print(f\"\u2705 Automation completed: {result}\")\n\n# Run it\nasyncio.run(automate_website())\n```\n\nThat's it! The AI automatically finds the right elements on the page.\n\n## \ud83c\udfaf Key Features\n\n### \ud83e\udde0 AI-Powered Element Detection\n- **Natural Language**: Describe elements in plain English (\"Login button\", \"Search box\")\n- **Smart Locators**: Automatically generates reliable XPath, CSS, and Playwright selectors\n- **Self-Healing**: Adapts when websites change their structure\n\n### \ud83d\udd27 Easy Configuration\n```python\nfrom browser_service.config import config\n\n# Configure once, use everywhere\nconfig.GEMINI_API_KEY = \"your-api-key\"\nconfig.HEADLESS = True # Run without browser window\nconfig.TIMEOUT = 30 # Seconds to wait for elements\n```\n\n### \ud83c\udf10 Multiple Browser Support\n- Chrome/Chromium\n- Firefox\n- Safari (macOS)\n- Edge\n\n### \ud83d\udcca Built-in Monitoring\n```python\nfrom browser_service.utils import record_workflow_metrics\n\n# Track your automation performance\nmetrics = record_workflow_metrics(workflow_result)\nprint(f\"\u23f1\ufe0f Execution time: {metrics['duration']}s\")\nprint(f\"\ud83c\udfaf Success rate: {metrics['success_rate']}%\")\n```\n\n## \ud83d\udcda Usage Examples\n\n### Form Filling Automation\n\n```python\nworkflow = {\n \"url\": \"https://myapp.com/contact\",\n \"steps\": [\n {\"action\": \"type\", \"element\": \"Name field\", \"text\": \"John Doe\"},\n {\"action\": \"type\", \"element\": \"Email field\", \"text\": \"john@example.com\"},\n {\"action\": \"select\", \"element\": \"Country dropdown\", \"value\": \"United States\"},\n {\"action\": \"click\", \"element\": \"Submit button\"}\n ]\n}\n```\n\n### Data Extraction\n\n```python\nworkflow = {\n \"url\": \"https://news-site.com\",\n \"steps\": [\n {\"action\": \"extract\", \"element\": \"Article titles\", \"multiple\": True},\n {\"action\": \"extract\", \"element\": \"Publication dates\", \"multiple\": True}\n ]\n}\n```\n\n### E-commerce Automation\n\n```python\nworkflow = {\n \"url\": \"https://store.com\",\n \"steps\": [\n {\"action\": \"type\", \"element\": \"Search box\", \"text\": \"wireless headphones\"},\n {\"action\": \"click\", \"element\": \"Search button\"},\n {\"action\": \"click\", \"element\": \"First product\"},\n {\"action\": \"click\", \"element\": \"Add to cart button\"}\n ]\n}\n```\n\n## \ud83d\udd27 Configuration\n\n### Required Setup\n\n```python\nfrom browser_service.config import config\n\n# Required: Your Google Gemini API key\nconfig.GEMINI_API_KEY = \"your-gemini-api-key-here\"\n\n# Optional: Customize behavior\nconfig.HEADLESS = True # Run without browser UI\nconfig.TIMEOUT = 30 # Element wait timeout (seconds)\nconfig.BROWSER_TYPE = \"chrome\" # chrome, firefox, safari, edge\n```\n\n### Advanced Configuration\n\n```python\nfrom browser_service.config import BrowserServiceConfig\n\n# Create custom config\ncustom_config = BrowserServiceConfig(\n gemini_api_key=\"your-key\",\n headless=False,\n timeout=60,\n browser_type=\"firefox\"\n)\n```\n\n## \ud83c\udfae Action Types\n\n| Action | Description | Example |\n|--------|-------------|---------|\n| `click` | Click an element | `{\"action\": \"click\", \"element\": \"Submit button\"}` |\n| `type` | Type text into field | `{\"action\": \"type\", \"element\": \"Email field\", \"text\": \"user@email.com\"}` |\n| `select` | Select dropdown option | `{\"action\": \"select\", \"element\": \"Country\", \"value\": \"USA\"}` |\n| `extract` | Get element text | `{\"action\": \"extract\", \"element\": \"Price\"}` |\n| `wait` | Wait for element | `{\"action\": \"wait\", \"element\": \"Loading spinner\"}` |\n| `scroll` | Scroll to element | `{\"action\": \"scroll\", \"element\": \"Bottom of page\"}` |\n\n## \ud83c\udfd7\ufe0f API Reference\n\n### Core Functions\n\n```python\nfrom browser_service.tasks import process_workflow_task\nfrom browser_service.locators import generate_locators_from_attributes\nfrom browser_service.browser import BrowserSessionManager\n\n# Process a complete workflow\nresult = await process_workflow_task(workflow)\n\n# Generate locators for an element\nlocators = generate_locators_from_attributes(element_attributes)\n\n# Manage browser sessions\nbrowser = BrowserSessionManager()\nawait browser.start_session()\n# ... use browser ...\nawait browser.cleanup()\n```\n\n### Configuration Classes\n\n```python\nfrom browser_service.config import (\n config, # Global config instance\n BrowserServiceConfig, # Main config class\n BatchConfig, # Batch processing config\n LocatorConfig, # Locator generation config\n LLMConfig # AI model config\n)\n```\n\n## \ud83d\udc1b Troubleshooting\n\n### Common Issues\n\n**\u274c \"Element not found\" errors**\n```python\n# Solution: Make element descriptions more specific\n{\"action\": \"click\", \"element\": \"Blue Login button on the right\"} # Better\n{\"action\": \"click\", \"element\": \"Login button\"} # Worse\n```\n\n**\u274c \"API key invalid\" error**\n```python\n# Make sure you set your Gemini API key\nconfig.GEMINI_API_KEY = \"your-actual-api-key-from-google-ai-studio\"\n```\n\n**\u274c \"Timeout\" errors**\n```python\n# Increase timeout for slow pages\nconfig.TIMEOUT = 60 # 60 seconds instead of default 30\n```\n\n### Debug Mode\n\n```python\nimport logging\nfrom browser_service.utils import setup_logging\n\n# Enable detailed logging\nsetup_logging(level=logging.DEBUG)\n\n# Now you'll see detailed logs about element detection\n```\n\n## \ud83d\udccb Requirements\n\n- **Python**: 3.8 or higher\n- **API Key**: Google Gemini API key (free tier available)\n- **Browser**: Chrome/Chromium recommended (others supported)\n\n## \ud83e\udd1d Contributing\n\nFound a bug or want to improve Browser Service?\n\n1. **\ud83d\udc1b Report Issues**: [GitHub Issues](https://github.com/monkscode/browser-service/issues)\n2. **\ud83d\udca1 Feature Requests**: Open an issue with \"Feature Request\" label\n3. **\ud83d\udd27 Code Contributions**: Fork \u2192 Branch \u2192 PR\n\n## \ud83d\udcc4 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4b\u200d\u2642\ufe0f Support\n\n- **\ud83d\udcd6 Documentation**: More examples in `/examples` folder\n- **\ud83d\udcac Questions**: [GitHub Discussions](https://github.com/monkscode/browser-service/discussions)\n- **\ud83d\udc1b Bug Reports**: [GitHub Issues](https://github.com/monkscode/browser-service/issues)\n\n---\n\n**Ready to automate?** \ud83d\ude80 Install now and start building intelligent browser automation!\n\n```bash\npip install browser-service\n```\n",
"bugtrack_url": null,
"license": "Apache 2.0",
"summary": "Browser automation service with AI-powered element identification and locator generation",
"version": "1.0.1",
"project_urls": {
"Bug Tracker": "https://github.com/monkscode/browser-service/issues",
"Documentation": "https://github.com/monkscode/browser-service#readme",
"Homepage": "https://github.com/monkscode/browser-service",
"Repository": "https://github.com/monkscode/browser-service"
},
"split_keywords": [
"browser",
" automation",
" testing",
" locators",
" selenium",
" playwright",
" robot-framework",
" ai"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "aa2b500228d37767c2a110c15b5db9892442d671be63e688c41348e26c8fbc0e",
"md5": "fb2dccc4444eb798281bb35dd6419490",
"sha256": "4e13ca14c77322f70c96b1c1386644a76390b3c54fece5dd71b3003dda72f1fd"
},
"downloads": -1,
"filename": "browser_service-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fb2dccc4444eb798281bb35dd6419490",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 83234,
"upload_time": "2025-11-06T18:43:30",
"upload_time_iso_8601": "2025-11-06T18:43:30.063623Z",
"url": "https://files.pythonhosted.org/packages/aa/2b/500228d37767c2a110c15b5db9892442d671be63e688c41348e26c8fbc0e/browser_service-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "c33bc80ed9b6ba47e425a2df9e5b57c697a3806b5fd1309dabfe4d8827d76cb9",
"md5": "33c83c38cffc9b377b8398fadb55dedf",
"sha256": "66418662ed356ac598ba6481736ca4942eb3a4840fd1ebca9b50ad37a06d257d"
},
"downloads": -1,
"filename": "browser_service-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "33c83c38cffc9b377b8398fadb55dedf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 74197,
"upload_time": "2025-11-06T18:43:30",
"upload_time_iso_8601": "2025-11-06T18:43:30.988975Z",
"url": "https://files.pythonhosted.org/packages/c3/3b/c80ed9b6ba47e425a2df9e5b57c697a3806b5fd1309dabfe4d8827d76cb9/browser_service-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-11-06 18:43:30",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "monkscode",
"github_project": "browser-service",
"github_not_found": true,
"lcname": "browser-service"
}
JSON
