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"
}

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")

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
}

Each products[] entry:

Match Grade Semantics

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

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):

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

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

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.