superacli 1.1.5 → 1.1.7

package/ref-monty/docs/usage-guide.md

@@ -1,117 +0,0 @@
-# Monty Usage Guide
-
-Monty is a minimal, secure Python interpreter written in Rust, designed specifically for running untrusted code generated by AI agents.
-
-## Core Concepts
-
-### 1. Sandboxing
-Monty is a "strict sandbox" by default. It has NO access to:
-- Filesystem
-- Network
-- Environment variables
-- Subprocesses
-
-All interactions with the host must be explicitly provided via **External Functions**.
-
-### 2. Startup Latency
-Monty starts in microseconds (<1μs for basic code), making it ideal for embedding in low-latency agent loops where a full container or WASM runtime would be too slow.
-
-### 3. Snapshotting
-You can "pause" Monty at any external function call, serialize its state (`dump()`), and "resume" it later (`load()`), even in a different process.
-
----
-
-## Installation
-
-### Python
-```bash
-uv add pydantic-monty
-# or
-pip install pydantic-monty
-```
-
-### JavaScript / TypeScript
-```bash
-npm install @pydantic/monty
-```
-
----
-
-## Basic Usage
-
-### Python
-```python
-import pydantic_monty
-
-m = pydantic_monty.Monty("x + y", inputs=['x', 'y'])
-result = m.run(inputs={'x': 10, 'y': 20})
-print(result) # 30
-```
-
-### JavaScript
-```javascript
-import { Monty } from '@pydantic/monty'
-
-const m = new Monty('1 + 2')
-const result = m.run()
-console.log(result) // 3
-```
-
----
-
-## External Functions (Interacting with the Host)
-
-To let Python code "call back" to your host environment, provide functions in the `run` call.
-
-### Python Example
-```python
-def my_host_tool(n: int) -> int:
-    return n * 2
-
-result = m.run(
-    external_functions={'double': my_host_tool}
-)
-```
-
-### JavaScript Example
-```javascript
-const result = m.run({
-  externalFunctions: {
-    add: (a, b) => a + b,
-  },
-})
-```
-
----
-
-## Iterative Execution (Advanced)
-
-If you need to perform async operations or complex host logic, use `start()` and `resume()`.
-
-```python
-# Starts execution until it hits an external function
-progress = m.start(inputs={'url': 'https://example.com'})
-
-if isinstance(progress, pydantic_monty.FunctionSnapshot):
-    print(f"Calling {progress.function_name} with {progress.args}")
-    # Resume with a value from the host
-    progress = progress.resume(return_value="response data")
-
-print(progress.output)
-```
-
----
-
-## Resource Limits
-
-Prevent infinite loops or memory exhaustion:
-
-```python
-result = m.run(
-    limits={
-        'max_duration_secs': 5,
-        'max_memory': 1024 * 1024, # 1MB
-        'max_recursion_depth': 100
-    }
-)
-```

package/ref-monty/examples/README.md

@@ -1,3 +0,0 @@
-# Monty Examples
-
-Numerous examples of what monty can do, and how.

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

@@ -1,3 +0,0 @@
-# Team Expense Analysis
-
-From [this](https://platform.claude.com/cookbook/tool-use-programmatic-tool-calling-ptc#understanding-the-third-party-api) Anthropic example.

package/ref-monty/examples/expense_analysis/data.py

@@ -1,124 +0,0 @@
-from typing import Any
-
-team_members = [
-    {'id': 1, 'name': 'Alice Chen'},
-    {'id': 2, 'name': 'Bob Smith'},
-    {'id': 3, 'name': 'Carol Jones'},
-    {'id': 4, 'name': 'David Kim'},
-    {'id': 5, 'name': 'Eve Wilson'},
-]
-
-# Simulated expense data (multiple line items per person to bloat traditional context)
-expenses = {
-    1: [  # Alice - under budget
-        {'date': '2024-07-15', 'amount': 450.00, 'description': 'Flight to NYC'},
-        {'date': '2024-07-16', 'amount': 200.00, 'description': 'Hotel NYC'},
-        {'date': '2024-07-17', 'amount': 85.00, 'description': 'Meals NYC'},
-        {'date': '2024-08-20', 'amount': 380.00, 'description': 'Flight to Chicago'},
-        {'date': '2024-08-21', 'amount': 175.00, 'description': 'Hotel Chicago'},
-        {'date': '2024-09-05', 'amount': 520.00, 'description': 'Flight to Seattle'},
-        {'date': '2024-09-06', 'amount': 225.00, 'description': 'Hotel Seattle'},
-        {'date': '2024-09-07', 'amount': 95.00, 'description': 'Meals Seattle'},
-    ],
-    2: [  # Bob - over standard budget but has custom budget
-        {'date': '2024-07-01', 'amount': 850.00, 'description': 'Flight to London'},
-        {'date': '2024-07-02', 'amount': 450.00, 'description': 'Hotel London'},
-        {'date': '2024-07-03', 'amount': 125.00, 'description': 'Meals London'},
-        {'date': '2024-07-04', 'amount': 450.00, 'description': 'Hotel London'},
-        {'date': '2024-07-05', 'amount': 120.00, 'description': 'Meals London'},
-        {'date': '2024-08-10', 'amount': 780.00, 'description': 'Flight to Tokyo'},
-        {'date': '2024-08-11', 'amount': 380.00, 'description': 'Hotel Tokyo'},
-        {'date': '2024-08-12', 'amount': 380.00, 'description': 'Hotel Tokyo'},
-        {'date': '2024-08-13', 'amount': 150.00, 'description': 'Meals Tokyo'},
-        {'date': '2024-09-15', 'amount': 920.00, 'description': 'Flight to Singapore'},
-        {'date': '2024-09-16', 'amount': 320.00, 'description': 'Hotel Singapore'},
-        {'date': '2024-09-17', 'amount': 320.00, 'description': 'Hotel Singapore'},
-        {'date': '2024-09-18', 'amount': 180.00, 'description': 'Meals Singapore'},
-    ],
-    3: [  # Carol - way over budget (no custom budget)
-        {'date': '2024-07-08', 'amount': 1200.00, 'description': 'Flight to Paris'},
-        {'date': '2024-07-09', 'amount': 550.00, 'description': 'Hotel Paris'},
-        {'date': '2024-07-10', 'amount': 550.00, 'description': 'Hotel Paris'},
-        {'date': '2024-07-11', 'amount': 550.00, 'description': 'Hotel Paris'},
-        {'date': '2024-07-12', 'amount': 200.00, 'description': 'Meals Paris'},
-        {'date': '2024-08-25', 'amount': 1100.00, 'description': 'Flight to Sydney'},
-        {'date': '2024-08-26', 'amount': 480.00, 'description': 'Hotel Sydney'},
-        {'date': '2024-08-27', 'amount': 480.00, 'description': 'Hotel Sydney'},
-        {'date': '2024-08-28', 'amount': 480.00, 'description': 'Hotel Sydney'},
-        {'date': '2024-08-29', 'amount': 220.00, 'description': 'Meals Sydney'},
-        {'date': '2024-09-20', 'amount': 650.00, 'description': 'Flight to Denver'},
-        {'date': '2024-09-21', 'amount': 280.00, 'description': 'Hotel Denver'},
-    ],
-    4: [  # David - slightly under budget
-        {'date': '2024-07-22', 'amount': 420.00, 'description': 'Flight to Boston'},
-        {'date': '2024-07-23', 'amount': 190.00, 'description': 'Hotel Boston'},
-        {'date': '2024-07-24', 'amount': 75.00, 'description': 'Meals Boston'},
-        {'date': '2024-08-05', 'amount': 510.00, 'description': 'Flight to Austin'},
-        {'date': '2024-08-06', 'amount': 210.00, 'description': 'Hotel Austin'},
-        {'date': '2024-08-07', 'amount': 90.00, 'description': 'Meals Austin'},
-        {'date': '2024-09-12', 'amount': 480.00, 'description': 'Flight to Portland'},
-        {'date': '2024-09-13', 'amount': 195.00, 'description': 'Hotel Portland'},
-        {'date': '2024-09-14', 'amount': 85.00, 'description': 'Meals Portland'},
-    ],
-    5: [  # Eve - over standard budget (no custom budget)
-        {'date': '2024-07-03', 'amount': 680.00, 'description': 'Flight to Miami'},
-        {'date': '2024-07-04', 'amount': 320.00, 'description': 'Hotel Miami'},
-        {'date': '2024-07-05', 'amount': 320.00, 'description': 'Hotel Miami'},
-        {'date': '2024-07-06', 'amount': 145.00, 'description': 'Meals Miami'},
-        {'date': '2024-08-18', 'amount': 750.00, 'description': 'Flight to San Diego'},
-        {'date': '2024-08-19', 'amount': 290.00, 'description': 'Hotel San Diego'},
-        {'date': '2024-08-20', 'amount': 290.00, 'description': 'Hotel San Diego'},
-        {'date': '2024-08-21', 'amount': 130.00, 'description': 'Meals San Diego'},
-        {'date': '2024-09-08', 'amount': 820.00, 'description': 'Flight to Las Vegas'},
-        {'date': '2024-09-09', 'amount': 380.00, 'description': 'Hotel Las Vegas'},
-        {'date': '2024-09-10', 'amount': 380.00, 'description': 'Hotel Las Vegas'},
-        {'date': '2024-09-11', 'amount': 175.00, 'description': 'Meals Las Vegas'},
-    ],
-}
-
-# Custom budgets (only Bob has one)
-custom_budgets = {
-    2: {'amount': 7000.00, 'reason': 'International travel required'},
-}
-
-
-async def get_team_members(department: str) -> dict[str, Any]:
-    """Get list of team members for a department.
-
-    Args:
-        department: The department name (e.g., "Engineering").
-
-    Returns:
-        Dictionary with list of team members.
-    """
-    return {'department': department, 'members': team_members}
-
-
-async def get_expenses(user_id: int, quarter: str, category: str) -> dict[str, Any]:
-    """Get expense line items for a user.
-
-    Args:
-        user_id: The user's ID.
-        quarter: The quarter (e.g., "Q3").
-        category: The expense category (e.g., "travel").
-
-    Returns:
-        Dictionary with expense items.
-    """
-    items = expenses.get(user_id, [])
-    return {'user_id': user_id, 'quarter': quarter, 'category': category, 'expenses': items}
-
-
-async def get_custom_budget(user_id: int) -> dict[str, Any] | None:
-    """Get custom budget for a user if they have one.
-
-    Args:
-        user_id: The user's ID.
-
-    Returns:
-        Custom budget info or None if no custom budget.
-    """
-    budget_info = custom_budgets.get(user_id)
-    if budget_info:
-        return {'user_id': user_id, 'budget': budget_info['amount'], 'reason': budget_info['reason']}
-    return None

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

@@ -1,115 +0,0 @@
-import data
-
-import pydantic_monty
-
-type_definitions = '''
-from typing import Any
-
-async def get_team_members(department: str) -> dict[str, Any]:
-    """Get list of team members for a department.
-    Args:
-        department: The department name (e.g., "Engineering").
-    Returns:
-        Dictionary with list of team members.
-    """
-    ...
-
-async def get_expenses(user_id: int, quarter: str, category: str) -> dict[str, Any]:
-    """Get expense line items for a user.
-    Args:
-        user_id: The user's ID.
-        quarter: The quarter (e.g., "Q3").
-        category: The expense category (e.g., "travel").
-    Returns:
-        Dictionary with expense items.
-    """
-    ...
-
-async def get_custom_budget(user_id: int) -> dict[str, Any] | None:
-    """Get custom budget for a user if they have one.
-    Args:
-        user_id: The user's ID.
-    Returns:
-        Custom budget info or None if no custom budget.
-    """
-    ...
-'''
-
-code = """
-# Get Engineering team members
-team_data = await get_team_members(department="Engineering")
-team_members = team_data.get("members", [])
-
-# Standard budget
-STANDARD_BUDGET = 5000
-
-# Process each team member
-total_members = len(team_members)
-over_budget_list = []
-
-for member in team_members:
-    user_id = member.get("id")
-    name = member.get("name")
-
-    # Get Q3 travel expenses for this user
-    expenses_data = await get_expenses(user_id=user_id, quarter="Q3", category="travel")
-    expense_items = expenses_data.get("expenses", [])
-
-    # Sum up total expenses
-    total_spent = sum(item.get("amount", 0) for item in expense_items)
-
-    # Check if they exceeded standard budget
-    if total_spent > STANDARD_BUDGET:
-        # Check for custom budget
-        custom_budget_data = await get_custom_budget(user_id=user_id)
-
-        if custom_budget_data is not None:
-            budget = custom_budget_data.get("budget", STANDARD_BUDGET)
-        else:
-            budget = STANDARD_BUDGET
-
-        # Check if they exceeded their actual budget (standard or custom)
-        if total_spent > budget:
-            amount_over = total_spent - budget
-            over_budget_list.append({
-                "name": name,
-                "total_spent": total_spent,
-                "budget": budget,
-                "amount_over": amount_over
-            })
-
-# Return the analysis
-{
-    "total_team_members_analyzed": total_members,
-    "count_exceeded_budget": len(over_budget_list),
-    "over_budget_details": over_budget_list
-}
-"""
-
-
-m = pydantic_monty.Monty(
-    code,
-    inputs=['prompt'],
-    script_name='expense.py',
-    type_check=True,
-    type_check_stubs=type_definitions,
-)
-
-
-async def main():
-    output = await pydantic_monty.run_monty_async(
-        m,
-        inputs={'prompt': 'testing'},
-        external_functions={
-            'get_team_members': data.get_team_members,
-            'get_expenses': data.get_expenses,
-            'get_custom_budget': data.get_custom_budget,
-        },
-    )
-    print(output)
-
-
-if __name__ == '__main__':
-    import asyncio
-
-    asyncio.run(main())

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

@@ -1,20 +0,0 @@
-# SQL Playground: Customer Sentiment Analysis
-
-This example demonstrates using Monty for a task that **cannot be solved with a single SQL query**: analyzing customer purchase data (CSV) and correlating it with their social media sentiment (JSON tweets).
-
-Data is from <https://github.com/mafudge/datasets>.
-
-## Why This Example is Interesting
-
-1. **Cross-format data joining**: CSV customer data must join with JSON tweets via Twitter handle - requires programmatic data wrangling
-2. **Loop-based external calls**: Sentiment analysis for each tweet happens in a loop - with JSON tool calling this would flood the context window with 50+ results
-3. **In-sandbox computation**: Averages, correlation, and aggregation happen in Python - no need for the LLM to do mental math
-4. **Variable iteration**: Different customers have different numbers of tweets - code handles this naturally
-5. **File sandboxing**: Uses `OSAccess` to mount data files, demonstrating secure file access patterns
-6. **Type checking**: Validates LLM-generated code against type stubs before execution
-
-## To run
-
-```bash
-uv run python examples/sql_playground/main.py
-```

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

@@ -1,129 +0,0 @@
-from __future__ import annotations
-
-import json
-import tempfile
-from dataclasses import dataclass
-from pathlib import PurePosixPath
-from typing import Any
-
-from pydantic_monty import OSAccess
-
-try:
-    import duckdb
-except ImportError as e:
-    raise ImportError('duckdb is required for query_csv. Install with: pip install duckdb') from e
-
-
-@dataclass
-class ExternalFunctions:
-    fs: OSAccess
-
-    async def query_csv(
-        self, filepath: PurePosixPath, sql: str, parameters: dict[str, Any] | None = None
-    ) -> list[dict[str, Any]]:
-        """Execute SQL query on a CSV file using DuckDB.
-
-        Args:
-            filepath: Path to the CSV file in the virtual filesystem.
-            sql: SQL query to execute. The CSV data is available as a table named 'data'.
-            parameters: Optional dictionary of parameters to bind to the SQL query.
-
-        Returns:
-            List of dictionaries, one per row, with column names as keys.
-        """
-        # Read CSV content from virtual filesystem
-        content = self.fs.path_read_bytes(filepath)
-
-        # Write to a temporary file for DuckDB to read
-        # (DuckDB's read_csv_auto works best with file paths)
-        with tempfile.NamedTemporaryFile(mode='wb', suffix='.csv') as tmp:
-            tmp.write(content)
-            tmp.flush()
-
-            conn = duckdb.connect(':memory:')
-            # Create table from CSV
-            # NOTE! duckdb (horribly) reads locals as tables, hence `data` here that isn't used
-            data = conn.read_csv(tmp.name)
-            # Execute the user's query
-            result_rel = conn.execute(sql, parameters)
-            del data
-        # Get column names and rows, then convert to list of dicts
-        columns = [desc[0] for desc in result_rel.description]
-        rows = result_rel.fetchall()
-        return [dict(zip(columns, row)) for row in rows]
-
-    async def read_json(self, filepath: PurePosixPath) -> list[Any] | dict[str, Any]:
-        """Read and parse a JSON file from the virtual filesystem.
-
-        Args:
-            filepath: Path to the JSON file in the virtual filesystem.
-
-        Returns:
-            Parsed JSON data (list or dict).
-        """
-        content = self.fs.path_read_text(filepath)
-        return json.loads(content)
-
-    @staticmethod
-    async def analyze_sentiment(text: str) -> float:
-        """Analyze sentiment of text using simple keyword matching.
-
-        This is a basic sentiment analyzer that scores text based on
-        the presence of positive and negative keywords. For production use,
-        you would want to use a proper NLP library or API.
-
-        Args:
-            text: The text to analyze.
-
-        Returns:
-            Sentiment score from -1.0 (very negative) to +1.0 (very positive).
-            A score of 0.0 indicates neutral sentiment.
-
-        Example:
-            >>> await analyze_sentiment('This product is amazing!')
-            0.3
-        """
-        positive_words = [
-            'amazing',
-            'great',
-            'love',
-            'thank',
-            'helpful',
-            'a+',
-            'good',
-            'best',
-            'excellent',
-            'awesome',
-            'fantastic',
-            'wonderful',
-            'glad',
-            'enjoy',
-            'better',
-        ]
-        negative_words = [
-            'bad',
-            'angry',
-            'hate',
-            'terrible',
-            'worst',
-            'fraud',
-            'awful',
-            'horrible',
-            'disappointed',
-            'poor',
-            'useless',
-        ]
-
-        score = 0.0
-        text_lower = text.lower()
-
-        for word in positive_words:
-            if word in text_lower:
-                score += 0.3
-
-        for word in negative_words:
-            if word in text_lower:
-                score -= 0.3
-
-        # Clamp score to [-1, 1]
-        return max(-1.0, min(1.0, score))

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

@@ -1,81 +0,0 @@
-"""SQL Playground Example: Customer Sentiment Analysis with SQL and JSON."""
-
-from __future__ import annotations
-
-import asyncio
-from pathlib import Path
-
-from external_functions import ExternalFunctions
-
-import pydantic_monty
-from pydantic_monty import MemoryFile, OSAccess
-
-# Path to the mafudge datasets repository (adjust if needed)
-THIS_DIR = Path(__file__).parent
-REPO_ROOT = THIS_DIR.parent.parent
-MAFUDGE_DATASETS = (REPO_ROOT / '..' / 'mafudge_datasets').resolve()
-assert MAFUDGE_DATASETS.is_dir(), f'mafudge_datasets directory not found at {MAFUDGE_DATASETS}. '
-SANDBOX_CODE_PATH = THIS_DIR / 'sandbox_code.py'
-
-TYPE_STUBS = (THIS_DIR / 'type_stubs.pyi').read_text()
-SANDBOX_CODE = SANDBOX_CODE_PATH.read_text()
-
-# Read file contents
-customers_csv = (MAFUDGE_DATASETS / 'customers' / 'customers.csv').read_text()
-surveys_csv = (MAFUDGE_DATASETS / 'customers' / 'surveys.csv').read_text()
-tweets_json = (MAFUDGE_DATASETS / 'tweets' / 'tweets.json').read_text()
-
-# Create virtual filesystem with mounted files
-fs = OSAccess(
-    [
-        MemoryFile('/data/customers/customers.csv', content=customers_csv),
-        MemoryFile('/data/customers/surveys.csv', content=surveys_csv),
-        MemoryFile('/data/tweets/tweets.json', content=tweets_json),
-    ]
-)
-
-
-async def main():
-    """Run the customer sentiment analysis in the Monty sandbox.
-
-    Returns:
-        List of analysis results for top customers with sentiment scores.
-    """
-    # Set up the virtual filesystem with data files
-
-    # Create external functions that can access the filesystem
-    external_funcs = ExternalFunctions(fs)
-
-    # Create the Monty runner with type checking enabled
-    m = pydantic_monty.Monty(
-        SANDBOX_CODE_PATH.read_text(),
-        script_name='sql_playground.py',
-        type_check=True,
-        type_check_stubs=TYPE_STUBS,
-    )
-
-    # Run the analysis with external functions and OS access
-    results = await pydantic_monty.run_monty_async(
-        m,
-        external_functions={
-            'query_csv': external_funcs.query_csv,
-            'read_json': external_funcs.read_json,
-            'analyze_sentiment': external_funcs.analyze_sentiment,
-        },
-        os=fs,
-    )
-
-    if not results:
-        print('No results found. Check if customers have matching Twitter handles and tweets.')
-    for r in results:
-        sentiment_emoji = '😊' if r['avg_sentiment'] > 0 else '😐' if r['avg_sentiment'] == 0 else '😞'
-        print(f'  {r["name"]}')
-        print(f'    Purchases: ${r["total_purchases"]:,}')
-        print(f'    Twitter: @{r["twitter"]}')
-        print(f'    Tweets: {r["tweet_count"]}')
-        print(f'    Sentiment: {r["avg_sentiment"]:+.2f} {sentiment_emoji}')
-        print()
-
-
-if __name__ == '__main__':
-    asyncio.run(main())

package/ref-monty/examples/sql_playground/sandbox_code.py

@@ -1,82 +0,0 @@
-"""Sandboxed analysis code that runs inside Monty.
-
-This code is executed in the Monty sandbox with access to external functions
-for SQL queries, JSON parsing, and sentiment analysis.
-"""
-
-from pathlib import Path
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    from type_stubs import analyze_sentiment, query_csv, read_json
-
-
-async def main():
-    # Step 1: Query top 10 customers by total purchases
-    print('getting top customers...')
-    top_customers = await query_csv(
-        filepath=Path('/data/customers/customers.csv'),
-        sql="""
-        SELECT "First", "Last", "Email", "Total Purchased" as TotalPurchased
-        FROM data
-        ORDER BY "Total Purchased"
-        DESC LIMIT 10
-        """,
-    )
-
-    # Step 2: Get their Twitter handles from the survey data
-    emails: list[str] = [c['Email'] for c in top_customers]
-    print('getting twitter handles...')
-    twitter_handles = await query_csv(
-        Path('/data/customers/surveys.csv'),
-        f"""
-        SELECT "Email", "Twitter Username" as Twitter
-        FROM data
-        WHERE "Email" IN $emails
-        """,
-        parameters={'emails': emails},
-    )
-    email_to_twitter = {row['Email']: row['Twitter'] for row in twitter_handles}
-
-    # Step 3: Load all tweets
-    tweets = await read_json(filepath=Path('/data/tweets/tweets.json'))
-    assert isinstance(tweets, list)
-
-    print(f'processing {len(top_customers)} customers...')
-
-    # Step 4: For each customer, find their tweets and analyze sentiment
-    results: list[dict[str, object]] = []
-    for customer in top_customers:
-        twitter = email_to_twitter.get(customer['Email'])
-        if not twitter:
-            continue
-
-        # Find tweets by this user
-        user_tweets = [t for t in tweets if t['user'] == twitter]
-        if not user_tweets:
-            continue
-
-        # Analyze sentiment of each tweet
-        sentiments: list[float] = []
-        for tweet in user_tweets:
-            score = await analyze_sentiment(text=tweet['text'])
-            sentiments.append(score)
-
-        # Calculate average sentiment
-        avg_sentiment = sum(sentiments) / len(sentiments)
-        print(f'{customer["First"]} {customer["Last"]} - {avg_sentiment=}')
-
-        results.append(
-            {
-                'name': f'{customer["First"]} {customer["Last"]}',
-                'total_purchases': customer['TotalPurchased'],
-                'twitter': twitter,
-                'tweet_count': len(user_tweets),
-                'avg_sentiment': round(avg_sentiment, 2),
-            }
-        )
-        return results
-
-
-# Return the analysis results
-await main()  # pyright: ignore