spb/air Public MIT

1# CLAUDE.md — Projet AIR (Accounting Intermediate Representation)23> **Auteur du projet : Simon-Pierre Boucher — contact@spboucher.ai**4> Ce fichier est la source de vérité pour Claude Code. Lis-le intégralement avant toute action.56---78## 0. RÈGLE ABSOLUE — En-tête obligatoire de chaque fichier910**CHAQUE fichier créé ou modifié dans ce projet DOIT commencer par un en-tête d'auteur.**11Aucune exception : code source, tests, docs, scripts, configs, schémas, notebooks.1213### Formats selon le type de fichier1415**Python (.py)**16```python17# =============================================================================18# Projet : AIR — Accounting Intermediate Representation19# Auteur : Simon-Pierre Boucher20# Contact : contact@spboucher.ai21# Fichier : <nom_du_fichier>22# Description : <une ligne décrivant le rôle du fichier>23# =============================================================================24```2526**TypeScript / JavaScript / Rust / Go / C / Zig (.ts, .js, .rs, .go, .c, .zig)**27```ts28// =============================================================================29// Projet : AIR — Accounting Intermediate Representation30// Auteur : Simon-Pierre Boucher31// Contact : contact@spboucher.ai32// Fichier : <nom_du_fichier>33// Description : <une ligne>34// =============================================================================35```3637**Markdown (.md)**38```markdown39<!--40Projet : AIR — Accounting Intermediate Representation41Auteur : Simon-Pierre Boucher42Contact : contact@spboucher.ai43Fichier : <nom_du_fichier>44-->45```4647**YAML / TOML / config (.yaml, .yml, .toml)**48```yaml49# Projet : AIR — Accounting Intermediate Representation50# Auteur : Simon-Pierre Boucher51# Contact : contact@spboucher.ai52```5354**JSON** : le format JSON n'accepte pas les commentaires. Ajouter une clé au niveau racine :55```json56{ "_author": "Simon-Pierre Boucher <contact@spboucher.ai>", ... }57```5859**SQL (.sql)**60```sql61-- =============================================================================62-- Projet : AIR | Auteur : Simon-Pierre Boucher | contact@spboucher.ai63-- =============================================================================64```6566✅ Avant de terminer toute tâche, vérifie que tous les fichiers touchés portent l'en-tête.67✅ Ajoute un hook / script `scripts/check_headers.py` qui échoue en CI si un fichier n'a pas l'en-tête.6869---7071## 1. RÈGLE ABSOLUE — Recherche web intensive AVANT de coder7273Ce projet touche des domaines où tes connaissances peuvent être incomplètes ou périmées : normes comptables, fiscalité, API des ERP, design de compilateurs. **Tu ne dois JAMAIS deviner.**7475### Protocole de recherche obligatoire7677Avant chaque nouveau module ou décision de design importante :78791. **Fais au minimum 3 à 5 recherches web ciblées** sur le sujet (spécifications, docs officielles, articles récents, RFC, standards existants).802. **Consulte les sources primaires** : documentation officielle des ERP (SAP, QuickBooks, Xero, Odoo, Oracle NetSuite, Sage, Dynamics), sites gouvernementaux (ARC/Revenu Québec pour TPS/TVQ, IRS pour sales tax US), sites des normalisateurs (IFRS Foundation, FASB pour US GAAP, CPA Canada pour ASPE).813. **Documente tes trouvailles** dans `docs/research/<sujet>.md` (avec en-tête auteur) : sources, dates de consultation, résumé, décisions prises.824. **Vérifie l'existant** : avant d'inventer un format, recherche les standards déjà en place (voir §1.1) pour t'en inspirer ou t'y aligner.835. Si une info fiscale ou normative est incertaine ou pourrait avoir changé : **recherche web obligatoire**, jamais de mémoire seule.8485### 1.1 Sujets à rechercher intensivement (checklist de démarrage)8687- [ ] **Standards de données comptables existants** : XBRL / XBRL-GL, ISO 20022, UBL (Universal Business Language), Peppol, OFX, camt.053, EDIFACT, hledger/beancount/ledger-cli (plain text accounting), REA ontology (Resources-Events-Agents), ValueFlows, OpenCorporates schemas.88- [ ] **Architecture LLVM** : structure de l'IR, forme SSA, pass manager, backends, tablegen — pour transposer correctement les concepts.89- [ ] **API ERP** : SAP OData/BAPI/IDoc, QuickBooks Online API (JournalEntry, Invoice, Payment), Xero Accounting API, Odoo XML-RPC/ORM, NetSuite SuiteTalk, Sage Intacct.90- [ ] **Normes comptables** : IFRS (IFRS 15 revenus, IFRS 16 locations, IAS 21 devises), US GAAP (ASC 606, ASC 842), ASPE canadien (chapitres pertinents).91- [ ] **Fiscalité** : TPS/TVQ Canada (taux actuels, règles de lieu de fourniture), sales tax US (nexus, taux par État), TVA UE si pertinent.92- [ ] **Event sourcing & double-entry engines** : Martin Fowler (Accounting Patterns), TigerBeetle, Formance Ledger, Modern Treasury, Increase, Stripe Ledger — architectures de grands ledgers.93- [ ] **Rapprochement bancaire & formats bancaires** : ISO 20022 camt, MT940, Plaid/Flinks API.94- [ ] **Structured outputs LLM** : meilleures pratiques actuelles pour extraction structurée (JSON Schema, tool use, validation).9596⚠️ Les taux de taxes, seuils de capitalisation, et versions d'API **changent**. Toujours vérifier la date des sources et privilégier les documents officiels récents.9798---99100## 2. Vision du projet101102AIR est à la comptabilité ce que LLVM est à la compilation.103104**Problème** : chaque ERP (SAP, Oracle, QuickBooks, Xero, Sage, Odoo, Dynamics) réinvente le même modèle comptable. Les LLM sont excellents pour comprendre ("cette facture = 3 ordinateurs payés par Visa") mais peu fiables pour appliquer des centaines de règles comptables/fiscales sans erreur.105106**Solution** : séparer la *compréhension* (LLM) de l'*application des règles* (compilateur déterministe).107108```109Facture / Email / Banque / POS / API110            ↓111        LLM (extraction)112            ↓113        AIR (événement économique, PAS une écriture)114            ↓115        Passes (validation, taxes, FX, fraude, approbation)116            ↓117        Compilation déterministe (AIC)118            ↓119   Backends : SAP | QuickBooks | Xero | Odoo | IFRS | US GAAP | ASPE120```121122**Principe fondamental** : le LLM ne produit JAMAIS une écriture comptable finale. Il produit uniquement de l'AIR. Le compilateur applique les politiques, normes et taxes de façon déterministe, traçable et testable.123124---125126## 3. Composants de l'écosystème127128| Composant | Analogie LLVM | Rôle |129|---|---|---|130| **AIR** | LLVM IR | Format universel décrivant les événements économiques |131| **AIC** | clang/llc | Compilateur AIR → écritures comptables |132| **ALSL** | TableGen | Langage déclaratif de règles (politiques, taxes, normes) |133| **Backends** | x86/ARM backends | Générateurs SAP, QBO, Xero, Odoo, etc. |134| **Passes** | Optimization passes | Validation, fusion, netting, doublons, conformité |135| **SDK Agents** | libclang | API standard pour agents IA (syscalls comptables) |136| **AIR Kernel** | microkernel | Services : Ledger, Tax, FX, Policy, Period, Audit, Approval, Reporting |137138### 3.1 AIR — le format139140Un événement économique (`EconomicEvent`), pas un journal. Exemple cible :141142```yaml143EconomicEvent:144  id: evt_01H...            # ULID145  type: Sale146  seller: company:acme147  buyer: customer:cust_123148  items:149    - sku: chair-std150      qty: 3151      unit_price: {amount: 333.33, currency: CAD}152  payment:153    method: card.visa154    gross: {amount: 1150.00, currency: CAD}155  delivery: {status: pending, expected: 2026-09-01}156  tax:157    jurisdiction: CA-QC158    codes: [GST, QST]159  meta:160    source: {kind: invoice_pdf, uri: "s3://...", ocr_score: 0.97}161    llm: {model: "...", confidence: 0.93, reasoning_hash: "sha256:..."}162    policy_version: "2026.08"163    timestamps: {ingested: ..., approved: null}164    approver: null165```166167Exigences du format :168- **Schéma formel** (JSON Schema + types Pydantic/TypeScript générés).169- **Forme SSA comptable** : chaque montant a une origine unique et traçable (Invoice → Tax → Payment → FX → Settlement → Write-off). Implémenter un graphe de provenance immuable.170- **Versionné** : `air_version` dans chaque document ; migrations explicites.171- **Immutabilité + diff** : compilation incrémentale — si une facture change, on recompile uniquement le delta (comme Git), avec écritures de contrepassation générées automatiquement.172173### 3.2 AIC — le compilateur174175Pipeline de passes ordonnées :176177```178OCR pass → Classification pass → Tax pass → FX pass →179Fraud pass → Approval pass → Optimization passes → Posting pass180```181182Passes d'optimisation :183- **Fusion** : 50 paiements identiques → 1 batch.184- **Netting** : 100 remboursements → compensation.185- **Reclassement** : Expense → Asset selon politiques (ex. capitalisation > 5000 $).186- **Détection doublons** : hachage + similarité.187- **Invariant permanent** : `Assets = Liabilities + Equity` vérifié après CHAQUE passe. Toute violation = échec de compilation avec diagnostic précis (comme les erreurs clang : localisation, cause, suggestion).188189### 3.3 ALSL — le langage de règles190191Déclaratif, versionné, testable :192193```194policy capitalization_ca:195  when event.type == Purchase and event.amount > 5000 CAD196  then classify as Asset(class: equipment)197198policy tax_quebec:199  when event.jurisdiction == CA-QC200  then apply GST(5%), QST(9.975%)201```202203⚠️ Les taux ci-dessus sont des exemples — **vérifie les taux actuels par recherche web** avant de les coder, et ne les code JAMAIS en dur dans le moteur : ils vivent dans les policies ALSL versionnées.204205### 3.4 Backends206207Chaque backend implémente une interface commune `Backend`:208- `capabilities()` — ce que la cible supporte209- `compile(journal: CompiledJournal) -> TargetPayload`210- `post(payload) -> PostingReceipt`211- `reverse(receipt) -> ReversalReceipt`212213Ordre de développement : **1) Backend générique CSV/journal**, 2) QuickBooks Online (API la plus accessible), 3) Xero, 4) Odoo, 5) SAP (le plus complexe — recherche approfondie requise sur OData/BAPI).214215### 3.5 SDK Agents — les "syscalls"216217Les agents IA n'accèdent JAMAIS au grand livre directement. API exclusive :218219```220CreateEconomicEvent() | Validate() | Compile() | Post() | Reverse()221Merge() | ClosePeriod() | Reconcile() | GenerateReport()222```223224Chaque appel est journalisé (audit log append-only, hash-chaîné).225226---227228## 4. Architecture technique229230### Stack recommandée (à valider par recherche)231- **Cœur (AIR + AIC + passes)** : Rust (fiabilité, typage fort) OU Python typé strict (vitesse de dev). Décision à documenter dans `docs/adr/0001-language.md` après recherche comparative.232- **Schémas** : JSON Schema comme source de vérité → génération de types Rust/Python/TS.233- **Montants** : JAMAIS de float. Décimal fixe (rust_decimal / Python Decimal), arrondi banker's rounding documenté par juridiction (à vérifier par recherche : règles d'arrondi TPS/TVQ).234- **Stockage** : event store append-only (PostgreSQL) + projections.235- **ALSL** : parser dédié (pest/lark) ; commencer par un sous-ensemble YAML avant le DSL complet.236237### Structure du dépôt238239```240air/241├── CLAUDE.md242├── README.md243├── docs/244│   ├── adr/                 # Architecture Decision Records245│   ├── research/            # Résultats de recherches web (OBLIGATOIRE)246│   └── spec/                # Spécification formelle AIR / ALSL247├── schemas/                 # JSON Schemas versionnés248├── core/                    # AIR types + graphe de provenance249├── aic/                     # Compilateur + pass manager250│   └── passes/251├── alsl/                    # Parser + évaluateur de règles252├── backends/253│   ├── generic_csv/254│   ├── quickbooks/255│   ├── xero/256│   └── odoo/257├── kernel/                  # Services (ledger, tax, fx, policy, audit...)258├── sdk/                     # SDK agents (syscalls)259├── ingestion/               # OCR + extraction LLM → AIR260├── tests/261│   ├── golden/              # Cas dorés : AIR → écritures attendues262│   ├── property/            # Property-based (invariant bilan)263│   └── fixtures/            # Factures réelles anonymisées264└── scripts/265    └── check_headers.py     # Vérifie les en-têtes auteur266```267268---269270## 5. Exigences de qualité non négociables2712721. **Déterminisme** : même AIR + mêmes policies = mêmes écritures, toujours. Aucun appel LLM dans le compilateur.2732. **Invariant comptable** : partie double vérifiée à chaque étape ; property-based testing (hypothesis/proptest) sur `Assets = Liabilities + Equity`.2743. **Traçabilité totale** : de chaque ligne d'écriture, on remonte à l'événement source, au document, au score OCR/LLM, à la version de policy, à l'approbateur.2754. **Golden tests** : chaque fonctionnalité comptable = cas dorés validés contre des exemples de la littérature comptable (trouvés par recherche web, sources citées).2765. **Diagnostics de qualité compilateur** : erreurs précises, localisées, avec suggestions.2776. **Aucun taux/seuil en dur** : tout paramètre fiscal ou de politique vit dans ALSL.2787. **En-têtes auteur** partout (voir §0), vérifiés en CI.279280---281282## 6. Plan de développement par phases283284**Phase 0 — Recherche (docs/research/)** : compléter la checklist §1.1, produire un rapport par sujet, rédiger les ADR fondateurs (langage, alignement ou non avec XBRL-GL/UBL/REA, modèle de montants).285286**Phase 1 — Cœur** : schéma AIR v0.1, types, graphe de provenance, invariant bilan, backend CSV générique, 20 golden tests (vente simple, achat, taxes QC, FX, remboursement).287288**Phase 2 — Compilateur** : pass manager, passes Tax (CA-QC d'abord) / FX / Validation, ALSL v0.1 (YAML), compilation incrémentale (diff + reversal).289290**Phase 3 — Backend réel** : QuickBooks Online (sandbox), OAuth, idempotence, Post/Reverse.291292**Phase 4 — Ingestion** : PDF → extraction structurée LLM → AIR, avec scores de confiance et file d'approbation humaine sous seuil.293294**Phase 5 — Kernel + SDK** : services, syscalls, audit log hash-chaîné, agent de démonstration.295296**Phase 6 — Optimisations** : fusion, netting, doublons, rapprochement bancaire (camt.053/MT940).297298---299300## 7. Workflow de travail attendu de Claude301302À chaque session :3031. Relire ce CLAUDE.md.3042. Identifier la tâche → **recherche web d'abord** si le sujet touche normes, taxes, API externes, ou standards.3053. Consigner la recherche dans `docs/research/`.3064. Écrire les tests avant/avec le code (golden + property).3075. Coder avec en-têtes auteur.3086. Lancer `scripts/check_headers.py` + suite de tests.3097. Mettre à jour la doc/ADR si une décision de design a été prise.310311### Interdits312- ❌ Coder une règle fiscale de mémoire sans source web vérifiée et citée.313- ❌ Utiliser des floats pour des montants.314- ❌ Laisser le LLM produire des écritures finales.315- ❌ Créer un fichier sans l'en-tête Simon-Pierre Boucher / contact@spboucher.ai.316- ❌ Casser l'invariant de la partie double, même temporairement.317318---319320*Fin du CLAUDE.md — Projet AIR — Simon-Pierre Boucher — contact@spboucher.ai*321