gatewaysdk 0.3.2__py3-none-any.whl

gatewaysdk/environment/core.py

@@ -0,0 +1,527 @@
+"""``gwenv.init`` and the :class:`Environment` object (spec §4).
+
+    import gatewaysdk.environment as gwenv
+
+    env = gwenv.init("refund-flows-env")     # slug or id; READY head
+    with env:                                # implicit world + ambient interception
+        my_agent("handle ticket #4415")
+    result = env.verify("refund_row_created")
+    assert result.passed, env.state("SELECT * FROM refunds")
+
+Local mode only in P1: the version bundle is pulled via the existing
+environments/benchmark-hub clients, extracted to a cache dir, and executed
+in-process (sqlite worlds for ``mock-tools``; per-task docker sandboxes for
+``harbor``). ``mode="remote"`` and ``hosts=`` transport patching are P2/P3.
+"""
+
+from __future__ import annotations
+
+import inspect
+import os
+import tempfile
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from pathlib import Path
+from typing import Any, Dict, Iterable, Iterator, List, Mapping, Optional, Union
+
+from .. import build as _build
+from ..benchmark_hub.client import BenchmarkPushError, GatewayBenchmarkClient
+from ..environments import GatewayEnvironmentClient, GatewayEnvironmentError
+from ._bundle import (
+    KIND_HARBOR,
+    KIND_MOCK_TOOLS,
+    EnvManifest,
+    HarborTask,
+    detect_kind,
+    load_handlers,
+    load_harbor_tasks,
+    parse_manifest,
+)
+from ._harbor import CliDockerRuntime, DockerRuntime, HarborWorld
+from ._world import _NO_INPUT, VerifierResult, World, WorldRegistry
+from .errors import (
+    EnvironmentKindError,
+    EnvironmentNotConfigured,
+    EnvironmentNotReady,
+    HermeticViolation,
+    ToolRouteError,
+    WorldStartError,
+)
+
+#: Env traffic records under ``gateway-env-{slug}`` — the tracing environment
+#: tag that keeps it out of production views (sibling of replay's
+#: ``gateway-replay``).
+ENV_ENVIRONMENT_PREFIX = "gateway-env-"
+
+_ROUTES = ("env", "prod")
+
+#: The ambiently-active world (set by ``with env:`` / ``env.branch()``); the
+#: ``define_tool`` wrapper consults it on every call.
+_active_world: ContextVar[Optional[World]] = ContextVar("gateway_env_world", default=None)
+
+
+def get_active_world() -> Optional[World]:
+    return _active_world.get()
+
+
+class RouteRecord:
+    """One routed call: where it went and how long it took."""
+
+    __slots__ = ("tool", "route", "duration_ms", "world_id")
+
+    def __init__(self, tool: str, route: str, duration_ms: float, world_id: Optional[str]) -> None:
+        self.tool = tool
+        self.route = route
+        self.duration_ms = duration_ms
+        self.world_id = world_id
+
+    def __repr__(self) -> str:  # pragma: no cover — debugging nicety
+        return f"RouteRecord({self.tool!r}, {self.route!r}, {self.duration_ms:.1f}ms, world={self.world_id})"
+
+
+class Report:
+    """Route provenance + hermetic accounting for one Environment."""
+
+    def __init__(self) -> None:
+        self.routes: List[RouteRecord] = []
+
+    @property
+    def hermetic(self) -> bool:
+        """False if ANY call reached prod."""
+        return not self.prod_calls()
+
+    def prod_calls(self) -> List[RouteRecord]:
+        return [record for record in self.routes if record.route == "prod"]
+
+
+class Environment:
+    """A resolved environment bundle plus its routing/runtime configuration.
+
+    Construct via :func:`init` (platform) or :func:`init_from_path` (local
+    bundle dir) rather than directly.
+    """
+
+    def __init__(
+        self,
+        bundle_path: Union[str, Path],
+        *,
+        slug: Optional[str] = None,
+        version: Optional[str] = None,
+        route: Optional[Mapping[str, str]] = None,
+        default_route: str = "env",
+        unsafe_allow_prod: Iterable[str] = (),
+        record: bool = True,
+        docker: Optional[DockerRuntime] = None,
+    ) -> None:
+        self.bundle_path = Path(bundle_path)
+        if not self.bundle_path.is_dir():
+            raise EnvironmentNotReady(f"bundle path does not exist: {self.bundle_path}")
+        self.kind = detect_kind(self.bundle_path)
+        self.version = version
+        self.record = record
+
+        if default_route not in _ROUTES:
+            raise ValueError(f"default_route must be one of {_ROUTES}, got {default_route!r}")
+        self._route: Dict[str, str] = dict(route or {})
+        for tool_name, target in self._route.items():
+            if target not in _ROUTES:
+                raise ValueError(f"route[{tool_name!r}] must be one of {_ROUTES}, got {target!r}")
+        self._default_route = default_route
+        self._unsafe_allow_prod = set(unsafe_allow_prod)
+        self.report = Report()
+        self._docker_runtime = docker
+
+        self.manifest: Optional[EnvManifest] = None
+        self._handlers: Dict[str, Any] = {}
+        self._harbor_tasks: List[HarborTask] = []
+        self._implicit_world: Optional[World] = None
+        self._enter_token: Any = None
+        self._tracing_cm: Any = None
+
+        if self.kind == KIND_MOCK_TOOLS:
+            self.manifest = parse_manifest(self.bundle_path)
+            self.slug = slug or self.manifest.name
+            self._handlers = load_handlers(self.bundle_path, self.manifest)
+            self._tmpdir = tempfile.TemporaryDirectory(prefix=f"gwenv-{_safe(self.slug)}-")
+            self._worlds_dir = Path(self._tmpdir.name)
+            self._template_db = self._worlds_dir / "template.db"
+            self._build_template_db()
+        else:
+            self.slug = slug or self.bundle_path.name
+            self._harbor_tasks = load_harbor_tasks(self.bundle_path)
+
+        _install_ambient_interceptor()
+
+    # -- kind guards -----------------------------------------------------
+
+    def _require_mock(self, operation: str) -> None:
+        if self.kind != KIND_MOCK_TOOLS:
+            raise EnvironmentKindError(
+                f"{operation} is a mock-tools seam, but '{self.slug}' is a "
+                f"{self.kind} environment — harbor envs are task sandboxes, not "
+                "tool mocks. Use env.tasks / env.task(name), world.exec(...), "
+                "and world.verify() instead."
+            )
+
+    def _require_harbor(self, operation: str) -> None:
+        if self.kind != KIND_HARBOR:
+            raise EnvironmentKindError(
+                f"{operation} is a harbor seam, but '{self.slug}' is a "
+                f"{self.kind} environment — use `with env:` / env.branch() and "
+                "the registry/execute seams instead."
+            )
+
+    # -- mock-tools: template + worlds ------------------------------------
+
+    def _build_template_db(self) -> None:
+        from ._materialize import materialize_template
+
+        materialize_template(self.bundle_path, self._template_db)
+
+    @contextmanager
+    def branch(self) -> Iterator[World]:
+        """A fresh world (file copy of the seed) — run N is identical to run 1.
+        The world is also ambiently active inside the block."""
+        self._require_mock("env.branch()")
+        world = World(self)
+        token = _active_world.set(world)
+        try:
+            yield world
+        finally:
+            _active_world.reset(token)
+
+    def __enter__(self) -> "Environment":
+        self._require_mock("with env:")
+        if self._implicit_world is not None:
+            self._implicit_world.close()
+        self._implicit_world = World(self)
+        self._enter_token = _active_world.set(self._implicit_world)
+        self._tracing_cm = self._enter_tracing_context()
+        return self
+
+    def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        if self._enter_token is not None:
+            _active_world.reset(self._enter_token)
+            self._enter_token = None
+        if self._tracing_cm is not None:
+            try:
+                self._tracing_cm.__exit__(exc_type, exc, tb)
+            except Exception:  # noqa: BLE001 — tracing is best-effort
+                pass
+            self._tracing_cm = None
+        # The implicit world stays alive: env.verify()/env.state() inspect the
+        # end state AFTER the block (spec §4.1 quickstart).
+
+    def _enter_tracing_context(self) -> Any:
+        """Tag traces with environment=gateway-env-{slug} while inside
+        ``with env:`` — best-effort, mirroring replay's REPLAY_ENVIRONMENT."""
+        try:
+            from ..tracing.exporters.gateway import is_gateway_configured
+
+            if not is_gateway_configured():
+                return None
+            from ..tracing.context import tracing_context
+
+            cm = tracing_context(environment=f"{ENV_ENVIRONMENT_PREFIX}{self.slug}")
+            cm.__enter__()
+            return cm
+        except Exception:  # noqa: BLE001 — tracing is best-effort
+            return None
+
+    def _ensure_world(self) -> World:
+        self._require_mock("the implicit world")
+        if self._implicit_world is None:
+            self._implicit_world = World(self)
+        return self._implicit_world
+
+    # -- delegates to the implicit world ----------------------------------
+
+    def execute(self, tool_name: str, tool_input: Any = _NO_INPUT) -> Any:
+        return self._ensure_world().execute(tool_name, tool_input)
+
+    def as_registry(self) -> WorldRegistry:
+        return self._ensure_world().as_registry()
+
+    def wrap_tools(self, tools: Any) -> Any:
+        return self._ensure_world().wrap_tools(tools)
+
+    def verify(self, name: str) -> VerifierResult:
+        return self._ensure_world().verify(name)
+
+    def state(self, sql: str, *params: Any) -> List[Dict[str, Any]]:
+        return self._ensure_world().state(sql, *params)
+
+    def reset(self) -> None:
+        self._ensure_world().reset()
+
+    # -- harbor ----------------------------------------------------------
+
+    @property
+    def tasks(self) -> List[HarborTask]:
+        """The env's Harbor tasks (harbor kind only)."""
+        self._require_harbor("env.tasks")
+        return list(self._harbor_tasks)
+
+    @contextmanager
+    def task(self, name: str) -> Iterator[HarborWorld]:
+        """Boot one harbor task's docker sandbox; cleaned up on exit."""
+        self._require_harbor("env.task()")
+        matches = [task for task in self._harbor_tasks if task.name == name]
+        if not matches:
+            raise KeyError(
+                f"no harbor task '{name}' in '{self.slug}' "
+                f"(tasks: {[task.name for task in self._harbor_tasks]})"
+            )
+        world = HarborWorld(self, matches[0], self._docker())
+        try:
+            yield world
+        finally:
+            world.close()
+
+    def _docker(self) -> DockerRuntime:
+        if self._docker_runtime is None:
+            self._docker_runtime = CliDockerRuntime()
+        return self._docker_runtime
+
+    # -- routing ----------------------------------------------------------
+
+    def resolve_route(self, tool_name: str) -> str:
+        """Route map > effects default (read→default_route, write→env,
+        irreversible→never prod unless unsafe_allow_prod) > default_route."""
+        explicit = self._route.get(tool_name)
+        effects = _effects_of(tool_name)
+        if explicit is not None:
+            route = explicit
+        elif effects in ("write", "irreversible"):
+            route = "env"
+        else:  # "read" or unregistered
+            route = self._default_route
+        if route == "prod" and effects == "irreversible" and tool_name not in self._unsafe_allow_prod:
+            raise ToolRouteError(
+                f"tool '{tool_name}' is declared effects='irreversible' — refusing "
+                "the prod route. Pass unsafe_allow_prod=['" + tool_name + "'] to "
+                "override (you probably don't want to)."
+            )
+        return route
+
+    def _record_route(self, tool: str, route: str, duration_ms: float, world_id: Optional[str]) -> None:
+        self.report.routes.append(RouteRecord(tool, route, duration_ms, world_id))
+
+    def assert_hermetic(self) -> None:
+        """Raise :class:`HermeticViolation` if any call reached prod."""
+        offending = self.report.prod_calls()
+        if offending:
+            lines = "\n".join(
+                f"  - {record.tool} ({record.duration_ms:.1f}ms)" for record in offending
+            )
+            raise HermeticViolation(
+                f"{len(offending)} call(s) reached prod during '{self.slug}':\n{lines}"
+            )
+
+    def close(self) -> None:
+        """Release worlds and temp state (also happens at GC/interpreter exit)."""
+        if self._implicit_world is not None:
+            self._implicit_world.close()
+            self._implicit_world = None
+        if self.kind == KIND_MOCK_TOOLS:
+            self._tmpdir.cleanup()
+
+
+def _safe(name: str) -> str:
+    return "".join(ch if ch.isalnum() or ch in "-_" else "-" for ch in name)[:40]
+
+
+def _effects_of(tool_name: str) -> Optional[str]:
+    for identity in _build.get_registered_tools():
+        if identity.get("name") == tool_name:
+            return identity.get("effects")
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Ambient interception — the define_tool wrapper's hook (spec §4.4, rung 1.5)
+# ---------------------------------------------------------------------------
+
+
+def _ambient_intercept(name: str, fn: Any, args: tuple, kwargs: dict) -> Any:
+    """Called by the ``define_tool`` wrapper on every invocation. No active
+    world → miss sentinel (the wrapper calls the original fn — the identity
+    path). Active world → route: env executes the bundle handler against the
+    world; prod passes through to the original fn WITH provenance logged."""
+    world = _active_world.get()
+    if world is None:
+        return _build._TOOL_INTERCEPT_MISS
+    env = world.env
+    route = env.resolve_route(name)
+
+    if route == "env":
+        if name not in env._handlers:
+            raise ToolRouteError(
+                f"tool '{name}' routes to env but '{env.slug}' serves no handler "
+                f"for it (served: {sorted(env._handlers)}) — add a handler, "
+                "route={'" + name + "': 'prod'}, or default_route='prod'."
+            )
+        tool_input = _bind_tool_input(fn, args, kwargs)
+        if inspect.iscoroutinefunction(fn):
+            async def _async_execute() -> Any:
+                return world.execute(name, tool_input)
+
+            return _async_execute()
+        return world.execute(name, tool_input)
+
+    # prod passthrough — the original fn IS the live implementation.
+    started = time.perf_counter()
+    if inspect.iscoroutinefunction(fn):
+        async def _async_prod() -> Any:
+            try:
+                return await fn(*args, **kwargs)
+            finally:
+                env._record_route(name, "prod", (time.perf_counter() - started) * 1000.0, world.id)
+
+        return _async_prod()
+    try:
+        return fn(*args, **kwargs)
+    finally:
+        env._record_route(name, "prod", (time.perf_counter() - started) * 1000.0, world.id)
+
+
+def _bind_tool_input(fn: Any, args: tuple, kwargs: dict) -> Any:
+    """Map the wrapped fn's call arguments to a kwargs dict for the env
+    handler (handlers mirror the real tool's parameter names)."""
+    if not args:
+        return dict(kwargs)
+    try:
+        bound = inspect.signature(fn).bind(*args, **kwargs)
+        return dict(bound.arguments)
+    except (TypeError, ValueError):
+        if len(args) == 1 and not kwargs:
+            return args[0]
+        return {"args": list(args), **kwargs}
+
+
+_interceptor_installed = False
+
+
+def _install_ambient_interceptor() -> None:
+    global _interceptor_installed
+    if not _interceptor_installed:
+        _build.set_tool_call_interceptor(_ambient_intercept)
+        _interceptor_installed = True
+
+
+# ---------------------------------------------------------------------------
+# init
+# ---------------------------------------------------------------------------
+
+
+def init_from_path(
+    path: Union[str, Path],
+    *,
+    slug: Optional[str] = None,
+    route: Optional[Mapping[str, str]] = None,
+    default_route: str = "env",
+    unsafe_allow_prod: Iterable[str] = (),
+    record: bool = True,
+    docker: Optional[DockerRuntime] = None,
+) -> Environment:
+    """Boot an environment straight from a local bundle directory — no
+    platform round-trip. The offline/dev/test twin of :func:`init`."""
+    return Environment(
+        path,
+        slug=slug,
+        route=route,
+        default_route=default_route,
+        unsafe_allow_prod=unsafe_allow_prod,
+        record=record,
+        docker=docker,
+    )
+
+
+def init(
+    ref: str,
+    *,
+    version: Optional[str] = None,
+    mode: str = "local",
+    route: Optional[Mapping[str, str]] = None,
+    default_route: str = "env",
+    hosts: Optional[Mapping[str, str]] = None,
+    unsafe_allow_prod: Iterable[str] = (),
+    record: bool = True,
+    host: Optional[str] = None,
+    public_key: Optional[str] = None,
+    secret_key: Optional[str] = None,
+    docker: Optional[DockerRuntime] = None,
+) -> Environment:
+    """Resolve ``ref`` (env slug or container id) on the platform, pull the
+    READY version bundle (or ``version`` — pin in CI!), and boot it locally.
+
+    Missing keys/config raise :class:`EnvironmentNotConfigured` here, never
+    mid-run. ``mode="remote"`` (hosted worlds) and ``hosts=`` (transport-level
+    host routing) are not part of P1.
+    """
+    if mode == "remote":
+        raise NotImplementedError(
+            "mode='remote' (platform-hosted worlds) lands with the mock-instance "
+            "manager — spec §4.9, phase P3. Use mode='local'."
+        )
+    if mode != "local":
+        raise ValueError(f"mode must be 'local' or 'remote', got {mode!r}")
+    if hosts:
+        raise NotImplementedError("hosts= transport routing lands in P2 — route tools, not hosts, for now.")
+
+    resolved_host = host or os.environ.get("GATEWAY_HOST") or ""
+    resolved_public = public_key or os.environ.get("GATEWAY_PUBLIC_KEY") or ""
+    resolved_secret = secret_key or os.environ.get("GATEWAY_SECRET_KEY") or ""
+    if not (resolved_host and resolved_public and resolved_secret):
+        raise EnvironmentNotConfigured(
+            "Gateway is not configured — set GATEWAY_HOST, GATEWAY_PUBLIC_KEY and "
+            "GATEWAY_SECRET_KEY (or pass host=/public_key=/secret_key=)."
+        )
+
+    env_client = GatewayEnvironmentClient(resolved_host, resolved_public, resolved_secret)
+    slug: Optional[str] = None
+    listing = env_client.list_environments(slug=ref)
+    if listing.environments:
+        slug = listing.environments[0].slug
+    else:
+        try:
+            slug = env_client.get_environment(ref).slug
+        except GatewayEnvironmentError:
+            raise EnvironmentNotReady(
+                f"environment '{ref}' not found (by slug or id) on {resolved_host}"
+            ) from None
+
+    bench = GatewayBenchmarkClient(resolved_host, resolved_public, resolved_secret)
+    try:
+        details = bench.resolve_version(slug, version or "latest")
+    except BenchmarkPushError as error:
+        raise EnvironmentNotReady(f"no runnable version for '{slug}': {error}") from None
+    content_hash = details.get("contentHash")
+    if not details.get("downloadUrl"):
+        raise EnvironmentNotReady(
+            f"'{slug}'@{version or 'latest'} resolved but has no uploaded bundle — "
+            "the version never finished building (no READY head)."
+        )
+
+    cache_root = Path(
+        os.environ.get("GATEWAY_ENV_CACHE") or Path.home() / ".cache" / "gatewaysdk" / "environments"
+    )
+    bundle_dir = cache_root / slug / (content_hash or version or "latest")
+    if not (bundle_dir.is_dir() and any(bundle_dir.iterdir())):
+        bundle_dir.mkdir(parents=True, exist_ok=True)
+        try:
+            bench.pull(f"{slug}@{version or content_hash or 'latest'}", target=str(bundle_dir))
+        except BenchmarkPushError as error:
+            raise EnvironmentNotReady(f"failed to pull '{slug}' bundle: {error}") from None
+
+    return Environment(
+        bundle_dir,
+        slug=slug,
+        version=content_hash or version,
+        route=route,
+        default_route=default_route,
+        unsafe_allow_prod=unsafe_allow_prod,
+        record=record,
+        docker=docker,
+    )

gatewaysdk/environment/errors.py

@@ -0,0 +1,58 @@
+"""Errors for ``gatewaysdk.environment`` (spec §4.7).
+
+All errors subclass :class:`GatewayEnvError` so callers can catch the whole
+family with one except clause. The §4.7 set is fixed; ``EnvironmentKindError``
+is an addendum addition for kind-mismatched API use (mock-tools seams on a
+harbor env and vice versa).
+"""
+
+from __future__ import annotations
+
+
+class GatewayEnvError(RuntimeError):
+    """Base error for the environment SDK."""
+
+
+class EnvironmentNotConfigured(GatewayEnvError):
+    """Missing host/keys — raised at ``init()``, never mid-run."""
+
+
+class EnvironmentNotReady(GatewayEnvError):
+    """No READY version to run against (or the env/bundle cannot be resolved)."""
+
+
+class WorldStartError(GatewayEnvError):
+    """A world failed to boot (sqlite template build, docker run, …) — the
+    message carries a remediation hint."""
+
+
+class ToolRouteError(GatewayEnvError):
+    """A tool call had nowhere to go: no env handler and no prod route, or a
+    route the current seam cannot honor (e.g. prod at the registry seam)."""
+
+
+class HermeticViolation(GatewayEnvError):
+    """Raised by ``env.assert_hermetic()`` when any call reached prod —
+    the message lists the offending calls."""
+
+
+class VerifierError(GatewayEnvError):
+    """Unknown verifier or verifier execution error, with the SQL/script
+    echoed for debugging."""
+
+
+class EnvironmentKindError(GatewayEnvError):
+    """An API surface was used on the wrong environment kind (harbor task
+    sandboxes vs mock-tools worlds)."""
+
+
+__all__ = [
+    "GatewayEnvError",
+    "EnvironmentNotConfigured",
+    "EnvironmentNotReady",
+    "WorldStartError",
+    "ToolRouteError",
+    "HermeticViolation",
+    "VerifierError",
+    "EnvironmentKindError",
+]