[rafvasq]

Pull Request

Issue

Towards #1746

Docstrings

• Kept the original titles and descriptions. Added docstrings to those which had none.
• Added Prerequisites: and Usage: blocks.
• Clarified sandbox behaviour in examples.

READMEs

• New sampling/README.md: defines a preset, links to requirements/, and has an ## Examples table.
• agents/README.md: a short description and an ## Examples table.

Other fixes

• react_using_mellea.py: documented the langchain-community and ddgs dependencies.
• Fixed function docstrings in python_plotting_preset.py that described sandboxed execution while passing use_sandbox=False.

Testing

• Tests added to the respective file if code was changed
• New code has 100% coverage if code was added
• Ensure existing tests and github automation passes (a maintainer will kick off the github automation when the rest of the PR is populated)

Attribution

• AI coding assistants used

---

Adding a new component, requirement, sampling strategy, or tool?

If your PR adds or modifies one of the types below, check the matching box. A checklist of type-specific review items will be posted as a comment.

• Component
• Requirement
• Sampling Strategy
• Tool

NOTE: Please ensure you have an issue that has been acknowledged by a core contributor and routed you to open a pull request against this repository. Otherwise, please open an issue before continuing with this pull request.

[planetf1]

Useful docs-only change: it makes sampling/ and the stdlib react() example discoverable, and the READMEs and index rows match the source. I ran both sampling examples against Ollama and they run. Three non-blocking points below, plus one follow-up suggestion.

Separately, not for this PR: presets.py:220 tells users to run uv sync --extra plotting, but no such extra exists in pyproject.toml.

[planetf1]

"Execution requirements" and "sandbox execution" read as if the generated code is run. In these examples it mostly isn't. With use_sandbox=False the tier is static, which only parses and import-checks (python_tools.py:424). That is the code-generation default and what four of the five plotting examples use. Suggest wording like "validates generated code, with optional Docker-sandboxed execution". Same wording at python_code_generation_preset.py:5 and python_plotting_preset.py:6.

Follow-up, not for this PR: the examples show the validate-and-repair loop but never execute generated code, so timeout_seconds, output_limit_chars and the savefig output aren't exercised. A real example with use_sandbox=True that runs the code and checks the result would show the preset's main value. A couple of docstrings still describe sandboxed behaviour too (python_plotting_preset.py:26 and :147).

[rafvasq]

Fixed to be more specific about sandbox use.

[planetf1]

Partially fixed, thanks. The README rows and both module docstrings now separate static validation from Docker execution, which reads well.

Two docstrings from my original comment are still unchanged: python_plotting_preset.py:38 says "Code executes without errors in isolated sandbox" while :45 passes use_sandbox=False, and :166 says "use_sandbox: Keep sandbox enabled for security" directly above use_sandbox=False at :177.

One wording issue in the new text: "import-check" overstates the default. With allowed_imports=None the bundle appends NoImportRestrictions, and StaticAnalysisEnvironment only checks imports when an allowlist is set (interpreter.py:257), so the default is parse-only. This affects python_code_generation_preset.py:5 and :8-9, python_plotting_preset.py:9-10, and the README's codegen row. "Parses the code, and checks imports when allowed_imports is set" would match the behaviour.

[rafvasq]

Thanks! I've fixed both docstrings and replaced the "import-check" wording in both module docstrings and the README codegen row.

[planetf1]

These examples need a running Ollama with the default model (granite4.2:3b), and the plotting ones need matplotlib, which isn't in any extra. example_without_output_path is the only one that runs generated code in Docker, so it also needs llm-sandbox (mellea[sandbox]), a running Docker daemon, and a sandbox image that runs on your machine. The default image is amd64-only, which can matter on Apple Silicon. A short prerequisites line would help.

It would also help that, when the sandbox can't run, the failure is hard to spot. The run reports Valid: 5/6 with the unmet requirement shown only as "sandbox execution with policy", and the underlying error never appears in the output. The script still prints "✓ completed", because it doesn't check the sampling result.

[rafvasq]

Updated the scripts to include ollama and dependency install commands in their Prerequisites. I think this helps towards keeping the examples self-contained and in case future examples are added under this directory that may not need the same prerequisites.

[planetf1]

Partially fixed. I walked through these as someone running the examples fresh:

1. ollama pull is listed before ollama serve, but pull needs the server up. Worth phrasing for users running Ollama as a service or via the desktop app too, e.g. "Ollama running (service, desktop app, or ollama serve), then ollama pull granite4.2:3b".
2. pip install matplotlib numpy beside a uv run Usage line is a trap: uv-managed venvs don't include pip, and a system pip installs into a different environment than uv run uses. uv pip install matplotlib numpy is the drop-in fix. (A plotting extra would also fix the --extra plotting reference in presets.py:220, but that's a follow-up.)
3. The plotting module's Prerequisites are incomplete for its own Usage line: running the module executes main(), which includes example_without_output_path, so it needs Docker and uv sync --extra sandbox. Those are only in that function's docstring. The amd64-only default sandbox image note is also still missing; on Apple Silicon that example can't pass as shipped even with Docker running, and the preset installs no packages into the container, so matplotlib may be missing there too.

On failure visibility: the docstring note is good, but the behaviour is unchanged. A newcomer sees four check lines, a Valid: 5/6 buried in the output, then a completed message, and reasonably concludes everything passed. SamplingResult.success exists (core/sampling.py:41), so checking it before printing a pass would close the gap. If documenting rather than fixing is preferred, I'd drop "fails silently" in the note, since the next sentence describes exactly what is reported.

P.S. while checking model tags: requirements/README.md:31 says ollama pull granite4.1:3b, but its examples use the default session, which is granite4.2:3b (session.py:271). Anyone following that README pulls the wrong 2 GB model and then triggers an auto-pull of the right one.

[rafvasq]

I reordered to ollama serve/ollama pull across all five scripts and switched to uv pip install matplotlib numpy.

The plotting module's Prerequisites now include uv sync --extra sandbox, and the docstring notes the Docker requirement and the amd64-only image.

On failure visibility, I went with the second option for this PR and dropped the "fails silently" message. The --extra plotting hint is tracked in the issue I opened #1763.

[planetf1]

The new Usage line can't work on a base install: the file imports langchain_community at :15, which only exists in the test extra (pyproject.toml:148). The documented command fails with an ImportError before reaching the inline comment at :23 that mentions the dependency. A Prerequisites block would fix it (uv pip install langchain-community ddgs). The other two react examples run on base deps but need Ollama with granite4.2:3b, and neither got a Prerequisites block, unlike the sampling files in this PR.

[rafvasq]

Added Prerequisites block to react_using_mellea.py and the README row also notes the two deps. The two react_from_scratch examples now have Prerequisites blocks too.

[planetf1]

The table reads clean, but a newcomer can't tell which row to start with, and the first row is the one needing an extra dependency. One sentence above the table would fix it, e.g. "Start with react_using_mellea.py for the shortest path; the react_from_scratch/ examples build the same loop by hand to show what the framework does for you." Separately, the old README's pointer to mellea/stdlib/requirements/tool_reqs.py was dropped. The react examples don't use it and tools/README.md:256 still points there, so this is fine if deliberate, just confirming it was a choice.

[rafvasq]

Added a line for starters.