plasmate-browser-use 0.3.0__tar.gz

plasmate_browser_use-0.3.0/.gitignore

@@ -0,0 +1,22 @@
+/target
+*.swp
+*.swo
+*~
+.DS_Store
+report.md
+.claude/settings.local.json
+smoke/node_modules/
+sdk/node/node_modules/
+sdk/node/dist/
+sdk/python/*.egg-info/
+sdk/python/dist/
+sdk/python/build/
+__pycache__/
+*.pyc
+
+# MCP registry publisher tokens
+.mcpregistry_*
+.vercel
+packages/*/node_modules/
+packages/*/.venv/
+packages/*/dist/

plasmate_browser_use-0.3.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: plasmate-browser-use
+Version: 0.3.0
+Summary: Plasmate SOM integration for Browser Use - 10x fewer tokens for AI web agents
+Project-URL: Homepage, https://plasmate.app
+Project-URL: Documentation, https://plasmate.app/docs/integration-browser-use
+Project-URL: Repository, https://github.com/plasmate-labs/plasmate
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: som-parser>=0.3.0
+Provides-Extra: browser-use
+Requires-Dist: browser-use>=0.12.0; extra == 'browser-use'
+Description-Content-Type: text/markdown
+
+# plasmate-browser-use
+
+SOM-based content extraction for [Browser Use](https://github.com/browser-use/browser-use). Drop-in alternative to Browser Use's default DOM serializer that uses Plasmate's Semantic Object Model (SOM) to reduce token costs by 10x or more.
+
+Instead of sending the full DOM tree to your LLM, Plasmate compresses web pages into a compact semantic representation. Same information, 90% fewer tokens, lower costs, faster responses.
+
+## Install
+
+```bash
+pip install plasmate-browser-use
+```
+
+## Prerequisites
+
+You need the `plasmate` binary installed:
+
+```bash
+# Via cargo
+cargo install plasmate
+
+# Or via install script
+curl -fsSL https://plasmate.app/install.sh | sh
+```
+
+Verify it works:
+
+```bash
+plasmate --version
+```
+
+## Quick Start
+
+### Basic extraction
+
+```python
+from plasmate_browser_use import PlasmateExtractor
+
+extractor = PlasmateExtractor()
+
+# Get raw SOM data as a dict
+som = extractor.extract("https://news.ycombinator.com")
+print(f"Elements: {som['meta']['element_count']}")
+print(f"Compression: {som['meta']['html_bytes'] / som['meta']['som_bytes']:.1f}x")
+```
+
+### Get page context for an LLM
+
+The `get_page_context()` method returns a formatted string optimized for LLM consumption, with interactive elements, links, content, and compression stats:
+
+```python
+context = extractor.get_page_context("https://example.com")
+print(context)
+```
+
+Output:
+
+```
+# Example Domain
+URL: https://example.com
+Language: en
+
+## Interactive Elements (1)
+  [e1] link "More information..." (click)
+
+## Content
+This domain is for use in illustrative examples in documents...
+
+---
+Compression: 15.2x (1256 HTML bytes -> 83 SOM bytes)
+Elements: 5 (1 interactive)
+```
+
+### Markdown extraction
+
+```python
+md = extractor.extract_markdown("https://example.com")
+print(md)
+```
+
+### Async support
+
+All methods have async variants:
+
+```python
+import asyncio
+
+async def main():
+    extractor = PlasmateExtractor()
+    context = await extractor.get_page_context_async("https://example.com")
+    som = await extractor.extract_async("https://example.com")
+    md = await extractor.extract_markdown_async("https://example.com")
+
+asyncio.run(main())
+```
+
+### Using with a Browser Use agent
+
+```python
+from browser_use import Agent
+from plasmate_browser_use import PlasmateExtractor
+
+extractor = PlasmateExtractor()
+
+# Get compact page context instead of full DOM
+context = extractor.get_page_context("https://example.com/products")
+
+# Feed to your Browser Use agent with 10x fewer tokens
+agent = Agent(task="Find the cheapest product", page_context=context)
+result = await agent.run()
+```
+
+### Token savings comparison
+
+```python
+from plasmate_browser_use import PlasmateExtractor, token_count_comparison
+
+extractor = PlasmateExtractor()
+som = extractor.extract("https://news.ycombinator.com")
+stats = token_count_comparison(som)
+
+print(f"HTML tokens: ~{stats['html_tokens_est']:,}")
+print(f"SOM tokens:  ~{stats['som_tokens_est']:,}")
+print(f"Savings:     {stats['token_savings_pct']}%")
+print(f"Ratio:       {stats['token_ratio']}x fewer tokens")
+```
+
+## Typical token savings
+
+| Site | HTML tokens | SOM tokens | Reduction |
+|------|------------|------------|-----------|
+| Hacker News | ~22,000 | ~1,200 | 18x |
+| Wikipedia article | ~85,000 | ~8,500 | 10x |
+| Amazon product page | ~120,000 | ~6,000 | 20x |
+| Google search results | ~45,000 | ~3,500 | 13x |
+
+Numbers vary by page. The more complex the page (ads, trackers, layout noise), the bigger the savings.
+
+## How it works
+
+1. Plasmate fetches the page and parses the HTML
+2. The DOM is compiled into a Semantic Object Model (SOM) that preserves meaning while stripping layout noise
+3. The SOM is serialized into a compact format with tagged interactive elements
+4. Your LLM agent sees the same page information in 10x fewer tokens
+
+## Links
+
+- [Plasmate](https://plasmate.app) -- the SOM engine
+- [SOM Spec](https://plasmate.app/docs/som-spec) -- Semantic Object Model specification
+- [Browser Use](https://github.com/browser-use/browser-use) -- AI agent browser framework
+- [Token cost analysis](https://plasmate.app/docs/cost-analysis) -- detailed benchmarks
+
+## License
+
+Apache-2.0

plasmate_browser_use-0.3.0/README.md

@@ -0,0 +1,154 @@
+# plasmate-browser-use
+
+SOM-based content extraction for [Browser Use](https://github.com/browser-use/browser-use). Drop-in alternative to Browser Use's default DOM serializer that uses Plasmate's Semantic Object Model (SOM) to reduce token costs by 10x or more.
+
+Instead of sending the full DOM tree to your LLM, Plasmate compresses web pages into a compact semantic representation. Same information, 90% fewer tokens, lower costs, faster responses.
+
+## Install
+
+```bash
+pip install plasmate-browser-use
+```
+
+## Prerequisites
+
+You need the `plasmate` binary installed:
+
+```bash
+# Via cargo
+cargo install plasmate
+
+# Or via install script
+curl -fsSL https://plasmate.app/install.sh | sh
+```
+
+Verify it works:
+
+```bash
+plasmate --version
+```
+
+## Quick Start
+
+### Basic extraction
+
+```python
+from plasmate_browser_use import PlasmateExtractor
+
+extractor = PlasmateExtractor()
+
+# Get raw SOM data as a dict
+som = extractor.extract("https://news.ycombinator.com")
+print(f"Elements: {som['meta']['element_count']}")
+print(f"Compression: {som['meta']['html_bytes'] / som['meta']['som_bytes']:.1f}x")
+```
+
+### Get page context for an LLM
+
+The `get_page_context()` method returns a formatted string optimized for LLM consumption, with interactive elements, links, content, and compression stats:
+
+```python
+context = extractor.get_page_context("https://example.com")
+print(context)
+```
+
+Output:
+
+```
+# Example Domain
+URL: https://example.com
+Language: en
+
+## Interactive Elements (1)
+  [e1] link "More information..." (click)
+
+## Content
+This domain is for use in illustrative examples in documents...
+
+---
+Compression: 15.2x (1256 HTML bytes -> 83 SOM bytes)
+Elements: 5 (1 interactive)
+```
+
+### Markdown extraction
+
+```python
+md = extractor.extract_markdown("https://example.com")
+print(md)
+```
+
+### Async support
+
+All methods have async variants:
+
+```python
+import asyncio
+
+async def main():
+    extractor = PlasmateExtractor()
+    context = await extractor.get_page_context_async("https://example.com")
+    som = await extractor.extract_async("https://example.com")
+    md = await extractor.extract_markdown_async("https://example.com")
+
+asyncio.run(main())
+```
+
+### Using with a Browser Use agent
+
+```python
+from browser_use import Agent
+from plasmate_browser_use import PlasmateExtractor
+
+extractor = PlasmateExtractor()
+
+# Get compact page context instead of full DOM
+context = extractor.get_page_context("https://example.com/products")
+
+# Feed to your Browser Use agent with 10x fewer tokens
+agent = Agent(task="Find the cheapest product", page_context=context)
+result = await agent.run()
+```
+
+### Token savings comparison
+
+```python
+from plasmate_browser_use import PlasmateExtractor, token_count_comparison
+
+extractor = PlasmateExtractor()
+som = extractor.extract("https://news.ycombinator.com")
+stats = token_count_comparison(som)
+
+print(f"HTML tokens: ~{stats['html_tokens_est']:,}")
+print(f"SOM tokens:  ~{stats['som_tokens_est']:,}")
+print(f"Savings:     {stats['token_savings_pct']}%")
+print(f"Ratio:       {stats['token_ratio']}x fewer tokens")
+```
+
+## Typical token savings
+
+| Site | HTML tokens | SOM tokens | Reduction |
+|------|------------|------------|-----------|
+| Hacker News | ~22,000 | ~1,200 | 18x |
+| Wikipedia article | ~85,000 | ~8,500 | 10x |
+| Amazon product page | ~120,000 | ~6,000 | 20x |
+| Google search results | ~45,000 | ~3,500 | 13x |
+
+Numbers vary by page. The more complex the page (ads, trackers, layout noise), the bigger the savings.
+
+## How it works
+
+1. Plasmate fetches the page and parses the HTML
+2. The DOM is compiled into a Semantic Object Model (SOM) that preserves meaning while stripping layout noise
+3. The SOM is serialized into a compact format with tagged interactive elements
+4. Your LLM agent sees the same page information in 10x fewer tokens
+
+## Links
+
+- [Plasmate](https://plasmate.app) -- the SOM engine
+- [SOM Spec](https://plasmate.app/docs/som-spec) -- Semantic Object Model specification
+- [Browser Use](https://github.com/browser-use/browser-use) -- AI agent browser framework
+- [Token cost analysis](https://plasmate.app/docs/cost-analysis) -- detailed benchmarks
+
+## License
+
+Apache-2.0

plasmate_browser_use-0.3.0/examples/basic_agent.py

@@ -0,0 +1,24 @@
+"""Example: Using Plasmate SOM with Browser Use for cheaper AI browsing."""
+import asyncio
+from plasmate_browser_use import PlasmateExtractor
+
+
+async def main():
+    extractor = PlasmateExtractor()
+
+    # Get SOM-formatted page context (10x fewer tokens than raw HTML)
+    context = extractor.get_page_context("https://news.ycombinator.com")
+    print(context)
+
+    # Or get structured SOM data
+    som = extractor.extract("https://news.ycombinator.com")
+    print(f"Compression: {som['meta']['html_bytes'] / som['meta']['som_bytes']:.1f}x")
+    print(f"Elements: {som['meta']['element_count']}")
+
+    # Or just markdown
+    md = extractor.extract_markdown("https://news.ycombinator.com")
+    print(md[:500])
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

plasmate_browser_use-0.3.0/plasmate_browser_use/__init__.py

@@ -0,0 +1,24 @@
+"""
+Plasmate SOM integration for Browser Use.
+
+Provides SOM-based content extraction that can replace or complement
+Browser Use's default DOM serialization, reducing token costs by 90%+.
+
+Example::
+
+    from plasmate_browser_use import PlasmateExtractor
+
+    extractor = PlasmateExtractor()
+    context = extractor.get_page_context("https://example.com")
+    print(context)
+"""
+
+from .extractor import PlasmateExtractor
+from .utils import token_count_comparison, estimate_tokens
+
+__all__ = [
+    "PlasmateExtractor",
+    "token_count_comparison",
+    "estimate_tokens",
+]
+__version__ = "0.3.0"

plasmate_browser_use-0.3.0/plasmate_browser_use/extractor.py

@@ -0,0 +1,145 @@
+"""Plasmate SOM extractor for Browser Use.
+
+Provides SOM-based content extraction that can replace or complement
+Browser Use's default DOM serialization, reducing token costs by 90%+.
+"""
+
+import asyncio
+import json
+import subprocess
+from typing import Optional
+
+from som_parser import parse_som, get_links, get_interactive_elements, get_text, to_markdown
+
+
+class PlasmateExtractor:
+    """Extract web page content using Plasmate's SOM format.
+
+    Use this alongside Browser Use to get structured, token-efficient
+    page representations instead of raw DOM serialization.
+    """
+
+    def __init__(self, plasmate_bin: str = "plasmate"):
+        self.plasmate_bin = plasmate_bin
+        self._verify_binary()
+
+    def _verify_binary(self):
+        """Check that plasmate binary is available."""
+        try:
+            result = subprocess.run(
+                [self.plasmate_bin, "--version"],
+                capture_output=True, text=True, timeout=5
+            )
+            if result.returncode != 0:
+                raise RuntimeError(f"plasmate binary not working: {result.stderr}")
+        except FileNotFoundError:
+            raise RuntimeError(
+                "plasmate binary not found. Install with: cargo install plasmate\n"
+                "Or: curl -fsSL https://plasmate.app/install.sh | sh"
+            )
+
+    def extract(self, url: str) -> dict:
+        """Fetch a URL and return parsed SOM output.
+
+        Returns the full SOM dict with regions, elements, meta, etc.
+        """
+        result = subprocess.run(
+            [self.plasmate_bin, "fetch", url],
+            capture_output=True, text=True, timeout=30
+        )
+        if result.returncode != 0:
+            raise RuntimeError(f"plasmate fetch failed: {result.stderr}")
+        return json.loads(result.stdout)
+
+    async def extract_async(self, url: str) -> dict:
+        """Async version of extract."""
+        proc = await asyncio.create_subprocess_exec(
+            self.plasmate_bin, "fetch", url,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE
+        )
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30)
+        if proc.returncode != 0:
+            raise RuntimeError(f"plasmate fetch failed: {stderr.decode()}")
+        return json.loads(stdout.decode())
+
+    def extract_markdown(self, url: str) -> str:
+        """Fetch a URL and return SOM content as markdown.
+
+        This is the simplest integration -- just get readable text
+        with structure preserved.
+        """
+        som_data = self.extract(url)
+        som = parse_som(som_data)
+        return to_markdown(som)
+
+    async def extract_markdown_async(self, url: str) -> str:
+        """Async version of extract_markdown."""
+        som_data = await self.extract_async(url)
+        som = parse_som(som_data)
+        return to_markdown(som)
+
+    def get_page_context(self, url: str) -> str:
+        """Get a token-efficient page context string for LLM consumption.
+
+        Returns a formatted string with:
+        - Page title and URL
+        - Interactive elements (what the agent can do)
+        - Content summary
+        - Compression stats
+        """
+        som_data = self.extract(url)
+        return self._build_context(som_data)
+
+    async def get_page_context_async(self, url: str) -> str:
+        """Async version of get_page_context."""
+        som_data = await self.extract_async(url)
+        return self._build_context(som_data)
+
+    def _build_context(self, som_data: dict) -> str:
+        """Build the LLM context string from raw SOM data."""
+        som = parse_som(som_data)
+
+        lines = []
+        lines.append(f"# {som.title}")
+        lines.append(f"URL: {som.url}")
+        lines.append(f"Language: {som.lang}")
+        lines.append("")
+
+        # Interactive elements
+        interactive = get_interactive_elements(som)
+        if interactive:
+            lines.append(f"## Interactive Elements ({len(interactive)})")
+            for el in interactive:
+                actions = ", ".join(el.actions) if el.actions else ""
+                label = el.text or el.label or (el.attrs.get("placeholder", "") if el.attrs else "")
+                lines.append(f'  [{el.id}] {el.role} "{label}" ({actions})')
+            lines.append("")
+
+        # Links
+        links = get_links(som)
+        if links:
+            lines.append(f"## Links ({len(links)})")
+            for link in links[:20]:  # Cap at 20
+                lines.append(f"  [{link['id']}] {link['text']} -> {link['href']}")
+            if len(links) > 20:
+                lines.append(f"  ... and {len(links) - 20} more")
+            lines.append("")
+
+        # Content
+        text = get_text(som)
+        if text:
+            lines.append("## Content")
+            lines.append(text[:2000])  # Cap content
+            if len(text) > 2000:
+                lines.append(f"... ({len(text) - 2000} more characters)")
+
+        # Stats
+        meta = som.meta
+        ratio = meta.html_bytes / max(meta.som_bytes, 1)
+        lines.append("")
+        lines.append("---")
+        lines.append(f"Compression: {ratio:.1f}x ({meta.html_bytes} HTML bytes -> {meta.som_bytes} SOM bytes)")
+        lines.append(f"Elements: {meta.element_count} ({meta.interactive_count} interactive)")
+
+        return "\n".join(lines)

plasmate_browser_use-0.3.0/plasmate_browser_use/utils.py

@@ -0,0 +1,64 @@
+"""Helper functions for the Plasmate Browser Use integration."""
+
+from typing import Any, Optional
+
+
+def estimate_tokens(text: str) -> int:
+    """Estimate token count for a string (roughly 4 chars per token)."""
+    return len(text.encode("utf-8")) // 4
+
+
+def token_count_comparison(
+    som_data: dict[str, Any],
+    som_text: Optional[str] = None,
+) -> dict[str, Any]:
+    """Compare token counts between raw HTML and SOM representation.
+
+    Useful for benchmarking and demonstrating the token savings Plasmate
+    provides over traditional browser backends.
+
+    Args:
+        som_data: A SOM document dict (as returned by Plasmate).
+        som_text: Pre-rendered SOM text. If not provided, token estimate
+            is based on the SOM bytes from metadata.
+
+    Returns:
+        Dict with token counts and savings ratio::
+
+            {
+                "html_bytes": 87234,
+                "som_bytes": 4521,
+                "html_tokens_est": 21808,
+                "som_tokens_est": 1130,
+                "byte_ratio": 19.3,
+                "token_ratio": 19.3,
+                "token_savings_pct": 94.8,
+            }
+    """
+    meta = som_data.get("meta", {})
+    html_bytes = meta.get("html_bytes", 0)
+    som_bytes = meta.get("som_bytes", 0)
+
+    if som_text is not None:
+        som_text_bytes = len(som_text.encode("utf-8"))
+    else:
+        som_text_bytes = som_bytes
+
+    # Token estimation: ~4 chars per token (standard heuristic)
+    html_tokens = html_bytes // 4
+    som_tokens = som_text_bytes // 4
+
+    byte_ratio = html_bytes / som_bytes if som_bytes else 0
+    token_ratio = html_tokens / som_tokens if som_tokens else 0
+    savings_pct = (1 - som_tokens / html_tokens) * 100 if html_tokens else 0
+
+    return {
+        "html_bytes": html_bytes,
+        "som_bytes": som_bytes,
+        "som_text_bytes": som_text_bytes,
+        "html_tokens_est": html_tokens,
+        "som_tokens_est": som_tokens,
+        "byte_ratio": round(byte_ratio, 1),
+        "token_ratio": round(token_ratio, 1),
+        "token_savings_pct": round(savings_pct, 1),
+    }

plasmate_browser_use-0.3.0/pyproject.toml

@@ -0,0 +1,25 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "plasmate-browser-use"
+version = "0.3.0"
+description = "Plasmate SOM integration for Browser Use - 10x fewer tokens for AI web agents"
+readme = "README.md"
+license = "Apache-2.0"
+requires-python = ">=3.11"
+dependencies = [
+    "som-parser>=0.3.0",
+]
+
+[project.optional-dependencies]
+browser-use = ["browser-use>=0.12.0"]
+
+[project.urls]
+Homepage = "https://plasmate.app"
+Documentation = "https://plasmate.app/docs/integration-browser-use"
+Repository = "https://github.com/plasmate-labs/plasmate"
+
+[tool.hatch.build.targets.wheel]
+packages = ["plasmate_browser_use"]