aetherius 0.2.0__py3-none-any.whl

aetherius/core/actions/base.py

@@ -0,0 +1,99 @@
+"""Capability enum and ACT_CAPABILITIES map: the authoritative action/Act compatibility table."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class Capability(str, Enum):
+    # ── Act I — Vector ──────────────────────────────────────────────────────────
+    HTTP_REQUEST = "http.request"
+    SET = "set"
+    ASSERT = "assert"
+    EMIT = "emit"
+    WAIT = "wait"
+
+    # ── Act II — Continuum (browser) ─────────────────────────────────────────
+    NAVIGATE = "navigate"
+    BACK = "back"
+    FORWARD = "forward"
+    RELOAD = "reload"
+    CLICK = "click"
+    FILL = "fill"
+    TYPE = "type"
+    PRESS = "press"
+    SELECT = "select"
+    HOVER = "hover"
+    SCROLL = "scroll"
+    UPLOAD = "upload"
+    DRAG = "drag"
+    SCREENSHOT = "screenshot"
+    EVALUATE = "evaluate"
+    WAIT_FOR = "wait_for"
+
+    # ── Flow (all Acts) ──────────────────────────────────────────────────────
+    IF = "if"
+    REPEAT = "repeat"
+    FOR_EACH = "for_each"
+
+    # ── Extract (all Acts) ───────────────────────────────────────────────────
+    EXTRACT = "extract"
+
+
+_VECTOR_CAPS: frozenset[Capability] = frozenset(
+    {
+        Capability.HTTP_REQUEST,
+        Capability.SET,
+        Capability.ASSERT,
+        Capability.EMIT,
+        Capability.WAIT,
+        Capability.IF,
+        Capability.FOR_EACH,
+        Capability.EXTRACT,
+    }
+)
+
+_CONTINUUM_CAPS: frozenset[Capability] = _VECTOR_CAPS | frozenset(
+    {
+        Capability.NAVIGATE,
+        Capability.BACK,
+        Capability.FORWARD,
+        Capability.RELOAD,
+        Capability.CLICK,
+        Capability.FILL,
+        Capability.TYPE,
+        Capability.PRESS,
+        Capability.SELECT,
+        Capability.HOVER,
+        Capability.SCROLL,
+        Capability.UPLOAD,
+        Capability.DRAG,
+        Capability.SCREENSHOT,
+        Capability.EVALUATE,
+        Capability.WAIT_FOR,
+        Capability.REPEAT,
+    }
+)
+
+ACT_CAPABILITIES: dict[str, frozenset[Capability]] = {
+    "vector": _VECTOR_CAPS,
+    "continuum": _CONTINUUM_CAPS,
+    # Oracle and Phantom inherit all Continuum capabilities plus vision-specific ones.
+    "oracle": _CONTINUUM_CAPS,
+    "phantom": _CONTINUUM_CAPS,
+}
+
+
+# Actions listed in ACT_CAPABILITIES but not yet dispatched by the Act's driver: declaring them
+# keeps the capability table forward-looking, but the builder must flag them "not runnable yet".
+# ``extract`` (vector) is implemented inside ``http.request`` rather than as a standalone step;
+# ``http.request`` (continuum) is inherited from the vector capability set but the browser driver
+# does not run it yet. Guarded by tests/unit/acts/test_action_dispatch.py, which fails the moment a
+# declared capability is neither dispatched nor listed here; shrink each entry as drivers catch up.
+# Only runnable Acts appear (see IMPLEMENTED_ACTS).
+PENDING_ACTIONS: dict[str, frozenset[Capability]] = {
+    "vector": frozenset({Capability.IF, Capability.FOR_EACH, Capability.EXTRACT}),
+    "continuum": frozenset(
+        {Capability.IF, Capability.FOR_EACH, Capability.REPEAT, Capability.HTTP_REQUEST}
+    ),
+}

aetherius/core/actions/data.py

@@ -0,0 +1,126 @@
+"""Data actions: http.request, extract, assert, set, screenshot, evaluate.
+
+Specs projected by the builder catalogue. Object/array parameters (headers, form, outputs, ...) are
+edited as JSON: the schema leaves their shape open on purpose, and the placeholders show the
+expected form.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .spec import ActionSpec, ParamSpec
+
+SPECS: Final[tuple[ActionSpec, ...]] = (
+    ActionSpec(
+        "http.request",
+        "Send an HTTP request and optionally extract from the response (Act I).",
+        params=(
+            ParamSpec("method", "string", default="GET", help="HTTP method.", placeholder="POST"),
+            ParamSpec(
+                "url",
+                "string",
+                required=True,
+                help="Request URL.",
+                placeholder="{{ vars.domain }}/api",
+            ),
+            ParamSpec(
+                "headers",
+                "object",
+                help="Request headers.",
+                placeholder='{"Accept": "application/json"}',
+            ),
+            ParamSpec("params", "object", help="Query-string parameters."),
+            ParamSpec(
+                "form", "object", help="URL-encoded form body (mutually exclusive with json)."
+            ),
+            ParamSpec("json", "object", help="JSON body (mutually exclusive with form)."),
+            ParamSpec(
+                "expect", "object", help="Response assertions.", placeholder='{"status": 200}'
+            ),
+            ParamSpec(
+                "extract",
+                "object",
+                help="Named JSONPath/CSS extractions from the response.",
+                placeholder='{"items": {"from": "json", "path": "$[*]"}}',
+            ),
+        ),
+    ),
+    ActionSpec(
+        "extract",
+        "Read values from the current page's DOM into named outputs (Act II).",
+        params=(
+            ParamSpec(
+                "outputs",
+                "object",
+                required=True,
+                help="Map of output name to a selector spec (as: text/number/html/attr/list, "
+                "or each/fields for records).",
+                placeholder='{"title": {"selector": "h1", "as": "text"}}',
+            ),
+        ),
+    ),
+    ActionSpec(
+        "assert",
+        "Fail the run unless a rendered condition is truthy.",
+        params=(
+            ParamSpec(
+                "condition",
+                "string",
+                required=True,
+                help="Expression that must be truthy.",
+                placeholder="{{ steps.week.status_code == 200 }}",
+            ),
+            ParamSpec("message", "string", help="Message shown when the assertion fails."),
+        ),
+    ),
+    ActionSpec(
+        "set",
+        "Store a rendered value under this step's id, for later interpolation.",
+        params=(
+            ParamSpec(
+                "value",
+                "string",
+                required=True,
+                help="Value to store.",
+                placeholder="{{ inputs.group }}",
+            ),
+        ),
+    ),
+    ActionSpec(
+        "screenshot",
+        "Capture a screenshot artifact of the page or an element (Act II).",
+        params=(
+            ParamSpec(
+                "name", "string", help="File name for the artifact (defaults to the step id)."
+            ),
+            ParamSpec("selector", "string", help="Element to capture; omit for the whole page."),
+            ParamSpec(
+                "full_page",
+                "boolean",
+                default=False,
+                help="Capture the full scrollable page when no selector is given.",
+            ),
+            ParamSpec(
+                "selector_type",
+                "string",
+                default="css",
+                help="How to read 'selector': css (default), xpath or text.",
+            ),
+        ),
+    ),
+    ActionSpec(
+        "evaluate",
+        "Run injected JavaScript in the page and return its result (Act II).",
+        params=(
+            ParamSpec(
+                "script",
+                "string",
+                required=True,
+                help="JavaScript expression or function.",
+                placeholder="() => document.title",
+            ),
+            ParamSpec("arg", "object", help="Optional argument passed to the script."),
+        ),
+    ),
+)

aetherius/core/actions/flow.py

@@ -0,0 +1,76 @@
+"""Control-flow actions: wait, wait_for, emit, if, repeat, for_each.
+
+Specs projected by the builder catalogue. ``if``/``repeat``/``for_each`` are declared in the
+capability table but not executed by any driver yet, so the builder marks them "not runnable yet";
+their parameter shapes here are indicative and will firm up when a driver implements them.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .spec import ActionSpec, ParamSpec
+
+SPECS: Final[tuple[ActionSpec, ...]] = (
+    ActionSpec(
+        "wait",
+        "Pause for a fixed number of milliseconds.",
+        params=(ParamSpec("ms", "number", help="Milliseconds to wait.", placeholder="1000"),),
+    ),
+    ActionSpec(
+        "wait_for",
+        "Block until a selector reaches a state (Act II).",
+        params=(
+            ParamSpec(
+                "selector",
+                "string",
+                required=True,
+                help="Selector to wait for.",
+                placeholder=".results",
+            ),
+            ParamSpec(
+                "state",
+                "string",
+                default="visible",
+                help="Target state: visible, attached, hidden or detached.",
+            ),
+            ParamSpec("timeout_ms", "number", help="Give up after this many milliseconds."),
+            ParamSpec(
+                "on_timeout", "string", help="Named failure on timeout, e.g. 'fail:LOGIN_FAILED'."
+            ),
+        ),
+    ),
+    ActionSpec(
+        "emit",
+        "Emit a progress event with a message.",
+        params=(
+            ParamSpec("message", "string", help="Event message.", placeholder="LOGIN_SUCCESS"),
+        ),
+    ),
+    ActionSpec(
+        "if",
+        "Run nested steps conditionally (declared, not runnable yet).",
+        params=(
+            ParamSpec("condition", "string", help="Expression deciding the branch."),
+            ParamSpec("then", "array", help="Steps to run when the condition holds."),
+            ParamSpec("else", "array", help="Steps to run otherwise."),
+        ),
+    ),
+    ActionSpec(
+        "repeat",
+        "Run nested steps a fixed number of times (declared, not runnable yet).",
+        params=(
+            ParamSpec("times", "integer", help="How many iterations."),
+            ParamSpec("steps", "array", help="Steps to repeat."),
+        ),
+    ),
+    ActionSpec(
+        "for_each",
+        "Run nested steps once per item (declared, not runnable yet).",
+        params=(
+            ParamSpec("items", "string", help="Expression yielding the items to iterate."),
+            ParamSpec("as", "string", help="Loop variable name."),
+            ParamSpec("steps", "array", help="Steps to run per item."),
+        ),
+    ),
+)

aetherius/core/actions/interaction.py

@@ -0,0 +1,109 @@
+"""Interaction actions: click, fill, type, press, select, hover, scroll, upload, drag.
+
+Specs projected by the builder catalogue. Parameter names mirror the Playwright page operations in
+``acts/continuum/actions.py`` exactly, so the forms produce steps the driver runs unchanged.
+"""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .spec import ActionSpec, ParamSpec
+
+# Selector-based actions share these two parameters; declared once to stay in sync.
+_SELECTOR = ParamSpec(
+    "selector", "string", required=True, help="Target element selector.", placeholder="#submit"
+)
+_SELECTOR_TYPE = ParamSpec(
+    "selector_type",
+    "string",
+    default="css",
+    help="How to read 'selector': css (default), xpath or text.",
+)
+
+SPECS: Final[tuple[ActionSpec, ...]] = (
+    ActionSpec("click", "Click an element.", params=(_SELECTOR, _SELECTOR_TYPE)),
+    ActionSpec(
+        "fill",
+        "Set an input's value in one shot (clears it first).",
+        params=(
+            _SELECTOR,
+            ParamSpec(
+                "value",
+                "string",
+                required=True,
+                help="Value to set.",
+                placeholder="{{ inputs.query }}",
+            ),
+            _SELECTOR_TYPE,
+        ),
+    ),
+    ActionSpec(
+        "type",
+        "Type text character by character (for fields that react to each keystroke).",
+        params=(
+            _SELECTOR,
+            ParamSpec("text", "string", required=True, help="Text to type."),
+            ParamSpec("delay_ms", "number", help="Delay between keystrokes, in milliseconds."),
+            _SELECTOR_TYPE,
+        ),
+    ),
+    ActionSpec(
+        "press",
+        "Press a keyboard key, optionally focused on an element.",
+        params=(
+            ParamSpec("key", "string", required=True, help="Key name.", placeholder="Enter"),
+            ParamSpec("selector", "string", help="Element to focus before pressing (optional)."),
+            _SELECTOR_TYPE,
+        ),
+    ),
+    ActionSpec(
+        "select",
+        "Choose one or more options in a <select> element.",
+        params=(
+            _SELECTOR,
+            ParamSpec(
+                "values",
+                "array",
+                required=True,
+                help="Option value(s) to select.",
+                placeholder='["option-1"]',
+            ),
+            _SELECTOR_TYPE,
+        ),
+    ),
+    ActionSpec("hover", "Move the pointer over an element.", params=(_SELECTOR, _SELECTOR_TYPE)),
+    ActionSpec(
+        "scroll",
+        "Scroll an element into view, or scroll the page by a delta.",
+        params=(
+            ParamSpec("selector", "string", help="Element to scroll into view (optional)."),
+            ParamSpec("dx", "number", help="Horizontal wheel delta when no selector is given."),
+            ParamSpec("dy", "number", help="Vertical wheel delta when no selector is given."),
+            _SELECTOR_TYPE,
+        ),
+    ),
+    ActionSpec(
+        "upload",
+        "Set the file(s) of a file input.",
+        params=(
+            _SELECTOR,
+            ParamSpec(
+                "file",
+                "string",
+                required=True,
+                help="Path to the file to upload.",
+                placeholder="{{ inputs.video }}",
+            ),
+            _SELECTOR_TYPE,
+        ),
+    ),
+    ActionSpec(
+        "drag",
+        "Drag one element onto another.",
+        params=(
+            ParamSpec("source", "string", required=True, help="Selector to drag from."),
+            ParamSpec("target", "string", required=True, help="Selector to drop onto."),
+        ),
+    ),
+)

aetherius/core/actions/navigation.py

@@ -0,0 +1,32 @@
+"""Navigation actions: navigate, back, forward, reload. Specs projected by the builder catalogue."""
+
+from __future__ import annotations
+
+from typing import Final
+
+from .spec import ActionSpec, ParamSpec
+
+SPECS: Final[tuple[ActionSpec, ...]] = (
+    ActionSpec(
+        "navigate",
+        "Open a URL in the browser.",
+        params=(
+            ParamSpec(
+                "url",
+                "string",
+                required=True,
+                help="Absolute URL to open.",
+                placeholder="https://example.com",
+            ),
+            ParamSpec(
+                "wait_until",
+                "string",
+                default="load",
+                help="Load state to wait for: load, domcontentloaded, networkidle or commit.",
+            ),
+        ),
+    ),
+    ActionSpec("back", "Go back one entry in the browser history."),
+    ActionSpec("forward", "Go forward one entry in the browser history."),
+    ActionSpec("reload", "Reload the current page."),
+)

aetherius/core/actions/registry.py

@@ -0,0 +1,70 @@
+"""Central action registry: single source of truth for all supported action handlers.
+
+Handlers self-register via the @register decorator at module import time.
+The engine imports the relevant driver module to trigger registration.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from ..errors import ActionError
+from .spec import ActionSpec
+
+# action name → handler callable
+ActionHandler = Callable[..., dict[str, Any]]
+
+_registry: dict[str, ActionHandler] = {}
+
+# action name → declarative field spec, aggregated lazily from the family modules on first use.
+_specs: dict[str, ActionSpec] | None = None
+
+
+def register(name: str) -> Callable[[ActionHandler], ActionHandler]:
+    """Decorator that registers a handler function under *name* in the registry."""
+
+    def decorator(fn: ActionHandler) -> ActionHandler:
+        _registry[name] = fn
+        return fn
+
+    return decorator
+
+
+def get_handler(action_name: str) -> ActionHandler:
+    """Return the handler for *action_name* or raise ActionError."""
+    try:
+        return _registry[action_name]
+    except KeyError:
+        raise ActionError(f"Unknown action: {action_name!r}. Available: {sorted(_registry)}")
+
+
+def registered_actions() -> list[str]:
+    """Return a sorted list of all registered action names."""
+    return sorted(_registry)
+
+
+def action_specs() -> dict[str, ActionSpec]:
+    """Return every action's field spec, keyed by name.
+
+    Aggregates the per-family ``SPECS`` tuples lazily (imported here, not at module load, to keep
+    ``import aetherius`` light) and caches the result. The union covers exactly the Capability set,
+    a bijection guarded by tests/unit/core/actions/test_specs.py.
+    """
+    global _specs
+    if _specs is None:
+        from . import data, flow, interaction, navigation
+
+        collected: dict[str, ActionSpec] = {}
+        for module in (navigation, interaction, data, flow):
+            for spec in module.SPECS:
+                collected[spec.name] = spec
+        _specs = collected
+    return _specs
+
+
+def get_spec(name: str) -> ActionSpec:
+    """Return the field spec for *name* or raise ActionError."""
+    try:
+        return action_specs()[name]
+    except KeyError:
+        raise ActionError(f"Unknown action: {name!r}. Available: {sorted(action_specs())}")

aetherius/core/actions/spec.py

@@ -0,0 +1,42 @@
+"""Declarative field specs for actions: the typed metadata the builder projects into forms.
+
+The action *registry* dispatches by name; this module describes each action's parameters (name,
+kind, whether required, a one-line help, an example placeholder) so a UI can generate a form and a
+validator can flag a missing required field before the step ever runs. The specs are the single
+source the builder catalogue is a projection of — they carry no behaviour, only shape.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal
+
+# Object/array params are edited as JSON (their shape is left open by the schema on purpose);
+# scalar kinds map to a flat form field.
+ParamKind = Literal["string", "number", "integer", "boolean", "object", "array"]
+
+
+@dataclass(frozen=True)
+class ParamSpec:
+    """One parameter of an action: how a form renders it and how a validator checks it."""
+
+    name: str
+    kind: ParamKind
+    required: bool = False
+    help: str = ""
+    default: Any = None
+    # Example value shown to guide the user; a JSON snippet for object/array params.
+    placeholder: str = ""
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    """An action's name, a one-line summary, and its ordered parameters."""
+
+    name: str
+    summary: str
+    params: tuple[ParamSpec, ...] = field(default_factory=tuple)
+
+    def required_params(self) -> tuple[ParamSpec, ...]:
+        """The subset of parameters a Blueprint step must provide for this action."""
+        return tuple(p for p in self.params if p.required)

aetherius/core/blueprint/__init__.py

@@ -0,0 +1 @@
+"""Blueprint subsystem: typed model, loader, semantic validator and template interpolation for the instruction files."""

aetherius/core/blueprint/loader.py

@@ -0,0 +1,82 @@
+"""Load and parse a Blueprint from a JSON or YAML file, validate it against the JSON Schema,
+then return a typed Blueprint model."""
+
+from __future__ import annotations
+
+import importlib.resources
+import json
+from pathlib import Path
+from typing import Any
+
+import jsonschema
+import yaml
+from pydantic import ValidationError
+
+from ..errors import BlueprintLoadError, BlueprintSchemaError
+from .models import Blueprint
+
+_schema: dict[str, Any] | None = None
+
+
+def blueprint_schema() -> dict[str, Any]:
+    """Return the packaged Blueprint JSON Schema (cached singleton)."""
+    global _schema
+    if _schema is None:
+        pkg = importlib.resources.files("aetherius._contracts")
+        schema_text = (pkg / "blueprint.schema.json").read_text(encoding="utf-8")
+        _schema = json.loads(schema_text)
+    return _schema
+
+
+def _get_schema() -> dict[str, Any]:
+    """Deprecated internal alias for blueprint_schema(); kept for existing callers."""
+    return blueprint_schema()
+
+
+def validate_blueprint_data(data: Any, *, source: str = "<data>") -> Blueprint:
+    """Validate an in-memory Blueprint dict against the schema and model, returning the model.
+
+    The counterpart to :func:`load_blueprint` for data that never touched disk (the builder assembles
+    a Blueprint before there is a file). *source* only labels error messages.
+
+    Raises:
+        BlueprintSchemaError: JSON Schema violation or Pydantic constraint failure.
+    """
+    try:
+        jsonschema.validate(data, blueprint_schema())
+    except jsonschema.ValidationError as exc:
+        raise BlueprintSchemaError(
+            f"Blueprint schema violation in {source}: {exc.message}"
+        ) from exc
+
+    try:
+        return Blueprint.model_validate(data)
+    except ValidationError as exc:
+        raise BlueprintSchemaError(f"Blueprint model validation failed in {source}: {exc}") from exc
+
+
+def load_blueprint(path: str | Path) -> Blueprint:
+    """Parse a Blueprint file (JSON or YAML) and return a validated model.
+
+    Raises:
+        BlueprintLoadError: file not found or not parseable.
+        BlueprintSchemaError: JSON Schema violation or Pydantic constraint failure.
+    """
+    path = Path(path)
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        raise BlueprintLoadError(f"Blueprint file not found: {path}")
+    except OSError as exc:
+        raise BlueprintLoadError(f"Cannot read Blueprint file: {path} — {exc}") from exc
+
+    suffix = path.suffix.lower()
+    try:
+        if suffix in {".yaml", ".yml"}:
+            data: Any = yaml.safe_load(raw)
+        else:
+            data = json.loads(raw)
+    except (json.JSONDecodeError, yaml.YAMLError) as exc:
+        raise BlueprintLoadError(f"Cannot parse Blueprint file: {path} — {exc}") from exc
+
+    return validate_blueprint_data(data, source=str(path))