openrat 0.1.0__py3-none-any.whl

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/__main__.py

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

openrat/api/__init__.py

@@ -0,0 +1,27 @@
+from importlib import import_module
+
+"""OpenRat API entry points.
+
+Public API:
+  - Openrat: Primary framework facade
+
+Internal runtime (not for external use):
+  - OpenRatAgent: Low-level runtime adapter
+  - run(): Direct execution helper
+"""
+
+__all__ = ["Openrat"]
+
+_EXPORTS = {
+	"Openrat": ("openrat.api.openrat", "Openrat"),
+}
+
+
+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/api/openrat.py

@@ -0,0 +1,109 @@
+from collections.abc import Iterable, Mapping
+from typing import Any, TYPE_CHECKING
+
+from openrat.core.artifact import Artifact
+from openrat.core.governance.autonomy import AutonomyLevel
+from openrat.core.experiment_spec import ExperimentSpec
+from openrat.core.session.session import Session
+from openrat.model.types import Message, ModelResponse
+from openrat.core.protocols import ToolProtocol, ToolRegistryProtocol
+from openrat.tasks.plan.plan import Plan
+
+if TYPE_CHECKING:
+    from .runner import OpenRatAgent
+
+
+class Openrat:
+    """Framework facade for experiment orchestration.
+
+    Orchestrates the workflow:
+    1. create_session() — define autonomy and governance
+    2. build_plan() — construct execution plan from spec
+    3. execute_plan() — execute with policy approval
+
+    Also provides direct execution (app.run()) and LLM loops (app.chat())
+    for convenience, though the framework workflow is recommended.
+    """
+
+    def __init__(self, config: Mapping[str, Any] | None = None):
+        self._config = dict(config or {})
+        self._agent: "OpenRatAgent | None" = None
+
+    def _ensure_agent(self) -> "OpenRatAgent":
+        if self._agent is None:
+            from .runner import OpenRatAgent
+
+            self._agent = OpenRatAgent(self._config)
+        return self._agent
+
+    @property
+    def tool_registry(self) -> ToolRegistryProtocol | None:
+        """Low-level tool registry (internal extension point).
+
+        This property is provided for advanced use cases that register custom tools
+        for the LLM loop. It is not part of the planned session/spec/plan/artifact
+        workflow and should be considered internal — subject to change.
+
+        For most use cases, use the framework workflow instead:
+            plan = app.build_plan(spec, session)
+            artifact = app.execute_plan(plan)
+        """
+        return getattr(self._ensure_agent(), "tool_registry", None)
+
+    def run(
+        self,
+        path: str,
+        timeout: int | None = None,
+        isolate: bool = True,
+        memory: str = "512m",
+        cpus: str = "1.0",
+    ) -> Mapping[str, Any]:
+        """Direct compatibility path (non-planned execution)."""
+        return self._ensure_agent().run(
+            path,
+            timeout=timeout,
+            isolate=isolate,
+            memory=memory,
+            cpus=cpus,
+        )
+
+    def chat(self, messages: str | list[Message], max_turns: int = 10) -> ModelResponse:
+        """Direct compatibility path to the low-level LLM agent loop."""
+        return self._ensure_agent().chat(messages, max_turns=max_turns)
+
+    def create_session(
+        self,
+        *,
+        autonomy: AutonomyLevel,
+        patch_policy: str,
+        user_approvals: Iterable[str] | None = None,
+    ) -> Session:
+        return Session(
+            autonomy=autonomy,
+            patch_policy=patch_policy,
+            user_approvals=set(user_approvals or set()),
+        )
+
+    def spec_from_final_json(self, data: Mapping[str, Any]) -> ExperimentSpec:
+        return ExperimentSpec.from_final_json(data)
+
+    def build_plan(
+        self,
+        spec: ExperimentSpec,
+        session: Session,
+        tool_capabilities: Mapping[str, str] | None = None,
+    ) -> Plan:
+        return Plan.build(spec, session, tool_capabilities=tool_capabilities)
+
+    def execute_plan(self, plan: Plan, session: Session, tools: Mapping[str, ToolProtocol]) -> Artifact:
+        plan.assert_executable()
+        plan.dag.execute(tools=tools, session=session)
+        return Artifact.from_dag_execution(
+            dag=plan.dag,
+            plan=plan,
+            session=session,
+            logs=(),
+            metrics={},
+            diagnostics={"governance": session.governance_report()},
+            patches_applied=tuple(p.get("patch_id", "") for p in session.patches_applied),
+        )

openrat/api/runner.py

@@ -0,0 +1,318 @@
+from pathlib import Path
+from collections.abc import Mapping
+from typing import Any
+import shutil
+import tempfile
+import re
+
+from openrat.core.governance.autonomy import AutonomyLevel
+from openrat.core.session.session import Session
+from openrat.executors import DockerExecutor
+from openrat.core.errors import UserInputError, EnvironmentError, InternalError
+from openrat.model.types import Message, ModelResponse
+from openrat.core.protocols import ExecutorProtocol, ToolRegistryProtocol
+from openrat.sandbox.guardrails import validate_command_guardrails
+
+
+DEFAULT_TIMEOUT_SECONDS = 300
+MAX_TIMEOUT_SECONDS = 3600
+DEFAULT_MEMORY_LIMIT = "512m"
+MAX_MEMORY_BYTES = 4 * 1024 * 1024 * 1024  # 4 GiB
+DEFAULT_CPU_LIMIT = "1.0"
+MAX_CPU_LIMIT = 4.0
+_MEMORY_RE = re.compile(r"^(\d+)([mMgG])$")
+
+
+def validate_experiment_path(path: str) -> Path:
+    """Validate and normalize an experiment file path.
+    
+    Internal utility; not part of public API.
+    
+    Raises:
+        EnvironmentError: If path is outside cwd or does not exist.
+    """
+    p = Path(path)
+    if not p.exists():
+        raise EnvironmentError(f"Experiment file not found: {path}")
+    p = p.resolve()
+    cwd = Path.cwd().resolve()
+    try:
+        p.relative_to(cwd)
+    except ValueError:
+        # restrict running experiments outside current working directory
+        # Invalid experiment path currently mapped to EnvironmentError. This could also be argued as UserInputError.
+        raise EnvironmentError("Experiment path must live inside the current working directory")
+    return p
+
+
+# Backward-compatible alias (private name indicates legacy)
+_validate_experiment_path = validate_experiment_path
+
+
+def _choose_executor(preferred: str | None, docker_image: str) -> ExecutorProtocol:
+    if preferred is not None and preferred != "docker":
+        raise UserInputError(
+            f"unsupported executor '{preferred}'",
+            hint="Openrat requires executor='docker'.",
+        )
+
+    if not shutil.which("docker"):
+        raise EnvironmentError(
+            "docker executor requested but docker is not available",
+            hint="Install Docker to run Openrat experiments.",
+        )
+
+    return DockerExecutor(image=docker_image)
+
+
+def _validate_managed_mount_path(path: Path, *, allowed_base: Path, label: str) -> str:
+    resolved = path.resolve()
+    base = allowed_base.resolve()
+    if not resolved.exists() or not resolved.is_dir():
+        raise InternalError(f"managed {label} must be an existing directory")
+    try:
+        resolved.relative_to(base)
+    except ValueError as exc:
+        raise InternalError(f"managed {label} escaped allowed execution base") from exc
+    if resolved.is_symlink():
+        raise InternalError(f"managed {label} must not be a symlink")
+    return str(resolved)
+
+
+def _memory_to_bytes(value: str) -> int:
+    match = _MEMORY_RE.match(value.strip())
+    if not match:
+        raise UserInputError("memory must match '<number><m|g>', e.g. '512m' or '1g'")
+
+    amount = int(match.group(1))
+    unit = match.group(2).lower()
+    if amount <= 0:
+        raise UserInputError("memory must be greater than zero")
+
+    if unit == "m":
+        return amount * 1024 * 1024
+    return amount * 1024 * 1024 * 1024
+
+
+def _normalize_timeout(timeout: int | None, *, allow_unbounded_limits: bool) -> int | None:
+    if timeout is None:
+        if allow_unbounded_limits:
+            return None
+        return DEFAULT_TIMEOUT_SECONDS
+
+    if not isinstance(timeout, int) or timeout <= 0:
+        raise UserInputError("timeout must be a positive integer")
+
+    if not allow_unbounded_limits and timeout > MAX_TIMEOUT_SECONDS:
+        raise UserInputError(f"timeout must be <= {MAX_TIMEOUT_SECONDS} seconds")
+
+    return timeout
+
+
+def _normalize_limits(
+    *,
+    timeout: int | None,
+    memory: str,
+    cpus: str,
+    allow_unbounded_limits: bool,
+) -> tuple[int | None, str, str]:
+    normalized_timeout = _normalize_timeout(timeout, allow_unbounded_limits=allow_unbounded_limits)
+
+    memory_limit = str(memory or DEFAULT_MEMORY_LIMIT).strip().lower()
+    if memory_limit in {"none", "unbounded", "unlimited"}:
+        if not allow_unbounded_limits:
+            raise UserInputError("unbounded memory requires explicit allow_unbounded_limits opt-in")
+    else:
+        memory_bytes = _memory_to_bytes(memory_limit)
+        if memory_bytes > MAX_MEMORY_BYTES:
+            raise UserInputError("memory exceeds maximum allowed limit of 4g")
+
+    cpu_limit = str(cpus or DEFAULT_CPU_LIMIT).strip().lower()
+    if cpu_limit in {"none", "unbounded", "unlimited"}:
+        if not allow_unbounded_limits:
+            raise UserInputError("unbounded CPU requires explicit allow_unbounded_limits opt-in")
+    else:
+        try:
+            cpu_value = float(cpu_limit)
+        except ValueError as exc:
+            raise UserInputError("cpus must be a numeric string") from exc
+
+        if cpu_value <= 0:
+            raise UserInputError("cpus must be greater than zero")
+        if cpu_value > MAX_CPU_LIMIT:
+            raise UserInputError(f"cpus must be <= {MAX_CPU_LIMIT}")
+
+    return normalized_timeout, memory_limit, cpu_limit
+
+
+def run(
+    path: str,
+    *,
+    executor: str | None = None,
+    timeout: int | None = None,
+    docker_image: str = "python:3.11",
+    isolate: bool = True,
+    memory: str = "512m",
+    cpus: str = "1.0",
+    allow_unbounded_limits: bool = False,
+) -> Mapping[str, Any]:
+    """Internal direct execution helper (not part of public API).
+    
+    By default this will copy the experiment into a per-run ephemeral directory
+    and execute inside that directory to limit filesystem access. The runner will
+    create separate `code/` (read-only) and `outputs/` (writable) mounts for Docker.
+    """
+    p = validate_experiment_path(path)
+    exec_obj = _choose_executor(executor, docker_image)
+
+    timeout_limit, memory_limit, cpu_limit = _normalize_limits(
+        timeout=timeout,
+        memory=memory,
+        cpus=cpus,
+        allow_unbounded_limits=allow_unbounded_limits,
+    )
+
+    if isolate:
+        with tempfile.TemporaryDirectory(prefix="openrat-run-") as td:
+            td_path = Path(td)
+            code_dir = td_path / "code"
+            outputs_dir = td_path / "outputs"
+            code_dir.mkdir()
+            outputs_dir.mkdir()
+            # copy experiment into code subdir
+            dest = code_dir / p.name
+            shutil.copy2(p, dest)
+
+            command = ["python", f"/code/{dest.name}"]
+            validate_command_guardrails(command)
+
+            payload = {
+                # run using container-local paths
+                "command": command,
+                "cwd": str(outputs_dir),
+                "timeout": timeout_limit,
+                "code_dir": _validate_managed_mount_path(code_dir, allowed_base=td_path, label="code_dir"),
+                "outputs_dir": _validate_managed_mount_path(outputs_dir, allowed_base=td_path, label="outputs_dir"),
+                "limits": {"memory": memory_limit, "cpus": cpu_limit},
+                "allow_unbounded_limits": allow_unbounded_limits,
+            }
+            result = exec_obj.execute(payload)
+            return result
+
+    command = ["python", str(p)]
+    validate_command_guardrails(command)
+
+    payload = {
+        "command": command,
+        "cwd": str(p.parent),
+        "timeout": timeout_limit,
+        "limits": {"memory": memory_limit, "cpus": cpu_limit},
+        "allow_unbounded_limits": allow_unbounded_limits,
+    }
+
+    result = exec_obj.execute(payload)
+    return result
+
+
+class OpenRatAgent:
+    """Internal runtime adapter (not part of public API).
+
+    Provides direct execution and LLM agent loop capabilities.
+    Internal use only; use Openrat facade for public workflows.
+
+    Configuration:
+      - Execution keys (``executor``, ``docker_image``) for direct paths
+      - Model keys (``provider``, ``api_key``, ``model_name``) for LLM loop
+    """
+
+    def __init__(self, config: Mapping[str, Any] | None = None):
+        self.config = dict(config or {})
+        self.executor = self.config.get("executor")
+        self.docker_image = self.config.get("docker_image", "python:3.11")
+        self.allow_unbounded_limits = bool(self.config.get("allow_unbounded_limits", False))
+
+        session_from_config = self.config.get("session")
+        if isinstance(session_from_config, Session):
+            self.session = session_from_config
+        else:
+            autonomy_raw = self.config.get("autonomy", AutonomyLevel.OBSERVE)
+            autonomy = autonomy_raw if isinstance(autonomy_raw, AutonomyLevel) else AutonomyLevel(int(autonomy_raw))
+            self.session = Session(
+                autonomy=autonomy,
+                patch_policy=str(self.config.get("patch_policy", "disabled")),
+                user_approvals=set(self.config.get("user_approvals") or set()),
+            )
+
+        # Build the LLM agent loop only when a model provider is configured.
+        self.agent_loop: Any = None
+        self.tool_registry: ToolRegistryProtocol | None = None
+        if self.config.get("provider"):
+            from openrat.model.factory import ModelFactory
+            from openrat.model.agent_loop import AgentLoop
+            from openrat.tools.registry import ToolRegistry
+
+            adapter = ModelFactory.create(self.config)
+            self.tool_registry = ToolRegistry(session=self.session)
+
+            # Register the execution runner as callable tool for the model.
+            _self = self
+
+            def run_experiment(arguments: Mapping[str, Any]) -> Mapping[str, Any]:
+                path = arguments.get("path")
+                if not path:
+                    return {"status": "error", "reason": "path is required"}
+                return _self.run(
+                    path,
+                    timeout=arguments.get("timeout"),
+                    isolate=arguments.get("isolate", True),
+                    memory=arguments.get("memory", "512m"),
+                    cpus=arguments.get("cpus", "1.0"),
+                )
+
+            run_experiment.capability = "observe"
+            run_experiment.__openrat_trusted__ = True
+
+            self.tool_registry.register(
+                "run_experiment",
+                run_experiment,
+                capability="observe",
+                trusted=True,
+            )
+            self.agent_loop = AgentLoop(adapter, tool_registry=self.tool_registry)
+
+    def run(self, path: str, timeout: int | None = None, isolate: bool = True, memory: str = "512m", cpus: str = "1.0") -> Mapping[str, Any]:
+        """Internal direct execution (not part of public API)."""
+        self.session.authorize(
+            "observe",
+            action="runner.run",
+            metadata={"path": path},
+        )
+        return run(
+            path,
+            executor=self.executor,
+            timeout=timeout,
+            docker_image=self.docker_image,
+            isolate=isolate,
+            memory=memory,
+            cpus=cpus,
+            allow_unbounded_limits=self.allow_unbounded_limits,
+        )
+
+    def chat(self, messages: str | list[Message], max_turns: int = 10) -> ModelResponse:
+        """Internal LLM agent loop (not part of public API).
+
+        ``messages`` can be:
+        - a plain string (converted to a single user Message), or
+        - a list of ``openrat.model.types.Message`` objects.
+
+        Requires ``provider`` (and usually ``api_key``, ``model_name``) in config.
+        """
+        if self.agent_loop is None:
+            raise UserInputError(
+                "No model configured. Pass 'provider', 'api_key', and 'model_name' "
+                "in the config dict to enable the LLM agent loop."
+            )
+        from openrat.model.types import Message as _Message
+        if isinstance(messages, str):
+            messages = [_Message(role="user", content=messages)]
+        return self.agent_loop.run(list(messages), max_turns=max_turns)

openrat/core/__init__.py

@@ -0,0 +1,31 @@
+from importlib import import_module
+
+"""Core framework types (Session, Artifact, ExperimentSpec, AutonomyLevel).
+
+These types represent:
+  - Artifact: Immutable execution results (value type)
+  - ExperimentSpec: Declarative experiment intent (immutable specification)
+  - Session: Execution authority and approval state (mutable during execution)
+  - AutonomyLevel: Governance levels for capability authorization
+
+All are accessible via the main openrat package.
+"""
+
+__all__ = ["Artifact", "ExperimentSpec", "Session", "AutonomyLevel"]
+
+_EXPORTS = {
+	"Artifact": ("openrat.core.artifact", "Artifact"),
+	"ExperimentSpec": ("openrat.core.experiment_spec", "ExperimentSpec"),
+	"Session": ("openrat.core.session.session", "Session"),
+	"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/core/artifact.py

@@ -0,0 +1,117 @@
+from dataclasses import dataclass, field
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+from types import MappingProxyType
+from datetime import datetime, timezone
+from uuid import UUID, uuid4
+
+if TYPE_CHECKING:
+    from openrat.core.session.session import Session
+    from openrat.tasks.dag.dag import DAG
+    from openrat.tasks.plan.plan import Plan
+
+
+@dataclass(frozen=True)
+class Artifact:
+    """Immutable result of experiment execution.
+    
+    Contains observations, evaluations, logs, and metadata from a completed run.
+    """
+    id: UUID
+    created_at: datetime
+
+    observations: Mapping[str, Any]
+    evaluations: Mapping[str, Any]
+    diagnostics: Mapping[str, Any]
+
+    logs: Sequence[str]
+    patches_applied: Sequence[str]
+
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    @classmethod
+    def create(
+        cls,
+        *,
+        observations: Mapping[str, Any],
+        evaluations: Mapping[str, Any],
+        diagnostics: Mapping[str, Any],
+        logs: Sequence[str],
+        patches_applied: Sequence[str],
+        metadata: Mapping[str, Any] | None = None,
+    ) -> "Artifact":
+        """Create an immutable execution artifact."""
+        return cls(
+            id=uuid4(),
+            created_at=datetime.now(timezone.utc),
+            observations=MappingProxyType(dict(observations)),
+            evaluations=MappingProxyType(dict(evaluations)),
+            diagnostics=MappingProxyType(dict(diagnostics)),
+            logs=tuple(logs),
+            patches_applied=tuple(patches_applied),
+            metadata=MappingProxyType(dict(metadata or {})),
+        )
+
+    @classmethod
+    def from_dag_execution(
+        cls,
+        *,
+        dag: "DAG",
+        plan: "Plan",
+        session: "Session",
+        logs: Sequence[str] = (),
+        metrics: Mapping[str, Any] | None = None,
+        diagnostics: Mapping[str, Any] | None = None,
+        patches_applied: Sequence[str] = (),
+    ) -> "Artifact":
+        observations = {
+            task_id: dict(record.outputs)
+            for task_id, record in dag.state.items()
+            if record.outputs
+        }
+        failed = [
+            task_id
+            for task_id, record in dag.state.items()
+            if getattr(record.state, "value", str(record.state)) == "failed"
+        ]
+
+        return cls.create(
+            observations=observations,
+            evaluations={
+                "status": "failed" if failed else "success",
+                "metrics": dict(metrics or {}),
+            },
+            diagnostics=dict(diagnostics or {}),
+            logs=tuple(logs),
+            patches_applied=tuple(patches_applied),
+            metadata={
+                "plan_id": str(plan.id),
+                "session_id": str(session.id),
+                "failed_tasks": failed,
+            },
+        )
+    
+    def summarize(self) -> dict[str, Any]:
+        return {
+            "id": str(self.id),
+            "status": self.evaluations.get("status"),
+            "metrics": self.evaluations.get("metrics", {}),
+            "patches_applied": len(self.patches_applied),
+        }
+
+    def has_failures(self) -> bool:
+        return bool(self.diagnostics)
+
+    #Minimal serialization:
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": str(self.id),
+            "created_at": self.created_at.isoformat(),
+            "observations": dict(self.observations),
+            "evaluations": dict(self.evaluations),
+            "diagnostics": dict(self.diagnostics),
+            "logs": list(self.logs),
+            "patches_applied": list(self.patches_applied),
+            "metadata": dict(self.metadata),
+        }