Requirements Library: Create python_tool_requirements() factory function

[akihikokuroda]

Implement the python_tool_requirements() factory function that bundles the five generic requirements with configurable parameters.

Implementation

• Create in mellea/stdlib/requirements/python_tools.py
• Support allowed_imports, output_limit_chars, timeout_seconds, use_sandbox parameters

Tests & Documentation

• Comprehensive docstring with Args, Returns, Raises, Examples sections
• Test factory returns correct requirement instances
• Test parameter propagation and various configuration combinations

Part of #1023

[akihikokuroda]

Analysis: Utilize Existing PythonExecutionReq

Existing Infrastructure

The existing PythonExecutionReq class in python_reqs.py already provides:

• ✅ Code extraction (uses _has_python_code_listing)
• ✅ Configurable execution modes: static analysis, sandbox, unsafe
• ✅ Timeout configuration (default 5s)
• ✅ Import allowlisting support
• ✅ Error propagation with readable messages

Design for python_tool_requirements() Factory

The factory should bundle:

1. PythonCodeExtraction — wraps _has_python_code_listing
2. PythonSyntaxValid — NEW AST-based syntax validation
3. PythonExecutesWithoutError — reuse/wrap PythonExecutionReq
4. OutputSizeLimit — NEW output size constraint
5. ImportRestrictions — NEW import allowlist validation (optional)

Implementation Pattern

def python_tool_requirements(
    allowed_imports: list[str] | None = None,
    output_limit_chars: int = 10000,
    timeout_seconds: int = 5,
    use_sandbox: bool = False,
) -> list[Requirement]:
    """Returns requirements for safe Python tool code generation.
    
    Validates:
    - Code is extractable from output
    - Syntax is valid
    - Executes without errors
    - Output stays within limits
    - Imports restricted if allowlist provided
    
    Args:
        allowed_imports: Whitelist of allowed top-level module imports.
        output_limit_chars: Maximum characters of captured output.
        timeout_seconds: Maximum execution time.
        use_sandbox: If True, use Docker-based sandbox; if False, use static analysis.
    
    Returns:
        List of Requirement objects bundled for Python tool validation.
    """
    requirements: list[Requirement] = [
        PythonCodeExtraction(),
        PythonSyntaxValid(),
        PythonExecutesWithoutError(
            timeout=timeout_seconds,
            allow_unsafe_execution=not use_sandbox,
            allowed_imports=allowed_imports,
            use_sandbox=use_sandbox,
        ),
        OutputSizeLimit(limit_chars=output_limit_chars),
    ]
    
    if allowed_imports:
        requirements.append(ImportRestrictions(allowed_imports=allowed_imports))
    
    return requirements

Key Decisions

1. Reuse PythonExecutionReq: Don't reimplement; use existing class
2. Wrap vs Extend: Consider if we need a new PythonExecutesWithoutError class or if we can expose PythonExecutionReq under a better name
3. Optional Requirements: ImportRestrictions should be optional (only included if allowlist provided)
4. Parameter Mapping:
   • use_sandbox=True → passes use_sandbox=True to PythonExecutionReq
   • use_sandbox=False → passes use_sandbox=False to PythonExecutionReq
   • Note the semantic difference: allow_unsafe_execution parameter in PythonExecutionReq

Testing Strategy

• Test factory returns correct requirement instances
• Test parameter propagation to bundled requirements
• Test that all requirements work together in a sampling loop
• Edge cases: empty allowed_imports, zero timeout, max output_limit