pydantic-ai-backend
File storage and sandbox backends for AI agents. Works with pydantic-ai and pydantic-deep.
Features
- BackendProtocol - Unified interface for file operations
- StateBackend - In-memory storage (perfect for testing)
- FilesystemBackend - Real filesystem with path sandboxing
- CompositeBackend - Route operations to different backends by path
- DockerSandbox - Isolated Docker containers with command execution
- SessionManager - Multi-user session management for Docker sandboxes
- RuntimeConfig - Pre-configured Docker environments
Installation
pip install pydantic-ai-backend
With Docker sandbox support:
pip install pydantic-ai-backend[docker]
Quick Start
In-Memory Backend (Testing)
from pydantic_ai_backends import StateBackend
backend = StateBackend()
# Write a file
backend.write("/src/app.py", "print('hello')")
# Read it back (with line numbers)
content = backend.read("/src/app.py")
print(content) # " 1\tprint('hello')"
# Search files
matches = backend.grep_raw("print")
Filesystem Backend
from pydantic_ai_backends import FilesystemBackend
backend = FilesystemBackend("/path/to/workspace")
# All operations are sandboxed to the root directory
backend.write("/data/file.txt", "content")
files = backend.glob_info("**/*.py")
Composite Backend
from pydantic_ai_backends import CompositeBackend, StateBackend, FilesystemBackend
backend = CompositeBackend(
default=StateBackend(), # For unmatched paths
routes={
"/project/": FilesystemBackend("/my/project"),
"/workspace/": FilesystemBackend("/tmp/workspace"),
},
)
# Routes to FilesystemBackend
backend.write("/project/app.py", "...")
# Routes to StateBackend (default)
backend.write("/temp/scratch.txt", "...")
Docker Sandbox
from pydantic_ai_backends import DockerSandbox
sandbox = DockerSandbox(image="python:3.12-slim")
try:
# Write and execute
sandbox.write("/workspace/script.py", "print(1 + 1)")
result = sandbox.execute("python /workspace/script.py")
print(result.output) # "2"
finally:
sandbox.stop()
Docker Sandbox with Runtime Config
from pydantic_ai_backends import DockerSandbox, RuntimeConfig
# Custom runtime with packages pre-installed
runtime = RuntimeConfig(
name="ml-env",
base_image="python:3.12-slim",
packages=["pandas", "numpy", "scikit-learn"],
)
sandbox = DockerSandbox(runtime=runtime)
result = sandbox.execute("python -c 'import pandas; print(pandas.__version__)'")
Built-in Runtimes
from pydantic_ai_backends import DockerSandbox
# Use a built-in runtime by name
sandbox = DockerSandbox(runtime="python-datascience")
# Available runtimes:
# - python-minimal: Clean Python 3.12
# - python-datascience: pandas, numpy, matplotlib, scikit-learn, seaborn
# - python-web: FastAPI, SQLAlchemy, httpx
# - node-minimal: Clean Node.js 20
# - node-react: TypeScript, Vite, React
Session Manager (Multi-User)
from pydantic_ai_backends import SessionManager
manager = SessionManager(default_runtime="python-datascience")
# Get or create sandbox for user
sandbox = await manager.get_or_create("user-123")
# Use the sandbox...
result = sandbox.execute("python script.py")
# Cleanup idle sessions
cleaned = await manager.cleanup_idle(max_idle=1800)
# Shutdown all sessions
await manager.shutdown()
Backend Protocol
All backends implement BackendProtocol:
class BackendProtocol(Protocol):
def ls_info(self, path: str) -> list[FileInfo]: ...
def read(self, path: str, offset: int = 0, limit: int = 2000) -> str: ...
def write(self, path: str, content: str | bytes) -> WriteResult: ...
def edit(self, path: str, old: str, new: str, replace_all: bool = False) -> EditResult: ...
def glob_info(self, pattern: str, path: str = "/") -> list[FileInfo]: ...
def grep_raw(self, pattern: str, path: str | None = None, glob: str | None = None) -> list[GrepMatch] | str: ...
SandboxProtocol extends this with command execution:
class SandboxProtocol(BackendProtocol, Protocol):
def execute(self, command: str, timeout: int | None = None) -> ExecuteResponse: ...
@property
def id(self) -> str: ...
Integration with pydantic-ai
from pydantic_ai import Agent
from pydantic_ai_backends import StateBackend
# Use backends with any pydantic-ai agent
backend = StateBackend()
# Your agent can use backend for file operations
# See pydantic-deep for full integration
Development
# Clone and install
git clone https://github.com/vstorm-co/pydantic-ai-backend.git
cd pydantic-ai-backend
make install
# Run tests
make test
# Run all checks
make all
License
MIT License - see LICENSE for details.
1 maintainer
Metadata
1 maintainer
Release files for pydantic-ai-backend 0.0.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| pydantic_ai_backend-0.0.3.tar.gz | 35.9 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| pydantic_ai_backend-0.0.3-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 63.2 kB
Release files / pydantic_ai_backend-0.0.3.tar.gz
| Download URL | pydantic_ai_backend-0.0.3.tar.gz |
|---|---|
| Size | 35.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
3a91268ea43c82231429d9f21f7b17d1265c9e8f702c8f728e84e16f919d6eff
|
|
BLAKE2b-256 checksum How to use checksums |
508437c8af42b491346b9d76b5f71b6ea6164386c19fbb77da7b1fe335b60a47
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 28, 2025.
Transparency logRelease files / pydantic_ai_backend-0.0.3-py3-none-any.whl
| Download URL | pydantic_ai_backend-0.0.3-py3-none-any.whl |
|---|---|
| Size | 27.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
eeb07d0cbacfb13c4fc73872eb798da48a6fd1778b56d1d4bf40607ad00dcead
|
|
BLAKE2b-256 checksum How to use checksums |
de8a8e40d4b5a18294143aac4feedaf16c3ce483f4a29a278fa33351dadeb2c2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Dec 28, 2025.
Transparency log
