aetherius 0.2.0__tar.gz

aetherius-0.2.0/.env.example

@@ -0,0 +1,20 @@
+# Aetherius local secrets — TEMPLATE.
+#
+# Copy this file to `.env` (which is git-ignored and never committed) and fill in real values:
+#     cp .env.example .env
+#
+# Each Blueprint declares secrets by name only; the value is read at run time from the environment
+# variable AETHERIUS_SECRET_<NAME> (the secret name, upper-cased). Example: a Blueprint secret
+# `cas_pass` is read from AETHERIUS_SECRET_CAS_PASS. Existing environment variables win over `.env`,
+# so CI and production stay in control. Single-quote values that contain # ! $ or spaces.
+#
+# In the Console (Runs screen), a secret found here is shown "loaded from .env" and can be left
+# blank. On the CLI, `.env` is loaded automatically when running from the repo, or pass --secret.
+
+# Demo login — quotes.toscrape.com accepts any username/password.
+AETHERIUS_SECRET_QUOTES_USER=demo
+AETHERIUS_SECRET_QUOTES_PASS=demo
+
+# Universite de Bordeaux ENT/CAS.
+AETHERIUS_SECRET_BORDEAUX_USER=your-username
+AETHERIUS_SECRET_BORDEAUX_PASS='your-password'

aetherius-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,69 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+# Least privilege: the workflow only needs to read the repository.
+permissions:
+  contents: read
+
+# Cancel superseded runs on the same ref to save minutes.
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  python:
+    name: Python (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # Base install stays light; heavy Act extras are not needed, tests marked
+      # browser/vision/agent skip themselves when their dependency is absent.
+      - run: python -m pip install -e ".[dev]"
+      - run: make lint
+      - run: make typecheck
+      - run: make test
+
+  browser:
+    name: Browser (Act II)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # Act II needs the [browser] extra and a real Chromium; --with-deps pulls the OS libraries.
+      - run: python -m pip install -e ".[browser,dev]"
+      - run: python -m playwright install --with-deps chromium
+      - run: make test-browser
+
+  typescript:
+    name: TypeScript SDK
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+      # The SDK end-to-end test spawns the real daemon, so the package must be importable.
+      - run: python -m pip install -e .
+      - run: make test-ts

aetherius-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+.venv/
+venv/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Node / TypeScript SDK
+node_modules/
+sdks/typescript/dist/
+*.tsbuildinfo
+
+# Aetherius runtime artifacts
+src/aetherius/models/store/*
+!src/aetherius/models/store/.gitkeep
+runs/
+profiles/
+*.har
+
+# Training assets (kept out of git; heavy)
+training/datasets/
+training/checkpoints/
+training/runs/
+
+# Secrets and local config
+.env
+.env.*
+!.env.example
+
+# OS / editor / tooling
+.DS_Store
+.idea/
+.vscode/
+.claude/

aetherius-0.2.0/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+Toutes les évolutions notables du projet sont consignées ici. Le format s'inspire de
+[Keep a Changelog](https://keepachangelog.com/fr/1.1.0/) et le versionnage suit
+[SemVer](https://semver.org/lang/fr/). Tant que la version reste en `0.x`, l'API publique peut encore
+évoluer entre deux versions mineures (durcissement de la Phase 1 en conditions réelles).
+
+## [0.2.0] - 2026-07-10
+
+Première release publique. Elle clôt la **Phase 1** : le socle d'Aetherius, utilisable comme
+**bibliothèque** (in-process Python) et comme **service** (daemon local + SDK), avec sa Console.
+
+### Ajouté
+- **Daemon local (FastAPI)** — passerelle HTTP + WebSocket exposant le moteur à tout langage
+  (`aetherius serve`, bind loopback, token bearer optionnel) : `POST /v1/runs`, `GET /v1/runs/{id}`,
+  `WS /v1/runs/{id}/events` (rejeu bufferisé + flux live jusqu'à `done`), `POST /v1/blueprints/validate`,
+  `GET /v1/schema`, `GET /health`. L'enregistrement reste host-local (`POST /v1/recorder/sessions` → 501).
+  Voir [docs/daemon.md](docs/daemon.md).
+- **SDK TypeScript** `@aetherius/client` (Node 20+) — spawn du daemon (ou `baseUrl`),
+  `client.run(blueprint, { inputs, secrets, onEvent })`, streaming d'événements typé.
+- **Console : écran Settings** — démarrer/arrêter le daemon et voir son statut, sans quitter le terminal.
+- **Act I — Vector** : client HTTP/API (requêtes, retries/backoff, 5 stratégies d'auth, extraction
+  JSONPath et CSS/XPath, moteur de templates Jinja2).
+- **Act II — Continuum** : automatisation d'un vrai navigateur (Playwright, extra `[browser]`) —
+  navigation, interactions, extraction DOM, `wait_for` avec échec nommé, sessions persistantes, debug.
+- **Système de discrétion (stealth)** : couche transverse (`options.stealth`) — souris humaine par
+  rejeu géométrique de gestes, clavier/scroll/timing humains, fingerprint, warmup de profil.
+- **Recorder** : création de Blueprint par démonstration (Continuum et Vector) + gesture recorder.
+- **Builder headless + Blueprint Studio** : construction guidée de Blueprints sans JSON, avec aperçu
+  validé en direct, réutilisable par la Console, le daemon et les SDKs.
+- **Console (Textual)** : Library, Runs, Catalog, Recorder, Blueprint Studio, Settings.
+- **Contrats** langage-agnostiques (`contracts/`) : schéma Blueprint, OpenAPI du daemon, schéma
+  d'événements — source de vérité, gardés par des tests.
+
+### Notes
+- SemVer `0.x` : l'API peut évoluer pendant le durcissement de la Phase 1.
+- La **Phase 2** ajoutera Act III (Oracle, vision) et Act IV (Phantom, agent autonome).
+
+[0.2.0]: https://github.com/kln-mltre/Aetherius/releases/tag/v0.2.0

aetherius-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,125 @@
+# Contribuer à Aetherius
+
+Merci de contribuer. Ce document résume le workflow de développement et les conventions à suivre.
+Le cadrage produit est dans le [README](README.md), l'architecture dans
+[docs/architecture.md](docs/architecture.md).
+
+## Mise en place
+
+Prérequis : Python 3.11+ et, pour le SDK TypeScript, Node 20+.
+
+```bash
+make install-dev          # installe le paquet en editable + les outils de dev
+```
+
+## Workflow
+
+Une seule commande fait foi, en local comme en CI :
+
+```bash
+make check                # format + lint (ruff) + types (mypy) + tests (pytest)
+```
+
+Cibles utiles :
+
+```bash
+make test                 # tests seuls, avec couverture
+make lint                 # ruff
+make typecheck            # mypy (strict)
+make check-all            # tout le dépôt : Python + SDK TypeScript
+make help                 # liste des cibles
+```
+
+Ouvre une branche par changement, garde `make check` vert, et découpe en commits lisibles.
+
+## Définition de « terminé »
+
+Une capacité utilisateur (un Act, une action, une option) n'est terminée que lorsque **tout** ceci
+est vrai. On ne saute pas une étape en attendant qu'on la réclame :
+
+1. **Tests miroir** écrits avec le code — voir [Tests](#tests).
+2. **Exemple exécutable** ajouté dans `examples/<act>/`, lançable depuis `aetherius run` et la
+   Console — voir [Exemples exécutables](#exemples-exécutables).
+3. **Doc à jour** dans le même changement — voir [Documentation](#documentation).
+4. **`make check` vert.**
+5. **Flux vérifié à la main** au moins une fois : le vrai `run`, pas seulement les tests (chaque
+   doc d'Act a une section « Tester … » pour ça).
+6. **Prise en main UI** pour une capacité **liée à l'UI et non triviale** (nouvel écran ou
+   interaction non évidente de la Console) : un walkthrough orienté UI dans la doc **et** des captures
+   SVG générées (`make screenshots`) — voir [Documentation](#documentation). Exception : une
+   interaction rudimentaire (ex. sélectionner une ligne pour lancer un run) n'en a pas besoin.
+
+## Principes de code
+
+- Un fichier de logique reste sous ~300 lignes ; au-delà, on découpe en sous-modules.
+- Typage strict (pydantic v2) ; les erreurs sont typées et jamais avalées.
+- `import aetherius` reste léger : aucune dépendance lourde (Playwright, ONNX, OpenCV, Anthropic)
+  importée au niveau module — elles sont chargées à la demande dans les Acts.
+- Les contrats (`contracts/`) sont la source de vérité ; le code et les SDK s'y conforment.
+- Le dictionnaire d'actions (`core/actions/registry.py`) est l'unique source ; le catalogue du
+  builder en est une projection (pas de duplication).
+- Commentaires sobres, orientés « pourquoi » ; pas d'emoji dans le code ni les logs. Le formatage et
+  le lint sont gérés par ruff (`make format`).
+
+## Tests
+
+- Toute nouvelle logique arrive **avec son test miroir** dans `tests/`. Une contribution n'est prête
+  que si `make check` est vert.
+- La suite doit passer **sans les extras lourds** : un test qui exige `[browser]`, `[vision]` ou
+  `[agent]` se skippe proprement via `pytest.importorskip(...)` et porte le marker correspondant.
+- Les contrats sont gardés par `tests/contracts/` : les garder verts quand un contrat évolue.
+- Structure, markers, fixtures et couverture sont détaillés dans [docs/testing.md](docs/testing.md).
+
+## Exemples exécutables
+
+Une capacité utilisateur arrive avec **au moins un Blueprint d'exemple réellement exécutable**,
+rangé dans `examples/<act>/` et lançable tel quel depuis `aetherius run` comme depuis la Console. Un
+exemple n'est pas un extrait décoratif : il doit tourner.
+
+- Privilégier un endpoint **public et autorisé** pour un exemple **zéro configuration** (ex.
+  `quotes.toscrape.com`, `books.toscrape.com`) : l'utilisateur ouvre la Console, clique Run, ça
+  marche.
+- Si des identifiants sont nécessaires, les passer par `.env` (`AETHERIUS_SECRET_*`, voir
+  [docs/secrets.md](docs/secrets.md)) et le signaler ; ne jamais coder un secret en dur, ni dans un
+  exemple, un test ou une fixture.
+- Un gabarit non exécutable (URLs placeholder, service privé) est marqué comme tel dans sa
+  `description` et ne compte pas comme l'exemple exécutable requis.
+- Les exemples sont validés contre le schéma par la CI (`tests/contracts/`), à n'importe quelle
+  profondeur sous `examples/`.
+
+## Documentation
+
+La doc évolue **avec** le code, dans le même changement — jamais « plus tard ». Un autre
+contributeur doit pouvoir reprendre à partir de la seule doc, sans contexte oral. À chaque
+contribution, mettre à jour :
+
+- la **doc de la partie concernée** (ex. [`docs/acts/<act>.md`](docs/acts/)) : décrire le *comment*
+  et les **limites connues**, pas seulement le *quoi* ; noter les décisions de conception
+  non-évidentes, pour qu'on ne les « corrige » pas par erreur plus tard ;
+- le **statut** dans le [README](README.md), section « État d'avancement » : la source de vérité du
+  jalon atteint et du prochain ;
+- tout **doc transverse** réellement touché (par ex. [docs/console.md](docs/console.md),
+  [docs/secrets.md](docs/secrets.md), [docs/testing.md](docs/testing.md)) ; ne pas dupliquer, mais
+  laisser un pointeur là où c'est utile.
+
+Style : sobre, orienté « pourquoi », sans emoji — comme le code.
+
+### Captures d'écran de la Console
+
+Les images de la doc (`docs/screenshots/*.svg`) sont **générées**, jamais prises à la main. La source
+unique est [`console/screenshots.py`](src/aetherius/console/screenshots.py), qui pilote l'app en
+headless et exporte chaque écran en SVG déterministe (identifiant normalisé, chemin local neutralisé).
+Règles :
+
+- après **toute** évolution d'un écran ou d'un layout Console, exécuter `make screenshots` et commiter
+  le résultat ;
+- pour un **nouvel** écran/interaction, ajouter un scénario dans `screenshots.py` (une fonction de
+  pilotage + une entrée dans `_SHOTS`), régénérer, puis l'intégrer dans la doc concernée ;
+- `make screenshots-check` (garde-fou, rejouable en CI) échoue si les captures committées sont
+  périmées, grâce au déterminisme.
+
+## Intégration continue
+
+La CI (`.github/workflows/ci.yml`) rejoue exactement les cibles `make` sur Python 3.11 et 3.12 et
+compile le SDK TypeScript. Il n'y a pas de logique de test hors du `Makefile` : ce qui passe en local
+passe en CI, et inversement.

aetherius-0.2.0/LICENSE

@@ -0,0 +1,11 @@
+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.

aetherius-0.2.0/Makefile

@@ -0,0 +1,68 @@
+# Aetherius developer tasks.
+# Single source of truth for "how we check the project": the CI (.github/workflows/ci.yml) calls
+# these same targets, so local and CI runs never drift.
+
+.DEFAULT_GOAL := help
+PY := python3
+TS_DIR := sdks/typescript
+
+.PHONY: help install-dev lint format format-check typecheck test test-fast test-browser test-ts check check-all screenshots screenshots-check dist release-check
+
+help: ## List available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## ' $(MAKEFILE_LIST) \
+		| awk 'BEGIN{FS=":.*?## "}{printf "  \033[36m%-14s\033[0m %s\n", $$1, $$2}'
+
+install-dev: ## Install the package with dev tooling (editable)
+	$(PY) -m pip install -e ".[dev]"
+
+lint: ## Lint with Ruff
+	ruff check .
+
+format: ## Format the code with Ruff
+	ruff format .
+
+format-check: ## Check formatting without writing (CI)
+	ruff format --check .
+
+typecheck: ## Strict static typing with mypy
+	mypy
+
+test: ## Run the full Python test suite with coverage
+	pytest --cov=aetherius --cov-report=term-missing
+
+test-fast: ## Run only the fast tests (skip heavy extras and slow tests)
+	pytest -m "not browser and not vision and not agent and not slow"
+
+test-browser: ## Run the browser tests (Act II) against a real Chromium; needs the [browser] extra
+	pytest -m browser
+
+test-ts: ## Typecheck, build and test the TypeScript SDK (unit + a real spawn E2E)
+	npm --prefix $(TS_DIR) install
+	npm --prefix $(TS_DIR) test
+
+screenshots: ## Regenerate the Console SVG screenshots under docs/screenshots/
+	$(PY) -m aetherius.console.screenshots
+
+screenshots-check: ## Fail if the committed screenshots are stale (deterministic; CI guard)
+	@tmp=$$(mktemp -d); \
+	$(PY) -c "import asyncio; from pathlib import Path; from aetherius.console.screenshots import capture_all; asyncio.run(capture_all(Path('$$tmp')))" >/dev/null; \
+	if diff -rq docs/screenshots "$$tmp" >/dev/null; then \
+		echo "screenshots up to date"; rm -rf "$$tmp"; \
+	else \
+		echo "Screenshots are stale — run 'make screenshots' and commit the result."; \
+		diff -rq docs/screenshots "$$tmp" || true; rm -rf "$$tmp"; exit 1; \
+	fi
+
+check: ## Full Python gate: format check, lint, types, tests
+	@$(MAKE) format-check lint typecheck test
+
+check-all: ## Full repository gate: Python + TypeScript SDK
+	@$(MAKE) check test-ts
+
+dist: ## Build the Python distribution (wheel + sdist) into dist/
+	rm -rf dist
+	$(PY) -m build
+
+release-check: ## Build and validate the distribution metadata before uploading (see RELEASING.md)
+	@$(MAKE) dist
+	$(PY) -m twine check dist/*