superacli 1.1.4 → 1.1.6

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

@@ -0,0 +1,117 @@
+# 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

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

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

@@ -0,0 +1,3 @@
+# 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

@@ -0,0 +1,124 @@
+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

@@ -0,0 +1,115 @@
+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

@@ -0,0 +1,20 @@
+# 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

@@ -0,0 +1,129 @@
+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

@@ -0,0 +1,81 @@
+"""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

@@ -0,0 +1,82 @@
+"""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