/comprendre

The contract. What goes in, what comes out, what happens with and without Haiku.

The guarantee

POST /comprendre always returns a well-formed JSON payload with product matches, corrections, and XAI audit. Default: anthropic=false. Zero external dependencies. The search bar works on day one before any secrets are configured. Pass anthropic=true to opt into LLM extraction for complex queries (requires API key on the EC2).

Request

POST /comprendre
Content-Type: application/json

{
  "text": "feuilete 44 cler",     // required: raw user input, typos welcome
  "factory_id": 3,              // optional, default 3
  "anthropic": false             // optional, default false. Set true to enable Haiku LLM.
}

Field	Type	Default	Description
`text`	string	—	Raw query. Typos, abbreviations, natural language. French glass terms.
`factory_id`	int	3	Monce factory (1, 3, 4, 9, 10). Future per-factory catalog routing.
`anthropic`	bool	false	If true AND API key is on the EC2, complex queries use Claude Haiku for semantic extraction. If false or no key, Snake-only.

Two modes, same shape

anthropic=false (default) Always works

Simple queries: Snake typo_corrector → product_matcher → catalog enrichment. 50-100ms.

Complex queries: Snake models (intent, glass_type, treatment, thickness, gas_type, position) assemble a structured extraction from keyword signals. Snake product_matcher then matches each component. 50-100ms.

Response: "extraction_method": "snake" or "none"

anthropic=true Needs API key

Simple queries: Same as above. LLM is not called for simple queries regardless of the flag.

Complex queries: Claude Haiku parses natural language into structured IGU fields. Snake matches components. 200-500ms.

Response: "extraction_method": "haiku". Falls back to "snake_fallback" if the call fails.

Response — Simple query

// POST /comprendre {"text": "miroir 6mm"}
{
  "factory_id": 3,
  "query_normalisee": "miroir 6mm",
  "corrections": null,
  "resultats": [{"num_article":"55015", "denomination":"Miroir 6mm argent", "confidence":1.0, "method":"snake_sat", "tier":1, "prix_indicatif_m2":16.0, "stock":"disponible"}],
  "composition_detectee": null,
  "resultats_composition": null,
  "autocompletion": ["Miroir 6mm argent"],
  "latency_ms": 54,
  "mode_utilise": "snake_direct",
  "extraction_method": "none",
  "haiku_available": false,
  "xai": {"matching_audit": "...", "intent_audit": "..."}
}

Response — Complex query (anthropic=false, default)

// POST /comprendre {"text": "double vitrage feuillete securite dehors LowE dedans argon 4/16/4"}
{
  "composition_detectee": true,
  "resultats_composition": [{"rang":1, "description":"...", "verre_ext":{...}, "intercalaire":{...}, "gaz":{...}, "verre_int":{...}}],
  "extraction_method": "snake",          // 10 models did the parsing
  "haiku_available": false,
  "xai": {
    // ...
    "snake_signals": {"glass_type":"feuillete", "treatment":"securite", "thickness":"44.2", "gas_type":"argon", "intent":"composition_igu"}
  }
}

Response — Complex query (anthropic=true)

// POST /comprendre {"text": "...", "anthropic": true}
{
  "extraction_method": "haiku",           // Claude Haiku parsed it
  "haiku_available": true,
  "latency_ms": 340,                     // LLM adds ~250ms
  "xai": {"parsing_audit": "LLM extraction: verre_ext=feuillete securite, ..."}
}

Response fields (always present)

Field	Type	Description
`factory_id`	int	Echo of request
`query_normalisee`	string	Typo-corrected query
`corrections`	array\|null	{original, corrige, type} list or null
`resultats`	array\|null	Ranked products (simple) or null (complex)
`composition_detectee`	bool\|null	true for IGU queries
`resultats_composition`	array\|null	IGU components with per-component confidence
`autocompletion`	array\|null	Suggested completions
`latency_ms`	int	Server processing time
`mode_utilise`	string	"snake_direct" or "llm_extraction + snake_matching"
`extraction_method`	string	"none" / "snake" / "haiku" / "snake_fallback"
`haiku_available`	bool	Is the API key configured on this EC2?
`xai`	object	Full audit trail

Environment

# /opt/selfservice/.env on the EC2
# Either one enables Haiku when anthropic=true is passed
ANTHROPIC_API_KEY=sk-ant-...
# or
AWS_BEARER_TOKEN=your-token

Without either key, haiku_available returns false and anthropic=true silently falls back to Snake. No crash, no error.

Behavior matrix

Query	anthropic flag	Key on EC2	extraction_method	Latency
Simple	any	any	`none`	50-100ms
Complex	false	any	`snake`	50-100ms
Complex	true	yes	`haiku`	200-500ms
Complex	true	no	`snake`	50-100ms
Complex	true	yes (fails)	`snake_fallback`	100-200ms

curl cheat sheet

# Default: Snake-only, always works
curl -X POST https://selfservice.aws.monce.ai/comprendre \
  -H "Content-Type: application/json" \
  -d '{"text": "feuilete 44 cler"}'

# Opt into Haiku for complex query
curl -X POST https://selfservice.aws.monce.ai/comprendre \
  -H "Content-Type: application/json" \
  -d '{"text": "double vitrage securite dehors thermique dedans argon", "anthropic": true}'

# Check Haiku availability
curl -s https://selfservice.aws.monce.ai/comprendre \
  -H "Content-Type: application/json" \
  -d '{"text":"test"}' | jq '.haiku_available'