aetherius 0.2.0__py3-none-any.whl

aetherius/core/extraction/json_extractor.py

@@ -0,0 +1,125 @@
+"""JSON extraction via JSONPath, with optional per-item field mapping and a safe where predicate."""
+
+from __future__ import annotations
+
+import ast
+import json
+import types
+from dataclasses import dataclass, field
+from typing import Any
+
+from jsonpath_ng.ext import parse as jpath_parse
+
+from ..errors import ExtractionError
+
+# AST node types allowed in a `where` expression.
+# Anything outside this set (calls, imports, comprehensions, …) is rejected.
+_ALLOWED_NODES = (
+    ast.Expression,
+    ast.Compare,
+    ast.Name,
+    ast.Attribute,
+    ast.Constant,
+    ast.BoolOp,
+    ast.And,
+    ast.Or,
+    ast.UnaryOp,
+    ast.Not,
+    ast.Eq,
+    ast.NotEq,
+    ast.Lt,
+    ast.LtE,
+    ast.Gt,
+    ast.GtE,
+    ast.In,
+    ast.NotIn,
+    ast.Is,
+    ast.IsNot,
+    ast.Load,
+)
+
+
+@dataclass
+class ExtractSpec:
+    from_: str  # "json" | "html"
+    path: str  # JSONPath expression, e.g. "$[*]"
+    where: str | None = None  # per-item predicate, e.g. "item.eventCategory != 'Vacances'"
+    fields: dict[str, str] = field(default_factory=dict)  # name -> JSONPath relative to item
+
+
+def _eval_predicate(expr: str, item: Any) -> bool:
+    """Evaluate a simple comparison expression against *item* with an AST safety check.
+
+    *item* is wrapped in SimpleNamespace so `item.attr` dot-access works on JSON dicts.
+    Raises ExtractionError if the expression contains disallowed AST nodes.
+    """
+    try:
+        tree = ast.parse(expr, mode="eval")
+    except SyntaxError as exc:
+        raise ExtractionError(f"Invalid where expression {expr!r}: {exc}") from exc
+
+    for node in ast.walk(tree):
+        if not isinstance(node, _ALLOWED_NODES):
+            raise ExtractionError(
+                f"Disallowed construct {type(node).__name__!r} in where expression {expr!r}. "
+                "Only comparisons and boolean logic are permitted."
+            )
+
+    ns: Any
+    if isinstance(item, dict):
+        ns = types.SimpleNamespace(**item)
+    else:
+        ns = item
+
+    try:
+        return bool(eval(compile(tree, "<where>", "eval"), {"__builtins__": {}}, {"item": ns}))
+    except Exception as exc:
+        raise ExtractionError(f"Error evaluating where expression {expr!r}: {exc}") from exc
+
+
+def _extract_fields(item_dict: dict[str, Any], fields: dict[str, str]) -> dict[str, Any]:
+    """Extract sub-fields from a single matched item using relative JSONPath expressions."""
+    result: dict[str, Any] = {}
+    for field_name, path in fields.items():
+        matches = jpath_parse(path).find(item_dict)
+        if not matches:
+            result[field_name] = None
+        elif len(matches) == 1:
+            result[field_name] = matches[0].value
+        else:
+            result[field_name] = [m.value for m in matches]
+    return result
+
+
+def extract_json(body: bytes, spec: dict[str, "ExtractSpec"]) -> dict[str, Any]:
+    """Run all extraction specs in *spec* against a JSON *body* and return the collected data.
+
+    Each key in *spec* becomes a key in the returned dict whose value is a list of matched items
+    (or a single value when only one item matches and no fields mapping is defined).
+    """
+    try:
+        data = json.loads(body)
+    except json.JSONDecodeError as exc:
+        raise ExtractionError(f"Cannot parse JSON response body: {exc}") from exc
+
+    result: dict[str, Any] = {}
+
+    for output_name, s in spec.items():
+        try:
+            matches = jpath_parse(s.path).find(data)
+        except Exception as exc:
+            raise ExtractionError(f"Invalid JSONPath {s.path!r}: {exc}") from exc
+
+        items = [m.value for m in matches]
+
+        if s.where:
+            items = [item for item in items if _eval_predicate(s.where, item)]
+
+        if s.fields:
+            items = [
+                _extract_fields(item if isinstance(item, dict) else {}, s.fields) for item in items
+            ]
+
+        result[output_name] = items
+
+    return result

aetherius/core/runtime/__init__.py

@@ -0,0 +1 @@
+"""Runtime: the orchestrator that turns a Blueprint into a Result by driving the selected Act."""

aetherius/core/runtime/context.py

@@ -0,0 +1,61 @@
+"""RunContext: mutable per-run state (resolved inputs, injected secrets, step outputs)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+from ..blueprint.models import Blueprint
+from ..errors import BlueprintValidationError
+
+
+@dataclass
+class RunContext:
+    run_id: str
+    blueprint: Blueprint
+    inputs: dict[str, Any]
+    secrets: dict[str, str]
+    step_outputs: dict[str, Any] = field(default_factory=dict)
+    started_at: datetime = field(default_factory=lambda: datetime.now(timezone.utc))
+
+    def template_ctx(self) -> dict[str, Any]:
+        """Build the Jinja2 context dict for rendering step fields and outputs."""
+        return {
+            "inputs": self.inputs,
+            "secrets": self.secrets,
+            "vars": self.blueprint.vars,
+            "env": dict(os.environ),
+            "steps": self.step_outputs,
+        }
+
+
+def resolve_inputs(
+    blueprint: Blueprint,
+    raw: Mapping[str, Any] | None,
+) -> dict[str, Any]:
+    """Validate and resolve caller-supplied inputs against the Blueprint input specs.
+
+    Raises:
+        BlueprintValidationError: a required input is missing.
+    """
+    raw = dict(raw or {})
+    resolved: dict[str, Any] = {}
+
+    for name, spec in blueprint.inputs.items():
+        if name in raw:
+            resolved[name] = raw[name]
+        elif spec.default is not None:
+            resolved[name] = spec.default
+        elif spec.required:
+            raise BlueprintValidationError(
+                f"Missing required input '{name}' for Blueprint '{blueprint.name}'."
+            )
+
+    # Pass through any extra caller inputs (Blueprint may not declare all runtime vars).
+    for name, value in raw.items():
+        if name not in resolved:
+            resolved[name] = value
+
+    return resolved

aetherius/core/runtime/engine.py

@@ -0,0 +1,188 @@
+"""RunEngine: orchestrates Act selection, step pipeline, retries, events, and Result assembly."""
+
+from __future__ import annotations
+
+import time
+import uuid
+from datetime import datetime, timezone
+from typing import Any, Mapping
+
+from ..blueprint.models import Blueprint
+from ..blueprint.template import render_value
+from ..blueprint.validator import validate_for_act
+from ..errors import AetheriusError, ActionError, RunError
+from ..events.bus import EventBus
+from ..events.models import EventType, RunEvent
+from ..events.sinks import LogSink, NullSink, Sink
+from ..runtime.context import RunContext, resolve_inputs
+from ..runtime.result import Result, RunStatus, StepResult
+
+
+IMPLEMENTED_ACTS: frozenset[str] = frozenset({"vector", "continuum"})
+
+
+def _make_driver(act: str) -> Any:
+    # Drivers are imported lazily so `import aetherius` never pulls in an Act's heavy
+    # dependencies (Playwright, ONNX, ...). Each driver defers its own extra to runtime.
+    if act == "vector":
+        from ...acts.vector.driver import VectorDriver
+
+        return VectorDriver()
+    if act == "continuum":
+        from ...acts.continuum.driver import ContinuumDriver
+
+        return ContinuumDriver()
+    raise ActionError(f"Act {act!r} is not implemented yet. Available: {sorted(IMPLEMENTED_ACTS)}.")
+
+
+class RunEngine:
+    def run(
+        self,
+        blueprint: Blueprint,
+        inputs: Mapping[str, Any] | None = None,
+        secrets: Mapping[str, str] | None = None,
+        *,
+        sinks: list[Sink] | None = None,
+        run_id: str | None = None,
+    ) -> Result:
+        validate_for_act(blueprint)
+
+        # The daemon assigns the id it returned to the caller (HTTP 202) before the run starts, so
+        # the streamed events carry a run_id the client already holds. In-process callers omit it.
+        run_id = run_id or uuid.uuid4().hex
+        started_at = datetime.now(timezone.utc)
+
+        from ...config.secrets import resolve_secrets
+
+        resolved_inputs = resolve_inputs(blueprint, inputs)
+        resolved_secrets = resolve_secrets(blueprint.secrets, secrets)
+        ctx = RunContext(
+            run_id=run_id,
+            blueprint=blueprint,
+            inputs=resolved_inputs,
+            secrets=resolved_secrets,
+            started_at=started_at,
+        )
+
+        bus = EventBus()
+        if sinks is not None:
+            for sink in sinks:
+                bus.register(sink)
+        else:
+            default_sink: Sink = (
+                LogSink(debug=blueprint.options.debug) if blueprint.options.debug else NullSink()
+            )
+            bus.register(default_sink)
+
+        driver = _make_driver(blueprint.act)
+        driver.setup(ctx)
+
+        bus.emit(
+            RunEvent(
+                run_id=run_id,
+                type=EventType.PROGRESS,
+                message=f"run started: {blueprint.name}",
+                level="info",
+            )
+        )
+
+        step_results: list[StepResult] = []
+        final_status = RunStatus.SUCCESS
+        run_error: str | None = None
+
+        try:
+            for i, step in enumerate(blueprint.steps):
+                step_key = step.id or f"_step_{i}"
+
+                bus.emit(
+                    RunEvent(
+                        run_id=run_id, type=EventType.STEP_STARTED, step_id=step.id, level="debug"
+                    )
+                )
+                t0 = time.monotonic()
+
+                def renderer(value: Any) -> Any:
+                    return render_value(value, ctx.template_ctx())
+
+                try:
+                    outputs = driver.run_step(step, ctx, bus, renderer)
+                    ctx.step_outputs[step_key] = outputs
+                    duration_ms = (time.monotonic() - t0) * 1000
+                    step_results.append(
+                        StepResult(
+                            step_id=step.id,
+                            action=step.action,
+                            status=RunStatus.SUCCESS,
+                            outputs=outputs,
+                            duration_ms=duration_ms,
+                        )
+                    )
+                    bus.emit(
+                        RunEvent(
+                            run_id=run_id,
+                            type=EventType.STEP_FINISHED,
+                            step_id=step.id,
+                            level="debug",
+                        )
+                    )
+
+                except AetheriusError as exc:
+                    duration_ms = (time.monotonic() - t0) * 1000
+                    step_results.append(
+                        StepResult(
+                            step_id=step.id,
+                            action=step.action,
+                            status=RunStatus.FAILED,
+                            error=str(exc),
+                            duration_ms=duration_ms,
+                        )
+                    )
+                    bus.emit(
+                        RunEvent(
+                            run_id=run_id,
+                            type=EventType.ERROR,
+                            step_id=step.id,
+                            message=str(exc),
+                            level="error",
+                        )
+                    )
+                    raise
+
+        except AetheriusError as exc:
+            final_status = RunStatus.FAILED
+            run_error = str(exc)
+
+        except Exception as exc:
+            final_status = RunStatus.FAILED
+            run_error = str(exc)
+            raise RunError(f"Unexpected error during run {run_id}: {exc}", cause=exc) from exc
+
+        finally:
+            driver.teardown(ctx)
+
+        # Render the outputs dict through the template engine.
+        final_outputs: dict[str, Any] = {}
+        if final_status == RunStatus.SUCCESS and blueprint.outputs:
+            final_outputs = render_value(blueprint.outputs, ctx.template_ctx())
+
+        finished_at = datetime.now(timezone.utc)
+        bus.emit(
+            RunEvent(
+                run_id=run_id,
+                type=EventType.DONE,
+                message=f"run finished: {final_status.value}",
+                level="info" if final_status == RunStatus.SUCCESS else "error",
+                data={"status": final_status.value, "error": run_error},
+            )
+        )
+
+        return Result(
+            run_id=run_id,
+            blueprint_name=blueprint.name,
+            status=final_status,
+            outputs=final_outputs,
+            step_results=step_results,
+            error=run_error,
+            started_at=started_at,
+            finished_at=finished_at,
+        )

aetherius/core/runtime/result.py

@@ -0,0 +1,39 @@
+"""Result and StepResult: structured outputs returned to the caller after a Blueprint run."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RunStatus(str, Enum):
+    SUCCESS = "success"
+    FAILED = "failed"
+    PARTIAL = "partial"
+
+
+class StepResult(BaseModel):
+    step_id: str | None
+    action: str
+    status: RunStatus
+    outputs: dict[str, Any] = Field(default_factory=dict)
+    error: str | None = None
+    duration_ms: float
+
+
+class Result(BaseModel):
+    run_id: str
+    blueprint_name: str
+    status: RunStatus
+    outputs: dict[str, Any] = Field(default_factory=dict)
+    step_results: list[StepResult] = Field(default_factory=list)
+    error: str | None = None
+    started_at: datetime
+    finished_at: datetime
+
+    @property
+    def duration_ms(self) -> float:
+        return (self.finished_at - self.started_at).total_seconds() * 1000

aetherius/core/runtime/selector.py

@@ -0,0 +1 @@
+"""Unified target model abstracting css, xpath, text and vision targets so actions are expressed independently of the Act."""

aetherius/models/__init__.py

@@ -0,0 +1 @@
+"""Runtime ML asset management (download, cache, versioning). Training lives under training/."""

aetherius/models/registry.py

@@ -0,0 +1 @@
+"""Model registry: resolve, download, cache and version the vision models referenced by Blueprints."""

aetherius/recorder/__init__.py

@@ -0,0 +1,12 @@
+"""Recorders that generate artifacts: Blueprints from a live session, and mouse gestures for the stealth library.
+
+Public entry points are re-exported here. None of the imports pull Playwright at module load: the
+browser is imported lazily inside the recording functions, so ``import aetherius`` stays light.
+"""
+
+from __future__ import annotations
+
+from .blueprint_recorder import record_blueprint
+from .gesture_recorder import record_gestures
+
+__all__ = ["record_blueprint", "record_gestures"]

aetherius/recorder/_capture_js.py

@@ -0,0 +1,80 @@
+"""In-page capture script for the Blueprint recorder (action capture).
+
+Listens for the real DOM events a demonstration produces (click, change, Enter) and reports a JSON
+descriptor for each to the ``__aetherius_capture`` binding. Element descriptors are built by the
+shared primitives on ``window.__aeSel`` (:mod:`._selector_js`), so the candidate/uniqueness logic is
+defined once and shared with the pick overlay.
+
+Two guards keep action capture and the overlay from stepping on each other: events originating in the
+overlay are ignored, and while a pick mode is active (``window.__aeRecorderPicking``) page actions are
+not recorded — the user is designating data, not driving the site.
+"""
+
+from __future__ import annotations
+
+# Self-invoking, guarded against double injection. Password fields never send their value: only a
+# redacted marker. Requires window.__aeSel (inject _selector_js.SELECTOR_JS first).
+RECORDER_JS = r"""
+(() => {
+  if (window.__aetheriusRecorder) return;
+  window.__aetheriusRecorder = true;
+
+  const TEXTUAL = new Set(['text', 'email', 'search', 'tel', 'url', 'number', 'password', '']);
+  const OVERLAY_ID = '__ae-recorder-overlay';
+
+  const send = (payload) => {
+    try { window.__aetherius_capture(JSON.stringify(payload)); } catch (e) {}
+  };
+
+  // Ignore events from the overlay itself, and any event while a pick mode is active.
+  const ignored = (e) => {
+    if (window.__aeRecorderPicking) return true;
+    const path = e.composedPath ? e.composedPath() : [];
+    return path.some((n) => n && n.id === OVERLAY_ID);
+  };
+
+  document.addEventListener('click', (e) => {
+    if (ignored(e)) return;
+    const el = e.target.closest(window.__aeSel.CLICKABLE);
+    if (!el) return;  // plain clicks (focusing a text field, selecting text) are not steps
+    const payload = { kind: 'click', descriptor: window.__aeSel.descriptorFor(el) };
+    // A link navigating to a real URL is far more robust replayed as a navigate (stable URL) than as
+    // a click (fragile selector). Buttons/submits have no reproducible URL, so they stay clicks.
+    if (el.tagName === 'A') {
+      const raw = el.getAttribute('href') || '';
+      if (raw && !raw.startsWith('#') && !raw.startsWith('javascript:') && /^https?:/i.test(el.href)) {
+        payload.href = el.href;
+      }
+    }
+    send(payload);
+  }, true);
+
+  document.addEventListener('change', (e) => {
+    if (ignored(e)) return;
+    const el = e.target;
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    if (tag === 'select') {
+      send({ kind: 'select', value: el.value, descriptor: window.__aeSel.descriptorFor(el) });
+      return;
+    }
+    if (tag !== 'input' && tag !== 'textarea') return;
+    const type = (el.getAttribute('type') || 'text').toLowerCase();
+    if (type === 'checkbox' || type === 'radio') return;  // captured as a click
+    if (tag === 'input' && !TEXTUAL.has(type)) return;
+    if (type === 'password') {
+      send({ kind: 'fill', redacted: true, descriptor: window.__aeSel.descriptorFor(el) });
+    } else {
+      send({ kind: 'fill', value: el.value, descriptor: window.__aeSel.descriptorFor(el) });
+    }
+  }, true);
+
+  document.addEventListener('keydown', (e) => {
+    if (ignored(e)) return;
+    if (e.key !== 'Enter') return;
+    const el = e.target;
+    const tag = el.tagName ? el.tagName.toLowerCase() : '';
+    if (tag !== 'input') return;  // Enter in a text field commonly submits without a visible button
+    send({ kind: 'press', key: 'Enter', descriptor: window.__aeSel.descriptorFor(el) });
+  }, true);
+})();
+"""

aetherius/recorder/_gesture_js.py

@@ -0,0 +1,40 @@
+"""In-page capture script for the gesture recorder.
+
+Streams raw pointer samples ``[x, y, t]`` (viewport pixels, seconds since page load) and click
+timestamps to the ``__aetherius_gesture`` binding. Moves are buffered and flushed on a timer and on
+every click, rather than sent one per ``pointermove``, so the binding is not hammered thousands of
+times a second. Segmentation into individual gestures is done in pure Python (:mod:`.gesture_recorder`).
+"""
+
+from __future__ import annotations
+
+# Self-invoking, guarded against double injection. performance.now() is milliseconds; we send seconds.
+GESTURE_RECORDER_JS = r"""
+(() => {
+  if (window.__aetheriusGestureRecorder) return;
+  window.__aetheriusGestureRecorder = true;
+
+  let buffer = [];
+  let clickAt = null;
+
+  const flush = () => {
+    if (buffer.length === 0 && clickAt === null) return;
+    const payload = { moves: buffer, click: clickAt };
+    buffer = [];
+    clickAt = null;
+    try { window.__aetherius_gesture(JSON.stringify(payload)); } catch (e) {}
+  };
+
+  document.addEventListener('pointermove', (e) => {
+    buffer.push([Math.round(e.clientX), Math.round(e.clientY), +(performance.now() / 1000).toFixed(4)]);
+  }, true);
+
+  document.addEventListener('pointerdown', (e) => {
+    buffer.push([Math.round(e.clientX), Math.round(e.clientY), +(performance.now() / 1000).toFixed(4)]);
+    clickAt = +(performance.now() / 1000).toFixed(4);
+    flush();
+  }, true);
+
+  setInterval(flush, 250);
+})();
+"""

aetherius/recorder/_names.py

@@ -0,0 +1,20 @@
+"""Tiny naming helpers shared by the recorder transforms: sanitize and de-duplicate identifiers."""
+
+from __future__ import annotations
+
+import re
+
+
+def ident(raw: str | None, *, fallback: str) -> str:
+    """Sanitize a free string into a lowercase identifier, or *fallback* if it is empty."""
+    base = re.sub(r"[^a-z0-9_]+", "_", (raw or "").lower()).strip("_")
+    return base or fallback
+
+
+def unique(base: str, taken: set[str]) -> str:
+    """Return *base*, suffixed (_2, _3, …) until it is not already in *taken*."""
+    name, counter = base, 2
+    while name in taken:
+        name = f"{base}_{counter}"
+        counter += 1
+    return name