aetherius 0.2.0__py3-none-any.whl

aetherius/stealth/policy.py

@@ -0,0 +1,133 @@
+"""StealthPolicy: the decoded, typed intent behind ``options.stealth``.
+
+The Blueprint carries ``options.stealth`` as loosely-typed data (off, a preset name, or an inline
+object) so the JSON Schema stays the single source of shape. This module turns that data into one
+frozen policy object the browser Acts can query without re-parsing: which humanizer features are on
+and which fingerprint profile to wear. ``build_policy`` is the only entry point; a no-op policy
+(everything off) preserves the historical default behaviour exactly.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal, get_args
+
+from ..core.errors import BlueprintValidationError
+
+MouseMode = Literal["off", "gestures"]
+KeyboardMode = Literal["off", "human"]
+ScrollMode = Literal["off", "eased"]
+
+_MOUSE_MODES = frozenset(get_args(MouseMode))
+_KEYBOARD_MODES = frozenset(get_args(KeyboardMode))
+_SCROLL_MODES = frozenset(get_args(ScrollMode))
+_KNOWN_KEYS = frozenset({"mouse", "keyboard", "scroll", "timing", "fingerprint"})
+
+
+@dataclass(frozen=True, slots=True)
+class StealthPolicy:
+    """Which discretion features are active for a run. Immutable once assembled.
+
+    ``mouse``/``keyboard``/``scroll`` gate the humanizers; ``distraction`` is the probability of an
+    occasional idle pause; ``fingerprint`` names a profile (or ``None`` to keep Playwright's stock
+    fingerprint). ``OFF`` is the identity policy: no feature touches the page.
+    """
+
+    mouse: MouseMode = "off"
+    keyboard: KeyboardMode = "off"
+    scroll: ScrollMode = "off"
+    distraction: float = 0.0
+    fingerprint: str | None = None
+
+    @property
+    def is_active(self) -> bool:
+        """True when at least one feature would alter the browser or its inputs."""
+        return (
+            self.mouse != "off"
+            or self.keyboard != "off"
+            or self.scroll != "off"
+            or self.fingerprint is not None
+        )
+
+
+# Identity policy shared by every "off" path, so callers can compare against a single instance.
+OFF = StealthPolicy()
+
+# Named presets usable as ``"stealth": "<name>"``. Kept deliberately small; a preset is just a
+# curated StealthPolicy so power users can still spell every field out inline.
+_PRESETS: dict[str, StealthPolicy] = {
+    "off": OFF,
+    "human": StealthPolicy(
+        mouse="gestures",
+        keyboard="human",
+        scroll="eased",
+        distraction=0.1,
+        fingerprint="chrome-desktop",
+    ),
+}
+
+
+def preset_names() -> list[str]:
+    """The stealth preset names usable as ``"stealth": "<name>"``, sorted. A public view of the
+    preset table so the builder offers exactly what ``build_policy`` accepts, without duplicating it.
+    """
+    return sorted(_PRESETS)
+
+
+def _fail(detail: str) -> BlueprintValidationError:
+    return BlueprintValidationError(f"Invalid options.stealth: {detail}")
+
+
+def _distraction(timing: Any) -> float:
+    if timing is None:
+        return 0.0
+    if not isinstance(timing, dict):
+        raise _fail("'timing' must be an object.")
+    value = timing.get("distraction", 0.0)
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise _fail("'timing.distraction' must be a number between 0 and 1.")
+    if not 0.0 <= value <= 1.0:
+        raise _fail("'timing.distraction' must be between 0 and 1.")
+    return float(value)
+
+
+def _choice(value: Any, allowed: frozenset[str], field: str) -> str:
+    if value is None:
+        return "off"
+    if value not in allowed:
+        raise _fail(f"'{field}' must be one of {sorted(allowed)}, got {value!r}.")
+    return str(value)
+
+
+def build_policy(raw: Any) -> StealthPolicy:
+    """Decode ``options.stealth`` into a :class:`StealthPolicy`.
+
+    Accepts the three shapes the schema allows: ``None``/``"off"`` (no-op), a preset name, or an
+    inline object. Anything else raises a typed :class:`BlueprintValidationError` rather than
+    silently degrading, so a malformed Blueprint fails loud and early.
+    """
+    if raw is None:
+        return OFF
+    if isinstance(raw, str):
+        preset = _PRESETS.get(raw)
+        if preset is None:
+            raise _fail(f"unknown preset {raw!r} (known: {sorted(_PRESETS)}).")
+        return preset
+    if not isinstance(raw, dict):
+        raise _fail("expected 'off', a preset name, or an object.")
+
+    unknown = set(raw) - _KNOWN_KEYS
+    if unknown:
+        raise _fail(f"unknown keys {sorted(unknown)} (allowed: {sorted(_KNOWN_KEYS)}).")
+
+    fingerprint = raw.get("fingerprint")
+    if fingerprint is not None and not isinstance(fingerprint, str):
+        raise _fail("'fingerprint' must be a profile name (string).")
+
+    return StealthPolicy(
+        mouse=_choice(raw.get("mouse"), _MOUSE_MODES, "mouse"),  # type: ignore[arg-type]
+        keyboard=_choice(raw.get("keyboard"), _KEYBOARD_MODES, "keyboard"),  # type: ignore[arg-type]
+        scroll=_choice(raw.get("scroll"), _SCROLL_MODES, "scroll"),  # type: ignore[arg-type]
+        distraction=_distraction(raw.get("timing")),
+        fingerprint=fingerprint,
+    )

aetherius/stealth/session/__init__.py

@@ -0,0 +1 @@
+"""Persistent browser sessions and profile warmup."""

aetherius/stealth/session/store.py

@@ -0,0 +1,35 @@
+"""Persistent browser profiles and per-run artifact directories.
+
+A *profile* is a directory Playwright reuses across runs to carry authentic cookies, cache and
+history (``launch_persistent_context``). A *run directory* collects the artifacts a single run
+produces (screenshots, HAR, DOM snapshots). Both live under the configured ``data_dir``.
+
+Only directory resolution lives here for now. Warmup (building an authentic history before an
+automation) and storage-state export are later milestones and are intentionally left out.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ...config.settings import get_settings
+
+
+def resolve_profile_dir(profile: str | None) -> Path | None:
+    """Return the directory for a persistent browser *profile*, creating it on demand.
+
+    Returns ``None`` when *profile* is falsy, signalling the caller to use an ephemeral
+    (non-persistent) browser context instead.
+    """
+    if not profile:
+        return None
+    path = get_settings().profiles_dir / profile
+    path.mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def run_dir(run_id: str) -> Path:
+    """Return the artifact directory for *run_id*, creating it on demand."""
+    path = get_settings().runs_dir / run_id
+    path.mkdir(parents=True, exist_ok=True)
+    return path

aetherius/stealth/session/warmup.py

@@ -0,0 +1,52 @@
+"""Profile warmup: build an authentic browsing history before automation.
+
+A persistent profile that jumps straight to a sensitive target on its very first request looks
+synthetic. Warmup visits a few innocuous pages first, dwelling on each, so the profile accrues real
+cookies, cache and history — the human touch a cold profile lacks. Generalizes the manual
+login-setup flow of the legacy projects.
+
+:func:`plan_warmup` is pure (the itinerary and dwell times, deterministic given an ``rng``);
+:func:`warmup_profile` plays it against a page. Kept intentionally small.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from random import Random
+from typing import Any
+
+from ..humanizer.timing import Sleeper, precise_sleep
+
+_DEFAULT_DWELL_MS = 2000.0
+_DEFAULT_RNG = Random()
+
+
+@dataclass(frozen=True, slots=True)
+class WarmupStep:
+    """One warmup visit: a URL and how long (seconds) to dwell before moving on."""
+
+    url: str
+    dwell_s: float
+
+
+@dataclass(frozen=True, slots=True)
+class WarmupPlan:
+    """An ordered warmup itinerary."""
+
+    steps: list[WarmupStep]
+
+
+def plan_warmup(
+    urls: Iterable[str], *, dwell_ms: float = _DEFAULT_DWELL_MS, rng: Random = _DEFAULT_RNG
+) -> WarmupPlan:
+    """Build a warmup itinerary from *urls*, each with a randomized dwell around *dwell_ms*."""
+    steps = [WarmupStep(url, rng.uniform(dwell_ms * 0.6, dwell_ms * 1.4) / 1000.0) for url in urls]
+    return WarmupPlan(steps)
+
+
+def warmup_profile(page: Any, plan: WarmupPlan, *, sleep: Sleeper = precise_sleep) -> None:
+    """Play *plan* against a page: navigate to each URL and dwell, accreting authentic history."""
+    for step in plan.steps:
+        page.goto(step.url)
+        sleep(step.dwell_s)

aetherius/version.py

@@ -0,0 +1,3 @@
+"""Single source of the package version."""
+
+__version__ = "0.2.0"

aetherius-0.2.0.data/data/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
+    }
+  }
+}