pydantic-ai-rlm 0.1.0__tar.gz

pydantic_ai_rlm-0.1.0/.gitignore

@@ -0,0 +1,101 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+.venv*/
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+.settings/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyright
+.pyright/
+
+# MkDocs documentation
+site/
+
+# UV
+uv.lock
+
+# Coverage directory
+.coverage/
+
+# OS files
+.DS_Store
+
+# Local development
+playground/
+*.local

pydantic_ai_rlm-0.1.0/.logfire/.gitignore

@@ -0,0 +1 @@
+*

pydantic_ai_rlm-0.1.0/.logfire/logfire_credentials.json

@@ -0,0 +1,6 @@
+{
+  "token": "pylf_v1_us_bBcHq1CyJmt3JYVtRjpTpgTGrr3SW3yy7Cvn3nN6kh11",
+  "project_name": "internal-demos",
+  "project_url": "https://logfire-us.pydantic.dev/wojciech-achtelik/internal-demos",
+  "logfire_api_url": "https://logfire-api.pydantic.dev"
+}

pydantic_ai_rlm-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,43 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+        args: [--maxkb=1000]
+      - id: check-json
+      - id: check-toml
+      - id: check-yaml
+      - id: detect-private-key
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+      - id: no-commit-to-branch
+        args: [--branch=main, --branch=master, --branch=production]
+      - id: trailing-whitespace
+      - id: check-merge-conflict
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.11
+    hooks:
+      - id: ruff-format
+      - id: ruff-check
+        args: [--fix]
+
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.9.22
+    hooks:
+      - id: uv-lock
+
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.30.0
+    hooks:
+      - id: gitleaks
+
+  - repo: local
+    hooks:
+      - id: ty
+        name: ty (type checker)
+        entry: uvx ty check
+        language: system
+        types: [python]
+        pass_filenames: false

pydantic_ai_rlm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pydantic AI RLM Contributors
+
+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.

pydantic_ai_rlm-0.1.0/PKG-INFO

@@ -0,0 +1,344 @@
+Metadata-Version: 2.4
+Name: pydantic-ai-rlm
+Version: 0.1.0
+Summary: Recursive Language Model (RLM) toolset for Pydantic AI - handle extremely large contexts
+Author: Pydantic AI RLM Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,context,llm,machine-learning,pydantic,pydantic-ai,recursive,repl
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pydantic-ai>=0.1.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1; extra == 'dev'
+Provides-Extra: logging
+Requires-Dist: rich>=13.0; extra == 'logging'
+Description-Content-Type: text/markdown
+
+<h1 align="center">Pydantic AI RLM</h1>
+
+<p align="center">
+  <b>Handle Extremely Large Contexts with Any LLM Provider</b>
+</p>
+
+<p align="center">
+  <a href="https://github.com/vstorm-co/pydantic-ai-rlm">GitHub</a> •
+  <a href="https://github.com/vstorm-co/pydantic-ai-rlm#examples">Examples</a>
+</p>
+
+<p align="center">
+  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python 3.10+"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT"></a>
+  <a href="https://github.com/pydantic/pydantic-ai"><img src="https://img.shields.io/badge/Powered%20by-Pydantic%20AI-E92063?logo=pydantic&logoColor=white" alt="Pydantic AI"></a>
+</p>
+
+<p align="center">
+  <b>Switch Providers Instantly</b>
+  &nbsp;•&nbsp;
+  <b>Sandboxed Code Execution</b>
+  &nbsp;•&nbsp;
+  <b>Sub-Model Delegation</b>
+  &nbsp;•&nbsp;
+  <b>Fully Type-Safe</b>
+</p>
+
+---
+
+## What is RLM?
+
+**RLM (Recursive Language Model)** is a pattern for handling contexts that exceed a model's context window, introduced by **Alex L. Zhang, Tim Kraska, and Omar Khattab** in their paper [Recursive Language Models](https://arxiv.org/abs/2512.24601). Instead of trying to fit everything into one prompt, the LLM writes Python code to programmatically explore and analyze the data.
+
+**The key insight:** An LLM can write code to search through millions of lines in seconds, then use `llm_query()` to delegate semantic analysis of relevant chunks to a sub-model.
+
+This library is an implementation inspired by the [original minimal implementation](https://github.com/alexzhang13/rlm-minimal).
+
+---
+
+## Get Started in 60 Seconds
+
+```bash
+pip install pydantic-ai-rlm
+```
+
+```python
+from pydantic_ai_rlm import run_rlm_analysis
+
+answer = await run_rlm_analysis(
+    context=massive_document,  # Can be millions of characters
+    query="Find the magic number hidden in the text",
+    model="openai:gpt-5",
+    sub_model="openai:gpt-5-mini",
+)
+```
+
+**That's it.** Your agent can now:
+
+- Write Python code to analyze massive contexts
+- Use `llm_query()` to delegate semantic analysis to sub-models
+- Work with any Pydantic AI compatible provider
+
+---
+
+## Why pydantic-ai-rlm?
+
+### Switch Providers Instantly
+
+Built on Pydantic AI, you can test any model with a single line change:
+
+```python
+# OpenAI
+agent = create_rlm_agent(model="openai:gpt-5", sub_model="openai:gpt-5-mini")
+
+# Anthropic
+agent = create_rlm_agent(model="anthropic:claude-sonnet-4-5", sub_model="anthropic:claude-haiku-4-5")
+
+agent = create_rlm_agent(model="anthropic:claude-sonnet-4-5", sub_model="openai:gpt-5-mini")
+```
+
+### Reusable Toolset
+
+The RLM toolset integrates with any pydantic-ai agent:
+
+```python
+from pydantic_ai import Agent
+from pydantic_ai_rlm import create_rlm_toolset, RLMDependencies
+
+# Use the toolset in any agent
+toolset = create_rlm_toolset(sub_model="openai:gpt-5-mini")
+agent = Agent("openai:gpt-5", toolsets=[toolset])
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         pydantic-ai-rlm                         │
+│                                                                 │
+│   ┌─────────────┐         ┌─────────────────────────────────┐   │
+│   │   Main LLM  │         │     Sandboxed REPL Environment  │   │
+│   │   (gpt-5)   │────────>│                                 │   │
+│   └─────────────┘         │   context = <your massive data> │   │
+│         │                 │                                 │   │
+│         │                 │   # LLM writes Python code:     │   │
+│         │                 │   for line in context.split():  │   │
+│         │                 │       if "magic" in line:       │   │
+│         │                 │           result = llm_query(   │   │
+│         │                 │               f"Analyze: {line}"│   │
+│         │                 │           )                     │   │
+│         │                 │                                 │   │
+│         │                 └───────────────┬─────────────────┘   │
+│         │                                 │                     │
+│         │                                 ▼                     │
+│         │                       ┌─────────────────┐             │
+│         │                       │    Sub LLM      │             │
+│         │                       │  (gpt-5-mini)   │             │
+│         │                       └─────────────────┘             │
+│         │                                                       │
+│         ▼                                                       │
+│   ┌─────────────┐                                               │
+│   │   Answer    │                                               │
+│   └─────────────┘                                               │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+1. **Main LLM** receives the query and writes Python code
+2. **REPL Environment** executes code with access to `context` variable
+3. **llm_query()** delegates semantic analysis to a cheaper/faster sub-model
+4. **Main LLM** synthesizes the final answer from code execution results
+
+---
+
+## Examples
+
+### Needle in Haystack
+
+Find specific information in massive text:
+
+```python
+from pydantic_ai_rlm import run_rlm_analysis
+
+# 1 million lines of text with a hidden number
+massive_text = generate_haystack(num_lines=1_000_000)
+
+answer = await run_rlm_analysis(
+    context=massive_text,
+    query="Find the magic number hidden in the text",
+    model="openai:gpt-5",
+    sub_model="openai:gpt-5-mini",
+)
+```
+
+### JSON Data Analysis
+
+Works with structured data too:
+
+```python
+from pydantic_ai_rlm import create_rlm_agent, RLMDependencies
+
+agent = create_rlm_agent(model="openai:gpt-5")
+
+deps = RLMDependencies(
+    context={"users": [...], "transactions": [...], "logs": [...]},
+)
+
+result = await agent.run(
+    "Find all users with suspicious transaction patterns",
+    deps=deps,
+)
+```
+
+---
+
+## API Reference
+
+### `create_rlm_agent()`
+
+Create a Pydantic AI agent with RLM capabilities.
+
+```python
+agent = create_rlm_agent(
+    model="openai:gpt-5",           # Main model for orchestration
+    sub_model="openai:gpt-5-mini",  # Model for llm_query() (optional)
+    code_timeout=60.0,               # Timeout for code execution
+    custom_instructions="...",       # Additional instructions
+)
+```
+
+### `create_rlm_toolset()`
+
+Create a standalone RLM toolset for composition.
+
+```python
+toolset = create_rlm_toolset(
+    code_timeout=60.0,
+    sub_model="openai:gpt-5-mini",
+)
+```
+
+### `run_rlm_analysis()` / `run_rlm_analysis_sync()`
+
+Convenience functions for quick analysis.
+
+```python
+# Async
+answer = await run_rlm_analysis(context, query, model="openai:gpt-5")
+
+# Sync
+answer = run_rlm_analysis_sync(context, query, model="openai:gpt-5")
+```
+
+### `RLMDependencies`
+
+Dependencies for RLM agents.
+
+```python
+deps = RLMDependencies(
+    context="...",  # str, dict, or list
+    config=RLMConfig(
+        code_timeout=60.0,
+        truncate_output_chars=50_000,
+        sub_model="openai:gpt-5-mini",
+    ),
+)
+```
+
+### `configure_logging()`
+
+Enable verbose logging to see what the agent is doing in real-time.
+
+```python
+from pydantic_ai_rlm import configure_logging, run_rlm_analysis
+
+# Enable logging (uses rich if installed, falls back to plain text)
+configure_logging(enabled=True)
+
+# Now you'll see code executions and outputs in the terminal
+answer = await run_rlm_analysis(
+    context=massive_document,
+    query="Find the magic number",
+    model="openai:gpt-5",
+)
+
+# Disable logging when done
+configure_logging(enabled=False)
+```
+
+Install with rich logging support for syntax highlighting and styled output:
+```bash
+pip install pydantic-ai-rlm[logging]
+```
+
+Or install rich separately:
+```bash
+pip install rich
+```
+
+When enabled, you'll see:
+- Syntax-highlighted code being executed (with rich)
+- Execution results with status indicators (SUCCESS/ERROR)
+- Execution time for each code block
+- Variables created during execution
+- LLM sub-queries and responses (when using `llm_query()`)
+
+**Note:** Logging works without rich installed - it will use plain text output instead of styled panels
+
+---
+
+## REPL Environment
+
+The sandboxed REPL provides:
+
+| Feature | Description |
+|---------|-------------|
+| `context` variable | Your data loaded and ready to use |
+| `llm_query(prompt)` | Delegate to sub-model (if configured) |
+| Safe built-ins | `print`, `len`, `range`, etc. |
+| Common imports | `json`, `re`, `collections`, etc. |
+| Persistent state | Variables persist across executions |
+| Output capture | stdout/stderr returned to agent |
+
+**Blocked for security:** `eval`, `exec`, `compile`, `open` (outside temp dir)
+
+---
+
+## Related Projects
+
+- **[rlm](https://github.com/alexzhang13/rlm)** - Original RLM implementation by Alex L. Zhang, Tim Kraska, and Omar Khattab
+- **[rlm-minimal](https://github.com/alexzhang13/rlm-minimal)** - Minal RLM implementation by Alex L. Zhang
+- **[pydantic-ai](https://github.com/pydantic/pydantic-ai)** - The foundation: Agent framework by Pydantic
+- **[pydantic-deep](https://github.com/vstorm-co/pydantic-deepagents)** - Full deep agent framework with planning, filesystem, and more
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/vstorm-co/pydantic-ai-rlm.git
+cd pydantic-ai-rlm
+pip install -e ".[dev]"
+pytest
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE)
+
+<p align="center">
+  <sub>Built with Pydantic AI by <a href="https://github.com/vstorm-co">vstorm-co</a></sub>
+</p>