Snake API is the production endpoint behind snake.aws.monce.ai. It serves
deterministic, auditable, sub-millisecond article matching across 13 production factories
in the FR/ES glass industry. The system replaces what an LLM call would otherwise do
— mapping unstructured catalog text to a canonical article reference — with
a constructive SAT classifier (Snake) layered with a fuzzy fallback and an arbitrator that
merges both signals into a single probability-summing ranking. No GPU, no model API key,
no stochastic sampling. Same query, same answer, every time, with a full reasoning trail.
This document explains why this EC2 exists, what it does, and how the pieces fit together.
A factory's order processing pipeline receives free-form text describing glass articles: OCR'd PDFs, email body extracts, hand-typed quote requests, multilingual specifications. For every line item the system must answer:
Where num_article is the canonical reference in the factory's catalog. Each
factory has its own catalog (1,000–17,000 distinct articles) and its own client list
(400–12,000 distinct buyers). The mapping must be:
/fix wizard) flow back
into snake_learning and trigger targeted rebuilds.An LLM would handle this at 200–2000ms per call, $0.001–$0.01 per call, non-deterministically, with no audit trail, with monthly model deprecations breaking reproducibility. Not viable.
Snake is a SAT-ensembled bucketed multiclass classifier built on the Dana Theorem (Charles Dana, 2024): any indicator function over a finite discrete domain can be encoded as a SAT instance in polynomial time. Decision-tree bucketing reduces this to linear time per training run. Snake constructs a CNF formula directly from data — no backtracking, no exponential search, no NP-hardness penalty.
The algorithm:
oppose() literal that
distinguishes f from at least one member t ∈ C. Take the
disjunction over uncovered subsets to build a clause that excludes f's without
excluding members.Construction cost per layer: O(L · n · b · m) where n = samples, b = bucket size (~125), m = features. Linear in the data. Inference: O(L · clauses_in_bucket) per query, sub-millisecond in practice.
Snake v5.4.6 ships with 30 boolean test types (substring, structural, splits, charclass,
distance, positional, crypto, numeric, exact, affix, vowel ratio) and 7 oppose profiles
that weight them differently per data type. The auto-detector picks balanced
or industrial for the glass tabular domain.
A single Snake call gives us a probability distribution. The endpoint exposes that as a three-tier matching cascade:
| Tier | Method | Threshold | Latency | Purpose |
|---|---|---|---|---|
| 1 | Snake SAT vote | ≥ 80% (configurable) | ~3 ms | Production matches. 100% ≡ exact synonym. |
| 2 | Fuzzy (Levenshtein + bigram) | ≥ 50% | ~1 ms | OCR drift, missing chars, separator variants. |
| 3 | LLM (Claude Haiku) | ≥ 70% | ~400 ms | Semantic last-resort, optional. |
v5.4.6 dropped Snake's built-in synonym_hash as a separate path. The reason:
when a query is a known synonym, SAT returns confidence = 1.0 by construction
(every layer votes for the right class). 100% confidence is the exact-match case.
No separate hash lookup needed. Cleaner cascade, fewer code paths, same behavior.
Snake gives a probability distribution that sums to 1.0. Fuzzy gives a similarity ranking, normalized to sum to 1.0 within the returned pool. Both signals are useful but have different failure modes: Snake misses OCR drift, fuzzy misses semantic intent.
The arbitrator merges them. For a query x with candidates from both sources, define:
where Z is a normalizing constant that restores ΣParb = 1.0. Articles voted by both sources accumulate two contributions and naturally outrank single-source winners. This is the “Both wins” magic visible on /ui: a green-outlined chip dominates a higher single-source confidence.
Full derivation and the proof that Σ = 1.0 holds independent of the relative magnitudes of the two pools: see /math.
An article belongs to a category (verre, intercalaire, remplissage, faconnage, croisillon,
forme, service, misc). We could route by keyword classifier on the OCR'd text. We don't.
Routing is driven by monce_db.articles.type_article_monce — a curated
French taxonomy maintained by the data team. 13 canonical types collapse to 8 field
buckets:
Verre simple, Verre feuilleté, Verre résine, Vitrage isolant → verre Intercalaire → intercalaire Gaz → remplissage Façonnage, Encoche spéciale → faconnage Croisillon, Partie de croisillon → croisillon Forme, Partie de forme → forme Service → service (uncurated) → misc
Why this matters for Spanish factories (F22, F23): their catalogs are in Spanish but
type_article_monce is curated FR. The data team owns the mapping; Snake follows.
Zero contamination of field models from cross-language confusion. Verified clean across
all 13 factories at deploy time.
| Metric | Value |
|---|---|
| Factories live | 13 (FR + ES) |
| Articles indexed | ~60,000 across all factories |
| Synonyms indexed | ~195,000 |
| Clients indexed | ~37,000 |
| Per-query latency (P50) | 3.7 ms |
| Throughput (single instance) | ~260 q/s sustained |
| Glass AGI benchmark | 97.6% |
| Field accuracy (/comprendre) | 85.9% |
| Wall-clock for full rebuild_all | ~9 min 20 s |
Snake API is the deterministic substrate for every glass-industry workflow at Monce. Quote engines call it. OCR pipelines call it. Excel-import flows call it. Hasna's correction wizard writes back to it. The auto-onboarding cron polls it. The observability dashboard graphs it.
If this EC2 goes dark, every downstream tool degrades to LLM fallback at 100x the cost and 100x the latency, with no audit trail. That's the operational case.
The scientific case is in /math: a constructive proof that you don't need an LLM for structured matching. Snake builds the answer; LLMs sample it.
Charles Dana · Monce SAS · snake.aws.monce.ai · deployed 2026-05-20
Co-Authored-By: Claude (Anthropic)