What you’ll build and why
The problem
A business with a structured catalogue and several branches gets product requests in every form: an exact SKU, a product name, a list of attributes, a synonym or a typo, in Arabic or in English, from staff or from customers. Search that only matches words misses many of these, and it cannot tell whether a product fits or which branch has it in stock. Handing the whole decision to a language model does not fix it either. On its own, a model can name a product that is not in the catalogue, ignore a compatibility rule or follow an instruction hidden in product text. Price, stock, compatibility and policy are business rules, and they should not depend on a model’s guess.
What you’ll build
This Build Guide walks you through a reference agentic search engine that reads a natural-language request in either language and turns it into a validated contract. The model chooses from a small allowlist of approved tools for the catalogue, inventory and compatibility. Application code then validates, filters and ranks the results, with stock per branch, and owns eligibility, price, policy and the final score. When a detail is missing or the fit is uncertain, the engine asks one focused question instead of showing false confidence, and a correction starts a new turn that reruns the same deterministic gates. Every product it shows carries an ID that came from a tool result, together with the rules that were applied, so each answer can be traced and audited. If the model provider or the schema check fails, search falls back to deterministic word and attribute matching, and the interface says so.
Who it’s for
The guide is for developers and technical leads at any business with a structured catalogue, a stable ID for every product, stock per branch and written inventory, compatibility and ranking policies. Those are the reference’s assumptions, and every record and name in it is fictional. The named stack is AI SDK for the tool loop, OpenRouter as a server-side model gateway, Zod at every boundary, Postgres for catalogue and search state, and a Web Hoster / Cloud Infrastructure for the application runtime. All of them are educational choices you can replace. The reference deliberately leaves out checkout, payment and order creation, live VIN, identity or customer-profile lookups, any mechanical, medical or safety diagnosis, and Ting’s prompts, private integrations and production scoring.
A reusable search pattern, not a one-branch build
This reference covers the critical path for any business with a structured catalogue and several branches: understand an English or Arabic request from staff or a customer, preserve safe session context, call approved tools, apply deterministic catalogue, stock and branch rules, ask for missing details, and return traceable ranked products. The records are fictional and the architecture is a reference implementation.
Included
- Natural-language product, SKU and attribute search
- English and Arabic request handling
- Grounded catalogue, inventory and compatibility tools
- Deterministic filtering, ranking and clarification
Not included
- Checkout, payment or order creation
- A live VIN, identity or customer-profile service
- A mechanical, medical or safety diagnosis
- Ting prompts, private integrations or production scoring
Interpret, retrieve, validate and rank
The language model converts a staff or customer request into a validated contract and chooses from a small allowlist of tools. Catalogue results are then validated, filtered and ranked by application code, with stock per branch. Every customer-visible product ID must originate in a tool result.
“Front brake pads for a 2021 sedan, 2.5 engine, in Jeddah today.”
Arabic or English- 1Read language, intent and entities
- 2Ask one focused follow-up if context is missing
- 3Call approved catalogue, fitment and stock tools
Enough context? If not, ask, then interpret again
- Eligibility and compatibility
- Deterministic ranking
- Approved part IDs only
- Stock per branch
- A traceable next action
Price, stock, fitment, policy, scoring and privacy stay outside the model.
Source
stateDiagram-v2
[*] --> IDLE
IDLE --> INTERPRETING
INTERPRETING --> NEEDS_CLARIFICATION: missing detail
NEEDS_CLARIFICATION --> INTERPRETING: correction
INTERPRETING --> RETRIEVING: valid contract
RETRIEVING --> VALIDATING
VALIDATING --> RANKING: grounded candidates
VALIDATING --> NEEDS_CLARIFICATION: uncertain fit
RANKING --> RESPONDING
RESPONDING --> COMPLETE
INTERPRETING --> FALLBACK: provider or schema failure
RETRIEVING --> FALLBACK: timeout
FALLBACK --> COMPLETE: deterministic result
FALLBACK --> FAILED: no safe resultNamed reference stack
The reference uses AI SDK for the tool loop, OpenRouter as a server-side model gateway, Zod for every boundary, Postgres for catalogue/search state, and a Web Hoster / Cloud Infrastructure for the application runtime. These are educational choices, not claims about Ting’s production stack.
AI SDK
Tool-loop orchestration, bounded steps and typed model outputs.
OpenRouter
A server-side model gateway with an approved model and explicit timeout, cost and fallback policy.
Zod
Validation for requests, interpretations, tool inputs and public responses.
Postgres
Catalogue mirror, search sessions, policy versions, evaluation cases and audit events.
Web Hoster / Cloud Infrastructure
Application runtime, same-origin API, secret injection, health checks and rollback.
Setup, code, tests and deployment are in the PDF
This page shows the scope, the architecture and the reference stack with its official documentation. The implementation sections listed below are in the full Build Guide PDF: enter your name and mobile number once and it downloads. This device then stays unlocked for every free Ting resource.
- 04 · Project and setupIn the PDF
- 05 · Data contractsIn the PDF
- 06 · Tools and retrievalIn the PDF
- 07 · Rules and rankingIn the PDF
- 08 · Response contractIn the PDF
- 09 · API and fallbackIn the PDF
- 10 · Evaluation and testsIn the PDF
- 11 · Deployment and observabilityIn the PDF
- 12 · Safety checklistIn the PDF