diff --git a/docs/docs/examples/index.md b/docs/docs/examples/index.md index f5a49a2e99..ffa7fdc05c 100644 --- a/docs/docs/examples/index.md +++ b/docs/docs/examples/index.md @@ -62,7 +62,7 @@ to run. | Category | What it shows | | -------- | ------------- | -| `requirements/` | String and functional validation requirements, custom predicate functions, and validation repair | +| `requirements/` | String and functional validation requirements, custom predicate functions, and validation repair; validating code generation and plotting with execution tiers and security policies | | `intrinsics/` | [Guardian adapter functions](../how-to/safety-guardrails.md): `guardian_check()` for harm, jailbreak, social bias, groundedness; `policy_guardrails()`; `factuality_detection()` / `factuality_correction()` | | `safety/` | *(Examples removed — see [Guardian how-to guide](../how-to/safety-guardrails.md) for the current API. The `RepairTemplateStrategy` gap is tracked in [#1071](https://github.com/generative-computing/mellea/issues/1071).)* | @@ -80,7 +80,7 @@ to run. | Category | What it shows | | -------- | ------------- | -| `sampling/` | Pre-packaged sampling presets and custom rejection sampling configurations | +| `sampling/` | Pre-configured sampling presets for Python code generation and data plotting | | `aLora/` | Training aLoRA adapters for fast constraint checking; performance optimisation | | `intrinsics/` | *(Non-Guardian)* Answer relevance, hallucination detection, citation validation — specialised adapter-backed checks. For Guardian safety functions see [Safety and validation](#safety-and-validation) above | | `granite-switch/` | Running adapter functions via OpenAI backend with Granite Switch embedded adapters | diff --git a/docs/examples/agents/README.md b/docs/examples/agents/README.md index e105b96437..034e685b37 100644 --- a/docs/examples/agents/README.md +++ b/docs/examples/agents/README.md @@ -1,39 +1,14 @@ # Agent Examples -This directory contains examples of implementing agent patterns with Mellea, specifically the ReACT (Reasoning and Acting) pattern. +Examples demonstrating agent architectures and the ReACT (Reasoning and Acting) loop in Mellea. -## Files +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. -### [react.py](./react/react_from_scratch/react.py) -A complete implementation of the ReACT agent pattern that combines reasoning and action in an iterative loop. The agent: -- Thinks about what to do next -- Selects an appropriate tool/action -- Generates arguments for the tool -- Observes the result -- Determines if the goal is achieved +## Examples -**Key Features:** -- Custom `ReactTool` and `ReactToolbox` classes for tool management -- Dynamic tool selection using Pydantic schemas -- Iterative thought-action-observation loop -- Example with weather lookup tools - -**Usage:** -```python -python docs/examples/agents/react/react_from_scratch/react.py -``` - -### [react_instruct.py](./react/react_from_scratch/react_instruct.py) -An alternative implementation of the ReACT pattern using Mellea's instruct-validate-repair paradigm. - -## Concepts Demonstrated - -- **Tool Management**: Creating and organizing tools for agent use -- **Dynamic Prompting**: Building system prompts with tool descriptions -- **Chat Context**: Using `ChatContext` for multi-turn conversations -- **Structured Output**: Using Pydantic models for type-safe responses -- **Iterative Reasoning**: Implementing thought-action-observation loops - -## Related Documentation - -- See `mellea/stdlib/requirements/tool_reqs.py` for tool requirements \ No newline at end of file +| File | Description | +| :--- | :--- | +| [`react/react_using_mellea.py`](./react/react_using_mellea.py) | ReACT agent using Mellea's stdlib `react()` framework with LangChain tool integration. Needs `langchain-community` and `ddgs`. | +| [`react/react_from_scratch/react.py`](./react/react_from_scratch/react.py) | A complete implementation of the ReACT agent pattern that combines reasoning and action in an iterative loop. | +| [`react/react_from_scratch/react_instruct.py`](./react/react_from_scratch/react_instruct.py) | An alternative implementation of the ReACT pattern using Mellea's instruct-validate-repair paradigm. | diff --git a/docs/examples/agents/react/react_from_scratch/react.py b/docs/examples/agents/react/react_from_scratch/react.py index b42e798ab3..476fc8686f 100644 --- a/docs/examples/agents/react/react_from_scratch/react.py +++ b/docs/examples/agents/react/react_from_scratch/react.py @@ -1,4 +1,16 @@ # pytest: ollama, e2e, qualitative +"""ReACT agent implementation built from scratch. + +Demonstrates implementing the ReACT (Reasoning and Acting) loop from first +principles, combining tool selection, argument generation, and observation. + +Prerequisites: + ollama serve + ollama pull granite4.2:3b + +Usage: + uv run python docs/examples/agents/react/react_from_scratch/react.py +""" import datetime import inspect diff --git a/docs/examples/agents/react/react_from_scratch/react_instruct.py b/docs/examples/agents/react/react_from_scratch/react_instruct.py index 694d998c53..bcee399267 100644 --- a/docs/examples/agents/react/react_from_scratch/react_instruct.py +++ b/docs/examples/agents/react/react_from_scratch/react_instruct.py @@ -1,4 +1,16 @@ # pytest: ollama, e2e, qualitative +"""ReACT agent using instruct-validate-repair. + +Demonstrates implementing the ReACT (Reasoning and Acting) loop using Mellea's +instruct-validate-repair paradigm for robust tool calling and reasoning. + +Prerequisites: + ollama serve + ollama pull granite4.2:3b + +Usage: + uv run python docs/examples/agents/react/react_from_scratch/react_instruct.py +""" import datetime import inspect diff --git a/docs/examples/agents/react/react_using_mellea.py b/docs/examples/agents/react/react_using_mellea.py index 422e8f3e54..cbb6b16096 100644 --- a/docs/examples/agents/react/react_using_mellea.py +++ b/docs/examples/agents/react/react_using_mellea.py @@ -1,6 +1,17 @@ # pytest: ollama, e2e, qualitative, slow +"""React examples using the Mellea library's framework. -"""React examples using the Mellea library's framework.""" +Demonstrates the ReACT (Reasoning and Acting) loop with tool integration, +using Mellea's stdlib react() function and LangChain tool interoperability. + +Prerequisites: + uv pip install langchain-community ddgs + ollama serve + ollama pull granite4.2:3b + +Usage: + uv run python docs/examples/agents/react/react_using_mellea.py +""" import asyncio diff --git a/docs/examples/sampling/README.md b/docs/examples/sampling/README.md new file mode 100644 index 0000000000..c29f85db9c --- /dev/null +++ b/docs/examples/sampling/README.md @@ -0,0 +1,14 @@ +# Sampling Examples + +Pre-configured sampling presets for constrained generation tasks. A preset bundles +a set of requirements with a repair strategy so a common task works in one call — +as an alternative to assembling requirements individually. See +[`requirements/`](../requirements/README.md) for the lower-level building blocks +these presets wrap. + +## Examples + +| File | Description | +| :--- | :--- | +| [`python_code_generation_preset.py`](./python_code_generation_preset.py) | Python code generation preset bundling extraction, syntax, and import requirements with automatic repair feedback. By default (`use_sandbox=False`) generated code is parsed but not executed, and imports are checked only when `allowed_imports` is set. Pass `use_sandbox=True` to run it in Docker. | +| [`python_plotting_preset.py`](./python_plotting_preset.py) | Matplotlib plotting preset bundling headless backend configuration and savefig() output validation. Most examples in this file override the default to `use_sandbox=False` (static validation); `example_without_output_path` uses the sandbox default and requires Docker. | diff --git a/docs/examples/sampling/python_code_generation_preset.py b/docs/examples/sampling/python_code_generation_preset.py index 1b2296abcf..1732ccf3f2 100644 --- a/docs/examples/sampling/python_code_generation_preset.py +++ b/docs/examples/sampling/python_code_generation_preset.py @@ -11,6 +11,17 @@ 4. Import restrictions (optional allowlist) 5. Output size limits 6. Model-friendly repair feedback for each failure type + +By default (`use_sandbox=False`) the generated code is parsed but not executed, +and imports are checked only when `allowed_imports` is set. Pass +`use_sandbox=True` to run the code in a Docker sandbox instead. + +Prerequisites: + ollama serve + ollama pull granite4.2:3b + +Usage: + uv run python docs/examples/sampling/python_code_generation_preset.py """ import mellea diff --git a/docs/examples/sampling/python_plotting_preset.py b/docs/examples/sampling/python_plotting_preset.py index 72c9e6dbc5..dbdb6a10fa 100644 --- a/docs/examples/sampling/python_plotting_preset.py +++ b/docs/examples/sampling/python_plotting_preset.py @@ -16,6 +16,21 @@ - loop_budget=3 (vs. 2 for code generation) - use_sandbox=True (vs. False for code generation) - timeout_seconds=10 (vs. 5 for code generation) + +Most examples in this file override the default with `use_sandbox=False`, so the +generated code is parsed but not executed, and imports are checked only when +`allowed_imports` is set. The exception is `example_without_output_path`, which +keeps the sandbox default and needs a running Docker daemon. The default +llm-sandbox image is amd64-only, so that example may not pass on Apple Silicon. + +Prerequisites: + uv sync --extra sandbox + uv pip install matplotlib numpy + ollama serve + ollama pull granite4.2:3b + +Usage: + uv run python docs/examples/sampling/python_plotting_preset.py """ import tempfile @@ -33,7 +48,7 @@ def example_scatter_plot(): The preset ensures: 1. matplotlib.use('Agg') is called for headless rendering 2. plt.savefig(output_path) is called with the specified path - 3. Code executes without errors in isolated sandbox + 3. Code parses without errors (static validation, since `use_sandbox=False`) """ session = mellea.start_session() @@ -91,6 +106,16 @@ def example_without_output_path(): Demonstrates using the preset when you don't care about a specific output path. The preset validates that matplotlib dependencies are available but doesn't enforce a specific savefig() call. + + Note: this is the only function in this file that uses the plotting preset's + sandbox default (`use_sandbox=True`). It requires a running Docker daemon and + `mellea[sandbox]` installed (`uv sync --extra sandbox`). The default sandbox + image (`ghcr.io/vndee/sandbox-python-311-bullseye`) ships matplotlib, so the + example can pass as shipped — provided Docker is available and the image runs + on your architecture (the image is amd64-only). If Docker is unavailable, the + run reports `Valid: X/Y` with the unmet requirement listed as "sandbox + execution with policy", and the script still prints "✓ completed" because it + does not check the sampling result. """ session = mellea.start_session() @@ -153,7 +178,7 @@ def example_with_custom_parameters(): Demonstrates fine-tuning the preset's parameters: - loop_budget: More repair attempts for complex plots - timeout_seconds: Longer timeout for rendering-heavy plots - - use_sandbox: Keep sandbox enabled for security + - use_sandbox: Disabled here so the example runs without Docker """ session = mellea.start_session()