launchhelm 0.1.0__py3-none-any.whl

launchhelm/commands.py

@@ -0,0 +1,231 @@
+"""Turn a typed function into a capability the session can register.
+
+Contract: parameter annotations ``int``, ``float``, ``str``, and ``bool``
+become scalar fields. ``list`` of those four becomes a list field. ``Schedule``
+becomes a schedule field of decimal points. A ``TypedDict`` becomes a nested
+record of those same types. ``T | None``
+or a default of ``None`` makes the field optional. A parameter named
+``context`` and annotated as ``CommandContext`` is injected and is not part
+of the schema. ``None`` returns become an empty object.
+
+Failure: ``TypeError`` for a missing annotation or a type this helper cannot
+describe.
+"""
+
+from __future__ import annotations
+
+import inspect
+import re
+import types
+from collections.abc import Callable
+from typing import (
+    Any,
+    TypedDict,
+    Union,
+    get_args,
+    get_origin,
+    get_type_hints,
+    is_typeddict,
+)
+
+from .models import Capability, CommandContext, opaque_schema
+from .values import JSONObject, JSONValue
+
+CommandFunction = Callable[..., JSONValue | None]
+_NAME = re.compile(r"^[a-z][a-z0-9_.:-]{0,127}$")
+
+
+class SchedulePoint(TypedDict):
+    """One decimal ``at`` and ``value`` on a piecewise schedule."""
+
+    at: str
+    value: str
+
+
+class Schedule(TypedDict):
+    """A command field of decimal points. ``command`` infers this annotation."""
+
+    points: list[SchedulePoint]
+
+
+def command_capability(function: CommandFunction, safe_point: str, *, name: str = "") -> Capability:
+    """Build a capability whose input fields match ``function`` parameters.
+
+    Contract: the capability name is ``name`` or the function name. The only
+    safe point is ``safe_point``.
+
+    Failure: ``TypeError`` from ``input_schema``. ``ValueError`` for a name
+    the protocol rejects.
+    """
+    chosen = name or function.__name__
+    if _NAME.fullmatch(chosen) is None:
+        raise ValueError(
+            "command name must start with a lowercase letter and contain only "
+            "lowercase letters, digits, and _.:-"
+        )
+    return Capability(
+        name=chosen,
+        provider="script",
+        version="1.0.0",
+        input_schema=input_schema(function),
+        output_schema=opaque_schema(),
+        safe_points=(safe_point,),
+    )
+
+
+def input_schema(function: CommandFunction) -> JSONObject:
+    """Return the semantic record schema for ``function`` parameters.
+
+    Failure: ``TypeError`` when a parameter has no supported annotation.
+    """
+    fields: list[JSONValue] = []
+    hints = _hints(function)
+    for parameter in _parameters(function):
+        annotation = hints.get(parameter.name, parameter.annotation)
+        field: JSONObject = {
+            "name": parameter.name,
+            "type": _type(annotation, parameter.name),
+        }
+        if _optional(annotation, parameter):
+            field["optional"] = True
+        fields.append(field)
+    return {
+        "revision": "1",
+        "root": {"kind": "record", "renderer": "form", "fields": fields},
+    }
+
+
+def adapt(
+    function: CommandFunction,
+) -> Callable[[JSONValue, CommandContext], JSONValue]:
+    """Return a handler that unpacks a payload into ``function`` parameters.
+
+    Contract: ``context`` is passed only when the function declares it.
+    ``None`` becomes ``{}``.
+
+    Failure: ``TypeError`` when the payload is not an object.
+    """
+    parameters = _parameters(function)
+    hints = _hints(function)
+    wants_context = _wants_context(function)
+
+    def handler(payload: JSONValue, context: CommandContext) -> JSONValue:
+        if not isinstance(payload, dict):
+            raise TypeError("command payload must be an object")
+        arguments: dict[str, Any] = {}
+        for parameter in parameters:
+            name = parameter.name
+            if name in payload:
+                arguments[name] = payload[name]
+                continue
+            if parameter.default is not inspect.Parameter.empty:
+                arguments[name] = parameter.default
+                continue
+            annotation = hints.get(name, parameter.annotation)
+            if _optional(annotation, parameter):
+                arguments[name] = None
+                continue
+            raise TypeError(f"command payload is missing {name}")
+        if wants_context:
+            arguments["context"] = context
+        result = function(**arguments)
+        if result is None:
+            return {}
+        return result
+
+    return handler
+
+
+def _parameters(function: CommandFunction) -> list[inspect.Parameter]:
+    signature = inspect.signature(function)
+    hints = _hints(function)
+    parameters: list[inspect.Parameter] = []
+    for parameter in signature.parameters.values():
+        if parameter.name == "self":
+            continue
+        annotation = hints.get(parameter.name, parameter.annotation)
+        if parameter.name == "context" and annotation is CommandContext:
+            continue
+        parameters.append(parameter)
+    return parameters
+
+
+def _wants_context(function: CommandFunction) -> bool:
+    hints = _hints(function)
+    return hints.get("context") is CommandContext
+
+
+def _hints(function: CommandFunction) -> dict[str, Any]:
+    try:
+        return get_type_hints(function)
+    except (NameError, TypeError, AttributeError):
+        return {}
+
+
+def _optional(annotation: object, parameter: inspect.Parameter) -> bool:
+    if parameter.default is None:
+        return True
+    origin = get_origin(annotation)
+    if origin is Union or origin is types.UnionType:
+        return type(None) in get_args(annotation)
+    return False
+
+
+def _unwrap(annotation: object) -> object:
+    origin = get_origin(annotation)
+    if origin is Union or origin is types.UnionType:
+        args = [arg for arg in get_args(annotation) if arg is not type(None)]
+        if len(args) == 1:
+            return args[0]
+    return annotation
+
+
+def _type(annotation: object, name: str, depth: int = 0) -> JSONObject:
+    annotation = _unwrap(annotation)
+    if annotation is Schedule or annotation == "Schedule":
+        return {"kind": "schedule", "renderer": "generic"}
+    if is_typeddict(annotation):
+        return _record(annotation, name, depth)
+    origin = get_origin(annotation)
+    if origin is list:
+        args = get_args(annotation)
+        if len(args) != 1:
+            raise TypeError(f"parameter {name} list must name one item type")
+        return {
+            "kind": "list",
+            "renderer": "generic",
+            "item": _type(args[0], name, depth + 1),
+        }
+    return _scalar(annotation, name)
+
+
+def _record(annotation: object, name: str, depth: int) -> JSONObject:
+    if depth > 8:
+        raise TypeError(f"parameter {name} record is nested too deeply")
+    hints = get_type_hints(annotation)
+    required = set(getattr(annotation, "__required_keys__", hints))
+    fields: list[JSONValue] = []
+    for field_name, field_type in hints.items():
+        field: JSONObject = {
+            "name": field_name,
+            "type": _type(field_type, f"{name}.{field_name}", depth + 1),
+        }
+        if field_name not in required:
+            field["optional"] = True
+        fields.append(field)
+    return {"kind": "record", "renderer": "form", "fields": fields}
+
+
+def _scalar(annotation: object, name: str) -> JSONObject:
+    if annotation is int:
+        return {"kind": "scalar", "scalar": "integer", "renderer": "numeric"}
+    if annotation is float:
+        return {"kind": "scalar", "scalar": "number", "renderer": "numeric"}
+    if annotation is str:
+        return {"kind": "scalar", "scalar": "string", "renderer": "text"}
+    if annotation is bool:
+        return {"kind": "scalar", "scalar": "boolean", "renderer": "check"}
+    raise TypeError(
+        f"parameter {name} must be int, float, str, bool, Schedule, "
+        "a TypedDict of those, a list of those, or optional"
+    )

launchhelm/env.py

@@ -0,0 +1,70 @@
+"""Load ``.env`` files without overriding the process environment.
+
+Contract: keys already set in the shell stay as they are. Files are read
+from the start directory up to the filesystem root. A file closer to the
+start wins over a parent file for keys that were unset.
+
+Failure: unreadable or malformed lines are skipped. A missing ``.env`` is
+not an error.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+
+def load_env(start: Path | None = None) -> None:
+    """Apply parent ``.env`` files onto unset environment keys.
+
+    Contract: see the module docstring. ``start`` defaults to the current
+    working directory.
+
+    Failure: none. Individual bad lines are ignored.
+    """
+    origin = (start or Path.cwd()).resolve()
+    directories: list[Path] = []
+    current = origin
+    while True:
+        directories.append(current)
+        if current.parent == current:
+            break
+        current = current.parent
+    preset = set(os.environ)
+    found: dict[str, str] = {}
+    for directory in reversed(directories):
+        path = directory / ".env"
+        if not path.is_file():
+            continue
+        for key, value in _parse(path):
+            if key not in preset:
+                found[key] = value
+    os.environ.update(found)
+
+
+def _parse(path: Path) -> list[tuple[str, str]]:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return []
+    pairs: list[tuple[str, str]] = []
+    for raw in text.splitlines():
+        line = raw.strip()
+        if not line or line.startswith("#"):
+            continue
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        key = key.strip()
+        if not key or not key.replace("_", "").isalnum() or key[0].isdigit():
+            continue
+        pairs.append((key, _unquote(value.strip())))
+    return pairs
+
+
+def _unquote(value: str) -> str:
+    if len(value) >= 2 and value[0] == value[-1] and value[0] in {'"', "'"}:
+        return value[1:-1]
+    return value

launchhelm/errors.py

@@ -0,0 +1,62 @@
+"""Public error types for the LaunchHelm Python SDK.
+
+Contract: every error carries a stable ``code`` suitable for logs and
+reconciliation. ``retryable`` is true only when repeating the same request
+with the same idempotency key is the specified recovery.
+
+Failure: these classes are the failure; they are never used as values.
+"""
+
+from __future__ import annotations
+
+
+class LaunchHelmError(Exception):
+    """Protocol, transport, or local runtime failure.
+
+    Contract: ``code`` is the machine-readable identity. ``status`` is the
+    HTTP status when the error came from a response, otherwise ``0``.
+    ``retryable`` is true only when the outcome is uncertain or the server
+    asked for a retry; it is never true for a definitive rejection.
+
+    Failure: raising this error fails the calling operation. Callers must not
+    treat a non-retryable error as success.
+    """
+
+    def __init__(
+        self, code: str, message: str, *, status: int = 0, retryable: bool = False
+    ) -> None:
+        super().__init__(f"{code}: {message}")
+        self.code = code
+        self.status = status
+        self.retryable = retryable
+
+
+class BufferFull(LaunchHelmError):
+    """A configured memory, spool, or command-journal byte budget is exhausted.
+
+    Contract: queued telemetry is preserved. The caller must shed load, wait
+    for drain, or enlarge the budget. Command-journal exhaustion fails closed
+    so tombstones cannot be dropped.
+
+    Failure: this is the failure. It is not retryable by repeating the same
+    ``log`` / ``remember`` call without releasing budget.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("buffer_full", "The configured durable buffer limit was reached")
+
+
+class RuntimeFenced(LaunchHelmError):
+    """This process no longer owns the participant execution session.
+
+    Contract: once fenced, ``log`` and ``flush`` raise this error. In-flight
+    points already snapshotted under the previous epoch remain associated
+    with that epoch. Unknown command effects are never automatically
+    re-executed.
+
+    Failure: this is terminal for the Runtime instance; construct a new one
+    after reconciliation.
+    """
+
+    def __init__(self) -> None:
+        super().__init__("fenced", "The runtime no longer owns its execution session")