godel-py 3.13.2__py3-none-any.whl

godel/__init__.py

@@ -0,0 +1,100 @@
+"""Godel — deterministic orchestrator for AI agent workflows."""
+__version__ = "3.13.2"
+
+import sys
+from pathlib import Path
+
+
+def version() -> str:
+    """Return the package version string from pyproject.toml."""
+    pyproject = Path(__file__).parent.parent / "pyproject.toml"
+    if sys.version_info >= (3, 11):
+        import tomllib
+        with open(pyproject, "rb") as f:
+            data = tomllib.load(f)
+    else:
+        import tomli  # type: ignore[import]
+        with open(pyproject, "rb") as f:
+            data = tomli.load(f)
+    return data["project"]["version"]
+
+
+from godel._decorators import workflow, step, WorkflowFail, parallel, retry
+from godel._run import run, CommandResult, CommandFailure
+from godel.io import print, input, sleep, read_text, write_text
+from godel._events import Event, EventStatus
+from godel._event_log import EventLog
+from godel._context import get_event_log
+from godel._exceptions import (
+    GodelStrictError,
+    StrictViolation,
+    ResumeError,
+    UnsafeResumeError,
+    SourceEditedError,
+    RewindSignal,
+    PauseSignal,
+    GodelError,
+    AgentRefusal,
+    SchemaValidationFailure,
+    HumanTimeout,
+    NonDeterministicEscape,
+    RewindUnsafe,
+    GodelWatchNotInstalledError,
+    ConfigError,
+    StepTimeout,
+)
+from godel._pause import check_pause_request, write_pause_request, clear_pause_request, pause
+from godel._config import load_config, GodelConfig, LoadedConfig, resolve_workflow, list_workflows, open_event_log
+from godel._rewind import rewind
+from godel._tail import tail
+from godel import det
+
+__all__ = [
+    "workflow",
+    "step",
+    "WorkflowFail",
+    "parallel",
+    "retry",
+    "run",
+    "CommandResult",
+    "CommandFailure",
+    "print",
+    "input",
+    "sleep",
+    "read_text",
+    "write_text",
+    "Event",
+    "EventStatus",
+    "EventLog",
+    "get_event_log",
+    "GodelStrictError",
+    "StrictViolation",
+    "ResumeError",
+    "UnsafeResumeError",
+    "SourceEditedError",
+    "RewindSignal",  # internal control-flow signal; exported for isinstance checks in tests
+    "rewind",
+    "det",
+    "GodelError",
+    "AgentRefusal",
+    "SchemaValidationFailure",
+    "HumanTimeout",
+    "NonDeterministicEscape",
+    "RewindUnsafe",
+    "GodelWatchNotInstalledError",
+    "ConfigError",
+    "StepTimeout",
+    "PauseSignal",
+    "check_pause_request",
+    "write_pause_request",
+    "clear_pause_request",
+    "pause",
+    "tail",
+    "version",
+    "load_config",
+    "GodelConfig",
+    "LoadedConfig",
+    "resolve_workflow",
+    "list_workflows",
+    "open_event_log",
+]

godel/__main__.py

@@ -0,0 +1,3 @@
+from godel.cli import main
+
+main()

godel/_config.py

@@ -0,0 +1,319 @@
+"""Two-tier config for godel.
+
+Project-level: ``<project>/.godel/settings.json`` (committed).
+User-level:    ``~/.godel/settings.json`` (+ per-project data under
+               ``~/.godel/projects/<rel>/``).
+
+Precedence (high→low): CLI flag > env var > project > user > default.
+
+See ``plans/steady-sniffing-candy.md`` for design notes.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from godel._exceptions import ConfigError
+
+
+CONFIG_DIR_NAME = ".godel"
+SETTINGS_FILENAME = "settings.json"
+WORKFLOWS_SUBDIR = "workflows"
+
+
+class WatchConfig(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+    default: bool = False
+    plain: bool = False
+
+
+class GodelConfig(BaseModel):
+    """Frozen merged config.  All fields optional with sensible defaults."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    runs_dir: str | None = None
+    workflows_dir: str = f"{CONFIG_DIR_NAME}/{WORKFLOWS_SUBDIR}"
+    strict: bool = True
+    lint: bool = True
+    stream_agents: bool = True
+    watch: WatchConfig = Field(default_factory=WatchConfig)
+    env: dict[str, str] = Field(default_factory=dict)
+    redact: list[str] = Field(default_factory=list)
+    capture_stdout: bool = False
+    transcript_max_bytes: int = 10 * 1024 * 1024
+    # NOTE: auto-checkpoint mode is a GODEL_AUTO_CHECKPOINT env var / CLI flag
+    # only — intentionally not a GodelConfig field.  It's execution-context
+    # metadata (how stdin answers are supplied for THIS invocation), not a
+    # persistable project setting.  godel.io reads os.environ directly.
+
+
+@dataclass(frozen=True)
+class LoadedConfig:
+    """Result of ``load_config``: merged model + provenance."""
+    config: GodelConfig
+    project_root: Path | None
+    sources: list[Path] = field(default_factory=list)
+
+    @property
+    def runs_dir(self) -> Path:
+        """Resolved absolute runs directory.
+
+        If ``config.runs_dir`` is unset, defaults to
+        ``~/.godel/projects/<rel>/runs`` (or ``./runs`` when no project root
+        is known — zero-config programmatic use).
+        """
+        if self.config.runs_dir:
+            rd = Path(self.config.runs_dir).expanduser()
+            if rd.is_absolute():
+                return rd
+            base = self.project_root if self.project_root else Path.cwd()
+            return (base / rd).resolve()
+        if self.project_root is None:
+            return (Path.cwd() / "runs").resolve()
+        return project_data_dir(self.project_root) / "runs"
+
+
+# ---------------------------------------------------------------------------
+# Directory helpers
+# ---------------------------------------------------------------------------
+
+def global_config_dir() -> Path:
+    """``~/.godel/`` (or ``$GODEL_HOME`` if set)."""
+    override = os.environ.get("GODEL_HOME")
+    if override:
+        return Path(override).expanduser().resolve()
+    return (Path.home() / CONFIG_DIR_NAME).resolve()
+
+
+def project_data_dir(project_root: Path) -> Path:
+    """``~/.godel/projects/<rel>/`` for this project.
+
+    ``<rel>`` = project_root with ``$HOME/`` stripped.  For projects outside
+    ``$HOME``, use ``_abs/<sha256(realpath)[:16]>``.
+    """
+    project_root = Path(project_root).resolve()
+    home = Path.home().resolve()
+    try:
+        rel = project_root.relative_to(home)
+        return global_config_dir() / "projects" / rel
+    except ValueError:
+        digest = hashlib.sha256(str(project_root).encode()).hexdigest()[:16]
+        return global_config_dir() / "projects" / "_abs" / digest
+
+
+def find_project_config(cwd: Path | None = None) -> Path | None:
+    """Walk up from *cwd* looking for a ``.godel/`` directory.
+
+    Stops at first of: filesystem root, ``$HOME``, or a dir containing ``.git/``
+    (that dir is still checked for ``.godel/`` before stopping).  Returns the
+    path of the ``.godel/`` dir, or ``None`` if none found.
+    """
+    start = Path(cwd).resolve() if cwd is not None else Path.cwd().resolve()
+    home = Path.home().resolve()
+
+    current = start
+    while True:
+        candidate = current / CONFIG_DIR_NAME
+        if candidate.is_dir():
+            return candidate
+
+        # Stop conditions (check *after* examining current dir):
+        if current == current.parent:
+            return None  # filesystem root
+        if current == home:
+            return None
+        if (current / ".git").exists():
+            return None
+
+        current = current.parent
+
+
+# ---------------------------------------------------------------------------
+# Loading
+# ---------------------------------------------------------------------------
+
+_BOOL_ENV_KEYS = {
+    "GODEL_STRICT": "strict",
+    "GODEL_LINT": "lint",
+    "GODEL_STREAM_AGENTS": "stream_agents",
+    "GODEL_CAPTURE_STDOUT": "capture_stdout",
+}
+
+_STR_ENV_KEYS = {
+    "GODEL_RUNS_DIR": "runs_dir",
+    "GODEL_WORKFLOWS_DIR": "workflows_dir",
+}
+
+
+def _read_json(path: Path) -> dict:
+    try:
+        with open(path) as f:
+            data = json.load(f)
+    except json.JSONDecodeError as exc:
+        raise ConfigError(f"{path}: malformed JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path}: top-level JSON must be an object")
+    return data
+
+
+def _parse_bool(raw: str) -> bool:
+    return raw.strip().lower() not in ("0", "false", "no", "")
+
+
+def _env_overrides() -> dict:
+    out: dict = {}
+    for env_key, field_name in _STR_ENV_KEYS.items():
+        v = os.environ.get(env_key)
+        if v:  # ignore unset and empty-string
+            out[field_name] = v
+    for env_key, field_name in _BOOL_ENV_KEYS.items():
+        v = os.environ.get(env_key)
+        if v is not None and v != "":
+            out[field_name] = _parse_bool(v)
+    return out
+
+
+def _merge(base: dict, overlay: dict) -> dict:
+    """Shallow merge; nested dicts (watch, env) shallow-merged too."""
+    out = dict(base)
+    for k, v in overlay.items():
+        if isinstance(v, dict) and isinstance(out.get(k), dict):
+            merged = dict(out[k])
+            merged.update(v)
+            out[k] = merged
+        else:
+            out[k] = v
+    return out
+
+
+_cache: dict[tuple, "LoadedConfig"] = {}
+
+
+def load_config(cwd: Path | str | None = None, *, use_cache: bool = True) -> LoadedConfig:
+    """Load merged config.
+
+    Layers (low→high): built-in defaults < ``~/.godel/settings.json`` <
+    ``<project>/.godel/settings.json`` < ``GODEL_*`` env vars.  CLI flags are
+    applied by callers on top of the returned model.
+
+    Memoized on ``(realpath(cwd), frozen env snapshot)`` — deep/NFS paths hit
+    the filesystem once per invocation.
+    """
+    cwd_path = Path(cwd).resolve() if cwd else Path.cwd().resolve()
+
+    env_snapshot = tuple(
+        sorted(
+            (k, os.environ[k])
+            for k in (*_BOOL_ENV_KEYS, *_STR_ENV_KEYS, "GODEL_HOME", "HOME")
+            if k in os.environ
+        )
+    )
+    cache_key = (str(cwd_path), env_snapshot)
+    if use_cache and cache_key in _cache:
+        return _cache[cache_key]
+
+    sources: list[Path] = []
+    merged: dict = {}
+
+    user_settings = global_config_dir() / SETTINGS_FILENAME
+    if user_settings.is_file():
+        merged = _merge(merged, _read_json(user_settings))
+        sources.append(user_settings)
+
+    project_dir = find_project_config(cwd_path)
+    project_root = project_dir.parent if project_dir else None
+    if project_dir:
+        project_settings = project_dir / SETTINGS_FILENAME
+        if project_settings.is_file():
+            merged = _merge(merged, _read_json(project_settings))
+            sources.append(project_settings)
+
+    merged = _merge(merged, _env_overrides())
+
+    try:
+        cfg = GodelConfig(**merged)
+    except Exception as exc:
+        raise ConfigError(f"invalid config: {exc}") from exc
+
+    loaded = LoadedConfig(config=cfg, project_root=project_root, sources=sources)
+    if use_cache:
+        _cache[cache_key] = loaded
+    return loaded
+
+
+def clear_cache() -> None:
+    """Clear the ``load_config`` memo table.  Primarily for tests."""
+    _cache.clear()
+
+
+# ---------------------------------------------------------------------------
+# Workflow resolution
+# ---------------------------------------------------------------------------
+
+def _workflow_search_dirs(loaded: LoadedConfig) -> list[Path]:
+    dirs: list[Path] = []
+    if loaded.project_root:
+        p = Path(loaded.config.workflows_dir)
+        if not p.is_absolute():
+            p = loaded.project_root / p
+        dirs.append(p)
+    dirs.append(global_config_dir() / WORKFLOWS_SUBDIR)
+    return dirs
+
+
+def resolve_workflow(name_or_path: str, loaded: LoadedConfig) -> Path:
+    """Resolve an arg to a workflow file path.
+
+    1. Existing file path → returned as-is (today's behavior).
+    2. Otherwise treat as a name; search project then user ``workflows/`` dir
+       for ``<name>.py``.
+    3. Raise ``ConfigError`` listing available names if not found.
+    """
+    p = Path(name_or_path)
+    if p.is_file():
+        return p.resolve()
+
+    for base in _workflow_search_dirs(loaded):
+        candidate = base / f"{name_or_path}.py"
+        if candidate.is_file():
+            return candidate.resolve()
+
+    available = sorted(list_workflows(loaded).keys())
+    hint = f"  available: {', '.join(available)}" if available else "  (no workflows registered)"
+    raise ConfigError(
+        f"workflow not found: {name_or_path!r}\n{hint}"
+    )
+
+
+def open_event_log(run_id: str, *, cwd: Path | str | None = None):
+    """Open an existing ``EventLog`` for *run_id* using the configured runs dir.
+
+    Convenience for programmatic callers so they don't hand-wire
+    ``EventLog.load(run_id, runs_dir=str(load_config().runs_dir))``.
+    """
+    from godel._event_log import EventLog
+    loaded = load_config(cwd)
+    return EventLog.load(run_id, runs_dir=str(loaded.runs_dir))
+
+
+def list_workflows(loaded: LoadedConfig) -> dict[str, Path]:
+    """Return name → path for every ``.py`` file in the search dirs.
+
+    Project workflows shadow user workflows on name collision.
+    """
+    found: dict[str, Path] = {}
+    # Walk in reverse so earlier (project) entries overwrite later (user) ones.
+    for base in reversed(_workflow_search_dirs(loaded)):
+        if not base.is_dir():
+            continue
+        for f in base.glob("*.py"):
+            if f.name.startswith("_"):
+                continue
+            found[f.stem] = f.resolve()
+    return found

godel/_context.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from godel._event_log import EventLog
+    from godel._replay import ReplayWalker
+    from godel._transcript import TranscriptWriter
+
+
+@dataclass
+class WorkflowContext:
+    run_id: str
+    step_stack: list[str] = field(default_factory=list)
+    event_log: "EventLog | None" = None
+    _invocation_counts: dict = field(default_factory=dict)
+    _step_local_seq: dict = field(default_factory=dict)
+    replay_walker: "ReplayWalker | None" = None
+    source_file: str = ""
+    _event_id_stack: list[str] = field(default_factory=list)
+    # Observability: whether agent stdout is streamed to the transcript.
+    # Defaults to True; disabled by setting GODEL_STREAM_AGENTS=0 in the env
+    # (typically via `godel run --no-stream`).
+    stream_agents: bool = True
+    # Advisory transcript writer (None outside @workflow or when streaming disabled).
+    transcript: "TranscriptWriter | None" = None
+    # Ordered list of event_ids for every @step that reached FINISHED.
+    # Populated by the @step decorator; used by last_step_event_id().
+    # NOTE (WARN-2): when steps run inside parallel(), branches append to this
+    # shared list in asyncio task-scheduling order, which is non-deterministic.
+    # Do not rely on the absolute positions of parallel-branch entries — only
+    # use last_step_event_id() from sequential (non-parallel) step boundaries.
+    _step_event_history: list[str] = field(default_factory=list)
+    # Per-branch replay suppress flag.  Mirrors event_log._replay_suppress but
+    # is scoped to THIS context only (not shared across parallel branches).
+    # Set to True when suppress is active at context creation / branch entry.
+    # Cleared to False when THIS branch (or a child of it) exits replay mode.
+    # Used by @step to correctly choose cached vs ephemeral event_id even when
+    # a sibling parallel branch has already cleared the shared event_log flag.
+    _local_replay_suppress: bool = False
+
+    def last_step_event_id(self, n: int = 1) -> str:
+        """Return the n-th most recent completed step event_id.
+
+        n=1 returns the most recently completed step, n=2 returns the one
+        before that, etc.
+
+        During replay the returned ID is the *original persisted* event_id
+        from the cached log, not the ephemeral event_id emitted during replay
+        re-execution.  This means the returned ID is always a valid key in
+        the persistent audit log regardless of whether the workflow is running
+        fresh or resuming.
+
+        Parallel-step caveat (WARN-2): steps that execute inside parallel()
+        append to the shared history in asyncio task-scheduling order, which
+        is non-deterministic.  Only use this method from sequential (non-
+        parallel) step boundaries if you need stable positional semantics.
+
+        Raises:
+            ValueError: if n < 1
+            IndexError: if fewer than n steps have reached their FINISHED
+                boundary (i.e. not enough completed steps in history yet).
+        """
+        if n < 1:
+            raise ValueError(f"n must be >= 1, got {n!r}")
+        history = self._step_event_history
+        if n > len(history):
+            raise IndexError(
+                f"Only {len(history)} step(s) have reached FINISHED in this "
+                f"workflow run so far; cannot retrieve n={n}"
+            )
+        return history[-n]
+
+    @property
+    def current_parent_event_id(self) -> str | None:
+        """Return the event_id of the innermost enclosing scope (step, fork, or workflow)."""
+        return self._event_id_stack[-1] if self._event_id_stack else None
+
+    def push_event_scope(self, event_id: str) -> None:
+        self._event_id_stack.append(event_id)
+
+    def pop_event_scope(self) -> str | None:
+        return self._event_id_stack.pop() if self._event_id_stack else None
+
+    def next_op_position(self) -> tuple[int, int]:
+        """Return (invocation_seq, step_local_seq) for the next leaf operation.
+
+        The invocation_seq is the enclosing step's count (before increment).
+        The step_local_seq auto-increments so consecutive ops get distinct keys.
+        """
+        step_path = tuple(self.step_stack)
+        # The @step decorator sets _invocation_counts[path] = old + 1,
+        # so the step's own invocation_seq (old) = current value - 1.
+        inv = max(0, self._invocation_counts.get(step_path, 1) - 1)
+        local_seq = self._step_local_seq.get(step_path, 0)
+        self._step_local_seq[step_path] = local_seq + 1
+        return inv, local_seq
+
+
+_current_workflow: ContextVar[WorkflowContext | None] = ContextVar(
+    "godel_workflow", default=None
+)
+_privileged: ContextVar[bool] = ContextVar("godel_privileged", default=False)
+_pending_replay: ContextVar = ContextVar("godel_pending_replay", default=None)
+_on_run_start: ContextVar = ContextVar("godel_on_run_start", default=None)
+
+# _current_stream_path tracks the nesting path of subprocess/agent launches.
+# Each launch site reads this contextvar on the *launching coroutine* (or
+# thread, for any future thread-pool dispatch) to compute the parent path,
+# then appends a fresh ULID to form the child path.  The child path is
+# stamped onto the Event by value at launch time — downstream consumers
+# reading the persisted log never query the contextvar.  This is the ONLY
+# contextvar used for stream-path propagation; cross-thread propagation (if
+# ever needed) must use contextvars.copy_context() + ctx.run(fn).
+_current_stream_path: ContextVar[list[str]] = ContextVar(
+    "godel_stream_path", default=[]
+)
+
+# _current_transcript holds the active TranscriptWriter for the current workflow
+# run, or None when no transcript is open.  Set by the @workflow / @step
+# decorators when capture_stdout=True is active.  @step decorators that opt
+# into capture_stdout read this to find the shared per-run writer.
+_current_transcript: ContextVar = ContextVar(
+    "godel_transcript", default=None
+)
+
+# _line_observer is set by agent wrappers to intercept subprocess stdout
+# line-by-line for real-time stream classification.  When set, the observer
+# callable receives each raw line (bytes, including the trailing newline) as
+# it arrives from the subprocess pipe.  The observer owns the line — run()
+# suppresses the default raw "stdout" transcript event when an observer is
+# active.  Same contextvar pattern as _privileged and _current_stream_path:
+# set/reset around the run() call site using ContextVar.set() + .reset().
+_line_observer: ContextVar = ContextVar("godel_line_observer", default=None)
+
+# _step_idempotent is True when the enclosing @step was decorated with
+# idempotent=True.  run() and agent.__call__() read this to decide whether
+# a STARTED-only log entry is safe to re-execute.
+_step_idempotent: ContextVar[bool] = ContextVar("godel_step_idempotent", default=False)
+
+
+def get_event_log():
+    """Retrieve the EventLog from the current workflow context."""
+    ctx = _current_workflow.get()
+    if ctx is None or ctx.event_log is None:
+        raise RuntimeError("get_event_log() called outside a @workflow")
+    return ctx.event_log