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

Send JSON request bodies only.
Never include extra fields — all request models use extra = "forbid" and will reject unknown keys with 422.
Never invent product locations. Only use location values returned by /api/agents/search.
Preserve conversation_id, logical_search_id, and product.location exactly as returned. Do not trim, modify, or regenerate.
For type: "new", omit conversation_id to let the server generate one.
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

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

HiArthur Product Search and Understanding

HiArthur Product Search and Understanding

Overview

When to Use This Skill

Quick-Start: End-to-End Flow

Step 1 — Start a new search

Step 2 — Fetch more results (pagination)

Step 3 — Deep-dive a product

Search Endpoint — Full Field Reference

New Search (type: "new")

search_query vs trim_query

Continue Search (type: "continue")

Search Response

Match Grade Semantics

Product Endpoint — Deep Analysis

Request

Response

FMEA Structure

Error Handling

Safety Rules

Frontend Handoff

Recommended Agent Usage Pattern

New Search (`type: "new"`)

`search_query` vs `trim_query`

Continue Search (`type: "continue"`)