docs: update for depth>1, add e2e test

Author: rawwerks

docs/api/rlm.md

@@ -45,11 +45,20 @@ RLM(
     depth: int = 0,
     max_depth: int = 1,
     max_iterations: int = 30,
+    max_budget: float | None = None,
+    max_timeout: float | None = None,
+    max_tokens: int | None = None,
+    max_errors: int | None = None,
     custom_system_prompt: str | None = None,
     other_backends: list[str] | None = None,
     other_backend_kwargs: list[dict] | None = None,
     logger: RLMLogger | None = None,
     verbose: bool = False,
+    persistent: bool = False,
+    on_subcall_start: Callable[[int, str, str], None] | None = None,
+    on_subcall_complete: Callable[[int, str, float, str | None], None] | None = None,
+    on_iteration_start: Callable[[int, int], None] | None = None,
+    on_iteration_complete: Callable[[int, int, float], None] | None = None,
 )
 ```
 
@@ -158,7 +167,7 @@ environment_kwargs = {
 **Type:** `int`  
 **Default:** `1`
 
-Maximum recursion depth for nested RLM calls. Currently only depth 1 is fully supported.
+Maximum recursion depth for nested RLM calls. Depth>1 recursive subcalls are supported in the local environment via `llm_query()`.
 
 When `depth >= max_depth`, the RLM falls back to a regular LM completion.
 
@@ -187,6 +196,46 @@ rlm = RLM(
 
 ---
 
+#### `max_budget`
+{: .no_toc }
+
+**Type:** `float | None`  
+**Default:** `None`
+
+Maximum total USD cost for a completion. If exceeded, RLM raises `BudgetExceededError`. This requires a backend that reports cost.
+
+---
+
+#### `max_timeout`
+{: .no_toc }
+
+**Type:** `float | None`  
+**Default:** `None`
+
+Maximum wall-clock seconds for a completion. If exceeded, RLM raises `TimeoutExceededError`.
+
+---
+
+#### `max_tokens`
+{: .no_toc }
+
+**Type:** `int | None`  
+**Default:** `None`
+
+Maximum total tokens (input + output) for a completion. If exceeded, RLM raises `TokenLimitExceededError`.
+
+---
+
+#### `max_errors`
+{: .no_toc }
+
+**Type:** `int | None`  
+**Default:** `None`
+
+Maximum consecutive REPL errors before aborting. If exceeded, RLM raises `ErrorThresholdExceededError`.
+
+---
+
 #### `custom_system_prompt`
 {: .no_toc }
 
@@ -401,6 +450,12 @@ rlm = RLM(backend="unknown")
 
 If the RLM exhausts `max_iterations` without finding a `FINAL()` answer, it prompts the LM one more time to provide a final answer based on the conversation history.
 
+RLM also raises explicit exceptions when limits are exceeded:
+- `BudgetExceededError`
+- `TimeoutExceededError`
+- `TokenLimitExceededError`
+- `ErrorThresholdExceededError`
+
 ---
 
 ## Thread Safety
@@ -458,4 +513,3 @@ result = rlm.completion(
     root_prompt="Summarize the key findings"
 )
 ```
-

docs/getting-started.md

@@ -133,6 +133,10 @@ This will display:
 | `environment_kwargs` | `dict` | `None` | Environment configuration |
 | `max_depth` | `int` | `1` | Maximum recursion depth |
 | `max_iterations` | `int` | `30` | Max REPL iterations per call |
+| `max_budget` | `float` | `None` | Max total USD cost (if provider reports cost) |
+| `max_timeout` | `float` | `None` | Max wall-clock seconds per completion |
+| `max_tokens` | `int` | `None` | Max total tokens (input + output) per completion |
+| `max_errors` | `int` | `None` | Max consecutive REPL errors before abort |
 | `custom_system_prompt` | `str` | `None` | Override default system prompt |
 | `other_backends` | `list` | `None` | Additional backends for sub-calls |
 | `other_backend_kwargs` | `list` | `None` | Configs for additional backends |
@@ -159,6 +163,18 @@ result = rlm.completion(
 - `root_model`: Model name used
 - `prompt`: Original input
 
+### Depth>1 Recursion
+
+Depth>1 recursive subcalls are supported. When code inside the REPL calls `llm_query()` and `max_depth` allows it, RLM spawns a child RLM with its own REPL. When `depth >= max_depth`, it falls back to a plain LM completion.
+
+### Limits and Exceptions
+
+RLM raises explicit exceptions when limits are exceeded:
+- `BudgetExceededError`
+- `TimeoutExceededError`
+- `TokenLimitExceededError`
+- `ErrorThresholdExceededError`
+
 ---
 
 ## Choosing an Environment
@@ -340,4 +356,3 @@ Upload `.jsonl` log files to visualize:
 - [API Reference](api/rlm.md) - Complete RLM class documentation
 - [Environments](environments/) - Deep dive into each environment
 - [Backends](backends.md) - Detailed backend configuration
-

tests/test_e2e_depth.py

@@ -0,0 +1,24 @@
+"""E2E test for depth>1 with real LLM via OpenRouter."""
+import os
+
+import pytest
+
+from rlm import RLM
+
+
+@pytest.mark.skipif(
+    not os.environ.get("OPENROUTER_API_KEY"),
+    reason="OPENROUTER_API_KEY not set",
+)
+def test_depth_2_real_llm():
+    """Test depth=2 recursion with google/gemini-3-flash-preview."""
+    rlm = RLM(
+        backend="openrouter",
+        backend_kwargs={"model_name": "google/gemini-3-flash-preview"},
+        max_iterations=2,
+        max_depth=2,
+    )
+    result = rlm.completion("What is 2+2? Answer with just the number.")
+    assert result.response is not None
+    assert len(result.response) > 0
+    print(f"Response: {result.response}")