pydantic-ai-rlm 0.1.0__py3-none-any.whl

pydantic_ai_rlm-0.1.0.dist-info/METADATA

@@ -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>

pydantic_ai_rlm-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pydantic_ai_rlm/__init__.py,sha256=94ev1VspkrVdB-PabCD6I791vZkBVASXv_qqneYQQ0I,794
+pydantic_ai_rlm/agent.py,sha256=_zHBLatfhquGw3vjHC06b0lBZRpLv2nrxi7w69f7lBY,4824
+pydantic_ai_rlm/dependencies.py,sha256=bzPXhCRJ-0D5N0FS32LAETXxp6cbInU00qaMr0qd_iQ,1306
+pydantic_ai_rlm/logging.py,sha256=DXJzfrfOnyR3VAbKF4_0Mc2MP7zqPmxyFDph4Q9kAb0,9308
+pydantic_ai_rlm/prompts.py,sha256=BpbugghZ_I_IjC_Il5pUClMG7bgWfzWgtsUsxwyjH10,3648
+pydantic_ai_rlm/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pydantic_ai_rlm/repl.py,sha256=twn6ArhaONYg49Feoi-sD6z0HkYHyHHc-prdBCsj0jo,14864
+pydantic_ai_rlm/toolset.py,sha256=g1244qq2VzaQVhAQixLGPCWW7vJqQfjhUgf0kDxkkzo,5564
+pydantic_ai_rlm/utils.py,sha256=_tqdMcD-_UbRbdK6ECD-XlXfRHgeAKj7ulLaXrYOJx4,1500
+pydantic_ai_rlm-0.1.0.dist-info/METADATA,sha256=2w1yJoJGl5HHCWcl6JRz5pDys0o4iBTLcWSsXuGt8nk,11613
+pydantic_ai_rlm-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+pydantic_ai_rlm-0.1.0.dist-info/licenses/LICENSE,sha256=ktSo7DxQBRIZIhD4P53iVxq88CG3cvXRTBRqPT8zO1c,1085
+pydantic_ai_rlm-0.1.0.dist-info/RECORD,,

pydantic_ai_rlm-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pydantic_ai_rlm-0.1.0.dist-info/licenses/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.