avo 0.1.2

Provider-agnostic reliability runtime for bounded, observable, resumable, replayable AI agent loops.

Bounded. Resumable. Provider-agnostic. Honest about why it stopped.

⚠️ 0.1 is an alpha foundation. Suitable for evaluation, deterministic tests, and local prototypes; not production-ready.

Install

Requires Python 3.11+. Core runtime depends only on Pydantic.

git clone https://github.com/Fqih/avo.git
cd avo
python -m pip install -e ".[dev,providers,sandbox]"

Optional extras

Verify the install:

avo doctor

Prints resolved provider / model / endpoint without an HTTP call — cheapest smoke test.

Quickstart

One typed tool call, then a final reply. No API key:

import asyncio
from pydantic import BaseModel

from avo import (
    AgentRuntime, FunctionTool, ModelResponse, TokenUsage, ToolCall,
)
from avo.providers import FakeProvider


class AddArguments(BaseModel):
    left: int
    right: int


async def add(arguments: AddArguments) -> object:
    return {"sum": arguments.left + arguments.right}


async def main() -> None:
    provider = FakeProvider(
        [
            ModelResponse(
                tool_call=ToolCall(
                    tool_call_id="addition-1", name="add",
                    arguments={"left": 2, "right": 3},
                ),
                usage=TokenUsage(input_tokens=12, output_tokens=5),
            ),
            ModelResponse(
                content="The sum is 5.",
                usage=TokenUsage(input_tokens=18, output_tokens=6),
            ),
        ]
    )

    runtime = AgentRuntime(
        provider=provider,
        tools=[
            FunctionTool(
                name="add",
                description="Add two integers.",
                arguments_model=AddArguments,
                function=add,
            )
        ],
    )
    result = await runtime.run("What is 2 + 3?")
    print(result.status.value, result.stop_reason.value, result.output)


asyncio.run(main())

examples/basic_agent.py ships this runnable end-to-end.

Configuration

All knobs live in AVO_* env vars. The chat REPL's first-run wizard can persist them to ~/.zshrc / ~/.bashrc.

Provider selection

Runtime + policy

See .env.example for a copy-paste template.

Providers

All four implement the same ModelProvider Protocol. Swapping providers is one line.

Application tools

avo.app_tools is the optional-but-default toolkit. Tools plug into the existing FunctionTool / ToolRegistry contract — no changes to the runtime, state machine, or event log.

Workspace safety

Workspace(root).validate_path(...) rejects ../, symlink escapes, absolute-path escapes, and null bytes before any I/O. validate_for_write refuses to follow symlinks at the leaf or any parent. write_file / edit_file open with O_NOFOLLOW on POSIX. No path the model can ask for exits the workspace root.

Shell sandbox

SandboxExecutor wraps docker-py. Each run_shell call creates a fresh container (remove=True), runs with network_mode="none" by default, applies a mem_limit and cpu_quota, times out via the runtime's LoopPolicy.tool_timeout_seconds, and removes the container before returning. run_shell never calls subprocess on the host — the sandbox is the only path to the shell.

Suit the network policy to your task:

from avo.app_tools.sandbox import SandboxExecutor

sandbox = SandboxExecutor(
    network_mode="bridge",  # default "none" — switch when network is required
    mem_limit="512m",
    cpu_quota=100000,
)

Approval policy

AVO_TOOLS_REQUIRE_APPROVAL lists tool names that must wait for explicit operator approval. Tools not in the list auto-approve. Wire a custom callback:

from avo.app_tools.approval import build_approval_callback

callback = build_approval_callback(
    on_require=lambda call: input(f"approve {call.name}? [y/N] ").lower() == "y",
)
runtime = AgentRuntime(provider=provider, tools=[...], approval_callback=callback)

CLI

avo [-d DATABASE] <command> [args]

Chat REPL slash commands

Examples

examples/ ships runnable Python files, all offline (no API key):

python examples/basic_agent.py
python examples/repeated_action.py
python examples/resume_after_interrupt.py
python examples/app_tools_demo.py

Development

python -m pip install -e ".[dev,providers,sandbox]"
ruff check .
ruff format --check .
mypy src/avo
pytest

Quality gates:

• ruff lint + format — line-length 100, per-file ignores for examples/, benchmark/.
• mypy strict on src/avo (Pydantic plugin).
• pytest --strict-config --strict-markers, asyncio mode auto.
• coverage branch coverage, fail-under 90%.

The suite needs no Docker — SandboxExecutor accepts an injectable client so tests inject a fake and assert the container config that would be sent. Live Docker integration is opt-in, same pattern as benchmark/live/tests/.

License

MIT — see LICENSE.