superacli 1.1.4 → 1.1.6

package/ref-monty/examples/sql_playground/type_stubs.pyi

@@ -0,0 +1,14 @@
+from pathlib import Path
+from typing import Any
+
+async def query_csv(filepath: Path, sql: str, parameters: dict[str, Any] | None = None) -> list[dict[str, Any]]:
+    """Execute SQL query on a CSV file using DuckDB."""
+    ...
+
+async def read_json(filepath: Path) -> list[Any] | dict[str, Any]:
+    """Read and parse a JSON file."""
+    ...
+
+async def analyze_sentiment(text: str) -> float:
+    """Analyze sentiment of text. Returns score from -1.0 to +1.0."""
+    ...

package/ref-monty/examples/web_scraper/README.md

@@ -0,0 +1,15 @@
+# Web Scraper Example
+
+This example uses Python dataclass APIs for playwright and beautifulsoup to allow the LLM
+to extract price data from the websites of model labs.
+
+We use Pydantic AI to generate code, but instead of using the `CodeExecutionToolset` type from Pydantic AI,
+we get the LLM to generate code directly allowing us to use new features of Monty not yet available in Pydantic AI.
+
+Look at `example_code.py` for an example of the kind of code sonnet 4.5 will generate in this case.
+
+Run the example with
+
+```bash
+uv run python -m examples.web_scraper.main
+```

package/ref-monty/examples/web_scraper/browser.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, AsyncIterator, Literal
+
+from playwright.async_api import Browser as PwBrowser, Page as PwPage, async_playwright
+
+if TYPE_CHECKING:
+    from .external_functions import Page
+
+pw_pages: dict[int, PwPage] = {}
+
+
+@asynccontextmanager
+async def start_browser() -> AsyncIterator[Browser]:
+    async with async_playwright() as p:
+        b = await p.chromium.launch()
+        yield Browser(b)
+        pw_pages.clear()
+        await b.close()
+
+
+@dataclass
+class Browser:
+    _pw_browser: PwBrowser
+
+    async def open_page(
+        self,
+        url: str,
+        wait_until: Literal['commit', 'domcontentloaded', 'load', 'networkidle'] = 'networkidle',
+    ) -> Page:
+        """Open a URL in a headless browser and return a `Page`.
+
+        Use this to load a web page so you can inspect its HTML content.
+
+        Args:
+            url: The URL to navigate to.
+            wait_until: When to consider navigation complete:
+                `'commit'` — after the response is received,
+                `'domcontentloaded'` — after the `DOMContentLoaded` event,
+                `'load'` — after the `load` event,
+                `'networkidle'` — after there are no network connections for 500ms.
+        """
+        from .external_functions import Page
+
+        page = await self._pw_browser.new_page()
+        await page.goto(url, wait_until=wait_until)
+        page_id = id(page)
+        pw_pages[page_id] = page
+        return Page(
+            url=page.url,
+            title=await page.title(),
+            html=await page.content(),
+            id=page_id,
+        )

package/ref-monty/examples/web_scraper/example_code.py

@@ -0,0 +1,59 @@
+import asyncio
+
+# Open the pricing page
+page = await open_page(url)
+
+# Parse the HTML with BeautifulSoup
+soup = beautiful_soup(page.html)
+
+# Find the main content area that contains pricing information
+# Let's look for tables or structured pricing data
+pricing_tables = soup.find_all('table')
+
+# Initialize a list to store all model pricing data
+all_models = []
+
+# Process each table found
+for table in pricing_tables:
+    # Get all rows in the table
+    rows = table.find_all('tr')
+
+    if len(rows) < 2:  # Skip tables without data rows
+        continue
+
+    # Get headers from the first row
+    header_row = rows[0]
+    headers = [th.get_text(strip=True) for th in header_row.find_all(['th', 'td'])]
+
+    # Process data rows
+    for row in rows[1:]:
+        cells = row.find_all(['td', 'th'])
+        if len(cells) < 2:
+            continue
+
+        # Extract cell values
+        row_data = [cell.get_text(strip=True) for cell in cells]
+
+        # Skip rows that might indicate deprecated models
+        row_text = ' '.join(row_data).lower()
+        if 'deprecated' in row_text or 'legacy' in row_text:
+            continue
+
+        # Create a dictionary for this model
+        model_info = {}
+        for i, value in enumerate(row_data):
+            if i < len(headers):
+                model_info[headers[i]] = value
+            else:
+                model_info[f'column_{i}'] = value
+
+        if model_info:  # Only add if we have data
+            all_models.append(model_info)
+
+# Print the results
+print(f'Found {len(all_models)} models with pricing data')
+print('\nModel pricing information:')
+for i, model in enumerate(all_models, 1):
+    print(f'\n{i}. {model}')
+
+all_models

package/ref-monty/examples/web_scraper/external_functions.py

@@ -0,0 +1,324 @@
+import re
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+
+from bs4 import BeautifulSoup, Tag as BsTag
+
+from .browser import PwPage, pw_pages
+
+
+async def open_page(
+    url: str,
+    wait_until: Literal['commit', 'domcontentloaded', 'load', 'networkidle'] = 'networkidle',
+) -> Page:
+    """Open a URL in a headless browser and return a `Page`.
+
+    Use this to load a web page so you can inspect its HTML content.
+
+    Args:
+        url: The URL to navigate to.
+        wait_until: When to consider navigation complete:
+            `'commit'` — after the response is received,
+            `'domcontentloaded'` — after the `DOMContentLoaded` event,
+            `'load'` — after the `load` event,
+            `'networkidle'` — after there are no network connections for 500ms.
+    """
+    raise NotImplementedError('this is here just to generate stubs, see _generate_stubs in main.py')
+
+
+@dataclass
+class Page:
+    """A snapshot of a Playwright page."""
+
+    url: str
+    title: str
+    html: str
+    id: int
+    _pw_page: PwPage = field(init=False)
+
+    def __post_init__(self):
+        self._pw_page = pw_pages[self.id]
+
+    async def go_to(
+        self,
+        url: str,
+        wait_until: Literal['commit', 'domcontentloaded', 'load', 'networkidle'] = 'networkidle',
+    ) -> None:
+        """Navigate the page to a new URL.
+
+        Args:
+            url: The URL to navigate to.
+            wait_until: When to consider navigation complete:
+                `'commit'` — after the response is received,
+                `'domcontentloaded'` — after the `DOMContentLoaded` event,
+                `'load'` — after the `load` event,
+                `'networkidle'` — after there are no network connections for 500ms.
+        """
+        await self._pw_page.goto(url, wait_until=wait_until)
+
+    async def click(self, selector: str, force: bool = False) -> None:
+        """Click an element matching the CSS selector and return the updated page.
+
+        Args:
+            selector: A CSS selector, e.g. `'button.submit'`, `'a[href="/next"]'`.
+            force: If `True`, bypass actionability checks (visibility, pointer-events interception).
+                Useful when an overlay or sticky nav covers the target element.
+        """
+        await self._pw_page.click(selector, force=force)
+        await self._pw_page.wait_for_load_state('networkidle')
+
+    async def fill(self, selector: str, value: str) -> None:
+        """Fill a form field matching the CSS selector with the given value.
+
+        Args:
+            selector: A CSS selector for an input/textarea, e.g. `'input[name="email"]'`.
+            value: The text to type into the field.
+        """
+        await self._pw_page.fill(selector, value)
+        await self._pw_page.wait_for_load_state('networkidle')
+
+    async def select_option(self, selector: str, value: str) -> None:
+        """Select an option in a `<select>` element.
+
+        Args:
+            selector: A CSS selector for the select element.
+            value: The value attribute of the option to select.
+        """
+        await self._pw_page.select_option(selector, value)
+        await self._pw_page.wait_for_load_state('networkidle')
+
+    async def check(self, selector: str) -> None:
+        """Check a checkbox or radio button.
+
+        Args:
+            selector: A CSS selector for the checkbox/radio input.
+        """
+        await self._pw_page.check(selector)
+        await self._pw_page.wait_for_load_state('networkidle')
+
+    async def press(self, selector: str, key: str) -> None:
+        """Press a keyboard key on a focused element.
+
+        Args:
+            selector: A CSS selector for the element to focus.
+            key: Key to press, e.g. `'Enter'`, `'Tab'`, `'ArrowDown'`.
+        """
+        await self._pw_page.press(selector, key)
+        await self._pw_page.wait_for_load_state('networkidle')
+
+    async def wait_for_selector(self, selector: str, timeout: float = 30_000) -> None:
+        """Wait for an element matching the CSS selector to appear, then return the updated page.
+
+        Args:
+            selector: A CSS selector to wait for.
+            timeout: Maximum time to wait in milliseconds (default 30 000).
+        """
+        await self._pw_page.wait_for_selector(selector, timeout=timeout)
+        await self._pw_page.wait_for_load_state('networkidle')
+
+    async def screenshot(self, full_page: bool = False) -> bytes:
+        """Take a screenshot of the current page.
+
+        Args:
+            full_page: If `True`, capture the full scrollable page rather than just the viewport.
+
+        Returns:
+            PNG image bytes.
+        """
+        return await self._pw_page.screenshot(full_page=full_page, type='png')
+
+    async def evaluate(self, expression: str) -> str:
+        """Evaluate a JavaScript expression on the page and return the result as a string.
+
+        Args:
+            expression: JavaScript to evaluate, e.g. `'document.title'`.
+        """
+        result = await self._pw_page.evaluate(expression)
+        return str(result)
+
+    async def get_text(self, selector: str) -> str:
+        """Get the text content of the first element matching the CSS selector.
+
+        Args:
+            selector: A CSS selector, e.g. `'h1'`, `'.price'`.
+
+        Returns:
+            The text content of the matched element, or an empty string if not found.
+        """
+        text = await self._pw_page.text_content(selector)
+        return text or ''
+
+    async def get_attribute(self, selector: str, name: str) -> str | None:
+        """Get an attribute value from the first element matching the CSS selector.
+
+        Args:
+            selector: A CSS selector.
+            name: Attribute name, e.g. `'href'`, `'src'`.
+
+        Returns:
+            The attribute value, or `None` if the element or attribute is not found.
+        """
+        return await self._pw_page.get_attribute(selector, name)
+
+
+def beautiful_soup(html: str) -> Tag:
+    """Parse html with BeautifulSoup and return a `Tag`.
+
+    Use this tool to get back a `Tag` object that can be used to extract information from HTML.
+    """
+    soup = BeautifulSoup(html, 'html.parser')
+    return _from_beautifulsoup(soup)
+
+
+@dataclass
+class Tag:
+    """A mirror of a BeautifulSoup `Tag`."""
+
+    name: str
+    attrs: dict[str, str | list[str]] = field(default_factory=dict)
+    string: str | None = None
+    text: str = ''
+    html: str = ''
+
+    def find(
+        self, name: str | None = None, attrs: dict[str, str] | None = None, string: str | None = None
+    ) -> 'Tag | None':
+        """Find the first descendant tag matching the criteria.
+
+        Args:
+            name: Tag name to match, e.g. `'a'`, `'div'`.
+            attrs: Attribute key-value pairs to filter on.
+            string: Match tags whose `.string` equals this value.
+
+        Returns:
+            The first matching `Tag`, or `None` if no match is found.
+        """
+        # bs4's types are horrible, this is the easiest work around
+        result = _parse(self.html).find(name, cast(Any, attrs), string=cast(Any, string))
+        if result is None:
+            return None
+        else:
+            return _from_beautifulsoup(result)
+
+    def find_all(
+        self,
+        name: str | re.Pattern[str] | None = None,
+        attrs: dict[str, str] | None = None,
+        string: str | None = None,
+        limit: int | None = None,
+    ) -> 'list[Tag]':
+        """Find all descendant tags matching the criteria.
+
+        Args:
+            name: Tag name or compiled regex to match.
+            attrs: Attribute key-value pairs to filter on.
+            string: Match tags whose `.string` equals this value.
+            limit: Stop after finding this many results.
+
+        Returns:
+            A list of matching `Tag` objects.
+        """
+        # bs4's types are horrible, this is the easiest work around
+        results = _parse(self.html).find_all(name, cast(Any, attrs), string=cast(Any, string), limit=limit)
+        return [_from_beautifulsoup(r) for r in results]
+
+    def select(self, selector: str) -> 'list[Tag]':
+        """Find all descendants matching a CSS selector.
+
+        Args:
+            selector: A CSS selector string, e.g. `'div.class > a'`.
+
+        Returns:
+            A list of matching `Tag` objects.
+        """
+        return [_from_beautifulsoup(r) for r in _parse(self.html).select(selector)]
+
+    def select_one(self, selector: str) -> 'Tag | None':
+        """Find the first descendant matching a CSS selector.
+
+        Args:
+            selector: A CSS selector string, e.g. `'div.class > a'`.
+
+        Returns:
+            The first matching `Tag`, or `None` if no match is found.
+        """
+        result = _parse(self.html).select_one(selector)
+        if result is None:
+            return None
+        return _from_beautifulsoup(result)
+
+    def get(self, key: str, default: str | None = None) -> str | list[str] | None:
+        """Get an attribute value by key.
+
+        Args:
+            key: The attribute name, e.g. `'href'`, `'class'`.
+            default: Value to return if the attribute is missing.
+
+        Returns:
+            The attribute value (a `str`, or `list[str]` for multi-valued
+            attributes like `class`), or `default` if not found.
+        """
+        return self.attrs.get(key, default)
+
+    def get_text(self, separator: str = '', strip: bool = False) -> str:
+        """Extract all text content within this tag.
+
+        Args:
+            separator: String inserted between text fragments.
+            strip: Whether to strip whitespace from each fragment.
+
+        Returns:
+            The concatenated text content.
+        """
+        return _parse(self.html).get_text(separator=separator, strip=strip)
+
+    def children(self) -> 'list[Tag | str]':
+        """Get the direct children of this tag.
+
+        Returns:
+            A list where each element is either a `Tag` or a `str`
+            (for navigable text nodes).
+        """
+        out: list[Tag | str] = []
+        for child in _parse(self.html).children:
+            if isinstance(child, BsTag):
+                out.append(_from_beautifulsoup(child))
+            else:
+                text = str(child)
+                if text:
+                    out.append(text)
+        return out
+
+
+# ------------------------------------------------------------------
+# Public helpers
+# ------------------------------------------------------------------
+
+
+def _from_beautifulsoup(element: BsTag) -> Tag:
+    """Convert a BeautifulSoup `Tag` into a Monty-compatible `Tag` dataclass."""
+    assert isinstance(element, BsTag), f'Expected a BeautifulSoup Tag, got {type(element)}'
+    string_val = element.string
+    return Tag(
+        name=element.name,
+        attrs=dict(element.attrs),
+        string=str(string_val) if string_val is not None else None,
+        text=element.get_text(),
+        html=str(element),
+    )
+
+
+def _parse(html: str) -> BsTag:
+    """Re-parse stored HTML into a BeautifulSoup tag.
+
+    If the HTML represents a full document the `BeautifulSoup` object
+    itself is returned (it behaves like a Tag).  Otherwise the first
+    child tag is returned so that `find`/`select` operate on the
+    correct element.
+    """
+    soup = BeautifulSoup(html, 'html.parser')
+    # If the html was a single tag, unwrap so searches are scoped correctly.
+    children = list(soup.children)
+    if len(children) == 1 and isinstance(children[0], BsTag):
+        return children[0]
+    return soup

package/ref-monty/examples/web_scraper/main.py

@@ -0,0 +1,193 @@
+import asyncio
+import re
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+import logfire
+import pydantic_core
+from pydantic_ai import Agent, ModelRequest, ModelRequestNode, UserPromptPart
+from pydantic_graph import End
+
+from pydantic_monty import Monty, MontyError, MontyRuntimeError, run_monty_async
+
+from .browser import start_browser
+from .external_functions import beautiful_soup
+from .sub_agent import RecordModels
+
+logfire.configure()
+logfire.instrument_pydantic_ai()
+
+THIS_DIR = Path(__file__).parent
+
+
+def _generate_stubs() -> str:
+    """Generate type stubs for external_functions.py using stubgen."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        subprocess.run(
+            ['uv', 'run', 'stubgen', 'external_functions.py', '--include-docstrings', '-o', tmpdir],
+            capture_output=True,
+            text=True,
+            cwd=THIS_DIR,
+            check=True,
+        )
+        return (Path(tmpdir) / 'external_functions.pyi').read_text()
+
+
+stubs = f"""
+{RecordModels.record_model_info_stub()}
+
+{_generate_stubs()}
+"""
+instrunctions = f"""
+You MUST return markdown with either a comment and python code to execute
+in a "```python" code block, or an explanation of your process to end.
+
+You MUST return only one code block to execute. DO NOT return multiple code blocks.
+
+You MUST use the `record_model_info` function to record information about every model you find.
+
+The runtime uses a restricted Python subset:
+- you cannot use the standard library except builtin functions and the following modules: `sys`, `typing`, `asyncio`
+- this means `json`, `collections`, `json`, `re`, `math`, `datetime`, `itertools`, `functools`, etc. are NOT available  use plain dicts, lists, and builtins instead
+- you cannot use third party libraries
+- you cannot define classes
+- the python executor is NOT a REPL, you must define all values each time you call python
+
+The last expression evaluated is the return value.
+
+You can use `print()` to get debug information while developing the code.
+
+Parallelism: use `asyncio.gather` to fire multiple calls at the same time instead of awaiting each one sequentially:
+
+You can use the following types functions and types:
+
+```python
+{stubs}
+```
+"""
+
+scrape_agent = Agent('gateway/anthropic:claude-sonnet-4-5', instructions=instrunctions)
+
+urls = {
+    'openai': 'https://developers.openai.com/api/docs/pricing',
+    'anthropic': 'https://platform.claude.com/docs/en/about-claude/pricing',
+    'groq': 'https://groq.com/pricing',
+}
+
+
+async def main(model: str):
+    url = urls[model]
+    prompt = f"""
+Get structured information including pricing data for all models from the following URL:
+
+{url}
+
+The HTML returned from this URL is too big for context, so make sure to process it with
+the functions provided or return a small snippet of the HTML to process.
+
+Ignore any deprecated models.
+"""
+
+    print_output: list[str] = []
+
+    def monty_print(_: Literal['stdout'], content: str):
+        print_output.append(content)
+
+    record_models = RecordModels()
+
+    async with start_browser() as browser:
+        async with scrape_agent.iter(prompt) as agent_run:
+            node = agent_run.next_node
+            while True:
+                while not isinstance(node, End):
+                    node = await agent_run.next(node)
+
+                extracted = ExtractCode.extract(node.data.output)
+                logfire.info(f'{extracted}')
+                if extracted.comment:
+                    print(f'LLM: {extracted.comment}')
+
+                if not extracted.code:
+                    print('done')
+                    break
+
+                try:
+                    with logfire.span('prepare monty', code=extracted.code):
+                        m = Monty(
+                            extracted.code,
+                            type_check=True,
+                            type_check_stubs=stubs,
+                        )
+                except MontyError as e:
+                    msg = f'Error Preparing Code: {e}'
+                    node = await agent_run.next(new_node(msg))
+                    continue
+
+                try:
+                    with logfire.span('running monty'):
+                        output = await run_monty_async(
+                            m,
+                            external_functions={
+                                'open_page': browser.open_page,
+                                'beautiful_soup': beautiful_soup,
+                                'record_model_info': record_models.record_model_info,
+                            },
+                            print_callback=monty_print,
+                        )
+                except MontyRuntimeError as e:
+                    msg = f'Error running code: {e.display()}'
+                else:
+                    msg = pydantic_core.to_json(output).decode()
+
+                if print_output:
+                    msg += f'\n\nPrint Output:\n---\n{"".join(print_output)}\n---'
+                    print_output.clear()
+                node = await agent_run.next(new_node(msg))
+
+        logfire.info('{models=}', models=record_models.models)
+
+
+def new_node(msg: str) -> ModelRequestNode[None, str]:
+    return ModelRequestNode(request=ModelRequest(instructions=instrunctions, parts=[UserPromptPart(content=msg)]))
+
+
+@dataclass
+class ExtractCode:
+    """Extract Python code from an LLM response.
+
+    Priority:
+    1. First ```python code fence
+    2. First code fence of any language
+    3. Entire response as-is
+    """
+
+    code: str | None
+    """Code extract from response.
+
+    First ```(python|py) code fence, or first unexplained
+
+    """
+    comment: str | None
+
+    @classmethod
+    def extract(cls, response: str) -> ExtractCode:
+        # Try ```python or ```py fences first
+        m = re.search(r'```(?:python|py)\s*\n(.*?)```', response, re.DOTALL)
+        if not m:
+            # Try any code fence
+            m = re.search(r'```\w*\s*\n(.*?)```', response, re.DOTALL)
+
+        if m:
+            code = m.group(1).strip()
+            # Extract comment as text before the code fence
+            comment = response[: m.start()].strip() or None
+            return cls(code=code, comment=comment)
+
+        return cls(code=None, comment=response.strip())
+
+
+if __name__ == '__main__':
+    asyncio.run(main('anthropic'))