eraaa: Era: The Jewelry Assistant That Turns Chat Into Inventory Logic
A close look at the state machine, hybrid retrieval stack, and staff handoff that make this open-source retail assistant feel more like a concierge than a chatbot.
- Era wins by narrowing customer language into constraints instead of trying to sound clever.
- Its real product is a pipeline that joins conversation state, metadata filters, and vector search around one recommendation loop.
- The enhanced stack matters because it adds persistence, analytics, and clean escalation, which are the pieces retail software needs to survive contact with a store.
- Human handoff is treated as part of the design, not as a failure mode.
A chatbot that behaves like a jeweler
Most shopping bots try to answer everything. Era does something sharper: it asks enough questions to turn a vague request into a search problem it can actually solve. In jewelry, that matters more than chat polish. A necklace is not just a product, it is metal, budget, occasion, taste, and often another person's feelings.
That is why Era feels different from a chatbot with a catalog bolted on. It behaves like a merchandiser with memory, not a language model guessing at preference. The useful unit is not a message. It is a structured preference set.
Why jewelry breaks generic chat
Jewelry is a worst-case retail domain for generic chat. A customer may ask for something elegant for a sister's graduation under $200, and every word matters. Miss the metal, the occasion, or the price ceiling, and the recommendation is wrong even if the prose sounds confident.
Era is built around that reality. The repository's product model carries the kind of metadata a human salesperson keeps in their head, such as metal, gemstones, recipient tags, occasion tags, and design type. That means the assistant is not just matching text. It is matching intent against inventory with enough structure to be useful.
How a sentence becomes a shortlist
The repo's conversation engine treats the chat as a finite state machine. It starts by identifying purpose, moves through preference gathering, then shifts into recommendation, or routes to staff when confidence drops. That sounds modest until you see the implication: the model is not allowed to wander. It has to decide what kind of problem this is before it solves it.
Once the assistant has a context object, preference extraction can keep adding detail without losing the thread. One branch pulls semantic similarity from embeddings. The other applies hard metadata filters from PostgreSQL, like budget, metal, gemstone, occasion, and recipient tags. The ranking step then scores the survivors against the current context. Era is useful because it narrows twice, once in language and once in inventory.
The enhanced stack is the real origin story
The codebase reads like a project that grew up in public. The simpler path in `main.py` is the prototype, the route that proves the idea. The enhanced path adds the scaffolding a real store needs, FastAPI, PostgreSQL, ChromaDB, Redis, analytics, and a staff dashboard. That shift matters because retail tools live or die on traceability.
The stack also shows a clear division of labor. `database.py` keeps relational truth in Postgres, `vector_db.py` builds the semantic layer, `rag_system.py` handles generation, and `conversation_engine.py` manages state. `analytics.py` makes the whole thing measurable by tracking signals like handoff rate and confidence levels. Era does not just answer shoppers. It records where the assistant was uncertain and how often a person had to step in.
That is the difference between a demo and an operating system. A demo can impress with a good answer. A retail assistant has to explain why it answered that way, remember what was already learned, and keep working when the answer should come from a human.
Era versus the usual store chatbot
The right comparison is not another jewelry bot. It is the default stack most stores already use.
| Dimension | Generic retail chatbot | Classic faceted search | Era |
|---|---|---|---|
| Memory | Short, fuzzy conversational memory | Usually none | Stateful context across the conversation |
| Retrieval | Broad language generation | Exact filter narrowing | Hybrid semantic search plus metadata filters |
| Precision | Sounds helpful, often guesses | Accurate but rigid | Precise without losing conversational flow |
| Escalation | Often absent | Not designed for it | Clean staff handoff when confidence is low |
| Failure mode | Confident nonsense | Too many clicks or too few results | Stops short and routes to a person |
The handoff is not a fallback
The smartest part of Era may be the least glamorous. It has a `STAFF_HANDOFF_REQUESTED` state, and that is the right move. Retail asks for taste, judgment, and context that a model should not fake. When the assistant cannot narrow the field enough, it should stop pretending and bring in a person.
The analytics layer makes that behavior legible. If handoffs spike, or confidence keeps dipping, the team can tell whether the catalog is thin, the retrieval is weak, or the prompt is asking for too much. That is how a system becomes tunable. It does not just answer. It produces signals the business can act on.
Era's real lesson is simple. Conversational UI only works when it is backed by the discipline of search and the humility of escalation. In jewelry, that combination is not a nice-to-have. It is the product.
