openrat 0.1.0

OpenRat: experiment orchestration and sandboxed execution framework

openrat

Your personal AI lab rat

Openrat is a research‑first, privacy‑preserving experiment agent designed to run, debug, chain, schedule, and report computational experiments while you go about your day.

It is built for researchers and research institutions who want automation without losing control, reproducibility, or interpretability.

What Openrat does

• Runs experiments in Docker with sandboxed execution
• Diagnoses failures and reports actionable diagnostics
• Chains and branches experiments based on results
• Safely applies bounded, auditable changes (e.g. configs, hyperparameters)
• Generates diagnostic artifacts (summaries, diffs, metrics, plots)
• Cluster / remote execution (coming soon)
• Optional email notifications (coming soon)

Openrat is editor‑agnostic (VS Code, Neovim, any IDE) and shell‑based by design.

Installation

Install from PyPI:

pip install openrat

For local development:

pip install -e .

Research‑first by design. Openrat is not a generic AI coding agent.

• It does not rewrite large portions of your codebase
• It preserves research intent and reproducibility
• All actions are explicit, logged, and reversible
• A human remains in the loop whenever ambiguity or risk arises

For larger changes, Openrat proposes patches with explanations rather than applying them automatically.

Bounded autonomy (capability‑scoped) Openrat uses graduated autonomy levels, enforced outside the model:

• Level 0 — Observe only: run, diagnose, report
• Level 1 — Parameter autonomy: modify configs and hyperparameters
• Level 2 — Runtime repair: apply minimal fixes for common runtime errors (with safeguards)
• Level 3 — Extended edits (opt‑in): larger patches within explicitly allowed scope

Openrat cannot increase its own autonomy. All permissions are user‑controlled and auditable.

Governance is configured via Session:

from openrat import Openrat, Session, AutonomyLevel

# Allow only observation (run, diagnose)
session = Session(
    autonomy=AutonomyLevel.OBSERVE,
    patch_policy="disabled"
)

# Build and execute plan within governance constraints
app = Openrat({"executor": "docker", "docker_image": "python:3.11"})
plan = app.build_plan(spec, session)
artifact = app.execute_plan(plan)

Experiment chaining & branching Openrat can:

• Run experiments sequentially or in parallel
• Branch based on metrics, failures, or diagnostics
• Modify parameters or select follow‑up experiments conditionally

Example: Run experiment B only if validation loss improves after experiment A. Chaining logic can be defined via natural language or structured instruction files (.yaml, .json, .md) for maximum reliability.

Model‑agnostic

• Supports local open‑source models or cloud models (GPT, Gemini)

Privacy & security

• Local runs
• No code, data, or experiments leave your machine unless you choose
• Remote control workflows (coming soon; see ROADMAP.md)
• Autonomy and permissions are enforced by policy, not by the model

Development

Run tests:

pytest tests/ -q

Set executor policy to production (default is auto):

Pytesting with EXECUTOR_POLICY=production pytest tests/

Usage Guide

1. Quick Execution (Simplest)

Run a script and capture output:

from openrat import Openrat

app = Openrat({"executor": "docker", "docker_image": "python:3.11"})
result = app.run(
    "experiments/train.py",
    timeout=120,
    isolate=True,    # copies script to temp dir for safety
    memory="1g",
    cpus="2.0",
)

print(result["stdout"])
print(f"Exit code: {result['return_code']}")

See examples/run_experiment.py for a complete example.

Examples require Docker to be running.

2. Framework Workflow (Recommended)

Build and execute an experiment plan with governance:

from openrat import Openrat, Session, AutonomyLevel, ExperimentSpec

# Create a session (defines autonomy and governance)
session = Session(
    autonomy=AutonomyLevel.OBSERVE,
    patch_policy="disabled",
)

# Define your experiment
spec = ExperimentSpec(
    goals=["Train model", "Evaluate"],
    metrics=["accuracy"],
    tasks=[...],
)

# Build and execute plan
app = Openrat({"executor": "docker", "docker_image": "python:3.11"})
plan = app.build_plan(spec, session)
artifact = app.execute_plan(plan, session, tools={...})

# Access results
print(artifact.status)
print(artifact.governance_report())

3. LLM Agent Loop (Chat Interface)

Let a language model decide which experiments to run and interpret results:

from openrat import Openrat, Message
import os

app = Openrat({
    "executor": "docker",
    "docker_image": "python:3.11",
    "provider": "openai_compatible",
    "base_url": "https://api.openai.com/v1",
    "api_key": os.environ["OPENAI_API_KEY"],
    "model_name": "gpt-4o",
})

# Chat with the model; it can call tools to run experiments
messages = [
    Message(role="system", content="You are a research assistant."),
    Message(role="user", content="Run experiments/train.py and summarize the results."),
]

response = app.chat(messages, max_turns=5)
print(response.content)

See examples/chat_agent.py for a complete example.

4. Custom Tools (Advanced)

Register custom functions that the LLM can call:

from openrat import Openrat

def read_metrics(arguments: dict) -> dict:
    """Custom tool callable by the LLM."""
    metric = arguments.get("metric", "accuracy")
    # Implement your metric reading logic
    return {"metric": metric, "value": 0.95}

app = Openrat({
    "provider": "openai_compatible",
    "api_key": "...",
    "model_name": "...",
    "autonomy": 3,
    "user_approvals": {"host.exec"},
})

# Untrusted callable tools require explicit host.exec opt-in
app.tool_registry.register("read_metrics", read_metrics, capability="host.exec")

# Now the LLM can call this tool
response = app.chat("Check the accuracy metric for me.")

See examples/custom_tool.py for a complete example.

Session & Governance

Every execution runs within a Session that defines:

• Autonomy level — what the agent can do (observe, modify params, apply fixes, edit code)
• Patch policy — whether patches are proposed (disabled) or auto-applied
• Approval scope — which capabilities require explicit approval

All governance decisions are logged in an immutable audit trail, captured in the final Artifact:

artifact.governance_report()
# {
#   "session_id": "...",
#   "autonomy": 0,  # Level 0 = observe only
#   "used_capabilities": ["observe"],
#   "blocked_capabilities": [],
#   "patches_proposed": [],
#   "events": [...]  # Full audit trail
# }

Executor policy

All execution is routed through the DockerExecutor, which runs scripts in an ephemeral container with --network none, --security-opt no-new-privileges, --cap-drop=ALL, --read-only, --tmpfs /tmp, --pids-limit 100, and bounded memory/CPU limits.

Openrat is safe-by-default for execution limits:

• default timeout: 300s
• max timeout: 3600s
• default memory: 512m (max 4g)
• default CPU: 1.0 (max 4.0)

Unbounded limits are blocked unless explicitly enabled by user config (allow_unbounded_limits=True).

from openrat.executors import set_executor_policy

# Both modes register the DockerExecutor (the only available backend)
set_executor_policy("production")   # explicit
set_executor_policy("auto")          # default

Roadmap

Planned items for v0.2+ and v0.3 are tracked in ROADMAP.md.