hiarthur

# 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

```json
POST /api/agents/search

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

Response:

```json
{
  "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,...