levain-cli 0.1.0__py3-none-any.whl

levain_recipe/translate.py

@@ -0,0 +1,142 @@
+"""Stage 4: PlusCal-to-TLA+ translation via tla2tools.jar."""
+
+from __future__ import annotations
+
+import os
+import re
+import subprocess
+import tempfile
+
+from ._java import RE_MODULE_NAME, require_java, resolve_jar
+from .models import ValidationError
+
+_TRANSLATE_TIMEOUT_S = 30
+
+
+def translate(
+    source: str,
+    module_name: str,
+) -> str | list[ValidationError]:
+    """Translate PlusCal to TLA+ using pcal.trans.
+
+    Parameters
+    ----------
+    source
+        Full TLA+ module text with PlusCal algorithm.
+    module_name
+        The module name (used for the temp filename).
+
+    Returns
+    -------
+    str | list[ValidationError]
+        The translated TLA+ source, or errors.
+    """
+    if not RE_MODULE_NAME.match(module_name):
+        return [
+            ValidationError(
+                stage="translate",
+                message="Invalid module name.",
+            )
+        ]
+    jar = resolve_jar()
+    if jar is None:
+        env_jar = os.environ.get("TLA2TOOLS_JAR")
+        if env_jar:
+            msg = f"TLA2TOOLS_JAR={env_jar!r} does not exist."
+        else:
+            msg = (
+                "tla2tools.jar not found. Set "
+                "TLA2TOOLS_JAR env var or place it "
+                "in tools/tla2tools.jar."
+            )
+        return [ValidationError(stage="translate", message=msg)]
+
+    java_or_err = require_java("translate")
+    if isinstance(java_or_err, list):
+        return java_or_err
+    java = java_or_err
+
+    with tempfile.TemporaryDirectory() as tmpdir:
+        spec_path = os.path.join(tmpdir, f"{module_name}.tla")
+        with open(spec_path, "w", encoding="utf-8") as f:
+            f.write(source)
+
+        try:
+            result = subprocess.run(
+                [
+                    java,
+                    "-cp",
+                    jar,
+                    "pcal.trans",
+                    spec_path,
+                ],
+                capture_output=True,
+                text=True,
+                timeout=_TRANSLATE_TIMEOUT_S,
+                cwd=tmpdir,
+                check=False,
+            )
+        except subprocess.TimeoutExpired:
+            return [
+                ValidationError(
+                    stage="translate",
+                    message=(
+                        "PlusCal translation timed out "
+                        f"after {_TRANSLATE_TIMEOUT_S}s."
+                    ),
+                )
+            ]
+
+        if result.returncode != 0:
+            errors = _parse_translation_errors(result.stderr + result.stdout)
+            return errors or [
+                ValidationError(
+                    stage="translate",
+                    message=(
+                        "PlusCal translation failed: "
+                        + (result.stderr or result.stdout)[:200]
+                    ),
+                )
+            ]
+
+        # Read back the translated file.
+        with open(spec_path, encoding="utf-8") as f:
+            translated = f.read()
+
+    return translated
+
+
+_RE_PCAL_ERROR = re.compile(
+    r"(?:line (\d+),?\s*column \d+)?\s*:?\s*(.*)",
+    re.IGNORECASE,
+)
+
+
+def _parse_translation_errors(
+    output: str,
+) -> list[ValidationError]:
+    """Parse pcal.trans error messages."""
+    errors: list[ValidationError] = []
+
+    for raw_line in output.splitlines():
+        line = raw_line.strip()
+        if not line:
+            continue
+        if "error" in line.lower() or "Unrecoverable" in line:
+            m = _RE_PCAL_ERROR.search(line)
+            line_num = None
+            msg = line
+            if m:
+                if m.group(1):
+                    line_num = int(m.group(1))
+                if m.group(2):
+                    msg = m.group(2).strip()
+            errors.append(
+                ValidationError(
+                    stage="translate",
+                    message=msg,
+                    line=line_num,
+                )
+            )
+
+    return errors

levain_recipe/user_input.py

@@ -0,0 +1,334 @@
+"""Projector: ``ValidatedSpec`` → user-input schema + validator.
+
+Surfaces the subset of a recipe's state that a customer can
+populate from outside the recipe — used by the API to (a) tell
+the FE what shape of input the recipe accepts and (b) validate
+``initial_state`` overlays on dispatch.
+
+Intentionally lossy: fields whose names start with ``_`` (the
+convention for harness-injected internals) and fields whose
+``reducer`` isn't in :data:`REDUCERS` are excluded.  The harness
+already overlays user-supplied state then overwrites with its own
+values in ``_build_initial_state``, so an excluded field is
+defence-in-depth: even a smuggled value would get clobbered
+before any node runs.
+
+Safe by construction: ``ValidatedSpec`` comes from tree-sitter
+parsing of ``graph.tla``; ``REDUCERS`` is a hardcoded registry of
+platform-blessed reducers.  No customer Python is imported, so a
+malicious recipe cannot influence the schema beyond declaring
+nameable variables and reducer names.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any, Literal, NotRequired, TypedDict
+
+from .models import INTERRUPT_BUILTIN, StateField, ValidatedSpec
+from .reducers import REDUCERS
+
+# Each kind names a JSON-shape the API knows how to validate and
+# the FE knows how to render.  The set is deliberately small —
+# adding a kind means teaching both sides.
+FieldKind = Literal[
+    "string",
+    "int",
+    "bool",
+    "messages",
+    "string_list",
+    "dict_list",
+]
+
+
+class FieldSchema(TypedDict):
+    """Per-field descriptor in :class:`UserInputSchema`."""
+
+    kind: FieldKind
+    reducer: NotRequired[str]  # only for list-typed fields
+    # Spec-declared default for the field (the RHS of the
+    # ``variables`` declaration in ``graph.tla``).  Surfaced so
+    # the FE can pre-fill the state editor on first paint, before
+    # any live checkpoint exists.  Omitted for list-typed fields
+    # — their PlusCal default is always ``<<>>`` which carries no
+    # useful pre-fill information for the chat shape we render.
+    default: NotRequired[Any]
+    # Free-form description authored as ``\* ...`` comments above
+    # the variable in graph.tla.  Surfaced so the FE can render a
+    # per-field helper in the State tab; omitted when the variable
+    # has no descriptive comments.
+    description: NotRequired[str]
+
+
+class UserInputSchema(TypedDict):
+    """User-settable subset of a recipe's state schema.
+
+    ``interrupting`` flags whether the recipe expects multiple
+    turns: a graph that contains an ``interrupt`` node loops back
+    to wait for the next user message between turns, while a
+    graph without one runs end-to-end on each dispatch and starts
+    fresh on the next.  The FE uses this to decide whether to
+    show a "single-shot" hint above the composer.
+    """
+
+    fields: dict[str, FieldSchema]
+    interrupting: bool
+
+
+def user_input_schema(spec: ValidatedSpec) -> UserInputSchema:
+    """Project a ``ValidatedSpec`` to its user-input schema."""
+    fields: dict[str, FieldSchema] = {}
+    for var in spec.variables:
+        if var.name.startswith("_"):
+            continue
+        descr = _field_schema(var)
+        if descr is None:
+            continue
+        fields[var.name] = descr
+    interrupting = any(
+        node.function == INTERRUPT_BUILTIN for node in spec.nodes
+    )
+    return {"fields": fields, "interrupting": interrupting}
+
+
+# Maps a spec scalar type to the FieldKind exposed externally.
+# Mirrored by ``_LIST_KIND_BY_REDUCER`` for list-typed fields.
+_SCALAR_KIND: dict[str, FieldKind] = {
+    "string": "string",
+    "int": "int",
+    "bool": "bool",
+}
+
+# Every entry maps a blessed reducer name to the FieldKind the
+# API + FE expose.  Add a row here only when both sides know how
+# to handle the new kind.
+_LIST_KIND_BY_REDUCER: dict[str, FieldKind] = {
+    "add_messages": "messages",
+    "add_str": "string_list",
+    "extend_list": "dict_list",
+}
+
+
+def _field_schema(var: StateField) -> FieldSchema | None:
+    scalar = _SCALAR_KIND.get(var.type)
+    if scalar is not None:
+        descr: FieldSchema = {"kind": scalar}
+        if var.default is not None:
+            descr["default"] = var.default
+        if var.description:
+            descr["description"] = var.description
+        return descr
+    if var.type != "list":
+        return None
+    if var.reducer is None or var.reducer not in REDUCERS:
+        return None
+    kind = _LIST_KIND_BY_REDUCER.get(var.reducer)
+    if kind is None:
+        return None
+    descr_list: FieldSchema = {"kind": kind, "reducer": var.reducer}
+    if var.description:
+        descr_list["description"] = var.description
+    return descr_list
+
+
+# ── Validation ──────────────────────────────────────────────
+
+
+# "system" is excluded intentionally: the recipe's system prompt is
+# set by the spec, not by the caller.  Allowing system-role messages
+# in user-supplied initial_state would be a prompt-injection vector.
+_VALID_MESSAGE_ROLES = ("user",)
+
+
+def validate_initial_state(
+    payload: Any,
+    schema: UserInputSchema,
+) -> list[str]:
+    """Return a list of human-readable error strings.  Empty = valid.
+
+    Validation is shallow but strict: unknown keys are rejected
+    rather than silently dropped, scalar types are checked exactly
+    (no truthy/falsy coercion, no int-from-bool), and list shapes
+    are walked one level deep.  Anything beyond the declared
+    :class:`FieldKind` set surfaces as "unknown field".
+    """
+    if not isinstance(payload, dict):
+        return ["initial_state must be a JSON object"]
+    fields = schema["fields"]
+    errors: list[str] = []
+    allowed = ", ".join(sorted(fields)) or "(none)"
+    for key, value in payload.items():
+        descr = fields.get(key)
+        if descr is None:
+            errors.append(f"Unknown field {key!r} (allowed: {allowed})")
+            continue
+        err = _validate_value(key, value, descr["kind"])
+        if err is not None:
+            errors.append(err)
+    return errors
+
+
+_KIND_VALIDATORS: dict[FieldKind, Callable[[str, Any], str | None]] = {}
+
+
+def _validate_value(key: str, value: Any, kind: FieldKind) -> str | None:
+    validator = _KIND_VALIDATORS.get(kind)
+    if validator is None:
+        return None
+    return validator(key, value)
+
+
+def _check_string(key: str, value: Any) -> str | None:
+    if not isinstance(value, str):
+        return _type_err(key, "string", value)
+    if not value:
+        return f"{key}: expected non-empty string"
+    return None
+
+
+def _check_int(key: str, value: Any) -> str | None:
+    # ``bool`` is a subclass of ``int`` in Python — exclude it
+    # explicitly so ``True`` doesn't sneak past an ``int`` field.
+    if isinstance(value, bool) or not isinstance(value, int):
+        return _type_err(key, "int", value)
+    return None
+
+
+def _check_bool(key: str, value: Any) -> str | None:
+    return None if isinstance(value, bool) else _type_err(key, "bool", value)
+
+
+def _check_string_list(key: str, value: Any) -> str | None:
+    if not isinstance(value, list) or not all(
+        isinstance(x, str) for x in value
+    ):
+        return f"{key}: expected list of strings"
+    return None
+
+
+def _check_dict_list(key: str, value: Any) -> str | None:
+    if not isinstance(value, list) or not all(
+        isinstance(x, dict) for x in value
+    ):
+        return f"{key}: expected list of objects"
+    return None
+
+
+def _type_err(key: str, expected: str, value: Any) -> str:
+    return f"{key}: expected {expected}, got {type(value).__name__}"
+
+
+def _validate_messages(key: str, value: Any) -> str | None:
+    if not isinstance(value, list) or not value:
+        return f"{key}: expected non-empty list of messages"
+    for i, m in enumerate(value):
+        if not isinstance(m, dict):
+            return f"{key}[{i}]: expected message object"
+        role = m.get("role")
+        content = m.get("content")
+        if role not in _VALID_MESSAGE_ROLES:
+            return (
+                f"{key}[{i}].role: must be one of {list(_VALID_MESSAGE_ROLES)}"
+            )
+        if not isinstance(content, str) or not content:
+            return f"{key}[{i}].content: expected non-empty string"
+        extra = set(m) - {"role", "content"}
+        if extra:
+            return f"{key}[{i}]: unknown keys {sorted(extra)}"
+    return None
+
+
+# Populated after the per-kind helpers are defined so the lookup
+# in ``_validate_value`` resolves to a real Callable at import.
+_KIND_VALIDATORS.update(
+    {
+        "string": _check_string,
+        "int": _check_int,
+        "bool": _check_bool,
+        "messages": _validate_messages,
+        "string_list": _check_string_list,
+        "dict_list": _check_dict_list,
+    }
+)
+
+
+# ── Bare-prompt convenience ─────────────────────────────────
+
+
+def primary_input_field(
+    schema: UserInputSchema,
+) -> tuple[str, FieldKind] | None:
+    """Pick the canonical user-input field for a bare-prompt dispatch.
+
+    Heuristic, in order:
+
+    * ``messages`` (the chat shape — most customer recipes).
+    * ``plan_text`` (the platform task-recipe convention —
+      build / plan / review).
+    * The first scalar string field in declaration order.
+
+    Returns ``None`` when the recipe declares no obviously usable
+    field; the caller should refuse the dispatch with a 422.
+    """
+    fields = schema["fields"]
+    msgs = fields.get("messages")
+    if msgs is not None and msgs["kind"] == "messages":
+        return "messages", "messages"
+    plan = fields.get("plan_text")
+    if plan is not None and plan["kind"] == "string":
+        return "plan_text", "string"
+    for name, descr in fields.items():
+        if descr["kind"] == "string":
+            return name, "string"
+    return None
+
+
+def wrap_prompt(prompt: str, field: str, kind: FieldKind) -> dict[str, Any]:
+    """Build the ``initial_state`` overlay for a bare-prompt dispatch.
+
+    Mirrors what the FE would have constructed itself if it knew
+    the recipe shape; centralised here so the choice of "user"
+    role / single-message wrapping lives in one spot.
+    """
+    if kind == "messages":
+        return {field: [{"role": "user", "content": prompt}]}
+    if kind == "string":
+        return {field: prompt}
+    raise ValueError(
+        f"cannot wrap a bare prompt as kind {kind!r}; supply initial_state"
+    )
+
+
+# ── Inverse: pluck human text out of an existing overlay ────
+
+
+def user_text_from_overlay(overlay: dict[str, Any]) -> str:
+    """Best-effort extraction of human-readable text from a state overlay.
+
+    The inverse of :func:`wrap_prompt`: given an ``initial_state``
+    dict, recover the user's textual input (``messages[-1].content``
+    for chat shapes, ``plan_text`` for task shapes).  Returns
+    ``""`` when nothing looks like a user message — callers fall
+    back gracefully (event log row still renders; interrupt-resume
+    treats it as an empty reply).
+
+    Used by:
+
+    * The dispatch path to populate the ``user_message`` event log.
+    * The run / round read surfaces so a chat-shape recipe shows
+      the prompt the user actually sent.
+    * The harness's interrupt-resume callback so a chat-shape
+      recipe's ``interrupt`` node gets the new turn's message back
+      from ``langgraph.types.interrupt``.
+    """
+    msgs = overlay.get("messages")
+    if isinstance(msgs, list) and msgs:
+        last = msgs[-1]
+        if isinstance(last, dict) and last.get("role") == "user":
+            content = last.get("content")
+            if isinstance(content, str):
+                return content
+    plan = overlay.get("plan_text")
+    if isinstance(plan, str):
+        return plan
+    return ""