HiArthur Product Search and Understanding

Overview

Two-endpoint API for intelligent product search and deep product analysis. Products are sourced from Amazon, but results go far beyond what Amazon returns directly — every product is analyzed through a multi-stage pipeline combining computer vision, LLMs, and symbolic reasoning to evaluate how well each product actually matches what the user is looking for and where it's likely to disappoint.

• POST https://hiarthur.com/api/agents/search — find products matching a query. Each result is graded for fit against the user's requirements using vision + language models, not just keyword matching.
• POST https://hiarthur.com/api/agents/product — deep-dive one product for failure-mode analysis (FMEA), feature summary, and review synthesis. Uses LLM reasoning over product details and images to surface likely disappointments.

Base URL: https://hiarthur.com/api

Results can optionally be handed off to a GUI (e.g. https://hiarthur.com/c/<conversation_id> or https://hiarthur.com/product/f7e2a9c1b3d4) where users can browse results visually and continue the conversation interactively.

---

When to Use This Skill

Use this skill when you need to:

• Find products that match detailed user requirements
• Evaluate trade-offs between competing products
• Identify likely durability or design problems
• Understand why a product might disappoint buyers
• Compare products beyond simple ratings or keywords

Quick-Start: End-to-End Flow

Step 1 — Start a new search

POST /api/agents/search

{
  "type": "new",
  "search_query": "noise cancelling headphones for travel",
  "search_top_brands": true
}

Response:

{
  "conversation_id": "a1b2c3d4-...",
  "logical_search_id": "ls_abc123",
  "products": [
    {
      "product": {
        "description": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
        "brand": "Sony",
        "location": "product/f7e2a9c1b3d4",
        "price": 328.0,
        "rating": 4.6,
        "reviews_count": 12450
      },
      "explainer": "Strong noise canceling with long battery life, well suited for travel.",
      "match_grade": "Excellent"
    }
  ],
  "can_fetch_more": true
}

Step 2 — Fetch more results (pagination)

Reuse conversation_id and logical_search_id exactly as returned.

POST /api/agents/search

{
  "type": "continue",
  "conversation_id": "a1b2c3d4-...",
  "logical_search_id": "ls_abc123"
}

Repeat while can_fetch_more is true. A continue response with products: [] is valid (more may come on the next continue). Stop when can_fetch_more is false.

Step 3 — Deep-dive a product

Use a product.location value exactly as returned by search.

POST /api/agents/product

{
  "location": "product/f7e2a9c1b3d4"
}

Response:

{
  "fmea": {
    "unmitigated_failure_modes": [
      {
        "failure_name": "Headband cushion flattens over time",
        "likelihood": {
          "level": "medium",
          "reasoning": "Foam compression builds with daily wear, so most regular users will notice reduced comfort within months."
        },
        "impact": "annoying",
        "timeline": "within_a_year",
        "summary": "The headband padding can compress with regular use, making the headphones less comfortable for long listening sessions.",
        "evidence": [
          "Foam headband cushion visible in images",
          "No mention of memory foam or replaceable pads"
        ]
      }
    ],
    "mitigated_failure_modes": [
      {
        "failure_name": "Poor noise canceling on wind",
        "ownership_experience": "Multipoint wind-noise reduction",
        "reasoning": "Multiple microphones and adaptive ANC algorithms reduce wind interference compared to single-mic designs.",
        "evidence": [
          "Adaptive ANC with multiple external microphones",
          "Wind noise reduction mode listed in features"
        ]
      }
    ],
    "quality_summary": "These headphones prioritize audio quality and noise canceling performance. Most disappointment comes from comfort degradation over time rather than core functionality."
  },
  "features_summary": "Paragraph summarizing key product features based on listing data.",
  "reviews_summary": "Paragraph synthesizing themes and patterns from customer reviews."
}

---

Search Endpoint — Full Field Reference

New Search (type: "new")

Full example with all optional fields:

{
  "type": "new",
  "search_query": "noise cancelling headphones for travel",
  "search_top_brands": true,
  "trim_query": "Over-ear wireless headphones with active noise canceling and long battery life for airplane use",
  "brands": ["Sony", "Bose"],
  "search_filters": {
    "price_min": 100,
    "price_max": 400,
    "rating_min": 4.0,
    "reviews_min": 500
  },
  "search_sort": "relevance"
}

Field	Type	Required	Default	Description
type	"new"	yes	—	Discriminator.
search_query	string	yes	—	Broad retrieval query sent to the product catalog. Should be precise, user-intent-aligned, and include all key attributes (color, size, material, use case, gender).
search_top_brands	boolean	yes	—	When true, restricts results to recognized top brands in the category. Default to true for electronics, appliances, clothing, tools, beauty, home/kitchen. Default to false for books, media.
trim_query	string	no	same as search_query	Similarity-trimming query. After retrieval, products with low similarity to this string are removed. Should be a fluent, attribute-rich, natural-language description optimized for matching product titles and images. More descriptive than search_query. See examples below.
conversation_id	UUID string	no	server-generated	Omit to let the server create a new conversation. Supply to attach this search to an existing conversation.
brands	string[]	no	[]	Explicit brand-name constraints. Only populate when the user names specific brands. Use canonical names with proper capitalization (e.g., ["Nike", "Adidas"]).
search_filters	object	no	null	All sub-fields optional and nullable: price_min (number), price_max (number), rating_min (number), reviews_min (integer). No extra keys allowed.
search_sort	enum string	no	null	"relevance", "price_low", "price_high", or "best_sellers".

search_query vs trim_query

search_query drives broad catalog retrieval. trim_query is applied after retrieval as a similarity filter — products with low similarity to it are removed.

trim_query should read like a grounded, attribute-rich product description:

• "A men's sleeveless hooded vest made of shiny metallic fabric with a full zipper front."
• "A 12-pack of chocolate-flavored protein shakes, each bottle containing 20 grams of protein."
• "A thick purple yoga mat made of dense non-slip foam, measuring one inch in thickness."
• "A 10-inch nonstick frying pan with a ceramic coating and induction-compatible base."
• "Wireless Bluetooth 5.3 earbuds with noise-canceling features and at least 40 hours of battery life."

When omitted, trim_query defaults to search_query. Only set it when you have a more descriptive version.

Continue Search (type: "continue")

Field	Type	Required	Description
type	"continue"	yes	Discriminator.
conversation_id	UUID string	yes	Exact value from the prior search response.
logical_search_id	string	yes	Exact value from the prior search response.

Search Response

{
  "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "logical_search_id": "ls_abc123",
  "products": [
    {
      "product": {
        "description": "Sony WH-1000XM5 Wireless Noise Canceling Headphones",
        "brand": "Sony",
        "location": "product/f7e2a9c1b3d4",
        "price": 328.0,
        "rating": 4.6,
        "reviews_count": 12450
      },
      "explainer": "Strong noise canceling with long battery life, well suited for travel.",
      "match_grade": "Excellent"
    }
  ],
  "can_fetch_more": true
}

Field	Type	Description
conversation_id	string	Stable conversation identifier. Reuse for continue requests and frontend handoff.
logical_search_id	string	Identifies this search session for pagination. Reuse for continue requests.
products	array	ProductWithExplainer objects. May be empty (valid on continue).
can_fetch_more	boolean	The only pagination signal. true = more results available via continue.

Each products[] entry:

Field	Type	Description
product.description	string	Product title/description.
product.brand	string or null	Brand name if known.
product.location	string	Opaque product identifier (format: product/<cache_key>). Preserve exactly for /agents/product calls and frontend handoff.
product.price	number or null	Price in dollars.
product.rating	number or null	Star rating (e.g., 4.6).
product.reviews_count	integer or null	Number of customer reviews.
explainer	string	Human-readable rationale for the fit grade. May be empty.
match_grade	string	Canonical fit label. One of: "Excellent", "Good", "Partial", "Low".

Match Grade Semantics

Grade	Meaning
Excellent	All user requirements confirmed by evidence. All numeric constraints pass.
Good	All critical requirements confirmed, none contraindicated. Constraints pass or pass within tolerance.
Partial	At least one critical requirement is unconfirmed, missing, or contraindicated, OR some numeric constraints fail.
Low	Any requirement is contraindicated, OR no requirements could be evaluated.

---

Product Endpoint — Deep Analysis

Request

{ "location": "product/<cache_key>" }

Use only a location value returned by /api/agents/search. Never invent locations. Request model uses extra = "forbid".

Response

Field	Type	Description
fmea	object	Failure Mode and Effects Analysis. See structure below.
features_summary	string	Paragraph summarizing key product features.
reviews_summary	string	Paragraph synthesizing themes from customer reviews.

FMEA Structure

The fmea object describes how a product is likely to disappoint a buyer over time, framed as failure modes rather than feature ratings.

unmitigated_failure_modes — array, typically 3 entries, ordered by expected regret impact (likelihood x impact x immediacy):

Field	Type	Possible Values
failure_name	string	Concise description of what goes wrong.
likelihood.level	string	"low", "medium", "high"
likelihood.reasoning	string	Product-specific probability rationale with expected incidence.
impact	string	"cosmetic", "annoying", "performance_loss", "unusable"
timeline	string	"immediate", "within_a_year", "over_a_year"
summary	string	1–2 sentences on real-use customer impact.
evidence	string[]	Concrete cues from listing, specs, or images.

mitigated_failure_modes — array, 0–3 entries: common category failures that the product's design intentionally addresses.

Field	Type	Description
failure_name	string	The common failure that is unlikely here.
ownership_experience	string	Short positive reframe (max ~6 words, e.g., "Long cord with easy rewind").
reasoning	string	What design choices reduce this risk.
evidence	string[]	Concrete cues from listing.

quality_summary — string: A calm, informed paragraph synthesizing dominant risks, design priorities, disappointment timeline, fixability, and who the product is likely to satisfy vs. frustrate.

---

Error Handling

Status	Endpoint	Cause	Suggested Action
400	/agents/product	Invalid location format (empty, malformed, or contains path separators).	Verify the location was copied verbatim from a search result.
404	/agents/search (continue)	logical_search_id not found or expired from cache.	Start a new search with type: "new".
404	/agents/product	Product cache key or destination not found. May have expired.	Re-run search to get a fresh location.
422	Both	Schema validation failure: missing required field, wrong type, or extra key present.	Fix request body. All request models use extra = "forbid".
500	Both	Unhandled internal error.	Retry once with backoff. If persistent, report as a service issue.
502	/agents/search	Search backend did not return a final result, or returned an invalid payload.	Retry once. If persistent, the upstream search service may be degraded.

---

Safety Rules

1. Send JSON request bodies only.
2. Never include extra fields — all request models use extra = "forbid" and will reject unknown keys with 422.
3. Never invent product locations. Only use location values returned by /api/agents/search.
4. Preserve conversation_id, logical_search_id, and product.location exactly as returned. Do not trim, modify, or regenerate.
5. For type: "new", omit conversation_id to let the server generate one.
6. All endpoints use the base URL https://hiarthur.com/api.

---

Frontend Handoff

• Open c/<conversation_id> in a browser to resume that conversation within a GUI.
• Open a returned product location in a browser to open the product information and see product images in a GUI.
• Keep all backend-derived IDs and locations unchanged during handoff URL construction.

Recommended Agent Usage Pattern

1. Call /agents/search with type: "new".
2. Inspect the returned products.
3. If more candidates are needed, call /agents/search with type: "continue".
4. When a specific product requires deeper analysis, call /agents/product.