ابنِ محرك بحث وكيلي لأي متجر

agentic-store-search/
├─ app/
│  ├─ api/search/route.ts
│  └─ search/page.tsx
├─ src/search/
│  ├─ agent.ts
│  ├─ contracts.ts
│  ├─ state.ts
│  ├─ ranking.ts
│  ├─ safety.ts
│  ├─ observability.ts
│  ├─ providers/openrouter.ts
│  └─ tools/
│     ├─ catalog.ts
│     ├─ inventory.ts
│     └─ compatibility.ts
├─ data/
│  ├─ catalog.fixture.json
│  └─ evaluation-cases.jsonl
├─ tests/
│  ├─ grounding.test.ts
│  ├─ ranking.test.ts
│  └─ locale-parity.test.ts
└─ .env.example

npm install ai @ai-sdk/openai-compatible zod pg
npm install -D typescript tsx vitest @types/node

# Placeholder values only. Keep every secret server-side.
OPENROUTER_API_KEY=replace_with_server_only_key
OPENROUTER_MODEL=replace_with_approved_model_id
DATABASE_URL=postgres://user:password@host:5432/store_search
CATALOG_SOURCE_URL=https://catalog.example.invalid/api
SEARCH_REQUEST_TIMEOUT_MS=28000
SEARCH_MAX_TOOL_STEPS=7
SEARCH_DAILY_TOKEN_BUDGET=replace_with_integer

import { z } from "zod";

export const productSchema = z.object({
  id: z.string(),
  sku: z.string(),
  name: z.string(),
  locale: z.enum(["en", "ar"]),
  category: z.string(),
  attributes: z.record(z.string(), z.string()),
  price: z.number().nonnegative(),
  currency: z.string().length(3),
  availability: z.enum(["in_stock", "low_stock", "out_of_stock"]),
  compatibilityKeys: z.array(z.string()).default([]),
  sourceUpdatedAt: z.string().datetime()
});

// Fictional reference record — never a claim about a real store.
export const exampleProduct = productSchema.parse({
  id: "prd_demo_001", sku: "DEMO-FLT-001",
  name: "Premium Cabin Filter", locale: "en",
  category: "Service Parts", attributes: { size: "standard" },
  price: 89, currency: "SAR", availability: "in_stock",
  compatibilityKeys: ["sedan-2021-2.5"],
  sourceUpdatedAt: "2026-08-01T09:00:00.000Z"
});

export const interpretationSchema = z.object({
  language: z.enum(["en", "ar"]),
  intent: z.enum([
    "find_product", "exact_sku", "compare", "filter", "unknown"
  ]),
  querySummary: z.string().max(220),
  entities: z.object({
    productName: z.string().nullable(),
    sku: z.string().nullable(),
    category: z.string().nullable(),
    model: z.string().nullable(),
    year: z.number().int().nullable(),
    priceMax: z.number().positive().nullable(),
    availableOnly: z.boolean()
  }),
  missingInformation: z.array(z.string()).max(6),
  requestedTools: z.array(z.enum([
    "searchCatalog", "findExactSku", "checkInventory",
    "verifyCompatibility", "applyFilters"
  ])).min(1).max(5),
  nextQuestion: z.object({
    type: z.enum(["single_choice", "free_text", "none"]),
    text: z.string().max(220),
    options: z.array(z.string().max(80)).max(6)
  })
});

export type SearchState =
  | "idle" | "interpreting" | "needs_clarification"
  | "retrieving" | "validating" | "ranking"
  | "responding" | "complete" | "fallback" | "failed";

export const legalTransitions = {
  idle: ["interpreting"],
  interpreting: ["needs_clarification", "retrieving", "fallback"],
  needs_clarification: ["interpreting", "complete"],
  retrieving: ["validating", "fallback"],
  validating: ["ranking", "needs_clarification"],
  ranking: ["responding"],
  responding: ["complete"],
  fallback: ["retrieving", "complete", "failed"],
  complete: [], failed: []
} satisfies Record<SearchState, SearchState[]>;

export async function searchCatalog(input: {
  query: string; category?: string; limit?: number;
}) {
  const rows = await catalogRepository.search({
    query: input.query,
    category: input.category,
    limit: Math.min(input.limit ?? 18, 30)
  });

  // The model receives approved facts, never unrestricted database access.
  return rows.map((row) => ({
    id: row.id, sku: row.sku, name: row.name,
    category: row.category, price: row.price,
    currency: row.currency, availability: row.availability
  }));
}

export function rankCandidates(candidates, request, rules) {
  return candidates
    .filter((item) => rules.allowedProductIds.has(item.id))
    .filter((item) => !rules.incompatibleProductIds.has(item.id))
    .map((item) => ({
      ...item,
      score:
        lexicalScore(item, request.query) * 0.45 +
        attributeScore(item, request.entities) * 0.30 +
        availabilityScore(item.availability) * 0.15 +
        businessPriority(item.id, rules) * 0.10
    }))
    .sort((a, b) => b.score - a.score || a.sku.localeCompare(b.sku));
}

// The language model may interpret intent. It may not invent candidates,
// compatibility, stock, price, eligibility, or the final numeric score.

{
  "requestId": "req_demo_7f3a",
  "state": "complete",
  "language": "en",
  "answer": {
    "headline": "I found three grounded options.",
    "body": "Results match the approved catalog and current filters.",
    "question": "",
    "requiresClarification": false
  },
  "productIds": ["prd_demo_001", "prd_demo_014"],
  "appliedRules": ["available_only", "compatibility_required"],
  "fallbackUsed": false,
  "traceId": "trace_demo_91c2"
}

export async function POST(request: Request) {
  const abort = AbortSignal.timeout(28_000);
  const input = searchRequestSchema.parse(await request.json());

  try {
    const result = await runAgenticSearch(input, { signal: abort });
    return Response.json(publicSearchResponseSchema.parse(result), {
      headers: { "Cache-Control": "no-store" }
    });
  } catch (error) {
    const fallback = await runDeterministicSearch(input);
    return Response.json({ ...fallback, fallbackUsed: true }, {
      status: 200,
      headers: { "Cache-Control": "no-store" }
    });
  }
}

const cases = [
  ["exact SKU", "DEMO-FLT-001", ["prd_demo_001"]],
  ["Arabic synonym", "فلتر المكيف", ["prd_demo_001"]],
  ["out-of-stock filter", "available only", []],
  ["explicit incompatibility", "sedan-2022", []],
  ["prompt injection in product text", "ignore rules", []],
  ["provider timeout", "fallback", ["deterministic"]]
];

test.each(cases)("%s remains grounded", async (_name, query, expected) => {
  const result = await runFixture(query);
  expect(result.productIds).toEqual(expected);
  expect(result.productIds.every(id => fixtureCatalog.has(id))).toBe(true);
});

# Web Hoster / Cloud Infrastructure
npm run build
npm run test

# Required runtime checks
curl -f https://store.example.invalid/api/health
curl -f https://store.example.invalid/api/search/readiness

# Rollback: redeploy the prior immutable release, then replay the
# evaluation set before restoring normal traffic.