distill-slm 0.1.0__tar.gz

distill_slm-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+.env
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+runs/
+models/
+outputs/
+*.gguf
+*.safetensors
+.cache/
+.DS_Store

distill_slm-0.1.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Abdelilah OURTI
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

distill_slm-0.1.0/NOTICE

@@ -0,0 +1,9 @@
+Distill
+Copyright 2026 Abdelilah OURTI (AI Engineer) - https://neurautech.com
+
+This product includes software developed by Abdelilah OURTI.
+
+Les modeles eleves (Qwen 2.5, Llama 3.2) et les modeles professeurs restent
+soumis a leurs licences respectives. Verifiez les conditions d'utilisation de
+votre fournisseur de LLM professeur avant d'entrainer un modele sur ses sorties
+(voir la commande `distill run --check-terms`).

distill_slm-0.1.0/PKG-INFO

@@ -0,0 +1,415 @@
+Metadata-Version: 2.5
+Name: distill-slm
+Version: 0.1.0
+Summary: Transforme une description de tache et ~20 exemples en un petit modele specialise, evalue et pret pour Ollama, en une seule commande.
+Project-URL: Homepage, https://github.com/Abdelilah04116/distill
+Project-URL: Documentation, https://github.com/Abdelilah04116/distill#readme
+Project-URL: Source, https://github.com/Abdelilah04116/distill
+Project-URL: Article, https://neurautech.com
+Author-email: Abdelilah OURTI <abdelilahourti@gmail.com>
+Maintainer-email: Abdelilah OURTI <abdelilahourti@gmail.com>
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: distillation,fine-tuning,llm,lora,ollama,slm,synthetic-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40
+Requires-Dist: httpx>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: numpy>=1.24
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: all
+Requires-Dist: fastapi>=0.111; extra == 'all'
+Requires-Dist: huggingface-hub>=0.24; extra == 'all'
+Requires-Dist: langgraph-checkpoint-sqlite>=1.0.0; extra == 'all'
+Requires-Dist: langgraph>=0.2.28; extra == 'all'
+Requires-Dist: qdrant-client>=1.9; extra == 'all'
+Requires-Dist: sentence-transformers>=3.0; extra == 'all'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'all'
+Provides-Extra: dedup
+Requires-Dist: qdrant-client>=1.9; extra == 'dedup'
+Requires-Dist: sentence-transformers>=3.0; extra == 'dedup'
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.2; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Requires-Dist: types-pyyaml; extra == 'dev'
+Provides-Extra: graph
+Requires-Dist: langgraph-checkpoint-sqlite>=1.0.0; extra == 'graph'
+Requires-Dist: langgraph>=0.2.28; extra == 'graph'
+Provides-Extra: hub
+Requires-Dist: huggingface-hub>=0.24; extra == 'hub'
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.111; extra == 'serve'
+Requires-Dist: uvicorn[standard]>=0.30; extra == 'serve'
+Provides-Extra: train
+Requires-Dist: accelerate>=0.33; extra == 'train'
+Requires-Dist: bitsandbytes>=0.43; (sys_platform == 'linux') and extra == 'train'
+Requires-Dist: datasets>=2.20; extra == 'train'
+Requires-Dist: peft>=0.12; extra == 'train'
+Requires-Dist: torch>=2.3; extra == 'train'
+Requires-Dist: transformers>=4.44; extra == 'train'
+Requires-Dist: trl>=0.9; extra == 'train'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Distill
+
+**Ton propre modèle, spécialisé, local et 10× moins cher — sans écrire une ligne de code d'entraînement.**
+
+[![Licence](https://img.shields.io/badge/licence-Apache%202.0-blue.svg)](https://github.com/Abdelilah04116/distill/blob/main/LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
+[![CI](https://img.shields.io/github/actions/workflow/status/Abdelilah04116/distill/ci.yml?branch=main&label=CI)](https://github.com/Abdelilah04116/distill/actions/workflows/ci.yml)
+[![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/Abdelilah04116/distill/blob/main/notebooks/distill_colab.ipynb)
+
+Une description de tâche, une vingtaine d'exemples, une commande.
+En sortie : un SLM de 0,5 à 3 milliards de paramètres, évalué, quantifié, et prêt à tourner en local avec Ollama.
+
+</div>
+
+---
+
+## Le problème
+
+Les entreprises paient des LLM géants pour des tâches étroites et répétitives : classer des tickets, extraire des champs, router des demandes. C'est cher, c'est lent, et c'est souvent incompatible avec le RGPD dès que les données partent dans le cloud.
+
+**Distill utilise le gros LLM une seule fois, comme professeur**, pour former un élève qui fait la même tâche en local, pour une fraction du coût.
+
+```bash
+distill run --task examples/email-triage/task.yaml
+# ... génération, critique, entraînement, évaluation, export ...
+ollama run distill-email-triage
+```
+
+## Ce que ça fait, étape par étape
+
+<div align="center">
+  <img src="https://raw.githubusercontent.com/Abdelilah04116/distill/main/docs/architecture-linkedin.png" alt="task.yaml alimente le Générateur, puis le Critique, puis l'Entraînement LoRA, puis l'Évaluateur. Si la cible n'est pas atteinte, l'Améliorateur produit des exemples ciblés et renvoie au Critique, trois fois au maximum. Sinon, le pipeline exporte en GGUF, Ollama et FastAPI." width="880">
+</div>
+
+| Agent | Rôle | Fichier |
+|---|---|---|
+| **Générateur** | 2 000 à 5 000 exemples synthétiques, variés par persona, ton, longueur, fautes, cas limites | [generator.py](https://github.com/Abdelilah04116/distill/blob/main/distill/agents/generator.py) |
+| **Critique** | dédup exacte et sémantique, LLM-as-judge (note 1–5), équilibre des classes, isolation du test set | [critic.py](https://github.com/Abdelilah04116/distill/blob/main/distill/agents/critic.py) |
+| **Entraînement** | LoRA / QLoRA sur un seul GPU, courbe de loss en temps réel, reprise après interruption | [lora_trainer.py](https://github.com/Abdelilah04116/distill/blob/main/distill/training/lora_trainer.py) |
+| **Évaluateur** | élève, professeur et baseline sur le même test set, F1 par classe, latence, coût | [evaluator.py](https://github.com/Abdelilah04116/distill/blob/main/distill/agents/evaluator.py) |
+| **Améliorateur** | lit les erreurs réelles, génère des exemples ciblés, relance (3 fois maximum) | [improver.py](https://github.com/Abdelilah04116/distill/blob/main/distill/agents/improver.py) |
+| **Export** | fusion LoRA, GGUF (Q4_K_M, Q8_0), Modelfile Ollama, API FastAPI, rapport HTML | [export/](https://github.com/Abdelilah04116/distill/tree/main/distill/export/) |
+
+L'orchestration est un graphe LangGraph avec état persisté ([graph.py](https://github.com/Abdelilah04116/distill/blob/main/distill/graph.py)) : un run interrompu reprend là où il s'est arrêté. Si LangGraph n'est pas installé, le même enchaînement tourne en séquentiel.
+
+## Installation
+
+Le paquet n'est pas encore sur PyPI. Pour l'instant, on installe depuis le dépôt :
+
+```bash
+git clone https://github.com/Abdelilah04116/distill && cd distill
+python -m venv .venv && source .venv/bin/activate   # .venv\Scriptsctivate sous Windows
+
+pip install -e .                 # noyau : CLI, agents, évaluation, rapport
+pip install -e ".[all]"          # + LangGraph, Qdrant, embeddings, FastAPI
+pip install -e ".[train]"        # + torch, transformers, peft, trl (GPU)
+```
+
+Pour l'entraînement, Unsloth est optionnel mais recommandé — il est deux fois plus rapide et tient dans moins de VRAM :
+
+```bash
+pip install unsloth
+```
+
+Pour l'export GGUF, il faut llama.cpp compilé :
+
+```bash
+git clone https://github.com/ggerganov/llama.cpp && cd llama.cpp
+cmake -B build && cmake --build build --config Release
+export LLAMA_CPP_DIR=$PWD
+```
+
+## Démarrage rapide
+
+Il faut une clé pour le professeur, ou un modèle local qui en tient lieu.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+**Sans clé et sans budget**, le dépôt fournit une variante entièrement locale, où le professeur est un modèle open-weight servi par Ollama. Rien ne sort de la machine, rien n'est facturé :
+
+```bash
+ollama pull qwen2.5:7b-instruct
+distill run --task examples/email-triage/task.local.yaml
+```
+
+Le parcours complet sur la tâche de démonstration :
+
+```bash
+# 1. Vérifier la tâche et les exemples avant de dépenser quoi que ce soit
+distill validate --task examples/email-triage/task.yaml
+distill estimate --task examples/email-triage/task.yaml
+
+# 2. Lancer le pipeline complet (~4 $ de professeur, plafonné à 6 $)
+distill run --task examples/email-triage/task.yaml
+
+# 3. Essayer le modèle
+ollama run distill-email-triage
+
+# 4. Le servir en HTTP
+distill serve --task examples/email-triage/task.yaml
+curl -X POST localhost:8000/predict -H 'content-type: application/json' \
+     -d '{"input":"Bonjour, je n ai pas recu ma facture de janvier."}'
+```
+
+Autres commandes utiles :
+
+```bash
+distill run --task t.yaml --dry-run          # plan + estimation de coût, sans rien lancer
+distill run --task t.yaml --resume           # reprend le dernier run
+distill run --task t.yaml --skip-generation  # réutilise les exemples déjà produits
+distill watch --task t.yaml                  # suivi en direct : étapes, coût, courbe de loss
+distill review --task t.yaml                 # relecture humaine du test set, exemple par exemple
+distill eval --task t.yaml --backend ollama  # réévalue le modèle quantifié réellement livré
+distill report --task t.yaml                 # régénère le rapport HTML
+distill publish --task t.yaml --repo compte/modele --dry-run   # carte de modèle Hugging Face
+distill cache --clear                        # vide le cache des appels au professeur
+```
+
+## Le fichier `task.yaml`
+
+Tout le pipeline est piloté par un seul fichier. Le minimum vital :
+
+```yaml
+name: email-triage
+description: Tu tries les emails recus par le service client d'une PME francaise.
+language: francais
+
+output_schema:
+  type: object
+  additionalProperties: false
+  required: [categorie, urgence, resume]
+  properties:
+    categorie:
+      type: string
+      enum: [reclamation, facturation, technique, commercial, autre]
+    urgence:
+      type: string
+      enum: [basse, moyenne, haute]
+    resume:
+      type: string
+
+seeds: seeds.jsonl        # 10 à 50 exemples entrée → sortie attendue
+test_set: test_set.jsonl  # écrit à la main, jamais vu à l'entraînement
+
+teacher:
+  provider: anthropic
+  model: claude-opus-5-5
+
+student:
+  model: Qwen/Qwen2.5-1.5B-Instruct
+
+budget:
+  max_examples: 3000
+  max_cost_usd: 5.0       # plafond dur : dépassé, le run s'arrête proprement
+  max_duration_min: 120
+```
+
+L'exemple complet et commenté : [examples/email-triage/task.yaml](https://github.com/Abdelilah04116/distill/blob/main/examples/email-triage/task.yaml).
+
+### Mode 100 % local (RGPD strict)
+
+Aucune donnée ne quitte la machine, ni pendant l'entraînement ni après. Le professeur devient un modèle open-weight servi par vLLM :
+
+```bash
+vllm serve Qwen/Qwen2.5-32B-Instruct --port 8000
+```
+
+```yaml
+teacher:
+  provider: openai_compatible
+  base_url: http://localhost:8000/v1
+  model: Qwen/Qwen2.5-32B-Instruct
+  api_key_env: DISTILL_TEACHER_API_KEY
+  temperature: 0.9
+```
+
+`distill estimate` affiche alors explicitement qu'aucun coût API n'est engagé. C'est aussi la réponse au risque juridique : certaines conditions d'utilisation interdisent d'entraîner un modèle sur les sorties du fournisseur — vérifiez les vôtres, ou passez en local.
+
+## Évaluation : le protocole
+
+La crédibilité du projet tient à un benchmark honnête. Les règles sont appliquées par le code, pas seulement écrites ici :
+
+1. **Le test set est isolé avant toute génération.** Il n'entre jamais dans l'entraînement.
+2. **Double garde contre la fuite.** Dédup exacte par empreinte, puis dédup sémantique par embeddings contre le test set — un exemple généré trop proche d'un exemple de test est jeté, pas utilisé.
+3. **Mêmes entrées, même prompt d'inférence pour tous les modèles.** Le professeur ne bénéficie d'aucun prompt enrichi ([prompts.py](https://github.com/Abdelilah04116/distill/blob/main/distill/prompts.py) est la source unique).
+4. **Une sortie illisible est une erreur**, pas une ligne à ignorer. Un modèle qui répond n'importe quoi une fois sur dix n'obtient pas 100 % sur les neuf autres.
+5. **Une baseline est systématiquement mesurée** : le même petit modèle sans fine-tuning. C'est ce qui prouve l'apport de la distillation plutôt que celui du modèle de base.
+6. **Les échecs sont publiés.** Le rapport HTML contient les erreurs réelles de l'élève, non sélectionnées.
+
+### Comparer les trois tailles d'élève
+
+Le protocole demande de montrer le compromis taille / qualité. Chaque taille est un run complet, avec le même `task.yaml` et le même test set :
+
+```bash
+for m in Qwen/Qwen2.5-0.5B-Instruct Qwen/Qwen2.5-1.5B-Instruct Qwen/Qwen2.5-3B-Instruct; do
+  distill run --task examples/email-triage/task.yaml --student "$m" --skip-generation
+done
+```
+
+`--skip-generation` à partir du deuxième run réutilise le corpus déjà produit : les trois élèves apprennent sur exactement les mêmes données, et la comparaison porte bien sur la taille du modèle. Les trois rapports sont dans `runs/email-triage/`.
+
+### Tableau de résultats
+
+Les chiffres sont produits par votre run, sur votre machine. Le rapport les écrit dans `runs/<tâche>/<run>/report.html` et `metrics.json`.
+
+| Modèle | Exactitude | F1 macro | JSON valide | Latence moy. | Coût / 1 000 req. |
+|---|---|---|---|---|---|
+| LLM professeur | à mesurer | à mesurer | à mesurer | à mesurer | à mesurer |
+| Qwen 1.5B brut | à mesurer | à mesurer | à mesurer | à mesurer | à mesurer |
+| **Distill 1.5B** | à mesurer | à mesurer | à mesurer | à mesurer | à mesurer |
+
+Objectifs de la v1 : **≥ 90 %** du score du professeur, **≥ 10×** moins cher pour 1 000 requêtes, **≥ 5×** plus rapide, le tout en **moins de 2 h sur un GPU**.
+
+> Le coût local n'est pas zéro : il est dérivé du temps GPU réellement occupé, au prix horaire que vous déclarez dans `eval.local_gpu_cost_per_hour`. Comparer un coût API à « gratuit » serait malhonnête.
+
+## Matériel
+
+| Élève | VRAM nécessaire (QLoRA 4 bits) | Où |
+|---|---|---|
+| 0.5B | ~4 Go | Colab / Kaggle gratuit |
+| 1.5B | ~8 Go | Colab / Kaggle gratuit, RTX 3060 |
+| 3B | ~14 Go | RTX 4090, L4, A10 |
+
+Sans GPU local, le notebook [`notebooks/distill_colab.ipynb`](https://github.com/Abdelilah04116/distill/blob/main/notebooks/distill_colab.ipynb) exécute le pipeline complet sur le T4 gratuit de Colab ou Kaggle, compilation de llama.cpp et export GGUF compris. Sinon, tout le reste fonctionne sur CPU — génération, critique, évaluation d'un modèle Ollama, rapport — avec `--skip-training`.
+
+## Structure du dépôt
+
+```
+distill/
+├── distill/
+│   ├── cli.py                  # distill run / eval / export / serve / report
+│   ├── graph.py                # graphe LangGraph + état persisté
+│   ├── config.py               # task.yaml validé par Pydantic
+│   ├── schema.py               # JSON schema → modèle Pydantic
+│   ├── prompts.py              # le prompt d'inférence, défini une seule fois
+│   ├── metrics.py              # F1, exactitude, percentiles (sans sklearn)
+│   ├── costs.py                # tarifs, suivi du budget, coût par 1 000 requêtes
+│   ├── dedup.py                # embeddings + Qdrant, avec repli sans dépendance
+│   ├── agents/                 # generator · critic · evaluator · improver
+│   ├── training/               # lora_trainer (Unsloth ou TRL) · merge
+│   ├── export/                 # gguf · ollama
+│   ├── students/               # runners HF, Ollama, professeur
+│   ├── serving/api.py          # FastAPI /predict
+│   ├── review.py               # relecture humaine du test set
+│   ├── dashboard.py            # distill watch
+│   └── report/                 # rapport HTML autonome
+├── examples/email-triage/      # task.yaml + 24 seeds + 201 exemples de test
+├── notebooks/                  # exécution sur GPU gratuit (Colab / Kaggle)
+├── demo/                       # bande VHS du GIF + plan de tournage
+├── docs/                       # architecture, lancement, article
+├── docker/                     # image de service
+└── tests/
+```
+
+Un run produit un dossier autonome :
+
+```
+runs/email-triage/20261003-141205/
+├── task.resolved.yaml     # la config exacte utilisée
+├── data/                  # generated · train · test · rejected (.jsonl)
+├── train/                 # adaptateur LoRA, checkpoints, loss.jsonl
+├── eval/                  # metrics.json, errors.jsonl
+├── export/                # GGUF + Modelfile
+├── logs/events.jsonl      # journal structuré de toutes les étapes
+└── report.html
+```
+
+## Coûts
+
+Le budget est plafonné dans `task.yaml` et appliqué pendant le run, pas après :
+
+- `distill estimate` affiche une estimation **avant** de dépenser ;
+- chaque appel au professeur est mis en cache sur disque — relancer un run ne repaie pas la génération ;
+- au dépassement du plafond, le run s'arrête proprement, l'état et les données déjà produites sont conservés.
+
+## Limites connues
+
+Il vaut mieux les lire avant de lancer un run que de les découvrir après.
+
+- **Périmètre v1 : tâches textuelles à sortie structurée.** Classification, extraction de champs, routage. Pas de génération de texte long et libre, pas de multimodal, pas de multi-GPU.
+- **Les champs libres ne sont pas notés par égalité de chaînes.** Un résumé est comparé à titre indicatif ; le score porte sur les champs à valeurs fermées. Évaluer un résumé correctement demande un juge, pas un `==`.
+- **Le test set fourni dans `examples/` a été rédigé pour ce dépôt et doit être relu avant de publier des chiffres.** Le protocole parle d'un test set validé à la main : relisez-le, corrigez-le, c'est votre garantie d'honnêteté, pas la nôtre.
+- **La latence du professeur est mesurée sous concurrence** (4 appels en parallèle par défaut), celle de l'élève requête par requête. Le rapport précise la concurrence utilisée.
+- **Unsloth ne tourne pas partout.** Sans lui, le pipeline bascule sur Transformers + PEFT + TRL, plus lent mais équivalent.
+- **Le suivi est un tableau de bord de terminal, pas une interface web.** `distill watch` lit les fichiers que le run écrit de toute façon ; il n'y a ni serveur, ni base, ni historique multi-runs.
+
+## Relire le test set
+
+C'est la seule étape que personne ne peut automatiser à votre place, et celle dont dépendent tous les chiffres. Le pipeline l'outille :
+
+```bash
+distill review --task examples/email-triage/task.yaml --status   # où en est la relecture
+distill review --task examples/email-triage/task.yaml            # valider, corriger, supprimer
+```
+
+Chaque exemple s'affiche avec sa sortie attendue ; vous validez, corrigez ou supprimez. Les champs à valeurs fermées sont proposés sous forme de choix, donc une relecture ne peut pas introduire une valeur hors schéma — et une correction refusée laisse l'exemple intact. L'avancement est écrit à chaque réponse : arrêtez-vous au vingtième, reprenez demain.
+
+**Le test set livré dans `examples/` a été rédigé pour la démonstration, pas validé par un humain.** `distill review` est là pour que vous le fassiez avant de publier le moindre chiffre.
+
+## Suivre un run en cours
+
+Un run dure jusqu'à deux heures. Dans un second terminal :
+
+```bash
+distill watch --task examples/email-triage/task.yaml
+```
+
+Étapes en cours et terminées, nombre d'exemples retenus, ratio courant face au professeur, et la courbe de loss en sparkline. Tout vient de `logs/events.jsonl`, `train/loss.jsonl` et `state.json`, donc le suivi fonctionne aussi après coup (`--once`) et sur un run lancé par quelqu'un d'autre.
+
+## Publier le modèle
+
+```bash
+distill publish --task examples/email-triage/task.yaml --repo compte/distill-email-triage --dry-run
+```
+
+`--dry-run` écrit la carte de modèle dans `export/README.md` sans rien envoyer : relisez-la, puis relancez sans le drapeau. La carte est remplie avec les chiffres de votre run — tableau comparatif, limites connues, répartition des erreurs réelles, prompt système exact. Le GGUF f16 n'est pas envoyé dès lors qu'une version quantifiée existe.
+
+## Développement
+
+```bash
+git clone https://github.com/Abdelilah04116/distill && cd distill
+pip install -e ".[dev,serve]"
+pytest                  # tests unitaires, sans GPU ni réseau
+ruff check distill
+mypy distill
+```
+
+Les tests ne font aucun appel réseau : le professeur est remplacé par un faux déterministe ([tests/conftest.py](https://github.com/Abdelilah04116/distill/blob/main/tests/conftest.py)).
+
+## Aller plus loin
+
+- [notebooks/distill_colab.ipynb](https://github.com/Abdelilah04116/distill/blob/main/notebooks/distill_colab.ipynb) — le pipeline complet sur un GPU gratuit, de l'installation au GGUF téléchargeable.
+- [demo/](https://github.com/Abdelilah04116/distill/tree/main/demo/) — la bande VHS qui produit le GIF, et le plan de tournage de la vidéo de 60 à 90 s.
+- [docs/architecture.mmd](https://github.com/Abdelilah04116/distill/blob/main/docs/architecture.mmd) — le même schéma en Mermaid, pour l'éditer ou l'embarquer ailleurs.
+- [docs/LANCEMENT.md](https://github.com/Abdelilah04116/distill/blob/main/docs/LANCEMENT.md) — checklist de publication et textes des posts.
+- [docs/article.md](https://github.com/Abdelilah04116/distill/blob/main/docs/article.md) — brouillon de l'article technique.
+
+Dans ces trois derniers, les chiffres sont volontairement laissés entre crochets : ne publiez que ce que vous avez mesuré.
+
+## Licence et crédits
+
+Apache 2.0 — voir [LICENSE](https://github.com/Abdelilah04116/distill/blob/main/LICENSE).
+
+Les modèles élèves (Qwen 2.5, Llama 3.2) et les modèles professeurs restent soumis à leurs licences respectives.
+
+Créé par **Abdelilah OURTI**, AI Engineer.