Price Comparison Shopping Agent

naftiko: 1.0.0-alpha2
info:
  label: Price Comparison Shopping Agent
  description: |
    Composed workflow capability for a price-comparison shopping agent on top of
    BuyWhere. Performs keyword search, then side-by-side comparison of the top
    candidates, returning a ranked best-value answer ready for an LLM to summarize.
  tags:
    - BuyWhere
    - Shopping
    - Price Comparison
    - AI Agents
    - SEA
    - Southeast Asia
    - MCP
  created: '2026-05-16'
  modified: '2026-05-16'
capability:
  consumes:
    - ref: shared/buywhere-product-catalog-api.yaml
  exposes:
    - type: mcp
      port: 9090
      namespace: shopping-agent-mcp
      transport: http
      description: |
        Workflow MCP tools that compose multiple BuyWhere operations into one agent step.
      tools:
        - name: find_best_value
          description: |
            Search for a product, then compare the top N results and return the best-value
            option ranked by normalized USD price (or specified currency).
          hints: { readOnly: true, destructive: false, idempotent: true }
          inputParameters:
            - { name: q,             type: string,  required: true }
            - { name: country_code,  type: string }
            - { name: max_price,     type: number }
            - { name: shortlist,     type: integer, description: "How many candidates to compare. Default 5." }
          steps:
            - id: search
              call: buywhere.searchProducts
              with:
                q: input.q
                country_code: input.country_code
                max_price: input.max_price
                compact: true
                limit: input.shortlist
            - id: ids
              transform: "$.data[*].id | join(',')"
              from: search
            - id: compare
              call: buywhere.compareProducts
              with: { ids: steps.ids }
          outputParameters:
            - { type: object, mapping: "{ candidates: steps.compare.data, best: steps.compare.data | sort_by(.normalized_price_usd) | first }" }

        - name: deal_alert
          description: |
            Poll for active discounts in a target country and filter by keyword watchlist.
            Returns matching deals above min_discount.
          hints: { readOnly: true, destructive: false, idempotent: true }
          inputParameters:
            - { name: country_code, type: string, required: true }
            - { name: keywords,     type: string, description: "Comma-separated keywords to match against deal titles." }
            - { name: min_discount, type: number }
            - { name: limit,        type: integer }
          steps:
            - id: deals
              call: buywhere.getDeals
              with:
                country_code: input.country_code
                min_discount: input.min_discount
                limit: input.limit
          outputParameters:
            - { type: object, mapping: "{ deals: steps.deals.data | filter(.title contains_any input.keywords) }" }

        - name: product_research
          description: |
            Discover categories, then fetch a structured shortlist with comparison_attributes
            for a downstream LLM to write a buying guide.
          hints: { readOnly: true, destructive: false, idempotent: true }
          inputParameters:
            - { name: query,        type: string,  required: true }
            - { name: country_code, type: string }
            - { name: limit,        type: integer }
          steps:
            - id: categories
              call: buywhere.listCategories
              with: {}
            - id: candidates
              call: buywhere.searchProducts
              with:
                q: input.query
                country_code: input.country_code
                compact: true
                limit: input.limit
          outputParameters:
            - { type: object, mapping: "{ categories: steps.categories.data, products: steps.candidates.data }" }
binds: []