Hyperfold AI

Catalog Search

Test semantic product search from the command line.

Overview

The hyperfold search command tests how AI agents will discover products in your catalog. Unlike keyword search, semantic search understands intent and context—finding products that match what buyers mean, not just what they type.

# Natural language semantic search
$ hyperfold search "waterproof running shoes for marathon"

> [Vector] Generating query embedding...
> [Search] Querying Vertex AI Vector Search...
> [Results] 8 products found (semantic confidence: 0.91)

RANK  PRODUCT                    CONFIDENCE  PRICE    STOCK
1     AeroRun X2 Waterproof      0.94        $180     847
2     StormRunner GT             0.91        $165     234
3     TrailKing WP               0.88        $142     567
4     All-Weather Racer          0.85        $198     123
5     Marathon Pro Gore-Tex      0.82        $210     89

> [Insight] Results emphasize: waterproof + marathon-optimized
> [Insight] Price range: $142 - $210

Semantic Search

Semantic search understands natural language queries and product "vibes":

# Search by aesthetic/mood ("vibe matching")
$ hyperfold search "cozy autumn vibes sweater"

> [Vibe] Matching aesthetic: warm, comfortable, seasonal
> [Results] 6 products found

RANK  PRODUCT                    VIBE MATCH  COLORS
1     Chunky Knit Cardigan       0.96        rust, cream
2     Wool Blend Pullover        0.93        mustard, brown
3     Cable Knit Turtleneck      0.91        forest green
4     Fleece Hoodie              0.87        burgundy, gray

# Search for specific occasion
$ hyperfold search "elegant jacket for rainy wedding"

> [Context] Formal event + wet weather
> [Results] 5 products found

RANK  PRODUCT                    CONFIDENCE  PRICE
1     Elegant Rain Trench        0.94        $189
2     Waterproof Blazer          0.91        $245
3     All-Weather Sport Coat     0.88        $165

Query Types

Query TypeExample
Functional"shoes for running a marathon in the rain"
Aesthetic"minimalist scandinavian desk lamp"
Occasion"gift for dad who likes golf"
Comparative"something like AirPods but cheaper"
Problem-solving"my back hurts when I sit too long"

Filters & Facets

Combine semantic understanding with structured filters:

# Combine semantic search with filters
$ hyperfold search "running shoes" \
  --filter="price:<=150" \
  --filter="inventory.status:in_stock" \
  --filter="attributes.waterproof:true"

# Filter by category
$ hyperfold search "comfortable shoes" --category="footwear/running"

# Filter by attributes
$ hyperfold search "jacket" \
  --attr="size:M" \
  --attr="color:blue"

# Date-based filters
$ hyperfold search "new arrivals" --filter="created_after:2025-12-01"

# Exclude out of stock
$ hyperfold search "headphones" --in-stock-only

Faceted Search

Get aggregated facets for building filter UIs:

# Get faceted results for filtering UI
$ hyperfold search "shoes" --facets

> [Results] 234 products found

FACETS:
  Category:
    footwear/running     (89)
    footwear/casual      (67)
    footwear/athletic    (45)
    footwear/hiking      (33)

  Price Range:
    $0 - $50             (23)
    $50 - $100           (78)
    $100 - $200          (98)
    $200+                (35)

  Brand:
    Nike                 (56)
    Adidas               (43)
    AeroRun              (38)
    TrailKing            (29)

  Color:
    Black                (87)
    White                (65)
    Blue                 (54)
    Red                  (28)

Output Formats

Choose the output format that fits your workflow:

# Default: human-readable table
$ hyperfold search "laptop"

# JSON output for programmatic use
$ hyperfold search "laptop" --output=json

[
  {
    "product_id": "prod_macbook_pro",
    "name": "MacBook Pro 14\"",
    "confidence": 0.95,
    "price": 1999.00,
    "semantics": {
      "category": "electronics/computers/laptops",
      "usage_context": ["professional", "creative"],
      "visual_tags": ["silver", "slim", "modern"]
    }
  }
]

# IDs only (for piping to other commands)
$ hyperfold search "running shoes" --quiet
prod_aero_x2
prod_storm_gt
prod_trail_king

# Detailed output with all fields
$ hyperfold search "laptop" --verbose

Search Tuning

Fine-tune search behavior for your use case:

# Adjust confidence threshold
$ hyperfold search "blue shirt" --min-confidence=0.8

# Limit results
$ hyperfold search "electronics" --limit=20

# Diversify results (reduce similar items)
$ hyperfold search "shoes" --diversify

# Boost in-stock items
$ hyperfold search "popular items" --boost-in-stock

# Configure search parameters in hyperfold.yaml
search:
  default_limit: 10
  min_confidence: 0.7
  diversify: true
  boost_in_stock: true
  boost_factors:
    inventory_high: 1.1
    recently_added: 1.05
    high_margin: 1.02