/genesis // How /comprendre works

1. What /comprendre does

POST /comprendre is the single entry point for any business interaction. You send raw text — an invoice, an email, a complaint, a quote request, anything — and the controleur:

1. Extracts structured features from the text (via Claude Haiku or regex fallback)
2. Classifies the task type via a trained Snake SAT model (7 classes)
3. Routes to the appropriate sub-classifier in the Monce Suite
4. Returns the full response: prediction, probabilities, routing decision, XAI audit

It always returns a 200 with a viable JSON payload. No 502, no 500. If Haiku is down, it falls back to regex. If Snake fails, it falls back to "autre" with human escalation.

2. How to prompt it

Request

POST /comprendre
Content-Type: application/json

{
  "text": "your raw text here — invoice, email, complaint, anything",
  "factory_id": 3   // optional, defaults to 3. Monce factory ID (1=VIT, 3=Monce, 4=VIP, 9=Euro, 10=TGVI)
}

That's it. Two fields. text is required, factory_id is optional.

What to put in text

You can paste full documents, partial text, structured or unstructured. The longer and more realistic, the better Haiku extracts. But even a few keywords work in regex fallback mode.

curl examples

3. What goes in, what comes out

Input datastructure

{
  "text": string,       // REQUIRED — raw text content
  "factory_id": int     // optional — default 3
}

Output datastructure (always returned)

{
  "factory_id": 3,
  "version": "v0.1.0410",

  "controleur": {
    "tache_detectee": {
      "Prediction": "controle_facture_fournisseur",  // one of 7 task types
      "Probability": {                          // all 7 probabilities, sum to 1.0
        "controle_facture_fournisseur": 0.85,
        "classification_email": 0.05,
        ...
      },
      "method": "snake_sat"
    },
    "classifier_delegue": "procurementclassifier.aws.monce.ai",
    "confiance_routage": 0.85
  },

  "resultat_delegue": { ... },  // downstream classifier result (mocked in v0)

  "decision": {
    "action": "router",                    // router | valider_paiement | bloquer_paiement | escalade_humaine
    "raison": "Interaction routee vers...",
    "escalade": null
  },

  "quality_score": 0.81,      // 0-1, derived from routing confidence
  "latency_ms": 1200,          // end-to-end server time

  "xai": {
    "dispatch_audit": "Snake SAT audit trail...",
    "matching_audit": "...",     // null for non-facture tasks
    "anomaly_audit": "...",      // null for non-facture tasks
    "governance": "Dispatch: Snake SAT model. Features: {...}."
  },

  "extraction_mode": "haiku",  // "haiku" or "regex_fallback"
  "mock_downstream": true      // downstream classifiers are mocked in v0
}

4. Two modes: Haiku vs Regex fallback

Feature mapping comparison

5. EC2 setup: enabling Haiku

The controleur runs on EC2 behind nginx+certbot. Haiku calls go through AWS Bedrock (not direct Anthropic API).

Option A: Bedrock via IAM credentials (current setup)

Option B: Bedrock via instance profile (recommended for prod)

Option C: Direct Anthropic API key

Option D: Your .zshrc AWS_BEARER_TOKEN

Option E: No key at all

It still works. The controleur falls back to regex extraction. You get "extraction_mode": "regex_fallback" in the response. Snake still classifies. Quality is lower but the endpoint never fails.

6. Outcome comparison

Same input, two modes

Input: "FACTURE N FA-2026-0891 GlassCorp SA Trempe 10mm x 200 pcs 4200 EUR Total HT 12950 EUR"

{
  "controleur": {
    "tache_detectee": {
      "Prediction": "controle_facture_fournisseur",
      "Probability": {"controle_facture_fournisseur": 1.0, ...},
      "method": "snake_sat"
    },
    "classifier_delegue": "procurementclassifier.aws.monce.ai",
    "confiance_routage": 1.0
  },
  "resultat_delegue": {
    "type": "controle_facture",
    "fournisseur": {"match": "GlassCorp SA", "confidence": 0.95},
    "lignes": [{"ref_fournisseur": "VS-TMP10", "ref_interne": {...}, "controle_prix": {...}}],
    "controle_global": {"Prediction": "Conforme", ...},
    "verification_arithmetique": {"coherent": true, ...}
  },
  "extraction_mode": "haiku",
  "latency_ms": ~2000
}

{
  "controleur": {
    "tache_detectee": {
      "Prediction": "controle_facture_fournisseur",
      "Probability": {"controle_facture_fournisseur": 0.82, ...},
      "method": "snake_sat"
    },
    "classifier_delegue": "procurementclassifier.aws.monce.ai",
    "confiance_routage": 0.82
  },
  "resultat_delegue": {
    "type": "controle_facture",
    "fournisseur": {"match": "GlassCorp SA", "confidence": 0.95},
    "lignes": [...],       // regex-extracted, may miss some fields
    "controle_global": {...}
  },
  "extraction_mode": "regex_fallback",
  "latency_ms": ~50
}

When does it matter?

7. The 7 task types