Metadata-Version: 2.4
Name: openrat
Version: 0.1.0
Summary: OpenRat: experiment orchestration and sandboxed execution framework
Author: OpenRat contributors
License-Expression: MIT
Keywords: experiments,orchestration,automation,research,docker
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.0
Dynamic: license-file

# 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:

```bash
pip install openrat
```

For local development:

```bash
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`:

```python
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:

```bash
pytest tests/ -q
```

Set executor policy to production (default is `auto`):

```bash
Pytesting with EXECUTOR_POLICY=production pytest tests/
```


## Usage Guide

### 1. Quick Execution (Simplest)

Run a script and capture output:

```python
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:

```python
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:

```python
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:

```python
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`:

```python
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`).

```python
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`.
