/comprendre

Genesis — tout ce qu'il faut savoir pour utiliser l'endpoint

Ce que fait /comprendre

Le commercial dicte ou tape ses notes de visite terrain. /comprendre les analyse, extrait les signaux commerciaux, classifie la temperature de l'opportunite (Chaud / Tiede / Froid), recommande des produits vitrage, et genere un plan d'action. Le tout en une seule requete.

Comment le prompter

Parlez comme a un collegue. Pas besoin de structure, pas besoin de champs. Dites ce que vous avez vu, entendu, compris pendant la visite.

Plus il y a de signaux dans le texte, plus le scoring est precis. Les signaux cles :

Datastructure IN

{
  "text": "Visite chez Dupont a Marseille, ils refont leur gamme alu, 200 vitrages par mois, le patron veut des echantillons, en marre de leur fournisseur lent.",
  "factory_id": 3,
  "anthropic": false
}

anthropic: false (defaut) → extraction par mots-cles, Snake classifie. Pas d'API key requise.

anthropic: true → Claude Haiku extrait les signaux, Snake classifie. Necessite Bedrock ou ANTHROPIC_API_KEY.

Datastructure OUT

{
  "factory_id": 3,
  "version": "v0.1.0410",
  "latency_ms": 2611,
  "extraction_method": "haiku_bedrock",    // or "haiku_direct" or "keyword_fallback"
  "extraction": {
    "client_info": { "nom": "Dupont", "localisation": "Marseille", "segment": "menuisier_alu", "activite": "mixte" },
    "opportunite": { "volume_mensuel": 200, "insatisfaction_concurrent": true, "engagement_detecte": "demande d'echantillons", "decision_maker_present": true, ... },
    "besoins_techniques": [ { "besoin": "vitrages aluminium", "usage": "renouvellement gamme", "priorite": 1 } ],
    "contraintes": { "budget_m2": { "min": null, "max": null }, "delai_attendu": null },
    "signaux_achat": [ "demande d'echantillons", "insatisfaction fournisseur actuel", ... ],
    "objections_detectees": []
  },
  "mock": false,                           // true if Snake model not loaded
  "opportunite": {
    "temperature": {
      "Prediction": "Chaud",               // Chaud | Tiede | Froid
      "Probability": { "Chaud": 0.953, "Tiede": 0.039, "Froid": 0.008 },
      "method": "snake_sat"                // or "heuristic_fallback"
    },
    "probabilite_closing": 0.78,
    "ca_potentiel_annuel": 105600,
    "ca_calcul": "200 vitrages/mois x 12 mois x 44EUR/m2 moyen = 105KEUR"
  },
  "recommandations_produit": [ ... ],
  "cross_sell": [ ... ],
  "plan_action": [ ... ],
  "arguments_cles": [ ... ],
  "quality_score": 0.87,
  "xai": {
    "temperature_audit": "SAT classification: Chaud (P=0.95). 4 signaux. Audit: ...",
    "matching_audit": "Besoin 1: 'vitrages aluminium' -> ...",
    "budget_audit": "Budget non specifie.",
    "closing_audit": "P(closing) 78%: insatisfaction concurrent, decideur present, ..."
  }
}

Deux modes : avec et sans Haiku

Comparaison sur le meme texte

"Visite chez Dupont a Marseille, ils refont leur gamme alu, 200 vitrages par mois, le patron veut des echantillons, en marre de leur fournisseur actuel qui est lent."

Configuration EC2

Option 1 : Bedrock (recommande en prod)

L'EC2 utilise les credentials AWS pour appeler Claude via Bedrock. Pas besoin de cle API Anthropic.

# /opt/furnitureclassifier/.env
AWS_ACCESS_KEY_ID=AKIA...
AWS_SECRET_ACCESS_KEY=...
AWS_REGION=eu-west-3
SNAKE_MODEL_PATH=/opt/furnitureclassifier/models/opportunity_iter10.json

Le SDK anthropic.AnthropicBedrock() lit ces variables automatiquement. Le modele appele est eu.anthropic.claude-haiku-4-5-20251001-v1:0 (Haiku 4.5 via Bedrock EU).

Option 2 : API directe

# /opt/furnitureclassifier/.env
ANTHROPIC_API_KEY=sk-ant-...
SNAKE_MODEL_PATH=/opt/furnitureclassifier/models/opportunity_iter10.json

Utilise anthropic.Anthropic(api_key=...) avec le modele claude-haiku-4-5-20251001. La cle doit commencer par sk-ant-.

Option 3 : Pas de cle (keyword fallback)

# /opt/furnitureclassifier/.env
SNAKE_MODEL_PATH=/opt/furnitureclassifier/models/opportunity_iter10.json

Aucune cle API configuree. L'extraction tombe en mode keyword. Snake classifie quand meme sur les signaux detectes par regex. /comprendre retourne toujours un payload complet — jamais une 500.

Variable .zshrc / bearer token

Si vous avez un AWS_BEARER_TOKEN dans votre .zshrc, il faut le propager dans le .env du service :

# Sur votre machine locale
echo $AWS_BEARER_TOKEN

# Sur l'EC2, ajouter dans /opt/furnitureclassifier/.env
AWS_BEARER_TOKEN=votre_token

# Puis restart
sudo systemctl restart furnitureclassifier

Note : le SDK Anthropic Bedrock utilise AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY, pas le bearer token directement. Si vous utilisez un bearer token pour un autre service d'auth, il faut le mapper vers les credentials IAM appropriees.

Exemples de requetes

curl

curl -X POST https://furnitureclassifier.aws.monce.ai/comprendre \
  -H "Content-Type: application/json" \
  -d '{"text": "Visite chez Garnier, PVC neuf collectif RT2020, 300 vitrages/mois, echantillons demandes, marre du fournisseur actuel. Budget 38-42 eur/m2.", "factory_id": 3}'

Python (httpx)

import httpx

resp = httpx.post("https://furnitureclassifier.aws.monce.ai/comprendre", json={
    "text": "Visite chez Garnier, PVC neuf collectif RT2020, 300 vitrages/mois, echantillons demandes.",
    "factory_id": 3,
})
data = resp.json()
print(f"Temperature: {data['opportunite']['temperature']['Prediction']}")
print(f"Closing: {data['opportunite']['probabilite_closing']}")
print(f"Method: {data['extraction_method']}")

JavaScript (fetch)

const resp = await fetch('/comprendre', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    text: "Visite chez Garnier, PVC, 300 vitrages/mois, echantillons.",
    factory_id: 3
  })
});
const data = await resp.json();
console.log(data.opportunite.temperature.Prediction);
// "Chaud"

Pipeline complet

POST /comprendre { text: "..." }
        |
        v
 [1] EXTRACTION  ─────────────────────────────────────────
     |                                                     |
     | Haiku disponible?                                   | Non
     | Oui                                                 |
     v                                                     v
  Claude Haiku                                     Regex/keyword
  (Bedrock ou direct)                              (_keyword_extract)
  ~1-3s, haute precision                           <5ms, basique
     |                                                     |
     └──────────── extracted JSON ─────────────────────────┘
                        |
                        v
 [2] FEATURE ENGINEERING  (27 features)
     _extracted_to_snake_features()
     segment, volume, interactions, ratios, grades...
                        |
                        v
 [3] SNAKE SAT CLASSIFICATION
     30 layers, ~600 lookalikes
     Chaud / Tiede / Froid + probabilities
                        |
                        v
 [4] ENRICHMENT
     Product matching, closing probability,
     CA estimation, plan d'action, XAI audit
                        |
                        v
 [5] RESPONSE JSON  (toujours 200, jamais 500)

Garanties

Le seul cas de non-200 est un texte vide. Tout le reste retourne un payload complet avec les informations disponibles.