aetherius 0.2.0__py3-none-any.whl

aetherius-0.2.0.dist-info/METADATA

@@ -0,0 +1,606 @@
+Metadata-Version: 2.4
+Name: aetherius
+Version: 0.2.0
+Summary: A fixed, robust web-bot engine driven by declarative instruction files (Blueprints).
+Project-URL: Repository, https://github.com/kln-mltre/Aetherius
+Author: Kylian Malartre
+License: Aetherius
+        Copyright (c) 2026 Kylian MALARTRE (kln-mltre)
+        
+        This work is licensed under the Creative Commons Attribution-NonCommercial 4.0 International License.
+        
+        To view a copy of this license, visit http://creativecommons.org/licenses/by-nc/4.0/ or send a letter to Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+        
+        COMMERCIAL USE RESTRICTION
+        Any commercial use, including but not limited to selling the software, offering it as a paid service (SaaS), or using it to generate revenue directly or indirectly, is strictly prohibited without prior written consent from the author. 
+        
+        For commercial licensing inquiries or dual-licensing options, please contact the author directly.
+License-File: LICENSE
+Keywords: agent,automation,bot,browser,playwright,scraping,stealth
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.110
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonpath-ng>=1.6
+Requires-Dist: jsonschema>=4.21
+Requires-Dist: parsel>=1.9
+Requires-Dist: pydantic-settings>=2.2
+Requires-Dist: pydantic>=2.6
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.7
+Requires-Dist: tenacity>=8.2
+Requires-Dist: textual>=0.60
+Requires-Dist: typer>=0.12
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: websockets>=12.0
+Provides-Extra: agent
+Requires-Dist: anthropic>=0.25; extra == 'agent'
+Provides-Extra: all
+Requires-Dist: anthropic>=0.25; extra == 'all'
+Requires-Dist: numpy>=1.26; extra == 'all'
+Requires-Dist: onnxruntime>=1.17; extra == 'all'
+Requires-Dist: opencv-python-headless>=4.9; extra == 'all'
+Requires-Dist: pillow>=10.3; extra == 'all'
+Requires-Dist: playwright>=1.44; extra == 'all'
+Provides-Extra: browser
+Requires-Dist: playwright>=1.44; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.9; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.1; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: stealth
+Requires-Dist: numpy>=1.26; extra == 'stealth'
+Provides-Extra: vision
+Requires-Dist: numpy>=1.26; extra == 'vision'
+Requires-Dist: onnxruntime>=1.17; extra == 'vision'
+Requires-Dist: opencv-python-headless>=4.9; extra == 'vision'
+Requires-Dist: pillow>=10.3; extra == 'vision'
+Description-Content-Type: text/markdown
+
+# Aetherius
+
+```text
+▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚
+ ˚ ✦ ·       ✦      · ˚       ✦ ·      ˚ ·     ✦    · ˚ ✦      · ✦ ˚
+ █████╗ ███████╗████████╗██╗  ██╗███████╗██████╗ ██╗██╗   ██╗███████╗
+██╔══██╗██╔════╝╚══██╔══╝██║  ██║██╔════╝██╔══██╗██║██║   ██║██╔════╝
+███████║█████╗     ██║   ███████║█████╗  ██████╔╝██║██║   ██║███████╗
+██╔══██║██╔══╝     ██║   ██╔══██║██╔══╝  ██╔══██╗██║╚██╗ ██╔╝╚════██║
+██║  ██║███████╗   ██║   ██║  ██║███████╗██║  ██║██║ ╚████╔╝ ███████║
+╚═╝  ╚═╝╚══════╝   ╚═╝   ╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝  ╚══════╝
+            ❧──────────────────── ❦ ────────────────────❧
+                     ✦  per nubes, ad aethera  ✦
+▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚▞▚
+```
+
+> Se veut le produit du concept de bot web modulaire, poussé à son paroxysme.   
+> Capable de réaliser, sur la base d'un simple fichier d'instructions, n'importe quelle tâche.
+
+## La vision
+
+Dans la plupart des projets on réécrit le même code fragile : requêtes `axios`/HTTP, scraping,
+automatisation de navigateur. C'est répétitif, fastidieux, et ça casse dès que le site ou l'API
+change — il faut alors éditer ce code éparpillé dans chaque projet.
+
+**Aetherius inverse le problème.** Le moteur du bot est fixe et robuste. Le comportement, lui, est
+décrit dans un **fichier d'instructions déclaratif** (un *Blueprint*, en JSON). Quand un site
+change, on corrige **un Blueprint**, pas N codebases. Et parce que le moteur est exposé via un
+**daemon local**, on le pilote depuis **n'importe quel langage** (TypeScript, Python, …) avec le
+même fichier d'instructions.
+
+Aetherius est conçu pour être **exporté comme bibliothèque** et alimenter tous les projets :
+récupérer un emploi du temps via API, scraper une page derrière un login, publier une vidéo en
+restant indétectable, ou lâcher un agent autonome sur une tâche non scriptée.
+
+Aetherius est à la fois une **bibliothèque** (consommée en direct ou via un daemon par les apps clientes)
+et un **outil** : une **Console dans le terminal** pour créer, tester et gérer tout ça sans écrire
+une ligne de JSON à la main.
+
+<p align="center"><sub>▚▞▚ ✦ ▞▚▞</sub></p>
+
+## Le concept : 4 Acts
+
+Aetherius est un interprète qui joue en quatre **Acts**, du plus léger au plus puissant. Le
+Blueprint choisit l'Act adapté à la tâche.
+
+| Act | Nom | Moteur | Quand l'utiliser |
+|-----|-----|--------|------------------|
+| **I** | **Vector** | Requêtes HTTP/API | Les données sont derrière une API ou des endpoints stables. Le cas « axios ». Le plus rapide. |
+| **II** | **Continuum** | Navigateur scripté (Playwright) | Il faut un vrai navigateur : login, JS, session, DOM. Sélecteurs connus et stables. |
+| **III** | **Oracle** | Navigateur guidé par vision + discrétion | L'UI est fragile/obfusquée : Aetherius « voit » l'écran via un petit modèle entraîné et agit avec discrétion. |
+| **IV** | **Phantom** | Agent autonome | Objectif non scripté. Perçoit, raisonne, agit en boucle. Résilience maximale. Le plus lourd. |
+
+Plus l'Act est élevé, plus le Blueprint est **haut-niveau** (on décrit *quoi*, plus *comment*) et
+plus les dépendances sont lourdes (installées à la demande via des *extras*).
+
+### Act I — Vector
+Client HTTP robuste : requêtes GET/POST, encodage form/JSON, en-têtes, retries avec backoff,
+pagination, stratégies d'authentification (cookie, bearer, basic, form-login type CAS), extraction
+déclarative (JSONPath pour le JSON, CSS/XPath pour le HTML). Remplace les services `axios` écrits à
+la main ; les constantes magiques disséminées deviennent des `inputs` typés et documentés.
+
+### Act II — Continuum
+Automatisation d'un vrai navigateur (Playwright) qui suit le Blueprint à la lettre : navigation,
+remplissage, clics, attentes, extraction DOM, bridge JavaScript injecté. Gère les scénarios qui
+exigent un navigateur : login, cookies de session, contenu rendu par JS. C'est l'équivalent propre
+et réutilisable d'une « WebView cachée qui scrape ». Discrétion optionnelle.
+
+### Act III — Oracle
+Quand les sélecteurs sont trop fragiles ou absents, Oracle **regarde l'écran**. Un petit modèle de
+vision entraîné spécifiquement pour la tâche (exporté en ONNX) localise les éléments cibles sur des
+captures d'écran ; Aetherius clique par coordonnées à travers la couche de discrétion. Idéal pour
+les interfaces qui changent souvent ou piègent les bots.
+
+### Act IV — Phantom
+Un agent décisionnel autonome. Boucle **percevoir → raisonner → agir** : il perçoit la page (vision
++ DOM + arbre d'accessibilité), un planner (par défaut Claude, ex. `claude-fable-5` /
+`claude-opus-4-8`, remplaçable par un VLM local) décide de l'action suivante, et l'action est jouée
+via la couche de discrétion. Pour les objectifs non scriptés et la résilience maximale.
+
+> Aetherius est destiné à l'automatisation **autorisée** : ses propres comptes, ses propres données,
+> ses propres workflows.
+
+<p align="center"><sub>▚▞▚ ✦ ▞▚▞</sub></p>
+
+## Les fichiers d'instructions : les Blueprints
+
+Un Blueprint est un fichier JSON déclaratif et versionné. Enveloppe :
+
+```json
+{
+  "aetherius": "1.0",
+  "name": "domaine.tache",
+  "act": "vector",
+  "inputs":  { "param": { "type": "string", "required": true } },
+  "secrets": ["cle_injectee_au_runtime"],
+  "vars":    { "domain": "https://exemple.fr" },
+  "options": {
+    "debug": false,
+    "stealth": "off",
+    "session": { "profile": "mon-profil", "persist": true },
+    "timeout_ms": 30000,
+    "retries": { "max": 3, "backoff": "exponential" }
+  },
+  "steps":   [ /* la séquence d'actions */ ],
+  "outputs": { "resultat": "{{ steps.x.champ }}" }
+}
+```
+
+- **inputs** : paramètres typés (le Blueprint est réutilisable, pas figé sur une valeur).
+- **secrets** : identifiants/token fournis au runtime, **jamais** écrits dans le fichier (résolus
+  depuis l'environnement / un `.env` local — voir [docs/secrets.md](docs/secrets.md)).
+- **vars** : constantes locales (domaines, chemins).
+- **options** : `debug`, `stealth`, `session`, `timeout_ms`, `retries`.
+- **steps** : le *dictionnaire d'actions* (navigate, click, fill, type, http.request, extract,
+  wait, if, for_each, …). Chaque Act déclare quelles actions il supporte ; un Blueprint qui demande
+  une action non supportée par son Act échoue à la validation, avec un message clair.
+- **outputs** : la forme des données retournées, via interpolation `{{ }}`.
+
+Le format est défini une fois pour toutes dans [`contracts/blueprint.schema.json`](contracts/blueprint.schema.json).
+Des exemples exécutables (dérivés de vrais projets) sont dans [`examples/`](examples/).
+
+### Exemple — Act I (Vector) : emploi du temps par API
+Voir [`examples/vector/ukit-planning-week.blueprint.json`](examples/vector/ukit-planning-week.blueprint.json).
+
+```json
+{
+  "aetherius": "1.0",
+  "name": "ukit.planning.week",
+  "act": "vector",
+  "inputs": {
+    "group":  { "type": "string", "required": true },
+    "monday": { "type": "string", "format": "date", "required": true }
+  },
+  "vars": { "domain": "https://ade-web.exemple.fr" },
+  "steps": [
+    {
+      "id": "week",
+      "action": "http.request",
+      "method": "POST",
+      "url": "{{ vars.domain }}/calendar/data",
+      "headers": {
+        "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
+        "Accept": "application/json"
+      },
+      "form": {
+        "start": "{{ inputs.monday }}",
+        "end": "{{ inputs.monday | add_days(7) }}",
+        "resType": "103",
+        "calView": "agendaWeek",
+        "federationIds[]": "{{ inputs.group }}",
+        "colourScheme": "3"
+      },
+      "expect": { "status": 200 },
+      "extract": {
+        "events": {
+          "from": "json", "path": "$[*]",
+          "where": "item.eventCategory != 'Vacances'",
+          "fields": {
+            "id": "$.id", "start": "$.start", "end": "$.end",
+            "category": "$.eventCategory", "color": "$.backgroundColor",
+            "description": "$.description"
+          }
+        }
+      }
+    }
+  ],
+  "outputs": { "events": "{{ steps.week.events }}" }
+}
+```
+Les constantes autrefois codées en dur (`resType`, `colourScheme`) sont explicites, le filtrage
+`Vacances` et le parsing sont déclaratifs, et le groupe/la date sont des `inputs` réutilisables.
+
+### Exemple — Act II (Continuum) : login CAS + scraping
+Voir [`examples/continuum/ukit-scolarite-login.blueprint.json`](examples/continuum/ukit-scolarite-login.blueprint.json).
+
+```json
+{
+  "aetherius": "1.0",
+  "name": "ukit.scolarite.cold",
+  "act": "continuum",
+  "secrets": ["cas_user", "cas_pass"],
+  "options": { "session": { "profile": "scolarite", "persist": true }, "debug": false },
+  "steps": [
+    { "action": "navigate",  "url": "https://cas.exemple.fr/login" },
+    { "action": "fill",      "selector": "#username", "value": "{{ secrets.cas_user }}" },
+    { "action": "fill",      "selector": "#password", "value": "{{ secrets.cas_pass }}" },
+    { "action": "click",     "selector": "input[name=submit]" },
+    { "action": "wait_for",  "selector": ".ent-dashboard", "timeout_ms": 15000,
+      "on_timeout": "fail:LOGIN_FAILED" },
+    { "action": "emit",      "event": "LOGIN_SUCCESS" },
+    { "action": "navigate",  "url": "https://ent.exemple.fr/dossier" },
+    { "action": "extract",   "outputs": {
+        "firstName":     { "selector": ".identity .firstname", "as": "text" },
+        "studentNumber": { "selector": "#num-etudiant", "as": "text" },
+        "ine":           { "selector": "#ine", "as": "text" },
+        "email":         { "selector": ".mail", "as": "text" }
+    }},
+    { "action": "navigate",  "url": "https://webmail.exemple.fr" },
+    { "action": "extract",   "outputs": { "unread": { "selector": ".unread-count", "as": "number" } } }
+  ]
+}
+```
+Les sélecteurs sont désormais des **données** (plus du JS injecté codé en dur), le flux de login est
+déclaratif, et les événements (`LOGIN_SUCCESS`, …) restent disponibles pour suivre la progression.
+
+### Exemple — Act III (Oracle) : upload avec discrétion
+Voir [`examples/oracle/tiktok-upload.blueprint.json`](examples/oracle/tiktok-upload.blueprint.json).
+
+```json
+{
+  "aetherius": "1.0",
+  "name": "tiktok.upload",
+  "act": "oracle",
+  "inputs": {
+    "video":   { "type": "path",   "required": true },
+    "caption": { "type": "string", "required": true }
+  },
+  "options": {
+    "session": { "profile": "tiktok", "persist": true },
+    "stealth": {
+      "mouse": "gestures", "keyboard": "human", "scroll": "eased",
+      "timing": { "distraction": 0.1 }, "fingerprint": "chrome-desktop"
+    },
+    "debug": false
+  },
+  "vision": { "model": "tiktok-studio-ui@1" },
+  "steps": [
+    { "action": "navigate", "url": "https://www.tiktok.com/tiktokstudio/upload?lang=fr" },
+    { "action": "wait",     "min_ms": 3500, "max_ms": 6000 },
+    { "action": "upload",   "target": { "vision": "upload dropzone" }, "file": "{{ inputs.video }}" },
+    { "action": "type",     "target": { "vision": "caption textarea" }, "text": "{{ inputs.caption }}" },
+    { "action": "wait",     "min_ms": 2000, "max_ms": 4500 },
+    { "action": "click",    "target": { "vision": "Post button" } },
+    { "action": "wait_for", "target": { "vision": "publish success toast" }, "timeout_ms": 35000 }
+  ]
+}
+```
+
+<p align="center"><sub>▚▞▚ ✦ ▞▚▞</sub></p>
+
+## La Console Aetherius : tout gérer depuis le terminal
+
+Aetherius n'est pas qu'une bibliothèque : c'est aussi une **Console interactive dans le terminal**
+(construite avec Textual), le centre de contrôle de l'outil. On la lance simplement :
+
+```bash
+aetherius            # ouvre la Console
+```
+
+![La Console Aetherius : écran d'accueil](docs/screenshots/home.svg)
+
+> **État actuel** : la Console est navigable de bout en bout. Library, Runs, Catalog, le **Recorder**,
+> le **Blueprint Studio** et **Settings** (démarrer/arrêter le daemon) sont pleinement fonctionnels
+> pour Act I (Vector) et Act II (Continuum, avec l'extra `[browser]`) ; seul **Sessions** affiche
+> honnêtement son jalon en attente (stealth/session). Détails : [docs/console.md](docs/console.md).
+
+Depuis la Console, sans écrire de JSON à la main :
+- **Créer et éditer des Blueprints** via le **Blueprint Studio** (voir plus bas).
+- **Lancer des runs** et suivre en direct leurs événements, logs et artefacts.
+- **Explorer et comprendre** les 4 Acts et les modèles de vision disponibles (fiches explicatives).
+- **Gérer les profils/sessions** persistants et lancer un warmup.
+- **Piloter le daemon** (démarrer/arrêter) et la configuration.
+- **Parcourir la bibliothèque** de Blueprints (dupliquer, éditer, supprimer).
+
+### Créer un Blueprint : trois voies
+
+1. **Le Blueprint Studio (guidé, rapide, sans JSON)** — dans la Console. Sélection de l'Act (avec
+   son explication), ajout des steps via des formulaires, **aperçu JSON live** validé contre le
+   schéma en temps réel. L'option la plus rapide pour la majorité des cas.
+2. **Le Recorder (par démonstration)** — pour les tâches d'automatisation navigateur : l'action est
+   réalisée dans un navigateur visible, Aetherius capture et recrache un Blueprint propre, avec
+   **synthèse de sélecteurs robustes** (privilégie `data-testid`/aria/texte avant les chemins CSS
+   fragiles). Idéal quand la démonstration directe est plus simple que la description.
+3. **JSON à la main** — pour les power users qui veulent le contrôle total.
+
+![Le Blueprint Studio : construction guidée avec aperçu JSON validé en direct](docs/screenshots/studio.svg)
+
+La logique de construction vit dans un module `builder/` *headless* : la Console n'en est que
+l'habillage, et le daemon peut l'exposer pour construire des Blueprints programmatiquement.
+Prise en main illustrée : [docs/builder.md](docs/builder.md).
+
+## La discrétion (stealth), en option modulaire
+
+La discrétion n'est **pas** liée à un Act : c'est une couche transverse activée par
+`options.stealth`, applicable à tout Act qui pilote un navigateur (II, III, IV). Désactivée par
+défaut (no-op).
+
+Techniques disponibles (issues et généralisées du système *BioMouse* éprouvé) :
+- **Souris humaine** : rejeu d'un geste humain *réellement enregistré*, transformé
+  géométriquement (mise à l'échelle + rotation) pour atteindre n'importe quelle cible. Matching du
+  meilleur geste par distance et angle, timing inter-points préservé à la microseconde. Clics
+  off-center (30–70 % de l'élément), micro-pauses avant/pendant le clic.
+- **Clavier humain** : vitesse variable par session, fautes de frappe suivies de corrections,
+  délais accrus sur les espaces et caractères spéciaux.
+- **Scroll humain** : courbe d'easing ease-out cubique (départ rapide, fin douce).
+- **Timing humain** : délais aléatoires, pauses « distraction » occasionnelles, parking du curseur
+  pendant les attentes longues.
+- **Fingerprint** : masquage `navigator.webdriver`, `chrome.runtime`, `plugins`, `permissions` ;
+  profils de fingerprint cohérents (UA, viewport, timezone, WebGL, canvas).
+- **Profils persistants + warmup** : réutilisation d'un profil navigateur pour construire un
+  historique authentique (cookies, cache) avant l'automatisation.
+
+Activation :
+```json
+"options": { "stealth": { "mouse": "gestures", "keyboard": "human", "fingerprint": "chrome-desktop" } }
+```
+`"stealth": "off"` (défaut) ou `"stealth": "nom-de-preset"` sont aussi acceptés.
+
+**IA pour la discrétion ?** Approche hybride retenue : le rejeu géométrique de gestes est le moteur
+par défaut (léger, éprouvé, score reCAPTCHA élevé) — **pas besoin d'IA**. Deux upgrades ML
+*optionnels* sont prévus derrière la même interface : un modèle génératif de mouvements (pour ne pas
+se limiter à une bibliothèque finie de gestes) et un modèle de fingerprints cohérents. À activer
+seulement si un cas d'usage le justifie.
+
+## Le mode Debug
+
+`options.debug: true` :
+- **Acts navigateur (II/III/IV)** : fenêtre visible, overlay du curseur, surlignage des cibles,
+  ralenti (slow-mo). Idéal pour comprendre pourquoi un step échoue.
+- **Acts sans navigateur (I)** : logs terminal structurés (requêtes, réponses, extractions).
+- Tous les Acts émettent des **événements** consommables (progression, artefacts : screenshots,
+  HAR, snapshots DOM) écrits dans un répertoire de run.
+
+## Le Gesture Recorder
+
+En complément, un *gesture recorder* capture des traces de souris humaines réelles pour enrichir la
+bibliothèque de gestes du système de discrétion. (Le Blueprint recorder, lui, est décrit plus haut
+dans « Créer un Blueprint : trois voies ».)
+
+<p align="center"><sub>▚▞▚ ✦ ▞▚▞</sub></p>
+
+## Interopérabilité multi-langage
+
+Le cœur est en Python ; il est exposé à tous les langages via un **daemon local**.
+
+```
+┌─────────────┐   Blueprint + inputs + secrets    ┌──────────────────────────┐
+│  App        │ ────────────────────────────────► │  Aetherius Daemon        │
+│ (TS/Python) │        HTTP  +  WebSocket          │  (FastAPI)               │
+│  SDK mince  │ ◄──────────────────────────────── │  Runtime → Act I..IV     │
+└─────────────┘   résultat + flux d'événements     └──────────────────────────┘
+```
+
+- **Daemon** : `aetherius serve` (local, 127.0.0.1, token optionnel, `GET /health`).
+  - `POST /v1/runs` → `run_id` ; `GET /v1/runs/{id}` → statut + résultat.
+  - `WS /v1/runs/{id}/events` → flux d'événements (rejeu + live jusqu'à `done`).
+  - `POST /v1/blueprints/validate`, `GET /v1/schema`. `POST /v1/recorder/sessions` : `501`,
+    l'enregistrement reste host-local (CLI/Console).
+- **SDK TypeScript** `@aetherius/client` (Node 20+) : spawn le daemon (ou cible un `baseUrl`),
+  `client.run(blueprint, { inputs, secrets, onEvent })`, stream d'événements typé.
+- **SDK Python** : l'import in-process direct (`import aetherius`, sans daemon) ; le client remote
+  mince est différé.
+- **Contrats** ([`contracts/`](contracts/)) : JSON Schema du Blueprint + OpenAPI du daemon + schéma
+  d'événements = source de vérité ; les types des SDK s'y conforment (gardés par des tests).
+
+Détails, sécurité et « Tester le daemon » : [docs/daemon.md](docs/daemon.md).
+
+### Exécuter un Blueprint depuis le code applicatif
+
+La Console sert à *créer et gérer* les Blueprints. L'**exécution**, elle, se fait directement depuis
+le code applicatif, en chargeant un Blueprint **existant** — la Console n'est jamais requise au runtime.
+
+Python (in-process, sans daemon) :
+```python
+from aetherius import Aetherius
+
+client = Aetherius()
+result = client.run(
+    "blueprints/ukit-planning-week.blueprint.json",
+    inputs={"group": "TP-A1", "monday": "2026-09-07"},
+)
+print(result.outputs["events"])
+```
+
+TypeScript (via le daemon local, spawné automatiquement) :
+```ts
+import { Aetherius } from "@aetherius/client";
+
+const client = new Aetherius();
+const result = await client.run("blueprints/ukit-planning-week.blueprint.json", {
+  inputs: { group: "TP-A1", monday: "2026-09-07" },
+});
+console.log(result.outputs.events);
+```
+
+<p align="center"><sub>▚▞▚ ✦ ▞▚▞</sub></p>
+
+## Architecture du dépôt
+
+```
+src/aetherius/
+  core/        blueprint (models/loader/validator/template), actions (le dictionnaire),
+               runtime (engine/context/selector/result), extraction, events, errors, driver
+  acts/        vector (I), continuum (II), oracle (III), phantom (IV)
+  stealth/     policy, humanizer (mouse/keyboard/scroll/timing), gestures, fingerprint,
+               session (store/warmup), ml (optionnel)
+  recorder/    blueprint_recorder, gesture_recorder, capture, selector_synth
+  builder/     construction headless de Blueprint (factory, catalog, templates)
+  console/     interface terminale globale (Textual) : Blueprint Studio, runs, catalogue,
+               sessions, settings — la porte d'entrée de l'outil
+  models/      registry + cache des assets ML runtime
+  server/      daemon FastAPI (routes/jobs/schemas)
+  config/      settings
+contracts/     blueprint.schema.json, openapi.yaml, events.schema.json  (source de vérité)
+sdks/          typescript (@aetherius/client), python
+examples/      Blueprints de démonstration
+training/      entraînement des modèles Oracle (hors runtime)
+legacy_examples/  code de référence des projets d'origine (UKit, TikTok) + carte de provenance
+```
+
+Principe : chaque fichier de logique reste sous ~300 lignes ; typage strict (pydantic) ; erreurs
+typées (jamais avalées) ; les Acts sont des drivers interchangeables derrière une interface commune.
+
+## Installation (cible)
+
+```bash
+pip install aetherius            # cœur + Act I (Vector) + daemon + Console
+pip install aetherius[browser]   # + Act II (Continuum)
+pip install aetherius[vision]    # + Act III (Oracle)
+pip install aetherius[agent]     # + Act IV (Phantom)
+pip install aetherius[all]
+```
+
+Puis pour lancer la Console :
+```bash
+aetherius            # centre de contrôle interactif dans le terminal
+```
+
+## Développement
+
+Pour travailler sur Aetherius (et pas seulement le consommer). Prérequis : Python 3.11+ et, pour le
+SDK TypeScript, Node 20+.
+
+```bash
+git clone <repo> && cd Aetherius
+make install-dev          # installe le paquet en editable + les outils de dev
+```
+
+Le `Makefile` est le point d'entrée unique — les mêmes cibles servent en local et en CI :
+
+```bash
+make check                # avant de commit : format + lint (ruff) + types (mypy) + tests (pytest)
+make test                 # tests seuls, avec couverture
+make check-all            # tout le dépôt : Python + SDK TypeScript
+make help                 # liste des cibles
+```
+
+Conventions de contribution (discipline de test, invariants, structure des tests) :
+[`CONTRIBUTING.md`](CONTRIBUTING.md) et [`docs/testing.md`](docs/testing.md).
+
+<p align="center"><sub>▚▞▚ ✦ ▞▚▞</sub></p>
+
+## État d'avancement
+
+Le projet avance en deux grandes phases. La **Phase 1** — le socle, utilisable comme **bibliothèque**
+(in-process Python) et comme **service** (daemon + SDK) — est **terminée avec ce jalon** : un premier
+point de contrôle, à éprouver en conditions réelles avant d'attaquer la **Phase 2** (les deux Acts les
+plus lourds).
+
+### Phase 1 — le socle réutilisable (terminée)
+
+- [x] Vision, concept des 4 Acts, format Blueprint, architecture.
+- [x] Squelette : arborescence + stubs + contrats + exemples.
+- [x] **Act I — Vector** : moteur HTTP/API complet. `Aetherius().run(blueprint, inputs=...)` fonctionnel. Couverture : http.request (form/JSON/params/headers), extraction JSONPath avec `where` et mapping de champs, extraction HTML CSS/XPath, authentification (NoAuth/Bearer/Basic/Cookie/CAS form-login), retries/backoff (tenacity), moteur de templates Jinja2 (`{{ inputs.x | add_days(7) }}`), bus d'événements, hiérarchie d'erreurs typées. 69 tests, mypy strict, lint propre.
+- [x] **Console (Textual)** : navigation complète (`aetherius` ou `aetherius console`) — Library,
+  Runs et Catalog fonctionnels pour Act I (parcours des Blueprints, exécution avec formulaire
+  d'inputs/secrets et flux d'événements en direct, catalogue des 4 Acts). CLI scriptable
+  (`aetherius run|validate|record`). Le Recorder et le Blueprint Studio sont fonctionnels (voir
+  ci-dessous) ; seuls Sessions et Settings affichent leur jalon en attente ; voir
+  [docs/console.md](docs/console.md).
+- [x] **Act II — Continuum** : automatisation d'un vrai navigateur (Playwright, API synchrone).
+  Actions navigateur (navigate/back/forward/reload, click/fill/type/press/select/hover/scroll/
+  upload/drag), `wait_for` avec échec nommé (`on_timeout: "fail:CODE"`), extraction DOM typée
+  (text/number/html/attr/count), `evaluate` (JS injecté), `screenshot` (artefact), sessions
+  persistantes (profils réutilisés) et mode debug (fenêtre visible + slow-mo). Actions utilitaires
+  partagées avec Vector via un mixin (zéro duplication). Extra `[browser]` chargé à la demande ;
+  `import aetherius` reste léger. Tests unitaires (page factice, CI de base) + intégration vrai
+  Chromium (job CI dédié). Discrétion : **branchée** (voir ci-dessous).
+- [x] **Système de discrétion** : couche transverse activée par `options.stealth`, branchée dans
+  Continuum. `StealthPolicy` (off / preset / config fine). Fingerprint (masques `navigator.webdriver`/
+  `chrome.runtime`/`permissions`/`plugins` + profil cohérent UA/viewport/timezone/WebGL,
+  `chrome-desktop`). Souris humaine par rejeu géométrique de gestes (scale+rotation, timing préservé,
+  clic off-center), bibliothèque **source-agnostique** amorcée par un seed synthétique (min-jerk),
+  ouverte au recorder et au ML. Frappe humaine (typos+correction, délais), scroll ease-out, timing
+  avec distraction, warmup de profil. Cœur **stdlib pur** (tests en CI de base) ; intégration Chromium
+  réelle. Exemple : `examples/continuum/quotes-stealth.blueprint.json`. Détails :
+  [docs/stealth.md](docs/stealth.md).
+- [x] **Recorder (blueprint + gestes)** : création de Blueprint **par démonstration**,
+  **Act-agnostique** — une coquille commune (navigateur, overlay, session) + un **backend par Act**
+  derrière une interface unique (`recorder/base.py`, registre `act → backend`), choix de l'Act à la
+  main (`--act` / sélecteur Console). **Continuum** (Act II) : capture des actions DOM, **synthèse de
+  sélecteurs robustes** (`data-testid`/id/**href**/name/aria/classe avant le chemin CSS positionnel,
+  unicité mesurée in-page façon `get_by_text`), et **menu flottant** (overlay Shadow DOM) pour
+  **sélectionner les données** : champs, listes (`as: list`), tableaux/records (`each`/`fields`),
+  `wait_for`, paramétrage en `input`. **Vector** (Act I) : observe le trafic réseau (fetch/XHR/doc
+  JSON) et pique les champs dans la réponse → `http.request` + extraction JSONPath. Credentials et
+  en-têtes d'auth → `{{ secrets.x }}` (jamais stockés). Blueprint produit relu par le loader/validator
+  canonique, avec ses `outputs`. Console interactive + CLI (`aetherius record`). Gesture recorder
+  (`aetherius record-gestures`) : traces souris réelles vers la bibliothèque de discrétion. Trous
+  documentés pour Oracle/Phantom. Cœur pur en CI de base ; intégration Chromium réelle. Exemples :
+  `examples/continuum/quotes-recorded-{login,scrape}` + `examples/vector/jsonplaceholder-users-recorded`.
+  Détails : [docs/recorder.md](docs/recorder.md).
+- [x] **Builder headless + Blueprint Studio** : construction de Blueprints **sans JSON**, réutilisable
+  (Console, daemon, SDK). Module `builder/` pur : `catalog` (projection du dictionnaire d'actions),
+  `factory` (`BlueprintDraft` lossless, `validate_draft` non-levant pour l'aperçu live,
+  `build`/`save`), `templates` garantis valides. Specs d'actions déclaratives dans `core/actions/`
+  (l'invariant « registre = source, catalogue = projection » est désormais matérialisé), gardées par
+  deux tests anti-drift (bijection specs↔capabilities, dispatch specs↔drivers ; `PENDING_ACTIONS`
+  documente les actions déclarées mais pas encore exécutées). **Blueprint Studio** dans la Console :
+  sélection d'Act expliquée, inputs/secrets typés, steps par formulaires (params imbriqués en JSON +
+  trappe « raw JSON »), options durables, **aperçu JSON validé en direct**, et **édition** d'un
+  Blueprint existant (Library → `e`) — round-trip lossless garanti sur tous les exemples. Sauvegarde
+  dans `./blueprints`. Détails : [docs/builder.md](docs/builder.md).
+- [x] **Daemon local + SDK TypeScript** : daemon FastAPI (HTTP + WebSocket) exposant le moteur à tout
+  langage — `POST /v1/runs` (202 + `run_id`), `GET /v1/runs/{id}`, flux d'événements WebSocket (rejeu
+  bufferisé + live jusqu'à `done`), `POST /v1/blueprints/validate`, `GET /v1/schema`, `GET /health` ;
+  token bearer optionnel, bind loopback. Runs exécutés sur un thread de worker, événements relayés via
+  le pattern Sink (thread → asyncio). SDK TypeScript `@aetherius/client` (Node 20+) : spawn du daemon
+  (ou `baseUrl`), `client.run(blueprint, { inputs, secrets, onEvent })`, stream d'événements typé, avec
+  un E2E réel en CI. Console : l'écran **Settings** démarre/arrête le daemon. Enregistrement
+  volontairement host-local (`/v1/recorder/sessions` → 501). Détails : [docs/daemon.md](docs/daemon.md).
+
+**Phase 1 terminée.** Aetherius est utilisable comme bibliothèque et comme service ; c'est le point de
+contrôle prévu pour l'éprouver en conditions réelles et corriger avant la suite.
+
+### Phase 2 — les Acts autonomes (à venir)
+
+- [ ] Act III — Oracle (vision + entraînement).
+- [ ] Act IV — Phantom (agent).
+
+## Sources de référence
+
+Ce README et [`legacy_examples/README.md`](legacy_examples/README.md) constituent la documentation
+de référence complète du projet : vision, 4 Acts, format Blueprint, architecture. Les fichiers de
+[`legacy_examples/`](legacy_examples/) (carte de provenance) sont les cas d'usage réels à l'origine
+de chaque décision de conception.
+
+---
+
+<p align="center"><sub>❧ ▚▞▚ &nbsp;✦&nbsp; per nubes, ad aethera &nbsp;✦&nbsp; ▚▞▚ ❦</sub></p>