aetherius 0.2.0__py3-none-any.whl

aetherius/acts/vector/client.py

@@ -0,0 +1,129 @@
+"""HTTP client wrapper: httpx.Client with tenacity-based retries and pluggable auth."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+from tenacity import (
+    RetryError,
+    retry,
+    retry_if_exception_type,
+    stop_after_attempt,
+    wait_exponential,
+    wait_fixed,
+)
+
+from ...core.blueprint.models import RetriesOptions
+from ...core.errors import NetworkError, RetryExhaustedError, StatusAssertionError, TimeoutError
+from .auth import AuthStrategy, NoAuth
+
+_RETRYABLE = (httpx.TransportError, httpx.TimeoutException)
+
+
+def _build_retry(retries: RetriesOptions) -> Any:
+    """Return a tenacity retry decorator configured from Blueprint options."""
+    if retries.max == 0:
+        return None
+    stop = stop_after_attempt(retries.max + 1)
+    wait: Any
+    if retries.backoff == "exponential":
+        wait = wait_exponential(multiplier=1, min=1, max=30)
+    elif retries.backoff == "linear":
+        wait = wait_fixed(1)
+    else:
+        wait = wait_fixed(0)
+    return retry(
+        retry=retry_if_exception_type(_RETRYABLE),
+        stop=stop,
+        wait=wait,
+        reraise=True,
+    )
+
+
+class VectorClient:
+    def __init__(
+        self,
+        *,
+        timeout_ms: int = 30_000,
+        retries: RetriesOptions | None = None,
+        auth: AuthStrategy | None = None,
+    ) -> None:
+        self._timeout = timeout_ms / 1000
+        self._retries = retries or RetriesOptions()
+        self._auth: AuthStrategy = auth or NoAuth()
+        self._client = httpx.Client(timeout=self._timeout, follow_redirects=True)
+        self._auth.prepare(self._client)
+        self._retry_decorator = _build_retry(self._retries)
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        headers: dict[str, str] | None = None,
+        json: Any | None = None,
+        form: dict[str, str] | None = None,
+        params: dict[str, str] | None = None,
+        expected_status: int | None = None,
+    ) -> httpx.Response:
+        """Send an HTTP request with optional auth, retries, and status assertion.
+
+        Raises:
+            ActionError: if both json and form are provided.
+            TimeoutError: on httpx timeout.
+            RetryExhaustedError: after all retry attempts fail.
+            NetworkError: on other transport failures.
+            StatusAssertionError: if expected_status is set and response status doesn't match.
+        """
+        from ...core.errors import ActionError
+
+        if json is not None and form is not None:
+            raise ActionError("Cannot set both 'json' and 'form' on the same http.request step.")
+
+        req = httpx.Request(
+            method=method.upper(),
+            url=url,
+            headers=headers or {},
+            params=params,
+            json=json,
+            data=form,
+        )
+        req = self._auth.apply(req)
+
+        def _send() -> httpx.Response:
+            return self._client.send(req)
+
+        try:
+            if self._retry_decorator is not None:
+                response: httpx.Response = self._retry_decorator(_send)()
+            else:
+                response = _send()
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(f"Request timed out: {method} {url}") from exc
+        except RetryError as exc:
+            raise RetryExhaustedError(
+                f"All {self._retries.max} retry attempts failed: {method} {url}",
+                last_error=exc,
+            ) from exc
+        except httpx.TransportError as exc:
+            raise NetworkError(f"Transport error: {exc}") from exc
+
+        if expected_status is not None and response.status_code != expected_status:
+            raise StatusAssertionError(
+                expected=expected_status,
+                actual=response.status_code,
+                url=url,
+                body_preview=response.text,
+            )
+
+        return response
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> "VectorClient":
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()

aetherius/acts/vector/driver.py

@@ -0,0 +1,128 @@
+"""Vector driver: executes http.request and utility actions for Act I (no browser)."""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .._shared import SharedActionsMixin
+from ...core.blueprint.models import StepModel
+from ...core.errors import ActionError
+from ...core.events.bus import EventBus
+from ...core.extraction.html_extractor import HtmlExtractSpec, extract_html
+from ...core.extraction.json_extractor import ExtractSpec, extract_json
+from ...core.runtime.context import RunContext
+from .client import VectorClient
+
+
+class VectorDriver(SharedActionsMixin):
+    act = "vector"
+
+    def setup(self, ctx: RunContext) -> None:
+        timeout_ms = ctx.blueprint.options.timeout_ms or 30_000
+        self._client = VectorClient(
+            timeout_ms=timeout_ms,
+            retries=ctx.blueprint.options.retries,
+        )
+
+    def teardown(self, ctx: RunContext) -> None:
+        self._client.close()
+
+    def run_step(
+        self,
+        step: StepModel,
+        ctx: RunContext,
+        bus: EventBus,
+        renderer: Callable[[Any], Any],
+    ) -> dict[str, Any]:
+        match step.action:
+            case "http.request":
+                return self._http_request(step, ctx, bus, renderer)
+            case "set":
+                return self._set(step, renderer)
+            case "assert":
+                return self._assert(step, renderer)
+            case "emit":
+                return self._emit(step, ctx, bus, renderer)
+            case "wait":
+                return self._wait(step, renderer)
+            case _:
+                raise ActionError(f"VectorDriver: unsupported action {step.action!r}")
+
+    # ── Action handlers ───────────────────────────────────────────────────────
+
+    def _http_request(
+        self,
+        step: StepModel,
+        ctx: RunContext,
+        bus: EventBus,
+        renderer: Callable[[Any], Any],
+    ) -> dict[str, Any]:
+        p = step.extra_fields
+        method: str = renderer(p.get("method", "GET"))
+        url: str = renderer(p.get("url", ""))
+        headers: dict[str, str] = renderer(p.get("headers") or {})
+        form: dict[str, str] | None = renderer(p["form"]) if "form" in p else None
+        json_body: Any = renderer(p["json"]) if "json" in p else None
+        params: dict[str, str] | None = renderer(p.get("params"))
+        expect: dict[str, Any] = renderer(p.get("expect") or {})
+        expected_status: int | None = expect.get("status")
+
+        response = self._client.request(
+            method,
+            url,
+            headers=headers,
+            json=json_body,
+            form=form,
+            params=params,
+            expected_status=expected_status,
+        )
+
+        outputs: dict[str, Any] = {
+            "status_code": response.status_code,
+            "headers": dict(response.headers),
+        }
+
+        extract_specs: dict[str, Any] = p.get("extract") or {}
+        if extract_specs:
+            content_type = response.headers.get("content-type", "")
+            extracted = self._dispatch_extract(
+                response.content, extract_specs, content_type, renderer
+            )
+            outputs.update(extracted)
+
+        return outputs
+
+    def _dispatch_extract(
+        self,
+        body: bytes,
+        raw_specs: dict[str, Any],
+        content_type: str,
+        renderer: Callable[[Any], Any],
+    ) -> dict[str, Any]:
+        json_specs: dict[str, ExtractSpec] = {}
+        html_specs: dict[str, HtmlExtractSpec] = {}
+
+        for name, raw in raw_specs.items():
+            from_val: str = raw.get("from", "json")
+            if from_val == "json":
+                json_specs[name] = ExtractSpec(
+                    from_=from_val,
+                    path=raw.get("path", "$"),
+                    where=raw.get("where"),
+                    fields={k: v for k, v in (raw.get("fields") or {}).items()},
+                )
+            else:
+                html_specs[name] = HtmlExtractSpec(
+                    from_=from_val,
+                    selector=raw.get("selector", ""),
+                    selector_type=raw.get("selector_type", "css"),
+                    attr=raw.get("attr"),
+                    multiple=raw.get("multiple", True),
+                )
+
+        result: dict[str, Any] = {}
+        if json_specs:
+            result.update(extract_json(body, json_specs))
+        if html_specs:
+            result.update(extract_html(body, html_specs))
+        return result

aetherius/builder/__init__.py

@@ -0,0 +1,40 @@
+"""Headless Blueprint construction, reusable by the Console, the daemon and the SDKs.
+
+The Console is only its presentation layer: everything here is Textual-free. A ``BlueprintDraft`` is
+the editing state; ``validate_draft`` reports issues live; ``build_blueprint``/``save_blueprint``
+finalise it; ``act_infos``/``actions_for_act`` project the action registry into UI-ready records;
+``list_templates``/``template_draft`` seed a draft from a starter.
+"""
+
+from __future__ import annotations
+
+from .catalog import ActInfo, ActionInfo, act_infos, actions_for_act, get_act_info
+from .factory import (
+    BlueprintDraft,
+    StepDraft,
+    assemble_blueprint,
+    build_blueprint,
+    save_blueprint,
+    slugify_name,
+)
+from .templates import TemplateInfo, list_templates, template_draft
+from .validation import ValidationIssue, validate_draft
+
+__all__ = [
+    "ActInfo",
+    "ActionInfo",
+    "act_infos",
+    "actions_for_act",
+    "get_act_info",
+    "BlueprintDraft",
+    "StepDraft",
+    "assemble_blueprint",
+    "build_blueprint",
+    "save_blueprint",
+    "slugify_name",
+    "TemplateInfo",
+    "list_templates",
+    "template_draft",
+    "ValidationIssue",
+    "validate_draft",
+]

aetherius/builder/catalog.py

@@ -0,0 +1,93 @@
+"""UI-friendly metadata for Acts and actions, projected from the core action registry.
+
+This is the projection the README calls the builder catalogue: it joins the capability table
+(``core/actions/base.py``), the field specs (``core/actions/registry.action_specs``) and the
+runnable-Act set (``IMPLEMENTED_ACTS``) into flat, Textual-free records the Console and the daemon
+can render. No action metadata is defined here — only combined and ordered — so the registry stays
+the single source of truth.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..core.actions.base import ACT_CAPABILITIES, PENDING_ACTIONS, Capability
+from ..core.actions.registry import action_specs
+from ..core.actions.spec import ActionSpec
+from ..core.errors import BuilderError
+from ..core.runtime.engine import IMPLEMENTED_ACTS
+
+# Canonical display order, escalating Act by Act.
+_ACT_ORDER: tuple[str, ...] = ("vector", "continuum", "oracle", "phantom")
+
+_ACT_TITLES: dict[str, str] = {
+    "vector": "Vector — HTTP / API",
+    "continuum": "Continuum — scripted browser",
+    "oracle": "Oracle — vision-guided browser",
+    "phantom": "Phantom — autonomous agent",
+}
+
+# One-line explanation shown next to each Act in the picker and the catalogue.
+_ACT_SUMMARIES: dict[str, str] = {
+    "vector": "HTTP/API requests. Fastest, no browser. The 'axios' case.",
+    "continuum": "Scripted browser (Playwright): login, JS, session, DOM. Stable selectors.",
+    "oracle": "Vision-guided browser with discretion. Locates fragile/obfuscated UI on screen.",
+    "phantom": "Autonomous agent: perceive, reason, act in a loop. Unscripted goals.",
+}
+
+
+@dataclass(frozen=True)
+class ActInfo:
+    """An Act as the builder presents it: title, explanation, and whether it runs today."""
+
+    act: str
+    title: str
+    summary: str
+    implemented: bool
+
+
+@dataclass(frozen=True)
+class ActionInfo:
+    """An action available under an Act, with its spec and whether that Act runs it yet."""
+
+    spec: ActionSpec
+    runnable: bool
+
+
+def act_infos() -> list[ActInfo]:
+    """Every Act in canonical order, with its runnable status from IMPLEMENTED_ACTS."""
+    return [
+        ActInfo(
+            act=act,
+            title=_ACT_TITLES[act],
+            summary=_ACT_SUMMARIES[act],
+            implemented=act in IMPLEMENTED_ACTS,
+        )
+        for act in _ACT_ORDER
+    ]
+
+
+def get_act_info(act: str) -> ActInfo:
+    """Return the :class:`ActInfo` for *act* or raise :class:`BuilderError`."""
+    if act not in _ACT_TITLES:
+        raise BuilderError(f"Unknown act {act!r} (known: {list(_ACT_ORDER)}).")
+    return next(info for info in act_infos() if info.act == act)
+
+
+def actions_for_act(act: str) -> list[ActionInfo]:
+    """The actions an *act* supports, sorted by name, each flagged runnable or pending.
+
+    An action is runnable when its Act is implemented and the action is not in that Act's
+    PENDING_ACTIONS set (declared in the capability table but not dispatched by a driver yet).
+    """
+    caps = ACT_CAPABILITIES.get(act)
+    if caps is None:
+        raise BuilderError(f"Unknown act {act!r} (known: {list(_ACT_ORDER)}).")
+    specs = action_specs()
+    pending: frozenset[Capability] = PENDING_ACTIONS.get(act, frozenset())
+    implemented = act in IMPLEMENTED_ACTS
+    infos = [
+        ActionInfo(spec=specs[cap.value], runnable=implemented and cap not in pending)
+        for cap in caps
+    ]
+    return sorted(infos, key=lambda info: info.spec.name)

aetherius/builder/factory.py

@@ -0,0 +1,243 @@
+"""Assemble a valid Blueprint from structured choices, validating against the schema as it is built.
+
+The headless heart of the Blueprint Studio, reusable by the Console, the daemon and the SDKs. A
+:class:`BlueprintDraft` is the mutable editing state: raw data (dicts/lists), legitimately partial
+while a user is still filling it in. :func:`validate_draft` reports issues without raising (the live
+preview calls it on every change); :func:`build_blueprint` / :func:`save_blueprint` finalise it and
+raise typed errors. ``assemble_blueprint`` and ``slugify_name`` live here — the recorder, a producer
+of steps, re-exports them.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Mapping
+
+from ..core.actions.registry import get_spec
+from ..core.actions.spec import ParamKind
+from ..core.blueprint.loader import load_blueprint, validate_blueprint_data
+from ..core.blueprint.models import Blueprint
+from ..core.blueprint.validator import validate_for_act
+from ..core.errors import BuilderError
+from .validation import ValidationIssue, validate_draft
+
+__all__ = [
+    "slugify_name",
+    "assemble_blueprint",
+    "StepDraft",
+    "BlueprintDraft",
+    "ValidationIssue",
+    "validate_draft",
+    "build_blueprint",
+    "save_blueprint",
+]
+
+
+def slugify_name(name: str) -> str:
+    """Filesystem-safe stem derived from a Blueprint name (keeps dots, e.g. quotes.login)."""
+    slug = re.sub(r"[^A-Za-z0-9._-]+", "-", name).strip("-.")
+    return slug or "blueprint"
+
+
+def assemble_blueprint(
+    name: str,
+    steps: list[dict[str, Any]],
+    secrets: list[str],
+    *,
+    act: str = "continuum",
+    inputs: dict[str, Any] | None = None,
+    outputs: dict[str, Any] | None = None,
+    description: str | None = None,
+    vars: dict[str, Any] | None = None,
+    options: dict[str, Any] | None = None,
+    vision: dict[str, Any] | None = None,
+    goal: str | None = None,
+    constraints: list[str] | None = None,
+) -> dict[str, Any]:
+    """Assemble a minimal, ordered Blueprint dict for *act* (schema key order, empties omitted)."""
+    blueprint: dict[str, Any] = {"aetherius": "1.0", "name": name}
+    if description:
+        blueprint["description"] = description
+    blueprint["act"] = act
+    if inputs:
+        blueprint["inputs"] = inputs
+    if secrets:
+        blueprint["secrets"] = secrets
+    if vars:
+        blueprint["vars"] = vars
+    if options:
+        blueprint["options"] = options
+    if vision:
+        blueprint["vision"] = vision
+    if goal:
+        blueprint["goal"] = goal
+    if constraints:
+        blueprint["constraints"] = constraints
+    # A goal-only Blueprint (Phantom) legitimately has no steps; otherwise steps are always present.
+    if steps or not goal:
+        blueprint["steps"] = steps
+    if outputs:
+        blueprint["outputs"] = outputs
+    return blueprint
+
+
+# Empty value used to pre-seed a required parameter, per kind, so a freshly added step shows what it
+# still needs (and validate_draft flags it until filled). Empty object/array stay valid JSON.
+def _empty_value(kind: ParamKind) -> Any:
+    if kind == "boolean":
+        return False
+    if kind == "object":
+        return {}
+    if kind == "array":
+        return []
+    return ""
+
+
+@dataclass
+class StepDraft:
+    """One editable step: an action, an optional id, and its raw parameters."""
+
+    action: str
+    id: str | None = None
+    params: dict[str, Any] = field(default_factory=dict)
+
+    def to_data(self) -> dict[str, Any]:
+        """Serialise to the step dict shape (id first when set, then action, then params)."""
+        data: dict[str, Any] = {}
+        if self.id:
+            data["id"] = self.id
+        data["action"] = self.action
+        data.update(self.params)
+        return data
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any]) -> "StepDraft":
+        params = {k: v for k, v in data.items() if k not in ("id", "action")}
+        return cls(action=str(data.get("action", "")), id=data.get("id"), params=params)
+
+
+@dataclass
+class BlueprintDraft:
+    """Mutable editing state of a Blueprint. Lossless: carries every envelope field so an existing
+    file round-trips unchanged through ``from_data``/``to_data`` (e.g. refining recorder output)."""
+
+    name: str = ""
+    act: str = "vector"
+    description: str | None = None
+    inputs: dict[str, dict[str, Any]] = field(default_factory=dict)
+    secrets: list[str] = field(default_factory=list)
+    vars: dict[str, Any] = field(default_factory=dict)
+    options: dict[str, Any] = field(default_factory=dict)
+    steps: list[StepDraft] = field(default_factory=list)
+    outputs: dict[str, Any] = field(default_factory=dict)
+    vision: dict[str, Any] | None = None
+    goal: str | None = None
+    constraints: list[str] = field(default_factory=list)
+
+    def add_step(self, action: str, *, index: int | None = None) -> StepDraft:
+        """Append (or insert at *index*) a step, pre-seeding its required parameters."""
+        params: dict[str, Any] = {}
+        try:
+            spec = get_spec(action)
+        except Exception:
+            spec = None
+        if spec is not None:
+            for param in spec.required_params():
+                params[param.name] = _empty_value(param.kind)
+        step = StepDraft(action=action, params=params)
+        if index is None:
+            self.steps.append(step)
+        else:
+            self.steps.insert(max(0, min(index, len(self.steps))), step)
+        return step
+
+    def remove_step(self, index: int) -> None:
+        if 0 <= index < len(self.steps):
+            del self.steps[index]
+
+    def move_step(self, index: int, delta: int) -> None:
+        """Move the step at *index* by *delta* positions, clamped to the list bounds."""
+        if not (0 <= index < len(self.steps)):
+            return
+        target = max(0, min(index + delta, len(self.steps) - 1))
+        if target != index:
+            self.steps.insert(target, self.steps.pop(index))
+
+    def to_data(self) -> dict[str, Any]:
+        """Assemble the ordered Blueprint dict this draft represents (empties omitted)."""
+        return assemble_blueprint(
+            self.name,
+            [step.to_data() for step in self.steps],
+            list(self.secrets),
+            act=self.act,
+            inputs=dict(self.inputs) or None,
+            outputs=dict(self.outputs) or None,
+            description=self.description,
+            vars=dict(self.vars) or None,
+            options=dict(self.options) or None,
+            vision=self.vision,
+            goal=self.goal,
+            constraints=list(self.constraints) or None,
+        )
+
+    @classmethod
+    def from_data(cls, data: Mapping[str, Any]) -> "BlueprintDraft":
+        """Build a draft from a Blueprint dict (as loaded from a file), preserving every field."""
+        return cls(
+            name=str(data.get("name", "")),
+            act=str(data.get("act", "vector")),
+            description=data.get("description"),
+            inputs={k: dict(v) for k, v in (data.get("inputs") or {}).items()},
+            secrets=list(data.get("secrets") or []),
+            vars=dict(data.get("vars") or {}),
+            options=dict(data.get("options") or {}),
+            steps=[StepDraft.from_data(s) for s in (data.get("steps") or [])],
+            outputs=dict(data.get("outputs") or {}),
+            vision=data.get("vision"),
+            goal=data.get("goal"),
+            constraints=list(data.get("constraints") or []),
+        )
+
+
+def build_blueprint(draft: BlueprintDraft) -> Blueprint:
+    """Finalise *draft* into a validated Blueprint model, raising typed errors on any problem."""
+    blueprint = validate_blueprint_data(draft.to_data(), source="<studio>")
+    validate_for_act(blueprint)
+    return blueprint
+
+
+def save_blueprint(
+    draft: BlueprintDraft,
+    *,
+    path: Path | str | None = None,
+    out_dir: Path | str | None = None,
+) -> Path:
+    """Validate and write *draft* to disk, returning the file path.
+
+    With *path* (edit mode) the file is overwritten in place. Otherwise the file is created under
+    *out_dir* (or ``./blueprints``) as ``{slug}.blueprint.json``; a name collision with a different
+    existing file raises :class:`BuilderError` rather than clobbering it. Validation runs before any
+    write, and the written file is re-read through the canonical loader as a final guarantee.
+    """
+    build_blueprint(draft)  # raise before touching disk
+
+    if path is not None:
+        target = Path(path)
+        target.parent.mkdir(parents=True, exist_ok=True)
+    else:
+        target_dir = Path(out_dir) if out_dir is not None else Path.cwd() / "blueprints"
+        target_dir.mkdir(parents=True, exist_ok=True)
+        target = target_dir / f"{slugify_name(draft.name)}.blueprint.json"
+        if target.exists():
+            raise BuilderError(
+                f"A Blueprint already exists at {target}. Rename this one, or open that file to edit."
+            )
+
+    target.write_text(
+        json.dumps(draft.to_data(), indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+    validate_for_act(load_blueprint(target))
+    return target