From d1342768190f2e2d1aedad61919c0815ff57db24 Mon Sep 17 00:00:00 2001 From: Yiorgis Gozadinos Date: Tue, 24 Feb 2026 12:26:04 +0200 Subject: [PATCH] Update docs --- CHANGELOG.md | 2 +- docs/agents/rlm.md | 121 +++++++------------------------------------ docs/skills/index.md | 4 +- docs/skills/rlm.md | 5 +- docs/tools.md | 2 +- 5 files changed, 23 insertions(+), 111 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index e6f84ce7..badb9a92 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,7 +4,7 @@ ### Changed - **RLM sandbox**: Replaced Docker-based code execution with [pydantic-monty](https://github.com/pydantic/monty), a minimal secure Python interpreter written in Rust. Eliminates Docker as a runtime dependency for RLM with sub-millisecond sandbox startup -- **RLM sandbox functions**: Added `get_chunk(chunk_id)` for retrieving chunk content and metadata from search results. `get_docling_document(document_id)` now returns the full document structure as a JSON dict +- **RLM sandbox functions**: Added `get_chunk(chunk_id)` for retrieving chunk content and metadata from search results. `get_docling_document(document_id)` now returns the full document structure as a JSON dict. All sandbox functions now require `await` - **`RLMConfig`**: Removed `docker_image` and `docker_memory_limit` fields ### Added diff --git a/docs/agents/rlm.md b/docs/agents/rlm.md index fbf267ad..30a7346e 100644 --- a/docs/agents/rlm.md +++ b/docs/agents/rlm.md @@ -11,7 +11,7 @@ The RLM agent enables complex analytical tasks by writing and executing Python c 1. The agent receives a question 2. It writes Python code to explore the knowledge base -3. Code executes in a sandboxed Python interpreter with access to haiku.rag functions +3. Code executes in a sandboxed Python interpreter with access to knowledge base functions 4. The agent iterates: run code, examine results, refine approach 5. Final answer is synthesized from the gathered data @@ -52,116 +52,35 @@ async with HaikuRAG(path_to_db) as client: ) ``` -## Available Functions +## Sandbox Capabilities -Inside the sandbox, these functions are available (no imports needed): +The agent's code runs in a sandboxed Python interpreter ([pydantic-monty](https://github.com/pydantic/monty)) with access to these knowledge base functions: -### search(query, limit=10) +| Function | Description | +|----------|-------------| +| `search(query, limit)` | Hybrid search (vector + full-text) returning matching chunks with scores | +| `list_documents(limit, offset)` | List documents in the knowledge base | +| `get_document(id_or_title)` | Get full text content of a document | +| `get_chunk(chunk_id)` | Get a chunk with metadata (headings, page numbers, labels) for citations | +| `get_docling_document(document_id)` | Get the full DoclingDocument structure as a dict (texts, tables, pictures, pages) | +| `llm(prompt)` | Call an LLM for classification, summarization, or extraction | -Search the knowledge base using hybrid search (vector + full-text). +When documents are pre-loaded via the `documents` parameter, they are injected as a `documents` variable accessible in the sandbox code. -```python -results = search("climate change impacts", limit=20) -for r in results: - print(r['document_title'], r['score']) - print(r['content'][:200]) -``` +### Python Features -Returns list of dicts with keys: `chunk_id`, `content`, `document_id`, `document_title`, `document_uri`, `score`, `page_numbers`, `headings` +The interpreter supports a subset of Python: variables, arithmetic, strings, f-strings, lists, dicts, tuples, sets, loops, conditionals, comprehensions, functions, async/await, try/except, and the `json` module. -### list_documents(limit=10, offset=0) +Not supported: imports (other than `json`), class definitions, generators/yield, match statements, decorators, `with` statements. For pattern matching, the agent can use string methods or the `llm()` function. -List available documents in the knowledge base. - -```python -docs = list_documents(limit=100) -for doc in docs: - print(doc['id'], doc['title']) -``` - -Returns list of dicts with keys: `id`, `title`, `uri`, `created_at` - -### get_document(id_or_title) - -Get the full text content of a document by ID, title, or URI. - -```python -content = get_document("Q1 Report") -if content: - print(len(content), "characters") -``` - -Returns the document content as a string, or `None` if not found. - -### get_chunk(chunk_id) - -Get a specific chunk by its ID (from search results). Use this to retrieve full chunk details and metadata for citations. - -```python -results = search("safety requirements", limit=5) -for r in results: - chunk = get_chunk(r['chunk_id']) - print(f"From '{chunk['document_title']}', page {chunk['page_numbers']}: {chunk['content'][:100]}") -``` - -Returns dict with keys: `chunk_id`, `content`, `document_id`, `document_title`, `headings`, `page_numbers`, `labels` - -### llm(prompt) - -Call an LLM directly for classification, summarization, or extraction tasks. - -```python -content = get_document("Q1 Report") -sentiment = llm(f"Classify the sentiment as positive, negative, or mixed: {content}") -print(sentiment) -``` - -Use this when you have content and need LLM reasoning without RAG search. - -## Pre-loaded Documents - -When documents are pre-loaded via the `documents` parameter, they're available as a `documents` variable: - -```python -# Available when documents are pre-loaded -for doc in documents: - print(doc['title'], len(doc['content'])) -``` - -Each document dict has keys: `id`, `title`, `uri`, `content` - -## Python Features - -The sandbox uses [pydantic-monty](https://github.com/pydantic/monty), a minimal secure Python interpreter written in Rust. It supports a subset of Python: - -**Supported:** variables, arithmetic, strings, f-strings, lists, dicts, tuples, sets, loops, conditionals, comprehensions, functions, try/except, and the `json` module. - -**Not supported:** imports (other than `json`), class definitions, generators/yield, match statements, decorators, `with` statements. - -For pattern matching or text extraction, use string methods (`str.split`, `str.find`, `str.startswith`, `in` operator) or the `llm()` function: - -```python -# Extract data with llm() instead of regex -numbers = [] -results = search("financial data", limit=20) -for r in results: - extracted = llm(f"Extract all dollar amounts as a comma-separated list of numbers (no $ signs): {r['content']}") - for part in extracted.split(','): - part = part.strip().replace(',', '') - if part.isdigit(): - numbers.append(int(part)) -if numbers: - print(f"Average: {sum(numbers) / len(numbers)}") -``` - -## Sandboxed Execution +### Security Code executes in an isolated interpreter with: - **No filesystem access**: Code cannot read or write files - **No network access**: Code cannot make HTTP requests or open sockets - **No imports**: Only the `json` module is available -- **Execution timeout**: Code times out after configurable limit (default 60s) +- **Execution timeout**: Configurable limit (default 60s) - **Output truncation**: Large outputs are truncated to prevent memory issues ## Context Filter @@ -176,11 +95,7 @@ result = await client.rlm( ) ``` -This is useful for: - -- Scoping to specific document sets -- Enforcing access control -- Limiting context for focused analysis +This is useful for scoping to specific document sets, enforcing access control, or limiting context for focused analysis. ## Configuration diff --git a/docs/skills/index.md b/docs/skills/index.md index fdf689f1..e405782e 100644 --- a/docs/skills/index.md +++ b/docs/skills/index.md @@ -7,7 +7,7 @@ haiku.rag exposes its RAG capabilities as [haiku.skills](https://github.com/ggoz | Skill | Description | |-------|-------------| | [`rag`](rag.md) | Search, retrieve, and answer questions from the knowledge base | -| [`rag-rlm`](rlm.md) | Computational analysis via code execution (requires Docker) | +| [`rag-rlm`](rlm.md) | Computational analysis via code execution | ## Discovery @@ -16,7 +16,7 @@ Skills are registered as Python entrypoints under `haiku.skills`. They are disco ```bash haiku-skills list --use-entrypoints # rag — Search, retrieve and analyze documents using RAG. -# rag-rlm — Analyze documents using code execution in a Docker sandbox. +# rag-rlm — Analyze documents using code execution in a sandboxed interpreter. ``` ## Usage diff --git a/docs/skills/rlm.md b/docs/skills/rlm.md index 45f6dc14..416f5d6d 100644 --- a/docs/skills/rlm.md +++ b/docs/skills/rlm.md @@ -1,9 +1,6 @@ # RLM Skill -The RLM (Reflexion Language Model) skill provides computational analysis via code execution. It writes and runs Python code in an isolated Docker sandbox to answer questions that require computation, aggregation, or data traversal. - -!!! warning "Requires Docker" - The `analyze` tool executes code in a Docker sandbox. Docker must be running on the host machine. This skill is not suitable for Docker-deployed applications — use the [`rag`](rag.md) skill alone in those environments. +The RLM (Recursive Language Model) skill provides computational analysis via code execution. It writes and runs Python code in a sandboxed interpreter to answer questions that require computation, aggregation, or data traversal. ## `create_skill(db_path?, config?)` diff --git a/docs/tools.md b/docs/tools.md index f129c801..378d967d 100644 --- a/docs/tools.md +++ b/docs/tools.md @@ -61,7 +61,7 @@ docs = create_document_toolset(config) ### Analysis Toolset -`create_analysis_toolset()` provides computational analysis via the RLM agent (Docker sandbox). +`create_analysis_toolset()` provides computational analysis via the RLM agent. ```python from haiku.rag.tools import create_analysis_toolset