openrat 0.1.0__tar.gz

openrat-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenRat contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

openrat-0.1.0/PKG-INFO

@@ -0,0 +1,295 @@
+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`.

openrat-0.1.0/README.md

@@ -0,0 +1,275 @@
+# 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`.

openrat-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "openrat"
+version = "0.1.0"
+description = "OpenRat: experiment orchestration and sandboxed execution framework"
+readme = "README.md"
+authors = [{ name = "OpenRat contributors" }]
+license = "MIT"
+requires-python = ">=3.11"
+dependencies = ["requests>=2.0"]
+keywords = ["experiments", "orchestration", "automation", "research", "docker"]
+classifiers = [
+	"Development Status :: 3 - Alpha",
+	"Intended Audience :: Science/Research",
+	"Programming Language :: Python :: 3",
+	"Programming Language :: Python :: 3.11",
+	"Programming Language :: Python :: 3.12",
+	"Programming Language :: Python :: 3.13",
+	"Operating System :: OS Independent",
+]
+
+[project.scripts]
+openrat = "ui.cli:main"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["openrat*", "ui*"]

openrat-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

openrat-0.1.0/src/openrat/__init__.py

@@ -0,0 +1,54 @@
+from importlib import import_module
+
+"""OpenRat: Experiment execution framework with planning & autonomy.
+
+Primary Public API:
+  Openrat: Framework workflow (session → spec → plan → artifact)
+
+Data Types & Governance:
+  ExperimentSpec: Experiment intent definition
+  Session, AutonomyLevel: Execution authority & governance
+  Artifact: Execution results
+
+Extension Points:
+  BaseTool: Tool implementation framework
+  ToolRegistry: Named tool registry
+
+For workflow documentation, see docs/AGENTS.md.
+For executor configuration, see docs/EXECUTOR_POLICY.md.
+"""
+
+__all__ = [
+	"Openrat",
+	"BaseTool",
+	"Artifact",
+	"ExperimentSpec",
+	"Session",
+	"Message",
+	"ModelResponse",
+	"AutonomyLevel",
+]
+
+
+_EXPORTS = {
+	"Openrat": ("openrat.api.openrat", "Openrat"),
+	"BaseTool": ("openrat.tools.base", "BaseTool"),
+	"Artifact": ("openrat.core.artifact", "Artifact"),
+	"ExperimentSpec": ("openrat.core.experiment_spec", "ExperimentSpec"),
+	"Session": ("openrat.core.session.session", "Session"),
+	"Message": ("openrat.model.types", "Message"),
+	"ModelResponse": ("openrat.model.types", "ModelResponse"),
+	"AutonomyLevel": ("openrat.core.governance.autonomy", "AutonomyLevel"),
+}
+
+
+def __getattr__(name):
+	if name not in _EXPORTS:
+		raise AttributeError(name)
+
+	module_name, symbol = _EXPORTS[name]
+	module = import_module(module_name)
+	value = getattr(module, symbol)
+	globals()[name] = value
+	return value
+

openrat-0.1.0/src/openrat/__main__.py

@@ -0,0 +1,5 @@
+from ui.cli import main
+
+
+if __name__ == "__main__":
+	raise SystemExit(main())