Requirements Library: Create python_plotting_requirements() factory function

[akihikokuroda]

Implement the python_plotting_requirements() factory function that bundles python_tool_requirements() with matplotlib-specific requirements.

Implementation

• Create in mellea/stdlib/requirements/plotting/matplotlib.py
• Accept output_path and allowed_imports parameters

Tests & Documentation

• Comprehensive docstring with Args, Returns, Raises, Examples sections
• Test factory returns correct bundled requirements
• Test parameter propagation and edge cases

Part of #1023

[akihikokuroda]

Design Based on PR #1040 Code Review

Context: Prior Attempt & Feedback

PR #1040 attempted to create python_plotting_requirements() factory. Key feedback:

Jake LoRocco:

• "Is there a reason that these requirements aren't appended as actual requirements... If possible, I think the preferred way would be: m.instruct(<description>, <requirements>, <sampling_strategy>"
• Factory should export a list of Requirement objects, not a bundled class
• Should integrate cleanly with Mellea's standard validation patterns

Fundamental Design Question:

• The PR used a bundled factory class pattern, but Mellea prefers composable lists of requirements
• Bundled pattern introduced new notation ("completely new class / notation")
• Better to return simple list that works with existing infra

Recommended Design for Task #1122

1. Factory Function Signature

def python_plotting_requirements(
    output_path: str,
    allowed_imports: list[str] | None = None,
) -> list[Requirement]:
    """Returns requirements for matplotlib plotting code generation.
    
    Validates:
    - All python_tool_requirements (code quality, execution)
    - Headless backend is configured
    - Plot is saved to output_path
    - matplotlib/numpy dependencies present
    
    Args:
        output_path: Where the plot should be saved (enables repair feedback).
        allowed_imports: Whitelist of allowed top-level module imports.
    
    Returns:
        List of Requirement objects for use with Mellea sampling strategies.
    
    Example:
        >>> from mellea.stdlib.requirements import python_plotting_requirements
        >>> reqs = python_plotting_requirements(output_path="/tmp/plot.png")
        >>> # Use with sampling: sampling=Sampling(requirements=reqs)
    """
    # Start with base Python tool requirements
    requirements = python_tool_requirements(
        allowed_imports=allowed_imports,
        output_limit_chars=10000,
        timeout_seconds=5,
        use_sandbox=False,
    )
    
    # Add plotting-specific requirements
    requirements.extend([
        MatplotlibHeadlessBackend(),
        PlotFileSaved(output_path=output_path),
        PlotDependenciesAvailable(),
    ])
    
    return requirements

2. Integration with Mellea Patterns

The factory returns a simple list, so it works with existing infrastructure:

from mellea.stdlib.requirements import python_plotting_requirements
from mellea.stdlib.components import Sampling

# Create requirements
reqs = python_plotting_requirements(output_path="/tmp/scatter.png")

# Use with sampling (standard Mellea pattern)
sampling = Sampling(requirements=reqs)

# Use with generation (standard Mellea pattern)
response = await backend.agenerate(
    prompt="Generate Python code for a scatter plot",
    sampling=sampling,
)

No new bundled class needed — just a factory function returning a list.

3. Key Design Decisions

1. Returns list, not custom class: Composition over new abstractions

   • Works with existing Sampling infrastructure
   • No new notation/class to learn
   • Aligns with Mellea's design philosophy

2. Builds on python_tool_requirements(): Composable design

   • Reuses base Python validation (code extraction, syntax, execution)
   • Adds plotting-specific validation on top
   • Both factories return lists that can be mixed/matched

3. Stores output_path: Enables repair feedback

   • Passed to PlotFileSaved for correct error messages
   • Allows post-execution validation (file exists?)
   • Improves repair guidance for models

4. Optional import restrictions: Pass through from caller

   • If allowed_imports=None, no restriction applied
   • If allowed_imports=['matplotlib', 'numpy'], only those allowed
   • Filters are composed naturally in requirement list

4. Example Usage Scenarios

Scenario 1: Generic plotting

reqs = python_plotting_requirements(output_path="/tmp/plot.png")
# Gets all 8 requirements (5 from python_tool + 3 plotting)

Scenario 2: Restricted imports

reqs = python_plotting_requirements(
    output_path="/tmp/plot.png",
    allowed_imports=["matplotlib", "numpy", "pandas"],
)
# Gets all requirements + import restriction applied

Scenario 3: Mix and match

# Create custom list by composing factories
reqs = python_tool_requirements(output_limit_chars=5000)
reqs.extend([
    MatplotlibHeadlessBackend(),
    PlotFileSaved(output_path="/tmp/plot.png"),
    # Skip PlotDependenciesAvailable if already known to be available
])

5. Export & Integration

Update mellea/stdlib/requirements/__init__.py:

from .plotting.matplotlib import (
    MatplotlibHeadlessBackend,
    PlotFileSaved,
    PlotDependenciesAvailable,
    python_plotting_requirements,
)

__all__ = [
    # ... existing exports ...
    "MatplotlibHeadlessBackend",
    "PlotFileSaved", 
    "PlotDependenciesAvailable",
    "python_plotting_requirements",
]

Update mellea/stdlib/requirements/plotting/__init__.py:

from .matplotlib import (
    MatplotlibHeadlessBackend,
    PlotFileSaved,
    PlotDependenciesAvailable,
    python_plotting_requirements,
)

__all__ = [
    "MatplotlibHeadlessBackend",
    "PlotFileSaved",
    "PlotDependenciesAvailable",
    "python_plotting_requirements",
]

Testing Strategy

• Test factory returns correct list of requirement instances
• Test parameter propagation to bundled requirements
• Test that list can be used directly with Sampling
• Test edge cases (missing output_path, empty allowed_imports)
• Integration test: factory output works end-to-end with sampling loop