Merge pull request #70 from vstorm-co/fixes/0.3.9

fix: browser tool

Author: DEENUU1

CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.9] - 2026-04-12
+
+### Added
+
+- **Chromium auto-install (`BrowserCapability.auto_install`)** — when the Chromium binary is missing,
+  `BrowserCapability` now automatically runs `playwright install chromium` via the current Python
+  interpreter before the first agent run. On success the launch is retried immediately; on failure the
+  browser degrades gracefully (tools hidden, no instructions injected) without crashing the agent.
+  Controlled via `auto_install: bool = True` on `BrowserCapability`.
+
+### Changed
+
+- **`install.sh` now ships browser support out of the box** — the one-line installer now installs
+  `pydantic-deep[cli,browser]` (was `[cli]`) and runs `playwright install chromium` automatically.
+  New users get a fully working browser without any manual steps.
+- **Browser tool usage guidance** — `BROWSER_INSTRUCTIONS` now includes an explicit "when to use
+  browser vs web_search / web_fetch" section. The model is instructed to prefer the lighter
+  `web_search` / `web_fetch` tools for information lookup and static pages, and to reserve the
+  Playwright browser for interactive workflows (login, forms, JS-heavy SPAs, screenshots).
+
 ## [0.3.8] - 2026-04-12
 
 ### Added

install.sh

@@ -52,15 +52,26 @@ fi
 echo ""
 
 # ── Step 2: install pydantic-deep ─────────────────────────────────────────────
-say "Installing pydantic-deep CLI..."
-uv tool install "pydantic-deep[cli]" --upgrade
+say "Installing pydantic-deep CLI (with browser support)..."
+uv tool install "pydantic-deep[cli,browser]" --upgrade
 
 echo ""
 
-# ── Step 3: verify ────────────────────────────────────────────────────────────
-# uv tool executables land in ~/.local/bin — add it for immediate verification
+# ── Step 3: install Chromium for browser automation ───────────────────────────
+say "Installing Chromium for browser automation..."
+# uv tool executables land in ~/.local/bin — ensure it's in PATH
 export PATH="$HOME/.local/bin:$PATH"
 
+# playwright entry-point is installed alongside pydantic-deep in the same tool env
+if playwright install chromium 2>/dev/null; then
+    ok "Chromium installed."
+else
+    warn "Chromium install failed — run 'playwright install chromium' manually."
+fi
+
+echo ""
+
+# ── Step 4: verify ────────────────────────────────────────────────────────────
 if command -v pydantic-deep &>/dev/null; then
     VERSION="$(pydantic-deep --version 2>&1 | head -1)"
     ok "${VERSION} installed successfully!"

pydantic_deep/capabilities/browser.py

@@ -77,8 +77,21 @@ async def _auto_install_chromium() -> bool:
 
 
 BROWSER_INSTRUCTIONS: str = """\
-You have access to a real web browser powered by Playwright. Use browser tools to:
+You have access to a real web browser powered by Playwright.
 
+**When to use the browser (and NOT web_search / web_fetch):**
+- Pages that require login, authentication, or session cookies
+- JavaScript-heavy SPAs that don't render without JS
+- Interactive workflows: clicking buttons, filling forms, multi-step flows
+- Scraping paginated or dynamically loaded content
+- Visual debugging — taking screenshots to inspect UI
+
+**When to use web_search / web_fetch instead:**
+- Looking up information, documentation, or public articles
+- Reading a known URL whose content is static or server-rendered
+- Any task that doesn't require interaction — prefer the lighter tools
+
+Browser tools:
 - `navigate(url)` — go to a URL and read the page as Markdown
 - `click(selector)` — click a CSS selector or pixel coordinates 'x,y'
 - `type_text(selector, text)` — fill an input field

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pydantic-deep"
-version = "0.3.8"
+version = "0.3.9"
 description = "Batteries-included agent harness for Python — tool-calling, sandboxed execution, multi-agent teams, and unlimited context on Pydantic AI"
 readme = "README.md"
 keywords = [