{"id":49173598,"url":"https://github.com/monkscode/browser-service","last_synced_at":"2026-04-22T21:00:55.583Z","repository":{"id":350527388,"uuid":"1091176009","full_name":"monkscode/browser-service","owner":"monkscode","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-20T09:17:36.000Z","size":380,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-21T02:13:53.247Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/monkscode.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-06T16:52:58.000Z","updated_at":"2026-04-20T07:23:43.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/monkscode/browser-service","commit_stats":null,"previous_names":["monkscode/browser-service"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/monkscode/browser-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkscode%2Fbrowser-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkscode%2Fbrowser-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkscode%2Fbrowser-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkscode%2Fbrowser-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/monkscode","download_url":"https://codeload.github.com/monkscode/browser-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/monkscode%2Fbrowser-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32154688,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T17:06:48.269Z","status":"ssl_error","status_checked_at":"2026-04-22T17:06:19.037Z","response_time":58,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-22T21:00:32.667Z","updated_at":"2026-04-22T21:00:55.577Z","avatar_url":"https://github.com/monkscode.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Browser Service 🤖\n\n**AI-powered browser automation made simple.** Automatically identify web elements and generate reliable locators for your automation scripts.\n\n[![PyPI version](https://badge.fury.io/py/browser-service.svg)](https://pypi.org/project/browser-service/)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n\n## ✨ 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- 🤖 Automated testing\n- 🔄 Web scraping\n- 📊 Data extraction\n- 🎯 UI automation\n- 🚀 Robotic Process Automation (RPA)\n\n## 🚀 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\"✅ 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## 🎯 Key Features\n\n### 🧠 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### 🔧 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### 🌐 Multiple Browser Support\n- Chrome/Chromium\n- Firefox\n- Safari (macOS)\n- Edge\n\n### 📊 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\"⏱️  Execution time: {metrics['duration']}s\")\nprint(f\"🎯 Success rate: {metrics['success_rate']}%\")\n```\n\n## 📚 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## 🔧 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## 🎮 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## 🏗️ 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## 🐛 Troubleshooting\n\n### Common Issues\n\n**❌ \"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**❌ \"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**❌ \"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## 📋 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## 🤝 Contributing\n\nFound a bug or want to improve Browser Service?\n\n1. **🐛 Report Issues**: [GitHub Issues](https://github.com/monkscode/browser-service/issues)\n2. **💡 Feature Requests**: Open an issue with \"Feature Request\" label\n3. **🔧 Code Contributions**: Fork → Branch → PR\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙋‍♂️ Support\n\n- **📖 Documentation**: More examples in `/examples` folder\n- **💬 Questions**: [GitHub Discussions](https://github.com/monkscode/browser-service/discussions)\n- **🐛 Bug Reports**: [GitHub Issues](https://github.com/monkscode/browser-service/issues)\n\n---\n\n**Ready to automate?** 🚀 Install now and start building intelligent browser automation!\n\n```bash\npip install browser-service\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkscode%2Fbrowser-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmonkscode%2Fbrowser-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmonkscode%2Fbrowser-service/lists"}