agentic-browsing-auditor 1.0.0__tar.gz

agentic_browsing_auditor-1.0.0/PKG-INFO

@@ -0,0 +1,98 @@
+Metadata-Version: 2.4
+Name: agentic-browsing-auditor
+Version: 1.0.0
+Summary: Lighthouse Agentic Browsing Audit CLI and local Web Dashboard
+Author-email: Amal Alexander <amalalex95@gmail.com>
+Project-URL: Homepage, https://github.com/amal-alexander/agentic-browsing-auditor
+Project-URL: LinkedIn, https://www.linkedin.com/in/amal-alexander-305780131/
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: Flask>=3.0.0
+Requires-Dist: click>=8.0.0
+Requires-Dist: rich>=13.0.0
+
+# Agentic Browsing Auditor
+
+[![PyPI Version](https://img.shields.io/pypi/v/agentic-browsing-auditor.svg)](https://pypi.org/project/agentic-browsing-auditor/)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-Amal%20Alexander-blue)](https://www.linkedin.com/in/amal-alexander-305780131/)
+
+A Python-based CLI tool and local dashboard to audit website performance for LLM agents using Google Lighthouse's experimental **Agentic Browsing** category (evaluates `llms.txt`, `WebMCP`, agent-centric accessibility, and layout stability).
+
+Developed by **Amal Alexander** ([LinkedIn](https://www.linkedin.com/in/amal-alexander-305780131/)).
+
+---
+
+## Why you need Chrome + Node
+
+The Agentic Browsing category:
+- Shipped in **Lighthouse 13.3** (May 2026) as part of the default config.
+- Requires **Chrome 150+** (or Chrome Canary).
+- Requires a local node environment to shell out to `lighthouse`.
+
+---
+
+## Setup & Installation
+
+You can install the auditor package directly from PyPI:
+
+```bash
+pip install agentic-browsing-auditor
+```
+
+### Pre-requisites
+
+1. **Install Node.js** (18+): https://nodejs.org
+2. **Install Lighthouse** globally:
+   ```bash
+   npm install -g lighthouse
+   ```
+3. **Get a compatible Chrome build.** Easiest path: install [Chrome Canary](https://www.google.com/chrome/canary/).
+4. **Point the tool at that Chrome binary** via the `CHROME_PATH` environment variable:
+   - **Windows (PowerShell)**:
+     ```powershell
+     $env:CHROME_PATH = "C:\Users\<YourUsername>\AppData\Local\Google\Chrome SxS\Application\chrome.exe"
+     ```
+   - **macOS**:
+     ```bash
+     export CHROME_PATH="/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
+     ```
+   - **Linux**:
+     ```bash
+     export CHROME_PATH="/usr/bin/google-chrome-canary"
+     ```
+
+---
+
+## Usage
+
+Once installed, you can access the auditor using the global CLI command `agentic-auditor`.
+
+### 1. Audit a Single URL
+Analyze a website and print a beautiful table of results directly inside the terminal:
+```bash
+agentic-auditor audit example.com
+```
+
+### 2. Bulk Audit URLs (with CSV export)
+Audit multiple URLs listed in a text file (one URL per line) and export the results to a CSV file.
+```bash
+agentic-auditor bulk urls.txt --output results.csv
+```
+
+### 3. Launch the Local Web Dashboard
+Serve the interactive visual Lighthouse-style dashboard locally:
+```bash
+agentic-auditor serve
+```
+Then visit http://localhost:5000 in your browser.
+
+---
+
+## Author & Contact
+
+Built and maintained by **Amal Alexander**.
+- **Email**: [amalalex95@gmail.com](mailto:amalalex95@gmail.com)
+- **LinkedIn**: [amal-alexander-305780131](https://www.linkedin.com/in/amal-alexander-305780131/)

agentic_browsing_auditor-1.0.0/README.md

@@ -0,0 +1,82 @@
+# Agentic Browsing Auditor
+
+[![PyPI Version](https://img.shields.io/pypi/v/agentic-browsing-auditor.svg)](https://pypi.org/project/agentic-browsing-auditor/)
+[![LinkedIn](https://img.shields.io/badge/LinkedIn-Amal%20Alexander-blue)](https://www.linkedin.com/in/amal-alexander-305780131/)
+
+A Python-based CLI tool and local dashboard to audit website performance for LLM agents using Google Lighthouse's experimental **Agentic Browsing** category (evaluates `llms.txt`, `WebMCP`, agent-centric accessibility, and layout stability).
+
+Developed by **Amal Alexander** ([LinkedIn](https://www.linkedin.com/in/amal-alexander-305780131/)).
+
+---
+
+## Why you need Chrome + Node
+
+The Agentic Browsing category:
+- Shipped in **Lighthouse 13.3** (May 2026) as part of the default config.
+- Requires **Chrome 150+** (or Chrome Canary).
+- Requires a local node environment to shell out to `lighthouse`.
+
+---
+
+## Setup & Installation
+
+You can install the auditor package directly from PyPI:
+
+```bash
+pip install agentic-browsing-auditor
+```
+
+### Pre-requisites
+
+1. **Install Node.js** (18+): https://nodejs.org
+2. **Install Lighthouse** globally:
+   ```bash
+   npm install -g lighthouse
+   ```
+3. **Get a compatible Chrome build.** Easiest path: install [Chrome Canary](https://www.google.com/chrome/canary/).
+4. **Point the tool at that Chrome binary** via the `CHROME_PATH` environment variable:
+   - **Windows (PowerShell)**:
+     ```powershell
+     $env:CHROME_PATH = "C:\Users\<YourUsername>\AppData\Local\Google\Chrome SxS\Application\chrome.exe"
+     ```
+   - **macOS**:
+     ```bash
+     export CHROME_PATH="/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary"
+     ```
+   - **Linux**:
+     ```bash
+     export CHROME_PATH="/usr/bin/google-chrome-canary"
+     ```
+
+---
+
+## Usage
+
+Once installed, you can access the auditor using the global CLI command `agentic-auditor`.
+
+### 1. Audit a Single URL
+Analyze a website and print a beautiful table of results directly inside the terminal:
+```bash
+agentic-auditor audit example.com
+```
+
+### 2. Bulk Audit URLs (with CSV export)
+Audit multiple URLs listed in a text file (one URL per line) and export the results to a CSV file.
+```bash
+agentic-auditor bulk urls.txt --output results.csv
+```
+
+### 3. Launch the Local Web Dashboard
+Serve the interactive visual Lighthouse-style dashboard locally:
+```bash
+agentic-auditor serve
+```
+Then visit http://localhost:5000 in your browser.
+
+---
+
+## Author & Contact
+
+Built and maintained by **Amal Alexander**.
+- **Email**: [amalalex95@gmail.com](mailto:amalalex95@gmail.com)
+- **LinkedIn**: [amal-alexander-305780131](https://www.linkedin.com/in/amal-alexander-305780131/)

agentic_browsing_auditor-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61.0.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "agentic-browsing-auditor"
+version = "1.0.0"
+description = "Lighthouse Agentic Browsing Audit CLI and local Web Dashboard"
+readme = "README.md"
+requires-python = ">=3.8"
+authors = [
+    { name = "Amal Alexander", email = "amalalex95@gmail.com" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "Flask>=3.0.0",
+    "click>=8.0.0",
+    "rich>=13.0.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/amal-alexander/agentic-browsing-auditor"
+"LinkedIn" = "https://www.linkedin.com/in/amal-alexander-305780131/"
+
+[project.scripts]
+agentic-auditor = "agentic_auditor.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+agentic_auditor = ["templates/*", "static/*"]

agentic_browsing_auditor-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

agentic_browsing_auditor-1.0.0/src/agentic_auditor/__init__.py

@@ -0,0 +1,10 @@
+from .auditor import run_lighthouse, build_report, normalize_url, AuditError
+from .app import app
+
+__all__ = [
+    "run_lighthouse",
+    "build_report",
+    "normalize_url",
+    "AuditError",
+    "app",
+]

agentic_browsing_auditor-1.0.0/src/agentic_auditor/app.py

@@ -0,0 +1,34 @@
+import os
+from flask import Flask, jsonify, render_template, request
+from .auditor import normalize_url, run_lighthouse, build_report, AuditError
+
+# Resolve template and static folders relative to this file
+base_dir = os.path.dirname(os.path.abspath(__file__))
+app = Flask(
+    __name__,
+    template_folder=os.path.join(base_dir, "templates"),
+    static_folder=os.path.join(base_dir, "static")
+)
+
+
+@app.route("/")
+def index():
+    return render_template("index.html")
+
+
+@app.route("/api/audit", methods=["POST"])
+def audit():
+    payload = request.get_json(silent=True) or {}
+    try:
+        url = normalize_url(payload.get("url", ""))
+        raw_report = run_lighthouse(url)
+        report = build_report(raw_report)
+        return jsonify({"ok": True, "report": report})
+    except AuditError as exc:
+        return jsonify({"ok": False, "error": str(exc)}), 400
+    except Exception as exc:  # safety net
+        return jsonify({"ok": False, "error": f"Unexpected error: {exc}"}), 500
+
+
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=5000, debug=True)

agentic_browsing_auditor-1.0.0/src/agentic_auditor/auditor.py

@@ -0,0 +1,241 @@
+import json
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from urllib.parse import urlparse
+
+CATEGORY_ID = "agentic-browsing"
+LIGHTHOUSE_TIMEOUT_SECONDS = 180
+
+
+class AuditError(Exception):
+    """Raised for any expected failure while running/parsing Lighthouse."""
+
+
+def normalize_url(raw: str) -> str:
+    raw = (raw or "").strip()
+    if not raw:
+        raise AuditError("Please enter a domain or URL.")
+    if not re.match(r"^https?://", raw, re.IGNORECASE):
+        raw = "https://" + raw
+    parsed = urlparse(raw)
+    if not parsed.netloc:
+        raise AuditError("That doesn't look like a valid domain or URL.")
+    return raw
+
+
+def find_lighthouse_binary() -> list:
+    """
+    Prefer a locally/globally installed `lighthouse` binary. Fall back to
+    `npx lighthouse`, which will download it on first run if needed.
+    """
+    # Check project-local node_modules first
+    # Walk up from this file's location to check if node_modules is present
+    base_dir = os.path.dirname(os.path.abspath(__file__))
+    # In a installed package, node_modules might be located in parent directories
+    # like the workspace root or site-packages.
+    # Let's search from base_dir upwards for node_modules/.bin/lighthouse
+    curr = base_dir
+    while True:
+        local_bin = os.path.join(curr, "node_modules", ".bin")
+        local_lh = os.path.join(local_bin, "lighthouse.cmd" if os.name == "nt" else "lighthouse")
+        if os.path.isfile(local_lh):
+            return [local_lh]
+        parent = os.path.dirname(curr)
+        if parent == curr:
+            break
+        curr = parent
+
+    lighthouse_path = shutil.which("lighthouse")
+    if lighthouse_path:
+        return [lighthouse_path]
+    npx_path = shutil.which("npx")
+    if npx_path:
+        return [npx_path, "--yes", "lighthouse"]
+    raise AuditError(
+        "Neither `lighthouse` nor `npx` was found on this machine. "
+        "Install Node.js, then run: npm install -g lighthouse"
+    )
+
+
+def resolve_chrome_path():
+    """
+    Resolve CHROME_PATH and validate it actually points at a file, so we
+    can fail loudly instead of silently falling back to whatever Chrome
+    chrome-launcher happens to find (usually stable Chrome).
+    """
+    chrome_path = os.environ.get("CHROME_PATH")
+    if not chrome_path:
+        return None
+    if not os.path.isfile(chrome_path):
+        raise AuditError(
+            f"CHROME_PATH is set to '{chrome_path}' but no file exists there. "
+            "Double-check the path (right-click your Chrome Canary shortcut "
+            "-> Properties -> Target on Windows)."
+        )
+    return chrome_path
+
+
+def run_lighthouse(url: str) -> dict:
+    binary_cmd = find_lighthouse_binary()
+    chrome_path = resolve_chrome_path()
+
+    with tempfile.TemporaryDirectory() as tmp_dir:
+        output_path = os.path.join(tmp_dir, "report.json")
+
+        chrome_flags = "--headless=new --no-sandbox --disable-gpu"
+
+        cmd = binary_cmd + [
+            url,
+            f"--only-categories={CATEGORY_ID}",
+            "--output=json",
+            f"--output-path={output_path}",
+            f"--chrome-flags={chrome_flags}",
+            "--quiet",
+            "--max-wait-for-load=45000",
+        ]
+
+        # chrome-launcher (used internally by Lighthouse) primarily reads
+        # the CHROME_PATH *environment variable*, not a CLI flag - so we
+        # pass it explicitly into the subprocess's environment, and also
+        # append --chrome-path for the (newer) Lighthouse versions that
+        # support it directly. Belt and suspenders.
+        run_env = os.environ.copy()
+        if chrome_path:
+            run_env["CHROME_PATH"] = chrome_path
+            cmd.append(f"--chrome-path={chrome_path}")
+            print(f"[agentic-audit] Using Chrome at: {chrome_path}")
+        else:
+            print(
+                "[agentic-audit] WARNING: CHROME_PATH is not set. "
+                "Lighthouse will auto-discover a Chrome install, which is "
+                "likely your regular stable Chrome (won't support the "
+                "agentic-browsing category)."
+            )
+
+        try:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=LIGHTHOUSE_TIMEOUT_SECONDS,
+                env=run_env,
+            )
+        except subprocess.TimeoutExpired as exc:
+            raise AuditError(
+                f"Lighthouse timed out after {LIGHTHOUSE_TIMEOUT_SECONDS}s "
+                "auditing this page."
+            ) from exc
+        except FileNotFoundError as exc:
+            raise AuditError(f"Couldn't launch Lighthouse: {exc}") from exc
+
+        if result.returncode != 0 or not os.path.exists(output_path):
+            stderr_tail = (result.stderr or "").strip()[-2000:]
+            raise AuditError(
+                "Lighthouse failed to produce a report. This usually means "
+                "Chrome couldn't be launched, the site couldn't be reached, "
+                "or your Chrome version doesn't support the Agentic Browsing "
+                f"category yet (needs Chrome 150+, or 130-149 with the "
+                f"webmcp-testing flag).\n\nDetails: {stderr_tail}"
+            )
+
+        with open(output_path, "r", encoding="utf-8") as f:
+            try:
+                return json.load(f)
+            except json.JSONDecodeError as exc:
+                raise AuditError("Lighthouse returned an unreadable report.") from exc
+
+
+def classify_audit(audit: dict) -> str:
+    """
+    Map a Lighthouse audit result to one of:
+    'fail', 'warning', 'pass', 'not_applicable', 'informative'
+    """
+    display_mode = audit.get("scoreDisplayMode")
+    score = audit.get("score")
+
+    if display_mode == "notApplicable":
+        return "not_applicable"
+    if display_mode == "informative":
+        return "informative"
+    if display_mode in ("manual", "error"):
+        return "warning"
+    if display_mode == "numeric":
+        # e.g. Cumulative Layout Shift - use score thresholds like Lighthouse does
+        if score is None:
+            return "informative"
+        if score >= 0.9:
+            return "pass"
+        if score >= 0.5:
+            return "warning"
+        return "fail"
+    # binary
+    if score == 1:
+        return "pass"
+    if score == 0:
+        return "fail"
+    return "warning"
+
+
+def build_report(raw: dict) -> dict:
+    categories = raw.get("categories", {})
+    category = categories.get(CATEGORY_ID)
+    if category is None:
+        raise AuditError(
+            "This Lighthouse report has no 'agentic-browsing' category. "
+            "Your Chrome/Lighthouse version likely doesn't support it yet."
+        )
+
+    audits_by_id = raw.get("audits", {})
+    groups_meta = raw.get("categoryGroups") or raw.get("groups") or {}
+
+    grouped: dict = {}
+    ungrouped = []
+
+    pass_count = 0
+    fail_or_warn_count = 0
+
+    for ref in category.get("auditRefs", []):
+        audit_id = ref.get("id")
+        audit = audits_by_id.get(audit_id, {})
+        status = classify_audit(audit)
+
+        entry = {
+            "id": audit_id,
+            "title": audit.get("title", audit_id),
+            "description": audit.get("description", ""),
+            "status": status,
+            "display_value": audit.get("displayValue"),
+            "score": audit.get("score"),
+        }
+
+        if status in ("pass",):
+            pass_count += 1
+        elif status in ("fail", "warning"):
+            fail_or_warn_count += 1
+
+        group_id = ref.get("group")
+        if group_id:
+            group_title = (groups_meta.get(group_id) or {}).get("title", group_id)
+            grouped.setdefault(group_id, {"title": group_title, "audits": []})
+            grouped[group_id]["audits"].append(entry)
+        else:
+            ungrouped.append(entry)
+
+    total_scored = pass_count + fail_or_warn_count
+    ratio_label = f"{pass_count}/{total_scored}" if total_scored else "N/A"
+
+    return {
+        "final_url": raw.get("finalUrl") or raw.get("requestedUrl"),
+        "fetch_time": raw.get("fetchTime"),
+        "lighthouse_version": raw.get("lighthouseVersion"),
+        "category_title": category.get("title", "Agentic Browsing"),
+        "category_description": category.get("description", ""),
+        "pass_ratio_label": ratio_label,
+        "pass_count": pass_count,
+        "scored_count": total_scored,
+        "ungrouped_audits": ungrouped,
+        "groups": list(grouped.values()),
+    }