fastweb-sdk 0.1.0__py3-none-any.whl

fastweb/__init__.py

@@ -0,0 +1,19 @@
+"""
+FastWeb Python SDK
+Zero-overhead, high-speed web execution for sovereign AI agents.
+
+NOTE: The FastWeb binary must be installed separately via:
+    python -m fastweb install
+
+Or manually:
+    curl -sL https://fastweb.b4n1.com/install | bash
+"""
+
+from .browser import AgentBrowser, BrowserMode, Page
+from .errors import BinaryNotFoundError
+
+__version__ = "0.1.0"
+__author__ = "Bani Montoya"
+__email__ = "banimontoya@gmail.com"
+
+__all__ = ["AgentBrowser", "BrowserMode", "Page", "BinaryNotFoundError"]

fastweb/__main__.py

@@ -0,0 +1,144 @@
+"""
+FastWeb CLI Entry Point
+"""
+
+
+def install_command():
+    """Handle the 'python -m fastweb install' command."""
+    import sys
+    import os
+    from pathlib import Path
+
+    print("FastWeb Binary Installer")
+    print("=" * 30)
+
+    # Import local modules to avoid circular imports
+    from .browser import get_fastweb_binary, get_fastweb_version
+
+    # Check if already installed
+    existing = get_fastweb_binary()
+    if existing:
+        version = get_fastweb_version()
+        print(f"FastWeb already installed at: {existing}")
+        print(f"Version: {version}")
+        response = input("Reinstall? (y/N): ").lower().strip()
+        if response not in ("y", "yes"):
+            print("Installation cancelled.")
+            return
+
+    # Determine install location
+    if os.access("/usr/local/bin", os.W_OK):
+        install_dir = Path("/usr/local/bin")
+        use_sudo = False
+    elif os.access(str(Path.home() / ".local/bin"), os.W_OK):
+        install_dir = Path.home() / ".local/bin"
+        use_sudo = False
+    else:
+        install_dir = Path.home() / ".fastweb" / "bin"
+        use_sudo = False  # User directory, no sudo needed
+
+    install_dir.mkdir(parents=True, exist_ok=True)
+    binary_path = install_dir / "fastweb"
+
+    # Download binary
+    version_url = "https://fastweb.b4n1.com/latest-version"
+    print(f"\nChecking latest version...")
+
+    try:
+        import requests
+
+        resp = requests.get(version_url, timeout=10)
+        version_info = resp.json()
+        download_url = version_info.get("url")
+        version = version_info.get("version", "unknown")
+        print(f"Latest version: {version}")
+        print(f"Downloading from: {download_url}")
+    except Exception as e:
+        print(f"Error getting version info: {e}")
+        sys.exit(1)
+
+    print(f"\nDownloading FastWeb {version}...")
+    try:
+        resp = requests.get(download_url, timeout=60)
+        resp.raise_for_status()
+
+        import tarfile
+
+        with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as tmp_tar:
+            tmp_tar.write(resp.content)
+            tmp_tar_path = tmp_tar.name
+
+        try:
+            # Extract and install binary
+            with tarfile.open(tmp_tar_path, "r:gz") as tar:
+                # Find the binary in the tar
+                for member in tar.getmembers():
+                    if member.isfile() and member.name.endswith(
+                        "/fastweb-v0.1.0-x86_64"
+                    ):
+                        # Extract the binary
+                        binary_data = tar.extractfile(member)
+                        if binary_data:
+                            with open(binary_path, "wb") as f:
+                                f.write(binary_data.read())
+                            break
+                else:
+                    # Fallback: look for any executable
+                    for member in tar.getmembers():
+                        if member.isfile():
+                            binary_data = tar.extractfile(member)
+                            if binary_data:
+                                with open(binary_path, "wb") as f:
+                                    f.write(binary_data.read())
+                                break
+
+            # Make executable
+            if use_sudo:
+                import subprocess
+
+                subprocess.run(["chmod", "+x", str(binary_path)], check=True)
+                if str(binary_path).startswith("/usr/local/bin") or str(
+                    binary_path
+                ).startswith("/usr/bin"):
+                    subprocess.run(
+                        ["sudo", "chmod", "+x", str(binary_path)], check=True
+                    )
+            else:
+                os.chmod(binary_path, 0o755)
+
+            # Verify installation
+            installed_version = get_fastweb_version()
+            print(f"✓ FastWeb {installed_version} installed to: {binary_path}")
+
+            if not use_sudo:
+                # Add to PATH instructions
+                rc_file = Path.home() / (
+                    ".bashrc"
+                    if os.environ.get("SHELL", "").endswith("bash")
+                    else ".zshrc"
+                )
+                path_line = f'export PATH="{install_dir}:$PATH"'
+                if rc_file.exists():
+                    content = rc_file.read_text()
+                    if path_line not in content:
+                        print(f"\nTo use FastWeb, add this to your {rc_file.name}:")
+                        print(f"  {path_line}")
+                else:
+                    print(
+                        f"\nTo use FastWeb, add this to your shell rc file (~/.bashrc or ~/.zshrc):"
+                    )
+                    print(f"  {path_line}")
+
+        finally:
+            try:
+                os.unlink(tmp_tar_path)
+            except:
+                pass
+
+    except Exception as e:
+        print(f"Error installing FastWeb: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    install_command()

fastweb/browser.py

@@ -0,0 +1,344 @@
+"""
+FastWeb Python SDK - Browser automation for AI agents
+
+This module provides a Python interface to the FastWeb Rust engine.
+The FastWeb binary must be installed separately via: python -m fastweb install
+"""
+
+import json
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from enum import Enum
+from typing import List, Optional
+import requests
+
+
+class BrowserMode(Enum):
+    """Browser execution modes."""
+
+    LIGHT = "light"
+    RENDER = "render"
+
+
+@dataclass
+class Page:
+    """Structured page data returned by FastWeb."""
+
+    url: str
+    markdown: str
+    links: List[str]
+    screenshot: Optional[str] = None
+
+    def get_main_content(self) -> str:
+        """Extract main content from markdown."""
+        lines = self.markdown.split("\n")
+        content_lines = lines[2:] if len(lines) > 2 else lines
+        return "\n".join(content_lines).strip()
+
+    def find_links_by_text(self, text: str) -> List[str]:
+        """Find links containing specific text."""
+        return [link for link in self.links if text.lower() in link.lower()]
+
+
+def get_fastweb_binary() -> Optional[str]:
+    """Find fastweb binary in common install locations."""
+    import os
+    from pathlib import Path
+    import shutil
+
+    # Check standard locations where the install script puts it
+    possible_locations = [
+        "/usr/local/bin/fastweb",
+        "/usr/bin/fastweb",
+        str(Path.home() / ".local/bin/fastweb"),
+        str(Path.home() / ".fastweb/bin/fastweb"),
+    ]
+
+    for loc in possible_locations:
+        if os.path.isfile(loc) and os.access(loc, os.X_OK):
+            return loc
+
+    return None
+
+
+class BinaryNotFoundError(RuntimeError):
+    """Raised when FastWeb binary is not found and needs to be installed."""
+
+    def __init__(self):
+        super().__init__(
+            "FastWeb binary not found. Please install it first:\n"
+            "  python -m fastweb install\n"
+            "Or manually:\n"
+            "  curl -sL https://fastweb.b4n1.com/install | bash"
+        )
+
+
+class AgentBrowser:
+    """
+    FastWeb Agent Browser
+
+    A browser instance optimized for AI agent workflows.
+    Requires FastWeb binary to be installed via: python -m fastweb install
+
+    Example:
+        >>> browser = AgentBrowser(mode=BrowserMode.LIGHT)
+        >>> page = browser.goto("https://example.com")
+        >>> print(page.markdown)
+    """
+
+    def __init__(
+        self,
+        mode: BrowserMode = BrowserMode.LIGHT,
+        timeout: int = 30,
+        user_agent: str = "FastWeb-Agent/1.0",
+    ):
+        self.mode = mode
+        self.timeout = timeout
+        self.user_agent = user_agent
+        self.session = requests.Session()
+        self.session.headers.update(
+            {
+                "User-Agent": user_agent,
+                "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+                "Accept-Language": "en-US,en;q=0.5",
+                "Accept-Encoding": "gzip, deflate",
+                "DNT": "1",
+                "Connection": "keep-alive",
+                "Upgrade-Insecure-Requests": "1",
+            }
+        )
+        # Verify binary is available - will raise BinaryNotFoundError if not found
+        from .errors import BinaryNotFoundError
+
+        binary_path = get_fastweb_binary()
+        if not binary_path:
+            raise BinaryNotFoundError()
+
+    @property
+    def binary_path(self) -> str:
+        """Get fastweb binary path."""
+        binary_path = get_fastweb_binary()
+        if not binary_path:
+            from .errors import BinaryNotFoundError
+
+            raise BinaryNotFoundError()
+        return binary_path
+
+    def goto(self, url: str) -> Page:
+        """Navigate to a URL and extract structured content."""
+        try:
+            response = self.session.get(url, timeout=self.timeout)
+            response.raise_for_status()
+
+            content_type = response.headers.get("content-type", "")
+            if "text/html" not in content_type:
+                raise ValueError(f"Not HTML content: {content_type}")
+
+            html = response.text
+
+            # Use Rust binary for parsing
+            return self._parse_with_rust(url, html)
+
+        except requests.RequestException as e:
+            raise requests.RequestException(f"Failed to fetch {url}: {e}")
+
+    def _parse_with_rust(self, url: str, html: str) -> Page:
+        """Parse HTML using Rust binary."""
+        # Write HTML to temp file
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".html", delete=False) as tmp:
+            tmp.write(html)
+            tmp_path = tmp.name
+
+        try:
+            # Run fastweb CLI
+            result = subprocess.run(
+                [self.binary_path, "fetch", url, "--text", "--links"],
+                capture_output=True,
+                timeout=30,
+            )
+
+            if result.returncode == 0 and result.stdout:
+                try:
+                    data = json.loads(result.stdout)
+                    return Page(
+                        url=url,
+                        markdown=data.get("text", ""),
+                        links=data.get("links", []),
+                    )
+                except json.JSONDecodeError:
+                    pass
+
+            raise RuntimeError(f"Binary parse failed: {result.stderr.decode()}")
+        finally:
+            try:
+                os.unlink(tmp_path)
+            except:
+                pass
+
+    def close(self):
+        """Close the browser session."""
+        self.session.close()
+
+
+def get_fastweb_version() -> str:
+    """Get FastWeb binary version."""
+    try:
+        result = subprocess.run(
+            [get_fastweb_binary(), "--version"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return "unknown"
+
+
+# CLI command implementation
+def install_command():
+    """Handle the 'python -m fastweb install' command."""
+    import sys
+    import os
+    from pathlib import Path
+
+    print("FastWeb Binary Installer")
+    print("=" * 30)
+
+    # Check if already installed
+    existing = get_fastweb_binary()
+    if existing:
+        version = get_fastweb_version()
+        print(f"FastWeb already installed at: {existing}")
+        print(f"Version: {version}")
+        response = input("Reinstall? (y/N): ").lower().strip()
+        if response not in ("y", "yes"):
+            print("Installation cancelled.")
+            return
+
+    # Determine install location
+    if os.access("/usr/local/bin", os.W_OK):
+        install_dir = Path("/usr/local/bin")
+        use_sudo = False
+    elif os.access(str(Path.home() / ".local/bin"), os.W_OK):
+        install_dir = Path.home() / ".local/bin"
+        use_sudo = False
+    else:
+        install_dir = Path.home() / ".fastweb" / "bin"
+        use_sudo = False  # User directory, no sudo needed
+
+    install_dir.mkdir(parents=True, exist_ok=True)
+    binary_path = install_dir / "fastweb"
+
+    # Download binary
+    version_url = "https://fastweb.b4n1.com/latest-version"
+    print(f"\nChecking latest version...")
+
+    try:
+        resp = requests.get(version_url, timeout=10)
+        version_info = resp.json()
+        download_url = version_info.get("url")
+        version = version_info.get("version", "unknown")
+        print(f"Latest version: {version}")
+        print(f"Downloading from: {download_url}")
+    except Exception as e:
+        print(f"Error getting version info: {e}")
+        sys.exit(1)
+
+    print(f"\nDownloading FastWeb {version}...")
+    try:
+        resp = requests.get(download_url, timeout=60)
+        resp.raise_for_status()
+
+        import tarfile
+
+        with tempfile.NamedTemporaryFile(suffix=".tar.gz", delete=False) as tmp_tar:
+            tmp_tar.write(resp.content)
+            tmp_tar_path = tmp_tar.name
+
+        try:
+            # Extract and install binary
+            with tarfile.open(tmp_tar_path, "r:gz") as tar:
+                # Find the binary in the tar
+                for member in tar.getmembers():
+                    if member.isfile() and member.name.endswith(
+                        "/fastweb-v0.1.0-x86_64"
+                    ):
+                        # Extract the binary
+                        binary_data = tar.extractfile(member)
+                        if binary_data:
+                            with open(binary_path, "wb") as f:
+                                f.write(binary_data.read())
+                            break
+                else:
+                    # Fallback: look for any executable
+                    for member in tar.getmembers():
+                        if member.isfile():
+                            binary_data = tar.extractfile(member)
+                            if binary_data:
+                                with open(binary_path, "wb") as f:
+                                    f.write(binary_data.read())
+                                break
+
+            # Make executable
+            if use_sudo:
+                import subprocess
+
+                subprocess.run(["chmod", "+x", str(binary_path)], check=True)
+                if str(binary_path).startswith("/usr/local/bin") or str(
+                    binary_path
+                ).startswith("/usr/bin"):
+                    subprocess.run(
+                        ["sudo", "chmod", "+x", str(binary_path)], check=True
+                    )
+            else:
+                os.chmod(binary_path, 0o755)
+
+            # Verify installation
+            installed_version = get_fastweb_version()
+            print(f"✓ FastWeb {installed_version} installed to: {binary_path}")
+
+            if not use_sudo:
+                # Add to PATH instructions
+                rc_file = Path.home() / (
+                    ".bashrc"
+                    if os.environ.get("SHELL", "").endswith("bash")
+                    else ".zshrc"
+                )
+                path_line = f'export PATH="{install_dir}:$PATH"'
+                if rc_file.exists():
+                    content = rc_file.read_text()
+                    if path_line not in content:
+                        print(f"\nTo use FastWeb, add this to your {rc_file.name}:")
+                        print(f"  {path_line}")
+                else:
+                    print(
+                        f"\nTo use FastWeb, add this to your shell rc file (~/.bashrc or ~/.zshrc):"
+                    )
+                    print(f"  {path_line}")
+
+        finally:
+            try:
+                os.unlink(tmp_tar_path)
+            except:
+                pass
+
+    except Exception as e:
+        print(f"Error installing FastWeb: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    # Allow running as module: python -m fastweb install
+    if len(sys.argv) > 1 and sys.argv[1] == "install":
+        install_command()
+    else:
+        print("FastWeb Python SDK")
+        print("Usage: python -m fastweb install")
+        print("       (to install the FastWeb binary)")
+        print("")
+        print("Once installed, use in your code:")
+        print("  from fastweb import BrowserMode, AgentBrowser")
+        print("  browser = AgentBrowser(mode=BrowserMode.LIGHT)")

fastweb/errors.py

@@ -0,0 +1,15 @@
+"""
+FastWeb SDK Exceptions
+"""
+
+
+class BinaryNotFoundError(RuntimeError):
+    """Raised when FastWeb binary is not found."""
+
+    def __init__(self):
+        super().__init__(
+            "FastWeb binary not found. Please install it first:\n"
+            "  python -m fastweb install\n"
+            "Or manually:\n"
+            "  curl -sL https://fastweb.b4n1.com/install | bash"
+        )

fastweb_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: fastweb-sdk
+Version: 0.1.0
+Summary: Python SDK for FastWeb Agentic Browser Engine - Requires explicit binary installation
+Author-email: Bani Montoya <banimontoya@gmail.com>
+License-Expression: MIT OR Apache-2.0
+Project-URL: Homepage, https://github.com/B4N1-com/fastweb
+Project-URL: Repository, https://github.com/B4N1-com/fastweb
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Dynamic: license-file
+
+# FastWeb Python SDK
+
+Python bindings for FastWeb: The Agentic Browser Engine.
+
+## Installation
+
+### 1. Install the Python SDK
+
+```bash
+pip install fastweb-sdk
+```
+
+### 2. Install the FastWeb Binary (Required)
+
+The SDK requires the FastWeb Rust binary to function. Install it explicitly:
+
+```bash
+python -m fastweb install
+```
+
+Or manually:
+
+```bash
+curl -sL https://fastweb.b4n1.com/install | bash
+```
+
+## Quick Start
+
+```python
+from fastweb import BrowserMode, AgentBrowser
+
+# Create a browser instance
+browser = AgentBrowser(mode=BrowserMode.LIGHT)
+
+# Navigate to a page
+page = browser.goto("https://example.com")
+
+# Access structured data
+print("Page content:")
+print(page.markdown)
+
+print(f"Found {len(page.links)} links")
+print("First 5 links:", page.links[:5])
+
+# Extract main content
+main_content = page.get_main_content()
+print("Main content preview:", main_content[:200] + "...")
+
+# Find specific links
+github_links = page.find_links_by_text("github")
+print("GitHub links:", github_links)
+
+# Close browser when done
+browser.close()
+```
+
+## Browser Modes
+
+### Light Mode (Default)
+
+- **Use case**: Reading articles, scraping static content, extracting links
+- **Performance**: < 15MB RAM, instant startup
+- **Capabilities**: HTML parsing, markdown conversion, link extraction
+- **Limitations**: No JavaScript execution
+
+```python
+browser = AgentBrowser(mode=BrowserMode.LIGHT)
+```
+
+### Render Mode
+
+- **Use case**: SPAs, form filling, visual verification
+- **Performance**: Higher memory usage, slower startup
+- **Capabilities**: Full JavaScript execution, screenshots, interaction
+
+```python
+browser = AgentBrowser(mode=BrowserMode.RENDER)
+```
+
+## API Reference
+
+### AgentBrowser
+
+Main browser class for web automation.
+
+#### Methods
+
+- `goto(url: str) -> Page`: Navigate to URL and return structured page data
+- `close()`: Close the browser session
+
+#### Parameters
+
+- `mode`: BrowserMode.LIGHT or BrowserMode.RENDER
+- `timeout`: Request timeout in seconds (default: 30)
+- `user_agent`: Custom user agent string
+
+### Page
+
+Structured data from a web page.
+
+#### Attributes
+
+- `url: str`: The page URL
+- `markdown: str`: Clean markdown content
+- `links: List[str]`: Extracted links
+- `screenshot: Optional[str]`: Base64-encoded screenshot (render mode only)
+
+#### Methods
+
+- `get_main_content() -> str`: Extract main content, skipping headers/footers
+- `find_links_by_text(text: str) -> List[str]`: Find links containing specific text
+
+## Context Manager
+
+Use `BrowserSession` for automatic cleanup:
+
+```python
+from fastweb import BrowserSession, BrowserMode
+
+with BrowserSession(mode=BrowserMode.LIGHT) as browser:
+    page = browser.goto("https://example.com")
+    print(page.markdown)
+# Browser automatically closed
+```
+
+## Development
+
+### Building
+
+```bash
+# Build Rust engine
+cd fastweb-engine/cli-core
+cargo build --release
+
+# Build Python SDK
+cd sdk-python
+python -m build
+```
+
+### Testing
+
+```bash
+# Run Rust tests
+cd fastweb-engine/cli-core
+cargo test
+
+# Run Python tests
+cd sdk-python
+python -m pytest
+```
+
+## Security
+
+- All HTTP requests use TLS
+- No arbitrary code execution
+- Input validation and sanitization
+- **Explicit Installation**: Binary must be installed via `python -m fastweb install` - no automatic downloads
+
+## License
+
+MIT OR Apache-2.0

fastweb_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+fastweb/__init__.py,sha256=n0-VFqpZLz_b9u4rV7xGQzqQ05wcyhGeB15P5XFPHrA,504
+fastweb/__main__.py,sha256=HvFgDjgyPLJmh90yf1Gzt9Gj82L1gjlRJBbocoCRyto,4991
+fastweb/browser.py,sha256=wytT0yQrNm47N6vSNKLVKgHEWKOFGWMDZ6jaSeQ4uCs,11188
+fastweb/errors.py,sha256=4GAX8KXbTIr7XS4CVBJ5EaKsP_w2xxTYvuxize1TBjA,391
+fastweb_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=qLamYHg6Dlg-8bg7A-_j35qfg5YWpSP-P_FQ8NsiUFg,1068
+fastweb_sdk-0.1.0.dist-info/METADATA,sha256=hVIideqy012oiijU9E9RcOjxp3wpp1k-TuoVWaER48k,4229
+fastweb_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+fastweb_sdk-0.1.0.dist-info/entry_points.txt,sha256=H-srTWKX73J2aZNnAHvAUhNRN5fH9mQzlbm7sWOPtMo,61
+fastweb_sdk-0.1.0.dist-info/top_level.txt,sha256=V-r157KWpldmRCXUQCAgzKVkcXvGZQ2WVwgs7xsYylw,8
+fastweb_sdk-0.1.0.dist-info/RECORD,,

fastweb_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

fastweb_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fastweb = fastweb.__main__:install_command

fastweb_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Bani Montoya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastweb_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+fastweb