ابنِ مساعد اكتشاف منتجات بالذكاء الاصطناعي

src/
  agent/
    graph.ts
    state.ts
    nodes/
      extract-facts.ts
      retrieve-catalog.ts
      choose-question.ts
      recommend.ts
      validate-response.ts
  catalog/
    products.json
    schema.ts
    retrieve.ts
  api/
    product-discovery.ts
  evals/
    dataset.json
    recommendation.test.ts

npm install @langchain/core @langchain/langgraph @openrouter/ai-sdk-provider ai langsmith zod

# Add your application framework and test runner separately.
# Keep credentials server-side.

# .env.example — placeholders only
OPENROUTER_API_KEY=replace_with_server_side_secret
OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
REFERENCE_MODEL_ID=choose_for_your_own_requirements
LANGSMITH_TRACING=true
LANGSMITH_API_KEY=replace_with_server_side_secret
LANGSMITH_PROJECT=product-discovery-reference

import { createOpenRouter } from "@openrouter/ai-sdk-provider";
import { generateObject } from "ai";
import { z } from "zod";

const ExtractedFactsSchema = z.object({
  facts: z.array(z.object({
    key: z.string().min(1),
    value: z.string().min(1),
    certainty: z.enum(["explicit", "uncertain", "inferred"])
  }))
});

const ModelEnvironment = z.object({
  OPENROUTER_API_KEY: z.string().min(1),
  OPENROUTER_BASE_URL: z.string().url(),
  REFERENCE_MODEL_ID: z.string().min(1)
}).parse(process.env);

export const openRouter = createOpenRouter({
  apiKey: ModelEnvironment.OPENROUTER_API_KEY,
  baseURL: ModelEnvironment.OPENROUTER_BASE_URL
});

// Use structured output for interpretation and explanation only.
// Deterministic retrieval and catalog validation remain authoritative.
export async function extractFacts(prompt: string) {
  return generateObject({
    model: openRouter(ModelEnvironment.REFERENCE_MODEL_ID),
    schema: ExtractedFactsSchema,
    prompt,
    temperature: 0
  });
}

export async function smokeTestReferenceModel() {
  const result = await generateObject({
    model: openRouter(ModelEnvironment.REFERENCE_MODEL_ID),
    schema: z.object({ status: z.literal("ready") }),
    prompt: "Return status=ready. Do not include any other field."
  });
  return result.object.status === "ready";
}

{
  "id": "customer-support-agent",
  "name": "Customer Support Agent",
  "summary": "Answers repeat customer questions",
  "problemsSolved": ["Repeated enquiries"],
  "bestFit": ["Approved support content"],
  "unsuitable": ["No reliable answer source"],
  "capabilities": ["Approved-answer retrieval"],
  "requirements": ["Escalation rules"],
  "related": ["internal-knowledge-agent"]
}

{
  "type": "recommendation",
  "message": "The strongest match is…",
  "products": [{ "id": "customer-support-agent" }],
  "matchReasons": ["Repeated customer questions"],
  "suggestions": ["What data would we need?"]
}

import { z } from "zod";

export const ProductSchema = z.object({
  id: z.string().min(1),
  name: z.string().min(1),
  summary: z.string().min(1),
  problemsSolved: z.array(z.string()),
  bestFit: z.array(z.string()),
  unsuitable: z.array(z.string()),
  capabilities: z.array(z.string()),
  requirements: z.array(z.string()),
  related: z.array(z.string()),
  cta: z.object({ label: z.string(), href: z.string() })
});

export const CatalogSchema = z.array(ProductSchema).min(1);
export type Product = z.infer<typeof ProductSchema>;

import { Annotation } from "@langchain/langgraph";

export type Fact = {
  key: string;
  value: string;
  certainty: "explicit" | "uncertain" | "inferred";
  sourceTurn: number;
};

export const DiscoveryState = Annotation.Root({
  messages: Annotation<Array<{ role: "user" | "assistant"; content: string }>>({
    reducer: (left, right) => left.concat(right), default: () => []
  }),
  facts: Annotation<Record<string, Fact>>({
    reducer: (current, updates) => ({ ...current, ...updates }), default: () => ({})
  }),
  askedFactKeys: Annotation<string[]>({
    reducer: (left, right) => [...new Set([...left, ...right])], default: () => []
  }),
  candidateIds: Annotation<string[]>({ default: () => [] }),
  response: Annotation<DiscoveryResponse | null>({ default: () => null })
});

export function mergeFacts(
  current: Record<string, Fact>,
  extracted: Fact[]
) {
  const next = { ...current };

  for (const fact of extracted) {
    const previous = next[fact.key];
    const visitorCorrectedIt = fact.certainty === "explicit" &&
      previous && previous.value !== fact.value;

    if (!previous || visitorCorrectedIt ||
        (previous.certainty === "inferred" && fact.certainty !== "inferred")) {
      next[fact.key] = fact;
    }
  }

  return next;
}

import catalogJson from "./products.json";
import { CatalogSchema, type Product } from "./schema";

const catalog = CatalogSchema.parse(catalogJson);

export function retrieveProducts(facts: Record<string, Fact>): Product[] {
  const terms = Object.values(facts)
    .filter((fact) => fact.certainty !== "inferred")
    .flatMap((fact) => fact.value.toLowerCase().split(/\s+/));

  return catalog
    .filter((product) => !violatesHardBoundary(product, facts))
    .map((product) => ({
      product,
      score: [...product.problemsSolved, ...product.bestFit, ...product.capabilities]
        .join(" ").toLowerCase().split(/\s+/)
        .filter((word) => terms.includes(word)).length
    }))
    .filter(({ score }) => score > 0)
    .sort((a, b) => b.score - a.score)
    .slice(0, 3)
    .map(({ product }) => product);
}

export function chooseQuestion(
  candidates: Product[],
  facts: Record<string, Fact>,
  askedFactKeys: string[]
) {
  const missing = candidateRequirements(candidates)
    .filter((requirement) => !facts[requirement.key])
    .filter((requirement) => !askedFactKeys.includes(requirement.key))
    .map((requirement) => ({
      ...requirement,
      value: separationScore(requirement, candidates) * requirement.decisionWeight
    }))
    .sort((a, b) => b.value - a.value);

  return missing[0] ?? null; // Ask one question, or move to recommendation.
}

export const DiscoveryResponseSchema = z.object({
  type: z.enum(["question", "recommendation", "comparison", "no_match", "error"]),
  message: z.string().min(1).max(1200),
  products: z.array(ProductSchema.pick({
    id: true, name: true, summary: true, capabilities: true, cta: true
  })).max(3),
  matchReasons: z.array(z.string()).max(6),
  suggestions: z.array(z.string()).max(3)
});

export function validateCatalogClaims(response: DiscoveryResponse, catalog: Product[]) {
  const allowed = new Map(catalog.map((product) => [product.id, product]));
  for (const product of response.products) {
    const source = allowed.get(product.id);
    if (!source || product.name !== source.name) throw new Error("Unsupported product");
    if (product.capabilities.some((item) => !source.capabilities.includes(item))) {
      throw new Error("Unsupported capability");
    }
  }
  return DiscoveryResponseSchema.parse(response);
}

import { END, START, StateGraph } from "@langchain/langgraph";

export const discoveryGraph = new StateGraph(DiscoveryState)
  .addNode("extractFacts", extractFacts)
  .addNode("retrieveCatalog", retrieveCatalog)
  .addNode("chooseQuestion", chooseQuestionNode)
  .addNode("recommend", recommend)
  .addNode("validate", validateResponse)
  .addEdge(START, "extractFacts")
  .addEdge("extractFacts", "retrieveCatalog")
  .addConditionalEdges("retrieveCatalog", routeAfterRetrieval, {
    ask: "chooseQuestion", recommend: "recommend", noMatch: "validate"
  })
  .addEdge("chooseQuestion", "validate")
  .addEdge("recommend", "validate")
  .addEdge("validate", END)
  .compile();

export async function POST(request: Request) {
  try {
    const input = RequestSchema.parse(await request.json());
    const result = await discoveryGraph.invoke({
      messages: [{ role: "user", content: input.message }],
      facts: input.state.facts,
      askedFactKeys: input.state.askedFactKeys
    });

    return Response.json(PublicResultSchema.parse({
      response: result.response,
      state: { facts: result.facts, askedFactKeys: result.askedFactKeys }
    }));
  } catch (error) {
    console.error("product_discovery_request_failed", safeErrorCode(error));
    return Response.json({
      response: deterministicFallback(),
      error: "The assisted response is temporarily unavailable."
    }, { status: 503 });
  }
}

const cases = [
  { input: "We need answers from approved support articles", expected: ["customer-support-agent"] },
  { input: "Actually, this is for employees", correction: { audience: "employees" } },
  { input: "Recommend a payroll system", expectedType: "no_match" }
];

for (const testCase of cases) {
  const result = await discoveryGraph.invoke(toInitialState(testCase.input));
  assertCatalogGrounded(result.response, catalog);
  assertNoRepeatedQuestion(result.askedFactKeys);
  assertExpectedOutcome(result.response, testCase);
  // Record the run in a LangSmith dataset for trace review and regression trends.
}