dspy-rlm-hooks 0.1.2__tar.gz

dspy_rlm_hooks-0.1.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Edward Boswell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

dspy_rlm_hooks-0.1.2/PKG-INFO

@@ -0,0 +1,322 @@
+Metadata-Version: 2.4
+Name: dspy-rlm-hooks
+Version: 0.1.2
+Summary: Lifecycle instrumentation for DSPy's RLM (Recursive Language Model).
+Keywords: dspy,ai,recursive language model,hooks,instrumentation,rlm
+Author: Edward Boswell
+Author-email: Edward Boswell <thememium@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: OS Independent
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: dspy>=3.1.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Python: >=3.12
+Project-URL: Homepage, https://github.com/thememium/dspy-rlm-hooks
+Project-URL: Documentation, https://github.com/thememium/dspy-rlm-hooks
+Project-URL: Repository, https://github.com/thememium/dspy-rlm-hooks.git
+Project-URL: Issues, https://github.com/thememium/dspy-rlm-hooks/issues
+Project-URL: Changelog, https://github.com/thememium/dspy-rlm-hooks/blob/master/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+<a name="readme-top"></a>
+
+<div align="center">
+  <h3 align="center">DSPy RLM Hooks</h3>
+
+  <p align="center">
+    Lifecycle instrumentation for DSPy's RLM (Recursive Language Model).
+    <br />
+    <a href="#table-of-contents"><strong>Explore the Documentation »</strong></a>
+    <br />
+    <a href="https://github.com/thememium/dspy-rlm-hooks/issues">Report Bug</a>
+    ·
+    <a href="https://github.com/thememium/dspy-rlm-hooks/issues">Request Feature</a>
+  </p>
+</div>
+
+<!-- TABLE OF CONTENTS -->
+
+<a name="table-of-contents"></a>
+
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li><a href="#about">About</a></li>
+    <li><a href="#quick-start">Quick Start</a></li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#development">Development</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+<!-- ABOUT -->
+
+## About
+
+DSPy RLM Hooks injects **lifecycle hooks** into DSPy's internal `RLM` iteration loop, giving you full control over every stage of code generation, execution, and history tracking.
+
+- **Code Rewriting** — Fix or augment LLM-generated code before it runs
+- **Variable Injection** — Seed the interpreter with persistent variables and imports
+- **Result Auditing** — Transform, validate, or retry on errors
+- **History Management** — Inspect and modify the REPL history between iterations
+- **Sync & Async** — Hooks work in either mode; coroutines are auto-detected
+
+Requires **DSPy 3.1+** and **Pydantic 2+**.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- ARCHITECTURE -->
+
+## Architecture
+
+### RLM Hook Lifecycle
+
+```mermaid
+flowchart LR
+    subgraph Iteration["RLM Iteration"]
+        PreIter["pre_iteration_hook"] --> Gen["Generate Code"]
+        Gen --> PreExec["pre_execution_hook"]
+        PreExec --> Exec["Execute Code"]
+        Exec --> PostExec["post_execution_hook"]
+        PostExec --> PostIter["post_iteration_hook"]
+    end
+
+    PreIter -.->|inject vars, prepend code| Gen
+    PreExec -.->|rewrite code| Exec
+    PostExec -.->|transform result| PostIter
+```
+
+Hooks fire at each stage of an RLM iteration, allowing inspection and modification of behaviour.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- QUICK START -->
+
+## Quick Start
+
+### Install
+
+Install dspy-rlm-hooks with uv (recommended):
+
+```bash
+uv add dspy-rlm-hooks
+```
+
+Or with pip:
+
+```bash
+pip install dspy-rlm-hooks
+```
+
+### Basic Usage
+
+```python
+import dspy
+from dspy_rlm_hooks import enable_rlm_hooks, PreIterationOutput
+
+rlm = dspy.RLM(...)
+
+def inject_math(iteration, variables, history, input_args):
+    return PreIterationOutput(
+        extra_vars={"tool": "calculator"},
+        python_code="import math",
+    )
+
+enable_rlm_hooks(rlm, pre_iteration_hook=inject_math)
+
+result = rlm(question="What is the square root of 1764?")
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- USAGE -->
+
+## Usage
+
+### All Four Hooks
+
+A realistic example showing how each hook can be used to build a **safe, instrumented agent**:
+
+```python
+from dspy_rlm_hooks import (
+    enable_rlm_hooks,
+    PreIterationOutput,
+    PreExecutionOutput,
+    PostExecutionOutput,
+    PostIterationOutput,
+)
+from dspy.primitives.repl_types import REPLHistory
+import re
+
+# ── Pre-iteration: seed interpreter with a regex toolkit ──
+
+def pre_iteration(iteration, variables, history, input_args):
+    """Inject a regex helper and seed variables before every iteration."""
+    return PreIterationOutput(
+        extra_vars={"search_pattern": r"TODO|FIXME|HACK"},
+        python_code="""
+import re
+
+def grep(pattern, text):
+    return re.findall(pattern, text)
+""",
+    )
+
+# ── Pre-execution: block dangerous code ──
+
+FORBIDDEN = re.compile(r"\b(eval|exec|compile|__import__)\b")
+
+def pre_execution(iteration, code, variables, history, input_args):
+    """Sanitise generated code before it reaches the interpreter."""
+    if FORBIDDEN.search(code):
+        safe_code = FORBIDDEN.sub("# BLOCKED", code)
+        return PreExecutionOutput(code=safe_code)
+    return PreExecutionOutput(code=code)
+
+# ── Post-execution: retry on error ──
+
+def post_execution(iteration, code, result, variables, history, input_args):
+    """If execution raised an error, wrap a hint so the LLM retries next round."""
+    if isinstance(result, str) and result.startswith("[Error]"):
+        return PostExecutionOutput(
+            result=f"{result}\n# Hint: the variable 'search_pattern' is already in scope."
+        )
+    return PostExecutionOutput(result=result)
+
+# ── Post-iteration: enforce iteration budget ──
+
+MAX_ITERATIONS = 5
+current_iter_count = 0
+
+def post_iteration(iteration, pred, code, result, history: REPLHistory):
+    """Track iterations and stop early if the budget is exhausted."""
+    global current_iter_count
+    current_iter_count += 1
+    if current_iter_count >= MAX_ITERATIONS:
+        # Return empty history to signal stop
+        return PostIterationOutput(history=REPLHistory(entries=[]))
+    return PostIterationOutput(history=history)
+
+# ── Wire everything up ──
+
+enable_rlm_hooks(
+    rlm,
+    pre_iteration_hook=pre_iteration,
+    pre_execution_hook=pre_execution,
+    post_execution_hook=post_execution,
+    post_iteration_hook=post_iteration,
+)
+
+result = rlm(question="Find all TODO comments in the codebase")
+```
+
+### Async Hooks
+
+Return a coroutine and the system handles it automatically:
+
+```python
+async def fetch_context(iteration, variables, history, input_args):
+    context = await remote_cache.get(input_args["question"])
+    return PreIterationOutput(extra_vars={"cached_context": context})
+
+enable_rlm_hooks(rlm, pre_iteration_hook=fetch_context)
+```
+
+### Disabling Hooks
+
+```python
+from dspy_rlm_hooks import disable_rlm_hooks
+
+disable_rlm_hooks(rlm)
+```
+
+Removes all monkey-patched overrides and reverts to original behaviour.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Hook Reference
+
+| Hook | When it fires | What it can do |
+| --- | --- | --- |
+| **PreIteration** | Before action generation | Inject variables (`extra_vars`) and persistent code (`python_code`) |
+| **PreExecution** | After code generation, before running | Rewrite or sanitise the generated `code` string |
+| **PostExecution** | After code runs, before history processing | Transform, audit, or replace the raw `result` |
+| **PostIteration** | After result is folded into history | Save learnings, trigger side effects, or modify `history` |
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- DEVELOPMENT -->
+
+## Development
+
+### Code Quality
+
+This project uses several tools to maintain code quality:
+
+- **Ruff:** Linting and formatting
+- **isort:** Import sorting
+- **pytest:** Testing framework
+- **ty:** Type checking
+- **deptry:** Dependency analysis
+
+**Available commands:**
+
+```sh
+# Run all quality checks
+uv run poe clean-full
+
+# Individual checks
+uv run poe lint          # Ruff linting
+uv run poe format        # Ruff formatting
+uv run poe sort          # Import sorting
+uv run poe typecheck     # Type checking
+uv run poe deptry        # Dependency analysis
+```
+
+### Testing
+
+Run tests using pytest:
+
+```sh
+# Run all tests
+uv run pytest
+
+# Run specific test
+uv run pytest path/to/test.py::test_name
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- CONTRIBUTING -->
+
+## Contributing
+
+Quick workflow:
+
+1. Fork and branch: `git checkout -b feature/name`
+2. Make changes
+3. Run checks: `uv run poe clean-full`
+4. Commit and push
+5. Open a Pull Request
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- LICENSE -->
+
+## License
+
+MIT (as declared in `pyproject.toml`).
+
+---
+
+<div align="center">
+  <p>
+    <sub>Built by <a href="https://github.com/thememium">thememium</a></sub>
+  </p>
+</div>

dspy_rlm_hooks-0.1.2/README.md

@@ -0,0 +1,297 @@
+<a name="readme-top"></a>
+
+<div align="center">
+  <h3 align="center">DSPy RLM Hooks</h3>
+
+  <p align="center">
+    Lifecycle instrumentation for DSPy's RLM (Recursive Language Model).
+    <br />
+    <a href="#table-of-contents"><strong>Explore the Documentation »</strong></a>
+    <br />
+    <a href="https://github.com/thememium/dspy-rlm-hooks/issues">Report Bug</a>
+    ·
+    <a href="https://github.com/thememium/dspy-rlm-hooks/issues">Request Feature</a>
+  </p>
+</div>
+
+<!-- TABLE OF CONTENTS -->
+
+<a name="table-of-contents"></a>
+
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li><a href="#about">About</a></li>
+    <li><a href="#quick-start">Quick Start</a></li>
+    <li><a href="#usage">Usage</a></li>
+    <li><a href="#development">Development</a></li>
+    <li><a href="#contributing">Contributing</a></li>
+    <li><a href="#license">License</a></li>
+  </ol>
+</details>
+
+<!-- ABOUT -->
+
+## About
+
+DSPy RLM Hooks injects **lifecycle hooks** into DSPy's internal `RLM` iteration loop, giving you full control over every stage of code generation, execution, and history tracking.
+
+- **Code Rewriting** — Fix or augment LLM-generated code before it runs
+- **Variable Injection** — Seed the interpreter with persistent variables and imports
+- **Result Auditing** — Transform, validate, or retry on errors
+- **History Management** — Inspect and modify the REPL history between iterations
+- **Sync & Async** — Hooks work in either mode; coroutines are auto-detected
+
+Requires **DSPy 3.1+** and **Pydantic 2+**.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- ARCHITECTURE -->
+
+## Architecture
+
+### RLM Hook Lifecycle
+
+```mermaid
+flowchart LR
+    subgraph Iteration["RLM Iteration"]
+        PreIter["pre_iteration_hook"] --> Gen["Generate Code"]
+        Gen --> PreExec["pre_execution_hook"]
+        PreExec --> Exec["Execute Code"]
+        Exec --> PostExec["post_execution_hook"]
+        PostExec --> PostIter["post_iteration_hook"]
+    end
+
+    PreIter -.->|inject vars, prepend code| Gen
+    PreExec -.->|rewrite code| Exec
+    PostExec -.->|transform result| PostIter
+```
+
+Hooks fire at each stage of an RLM iteration, allowing inspection and modification of behaviour.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- QUICK START -->
+
+## Quick Start
+
+### Install
+
+Install dspy-rlm-hooks with uv (recommended):
+
+```bash
+uv add dspy-rlm-hooks
+```
+
+Or with pip:
+
+```bash
+pip install dspy-rlm-hooks
+```
+
+### Basic Usage
+
+```python
+import dspy
+from dspy_rlm_hooks import enable_rlm_hooks, PreIterationOutput
+
+rlm = dspy.RLM(...)
+
+def inject_math(iteration, variables, history, input_args):
+    return PreIterationOutput(
+        extra_vars={"tool": "calculator"},
+        python_code="import math",
+    )
+
+enable_rlm_hooks(rlm, pre_iteration_hook=inject_math)
+
+result = rlm(question="What is the square root of 1764?")
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- USAGE -->
+
+## Usage
+
+### All Four Hooks
+
+A realistic example showing how each hook can be used to build a **safe, instrumented agent**:
+
+```python
+from dspy_rlm_hooks import (
+    enable_rlm_hooks,
+    PreIterationOutput,
+    PreExecutionOutput,
+    PostExecutionOutput,
+    PostIterationOutput,
+)
+from dspy.primitives.repl_types import REPLHistory
+import re
+
+# ── Pre-iteration: seed interpreter with a regex toolkit ──
+
+def pre_iteration(iteration, variables, history, input_args):
+    """Inject a regex helper and seed variables before every iteration."""
+    return PreIterationOutput(
+        extra_vars={"search_pattern": r"TODO|FIXME|HACK"},
+        python_code="""
+import re
+
+def grep(pattern, text):
+    return re.findall(pattern, text)
+""",
+    )
+
+# ── Pre-execution: block dangerous code ──
+
+FORBIDDEN = re.compile(r"\b(eval|exec|compile|__import__)\b")
+
+def pre_execution(iteration, code, variables, history, input_args):
+    """Sanitise generated code before it reaches the interpreter."""
+    if FORBIDDEN.search(code):
+        safe_code = FORBIDDEN.sub("# BLOCKED", code)
+        return PreExecutionOutput(code=safe_code)
+    return PreExecutionOutput(code=code)
+
+# ── Post-execution: retry on error ──
+
+def post_execution(iteration, code, result, variables, history, input_args):
+    """If execution raised an error, wrap a hint so the LLM retries next round."""
+    if isinstance(result, str) and result.startswith("[Error]"):
+        return PostExecutionOutput(
+            result=f"{result}\n# Hint: the variable 'search_pattern' is already in scope."
+        )
+    return PostExecutionOutput(result=result)
+
+# ── Post-iteration: enforce iteration budget ──
+
+MAX_ITERATIONS = 5
+current_iter_count = 0
+
+def post_iteration(iteration, pred, code, result, history: REPLHistory):
+    """Track iterations and stop early if the budget is exhausted."""
+    global current_iter_count
+    current_iter_count += 1
+    if current_iter_count >= MAX_ITERATIONS:
+        # Return empty history to signal stop
+        return PostIterationOutput(history=REPLHistory(entries=[]))
+    return PostIterationOutput(history=history)
+
+# ── Wire everything up ──
+
+enable_rlm_hooks(
+    rlm,
+    pre_iteration_hook=pre_iteration,
+    pre_execution_hook=pre_execution,
+    post_execution_hook=post_execution,
+    post_iteration_hook=post_iteration,
+)
+
+result = rlm(question="Find all TODO comments in the codebase")
+```
+
+### Async Hooks
+
+Return a coroutine and the system handles it automatically:
+
+```python
+async def fetch_context(iteration, variables, history, input_args):
+    context = await remote_cache.get(input_args["question"])
+    return PreIterationOutput(extra_vars={"cached_context": context})
+
+enable_rlm_hooks(rlm, pre_iteration_hook=fetch_context)
+```
+
+### Disabling Hooks
+
+```python
+from dspy_rlm_hooks import disable_rlm_hooks
+
+disable_rlm_hooks(rlm)
+```
+
+Removes all monkey-patched overrides and reverts to original behaviour.
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+## Hook Reference
+
+| Hook | When it fires | What it can do |
+| --- | --- | --- |
+| **PreIteration** | Before action generation | Inject variables (`extra_vars`) and persistent code (`python_code`) |
+| **PreExecution** | After code generation, before running | Rewrite or sanitise the generated `code` string |
+| **PostExecution** | After code runs, before history processing | Transform, audit, or replace the raw `result` |
+| **PostIteration** | After result is folded into history | Save learnings, trigger side effects, or modify `history` |
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- DEVELOPMENT -->
+
+## Development
+
+### Code Quality
+
+This project uses several tools to maintain code quality:
+
+- **Ruff:** Linting and formatting
+- **isort:** Import sorting
+- **pytest:** Testing framework
+- **ty:** Type checking
+- **deptry:** Dependency analysis
+
+**Available commands:**
+
+```sh
+# Run all quality checks
+uv run poe clean-full
+
+# Individual checks
+uv run poe lint          # Ruff linting
+uv run poe format        # Ruff formatting
+uv run poe sort          # Import sorting
+uv run poe typecheck     # Type checking
+uv run poe deptry        # Dependency analysis
+```
+
+### Testing
+
+Run tests using pytest:
+
+```sh
+# Run all tests
+uv run pytest
+
+# Run specific test
+uv run pytest path/to/test.py::test_name
+```
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- CONTRIBUTING -->
+
+## Contributing
+
+Quick workflow:
+
+1. Fork and branch: `git checkout -b feature/name`
+2. Make changes
+3. Run checks: `uv run poe clean-full`
+4. Commit and push
+5. Open a Pull Request
+
+<p align="right">(<a href="#readme-top">back to top</a>)</p>
+
+<!-- LICENSE -->
+
+## License
+
+MIT (as declared in `pyproject.toml`).
+
+---
+
+<div align="center">
+  <p>
+    <sub>Built by <a href="https://github.com/thememium">thememium</a></sub>
+  </p>
+</div>

dspy_rlm_hooks-0.1.2/pyproject.toml

@@ -0,0 +1,81 @@
+[project]
+name = "dspy-rlm-hooks"
+version = "0.1.2"
+description = "Lifecycle instrumentation for DSPy's RLM (Recursive Language Model)."
+readme = "README.md"
+requires-python = ">=3.12"
+authors = [{ name = "Edward Boswell", email = "thememium@gmail.com" }]
+keywords = [
+  "dspy",
+  "ai",
+  "recursive language model",
+  "hooks",
+  "instrumentation",
+  "rlm",
+]
+classifiers = [
+  "Operating System :: OS Independent",
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = ["dspy>=3.1.0", "pydantic>=2.0.0"]
+license = "MIT"
+license-files = ["LICEN[CS]E*"]
+
+[project.urls]
+Homepage = "https://github.com/thememium/dspy-rlm-hooks"
+Documentation = "https://github.com/thememium/dspy-rlm-hooks"
+Repository = "https://github.com/thememium/dspy-rlm-hooks.git"
+Issues = "https://github.com/thememium/dspy-rlm-hooks/issues"
+Changelog = "https://github.com/thememium/dspy-rlm-hooks/blob/master/CHANGELOG.md"
+
+[build-system]
+requires = ["uv_build>=0.11.6,<0.12.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+  "deptry>=0.25.1",
+  "isort>=8.0.1",
+  "poethepoet>=0.46.0",
+  "pytest-asyncio>=0.26.0",
+  "pytest>=9.0.3",
+  "python-dotenv>=1.2.2",
+  "ruff>=0.15.13",
+  "ty>=0.0.37",
+  "usechange>=0.1.28",
+]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["dspy_rlm_hooks*"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+markers = ["asyncio: marks tests as async (pytest-asyncio)"]
+filterwarnings = [
+  "ignore::DeprecationWarning:dspy.predict.avatar.signatures",
+  "ignore::DeprecationWarning:dspy.teleprompt.avatar_optimizer",
+]
+
+[tool.deptry]
+known_first_party = ["dspy_rlm_hooks"]
+exclude = ["venv", "\\.venv", "tests", "\\.git"]
+ignore_notebooks = true
+
+[tool.poe.tasks]
+dev = "uv run src/dspy_rlm_hooks/__init__.py"
+clean-full = "sh -c 'uv run isort . && uv run ruff check . --fix && uv run ruff format . && uv run deptry . && uv run ty check'"
+clean = "sh -c 'uv run isort . && uv run ruff format .'"
+test = "uv run pytest tests/ -v"
+test-e2e = "uv run pytest tests/ -v --run-e2e"
+sort = "uv run isort ."
+lint = "uv run ruff check ."
+format = "uv run ruff format ."
+deptry = "uv deptry ."
+typecheck = "uv run ty check"
+release = "uv run usechange release"

dspy_rlm_hooks-0.1.2/src/dspy_rlm_hooks/__init__.py

@@ -0,0 +1,77 @@
+"""DSPy RLM Hooks — lifecycle instrumentation for :class:`~dspy.RLM`.
+
+This package monkey-patches the internal iteration loop of DSPy's
+:class:`~dspy.RLM` (Recursive Language Model) to expose *lifecycle hooks* at
+every stage of an iteration:
+
+1. **pre_iteration** – before the LLM generates the next action
+2. **pre_execution** – after code generation, before running it
+3. **post_execution** – after code runs, before the result is recorded
+4. **post_iteration** – after the result is folded into history
+
+Hooks may be synchronous **or** asynchronous.  The system auto-detects
+coroutine return values and handles both paths transparently.
+
+Compatibility
+-------------
+Tested against **DSPy 3.1+**.  Because the package instruments *private*
+DSPy internals, future DSPy releases may require updates.  A runtime
+validation check raises :class:`AttributeError` if the RLM instance does
+not expose the expected API.
+
+Quick start
+-----------
+::
+
+    import dspy
+    from dspy_rlm_hooks import enable_rlm_hooks, PreIterationOutput
+
+    rlm = dspy.RLM(...)
+
+    def inject_debug(iteration, variables, history, input_args):
+        return PreIterationOutput(extra_vars={"debug": True})
+
+    enable_rlm_hooks(rlm, pre_iteration_hook=inject_debug)
+
+    # Use rlm normally — hooks fire automatically.
+    result = rlm(question="What is 2 + 2?")
+
+Public API
+----------
+"""
+
+from __future__ import annotations
+
+from dspy_rlm_hooks.patcher import disable_rlm_hooks, enable_rlm_hooks
+from dspy_rlm_hooks.types import (
+    PostExecutionHook,
+    PostExecutionOutput,
+    PostIterationHook,
+    PostIterationOutput,
+    PreExecutionHook,
+    PreExecutionOutput,
+    PreIterationHook,
+    PreIterationOutput,
+    RLMHook,
+)
+
+try:
+    from importlib.metadata import version
+
+    __version__ = version("dspy-rlm-hooks")
+except ImportError:
+    __version__ = "unknown"
+
+__all__ = [
+    "PreIterationHook",
+    "PreExecutionHook",
+    "PostExecutionHook",
+    "PostIterationHook",
+    "PreIterationOutput",
+    "PreExecutionOutput",
+    "PostExecutionOutput",
+    "PostIterationOutput",
+    "RLMHook",
+    "enable_rlm_hooks",
+    "disable_rlm_hooks",
+]

dspy_rlm_hooks-0.1.2/src/dspy_rlm_hooks/patcher.py

@@ -0,0 +1,361 @@
+"""Monkey-patch DSPy :class:`~dspy.RLM` instances to support lifecycle hooks.
+
+This module provides :func:`enable_rlm_hooks`, which injects custom behaviour
+into the RLM's private iteration loop.  Hooks may be sync *or* async; the
+system auto-detects coroutines via :func:`asyncio.iscoroutine` and handles both
+paths transparently.
+
+.. warning::
+    This module uses monkey-patching to instrument DSPy internals.  It is
+    designed for DSPy **3.1+** and may require updates if the internal RLM
+    API changes in future releases.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from types import MethodType
+from typing import Any, cast
+
+from dspy.primitives.prediction import Prediction
+from dspy.primitives.repl_types import REPLHistory, REPLVariable
+
+from dspy_rlm_hooks.types import (
+    PostExecutionHook,
+    PostExecutionOutput,
+    PostIterationHook,
+    PostIterationOutput,
+    PreExecutionHook,
+    PreExecutionOutput,
+    PreIterationHook,
+    PreIterationOutput,
+)
+from dspy_rlm_hooks.utils import _strip_code_fences
+
+logger = logging.getLogger(__name__)
+
+
+def _run_async(coroutine):
+    """Run an async coroutine, handling both sync and async contexts."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coroutine)
+    else:
+        new_loop = asyncio.new_event_loop()
+        try:
+            return new_loop.run_until_complete(coroutine)
+        finally:
+            new_loop.close()
+
+
+_REQUIRED_METHODS = (
+    "_execute_iteration",
+    "_aexecute_iteration",
+    "_process_execution_result",
+    "generate_action",
+    "max_iterations",
+    "verbose",
+)
+
+
+def _validate_rlm(rlm: Any) -> None:
+    """Ensure *rlm* exposes the internal methods we need to patch."""
+    missing = [name for name in _REQUIRED_METHODS if not hasattr(rlm, name)]
+    if missing:
+        raise AttributeError(
+            f"RLM instance missing required attributes: {', '.join(missing)}. "
+            "Ensure you are passing a dspy.RLM instance from dspy>=3.1."
+        )
+
+
+def _execute_code(self: Any, repl: Any, code: str, input_args: dict[str, Any]) -> Any:
+    """Run ``code`` inside the REPL, prepending any persisted globals.
+
+    Mirrors the original ``RLM._execute_code`` logic and is bound as a
+    replacement method during :func:`enable_rlm_hooks`.
+    """
+    if hasattr(repl, "repl_globals") and repl.repl_globals:
+        code = repl.repl_globals + "\n" + code
+    try:
+        return repl.execute(code, variables=dict(input_args))
+    except Exception as exc:  # noqa: BLE001
+        return f"[Error] {exc}"
+
+
+def _execute_iteration(
+    self: Any,
+    repl: Any,
+    variables: list[REPLVariable],
+    history: REPLHistory,
+    iteration: int,
+    input_args: dict[str, Any],
+    output_field_names: list[str],
+) -> Prediction | REPLHistory:
+    """Synchronous RLM iteration with hook support.
+
+    Lifecycle::
+
+        pre_iteration → generate_action → pre_execution → execute → post_execution → post_iteration
+    """
+    # --- pre-iteration hook ---
+    if self._hook_pre_iteration:
+        pre_iter_out = self._hook_pre_iteration(
+            iteration, variables, history, input_args
+        )
+        if asyncio.iscoroutine(pre_iter_out):
+            pre_iter_out = _run_async(pre_iter_out)
+        pre_iter_out = cast(PreIterationOutput, pre_iter_out)
+        input_args = {**input_args, **pre_iter_out.extra_vars}
+        if pre_iter_out.python_code:
+            current_globals = getattr(repl, "repl_globals", "") or ""
+            repl.repl_globals = current_globals + "\n" + pre_iter_out.python_code
+
+    # --- action generation ---
+    variables_info = [variable.format() for variable in variables]
+    action = self.generate_action(
+        variables_info=variables_info,
+        repl_history=history,
+        iteration=f"{iteration + 1}/{self.max_iterations}",
+    )
+
+    if self.verbose:
+        logger.info(
+            "RLM iteration %d/%d\nReasoning: %s\nCode:\n%s",
+            iteration + 1,
+            self.max_iterations,
+            action.reasoning,
+            action.code,
+        )
+
+    # --- strip fences ---
+    try:
+        code = _strip_code_fences(action.code)
+    except SyntaxError as exc:
+        code = action.code
+        result = f"[Error] {exc}"
+        return self._process_execution_result(
+            action, code, result, history, output_field_names
+        )
+
+    # --- pre-execution hook ---
+    if self._hook_pre_execution:
+        pre_exec_out = self._hook_pre_execution(
+            iteration, code, variables, history, input_args
+        )
+        if asyncio.iscoroutine(pre_exec_out):
+            pre_exec_out = _run_async(pre_exec_out)
+        pre_exec_out = cast(PreExecutionOutput, pre_exec_out)
+        code = pre_exec_out.code
+
+    # --- execute ---
+    result = self._execute_code(repl, code, input_args)
+
+    # --- post-execution hook ---
+    if self._hook_post_execution:
+        post_exec_out = self._hook_post_execution(
+            iteration, code, result, variables, history, input_args
+        )
+        if asyncio.iscoroutine(post_exec_out):
+            post_exec_out = _run_async(post_exec_out)
+        post_exec_out = cast(PostExecutionOutput, post_exec_out)
+        result = post_exec_out.result
+
+    # --- process result ---
+    processed = self._process_execution_result(
+        action, code, result, history, output_field_names
+    )
+
+    # --- post-iteration hook ---
+    if self._hook_post_iteration and isinstance(processed, REPLHistory):
+        post_iter_out = self._hook_post_iteration(
+            iteration, action, code, result, processed
+        )
+        if asyncio.iscoroutine(post_iter_out):
+            post_iter_out = _run_async(post_iter_out)
+        post_iter_out = cast(PostIterationOutput, post_iter_out)
+        processed = post_iter_out.history
+
+    return processed
+
+
+async def _aexecute_iteration(
+    self: Any,
+    repl: Any,
+    variables: list[REPLVariable],
+    history: REPLHistory,
+    iteration: int,
+    input_args: dict[str, Any],
+    output_field_names: list[str],
+) -> Prediction | REPLHistory:
+    """Asynchronous RLM iteration with hook support.
+
+    Mirrors :func:`_execute_iteration` but uses ``await`` for async hooks
+    and ``generate_action.acall``.
+    """
+    # --- pre-iteration hook ---
+    if self._hook_pre_iteration:
+        pre_iter_out = self._hook_pre_iteration(
+            iteration, variables, history, input_args
+        )
+        if asyncio.iscoroutine(pre_iter_out):
+            pre_iter_out = await pre_iter_out
+        pre_iter_out = cast(PreIterationOutput, pre_iter_out)
+        input_args = {**input_args, **pre_iter_out.extra_vars}
+        if pre_iter_out.python_code:
+            current_globals = getattr(repl, "repl_globals", "") or ""
+            repl.repl_globals = current_globals + "\n" + pre_iter_out.python_code
+
+    # --- action generation ---
+    variables_info = [variable.format() for variable in variables]
+    pred = await self.generate_action.acall(
+        variables_info=variables_info,
+        repl_history=history,
+        iteration=f"{iteration + 1}/{self.max_iterations}",
+    )
+
+    if self.verbose:
+        logger.info(
+            "RLM iteration %d/%d\nReasoning: %s\nCode:\n%s",
+            iteration + 1,
+            self.max_iterations,
+            pred.reasoning,
+            pred.code,
+        )
+
+    # --- strip fences ---
+    try:
+        code = _strip_code_fences(pred.code)
+    except SyntaxError as exc:
+        code = pred.code
+        result = f"[Error] {exc}"
+        return self._process_execution_result(
+            pred, code, result, history, output_field_names
+        )
+
+    # --- pre-execution hook ---
+    if self._hook_pre_execution:
+        pre_exec_out = self._hook_pre_execution(
+            iteration, code, variables, history, input_args
+        )
+        if asyncio.iscoroutine(pre_exec_out):
+            pre_exec_out = await pre_exec_out
+        pre_exec_out = cast(PreExecutionOutput, pre_exec_out)
+        code = pre_exec_out.code
+
+    # --- execute ---
+    result = self._execute_code(repl, code, input_args)
+
+    # --- post-execution hook ---
+    if self._hook_post_execution:
+        post_exec_out = self._hook_post_execution(
+            iteration, code, result, variables, history, input_args
+        )
+        if asyncio.iscoroutine(post_exec_out):
+            post_exec_out = await post_exec_out
+        post_exec_out = cast(PostExecutionOutput, post_exec_out)
+        result = post_exec_out.result
+
+    # --- process result ---
+    processed = self._process_execution_result(
+        pred, code, result, history, output_field_names
+    )
+
+    # --- post-iteration hook ---
+    if self._hook_post_iteration and isinstance(processed, REPLHistory):
+        post_iter_out = self._hook_post_iteration(
+            iteration, pred, code, result, processed
+        )
+        if asyncio.iscoroutine(post_iter_out):
+            post_iter_out = await post_iter_out
+        post_iter_out = cast(PostIterationOutput, post_iter_out)
+        processed = post_iter_out.history
+
+    return processed
+
+
+def enable_rlm_hooks(
+    rlm: Any,
+    *,
+    pre_iteration_hook: PreIterationHook | None = None,
+    pre_execution_hook: PreExecutionHook | None = None,
+    post_execution_hook: PostExecutionHook | None = None,
+    post_iteration_hook: PostIterationHook | None = None,
+) -> None:
+    """Inject lifecycle hooks into a :class:`~dspy.RLM` instance.
+
+    Monkey-patches the RLM's private ``_execute_iteration`` and
+    ``_aexecute_iteration`` methods so that user-provided hooks are invoked
+    at each stage of the iteration loop.
+
+    Hooks can be **sync** or **async** — the system automatically detects
+    coroutine return values via :func:`asyncio.iscoroutine` and handles both
+    paths.
+
+    Lifecycle order::
+
+        pre_iteration_hook → generate_action → pre_execution_hook → execute → post_execution_hook → post_iteration_hook
+
+    Args:
+        rlm: The RLM instance to patch.  Must expose the internal methods
+            ``_execute_iteration``, ``_aexecute_iteration``,
+            ``_process_execution_result``, ``generate_action``/``generate_action.acall``,
+            ``max_iterations``, and ``verbose``.
+        pre_iteration_hook: Called before action generation.  May inject
+            variables via :attr:`PreIterationOutput.extra_vars` or prepend
+            persistent code via :attr:`PreIterationOutput.python_code`.
+        pre_execution_hook: Called after code is generated, before execution.
+            May rewrite the generated ``code`` string.
+        post_execution_hook: Called after code executes, before the result is
+            processed into history.  May transform or audit ``result``.
+        post_iteration_hook: Called after the result is processed into history.
+            May save learnings, trigger side effects, or modify history.
+
+    Raises:
+        AttributeError: If *rlm* does not expose the expected internal API.
+
+    Example:
+        >>> def my_pre_iter(iteration, variables, history, input_args):
+        ...     return PreIterationOutput(extra_vars={"debug": True})
+        ...
+        >>> enable_rlm_hooks(rlm, pre_iteration_hook=my_pre_iter)
+    """
+    _validate_rlm(rlm)
+
+    # Store hook references on the instance
+    rlm._hook_pre_iteration = pre_iteration_hook
+    rlm._hook_pre_execution = pre_execution_hook
+    rlm._hook_post_execution = post_execution_hook
+    rlm._hook_post_iteration = post_iteration_hook
+
+    # Bind patched methods
+    rlm._execute_iteration = MethodType(_execute_iteration, rlm)
+    rlm._aexecute_iteration = MethodType(_aexecute_iteration, rlm)
+    rlm._execute_code = MethodType(_execute_code, rlm)
+
+
+def disable_rlm_hooks(rlm: Any) -> None:
+    """Remove lifecycle hooks from an RLM instance.
+
+    Deletes the monkey-patched overrides and hook attributes that were added
+    by :func:`enable_rlm_hooks`.  After calling this, the instance reverts
+    to its original behaviour.
+
+    Args:
+        rlm: A previously patched RLM instance.
+
+    Example:
+        >>> disable_rlm_hooks(rlm)
+    """
+    for attr in (
+        "_hook_pre_iteration",
+        "_hook_pre_execution",
+        "_hook_post_execution",
+        "_hook_post_iteration",
+        "_execute_iteration",
+        "_aexecute_iteration",
+        "_execute_code",
+    ):
+        if hasattr(rlm, attr):
+            delattr(rlm, attr)

dspy_rlm_hooks-0.1.2/src/dspy_rlm_hooks/types.py

@@ -0,0 +1,152 @@
+"""Type definitions for the DSPy RLM hook system.
+
+
+
+Usage::
+
+    from dspy_rlm_hooks import (
+        PreIterationHook,
+        PreIterationOutput,
+        enable_rlm_hooks,
+    )
+"""
+
+from __future__ import annotations
+
+from typing import Any, Awaitable, Protocol, runtime_checkable
+
+import pydantic
+from dspy.primitives.repl_types import REPLHistory
+
+
+class PreIterationOutput(pydantic.BaseModel):
+    """Data produced by a ``pre_iteration`` hook.
+
+    Allows injecting variables and persistent Python code into the interpreter
+    namespace before the LLM generates the next action.
+
+    Attributes:
+        extra_vars: Variables to inject into the interpreter namespace before
+            the next code generation.  These are merged into ``input_args``.
+        python_code: Code to prepend to generated code on every execution.
+            Persists across iterations via ``repl.repl_globals``.
+    """
+
+    extra_vars: dict[str, Any] = pydantic.Field(default_factory=dict)
+    python_code: str = ""
+
+
+class PreExecutionOutput(pydantic.BaseModel):
+    """Data produced by a ``pre_execution`` hook.
+
+    Allows rewriting or augmenting the LLM-generated code before it is
+    sent to the code interpreter.
+
+    Attributes:
+        code: The code to execute.  Usually the LLM-generated code, but can
+            be rewritten (e.g. to add imports, fix patterns, inject helpers).
+    """
+
+    code: str
+
+
+class PostExecutionOutput(pydantic.BaseModel):
+    """Data produced by a ``post_execution`` hook.
+
+    Allows transforming, auditing, or replacing the raw execution result
+    before it is processed into history.
+
+    Attributes:
+        result: The result to pass to history.  Can transform or replace the
+            raw execution result.
+    """
+
+    result: Any
+
+
+class PostIterationOutput(pydantic.BaseModel):
+    """Data produced by a ``post_iteration`` hook.
+
+    Allows modifying or persisting the REPL history after the iteration
+    result has been processed.
+
+    Attributes:
+        history: The updated history for the next iteration.  Return the same
+            history to persist it, or a modified copy to change it.
+    """
+
+    history: REPLHistory
+
+
+@runtime_checkable
+class PreIterationHook(Protocol):
+    """Called before action generation in each RLM iteration.
+
+    Receives the current iteration index, variable state, history, and input
+    arguments.  May return :class:`PreIterationOutput` (sync) or an
+    ``Awaitable[PreIterationOutput]`` (async).
+    """
+
+    def __call__(
+        self,
+        iteration: int,
+        variables: list[Any],
+        history: list[Any],
+        input_args: dict[str, Any],
+    ) -> PreIterationOutput | Awaitable[PreIterationOutput]: ...
+
+
+@runtime_checkable
+class PreExecutionHook(Protocol):
+    """Called after code generation, before execution.
+
+    Receives the generated code and may rewrite it.
+    """
+
+    def __call__(
+        self,
+        iteration: int,
+        code: str,
+        variables: list[Any],
+        history: list[Any],
+        input_args: dict[str, Any],
+    ) -> PreExecutionOutput | Awaitable[PreExecutionOutput]: ...
+
+
+@runtime_checkable
+class PostExecutionHook(Protocol):
+    """Called after code execution, before result processing.
+
+    Receives the raw execution result and may transform or audit it.
+    """
+
+    def __call__(
+        self,
+        iteration: int,
+        code: str,
+        result: Any,
+        variables: list[Any],
+        history: list[Any],
+        input_args: dict[str, Any],
+    ) -> PostExecutionOutput | Awaitable[PostExecutionOutput]: ...
+
+
+@runtime_checkable
+class PostIterationHook(Protocol):
+    """Called after the iteration result is processed into history.
+
+    Receives the updated history and may modify or persist it.
+    """
+
+    def __call__(
+        self,
+        iteration: int,
+        pred: Any,
+        code: str,
+        result: Any,
+        history: REPLHistory,
+    ) -> PostIterationOutput | Awaitable[PostIterationOutput]: ...
+
+
+RLMHook = PreIterationHook | PreExecutionHook | PostExecutionHook | PostIterationHook
+"""Union of all hook protocols.  Used for type narrowing."""

dspy_rlm_hooks-0.1.2/src/dspy_rlm_hooks/utils.py

@@ -0,0 +1,56 @@
+"""Small internal utilities for the RLM hook system."""
+
+from __future__ import annotations
+
+
+def _strip_code_fences(code: str) -> str:
+    """Remove markdown code fences from LLM-generated code.
+
+    Handles both plain `` ``` `` fences and language-tagged ones
+    (`` ```python ``).  Raises :class:`SyntaxError` when a non-Python
+    language fence is detected.
+
+    Args:
+        code: Raw code string, potentially wrapped in markdown fences.
+
+    Returns:
+        Clean code with fences stripped.
+
+    Raises:
+        SyntaxError: If the fence specifies a language other than Python.
+    """
+    code = code.strip()
+    if "```" not in code:
+        return code
+
+    lines = code.splitlines()
+    while len(lines) >= 2 and lines[0].strip() == "```" and lines[-1].strip() == "```":
+        lines.pop(0)
+        lines.pop()
+    code = "\n".join(lines).strip()
+
+    if "```" not in code:
+        return code
+
+    # If there are still fences after stripping plain pairs,
+    # it may be a language-tagged block or multiple blocks.
+    # Strip one more language-tagged fence if present.
+    fence_start = code.find("```")
+    lang_line, separator, remainder = code[fence_start + 3 :].partition("\n")
+    if not separator:
+        return code
+
+    lang = (lang_line.strip().split(maxsplit=1)[0] if lang_line.strip() else "").lower()
+    if lang not in {"python", "py", "python3", "py3", ""}:
+        raise SyntaxError(
+            f"Expected Python code but got ```{lang} fence. "
+            f"Write Python code, not {lang}."
+        )
+
+    block_end = remainder.find("```")
+    if block_end == -1:
+        return remainder.strip()
+    if block_end == 0:
+        # Opening and closing fences are adjacent — return everything after
+        return remainder[3:].strip()
+    return remainder[:block_end].strip()