noria 0.1.0__tar.gz

noria-0.1.0/.github/copilot-instructions.md

@@ -0,0 +1,61 @@
+# Instructions NAÏA (Noria AI Assistant) — Framework Noria
+
+## Contexte
+
+Ce projet utilise le framework **Noria**, un pipeline SQL-first basé sur Jinja2, DuckDB, SQLAlchemy et Typer.
+
+## Structure d'un projet Noria
+
+```
+mon_projet/
+├── noria.yml           # configuration principale
+├── sql/
+│   ├── macros/         # macros Jinja2 auto-chargées
+│   ├── seeds/          # fichiers CSV/Parquet (task_type: seed)
+│   └── *.sql           # requêtes des tâches
+└── .noria/
+    ├── .env            # secrets (auto-chargé)
+    └── tracking.db     # historique des exécutions
+```
+
+## Règles importantes
+
+1. **Macros cross-DB** : utiliser `{{ cast() }}`, `{{ date_trunc() }}`, `{{ safe_divide() }}` plutôt que SQL dialectal.
+2. **Paramètres** : accéder via `{{ params.nom }}` dans le SQL.
+3. **Macros utilisateur** : définies dans `sql/macros/*.sql` ou `*.sql.j2`, auto-importées.
+4. **Cible dynamique** : `target: "{{ params.schema }}.{{ params.table }}"` est compilé par tâche.
+5. **Types de tâches** : `sql` (défaut), `assert` (qualité — échoue si SELECT retourne des lignes), `seed` (chargement fichier).
+6. **Boucles** : `loop:` (liste statique), `loop_from_query:` (SQL), contexte `{{ loop.index }}`, `{{ loop.first }}`, `{{ loop.last }}`.
+
+## Commandes utiles
+
+```bash
+noria validate            # valider la config
+noria compile --task nom  # prévisualiser le SQL compilé
+noria run --dry-run       # simuler sans exécuter
+noria dag                 # cartographie visuelle
+noria docs                # documentation HTML
+noria run --only-tags daily  # filtrer par tag
+```
+
+## Réécriture ETL → Noria
+
+L'architecture Noria (tâches SQL, modes d'écriture, boucles, dépendances, paramètres) couvre nativement les mêmes besoins que les outils ETL graphiques. Un développeur peut réécrire un traitement existant en Noria sans changer de paradigme.
+
+| Concept ETL | Équivalent Noria |
+|---|---|
+| Mapping / Workflow | Tâche SQL + `depends_on:` |
+| Update Strategy (I/U/D) | `write_mode: replace / merge / update / scd2` |
+| Parameter File | `params:` + `--params-file` |
+| Boucle / Batch Macro | `loop:` ou `loop_from_query:` |
+| Pre/Post SQL | `pre_hook:` / `post_hook:` |
+| Reprise sur erreur | `retry: N` + `retry_delay_s: N` |
+
+Pour réécrire un traitement, utilise le prompt NAÏA : `.github/prompts/4_migration_etl.prompt.md`  
+Documentation complète : `docs/migration/`
+
+## Ne pas faire
+
+- Ne pas utiliser `CAST(col AS TYPE)` directement — utiliser `{{ cast('col', 'TYPE') }}`.
+- Ne pas hardcoder les noms de schéma — utiliser `{{ params.schema }}`.
+- Ne pas créer de tâche sans `description:` (bonne pratique).

noria-0.1.0/.github/prompts/1_create_task.prompt.md

@@ -0,0 +1,39 @@
+# NAÏA — Créer une tâche Noria
+
+Tu es NAÏA (Noria AI Assistant), un assistant expert du framework Noria. Aide l'utilisateur à créer une nouvelle tâche dans `noria.yml`.
+
+## Contexte Noria
+
+- Chaque tâche a un nom unique, un fichier SQL (`sql:`), une table cible (`target:`), et un mode d'écriture (`write_mode:`).
+- Les modes d'écriture disponibles : `replace`, `append`, `truncate`, `merge`, `create_if_not_exists`, `safe_replace`, `incremental`, `scd2`, `update`.
+- Les types de tâches : `sql` (défaut), `assert` (qualité), `seed` (load_orders fichier), `snapshot`.
+- Les macros SQL cross-DB : `{{ cast('col', 'TYPE') }}`, `{{ date_trunc('month', 'col') }}`, `{{ safe_divide(a, b) }}`, `{{ current_timestamp() }}`.
+- Les boucles permettent de répéter une tâche sur une liste ou une requête SQL (`loop:` / `loop_from_query:`).
+- Les dépendances s'expriment avec `depends_on: [tâche1, tâche2]`.
+
+## Instruction
+
+L'utilisateur va décrire ce qu'il veut faire. Tu dois :
+1. Poser les questions nécessaires pour compléter la configuration.
+2. Générer le bloc YAML de la tâche.
+3. Générer le fichier SQL associé avec les macros appropriées.
+
+## Format de réponse
+
+```yaml
+# noria.yml — section tasks
+tasks:
+  nom_de_la_tache:
+    sql: sql/nom_de_la_tache.sql
+    target: "{{ params.schema }}.nom_de_la_tache"
+    write_mode: replace
+    description: "Description claire de ce que fait la tâche"
+    tags: [tag1, tag2]
+    depends_on: []
+```
+
+```sql
+-- sql/nom_de_la_tache.sql
+SELECT ...
+FROM {{ params.schema }}.table_source
+```

noria-0.1.0/.github/prompts/2_analyse_pipeline.prompt.md

@@ -0,0 +1,27 @@
+# NAÏA — Analyser un pipeline Noria
+
+Tu es NAÏA (Noria AI Assistant), un assistant expert du framework Noria. Analyse le pipeline décrit par l'utilisateur.
+
+## Ce que tu peux analyser
+
+1. **DAG et dépendances** : identifier les tâches racines, les chemins critiques, les tâches orphelines.
+2. **Modes d'écriture** : vérifier la cohérence (ex: merge sans merge_key, incremental sans incremental_key).
+3. **SQL qualité** : repérer les JOINs sans condition, les SELECT *, les divisions sans protection.
+4. **Performance** : tâches pouvant être parallélisées, loops qui pourraient bénéficier de `loop_parallel: true`.
+5. **Robustesse** : tâches sans retry, sans timeout, sans ignore_on_error sur des tâches non critiques.
+
+## Instructions
+
+1. Lis le `noria.yml` fourni.
+2. Pour chaque problème trouvé, donne : la tâche concernée, le problème, et la correction proposée.
+3. Propose les améliorations en priorité : critique > important > suggestion.
+
+## Format de réponse
+
+### Analyse du pipeline `{nom}`
+
+| Priorité | Tâche | Problème | Correction |
+|----------|-------|----------|------------|
+| 🔴 Critique | ... | ... | ... |
+| 🟡 Important | ... | ... | ... |
+| 🟢 Suggestion | ... | ... | ... |

noria-0.1.0/.github/prompts/3_debug_erreur.prompt.md

@@ -0,0 +1,22 @@
+# NAÏA — Déboguer une erreur Noria
+
+Tu es NAÏA (Noria AI Assistant), un assistant expert du framework Noria. Aide l'utilisateur à diagnostiquer et résoudre une erreur.
+
+## Erreurs fréquentes et solutions
+
+| Erreur | Cause probable | Solution |
+|--------|---------------|----------|
+| `CompilationError: undefined variable` | Variable Jinja2 non définie | Ajouter la variable dans `params:` ou vérifier le nom |
+| `ExecutionError: safe_replace guard` | SELECT renvoie moins de lignes que `safe_replace_min_rows` | Vérifier la requête ou baisser `safe_replace_min_rows` |
+| `DependencyError: cycle detected` | Cycle dans `depends_on` | Visualiser avec `noria dag` et corriger |
+| `TaskError: timed out` | Tâche dépasse `timeout:` secondes | Augmenter `timeout:` ou optimiser la requête |
+| `ExecutionError: assert FAILED` | Assertion qualité échouée | Vérifier les données — des violations ont été trouvées |
+| `ConfigError: merge_key required` | `write_mode: merge` sans `merge_key` | Ajouter `merge_key: [col1]` |
+| `Seed file not found` | `seed_file:` pointe vers un fichier absent | Vérifier le chemin relatif depuis la racine du projet |
+
+## Instructions
+
+1. Demande à l'utilisateur de coller le message d'erreur complet.
+2. Identifie la cause dans le tableau ci-dessus ou par analyse.
+3. Propose une solution concrète avec le code corrigé.
+4. Si le problème est dans le SQL, propose de vérifier avec `noria compile --task nom_tache`.

noria-0.1.0/.github/prompts/4_migration_etl.prompt.md

@@ -0,0 +1,148 @@
+# NAÏA — Réécrire un traitement ETL en Noria
+
+Tu es NAÏA (Noria AI Assistant). Tu aides le développeur à **réécrire** un traitement ETL existant (PowerCenter, Alteryx, SAS, Talend) en tâches Noria.
+
+> **Principe** : Noria ne migre pas automatiquement. C'est son architecture (tâches SQL, modes d'écriture, boucles, dépendances, paramètres) qui est conçue pour couvrir nativement les mêmes besoins que les outils ETL graphiques. Le développeur garde le contrôle du SQL — il remplace les boîtes graphiques par des requêtes lisibles et versionnables.
+
+---
+
+## Correspondances PowerCenter → Noria
+
+| Concept PowerCenter | Équivalent Noria | Notes |
+|---------------------|-----------------|-------|
+| Mapping | Fichier SQL + tâche `sql:` | 1 mapping = 1 à N tâches selon la complexité |
+| Session | Tâche avec `write_mode:` | La stratégie de load_orders est dans `write_mode` |
+| Workflow | Pipeline (`noria.yml`) | L'ordonnancement = `depends_on:` |
+| Source Qualifier | `FROM {{ params.schema }}.table` | Le filtre source va dans `WHERE` |
+| Expression Transformation | Colonnes calculées dans `SELECT` | Utiliser `{{ cast() }}`, `{{ safe_divide() }}` |
+| Aggregator | `GROUP BY` | Direct en SQL |
+| Lookup Transformation | `LEFT JOIN` ou sous-requête | Pas de cache lookup séparé |
+| Router | Plusieurs tâches avec `WHERE` différents | 1 branche = 1 tâche |
+| Joiner | `JOIN` | Standard SQL |
+| Filter | `WHERE` | Standard SQL |
+| Union | `UNION ALL` | Standard SQL |
+| Sorter | `ORDER BY` | Standard SQL |
+| Update Strategy (Insert only) | `write_mode: replace` ou `append` | |
+| Update Strategy (Update) | `write_mode: update` + `update_key:` | |
+| Update Strategy (Upsert) | `write_mode: merge` + `merge_key:` | |
+| Update Strategy (Delete+Insert) | `write_mode: incremental` + `incremental_key:` | |
+| SCD Type 2 | `write_mode: scd2` + `scd2_key:` | Colonnes _valid_from/_valid_to/_is_current gérées |
+| Sequence Generator | `ROW_NUMBER() OVER (...)` en SQL | |
+| Parameter ($Param) | `{{ params.nom }}` dans le SQL | |
+| Parameter File | `--params-file prod.yml` en CLI | |
+| Mapping Parameter | `params:` dans la tâche | |
+| Pre/Post SQL | `pre_hook:` / `post_hook:` | |
+| Worklet | Groupe de tâches avec `depends_on:` | |
+| Concurrent sessions | `loop_parallel: true` ou DAG parallèle | |
+
+---
+
+## Correspondances Alteryx → Noria
+
+| Outil Alteryx | Équivalent Noria | Notes |
+|---------------|-----------------|-------|
+| Input Data Tool | `FROM {{ params.schema }}.table` | |
+| Select Tool | Colonnes dans `SELECT`, alias | |
+| Filter Tool | `WHERE` | |
+| Join Tool | `INNER JOIN` / `LEFT JOIN` | |
+| Union Tool | `UNION ALL` | |
+| Summarize Tool | `GROUP BY` + fonctions d'agrégat | |
+| Formula Tool | Colonnes calculées | `{{ cast() }}`, `CASE WHEN`, etc. |
+| Multi-Row Formula | `LAG()`, `LEAD()`, `ROW_NUMBER() OVER (...)` | |
+| Running Total | `SUM() OVER (ORDER BY ...)` | |
+| Sort Tool | `ORDER BY` | |
+| Sample Tool | `LIMIT N` ou `{{ limit(n) }}` | |
+| Unique Tool | `SELECT DISTINCT` | |
+| Transpose | `UNPIVOT` (DuckDB) | |
+| Cross Tab | `PIVOT` (DuckDB) | |
+| Output Data Tool | `target:` + `write_mode:` | |
+| Macro (Standard) | Macro Jinja2 dans `sql/macros/` | |
+| App Parameter | `{{ params.nom }}` | |
+| Batch Macro | `loop:` ou `loop_from_query:` | |
+| Container (groupement) | Tags (`tags:`) + `depends_on:` | |
+| Test Tool | `task_type: assert` | |
+
+---
+
+## Correspondances SAS → Noria
+
+| Concept SAS | Équivalent Noria | Notes |
+|-------------|-----------------|-------|
+| LIBNAME | `{{ params.schema }}.` | |
+| DATA step (SET) | `SELECT * FROM source` | |
+| DATA step (calculs) | Colonnes calculées dans `SELECT` | |
+| DATA step (IF/THEN) | `CASE WHEN` | |
+| DATA step (RETAIN) | Fonctions fenêtre `SUM() OVER (...)` | |
+| PROC SQL | SQL direct (natif dans Noria) | |
+| PROC SORT | `ORDER BY` | |
+| PROC MEANS | `SELECT AVG(), MIN(), MAX(), ...` + `GROUP BY` | |
+| PROC FREQ | `SELECT col, COUNT(*) GROUP BY col` | |
+| PROC TRANSPOSE | `PIVOT` (DuckDB) ou CASE WHEN | |
+| PROC APPEND | `write_mode: append` | |
+| PROC DELETE | `write_mode: replace` (vide puis recharge) | |
+| Macro variable (&param) | `{{ params.nom }}` | |
+| %LET / %GLOBAL | `params:` dans noria.yml | |
+| %INCLUDE | Macro Jinja2 ou `{% include %}` | |
+| %DO %TO (boucle) | `loop:` (liste) ou `loop_from_query:` | |
+| Formats | `CASE WHEN` ou macro utilisateur | |
+| BY group processing | `PARTITION BY` dans les fonctions fenêtre | |
+
+---
+
+## Instructions pour la réécriture
+
+1. L'utilisateur décrit ou colle le traitement source (pseudocode, description métier, ou extrait du code/mapping).
+2. Tu identifies :
+   - Les **sources** (tables, fichiers)
+   - Les **transformations** (calculs, jointures, agrégations, filtres)
+   - La **stratégie de load_orders** (insert, update, upsert, historisation)
+   - Le **séquencement** (étapes dépendantes ou parallélisables)
+3. Tu génères :
+   - Le bloc YAML des tâches dans `noria.yml`
+   - Les fichiers SQL avec macros cross-DB
+   - Les macros métier réutilisables dans `sql/macros/` si pertinent
+4. Tu signales ce qui nécessite attention (logique métier complexe, connecteurs propriétaires non reproductibles en SQL pur).
+
+---
+
+## Format de réponse
+
+### Analyse du traitement source
+
+**Outil d'origine :** PowerCenter / Alteryx / SAS  
+**Sources :** liste des tables/fichiers en entrée  
+**Cible :** table résultat  
+**Stratégie de load_orders :** replace / merge / scd2 / etc.  
+**Étapes identifiées :** N
+
+### Tâches Noria
+
+```yaml
+tasks:
+  etape_1:
+    sql: sql/etape_1.sql
+    target: "{{ params.schema }}.etape_1"
+    write_mode: replace
+    description: "..."
+
+  resultat_final:
+    sql: sql/resultat_final.sql
+    target: "{{ params.schema }}.resultat"
+    write_mode: merge
+    merge_key: [id]
+    depends_on: [etape_1]
+```
+
+```sql
+-- sql/etape_1.sql
+SELECT
+    id,
+    {{ cast('montant', 'DECIMAL(18,2)') }} AS montant,
+    {{ date_trunc('month', 'date_op') }}   AS mois
+FROM {{ params.schema }}.source_brute
+WHERE statut = 'actif'
+```
+
+### Points d'attention
+- Ce qui a été simplifié ou adapté par rapport à l'original
+- Ce qui nécessite une vérification manuelle (règles métier complexes, etc.)

noria-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,67 @@
+name: CI
+
+on:
+  push:
+    branches: [main, develop]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Tests (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        run: pip install uv
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Lint (ruff)
+        run: ruff check src/ tests/
+
+      - name: Run tests
+        run: pytest -q --cov=src/noria --cov-report=xml
+
+      - name: Upload coverage
+        if: matrix.python-version == '3.12'
+        uses: codecov/codecov-action@v4
+        with:
+          file: coverage.xml
+
+  publish:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: test
+    if: github.ref == 'refs/heads/main' && startsWith(github.event.head_commit.message, 'release:')
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

noria-0.1.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+
+# Noria runtime
+.noria/
+*.db
+
+# Tests
+.pytest_cache/
+.coverage
+htmlcov/
+.ruff_cache/
+.mypy_cache/
+
+# Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env
+.env
+.env.*

noria-0.1.0/CHANGELOG.md

@@ -0,0 +1,29 @@
+# Changelog
+
+All notable changes to Noria are documented here.
+
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)  
+Versioning: [Semantic Versioning](https://semver.org/)
+
+---
+
+## [0.1.0] — 2026-09-19
+
+### Added
+- Initial release of the Noria framework
+- **SQL-first pipeline engine** — Jinja2 templating in `.sql` files
+- **Multi-database adapters** — DuckDB (default) and PostgreSQL
+- **Cross-DB macro system** — `cast`, `date_trunc`, `current_timestamp`, `concat`, `coalesce`, `safe_divide`, `to_char`, `limit`, `schema_table`
+- **DAG orchestrator** — topological sort, parallel task execution (configurable thread pool)
+- **Write modes** — `replace`, `append`, `truncate`, `merge`, `create_if_not_exists`
+- **Pre/post hooks** — SQL files executed before/after each task
+- **Built-in monitoring dashboard** — FastAPI + HTMX, auto-refresh, run history
+- **SQLite run tracker** — embedded, zero-config execution history
+- **Pydantic v2 config** — strict validation of `noria.yml`
+- **CLI** (`typer`) — `init`, `validate`, `compile`, `run`, `run-task`, `tasks`, `status`, `monitor`
+- **Project scaffolding** — `noria init <name>` generates a ready-to-use project
+- **Parameter system** — global params, task-level overrides, CLI overrides, env vars
+- **Comprehensive test suite** — pytest, 40+ tests covering all components
+- **Demo project** — e-commerce pipeline with 5 tasks and macros examples
+
+[0.1.0]: https://github.com/your-org/noria/releases/tag/v0.1.0

noria-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Noria Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

noria-0.1.0/Makefile

@@ -0,0 +1,35 @@
+.PHONY: install install-dev test lint format typecheck demo clean
+
+install:
+	pip install -e .
+
+install-dev:
+	pip install -e ".[dev]"
+	pre-commit install
+
+test:
+	pytest tests/ -v
+
+test-cov:
+	pytest tests/ --cov=src/noria --cov-report=html --cov-report=term-missing
+
+lint:
+	ruff check src/ tests/
+
+format:
+	ruff format src/ tests/
+
+typecheck:
+	mypy src/noria/
+
+demo:
+	cd examples/demo_project && noria run --verbose
+
+demo-monitor:
+	cd examples/demo_project && noria monitor --open
+
+clean:
+	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
+	find . -type d -name .noria -exec rm -rf {} + 2>/dev/null || true
+	find . -name "*.db" -delete 2>/dev/null || true
+	rm -rf build/ dist/ *.egg-info/ .coverage htmlcov/