ellements 0.2.0__py3-none-any.whl

ellements/fslm/builtins.py

@@ -0,0 +1,103 @@
+"""Small built-in binding functions for YAML-authored machines."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .context import FSLMContext
+
+_MISSING = object()
+
+
+def payload_exists(ctx: FSLMContext, args: dict[str, Any]) -> bool:
+    """Return whether a JSON path exists in the current event payload."""
+    return _get_path(ctx, args["path"], missing=_MISSING) is not _MISSING
+
+
+def payload_equals(ctx: FSLMContext, args: dict[str, Any]) -> bool:
+    """Return whether a JSON path equals a value."""
+    return bool(_get_path(ctx, args["path"]) == args.get("value"))
+
+
+def payload_not_equals(ctx: FSLMContext, args: dict[str, Any]) -> bool:
+    """Return whether a JSON path does not equal a value."""
+    return bool(_get_path(ctx, args["path"]) != args.get("value"))
+
+
+def var_exists(ctx: FSLMContext, args: dict[str, Any]) -> bool:
+    """Return whether a snapshot variable exists."""
+    return _get_path(ctx, args["path"], missing=_MISSING) is not _MISSING
+
+
+def var_equals(ctx: FSLMContext, args: dict[str, Any]) -> bool:
+    """Return whether a snapshot variable path equals a value."""
+    return bool(_get_path(ctx, args["path"]) == args.get("value"))
+
+
+def var_not_equals(ctx: FSLMContext, args: dict[str, Any]) -> bool:
+    """Return whether a snapshot variable path does not equal a value."""
+    return bool(_get_path(ctx, args["path"]) != args.get("value"))
+
+
+def assign(_ctx: FSLMContext, args: dict[str, Any]) -> dict[str, Any]:
+    """Return a variable assignment patch."""
+    return {str(args["path"]).removeprefix("$.snapshot.variables."): args.get("value")}
+
+
+def increment(ctx: FSLMContext, args: dict[str, Any]) -> dict[str, Any]:
+    """Return a variable increment patch."""
+    key = str(args["path"]).removeprefix("$.snapshot.variables.")
+    current = _get_path(ctx, args["path"], missing=0)
+    return {key: current + args.get("by", 1)}
+
+
+def append(ctx: FSLMContext, args: dict[str, Any]) -> dict[str, Any]:
+    """Return a variable list-append patch."""
+    key = str(args["path"]).removeprefix("$.snapshot.variables.")
+    current = _get_path(ctx, args["path"], missing=[])
+    if not isinstance(current, list):
+        current = [current]
+    return {key: [*current, args.get("value")]}
+
+
+def copy_payload_to_var(ctx: FSLMContext, args: dict[str, Any]) -> dict[str, Any]:
+    """Copy an event payload value to a snapshot variable."""
+    value = _get_path(ctx, args["payload_path"])
+    key = str(args["var_path"]).removeprefix("$.snapshot.variables.")
+    return {key: value}
+
+
+def _get_path(ctx: FSLMContext, path: str, *, missing: Any = None) -> Any:
+    root: Any
+    if path.startswith("$.event.payload"):
+        root = ctx.event.payload
+        parts = path.removeprefix("$.event.payload").strip(".").split(".")
+    elif path.startswith("$.snapshot.variables"):
+        root = ctx.snapshot.variables
+        parts = path.removeprefix("$.snapshot.variables").strip(".").split(".")
+    else:
+        root = {"event": {"payload": ctx.event.payload}, "snapshot": {"variables": ctx.snapshot.variables}}
+        parts = path.removeprefix("$.").split(".")
+    if parts == [""]:
+        return root
+    current = root
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return missing
+    return current
+
+
+__all__ = [
+    "append",
+    "assign",
+    "copy_payload_to_var",
+    "increment",
+    "payload_equals",
+    "payload_exists",
+    "payload_not_equals",
+    "var_equals",
+    "var_exists",
+    "var_not_equals",
+]

ellements/fslm/cli.py

@@ -0,0 +1,199 @@
+"""`fslm` command-line interface."""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from collections.abc import Callable
+from pathlib import Path
+from typing import Literal, cast
+
+from .definition import MachineDefinition
+from .kernel import FSLMKernel
+from .loading import load_machine_definition
+from .models import FSLMEvent, MachineSnapshot
+from .rendering import ColorMode, render_snapshot, render_step, render_validation
+from .visualization import to_mermaid
+
+OutputFormat = Literal["json", "rich"]
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="fslm",
+        description="Run and inspect ellements finite-state linguistic machines.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    validate = sub.add_parser("validate", help="Validate a Python-defined machine.")
+    validate.add_argument("spec")
+    validate.add_argument("--bindings", action="append", default=None)
+    _add_human_output_options(validate)
+    validate.set_defaults(handler=_validate)
+
+    mermaid = sub.add_parser("mermaid", help="Render a spec as Mermaid.")
+    mermaid.add_argument("spec")
+    mermaid.add_argument("--bindings", action="append", default=None)
+    mermaid.set_defaults(handler=_mermaid)
+
+    init_state = sub.add_parser("init-state", help="Create an initial snapshot.")
+    init_state.add_argument("spec")
+    init_state.add_argument("--bindings", action="append", default=None)
+    init_state.add_argument("--machine-id", default=None)
+    init_state.add_argument("--seed", type=int, default=None)
+    init_state.add_argument("--state-dir", type=Path, default=None)
+    _add_human_output_options(init_state)
+    init_state.set_defaults(handler=_init_state)
+
+    inspect = sub.add_parser("inspect", help="Print a snapshot JSON file.")
+    inspect.add_argument("snapshot", type=Path)
+    inspect.add_argument("--spec", default=None, help="Optional machine spec for state objectives.")
+    _add_human_output_options(inspect)
+    inspect.set_defaults(handler=_inspect)
+
+    step = sub.add_parser("step", help="Run one machine step.")
+    step.add_argument("spec")
+    step.add_argument("--bindings", action="append", default=None)
+    step.add_argument("--snapshot", type=Path)
+    step.add_argument("--state-dir", type=Path, default=None)
+    step.add_argument("--event", type=Path, required=True)
+    _add_human_output_options(step)
+    step.set_defaults(handler=_step)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        handler: Callable[[argparse.Namespace], int] = args.handler
+        return handler(args)
+    except Exception as exc:
+        sys.stderr.write(f"{type(exc).__name__}: {exc}\n")
+        return 1
+
+
+def _validate(args: argparse.Namespace) -> int:
+    spec = _load_definition(args).spec
+    if _output_format(args) == "rich":
+        render_validation(spec, color=_color_mode(args))
+    else:
+        print(json.dumps({"ok": True, "machine": spec.name}, sort_keys=True))
+    return 0
+
+
+def _mermaid(args: argparse.Namespace) -> int:
+    print(to_mermaid(_load_definition(args).spec), end="")
+    return 0
+
+
+def _init_state(args: argparse.Namespace) -> int:
+    spec = _load_definition(args).spec
+    snapshot = spec.initial_snapshot(
+        machine_id=args.machine_id,
+        random_seed=args.seed,
+    )
+    if args.state_dir is not None:
+        args.state_dir.mkdir(parents=True, exist_ok=True)
+        (args.state_dir / "snapshot.json").write_text(
+            json.dumps(snapshot.model_dump(mode="json"), indent=2, sort_keys=True),
+            encoding="utf-8",
+        )
+    if _output_format(args) == "rich":
+        render_snapshot(
+            snapshot,
+            spec=spec,
+            title="FSLM Initial State",
+            color=_color_mode(args),
+        )
+    else:
+        print(json.dumps(snapshot.model_dump(mode="json"), indent=2, sort_keys=True))
+    return 0
+
+
+def _inspect(args: argparse.Namespace) -> int:
+    snapshot = MachineSnapshot.model_validate(
+        json.loads(args.snapshot.read_text(encoding="utf-8"))
+    )
+    if _output_format(args) == "rich":
+        spec = _load_definition(args).spec if args.spec is not None else None
+        render_snapshot(snapshot, spec=spec, color=_color_mode(args))
+    else:
+        print(json.dumps(snapshot.model_dump(mode="json"), indent=2, sort_keys=True))
+    return 0
+
+
+def _step(args: argparse.Namespace) -> int:
+    definition = _load_definition(args)
+    snapshot_path = args.snapshot
+    if snapshot_path is None and args.state_dir is not None:
+        snapshot_path = args.state_dir / "snapshot.json"
+    if snapshot_path is None:
+        raise ValueError("--snapshot or --state-dir is required")
+    snapshot = MachineSnapshot.model_validate(json.loads(snapshot_path.read_text("utf-8")))
+    event = FSLMEvent.model_validate(json.loads(args.event.read_text(encoding="utf-8")))
+    result = asyncio.run(FSLMKernel(definition).step(snapshot, event))
+    if args.state_dir is not None:
+        args.state_dir.mkdir(parents=True, exist_ok=True)
+        (args.state_dir / "snapshot.json").write_text(
+            json.dumps(
+                result.new_snapshot.model_dump(mode="json"),
+                indent=2,
+                sort_keys=True,
+            ),
+            encoding="utf-8",
+        )
+    if _output_format(args) == "rich":
+        render_step(
+            result,
+            definition=definition,
+            event=event,
+            state_dir=args.state_dir,
+            color=_color_mode(args),
+        )
+    else:
+        print(json.dumps(result.model_dump(mode="json"), indent=2, sort_keys=True))
+    return 0
+
+
+def _add_human_output_options(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--format",
+        choices=("json", "rich"),
+        default="json",
+        help="Output format. JSON is stable for automation; rich is designed for humans.",
+    )
+    parser.add_argument(
+        "--color",
+        choices=("auto", "always", "never"),
+        default="auto",
+        help="Color handling for rich output.",
+    )
+
+
+def _output_format(args: argparse.Namespace) -> OutputFormat:
+    value = args.format
+    if value not in {"json", "rich"}:
+        raise ValueError(f"unsupported output format: {value}")
+    return cast(OutputFormat, value)
+
+
+def _color_mode(args: argparse.Namespace) -> ColorMode:
+    value = args.color
+    if value not in {"auto", "always", "never"}:
+        raise ValueError(f"unsupported color mode: {value}")
+    return cast(ColorMode, value)
+
+
+def _load_definition(args: argparse.Namespace) -> MachineDefinition:
+    bindings = getattr(args, "bindings", None)
+    return load_machine_definition(args.spec, binding_modules=list(bindings or []))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+
+
+__all__ = ["build_parser", "main"]

ellements/fslm/context.py

@@ -0,0 +1,50 @@
+"""Runtime context passed to FSLM callables."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from ellements.core import ToolRegistry
+
+from .definition import MachineDefinition
+from .models import (
+    FSLMEvent,
+    MachineSnapshot,
+    MachineSpec,
+    StateSpec,
+    TransitionSpec,
+)
+
+
+@dataclass(slots=True)
+class FSLMContext:
+    """Context object passed to deterministic and NL hooks."""
+
+    spec: MachineSpec
+    definition: MachineDefinition
+    state: StateSpec
+    transition: TransitionSpec | None
+    snapshot: MachineSnapshot
+    event: FSLMEvent
+    vars: Mapping[str, Any]
+    step_id: str
+    run_id: str | None = None
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+    @property
+    def tools(self) -> ToolRegistry | None:
+        """Tool registry available to this machine, if any."""
+        return self.definition.bindings.tools
+
+    async def call_tool(self, name: str, **arguments: Any) -> Any:
+        """Invoke a registered ellements tool by name."""
+        if self.tools is None:
+            raise KeyError(f"no tool registry configured for {name!r}")
+        if name not in self.tools:
+            raise KeyError(f"tool {name!r} is not registered")
+        return await self.tools[name].invoke(**arguments)
+
+
+__all__ = ["FSLMContext"]

ellements/fslm/definition.py

@@ -0,0 +1,163 @@
+"""Executable FSLM definitions and runtime bindings."""
+
+from __future__ import annotations
+
+import importlib
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from types import ModuleType
+from typing import Any, cast
+
+from ellements.core import ToolRegistry
+
+from .models import MachineSpec
+
+BindingCallable = Callable[..., Any]
+
+
+@dataclass
+class RuntimeBindings:
+    """Non-serializable runtime objects referenced by a `MachineSpec`."""
+
+    guards: dict[str, BindingCallable] = field(default_factory=dict)
+    invariants: dict[str, BindingCallable] = field(default_factory=dict)
+    effects: dict[str, BindingCallable] = field(default_factory=dict)
+    actions: dict[str, BindingCallable] = field(default_factory=dict)
+    outputs: dict[str, BindingCallable] = field(default_factory=dict)
+    evaluators: dict[str, Any] = field(default_factory=dict)
+    modules: dict[str, ModuleType] = field(default_factory=dict)
+    tools: ToolRegistry | None = None
+
+    def merge(self, other: RuntimeBindings) -> RuntimeBindings:
+        """Return a binding set with `other` taking precedence."""
+        return RuntimeBindings(
+            guards={**self.guards, **other.guards},
+            invariants={**self.invariants, **other.invariants},
+            effects={**self.effects, **other.effects},
+            actions={**self.actions, **other.actions},
+            outputs={**self.outputs, **other.outputs},
+            evaluators={**self.evaluators, **other.evaluators},
+            modules={**self.modules, **other.modules},
+            tools=other.tools or self.tools,
+        )
+
+    def resolve(self, ref: str, category: str) -> BindingCallable:
+        """Resolve a binding reference for one callable category."""
+        registry = self._registry(category)
+        if ref in registry:
+            return registry[ref]
+        if ref.startswith("builtin."):
+            return _builtin(ref)
+        if "." in ref:
+            alias, _, name = ref.partition(".")
+            module = self.modules.get(alias)
+            if module is not None and hasattr(module, name):
+                value = getattr(module, name)
+                if callable(value):
+                    return cast(BindingCallable, value)
+                raise TypeError(f"binding {ref!r} is not callable")
+        imported = _import_ref(ref)
+        if imported is not None:
+            return imported
+        raise KeyError(f"unresolved {category} binding reference {ref!r}")
+
+    def _registry(self, category: str) -> dict[str, BindingCallable]:
+        registries = {
+            "guard": self.guards,
+            "invariant": self.invariants,
+            "effect": self.effects,
+            "action": self.actions,
+            "output": self.outputs,
+        }
+        return registries.get(category, {})
+
+
+@dataclass
+class MachineDefinition:
+    """Executable machine definition: serializable spec plus bindings."""
+
+    spec: MachineSpec
+    bindings: RuntimeBindings = field(default_factory=RuntimeBindings)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.spec, name)
+
+    def initial_snapshot(self, **kwargs: Any) -> Any:
+        """Delegate initial snapshot creation to the spec."""
+        return self.spec.initial_snapshot(**kwargs)
+
+    def to_json_file(self, path: str) -> None:
+        """Write the serializable spec as JSON."""
+        self.spec.to_json_file(path)
+
+
+def coerce_definition(
+    value: MachineDefinition | MachineSpec | Any,
+    *,
+    bindings: RuntimeBindings | None = None,
+) -> MachineDefinition:
+    """Normalize specs/builders/callables into a `MachineDefinition`."""
+    if isinstance(value, MachineDefinition):
+        if bindings is None:
+            return value
+        return MachineDefinition(value.spec, value.bindings.merge(bindings))
+    if isinstance(value, MachineSpec):
+        return MachineDefinition(value, bindings or RuntimeBindings())
+    build = getattr(value, "build", None)
+    if callable(build):
+        return coerce_definition(build(), bindings=bindings)
+    if callable(value):
+        return coerce_definition(value(), bindings=bindings)
+    raise TypeError(
+        "expected MachineDefinition, MachineSpec, builder with build(), "
+        "or callable returning one"
+    )
+
+
+def bindings_from_mapping(mapping: Mapping[str, Mapping[str, BindingCallable]]) -> RuntimeBindings:
+    """Build bindings from a nested mapping keyed by category."""
+    return RuntimeBindings(
+        guards=dict(mapping.get("guards", {})),
+        invariants=dict(mapping.get("invariants", {})),
+        effects=dict(mapping.get("effects", {})),
+        actions=dict(mapping.get("actions", {})),
+        outputs=dict(mapping.get("outputs", {})),
+    )
+
+
+def _builtin(ref: str) -> BindingCallable:
+    from . import builtins
+
+    name = ref.removeprefix("builtin.")
+    value = getattr(builtins, name, None)
+    if callable(value):
+        return cast(BindingCallable, value)
+    raise KeyError(f"unknown built-in binding {ref!r}")
+
+
+def _import_ref(ref: str) -> BindingCallable | None:
+    module_name: str
+    attr_name: str
+    if ":" in ref:
+        module_name, attr_name = ref.rsplit(":", 1)
+    elif "." in ref:
+        module_name, attr_name = ref.rsplit(".", 1)
+    else:
+        return None
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError:
+        return None
+    value = getattr(module, attr_name)
+    if not callable(value):
+        raise TypeError(f"binding {ref!r} is not callable")
+    return cast(BindingCallable, value)
+
+
+__all__ = [
+    "BindingCallable",
+    "MachineDefinition",
+    "RuntimeBindings",
+    "bindings_from_mapping",
+    "coerce_definition",
+]

ellements/fslm/det.py

@@ -0,0 +1,173 @@
+"""Deterministic helper namespace for FSLM definitions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .models import ActionSpec, EffectSpec, GuardSpec, InvariantSpec, OutputSpec
+
+
+@dataclass(frozen=True)
+class BoundGuard:
+    spec: GuardSpec
+    fn: Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class BoundInvariant:
+    spec: InvariantSpec
+    fn: Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class BoundOutput:
+    spec: OutputSpec
+    fn: Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class BoundAction:
+    spec: ActionSpec
+    fn: Callable[..., Any] | None = None
+    argument_factory: Callable[..., Any] | None = None
+
+
+@dataclass(frozen=True)
+class BoundEffect:
+    spec: EffectSpec
+    fn: Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class Increment:
+    path: str
+    by: int | float = 1
+
+
+def guard(
+    id: str,
+    fn: Callable[..., Any] | None = None,
+    *,
+    ref: str | None = None,
+    args: Mapping[str, Any] | None = None,
+    min_confidence: float | None = None,
+) -> GuardSpec | BoundGuard:
+    """Declare a deterministic guard."""
+    spec = GuardSpec(
+        id=id,
+        kind="deterministic",
+        ref=ref or id,
+        args=dict(args or {}),
+        min_confidence=min_confidence,
+    )
+    return BoundGuard(spec, fn) if fn is not None else spec
+
+
+def invariant(
+    id: str,
+    fn: Callable[..., Any] | None = None,
+    *,
+    ref: str | None = None,
+    args: Mapping[str, Any] | None = None,
+    severity: str = "error",
+) -> InvariantSpec | BoundInvariant:
+    """Declare a deterministic invariant."""
+    spec = InvariantSpec(
+        id=id,
+        kind="deterministic",
+        ref=ref or id,
+        args=dict(args or {}),
+        severity=severity,  # type: ignore[arg-type]
+    )
+    return BoundInvariant(spec, fn) if fn is not None else spec
+
+
+def output(
+    type: str,
+    fn: Callable[..., Any] | None = None,
+    *,
+    ref: str | None = None,
+    args: Mapping[str, Any] | None = None,
+    description: str = "",
+) -> OutputSpec | BoundOutput:
+    """Declare a deterministic output."""
+    spec = OutputSpec(
+        type=type,
+        kind="deterministic",
+        ref=ref or type,
+        args=dict(args or {}),
+        description=description,
+    )
+    return BoundOutput(spec, fn) if fn is not None else spec
+
+
+def action(
+    tool: str,
+    *,
+    name: str | None = None,
+    arguments: Mapping[str, Any] | Callable[..., Any] | None = None,
+    requires_safety_check: bool = False,
+    args: Mapping[str, Any] | None = None,
+) -> BoundAction | ActionSpec:
+    """Declare a deterministic tool action."""
+    spec = ActionSpec(
+        name=name or tool,
+        kind="tool",
+        tool=tool,
+        arguments=dict(arguments or {}) if isinstance(arguments, Mapping) else {},
+        args=dict(args or {}),
+        requires_approval=requires_safety_check,
+    )
+    if callable(arguments):
+        return BoundAction(spec, argument_factory=arguments)
+    return spec
+
+
+def call(
+    name: str,
+    fn: Callable[..., Any],
+    *,
+    args: Mapping[str, Any] | None = None,
+) -> BoundAction:
+    """Declare a deterministic side-effectful Python call."""
+    spec = ActionSpec(
+        name=name,
+        kind="deterministic",
+        ref=name,
+        args=dict(args or {}),
+    )
+    return BoundAction(spec, fn=fn)
+
+
+def effect(
+    id: str,
+    fn: Callable[..., Any],
+    *,
+    args: Mapping[str, Any] | None = None,
+) -> BoundEffect:
+    """Declare a pure deterministic effect function."""
+    return BoundEffect(EffectSpec(id=id, ref=id, args=dict(args or {})), fn)
+
+
+def increment(path: str, by: int | float = 1) -> Increment:
+    """Declare an increment effect shorthand for `.effects(...)`."""
+    return Increment(path=path, by=by)
+
+
+__all__ = [
+    "BoundAction",
+    "BoundEffect",
+    "BoundGuard",
+    "BoundInvariant",
+    "BoundOutput",
+    "Increment",
+    "action",
+    "call",
+    "effect",
+    "guard",
+    "increment",
+    "invariant",
+    "output",
+]