aetherius 0.2.0__py3-none-any.whl

aetherius/core/blueprint/models.py

@@ -0,0 +1,81 @@
+"""Pydantic v2 models for a Blueprint. Single typed representation of an instruction file.
+
+Source of truth for the shape: contracts/blueprint.schema.json.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, model_validator
+
+
+class InputSpec(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    type: Literal["string", "number", "integer", "boolean", "date", "path", "object", "array"]
+    required: bool = False
+    format: str | None = None
+    default: Any = None
+    description: str | None = None
+
+
+class RetriesOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    max: int = 0
+    backoff: Literal["none", "linear", "exponential"] = "none"
+
+
+class SessionOptions(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    profile: str | None = None
+    persist: bool = False
+
+
+class Options(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    debug: bool = False
+    timeout_ms: int | None = None
+    retries: RetriesOptions = Field(default_factory=RetriesOptions)
+    stealth: Any = None
+    session: SessionOptions | None = None
+
+
+class StepModel(BaseModel):
+    # extra="allow": action-specific keys are passed through and validated per-action by the engine.
+    model_config = ConfigDict(extra="allow")
+
+    id: str | None = None
+    action: str
+
+    @property
+    def extra_fields(self) -> dict[str, Any]:
+        """Action-specific parameters (all keys beyond id and action)."""
+        return self.model_extra or {}
+
+
+class Blueprint(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    aetherius: str
+    name: str
+    description: str | None = None
+    act: Literal["vector", "continuum", "oracle", "phantom"]
+    inputs: dict[str, InputSpec] = Field(default_factory=dict)
+    secrets: list[str] = Field(default_factory=list)
+    vars: dict[str, Any] = Field(default_factory=dict)
+    options: Options = Field(default_factory=Options)
+    vision: dict[str, Any] | None = None
+    goal: str | None = None
+    constraints: list[str] = Field(default_factory=list)
+    steps: list[StepModel] = Field(default_factory=list)
+    outputs: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def _require_steps_or_goal(self) -> "Blueprint":
+        if not self.steps and not self.goal:
+            raise ValueError("A Blueprint must declare either 'steps' or 'goal'.")
+        return self

aetherius/core/blueprint/template.py

@@ -0,0 +1,101 @@
+"""Runtime interpolation of the {{ }} syntax over inputs, secrets, vars, env, and step outputs.
+
+Uses Jinja2 SandboxedEnvironment with StrictUndefined so missing variables surface
+immediately as TemplateError rather than silently rendering to empty strings.
+
+When a value is a "bare" single-expression string like ``{{ steps.req.events }}``, the raw
+Python object is returned instead of its string representation — this preserves lists and dicts
+through the outputs rendering pipeline.
+"""
+
+from __future__ import annotations
+
+import datetime
+import re
+from typing import Any
+
+from jinja2 import StrictUndefined, TemplateError as _Jinja2Error, Undefined as _Undefined
+from jinja2.sandbox import SandboxedEnvironment
+
+from ..errors import TemplateError
+
+# Matches strings that are exactly one {{ … }} expression (possibly with surrounding whitespace).
+_BARE_EXPR = re.compile(r"^\s*\{\{(.*?)\}\}\s*$", re.DOTALL)
+
+# ── Custom filters ─────────────────────────────────────────────────────────────
+
+
+def _filter_add_days(value: str, n: int) -> str:
+    """Add *n* days to an ISO 8601 date string and return an ISO 8601 date string."""
+    try:
+        date = datetime.date.fromisoformat(value)
+    except ValueError as exc:
+        raise TemplateError(f"add_days: cannot parse date {value!r}") from exc
+    return (date + datetime.timedelta(days=n)).isoformat()
+
+
+def _filter_sub_days(value: str, n: int) -> str:
+    return _filter_add_days(value, -n)
+
+
+def _filter_format_date(value: str, fmt: str) -> str:
+    """Reformat an ISO 8601 date string using a strftime format string."""
+    try:
+        date = datetime.date.fromisoformat(value)
+    except ValueError as exc:
+        raise TemplateError(f"format_date: cannot parse date {value!r}") from exc
+    return date.strftime(fmt)
+
+
+# ── Jinja2 environment ────────────────────────────────────────────────────────
+
+
+def _make_env() -> SandboxedEnvironment:
+    env = SandboxedEnvironment(undefined=StrictUndefined)
+    env.filters["add_days"] = _filter_add_days
+    env.filters["sub_days"] = _filter_sub_days
+    env.filters["format_date"] = _filter_format_date
+    return env
+
+
+_env = _make_env()
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+
+def render_value(value: Any, ctx: dict[str, Any]) -> Any:
+    """Recursively render {{ }} expressions in *value* against *ctx*.
+
+    Strings are rendered through Jinja2. Dicts and lists are rendered recursively.
+    Non-string scalars (int, bool, None, …) are passed through unchanged.
+
+    When a string is a single bare ``{{ expr }}`` expression, the raw Python object is
+    returned (not its string representation), so lists and dicts survive the pipeline.
+
+    Raises:
+        TemplateError: on undefined variable, bad filter, or syntax error.
+    """
+    if isinstance(value, str):
+        m = _BARE_EXPR.match(value)
+        if m:
+            # Single-expression: evaluate and return the raw Python value.
+            try:
+                # undefined_to_none=False so we receive Undefined rather than None.
+                compiled = _env.compile_expression(m.group(1).strip(), undefined_to_none=False)
+                result = compiled(**ctx)
+                # compile_expression ignores StrictUndefined; raise explicitly.
+                if isinstance(result, _Undefined):
+                    raise TemplateError(f"Undefined variable in expression: {m.group(1).strip()!r}")
+                return result
+            except _Jinja2Error as exc:
+                raise TemplateError(f"Template expression failed: {exc}") from exc
+        # Multi-part string: render as text.
+        try:
+            return _env.from_string(value).render(ctx)
+        except _Jinja2Error as exc:
+            raise TemplateError(f"Template rendering failed: {exc}") from exc
+    if isinstance(value, dict):
+        return {k: render_value(v, ctx) for k, v in value.items()}
+    if isinstance(value, list):
+        return [render_value(item, ctx) for item in value]
+    return value

aetherius/core/blueprint/validator.py

@@ -0,0 +1,45 @@
+"""Semantic validation: verifies that every step action is supported by the Blueprint's Act."""
+
+from __future__ import annotations
+
+from ..actions.base import ACT_CAPABILITIES
+from ..errors import BlueprintValidationError
+from .models import Blueprint
+
+# Map back from Capability value to the first Act that introduces it.
+_CAPABILITY_ORIGIN: dict[str, str] = {
+    "navigate": "continuum",
+    "back": "continuum",
+    "forward": "continuum",
+    "reload": "continuum",
+    "click": "continuum",
+    "fill": "continuum",
+    "type": "continuum",
+    "press": "continuum",
+    "select": "continuum",
+    "hover": "continuum",
+    "scroll": "continuum",
+    "upload": "continuum",
+    "drag": "continuum",
+    "screenshot": "continuum",
+    "evaluate": "continuum",
+    "wait_for": "continuum",
+}
+
+
+def validate_for_act(blueprint: Blueprint) -> None:
+    """Raise BlueprintValidationError if any step uses an action unsupported by blueprint.act.
+
+    This is a semantic check complementing the JSON Schema structural validation.
+    """
+    supported = ACT_CAPABILITIES.get(blueprint.act, frozenset())
+    supported_values = {cap.value for cap in supported}
+
+    for step in blueprint.steps:
+        if step.action not in supported_values:
+            origin = _CAPABILITY_ORIGIN.get(step.action)
+            hint = f" (requires act={origin!r} or higher)" if origin else ""
+            raise BlueprintValidationError(
+                f"Step {step.id!r}: action {step.action!r} is not supported "
+                f"by act={blueprint.act!r}{hint}."
+            )

aetherius/core/driver.py

@@ -0,0 +1,36 @@
+"""ActDriver protocol: contract that every Act (I..IV) driver must satisfy."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, Protocol
+
+if TYPE_CHECKING:
+    from .events.bus import EventBus
+    from .blueprint.models import StepModel
+    from .runtime.context import RunContext
+
+
+class ActDriver(Protocol):
+    act: ClassVar[str]
+
+    def setup(self, ctx: "RunContext") -> None:
+        """Called once before the first step. Open connections, create sessions, etc."""
+        ...
+
+    def teardown(self, ctx: "RunContext") -> None:
+        """Called once after the last step (even on failure). Close resources."""
+        ...
+
+    def run_step(
+        self,
+        step: "StepModel",
+        ctx: "RunContext",
+        bus: "EventBus",
+        renderer: Callable[[Any], Any],
+    ) -> dict[str, Any]:
+        """Execute a single step and return its output dict.
+
+        *renderer* is a callable that applies template rendering to any value.
+        The driver calls it on step fields before using them.
+        """
+        ...

aetherius/core/errors.py

@@ -0,0 +1,134 @@
+"""Typed exception hierarchy for Aetherius. Errors are never swallowed silently."""
+
+from __future__ import annotations
+
+
+class AetheriusError(Exception):
+    """Base for all Aetherius exceptions."""
+
+
+# ── Blueprint ──────────────────────────────────────────────────────────────────
+
+
+class BlueprintError(AetheriusError):
+    """Base for Blueprint-related errors."""
+
+
+class BlueprintLoadError(BlueprintError):
+    """File not found, unreadable, or not valid JSON/YAML."""
+
+
+class BlueprintSchemaError(BlueprintError):
+    """Blueprint violates the JSON Schema or Pydantic model constraints."""
+
+
+class BlueprintValidationError(BlueprintError):
+    """Semantic error: action not supported by the declared Act, missing required input, etc."""
+
+
+# ── Template ───────────────────────────────────────────────────────────────────
+
+
+class TemplateError(AetheriusError):
+    """Jinja2 rendering failure: undefined variable, bad filter, syntax error."""
+
+
+# ── Network ───────────────────────────────────────────────────────────────────
+
+
+class NetworkError(AetheriusError):
+    """Base for transport-level failures."""
+
+
+class TimeoutError(NetworkError):
+    """Request exceeded the configured timeout."""
+
+
+class RetryExhaustedError(NetworkError):
+    """All retry attempts failed. Wraps the last transport exception."""
+
+    def __init__(self, message: str, last_error: Exception) -> None:
+        super().__init__(message)
+        self.last_error = last_error
+
+
+# ── HTTP assertions ────────────────────────────────────────────────────────────
+
+
+class StatusAssertionError(AetheriusError):
+    """HTTP response status does not match `expect.status`."""
+
+    def __init__(
+        self,
+        expected: int,
+        actual: int,
+        url: str,
+        body_preview: str = "",
+    ) -> None:
+        super().__init__(
+            f"Expected HTTP {expected}, got {actual} — {url}"
+            + (f"\n{body_preview[:200]}" if body_preview else "")
+        )
+        self.expected = expected
+        self.actual = actual
+        self.url = url
+        self.body_preview = body_preview
+
+
+# ── Extraction ────────────────────────────────────────────────────────────────
+
+
+class ExtractionError(AetheriusError):
+    """JSONPath / CSS / XPath / predicate evaluation failure."""
+
+
+# ── Actions ───────────────────────────────────────────────────────────────────
+
+
+class ActionError(AetheriusError):
+    """Unknown action name or missing required action parameter."""
+
+
+class StepTimeoutError(AetheriusError):
+    """A step waited past its budget (e.g. wait_for). Carries the Blueprint's failure code."""
+
+    def __init__(self, message: str, *, code: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+# ── Dependencies ──────────────────────────────────────────────────────────────
+
+
+class DependencyError(AetheriusError):
+    """A required optional dependency (an Act extra) is not installed."""
+
+    def __init__(self, message: str, *, extra: str | None = None) -> None:
+        super().__init__(message)
+        self.extra = extra
+
+
+# ── Recorder ──────────────────────────────────────────────────────────────────
+
+
+class RecorderError(AetheriusError):
+    """No recorder backend for the requested Act (unknown, or a pending milestone)."""
+
+
+# ── Builder ───────────────────────────────────────────────────────────────────
+
+
+class BuilderError(AetheriusError):
+    """Headless builder failure: unknown Act or template, or a name collision on save."""
+
+
+# ── Runtime ───────────────────────────────────────────────────────────────────
+
+
+class RunError(AetheriusError):
+    """Engine-level failure wrapping an underlying AetheriusError."""
+
+    def __init__(self, message: str, cause: Exception) -> None:
+        super().__init__(message)
+        self.cause = cause
+        self.__cause__ = cause

aetherius/core/events/__init__.py

@@ -0,0 +1 @@
+"""Unified event system powering progress reporting, debug output and streaming."""

aetherius/core/events/bus.py

@@ -0,0 +1,28 @@
+"""Synchronous event fan-out: emits RunEvents to all registered sinks."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .sinks import Sink
+
+from .models import RunEvent
+
+_log = logging.getLogger(__name__)
+
+
+class EventBus:
+    def __init__(self) -> None:
+        self._sinks: list[Sink] = []
+
+    def register(self, sink: "Sink") -> None:
+        self._sinks.append(sink)
+
+    def emit(self, event: RunEvent) -> None:
+        for sink in self._sinks:
+            try:
+                sink.on_event(event)
+            except Exception:
+                _log.exception("Event sink %r raised an error; continuing.", sink)

aetherius/core/events/models.py

@@ -0,0 +1,29 @@
+"""Event types emitted during a Blueprint run. Mirrors contracts/events.schema.json."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Literal
+
+from pydantic import BaseModel, Field
+
+
+class EventType(str, Enum):
+    PROGRESS = "progress"
+    STEP_STARTED = "step_started"
+    STEP_FINISHED = "step_finished"
+    DEBUG = "debug"
+    ARTIFACT = "artifact"
+    ERROR = "error"
+    DONE = "done"
+
+
+class RunEvent(BaseModel):
+    run_id: str
+    ts: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    type: EventType
+    step_id: str | None = None
+    level: Literal["debug", "info", "warning", "error"] | None = None
+    message: str | None = None
+    data: dict[str, Any] = Field(default_factory=dict)

aetherius/core/events/sinks.py

@@ -0,0 +1,55 @@
+"""Event sinks: LogSink for terminal output, NullSink for tests.
+
+WebSocketSink is deferred to the daemon milestone.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Protocol, runtime_checkable
+
+from .models import EventType, RunEvent
+
+_log = logging.getLogger("aetherius.events")
+
+
+@runtime_checkable
+class Sink(Protocol):
+    def on_event(self, event: RunEvent) -> None: ...
+
+
+class NullSink:
+    """Discards all events. Used in tests."""
+
+    def on_event(self, event: RunEvent) -> None:
+        pass
+
+
+def format_event(event: RunEvent) -> str:
+    """Render a RunEvent as a single-line human-readable string.
+
+    Shared by LogSink and the Console's EventLog widget so the two presentations never drift.
+    """
+    msg = f"[{event.type.value}]"
+    if event.step_id:
+        msg += f" step={event.step_id}"
+    if event.message:
+        msg += f" {event.message}"
+    return msg
+
+
+class LogSink:
+    """Writes events to Python logging.
+
+    In debug mode every event is logged at DEBUG; otherwise only INFO and above.
+    """
+
+    def __init__(self, *, debug: bool = False) -> None:
+        self._debug = debug
+
+    def on_event(self, event: RunEvent) -> None:
+        level_str = event.level or ("debug" if event.type == EventType.DEBUG else "info")
+        level = getattr(logging, level_str.upper(), logging.INFO)
+        if not self._debug and level < logging.INFO:
+            return
+        _log.log(level, format_event(event))

aetherius/core/extraction/__init__.py

@@ -0,0 +1 @@
+"""Declarative extraction of structured data from JSON and HTML payloads."""

aetherius/core/extraction/html_extractor.py

@@ -0,0 +1,52 @@
+"""HTML extraction via CSS and XPath selectors using parsel."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from parsel import Selector
+
+from ..errors import ExtractionError
+
+
+@dataclass
+class HtmlExtractSpec:
+    from_: str  # "html"
+    selector: str  # CSS or XPath expression
+    selector_type: str = "css"  # "css" | "xpath"
+    attr: str | None = None  # attribute to extract; None → text content
+    multiple: bool = True  # True → list, False → first match only
+
+
+def extract_html(body: bytes, spec: dict[str, "HtmlExtractSpec"]) -> dict[str, Any]:
+    """Run all extraction specs in *spec* against an HTML *body*.
+
+    Returns a dict mapping each output name to a string (single) or list of strings (multiple).
+    """
+    try:
+        sel = Selector(text=body.decode("utf-8", errors="replace"))
+    except Exception as exc:
+        raise ExtractionError(f"Cannot parse HTML response body: {exc}") from exc
+
+    result: dict[str, Any] = {}
+
+    for output_name, s in spec.items():
+        try:
+            if s.selector_type == "xpath":
+                nodes = sel.xpath(s.selector)
+            else:
+                nodes = sel.css(s.selector)
+        except Exception as exc:
+            raise ExtractionError(
+                f"Invalid {s.selector_type} selector {s.selector!r}: {exc}"
+            ) from exc
+
+        if s.attr:
+            values = [node.attrib.get(s.attr, "") for node in nodes]
+        else:
+            values = nodes.getall()
+
+        result[output_name] = values if s.multiple else (values[0] if values else None)
+
+    return result