abi-runtime

Sandboxed file operations and model provider abstraction for AI agent execution. Enforce workspace boundaries, path allowlists, and provider-agnostic model calls.

Zero dependencies.

Install (after PyPI publication)

pip install abi-runtime

Status: Not yet published to PyPI. Install from source: pip install -e . from the repo root.

Quick start

Workspace sandbox

from pathlib import Path
from abi_runtime.sandbox import WorkspaceSandbox

# Create a sandbox rooted at the current workspace
sandbox = WorkspaceSandbox(
    workspace_root=Path("."),
    allow_patterns=["src/**", "tests/**"],
    deny_patterns=["*.env", ".git/**", "node_modules/**"],
)

# Safe file operations — path traversal and symlink escapes are blocked
content = sandbox.safe_read("src/main.py")
sandbox.safe_write("tests/output.txt", "result data")
files = sandbox.safe_list("src/")

Provider abstraction

from abi_runtime.providers import MockProvider, ProviderSettings

# Use the mock provider for deterministic testing
provider = MockProvider(default_response="Test output")
provider.set_response("auth", "OAuth2 implementation plan")

response = provider.generate("Design an auth system")
print(response.text)   # "OAuth2 implementation plan"
print(response.usage)  # {"input_tokens": ..., "output_tokens": ...}

# All invocations are recorded for assertions
assert len(provider.invocations) == 1

What's included

• WorkspaceSandbox -- sandboxed file operations with workspace root enforcement, path traversal blocking, and symlink escape detection
• Provider abstraction -- Provider protocol with MockProvider for testing and LocalProviderStub for offline use
• Allowlist/denylist -- declarative control over which files an agent can read and write
• Deterministic temp dirs -- hash-based temp directories for reproducible runs
• Runtime context capture -- environment metadata collection with secret redaction

ABI ecosystem

Related packages:

• abi-control-core -- contracts and audit trail SDK
• abi-policy -- policy evaluation engine
• abi-observability -- OTLP-compliant telemetry

Versioning

Follows Semantic Versioning. Current version: 0.1.2. See CHANGELOG.md for release notes.

License

MIT License (see LICENSE file).