aetherius 0.2.0__py3-none-any.whl

aetherius/__init__.py

@@ -0,0 +1,42 @@
+"""Aetherius: a fixed, robust web-bot engine driven by declarative instruction files (Blueprints).
+
+Public surface. Heavy machinery lives in subpackages and is imported lazily so that
+``import aetherius`` stays cheap and dependency-light. Blueprints are executed in-process
+through the :class:`Aetherius` facade, or from any language through the local daemon.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Mapping
+
+from .version import __version__
+
+if TYPE_CHECKING:
+    from .core.runtime.result import Result
+
+__all__ = ["Aetherius", "__version__"]
+
+
+class Aetherius:
+    """In-process entry point: load a Blueprint and run it.
+
+    The facade is deliberately thin. It defers to ``aetherius.core.runtime`` for execution
+    so that importing the package never pulls in Act-specific dependencies (Playwright, ONNX, …).
+    """
+
+    def run(
+        self,
+        blueprint: str,
+        *,
+        inputs: Mapping[str, Any] | None = None,
+        secrets: Mapping[str, str] | None = None,
+    ) -> "Result":
+        """Execute a Blueprint file and return its :class:`~aetherius.core.runtime.result.Result`.
+
+        ``blueprint`` is a path to a JSON or YAML instruction file; ``inputs`` fills its declared
+        parameters and ``secrets`` provides runtime-only credentials that are never persisted.
+        """
+        from .core.blueprint.loader import load_blueprint
+        from .core.runtime.engine import RunEngine
+
+        return RunEngine().run(load_blueprint(blueprint), inputs=inputs, secrets=secrets)

aetherius/__main__.py

@@ -0,0 +1,12 @@
+"""Enable ``python -m aetherius`` as an alias for the ``aetherius`` console script.
+
+Used by the Console and the TypeScript SDK to spawn the daemon with the current interpreter, without
+depending on the ``aetherius`` entry point being on PATH.
+"""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

aetherius/_contracts/blueprint.schema.json

@@ -0,0 +1,144 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://aetherius.dev/contracts/blueprint.schema.json",
+  "title": "Aetherius Blueprint",
+  "description": "The declarative instruction file executed by Aetherius. Language-agnostic source of truth shared by the Python core and every SDK.",
+  "type": "object",
+  "required": ["aetherius", "name", "act"],
+  "additionalProperties": false,
+  "properties": {
+    "aetherius": {
+      "type": "string",
+      "description": "Blueprint format version.",
+      "pattern": "^[0-9]+\\.[0-9]+$"
+    },
+    "name": {
+      "type": "string",
+      "description": "Dotted identifier, e.g. domain.task.",
+      "minLength": 1
+    },
+    "description": { "type": "string" },
+    "act": {
+      "description": "Execution engine.",
+      "enum": ["vector", "continuum", "oracle", "phantom"]
+    },
+    "inputs": {
+      "type": "object",
+      "description": "Declared, typed parameters that make the Blueprint reusable.",
+      "additionalProperties": { "$ref": "#/$defs/inputSpec" }
+    },
+    "secrets": {
+      "type": "array",
+      "description": "Names of runtime-only secrets. Values are injected at execution and never stored in the file.",
+      "items": { "type": "string" },
+      "uniqueItems": true
+    },
+    "vars": {
+      "type": "object",
+      "description": "Local constants (domains, paths) available for interpolation."
+    },
+    "options": { "$ref": "#/$defs/options" },
+    "vision": {
+      "type": "object",
+      "description": "Vision configuration for Oracle/Phantom.",
+      "properties": { "model": { "type": "string" } },
+      "additionalProperties": true
+    },
+    "goal": {
+      "type": "string",
+      "description": "High-level objective for Phantom (Act IV) when the run is not fully scripted."
+    },
+    "constraints": {
+      "type": "array",
+      "description": "Guardrails for Phantom.",
+      "items": { "type": "string" }
+    },
+    "steps": {
+      "type": "array",
+      "description": "The ordered action sequence (the action dictionary).",
+      "items": { "$ref": "#/$defs/step" }
+    },
+    "outputs": {
+      "type": "object",
+      "description": "Shape of the returned data, via interpolation of step results."
+    }
+  },
+  "anyOf": [
+    { "required": ["steps"] },
+    { "required": ["goal"] }
+  ],
+  "$defs": {
+    "inputSpec": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type"],
+      "properties": {
+        "type": { "enum": ["string", "number", "integer", "boolean", "date", "path", "object", "array"] },
+        "required": { "type": "boolean", "default": false },
+        "format": { "type": "string" },
+        "default": {},
+        "description": { "type": "string" }
+      }
+    },
+    "options": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "debug": {
+          "type": "boolean",
+          "default": false,
+          "description": "Visible browser + cursor overlay + slow-mo for browser Acts; structured terminal logs otherwise."
+        },
+        "stealth": { "$ref": "#/$defs/stealth" },
+        "session": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "profile": { "type": "string" },
+            "persist": { "type": "boolean", "default": false }
+          }
+        },
+        "timeout_ms": { "type": "integer", "minimum": 0 },
+        "retries": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "max": { "type": "integer", "minimum": 0 },
+            "backoff": { "enum": ["none", "linear", "exponential"] }
+          }
+        }
+      }
+    },
+    "stealth": {
+      "description": "Modular discretion. Off by default; a preset name; or an inline configuration.",
+      "oneOf": [
+        { "type": "string", "description": "\"off\" or a named preset." },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mouse": { "enum": ["off", "gestures"] },
+            "keyboard": { "enum": ["off", "human"] },
+            "scroll": { "enum": ["off", "eased"] },
+            "timing": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": { "distraction": { "type": "number", "minimum": 0, "maximum": 1 } }
+            },
+            "fingerprint": { "type": "string" }
+          }
+        }
+      ]
+    },
+    "step": {
+      "type": "object",
+      "description": "A single action. Parameters depend on the action; extra properties are allowed and validated per-action by the engine.",
+      "properties": {
+        "id": { "type": "string" },
+        "action": { "type": "string" }
+      },
+      "required": ["action"],
+      "additionalProperties": true
+    }
+  }
+}

aetherius/acts/__init__.py

@@ -0,0 +1 @@
+"""The four Acts: interchangeable execution engines behind the ActDriver protocol."""

aetherius/acts/_shared.py

@@ -0,0 +1,61 @@
+"""Act-agnostic action handlers shared by every driver.
+
+``emit``, ``wait``, ``set`` and ``assert`` carry no Act-specific behaviour: they manipulate the run
+context and the event bus, never a transport or a browser. They live here so each driver (Vector,
+Continuum, ...) inherits one implementation instead of duplicating it. Drivers dispatch to these
+from their own ``run_step`` ``match`` statement.
+"""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+from ..core.blueprint.models import StepModel
+from ..core.errors import StatusAssertionError
+from ..core.events.bus import EventBus
+from ..core.events.models import EventType, RunEvent
+from ..core.runtime.context import RunContext
+
+
+class SharedActionsMixin:
+    """Provides the Act-agnostic handlers (``emit``/``wait``/``set``/``assert``)."""
+
+    def _set(self, step: StepModel, renderer: Callable[[Any], Any]) -> dict[str, Any]:
+        value = renderer(step.extra_fields.get("value"))
+        return {"value": value}
+
+    def _assert(self, step: StepModel, renderer: Callable[[Any], Any]) -> dict[str, Any]:
+        p = step.extra_fields
+        condition: str = renderer(p.get("condition", ""))
+        if str(condition).strip().lower() not in {"true", "1", "yes"}:
+            message = renderer(p.get("message", f"Assertion failed: {p.get('condition')}"))
+            raise StatusAssertionError(expected=1, actual=0, url="<assert>", body_preview=message)
+        return {}
+
+    def _emit(
+        self,
+        step: StepModel,
+        ctx: RunContext,
+        bus: EventBus,
+        renderer: Callable[[Any], Any],
+    ) -> dict[str, Any]:
+        p = step.extra_fields
+        message: str = renderer(p.get("event", p.get("message", "")))
+        bus.emit(
+            RunEvent(
+                run_id=ctx.run_id,
+                type=EventType.PROGRESS,
+                step_id=step.id,
+                message=message,
+                level="info",
+            )
+        )
+        return {}
+
+    def _wait(self, step: StepModel, renderer: Callable[[Any], Any]) -> dict[str, Any]:
+        p = step.extra_fields
+        ms: float = float(renderer(p.get("ms", 0)))
+        if ms > 0:
+            time.sleep(ms / 1000)
+        return {}

aetherius/acts/continuum/__init__.py

@@ -0,0 +1,7 @@
+"""Act II - Continuum: scripted browser automation via Playwright."""
+
+from __future__ import annotations
+
+from .driver import ContinuumDriver
+
+__all__ = ["ContinuumDriver"]

aetherius/acts/continuum/actions.py

@@ -0,0 +1,149 @@
+"""Mapping of core actions to concrete Playwright page operations.
+
+Pure functions with a uniform signature ``(page, params, render) -> dict``: they translate a
+Blueprint step into one browser operation and return that step's outputs. Kept free of the event
+bus and filesystem on purpose, so they are trivially testable against a fake page. Artifact-producing
+actions (screenshot) and DOM reads (extract/wait_for/evaluate) live in the driver and bridge, which
+own the run context.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Mapping
+
+from ...core.errors import ActionError
+
+Renderer = Callable[[Any], Any]
+PageAction = Callable[[Any, Mapping[str, Any], Renderer], dict[str, Any]]
+
+
+def _locator(page: Any, params: Mapping[str, Any], render: Renderer) -> Any:
+    """Resolve a step's target into a Playwright locator.
+
+    ``selector`` is CSS by default; ``selector_type`` switches to ``xpath`` or ``text``.
+    """
+    selector = render(params.get("selector", ""))
+    if not selector:
+        raise ActionError("This action requires a 'selector'.")
+    selector_type = str(render(params.get("selector_type", "css")) or "css").lower()
+    if selector_type == "css":
+        return page.locator(selector)
+    if selector_type == "xpath":
+        return page.locator(selector if selector.startswith("xpath=") else f"xpath={selector}")
+    if selector_type == "text":
+        return page.get_by_text(selector)
+    raise ActionError(f"Unknown selector_type {selector_type!r} (expected css, xpath or text).")
+
+
+def navigate(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    url = render(params.get("url", ""))
+    if not url:
+        raise ActionError("navigate requires a 'url'.")
+    wait_until = render(params.get("wait_until", "load"))
+    response = page.goto(url, wait_until=wait_until)
+    return {"url": page.url, "status": response.status if response is not None else None}
+
+
+def back(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    page.go_back()
+    return {"url": page.url}
+
+
+def forward(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    page.go_forward()
+    return {"url": page.url}
+
+
+def reload(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    page.reload()
+    return {"url": page.url}
+
+
+def click(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    _locator(page, params, render).click()
+    return {}
+
+
+def fill(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    _locator(page, params, render).fill(render(params.get("value", "")))
+    return {}
+
+
+def type_text(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    text = render(params.get("text", params.get("value", "")))
+    delay = params.get("delay_ms")
+    locator = _locator(page, params, render)
+    if delay is not None:
+        locator.press_sequentially(text, delay=float(render(delay)))
+    else:
+        locator.press_sequentially(text)
+    return {}
+
+
+def press(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    key = render(params.get("key", ""))
+    if not key:
+        raise ActionError("press requires a 'key'.")
+    if params.get("selector"):
+        _locator(page, params, render).press(key)
+    else:
+        page.keyboard.press(key)
+    return {}
+
+
+def select(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    values = render(params.get("values", params.get("value")))
+    if values is None:
+        raise ActionError("select requires a 'value' or 'values'.")
+    _locator(page, params, render).select_option(values)
+    return {}
+
+
+def hover(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    _locator(page, params, render).hover()
+    return {}
+
+
+def scroll(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    if params.get("selector"):
+        _locator(page, params, render).scroll_into_view_if_needed()
+    else:
+        dx = float(render(params.get("dx", 0)) or 0)
+        dy = float(render(params.get("dy", 0)) or 0)
+        page.mouse.wheel(dx, dy)
+    return {}
+
+
+def upload(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    file = render(params.get("file", params.get("files")))
+    if not file:
+        raise ActionError("upload requires a 'file'.")
+    _locator(page, params, render).set_input_files(file)
+    return {}
+
+
+def drag(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    source = render(params.get("source", params.get("from", "")))
+    target = render(params.get("target", params.get("to", "")))
+    if not source or not target:
+        raise ActionError("drag requires 'source'/'from' and 'target'/'to' selectors.")
+    page.drag_and_drop(source, target)
+    return {}
+
+
+# Simple, side-effect-free page operations dispatched directly by the driver.
+PAGE_ACTIONS: dict[str, PageAction] = {
+    "navigate": navigate,
+    "back": back,
+    "forward": forward,
+    "reload": reload,
+    "click": click,
+    "fill": fill,
+    "type": type_text,
+    "press": press,
+    "select": select,
+    "hover": hover,
+    "scroll": scroll,
+    "upload": upload,
+    "drag": drag,
+}

aetherius/acts/continuum/bridge.py

@@ -0,0 +1,159 @@
+"""Injected-JavaScript bridge and DOM extraction helpers for scraping.
+
+Reads from the live page: ``extract`` turns a map of ``name -> {selector, as}`` into typed outputs,
+``wait_for`` blocks until a selector appears (honouring a Blueprint failure code on timeout), and
+``evaluate`` runs injected JavaScript. Like actions.py, these are pure ``(page, params, render)``
+functions so they test against a fake page.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Callable, Mapping
+
+from ...core.errors import ActionError, StepTimeoutError
+
+Renderer = Callable[[Any], Any]
+
+_NUMBER_RE = re.compile(r"-?\d+(?:[.,]\d+)?")
+
+
+def _is_timeout(exc: Exception) -> bool:
+    """True when *exc* is a Playwright (or builtin) timeout, matched by class name.
+
+    Avoids importing Playwright here so the module stays light and unit-testable.
+    """
+    return type(exc).__name__ == "TimeoutError"
+
+
+def _failure_code(on_timeout: Any) -> str | None:
+    """Parse ``"fail:CODE"`` into ``CODE``; anything else yields no code."""
+    if isinstance(on_timeout, str) and on_timeout.startswith("fail:"):
+        return on_timeout.split(":", 1)[1] or None
+    return None
+
+
+def _resolve(page: Any, selector: str, selector_type: str) -> Any:
+    if selector_type == "xpath":
+        return page.locator(selector if selector.startswith("xpath=") else f"xpath={selector}")
+    return page.locator(selector)
+
+
+def _coerce_number(text: str | None) -> float | int | None:
+    """Extract the first number from *text*, returning int when integral, else float."""
+    if not text:
+        return None
+    match = _NUMBER_RE.search(text)
+    if match is None:
+        return None
+    raw = match.group(0).replace(",", ".")
+    value = float(raw)
+    return int(value) if value.is_integer() else value
+
+
+def _read_value(target: Any, as_: str, spec: Mapping[str, Any]) -> Any:
+    """Read a single (already-resolved) locator as *as_*: text, number, html or attr."""
+    if as_ == "text":
+        return (target.inner_text() or "").strip()
+    if as_ == "number":
+        return _coerce_number(target.inner_text())
+    if as_ == "html":
+        return target.inner_html()
+    if as_ == "attr":
+        attr = spec.get("attr")
+        if not attr:
+            raise ActionError("extract 'as: attr' requires an 'attr' name.")
+        return target.get_attribute(attr)
+    raise ActionError(f"Unknown extract type {as_!r} (text, number, html, attr, list or count).")
+
+
+def _read_one(page: Any, selector: str, as_: str, spec: Mapping[str, Any]) -> Any:
+    selector_type = str(spec.get("selector_type", "css")).lower()
+    locator = _resolve(page, selector, selector_type)
+    if as_ == "count":
+        return locator.count()
+    return _read_value(locator.first, as_, spec)
+
+
+def _read_list(page: Any, selector: str, spec: Mapping[str, Any]) -> list[Any]:
+    """Read every match of *selector* as a list of values (item type via ``item``, default text)."""
+    selector_type = str(spec.get("selector_type", "css")).lower()
+    item_as = str(spec.get("item", "text")).lower()
+    locator = _resolve(page, selector, selector_type)
+    return [_read_value(target, item_as, spec) for target in locator.all()]
+
+
+def _read_records(page: Any, spec: Mapping[str, Any], render: Renderer) -> list[dict[str, Any]]:
+    """Read a repeating container into a list of records, one field per ``fields`` entry.
+
+    Each field's selector is resolved *within* its container, so a row's ``.title``/``.price`` are
+    read relative to that row rather than globally — the shape a table/list demonstration produces.
+    """
+    each = render(spec.get("each", ""))
+    if not each:
+        raise ActionError("extract records require an 'each' container selector.")
+    fields: Mapping[str, Any] = spec.get("fields") or {}
+    if not fields:
+        raise ActionError("extract records require a non-empty 'fields' map.")
+
+    records: list[dict[str, Any]] = []
+    for container in page.locator(each).all():
+        record: dict[str, Any] = {}
+        for field_name, field_spec in fields.items():
+            field_selector = render(field_spec.get("selector", ""))
+            if not field_selector:
+                raise ActionError(f"extract record field {field_name!r} requires a 'selector'.")
+            field_as = str(render(field_spec.get("as", "text"))).lower()
+            record[field_name] = _read_value(
+                container.locator(field_selector).first, field_as, field_spec
+            )
+        records.append(record)
+    return records
+
+
+def extract(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    specs: Mapping[str, Any] = params.get("outputs") or {}
+    result: dict[str, Any] = {}
+    for name, spec in specs.items():
+        if "each" in spec:
+            result[name] = _read_records(page, spec, render)
+            continue
+        selector = render(spec.get("selector", ""))
+        if not selector:
+            raise ActionError(f"extract output {name!r} requires a 'selector'.")
+        as_ = str(render(spec.get("as", "text"))).lower()
+        if as_ == "list":
+            result[name] = _read_list(page, selector, spec)
+        else:
+            result[name] = _read_one(page, selector, as_, spec)
+    return result
+
+
+def wait_for(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    selector = render(params.get("selector", ""))
+    if not selector:
+        raise ActionError("wait_for requires a 'selector'.")
+    kwargs: dict[str, Any] = {"state": render(params.get("state", "visible"))}
+    if params.get("timeout_ms") is not None:
+        kwargs["timeout"] = float(render(params.get("timeout_ms")))
+    try:
+        # `.first`: waiting is about presence, so a selector matching several elements is normal
+        # and must not trip Playwright's strict-mode (which is reserved for acting on one element).
+        page.locator(selector).first.wait_for(**kwargs)
+    except Exception as exc:
+        if _is_timeout(exc):
+            code = _failure_code(render(params.get("on_timeout")))
+            raise StepTimeoutError(
+                f"wait_for timed out for selector {selector!r}", code=code
+            ) from exc
+        raise
+    return {}
+
+
+def evaluate(page: Any, params: Mapping[str, Any], render: Renderer) -> dict[str, Any]:
+    script = render(params.get("script", params.get("expression", "")))
+    if not script:
+        raise ActionError("evaluate requires a 'script' or 'expression'.")
+    if "arg" in params:
+        return {"result": page.evaluate(script, render(params.get("arg")))}
+    return {"result": page.evaluate(script)}