Skip to content

Types API

FileInfo

pydantic_ai_backends.types.FileInfo

Bases: TypedDict

Information about a file or directory.

Source code in src/pydantic_ai_backends/types.py
Python
19
20
21
22
23
24
25
class FileInfo(TypedDict):
    """Information about a file or directory."""

    name: str
    path: str
    is_dir: bool
    size: int | None
Python
from pydantic_ai_backends import FileInfo

# Example
file_info: FileInfo = {
    "name": "app.py",
    "path": "/workspace/app.py",
    "is_dir": False,
    "size": 1234,
}

FileData

pydantic_ai_backends.types.FileData

Bases: TypedDict

Data structure for storing file content in StateBackend.

Source code in src/pydantic_ai_backends/types.py
Python
11
12
13
14
15
16
class FileData(TypedDict):
    """Data structure for storing file content in StateBackend."""

    content: list[str]  # Lines of the file
    created_at: str  # ISO 8601 timestamp
    modified_at: str  # ISO 8601 timestamp
Python
from pydantic_ai_backends import FileData

# Example (used internally by StateBackend)
file_data: FileData = {
    "content": ["line 1", "line 2", "line 3"],
    "created_at": "2024-01-15T10:30:00Z",
    "modified_at": "2024-01-15T11:00:00Z",
}

WriteResult

pydantic_ai_backends.types.WriteResult dataclass

Result of a write operation.

Source code in src/pydantic_ai_backends/types.py
Python
28
29
30
31
32
33
@dataclass
class WriteResult:
    """Result of a write operation."""

    path: str | None = None
    error: str | None = None
Python
from pydantic_ai_backends import WriteResult

# Success
result = WriteResult(path="/workspace/app.py")

# Error
result = WriteResult(error="Permission denied")

EditResult

pydantic_ai_backends.types.EditResult dataclass

Result of an edit operation.

Source code in src/pydantic_ai_backends/types.py
Python
36
37
38
39
40
41
42
@dataclass
class EditResult:
    """Result of an edit operation."""

    path: str | None = None
    error: str | None = None
    occurrences: int | None = None
Python
from pydantic_ai_backends import EditResult

# Success
result = EditResult(path="/workspace/app.py", occurrences=3)

# Error
result = EditResult(error="String not found")

ExecuteResponse

pydantic_ai_backends.types.ExecuteResponse dataclass

Response from command execution in a sandbox.

Source code in src/pydantic_ai_backends/types.py
Python
45
46
47
48
49
50
51
@dataclass
class ExecuteResponse:
    """Response from command execution in a sandbox."""

    output: str
    exit_code: int | None = None
    truncated: bool = False
Python
from pydantic_ai_backends import ExecuteResponse

# Example
response = ExecuteResponse(
    output="Hello, World!\n",
    exit_code=0,
    truncated=False,
)

GrepMatch

pydantic_ai_backends.types.GrepMatch

Bases: TypedDict

A single grep match result.

Source code in src/pydantic_ai_backends/types.py
Python
54
55
56
57
58
59
class GrepMatch(TypedDict):
    """A single grep match result."""

    path: str
    line_number: int
    line: str
Python
from pydantic_ai_backends import GrepMatch

# Example
match: GrepMatch = {
    "path": "/workspace/app.py",
    "line_number": 42,
    "line": "def hello_world():",
}

RuntimeConfig

pydantic_ai_backends.types.RuntimeConfig

Bases: BaseModel

Configuration for a Docker runtime environment.

A runtime defines a pre-configured execution environment with specific packages and settings. Can be used with DockerSandbox to provide ready-to-use environments without manual package installation.

Example
Python
from pydantic_ai_backends import RuntimeConfig, DockerSandbox

# Custom runtime with ML packages
ml_runtime = RuntimeConfig(
    name="ml-env",
    description="Machine learning environment",
    base_image="python:3.12-slim",
    packages=["torch", "transformers", "datasets"],
)

sandbox = DockerSandbox(runtime=ml_runtime)
Source code in src/pydantic_ai_backends/types.py
Python
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
class RuntimeConfig(BaseModel):
    """Configuration for a Docker runtime environment.

    A runtime defines a pre-configured execution environment with specific
    packages and settings. Can be used with DockerSandbox to provide
    ready-to-use environments without manual package installation.

    Example:
        ```python
        from pydantic_ai_backends import RuntimeConfig, DockerSandbox

        # Custom runtime with ML packages
        ml_runtime = RuntimeConfig(
            name="ml-env",
            description="Machine learning environment",
            base_image="python:3.12-slim",
            packages=["torch", "transformers", "datasets"],
        )

        sandbox = DockerSandbox(runtime=ml_runtime)
        ```
    """

    name: str
    """Unique name for the runtime (e.g., "python-datascience")."""

    description: str = ""
    """Human-readable description of the runtime."""

    # Image source (one of these)
    image: str | None = None
    """Ready-to-use Docker image (e.g., "myregistry/python-ds:v1")."""

    base_image: str | None = None
    """Base image to build upon (e.g., "python:3.12-slim")."""

    # Packages to install (only if base_image)
    packages: list[str] = []
    """Packages to install (e.g., ["pandas", "numpy", "matplotlib"])."""

    package_manager: Literal["pip", "npm", "apt", "cargo"] = "pip"
    """Package manager to use for installation."""

    # Additional configuration
    setup_commands: list[str] = []
    """Additional setup commands to run (e.g., ["apt-get update"])."""

    env_vars: dict[str, str] = {}
    """Environment variables to set in the container."""

    work_dir: str = "/workspace"
    """Working directory inside the container."""

    # Cache settings
    cache_image: bool = True
    """Whether to cache the built image locally."""

name instance-attribute

Unique name for the runtime (e.g., "python-datascience").

description = '' class-attribute instance-attribute

Human-readable description of the runtime.

image = None class-attribute instance-attribute

Ready-to-use Docker image (e.g., "myregistry/python-ds:v1").

base_image = None class-attribute instance-attribute

Base image to build upon (e.g., "python:3.12-slim").

packages = [] class-attribute instance-attribute

Packages to install (e.g., ["pandas", "numpy", "matplotlib"]).

package_manager = 'pip' class-attribute instance-attribute

Package manager to use for installation.

setup_commands = [] class-attribute instance-attribute

Additional setup commands to run (e.g., ["apt-get update"]).

env_vars = {} class-attribute instance-attribute

Environment variables to set in the container.

work_dir = '/workspace' class-attribute instance-attribute

Working directory inside the container.

cache_image = True class-attribute instance-attribute

Whether to cache the built image locally.

Python
from pydantic_ai_backends import RuntimeConfig

# Custom runtime
runtime = RuntimeConfig(
    name="ml-env",
    base_image="python:3.12-slim",
    packages=["torch", "transformers"],
    env_vars={"PYTHONUNBUFFERED": "1"},
    work_dir="/workspace",
)