docs/user_guide/08_semantic_router.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Semantic Routing\n",
    "\n",
    "RedisVL provides a `SemanticRouter` interface to utilize Redis' built-in search & aggregation in order to perform\n",
    "KNN-style classification over a set of `Route` references to determine the best match.\n",
    "\n",
    "This notebook will go over how to use Redis as a Semantic Router for your applications"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Define the Routes\n",
    "\n",
    "Below we define 3 different routes. One for `technology`, one for `sports`, and\n",
    "another for `entertainment`. Now for this example, the goal here is\n",
    "surely topic \"classification\". But you can create routes and references for\n",
    "almost anything.\n",
    "\n",
    "Each route has a set of references that cover the \"semantic surface area\" of the\n",
    "route. The incoming query from a user needs to be semantically similar to one or\n",
    "more of the references in order to \"match\" on the route.\n",
    "\n",
    "Additionally, each route has a `distance_threshold` which determines the maximum distance between the query and the reference for the query to be routed to the route. This value is unique to each route."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from redisvl.extensions.router import Route\n",
    "\n",
    "\n",
    "# Define routes for the semantic router\n",
    "technology = Route(\n",
    "    name=\"technology\",\n",
    "    references=[\n",
    "        \"what are the latest advancements in AI?\",\n",
    "        \"tell me about the newest gadgets\",\n",
    "        \"what's trending in tech?\"\n",
    "    ],\n",
    "    metadata={\"category\": \"tech\", \"priority\": 1},\n",
    "    distance_threshold=0.71\n",
    ")\n",
    "\n",
    "sports = Route(\n",
    "    name=\"sports\",\n",
    "    references=[\n",
    "        \"who won the game last night?\",\n",
    "        \"tell me about the upcoming sports events\",\n",
    "        \"what's the latest in the world of sports?\",\n",
    "        \"sports\",\n",
    "        \"basketball and football\"\n",
    "    ],\n",
    "    metadata={\"category\": \"sports\", \"priority\": 2},\n",
    "    distance_threshold=0.72\n",
    ")\n",
    "\n",
    "entertainment = Route(\n",
    "    name=\"entertainment\",\n",
    "    references=[\n",
    "        \"what are the top movies right now?\",\n",
    "        \"who won the best actor award?\",\n",
    "        \"what's new in the entertainment industry?\"\n",
    "    ],\n",
    "    metadata={\"category\": \"entertainment\", \"priority\": 3},\n",
    "    distance_threshold=0.7\n",
    ")\n"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Initialize the SemanticRouter\n",
    "\n",
    "``SemanticRouter`` will automatically create an index within Redis upon initialization for the route references. By default, it uses the `HFTextVectorizer` to \n",
    "generate embeddings for each route reference."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stderr",
     "output_type": "stream",
     "text": [
      "/Users/robert.shelton/Library/Caches/pypoetry/virtualenvs/redisvl-56gG2io_-py3.11/lib/python3.11/site-packages/tqdm/auto.py:21: TqdmWarning: IProgress not found. Please update jupyter and ipywidgets. See https://ipywidgets.readthedocs.io/en/stable/user_install.html\n",
      "  from .autonotebook import tqdm as notebook_tqdm\n"
     ]
    }
   ],
   "source": [
    "import os\n",
    "from redisvl.extensions.router import SemanticRouter\n",
    "from redisvl.utils.vectorize import HFTextVectorizer\n",
    "\n",
    "os.environ[\"TOKENIZERS_PARALLELISM\"] = \"false\"\n",
    "\n",
    "# Initialize the SemanticRouter\n",
    "router = SemanticRouter(\n",
    "    name=\"topic-router\",\n",
    "    vectorizer=HFTextVectorizer(),\n",
    "    routes=[technology, sports, entertainment],\n",
    "    redis_url=\"redis://localhost:6379\",\n",
    "    overwrite=True # Blow away any other routing index with this name\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\n",
      "\n",
      "Index Information:\n",
      "╭──────────────┬────────────────┬──────────────────┬─────────────────┬────────────╮\n",
      "│ Index Name   │ Storage Type   │ Prefixes         │ Index Options   │   Indexing │\n",
      "├──────────────┼────────────────┼──────────────────┼─────────────────┼────────────┤\n",
      "│ topic-router │ HASH           │ ['topic-router'] │ []              │          0 │\n",
      "╰──────────────┴────────────────┴──────────────────┴─────────────────┴────────────╯\n",
      "Index Fields:\n",
      "╭──────────────┬──────────────┬────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬────────────────┬─────────────────┬────────────────╮\n",
      "│ Name         │ Attribute    │ Type   │ Field Option   │ Option Value   │ Field Option   │ Option Value   │ Field Option   │   Option Value │ Field Option    │ Option Value   │\n",
      "├──────────────┼──────────────┼────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼────────────────┼─────────────────┼────────────────┤\n",
      "│ reference_id │ reference_id │ TAG    │ SEPARATOR      │ ,              │                │                │                │                │                 │                │\n",
      "│ route_name   │ route_name   │ TAG    │ SEPARATOR      │ ,              │                │                │                │                │                 │                │\n",
      "│ reference    │ reference    │ TEXT   │ WEIGHT         │ 1              │                │                │                │                │                 │                │\n",
      "│ vector       │ vector       │ VECTOR │ algorithm      │ FLAT           │ data_type      │ FLOAT32        │ dim            │            768 │ distance_metric │ COSINE         │\n",
      "╰──────────────┴──────────────┴────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴────────────────┴─────────────────┴────────────────╯\n"
     ]
    }
   ],
   "source": [
    "# look at the index specification created for the semantic router\n",
    "!rvl index info -i topic-router"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "11"
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "router._index.info()[\"num_docs\"]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Simple routing"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "RouteMatch(name='technology', distance=0.419145862261)"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Query the router with a statement\n",
    "route_match = router(\"Can you tell me about the latest in artificial intelligence?\")\n",
    "route_match"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "RouteMatch(name=None, distance=None)"
      ]
     },
     "execution_count": 6,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Query the router with a statement and return a miss\n",
    "route_match = router(\"are aliens real?\")\n",
    "route_match"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also route a statement to many routes and order them by distance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[RouteMatch(name='technology', distance=0.556493759155),\n",
       " RouteMatch(name='sports', distance=0.67106004556)]"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Perform multi-class classification with route_many() -- toggle the max_k and the distance_threshold\n",
    "route_matches = router.route_many(\"How is AI used in basketball?\", max_k=3)\n",
    "route_matches"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[RouteMatch(name='technology', distance=0.556493759155),\n",
       " RouteMatch(name='sports', distance=0.62926441431)]"
      ]
     },
     "execution_count": 8,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# Toggle the aggregation method -- note the different distances in the result\n",
    "from redisvl.extensions.router.schema import DistanceAggregationMethod\n",
    "\n",
    "route_matches = router.route_many(\"How is AI used in basketball?\", aggregation_method=DistanceAggregationMethod.min, max_k=3)\n",
    "route_matches"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note the different route match distances. This is because we used the `min` aggregation method instead of the default `avg` approach."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Update the routing config"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "from redisvl.extensions.router import RoutingConfig\n",
    "\n",
    "router.update_routing_config(\n",
    "    RoutingConfig(aggregation_method=DistanceAggregationMethod.min, max_k=3)\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[RouteMatch(name='sports', distance=0.663253903389)]"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "route_matches = router.route_many(\"Lebron James\")\n",
    "route_matches"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Router serialization"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'topic-router',\n",
       " 'routes': [{'name': 'technology',\n",
       "   'references': ['what are the latest advancements in AI?',\n",
       "    'tell me about the newest gadgets',\n",
       "    \"what's trending in tech?\"],\n",
       "   'metadata': {'category': 'tech', 'priority': 1},\n",
       "   'distance_threshold': 0.71},\n",
       "  {'name': 'sports',\n",
       "   'references': ['who won the game last night?',\n",
       "    'tell me about the upcoming sports events',\n",
       "    \"what's the latest in the world of sports?\",\n",
       "    'sports',\n",
       "    'basketball and football'],\n",
       "   'metadata': {'category': 'sports', 'priority': 2},\n",
       "   'distance_threshold': 0.72},\n",
       "  {'name': 'entertainment',\n",
       "   'references': ['what are the top movies right now?',\n",
       "    'who won the best actor award?',\n",
       "    \"what's new in the entertainment industry?\"],\n",
       "   'metadata': {'category': 'entertainment', 'priority': 3},\n",
       "   'distance_threshold': 0.7}],\n",
       " 'vectorizer': {'type': 'hf',\n",
       "  'model': 'sentence-transformers/all-mpnet-base-v2'},\n",
       " 'routing_config': {'max_k': 3, 'aggregation_method': 'min'}}"
      ]
     },
     "execution_count": 11,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "router.to_dict()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[32m11:57:04\u001b[0m \u001b[34mredisvl.index.index\u001b[0m \u001b[1;30mINFO\u001b[0m   Index already exists, not overwriting.\n"
     ]
    }
   ],
   "source": [
    "router2 = SemanticRouter.from_dict(router.to_dict(), redis_url=\"redis://localhost:6379\")\n",
    "\n",
    "assert router2.to_dict() == router.to_dict()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "metadata": {},
   "outputs": [],
   "source": [
    "router.to_yaml(\"router.yaml\", overwrite=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "\u001b[32m11:57:06\u001b[0m \u001b[34mredisvl.index.index\u001b[0m \u001b[1;30mINFO\u001b[0m   Index already exists, not overwriting.\n"
     ]
    }
   ],
   "source": [
    "router3 = SemanticRouter.from_yaml(\"router.yaml\", redis_url=\"redis://localhost:6379\")\n",
    "\n",
    "assert router3.to_dict() == router2.to_dict() == router.to_dict()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Add route references"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "['topic-router:technology:f243fb2d073774e81c7815247cb3013794e6225df3cbe3769cee8c6cefaca777',\n",
       " 'topic-router:technology:7e4bca5853c1c3298b4d001de13c3c7a79a6e0f134f81acc2e7cddbd6845961f']"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "router.add_route_references(route_name=\"technology\", references=[\"latest AI trends\", \"new tech gadgets\"])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Get route references"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 16,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'id': 'topic-router:technology:f243fb2d073774e81c7815247cb3013794e6225df3cbe3769cee8c6cefaca777',\n",
       "  'reference_id': 'f243fb2d073774e81c7815247cb3013794e6225df3cbe3769cee8c6cefaca777',\n",
       "  'route_name': 'technology',\n",
       "  'reference': 'latest AI trends'},\n",
       " {'id': 'topic-router:technology:851f51cce5a9ccfbbcb66993908be6b7871479af3e3a4b139ad292a1bf7e0676',\n",
       "  'reference_id': '851f51cce5a9ccfbbcb66993908be6b7871479af3e3a4b139ad292a1bf7e0676',\n",
       "  'route_name': 'technology',\n",
       "  'reference': 'what are the latest advancements in AI?'},\n",
       " {'id': 'topic-router:technology:149a9c9919c58534aa0f369e85ad95ba7f00aa0513e0f81e2aff2ea4a717b0e0',\n",
       "  'reference_id': '149a9c9919c58534aa0f369e85ad95ba7f00aa0513e0f81e2aff2ea4a717b0e0',\n",
       "  'route_name': 'technology',\n",
       "  'reference': \"what's trending in tech?\"},\n",
       " {'id': 'topic-router:technology:85cc73a1437df27caa2f075a29c497e5a2e532023fbb75378aedbae80779ab37',\n",
       "  'reference_id': '85cc73a1437df27caa2f075a29c497e5a2e532023fbb75378aedbae80779ab37',\n",
       "  'route_name': 'technology',\n",
       "  'reference': 'tell me about the newest gadgets'},\n",
       " {'id': 'topic-router:technology:7e4bca5853c1c3298b4d001de13c3c7a79a6e0f134f81acc2e7cddbd6845961f',\n",
       "  'reference_id': '7e4bca5853c1c3298b4d001de13c3c7a79a6e0f134f81acc2e7cddbd6845961f',\n",
       "  'route_name': 'technology',\n",
       "  'reference': 'new tech gadgets'}]"
      ]
     },
     "execution_count": 16,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# by route name\n",
    "refs = router.get_route_references(route_name=\"technology\")\n",
    "refs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 17,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "[{'id': 'topic-router:technology:f243fb2d073774e81c7815247cb3013794e6225df3cbe3769cee8c6cefaca777',\n",
       "  'reference_id': 'f243fb2d073774e81c7815247cb3013794e6225df3cbe3769cee8c6cefaca777',\n",
       "  'route_name': 'technology',\n",
       "  'reference': 'latest AI trends'}]"
      ]
     },
     "execution_count": 17,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# by reference id\n",
    "refs = router.get_route_references(reference_ids=[refs[0][\"reference_id\"]])\n",
    "refs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Delete route references"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 18,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "5"
      ]
     },
     "execution_count": 18,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# by route name\n",
    "deleted_count = router.delete_route_references(route_name=\"sports\")\n",
    "deleted_count"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 19,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "1"
      ]
     },
     "execution_count": 19,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "# by id\n",
    "deleted_count = router.delete_route_references(reference_ids=[refs[0][\"reference_id\"]])\n",
    "deleted_count"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Clean up the router"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 20,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use clear to flush all routes from the index\n",
    "router.clear()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 21,
   "metadata": {},
   "outputs": [],
   "source": [
    "# Use delete to clear the index and remove it completely\n",
    "router.delete()"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "redisvl-56gG2io_-py3.11",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.9"
  },
  "orig_nbformat": 4
 },
 "nbformat": 4,
 "nbformat_minor": 2
}