Muriersilk AI Sales Concierge

From brief to system boundary

The brief was not "add a chatbot." It was to create a reusable sales concierge that could answer care questions, help a shopper discover products, remain useful across page changes, and give an operator a clean takeover path.

The public experience is intentionally narrow. It appears only on English locale routes. The customer sees a persistent, enlarged popup that can hold real product cards, not a generic text bubble. Waiting states describe business work such as "Finding suitable pieces" and "Checking care guidance" instead of exposing model or tool jargon.

The safety boundary is equally deliberate. This is a read-only pre-sales surface. It does not reach customer, order, cart, payment, or checkout data. The runtime shares a repository with Medusa, but chatbot-api, chatbot-indexer, Qdrant, and the local model server run as separate services so a retrieval or generation failure does not become a checkout failure.

The first product and runtime designs were committed separately (0259d8d and 5fa56a3) before the contracts and retrieval implementation landed. That sequence matters: it kept product behavior, source-of-truth ownership, and failure boundaries visible before code made them expensive to change.

Retrieval architecture and source-of-truth split

PostgreSQL and Medusa own commercial truth. Qdrant is a rebuildable projection. Product, category, blog, landing-page, and policy changes enter a durable PostgreSQL outbox, wake the indexer through LISTEN/NOTIFY, debounce bursts, and remain recoverable through periodic sweeps.

The first retrieval profile combines dense Nomic Embed Text v1.5 vectors with BM25/FTS sparse evidence and reciprocal rank fusion. The embedding model runs as a Q6_K GGUF through the OpenAI-compatible llama.cpp endpoint, with the correct query and document prefixes. Product retrieval returns at most ten candidates. Knowledge retrieval returns four or five pieces of evidence. The model selects one to three products from the candidate set for each relevant turn.

That last phrase is important. The limit is per turn, not per conversation. A second shopping question can produce a fresh set of one to three cards.

Product and knowledge retrieval can run in the same turn. Pure conversation does not pay that cost. A planner decides whether the turn needs product retrieval, knowledge retrieval, both, or neither.

Why the first UI and mock path failed

The early browser path looked close to complete, but it hid several contract failures.

CopilotKit styles were not mounted correctly. A custom class landed on ChatView rather than the popup shell. The official header used three equal slots that could not hold a multi-line brand treatment. Scoped preflight rules flattened rounded controls. A newly created thread was also treated as an explicit persisted thread, so the welcome state disappeared.

The correction kept the official components, imported the v2 styles at the right boundary, targeted stable data attributes, reorganized the header slots, and applied only local CSS overrides. Thread creation and thread restoration became different states again.

The first mock commerce adapter was more dangerous. It hydrated different product IDs into the same demo scarf, masking real region selection, price, image, and CORS behavior. The browser path moved to real Medusa data with an explicit USD region and the secure local storefront origin. Only then could product cards count as evidence.

A second silent failure appeared when the llama.cpp base URL omitted /v1. Dense retrieval quietly became bm25_only. Readiness now verifies the configured mode and refuses to present a degraded path as hybrid.

Planner, Run A, hydration, and Run B

The interaction contract evolved into two bounded model runs for shopping and evidence turns.

Run A plans the turn, retrieves evidence, and emits stable product IDs. The browser hydrates those IDs from Medusa and renders current image, name, price, currency, and URL. Run B receives the rendered product context and writes the customer-facing explanation and recommendation reasons.

The model never owns the final price, currency, image, or link. This removes stale commercial fields from the generation contract and keeps a product card correct even when catalog data changes after indexing.

The wire path also needed hardening. CopilotKit can omit additionalProperties: false from a tool schema, so the backend applies a safe normalization before validation. The built-in agent can repeat lifecycle events, so the runner deduplicates them without replacing the real error code.

Refresh and retry exposed a race between the two runs and a pending product tool. The frontend now restores pending tool state. The service applies atomic transactions, idempotency, replay, and lease recovery. Commits cd7d700, a1c155a, and 727601c capture the storefront recovery path; the backend race and continuation work progressed through f694e5c, 592fe81, 153f39e, and 1015281.

Follow-up language created a harder problem. "Show me some" or "silk" is not a complete new search. The planner now reads structured conversation state and continues an unfinished task. It does not depend on brittle keyword rules for words such as "one", "it", or "them".

Context and cost boundary

The provider moves to a higher pricing tier above 32k input tokens. Both the planner and final generation therefore pass through a Context Compiler with a hard 28k budget.

The compiled context has four layers:

1. Stable policy and deterministic tool schema, arranged as a cacheable prefix.
2. Recent complete turns, current page, and unfinished tool state.
3. Structured medium-term intent, preferences, constraints, displayed product IDs, accepted or rejected products, and unresolved questions.
4. Product and knowledge evidence for the current turn.

The complete transcript remains durable in PostgreSQL. It is not copied into every provider call.

If a turn exceeds budget, the compiler deduplicates retrieval, truncates knowledge evidence, folds old conversation into structured summary, then compresses product evidence. It does not discard the current customer message, hard constraints, selected product IDs, unfinished tool state, or system policy.

The highest observed compiled input was 25,822 tokens. The highest observed provider prompt was 5,785. A separate cache check sent the same Alibaba-compatible request twice: both requests reported 6,320 prompt tokens, and the second reported 6,314 cached tokens.

Safety and catalog eligibility

One failure made the difference between semantic similarity and a usable retail system obvious. A shopper asked for gloves, but an early dense result included an eye mask and bonnet because all three were close to "silk" and "sensitive skin."

The fix was not another instruction asking the model to try harder. The planner gained a canonical product taxonomy. Qdrant applies product-type and material filters before dense and FTS fusion. A final eligibility guard rejects any selection outside the candidate set and the requested facet. The verified glove + silk request returned four real glove SKUs.

Tenant policy also records catalog truth. Muriersilk sells silk, so the assistant cannot suggest that cotton is an available alternative.

Product descriptions can contain language about eczema or dry hands. Run B may explain material, touch, friction, and intended design. It may not convert that copy into a claim that a product treats eczema, and it may not present a product as medical advice. The two interaction frames above show both sides of that boundary: the planner preserves a misspelled shopping intent, then the answer remains safe when the user asks for a treatment claim.

Chatwoot operations and reuse

Chatwoot Community Edition is the only operator workspace. The team did not build a second admin product.

Operators can search and replay conversations, assign ownership, add internal notes, and take over a customer thread. An embedded Dashboard App adds four operational views: Need to know, Qdrant Index Inspector, Context Inspector, and Prompt Settings.

Administrators can edit tenant business prompts. A save creates an immutable revision that applies to the next logical turn and can be rolled back. Every planner, retrieval, selection, display trace, and Run B generation inside one logical turn remains pinned to the same prompt revision. Normal agents see the setting but cannot change it.

Tool schemas, tool permissions, and platform safety policy are not operator-editable.

The same code supports shared multi-tenant and dedicated deployment profiles. Tenant routing trusts explicit storefront origins and Chatwoot accounts and fails closed when those anchors are missing or ambiguous. Tenant-composite keys, scoped dashboard sessions, atomic webhook receipt and message transitions, and commit-only broadcasts prevent one tenant or operator session from leaking into another.

Verification evidence

The cold local ingest covered 35 active products, 15 categories, and 125 blogs, for 175 entities. The initial retrieval generation produced 866 Qdrant points and 866 indexed vectors with green health.

The canonical Context Pack V2 reconciliation later reported:

• 175 of 175 entities covered
• zero missing and zero unexpected entities
• zero pending outbox items
• zero unresolved dead letters
• acceptingInput=true
• retrievalMode=hybrid

The fresh backend gate passed 70 test suites and 572 tests, followed by build:chatbot. The storefront record passed 56 test files with 860 unit tests, four Playwright browser scenarios, and the production build.

The real Alibaba-compatible provider smoke completed Run A, rendered actual glove cards from Medusa, completed Run B, rendered another product-card turn, and replayed the conversation. The final Context Pack V2 operation is recorded in commit 77561bd.

Honest limits

This is production-shaped work with real local services, real catalog data, a real provider, durable PostgreSQL state, Compose recovery, and browser verification.

It is not evidence that the concierge is deployed on Muriersilk production. Production rollout, live customer traffic, production monitoring, and the operational acceptance period are still pending. The case therefore reports the local end-to-end boundary directly instead of turning implementation maturity into a deployment claim.