keelrun 0.1.0__tar.gz

keelrun-0.1.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: keelrun
+Version: 0.1.0
+Summary: Keel — resilience as a zero-config Python front end (Tier 1 bootstrap, import hook, discovery).
+License-Expression: Apache-2.0
+Requires-Python: >=3.11
+Requires-Dist: keelrun-core==0.1.0
+Provides-Extra: dev
+Requires-Dist: httpx<0.29,>=0.27; extra == "dev"
+Requires-Dist: requests<2.33,>=2.31; extra == "dev"

keelrun-0.1.0/README.md

@@ -0,0 +1,92 @@
+# keel (Python front end)
+
+Production-grade resilience for any Python program, with **zero code changes**.
+`keel run app.py` intercepts your outbound calls (httpx, requests, aiohttp,
+urllib3, boto3, psycopg, LLM SDKs via `llm:` packs, `tool:`/`mcp:` targets,
+agent-framework packs, and `py:` function targets) and applies retries, backoff,
+timeouts, circuit breakers, rate limits, and an optional dev-mode response
+cache — all declared in one `keel.toml`, enforced by the native Rust core
+inside your process. No daemon, no port, no login.
+
+```
+$ cd python/keel && pip install -e . && keelrun-py-run app.py
+keel ▸ wrapped 14 call sites (httpx ×9, openai ×4) with production defaults — `keel init` to customize
+```
+
+(Not yet published to any registry; run from source. Published name will be
+`keelrun` — see `docs/naming-decision.md`.)
+
+Uninstalling Keel removes the behavior and nothing else: your code runs
+identically (minus resilience). No imports, no context objects, no base classes.
+
+## Backends
+
+Keel resolves a backend at startup (`KEEL_BACKEND=auto|native|stub`):
+
+- **native** (`keel_core`) — the PyO3 module bundling the Rust core. Required
+  for the persistent dev cache and for Tier 2 durable flows. Built from
+  `crates/keel-py` (`maturin develop`); prebuilt wheels are not published yet.
+- **stub** — a pure-Python core (the conformance reference). Tier 1 semantics
+  only; no journal, so no persistent cache and no flows.
+
+`auto` (the default) uses the native core when importable, else the stub.
+
+## Tier 2 — durable flows (Level 2)
+
+Designate an entrypoint in `keel.toml` and `keel run` executes it as a durable
+flow: every intercepted call inside is journaled, and a rerun after a crash
+substitutes already-completed steps from the journal instead of re-firing them.
+
+```toml
+[flows]
+entrypoints = ["py:pipeline:main"]   # module `pipeline`, function `main`
+```
+
+Crash it mid-run (`kill -9`), re-run the same command, and it resumes from where
+it stopped. `keel flows` shows resumable/completed flows; `keel trace <flow>`
+shows the step ledger.
+
+### v0.1 limitations (precise, never silent)
+
+Durability is a promise; a silent downgrade would be a Level 0 surprise. So this
+is a hard, actionable error rather than a quiet fallback:
+
+- **A journal is required.** Tier 2 replay lives in `.keel/journal.db`. If the
+  native core can't attach one (e.g. `KEEL_JOURNAL=""` or an unwritable dir), a
+  designated flow fails at startup with a config-level **KEEL-E005**
+  (unsupported-configuration) naming the cause and fix — it does not run
+  un-journaled. (The stub backend, which has no
+  journal at all, reports the same class of error, pointing you at the native
+  core.)
+
+This is enforced before any effect fires.
+
+### Async flow bodies
+
+An `async def` flow entrypoint is supported: `keel run` drives it with
+`asyncio.run`, and its `await`ed intercepted calls route through the **same**
+open flow handle a synchronous flow's calls use — journaled and replayed
+identically, with full Tier 1 resilience per step. Concurrent awaited effects
+inside one flow (`asyncio.gather`) are admitted — and therefore journaled — in
+the order their calls *reach* the flow handle, never in completion order, so
+replay always reproduces the same step sequence. Keep fan-out order
+deterministic (await sequentially, or fan out in a fixed, data-independent
+order): if the runtime reaches the handle in a different order on resume
+(racing tasks whose scheduling differs run-to-run), that is nondeterminism,
+handled per `flows.on_nondeterminism` like any other divergence.
+
+## Errors
+
+Every Keel error carries a stable `KEEL-E0NN` code (see `keel explain <code>`),
+a human first line (what / why / next), and — for machines — a `--json` twin on
+the CLI. On terminal failure the original exception propagates unchanged, with a
+`keel_outcome` attachment for those who look.
+
+## Testing
+
+```
+python3 -m unittest discover python/keel     # front-end suite (stub; native legs run if keel_core is built)
+```
+
+Native-only tests (flows, persistent cache, native adapters) skip cleanly when
+`keel_core` is not built.

keelrun-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+# Published as `keelrun` (docs/naming-decision.md); the IMPORT name stays
+# `keel` (see [tool.setuptools.packages.find] below) — only the PyPI
+# distribution name changes.
+name = "keelrun"
+license = "Apache-2.0"
+version = "0.1.0"
+description = "Keel — resilience as a zero-config Python front end (Tier 1 bootstrap, import hook, discovery)."
+requires-python = ">=3.11"
+# The native core wheel (import name `keel_core`, distribution name
+# `keelrun-core`), version-locked to this front end. When it is absent at
+# runtime (exotic platform, failed install), the vendored pure-Python stub
+# (`keel_core_stub`, shipped in this wheel and byte-identical to
+# python/keel-core-stub — checked by scripts/check-release-metadata.sh) takes
+# over, so there is never a compile. Beyond that, runtime is stdlib-only:
+# adapters activate only when their library is already present in the
+# environment, and never import an absent one.
+dependencies = ["keelrun-core==0.1.0"]
+
+# Test-only dependencies (the adapter contract-test farm). Install with
+# `pip install -e '.[dev]'` or `uv pip install httpx requests`. The library
+# versions the packs certify are pinned in each pack's `_PINNED`; these ranges
+# track them. Development for Task 10 used httpx 0.28.1 + requests 2.32.5 on
+# CPython 3.14 (system interpreter).
+[project.optional-dependencies]
+dev = ["httpx>=0.27,<0.29", "requests>=2.31,<2.33"]
+
+# Internal run entry. The public `keel run` CLI (Task 8) dispatches here for
+# Python entrypoints; `keelrun-py-run app.py [args...]` runs a script directly.
+[project.scripts]
+keelrun-py-run = "keel._run:main_run_entry"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+# `keel*` also picks up the vendored `keel_core_stub` fallback (see above).
+include = ["keel*"]

keelrun-0.1.0/setup.cfg

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

keelrun-0.1.0/src/keel/__init__.py

@@ -0,0 +1,26 @@
+"""Keel — the Python front end (Tier 1: resilience, zero code changes).
+
+`keel run app.py` installs, before user code loads: (1) a `sys.meta_path`
+import hook that wraps functions matching `py:` policy targets, and (2)
+per-call discovery recording to `.keel/discovery.db`. The resilience
+semantics live in the backend (`keel_core` native module when importable,
+else the in-repo pure-Python `keel_core_stub`); this package is the thin,
+stdlib-only front end that drives it.
+
+DX invariants (docs/dx-spec.md §3) this package must uphold:
+  1. zero code changes in user code;
+  2. uninstall = remove the package (no lock-in): see `uninstall_keel`;
+  4. silence on success (one stderr banner at startup, then quiet);
+  5. never swallow errors — the original exception propagates unchanged,
+     with a `keel_outcome` attachment for those who look;
+  and KEEL_DISABLE=1 makes a run byte-identical to one without Keel.
+
+The public entry points are `keel.bootstrap.install_keel` /
+`uninstall_keel` and the `keel._run` runner used by `python -m keel run`.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

keelrun-0.1.0/src/keel/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m keel run app.py [args...]` — the module entry point."""
+
+from __future__ import annotations
+
+from ._run import main_module
+
+main_module()

keelrun-0.1.0/src/keel/_backend.py

@@ -0,0 +1,149 @@
+"""Backend selection, isolated behind one seam (architecture §5.1, "the swap").
+
+A backend exposes `configure(policy)`, `execute(request, effect)`, and
+`report()` — the four-operation core surface the stub defines (advance_clock
+is test-only and unused here). Selection:
+
+  * native (`keel_core`) — the eventual PyO3 module (Task 6/14); probed by
+    import and required to expose `configure`/`execute`. It may not exist
+    yet, so a failed import is normal.
+  * stub (`keel_core_stub.KeelCoreStub`) — the in-repo pure-Python core.
+
+`KEEL_BACKEND` overrides selection:
+  * `stub`   → force the stub, never probe native
+  * `native` → require `keel_core`; raise KEEL-E040 if not loadable
+  * `auto` / unset → native if loadable, else the stub
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+from pathlib import Path
+from typing import Any, Mapping, Protocol, runtime_checkable
+
+from ._errors import KeelError
+
+
+@runtime_checkable
+class Backend(Protocol):
+    def configure(self, policy: dict[str, Any]) -> None: ...
+
+    def execute(self, request: dict[str, Any], effect: Any) -> dict[str, Any]: ...
+
+    def report(self) -> dict[str, Any]: ...
+
+
+class _NativeBackend:
+    """Front-end adapter over the native ``keel_core`` core, adding one thing the
+    PyO3 surface does not expose: ``layer(target, key)``, resolved from the
+    configured policy exactly as the stub's ``_layer`` / Node's
+    ``NativeBackend.layer`` do. The adapter packs read ``backend.layer`` to honor
+    ``idempotency.header`` and gate cache-body buffering; without this the knob is
+    dead under native (a Python/Node parity break). Every other attribute
+    (``execute``/``execute_async``/``report``/``persistent``/the flow surface)
+    delegates straight through, so the swap is transparent."""
+
+    def __init__(self, core: Any) -> None:
+        self._core = core
+        self._policy: dict[str, Any] = {}
+
+    def configure(self, policy: dict[str, Any]) -> None:
+        self._policy = policy if isinstance(policy, dict) else {}
+        self._core.configure(policy)
+
+    def layer(self, target: str, key: str) -> Any:
+        t = self._policy.get("target")
+        if isinstance(t, dict) and isinstance(t.get(target), dict) and key in t[target]:
+            return t[target][key]
+        defaults = self._policy.get("defaults")
+        if not isinstance(defaults, dict):
+            return None
+        if target.startswith("llm:"):
+            llm = defaults.get("llm")
+            if isinstance(llm, dict) and key in llm:
+                return llm[key]
+        outbound = defaults.get("outbound")
+        return outbound.get(key) if isinstance(outbound, dict) else None
+
+    def __getattr__(self, name: str) -> Any:
+        # Delegate everything else to the native core (execute, execute_async,
+        # report, persistent, enter_flow/exit_flow/journal_*, advance_clock, …).
+        return getattr(self._core, name)
+
+
+def _journal_path(cwd: str | Path | None, env: Mapping[str, str]) -> str | None:
+    """Where the native core attaches its journal (persistent dev cache + Tier 2).
+    `KEEL_JOURNAL` overrides the path; an explicit empty value disables it. This
+    is the *construction-time* default: keel.toml's `journal` key replaces it at
+    configure time unless KEEL_JOURNAL is set, in which case the env wins
+    (see ``bootstrap.apply_journal_env_override``)."""
+    override = env.get("KEEL_JOURNAL")
+    if override is not None:
+        return override or None  # empty string ⇒ no journal
+    base = Path(cwd) if cwd is not None else Path.cwd()
+    return str(base / ".keel" / "journal.db")
+
+
+def _try_load_native(journal_path: str | None) -> Backend | None:
+    try:
+        mod = importlib.import_module("keel_core")
+    except ImportError:
+        return None
+    ctor = getattr(mod, "KeelCore", None) or getattr(mod, "Core", None)
+    if ctor is None:
+        return None
+    inst = None
+    if journal_path:
+        try:
+            inst = ctor(journal_path=journal_path)  # attaches the persistent journal
+        except Exception:
+            inst = None  # journal open failed — fall back to an in-memory native core
+    if inst is None:
+        inst = ctor()
+    if callable(getattr(inst, "configure", None)) and callable(getattr(inst, "execute", None)):
+        # The native KeelCore exposes configure/execute/execute_async/report/
+        # persistent; wrap it only to add `layer(target, key)` (idempotency.header
+        # + cache-ttl gate parity), delegating everything else.
+        return _NativeBackend(inst)  # type: ignore[return-value]
+    return None
+
+
+def load_backend(
+    preferred: str | None = None,
+    *,
+    cwd: str | Path | None = None,
+    env: Mapping[str, str] | None = None,
+) -> Backend:
+    """Resolve the runtime backend per `KEEL_BACKEND` (or `preferred`). Under a
+    native backend, a journal is attached at `<cwd>/.keel/journal.db` (created on
+    demand) so the dev cache's `scope=persistent` replays across runs."""
+    environ = env if env is not None else os.environ
+    choice = (preferred if preferred is not None else environ.get("KEEL_BACKEND", "auto")) or "auto"
+    if choice not in ("auto", "native", "stub"):
+        # A user env-var mistake, not a Keel bug — E001 (config-level), not E040.
+        raise KeelError(
+            "KEEL-E001",
+            f"KEEL_BACKEND must be one of auto, native, or stub (got {choice!r}); "
+            "unset it or correct the value",
+        )
+
+    if choice != "stub":
+        native = _try_load_native(_journal_path(cwd, environ))
+        if native is not None:
+            return native
+        if choice == "native":
+            # A missing build/install is a user-environment problem, not a Keel
+            # bug, and not a malformed policy: the configuration is valid, the
+            # capability is absent — E005 (unsupported-configuration) with a
+            # concrete next step, never E040 ("file an issue").
+            raise KeelError(
+                "KEEL-E005",
+                "KEEL_BACKEND=native requires the keel_core native module, which is not "
+                "installed; build it (`maturin develop -m crates/keel-py/Cargo.toml`) or "
+                "unset KEEL_BACKEND to use the pure-Python stub",
+            )
+
+    from keel_core_stub import KeelCoreStub
+
+    return KeelCoreStub()

keelrun-0.1.0/src/keel/_defaults.py

@@ -0,0 +1,116 @@
+"""Level 0 embedded smart-defaults pack (DX spec §1) + the policy-merge helper.
+
+The policy applied when no keel.toml is present. It MIRRORS
+contracts/defaults.toml verbatim (that file is the frozen source of truth);
+we embed rather than read it so the installed package is self-contained
+(stdlib-only, works offline). Drift against the contract is caught by the
+parity test, which parses contracts/defaults.toml with `tomllib` and asserts
+deep equality when the repo file is present.
+
+`apply_pack_defaults` layers these defaults (and any provider-pack fragments)
+UNDER the user's keel.toml — the Python twin of `applyPackDefaults` in
+node/keel/src/defaults.mjs; with no pack fragments it is identical to the Node
+twin, and both front ends must agree (merge parity is a cross-language
+contract).
+
+The Level 0 hard rules — never change success-path semantics; never retry
+non-idempotent calls; do nothing if a call can't be wrapped safely — are
+BEHAVIOR, not config, and are enforced in the front end / backend, not here.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import Any, Iterable
+
+
+def outbound_defaults() -> dict[str, Any]:
+    """`[defaults.outbound]` — any intercepted network call."""
+    return {
+        "timeout": "30s",
+        "retry": {
+            "attempts": 3,
+            "schedule": "exp(200ms, x2, max 30s, jitter)",
+            "on": ["conn", "timeout", "429", "5xx"],
+        },
+        "breaker": {"failures": 5, "cooldown": "15s"},
+    }
+
+
+def llm_defaults() -> dict[str, Any]:
+    """`[defaults.llm]` — any `llm:*` target; the generic LLM pack layer.
+
+    Retry-After-aware retry (retry on conn/timeout/429/5xx; the core waits
+    `max(schedule_wait, retry_after)`) plus the dev-loop response cache
+    (`cache = { mode = "dev" }`, resolved to a concrete ttl off-prod and
+    dropped in prod by `keel.packs.llm.resolve_dev_cache`).
+    """
+    return {
+        "timeout": "120s",
+        "retry": {
+            "attempts": 6,
+            "schedule": "exp(500ms, x2, max 60s, jitter)",
+            "on": ["conn", "timeout", "429", "5xx"],
+        },
+        "breaker": {"failures": 5, "cooldown": "30s"},
+        "cache": {"mode": "dev"},
+    }
+
+
+def level0_defaults() -> dict[str, Any]:
+    """The embedded Level 0 policy, as the dict the backend's `configure`
+    expects (identical shape to keel.toml parsed to JSON)."""
+    return {"defaults": {"outbound": outbound_defaults(), "llm": llm_defaults()}}
+
+
+def _table(v: Any) -> dict[str, Any]:
+    return v if isinstance(v, dict) else {}
+
+
+def apply_pack_defaults(
+    policy: dict[str, Any],
+    pack_fragments: Iterable[dict[str, Any]] = (),
+) -> dict[str, Any]:
+    """Merge Level 0 defaults, then provider-pack fragments, then the user
+    policy — precedence ``defaults < packs < user`` — filling in any
+    ``defaults.outbound`` / ``defaults.llm`` key a higher layer did not set,
+    while a higher layer replaces a key it DOES set wholesale (the
+    per-layer-wholesale semantics of the defaults.toml header, matching the
+    engine's own per-key layer resolution).
+
+    Target tables are left untouched — the engine resolves target →
+    defaults.llm → defaults.outbound precedence per key at execute time.
+
+    Provider packs (``keel.packs.openai_pack`` / ``anthropic_pack``) currently
+    emit the generic ``[defaults.llm]`` layer, so folding their fragments is the
+    identity over the embedded defaults; the parameter is the seam by which a
+    future per-provider refinement would take effect.
+
+    Returns a NEW policy; the input is never mutated. Idempotent on
+    ``level0_defaults()``. Mirrors Node's ``applyPackDefaults`` (empty
+    ``pack_fragments`` → identical result).
+    """
+    out = deepcopy(policy) if isinstance(policy, dict) else {}
+    user_defaults = _table(out.get("defaults"))
+
+    pack_outbound: dict[str, Any] = {}
+    pack_llm: dict[str, Any] = {}
+    for frag in pack_fragments:
+        frag_defaults = _table(frag.get("defaults")) if isinstance(frag, dict) else {}
+        pack_outbound.update(_table(frag_defaults.get("outbound")))
+        pack_llm.update(_table(frag_defaults.get("llm")))
+
+    out["defaults"] = {
+        **user_defaults,
+        "outbound": {
+            **outbound_defaults(),
+            **pack_outbound,
+            **_table(user_defaults.get("outbound")),
+        },
+        "llm": {
+            **llm_defaults(),
+            **pack_llm,
+            **_table(user_defaults.get("llm")),
+        },
+    }
+    return out