Ionic shopping tool (#915)

2026-07-01 20:44:00 -04:00 · 2024-02-07 00:07:09 -07:00
parent d08422a620
commit b06623899c
9 changed files with 343 additions and 9 deletions
@@ -0,0 +1,43 @@
+# Ionic Shopping Tool
+
+[Ionic](https://ioniccommerce.com) is a plug and play ecommerce marketplace for AI Assistants. 
+By including the Ionic Tool in your agent, you are effortlessly providing your users with the ability 
+to shop and transact directly within your agent, and you’ll get a cut of the transaction.
+
+## Attribution
+Llearn more about how [Ionic attributes sales](https://docs.ioniccommerce.com/guides/attribution) 
+to your agent. Provide your Ionic API Key when instantiating the tool:
+```python
+from llama_hub.tools.ionic_shopping.base import IonicShoppingToolSpec
+
+ionic_tool = IonicShoppingToolSpec(api_key="<my Ionic API Key>").to_tool_list()
+```
+
+
+## Usage
+Try it out using the [Jupyter notebook](https://github.com/run-llama/llama-hub/blob/main/llama_hub/tools/notebooks/ionic_shopping.ipynb).
+
+```python
+import openai
+from llama_index.agent import OpenAIAgent
+from llama_hub.tools.ionic_shopping.base import IonicShoppingToolSpec
+
+openai.api_key = "sk-api-key"
+
+ionic_tool = IonicShoppingToolSpec(api_key="<my Ionic API Key>").to_tool_list()
+
+agent = OpenAIAgent.from_tools(ionic_tool)
+print(
+    agent.chat(
+        "I'm looking for a 5k monitor can you find me 3 options between $600 and $1000"
+    )
+)
+```
+
+`query`: used to search for products and to get product recommendations
+
+
+Your users can use natural language to specify how many results they would like to see 
+and what their budget is. 
+
+For more information on setting up your Agent with Ionic, see the [Ionic documentation](https://docs.ioniccommerce.com).
@@ -0,0 +1,6 @@
+"""Ionic Shopping Tool"""
+from llama_hub.tools.ionic_shopping.base import (
+    IonicShoppingToolSpec,
+)
+
+__all__ = ["IonicShoppingToolSpec"]
@@ -0,0 +1,63 @@
+from __future__ import annotations
+from typing import Optional
+from llama_index.tools.tool_spec.base import BaseToolSpec
+
+from ionic.models.components import Product, Query as SDKQuery, QueryAPIRequest
+from ionic.models.operations import QueryResponse, QuerySecurity
+
+
+class IonicShoppingToolSpec(BaseToolSpec):
+    """Ionic Shopping tool spec
+
+    This tool can be used to build e-commerce experiences with LLMs.
+    """
+
+    spec_functions = ["query"]
+
+    def __init__(self, api_key: Optional[str] = None) -> None:
+        """Ionic API Key
+
+        Learn more about attribution with Ionic API Keys
+        https://docs.ioniccommerce.com/guides/attribution
+        """
+        from ionic import Ionic as IonicSDK
+
+        if api_key:
+            self.client = IonicSDK(api_key_header=api_key)
+        else:
+            self.client = IonicSDK()
+
+    def query(
+        self,
+        query: str,
+        num_results: Optional[int] = 5,
+        min_price: Optional[int] = None,
+        max_price: Optional[int] = None,
+    ) -> list[Product]:
+        """
+        Use this function to search for products and to get product recommendations
+
+        Args:
+            query (str): A precise query of a product name or product category
+            num_results (Optional[int]): Defaults to 5. The number of product results to return.
+            min_price (Option[int]): The minimum price in cents the requester is willing to pay
+            max_price (Option[int]): The maximum price in cents the requester is willing to pay
+        """
+        request = QueryAPIRequest(
+            query=SDKQuery(
+                query=query,
+                num_results=num_results,
+                min_price=min_price,
+                max_price=max_price,
+            )
+        )
+        response: QueryResponse = self.client.query(
+            request=request,
+            security=QuerySecurity(),
+        )
+
+        return [
+            product
+            for result in response.query_api_response.results
+            for product in result.products
+        ]
@@ -0,0 +1 @@
+ionic-api-sdk
@@ -51,6 +51,10 @@
    "id": "tools/graphql",
    "author": "ajhofmann"
  },
+  "IonicShoppingToolSpec": {
+    "id": "tools/ionic_shopping",
+    "author": "stewartjarod"
+  },
  "MetaphorToolSpec": {
    "id": "tools/metaphor",
    "author": "ajhofmann"
@@ -0,0 +1,205 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "source": [
+    "# Ionic Shopping Tool\n",
+    "\n",
+    "[Ionic](https://www.ioniccommerce.com/) is a plug and play ecommerce marketplace for AI Assistants. By using Ionic, you are effortlessly providing your users with the ability to shop and transact directly within your agent, and you'll get a cut of the transaction.\n",
+    "\n",
+    "This is a basic jupyter notebook demonstrating how to integrate the Ionic Shopping Tool. For more information on setting up your Agent with Ionic, see the Ionic [documentation](https://docs.ioniccommerce.com/introduction).\n",
+    "\n",
+    "This Jupyter Notebook demonstrates how to use the Ionic tool with an Agent.\n",
+    "\n",
+    "---\n",
+    "\n",
+    "## Setup the Tool\n",
+    "### First, let's install our dependencies"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "8024471faac3a296"
+  },
+  {
+   "cell_type": "code",
+   "outputs": [],
+   "source": [
+    "!pip install llama-index llama-hub ionic-api-sdk"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "856d9803ec1cdd9c",
+   "execution_count": null
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### Configure OpenAI"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "eedd002505e12801"
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "initial_id",
+   "metadata": {
+    "collapsed": true,
+    "ExecuteTime": {
+     "end_time": "2024-01-29T22:46:08.765992Z",
+     "start_time": "2024-01-29T22:46:07.725961Z"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "import openai\n",
+    "from llama_index.agent import OpenAIAgent\n",
+    "\n",
+    "openai.api_key = \"sk-api-key\""
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### Import and configure the Ionic Shopping Tool "
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "8506dd2f8e36cad4"
+  },
+  {
+   "cell_type": "code",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "query\n"
+     ]
+    }
+   ],
+   "source": [
+    "from llama_hub.tools.ionic_shopping.base import IonicShoppingToolSpec\n",
+    "\n",
+    "# optionally add you Ionic API Key\n",
+    "# IonicShoppingToolSpec(api_key=\"<my Ionic API Key>\")\n",
+    "ionic_tool = IonicShoppingToolSpec().to_tool_list()\n",
+    "\n",
+    "for tool in ionic_tool:\n",
+    "    print(tool.metadata.name)"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2024-01-29T22:46:08.779746Z",
+     "start_time": "2024-01-29T22:46:08.766351Z"
+    }
+   },
+   "id": "f95ef80d8aa9bd5f",
+   "execution_count": 3
+  },
+  {
+   "cell_type": "markdown",
+   "source": [
+    "### Use Ionic"
+   ],
+   "metadata": {
+    "collapsed": false
+   },
+   "id": "80b4d128986d4a9"
+  },
+  {
+   "cell_type": "code",
+   "outputs": [],
+   "source": [
+    "agent = OpenAIAgent.from_tools(\n",
+    "    ionic_tool,\n",
+    ")"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2024-01-29T22:46:08.935312Z",
+     "start_time": "2024-01-29T22:46:08.780878Z"
+    }
+   },
+   "id": "18bd589c4fd6ef44",
+   "execution_count": 4
+  },
+  {
+   "cell_type": "code",
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Query Query(query='5k monitor', max_price=100000, min_price=60000, num_results=3)\n",
+      "Here are 3 options for a 5k monitor between $600 and $1000:\n",
+      "\n",
+      "1. SAMSUNG 27\" ViewFinity S9 Series 5K Computer Monitor - $999.99\n",
+      "   - [Details](https://www.amazon.com/dp/B0CB71BY87?tag=ioniccommer00-20&linkCode=osi&th=1&psc=1)\n",
+      "   - ![Thumbnail](https://m.media-amazon.com/images/I/41Wy2hc5P2L._SL160_.jpg)\n",
+      "   - Brand: SAMSUNG\n",
+      "   - Available on Amazon\n",
+      "\n",
+      "2. SAMSUNG 27\" Class QHD Curved Monitor - $699.99\n",
+      "   - [Details](https://brwi.short.gy/qxJVZ6)\n",
+      "   - ![Thumbnail](https://i5.walmartimages.com/asr/7794ed18-d65a-4996-abe0-82d2777c779c.5fab7f87d6e84f979a851f61049e549b.jpeg?odnHeight=100&odnWidth=100&odnBg=ffffff)\n",
+      "   - Brand: Samsung\n",
+      "   - UPC: 887276413129\n",
+      "   - Available at Walmart\n",
+      "\n",
+      "3. SAMSUNG 27\" ViewFinity S9 Series 5K Computer Monitor (Open Box) - $749.99\n",
+      "   - [Details](https://brwi.short.gy/YAYBuD)\n",
+      "   - ![Thumbnail](https://i.ebayimg.com/thumbs/images/g/qWIAAOSwSxFlRQi2/s-l225.jpg)\n",
+      "   - Available on eBay\n",
+      "\n",
+      "Please let me know if you need more information about any of these options.\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\n",
+    "    agent.chat(\n",
+    "        \"I'm looking for a 5k monitor can you find me 3 options between $600 and $1000\"\n",
+    "    )\n",
+    ")"
+   ],
+   "metadata": {
+    "collapsed": false,
+    "ExecuteTime": {
+     "end_time": "2024-01-29T22:46:55.891101Z",
+     "start_time": "2024-01-29T22:46:37.542833Z"
+    }
+   },
+   "id": "aa6ee6bd0b1c8f22",
+   "execution_count": 6
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}
@@ -1,4 +1,4 @@
-# This file is automatically @generated by Poetry 1.7.1 and should not be changed by hand.
+# This file is automatically @generated by Poetry 1.7.0 and should not be changed by hand.

 [[package]]
 name = "aiohttp"
@@ -1471,6 +1471,7 @@ files = [
    {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:69b023b2b4daa7548bcfbd4aa3da05b3a74b772db9e23b982788168117739938"},
    {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:81e0b275a9ecc9c0c0c07b4b90ba548307583c125f54d5b6946cfee6360c733d"},
    {file = "PyYAML-6.0.1-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:ba336e390cd8e4d1739f42dfe9bb83a3cc2e80f567d8805e11b46f4a943f5515"},
+    {file = "PyYAML-6.0.1-cp310-cp310-musllinux_1_1_x86_64.whl", hash = "sha256:326c013efe8048858a6d312ddd31d56e468118ad4cdeda36c719bf5bb6192290"},
    {file = "PyYAML-6.0.1-cp310-cp310-win32.whl", hash = "sha256:bd4af7373a854424dabd882decdc5579653d7868b8fb26dc7d0e99f823aa5924"},
    {file = "PyYAML-6.0.1-cp310-cp310-win_amd64.whl", hash = "sha256:fd1592b3fdf65fff2ad0004b5e363300ef59ced41c2e6b3a99d4089fa8c5435d"},
    {file = "PyYAML-6.0.1-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:6965a7bc3cf88e5a1c3bd2e0b5c22f8d677dc88a455344035f03399034eb3007"},
@@ -1478,8 +1479,16 @@ files = [
    {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:42f8152b8dbc4fe7d96729ec2b99c7097d656dc1213a3229ca5383f973a5ed6d"},
    {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:062582fca9fabdd2c8b54a3ef1c978d786e0f6b3a1510e0ac93ef59e0ddae2bc"},
    {file = "PyYAML-6.0.1-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:d2b04aac4d386b172d5b9692e2d2da8de7bfb6c387fa4f801fbf6fb2e6ba4673"},
+    {file = "PyYAML-6.0.1-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:e7d73685e87afe9f3b36c799222440d6cf362062f78be1013661b00c5c6f678b"},
    {file = "PyYAML-6.0.1-cp311-cp311-win32.whl", hash = "sha256:1635fd110e8d85d55237ab316b5b011de701ea0f29d07611174a1b42f1444741"},
    {file = "PyYAML-6.0.1-cp311-cp311-win_amd64.whl", hash = "sha256:bf07ee2fef7014951eeb99f56f39c9bb4af143d8aa3c21b1677805985307da34"},
+    {file = "PyYAML-6.0.1-cp312-cp312-macosx_10_9_x86_64.whl", hash = "sha256:855fb52b0dc35af121542a76b9a84f8d1cd886ea97c84703eaa6d88e37a2ad28"},
+    {file = "PyYAML-6.0.1-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:40df9b996c2b73138957fe23a16a4f0ba614f4c0efce1e9406a184b6d07fa3a9"},
+    {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a08c6f0fe150303c1c6b71ebcd7213c2858041a7e01975da3a99aed1e7a378ef"},
+    {file = "PyYAML-6.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:6c22bec3fbe2524cde73d7ada88f6566758a8f7227bfbf93a408a9d86bcc12a0"},
+    {file = "PyYAML-6.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:8d4e9c88387b0f5c7d5f281e55304de64cf7f9c0021a3525bd3b1c542da3b0e4"},
+    {file = "PyYAML-6.0.1-cp312-cp312-win32.whl", hash = "sha256:d483d2cdf104e7c9fa60c544d92981f12ad66a457afae824d146093b8c294c54"},
+    {file = "PyYAML-6.0.1-cp312-cp312-win_amd64.whl", hash = "sha256:0d3304d8c0adc42be59c5f8a4d9e3d7379e6955ad754aa9d6ab7a398b59dd1df"},
    {file = "PyYAML-6.0.1-cp36-cp36m-macosx_10_9_x86_64.whl", hash = "sha256:50550eb667afee136e9a77d6dc71ae76a44df8b3e51e41b77f6de2932bfe0f47"},
    {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:1fe35611261b29bd1de0070f0b2f47cb6ff71fa6595c077e42bd0c419fa27b98"},
    {file = "PyYAML-6.0.1-cp36-cp36m-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:704219a11b772aea0d8ecd7058d0082713c3562b4e271b849ad7dc4a5c90c13c"},
@@ -1496,6 +1505,7 @@ files = [
    {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:a0cd17c15d3bb3fa06978b4e8958dcdc6e0174ccea823003a106c7d4d7899ac5"},
    {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:28c119d996beec18c05208a8bd78cbe4007878c6dd15091efb73a30e90539696"},
    {file = "PyYAML-6.0.1-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:7e07cbde391ba96ab58e532ff4803f79c4129397514e1413a7dc761ccd755735"},
+    {file = "PyYAML-6.0.1-cp38-cp38-musllinux_1_1_x86_64.whl", hash = "sha256:49a183be227561de579b4a36efbb21b3eab9651dd81b1858589f796549873dd6"},
    {file = "PyYAML-6.0.1-cp38-cp38-win32.whl", hash = "sha256:184c5108a2aca3c5b3d3bf9395d50893a7ab82a38004c8f61c258d4428e80206"},
    {file = "PyYAML-6.0.1-cp38-cp38-win_amd64.whl", hash = "sha256:1e2722cc9fbb45d9b87631ac70924c11d3a401b2d7f410cc0e3bbf249f2dca62"},
    {file = "PyYAML-6.0.1-cp39-cp39-macosx_10_9_x86_64.whl", hash = "sha256:9eb6caa9a297fc2c2fb8862bc5370d0303ddba53ba97e71f08023b6cd73d16a8"},
@@ -1503,6 +1513,7 @@ files = [
    {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:5773183b6446b2c99bb77e77595dd486303b4faab2b086e7b17bc6bef28865f6"},
    {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_s390x.manylinux2014_s390x.whl", hash = "sha256:b786eecbdf8499b9ca1d697215862083bd6d2a99965554781d0d8d1ad31e13a0"},
    {file = "PyYAML-6.0.1-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bc1bf2925a1ecd43da378f4db9e4f799775d6367bdb94671027b73b393a7c42c"},
+    {file = "PyYAML-6.0.1-cp39-cp39-musllinux_1_1_x86_64.whl", hash = "sha256:04ac92ad1925b2cff1db0cfebffb6ffc43457495c9b3c39d3fcae417d7125dc5"},
    {file = "PyYAML-6.0.1-cp39-cp39-win32.whl", hash = "sha256:faca3bdcf85b2fc05d06ff3fbc1f83e1391b3e724afa3feba7d13eeab355484c"},
    {file = "PyYAML-6.0.1-cp39-cp39-win_amd64.whl", hash = "sha256:510c9deebc5c0225e8c96813043e62b680ba2f9c50a08d3724c7f28a747d1486"},
    {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"},
@@ -1915,13 +1926,13 @@ files = [

 [[package]]
 name = "typing-inspect"
-version = "0.8.0"
+version = "0.9.0"
 description = "Runtime inspection utilities for typing module."
 optional = false
 python-versions = "*"
 files = [
-    {file = "typing_inspect-0.8.0-py3-none-any.whl", hash = "sha256:5fbf9c1e65d4fa01e701fe12a5bca6c6e08a4ffd5bc60bfac028253a447c5188"},
-    {file = "typing_inspect-0.8.0.tar.gz", hash = "sha256:8b1ff0c400943b6145df8119c41c244ca8207f1f10c9c057aeed1560e4806e3d"},
+    {file = "typing_inspect-0.9.0-py3-none-any.whl", hash = "sha256:9ee6fc59062311ef8547596ab6b955e1b8aa46242d854bfc78f4f6b0eff35f9f"},
+    {file = "typing_inspect-0.9.0.tar.gz", hash = "sha256:b23fc42ff6f6ef6954e4852c1fb512cdd18dbea03134f91f856a95ccc9461f78"},
 ]

 [package.dependencies]
@@ -2157,4 +2168,4 @@ multidict = ">=4.0"
 [metadata]
 lock-version = "2.0"
 python-versions = ">=3.8.1,<3.12"
-content-hash = "cdee3348a99cb5fc26020c1f818f1950c8027301d6a65c37497dd1ebb0d0baf6"
+content-hash = "886ed83f4b3bde6c44c31b5820bef1138cc22ffd52f6d5afbb321cdc615705de"
@@ -27,8 +27,8 @@ pytest = "7.2.1"
 pytest-dotenv = "0.5.2"
 pytest_httpserver = "1.0.8"
 pytest-mock = "3.11.1"
-typing-inspect = "0.8.0"
-typing_extensions = "^4.5.0"
+typing-inspect = "0.9.0"
+typing_extensions = "^4.9.0"
 types-requests = "2.28.11.8"
 black = "22.12.0"
 isort = "5.11.4"
@@ -6,8 +6,8 @@ pytest_httpserver==1.0.8
 pytest-mock==3.11.1

 # pin types
-typing-inspect==0.8.0
-typing_extensions==4.5.0
+typing-inspect==0.9.0
+typing_extensions==4.9.0

 llama-index>=0.6.9
 atlassian-python-api
@@ -17,6 +17,7 @@ chromadb
 snowflake-sqlalchemy
 selenium
 python-arango
+ionic-api-sdk

 # hotfix
 psutil