Giphy and Websurfer Tutorial (#284)

* Initial giphy app example * Read giphy schema from our git repo * wip * wip * wip * Add websurfer to giphy example * Cleanup * wip * wip * Tutorial wip * Tutorial wip * wip * wip * Update Giphy tutorial to use mesop * wip * Add chat example * Add conclusion to tutorial * Update tutorial * Update tutorial * Added PNG files to LFS * detect secrets fixed --------- Co-authored-by: Davor Runje <[email protected]>
airtai · Sep 27, 2024 · 96a77d6 · 96a77d6
1 parent f87e915
commit 96a77d6
Show file tree

Hide file tree

Showing 14 changed files with 410 additions and 10 deletions.
diff --git a/.gitattributes b/.gitattributes
@@ -1,4 +1,10 @@
 *.jpg filter=lfs diff=lfs merge=lfs -text
 *.png filter=lfs diff=lfs merge=lfs -text
 *.pdf filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
 app/public/public-banner.png filter=lfs diff=lfs merge=lfs -text
+docs/docs/en/tutorial/giphy/images/gifs.png filter=lfs diff=lfs merge=lfs -text
+docs/docs/en/tutorial/giphy/images/initial_message.png filter=lfs diff=lfs merge=lfs -text
+docs/docs/en/tutorial/giphy/images/scraped_info.png filter=lfs diff=lfs merge=lfs -text
+docs/docs/en/tutorial/giphy/images/scraping1.png filter=lfs diff=lfs merge=lfs -text
+docs/docs/en/tutorial/giphy/images/scraping2.png filter=lfs diff=lfs merge=lfs -text
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -61,4 +61,8 @@ repos:
     hooks:
       - id: detect-secrets
         args: ["--baseline", ".secrets.baseline"]
-        exclude: package.lock.json|pnpm-lock.yaml
+        exclude: |
+          (?x)^(
+              package.lock.json|
+              pnpm-lock.yaml
+          )$
diff --git a/.secrets.baseline b/.secrets.baseline
@@ -90,10 +90,6 @@
     {
       "path": "detect_secrets.filters.allowlist.is_line_allowlisted"
     },
-    {
-      "path": "detect_secrets.filters.common.is_baseline_file",
-      "filename": ".secrets.baseline"
-    },
     {
       "path": "detect_secrets.filters.common.is_ignored_due_to_verification_policies",
       "min_level": 2
@@ -124,17 +120,31 @@
     },
     {
       "path": "detect_secrets.filters.heuristic.is_templated_secret"
+    },
+    {
+      "path": "detect_secrets.filters.regex.should_exclude_secret",
+      "pattern": [
+        "your_bing_api_key"
+      ]
     }
   ],
   "results": {
+    "docs/docs/en/tutorial/giphy/index.md": [
+      {
+        "type": "Secret Keyword",
+        "filename": "docs/docs/en/tutorial/giphy/index.md",
+        "hashed_secret": "63f8ff37d3848fcf04ef3afe45d0fc830678d1ce",
+        "is_verified": false,
+        "line_number": 70
+      }
+    ],
     "examples/autogen.ipynb": [
       {
         "type": "Base64 High Entropy String",
         "filename": "examples/autogen.ipynb",
         "hashed_secret": "f8be8ff0f1992b6fa091e7340a749213ab35fac7",
         "is_verified": false,
-        "line_number": 901,
-        "is_secret": false
+        "line_number": 901
       }
     ],
     "examples/openapi/giphy_openapi.json": [
@@ -143,10 +153,9 @@
         "filename": "examples/openapi/giphy_openapi.json",
         "hashed_secret": "e3ddfbda4fafddc6ce61a11ef9e9c0149bbfcc48",
         "is_verified": false,
-        "line_number": 1066,
-        "is_secret": false
+        "line_number": 1066
       }
     ]
   },
-  "generated_at": "2024-09-10T08:21:20Z"
+  "generated_at": "2024-09-27T14:05:45Z"
 }
diff --git a/docs/docs/SUMMARY.md b/docs/docs/SUMMARY.md
@@ -20,6 +20,8 @@ search:
         - [Security](user-guide/api/security.md)
     - [Testing](user-guide/testing/index.md)
     - [CLI](user-guide/cli/index.md)
+- Tutorial
+    - [Giphy API & WebSurfer](tutorial/giphy/index.md)
 - Reference
     - API
         - fastagency

diff --git a/docs/docs/en/tutorial/giphy/images/gifs.png b/docs/docs/en/tutorial/giphy/images/gifs.png
diff --git a/docs/docs/en/tutorial/giphy/images/initial_message.png b/docs/docs/en/tutorial/giphy/images/initial_message.png
diff --git a/docs/docs/en/tutorial/giphy/images/scraped_info.png b/docs/docs/en/tutorial/giphy/images/scraped_info.png
diff --git a/docs/docs/en/tutorial/giphy/images/scraping1.png b/docs/docs/en/tutorial/giphy/images/scraping1.png
diff --git a/docs/docs/en/tutorial/giphy/images/scraping2.png b/docs/docs/en/tutorial/giphy/images/scraping2.png
diff --git a/docs/docs/en/tutorial/giphy/index.md b/docs/docs/en/tutorial/giphy/index.md
@@ -0,0 +1,240 @@
+# Web Scraping and Giphy API Integration
+
+In this tutorial, we will explore how to leverage the **FastAgency** framework to create a dynamic and interactive chatbot that integrates two powerful agents:
+
+**WebSurferAgent** – A web-scraping agent capable of retrieving relevant content from webpages.
+**GiphyAgent** – An agent that interacts with the [Giphy](https://giphy.com){target="_blank"} **API** to fetch GIFs based on the user’s request.
+
+The chat system will operate between these two agents and the user, allowing them to scrape web content and generate GIFs based on that content, all within a seamless conversation. This tutorial will guide you through setting up these agents and handling user interaction in a secure, structured, and intuitive manner.
+
+## What You’ll Learn
+
+By the end of this tutorial, you’ll understand how to:
+
+- Integrate external APIs like [Giphy](https://giphy.com){target="_blank"} with **FastAgency**.
+- Build and register agents that can autonomously scrape the web for relevant information.
+- Use **FastAgency** workflows to manage agent interactions and user input.
+- Present scraped content to the user and offer personalized GIF suggestions based on that content.
+
+We will walk through setting up each agent, handling API security, and creating a cohesive conversation that can scrape data, process user input, and generate GIFs in response.
+
+Let’s dive into creating a powerful interactive agent system with **FastAgency**!
+
+
+## Installation and API Key Setup
+
+Before we dive into building our agents, let’s go over the necessary setup. We will guide you through installing the **FastAgency** framework and obtaining the API key needed for the Giphy integration.
+
+### Installing FastAgency
+
+To get started, you need to install FastAgency with OpenAPI submodule. You can do this using `pip`, Python's package installer.
+
+```bash
+pip install "fastagency[autogen,mesop,openapi]"
+```
+
+### API Key Setup
+**WebSurferAgent** requires an **Bing Web Search** API key and **GiphyAgent** requires an API key to interact with Giphy's service. Follow these steps to create your API keys:
+
+#### Create Bing Web Search API Key
+To create [Bing Web Search](https://www.microsoft.com/en-us/bing/apis/pricing){target="_blank"} API key, follow the guide provided.
+
+!!! note
+    You will need to create **Microsoft Azure** Account.
+
+#### Create a Giphy Account
+**Step 1**: If you don’t have a Giphy account, you’ll need to sign up:
+
+- Go to [Giphy Developers](https://developers.giphy.com){target="_blank"}
+- Click on **Create Account**.
+
+**Step 2**: Navigate to [Dashboard](https://developers.giphy.com/dashboard/){target="_blank"}
+!!! note
+    You may need to wait a few minutes after creating your account before being able to access the **Dashboard** page.
+- Click on **Create an API key** and choose **API** as the type of app and give it a name (e.g., "FastAgency Giphy App").
+- Agree to the terms and click Create App.
+
+**Step 3**: Get Your API Key
+After creating the app, you’ll be provided with an **API Key**.
+
+- Copy this key and continue with the following steps.
+
+#### Set Up Your API Keys in the Environment
+
+To securely use the API keys in your project, you should store it in an environment variables.
+
+You can set the API keys in your terminal as an environment variable:
+
+=== "Linux/macOS"
+    ```bash
+    export GIPHY_API_KEY="your_giphy_api_key"
+    export BING_API_KEY="your_bing_api_key"
+    ```
+=== "Windows"
+    ```bash
+    set GIPHY_API_KEY="your_giphy_api_key"
+    set BING_API_KEY="your_bing_api_key"
+    ```
+
+## Complete Application Code
+
+<details>
+<summary>main.py</summary>
+```python
+{! docs_src/tutorial/giphy/main.py !}
+```
+</details>
+
+
+## Code Walkthrough
+
+Now we will go over each key part of the code, explaining its function and purpose within the FastAgency framework. Understanding these components is crucial for building a dynamic interaction between the user, the **WebSurferAgent**, and the **GiphyAgent**.
+
+### Creating the Giphy API Instance
+The following lines shows hot to initializes the Giphy API by loading the OpenAPI specification from a URL. The OpenAPI spec defines how to interact with the Giphy API, including endpoints, parameters, and security details.
+
+Also, we configure the **Giphy API** with the __*GIPHY_API_KEY*__ using __*set_security_params*__ to authenticate our requests.
+```python
+{! docs_src/tutorial/giphy/main.py [ln:26-30] !}
+```
+
+For more information, visit [**API Integration User Guide**](../../user-guide/api){target="_blank"}.
+
+### Registering the Workflow
+
+Here, we initialize a new workflow using ***AutoGenWorkflows()*** and register it under the name ***"giphy_and_websurfer"***. The ***@wf.register*** decorator registers the function to handle chat flow with security enabled, combining both GiphyAgent and WebSurferAgent.
+
+```python
+{! docs_src/tutorial/giphy/main.py [ln:59-62] !}
+```
+
+### Interaction with the user
+This is a core function used by the **GiphyAgent** to either present the task result or ask a follow-up question to the user. The message is wrapped in a ***TextInput*** object, and then ***ui.process_message()*** sends it for user interaction.
+
+```python
+{! docs_src/tutorial/giphy/main.py [ln:66-77] !}
+```
+
+### Creating the Giphy and WebSurfer Agents
+
+- **GiphyAgent**: A ***ConversableAgent*** is created with the name "Giphy_Agent". It uses the system message defined earlier and relies on the termination function to end the chat when needed.
+- **WebSurferAgent**: The ***WebSurferAgent*** is responsible for scraping web content and passes the retrieved data to the **GiphyAgent**. It’s configured with a summarizer to condense web content, which is useful when presenting concise data to the user. For more information, visit [**WebSurfer User Guide**](../../user-guide/runtime/autogen/websurfer){target="_blank"}.
+
+```python
+{! docs_src/tutorial/giphy/main.py [ln:79-93] !}
+```
+
+### Registering Functions
+
+The function ***present_completed_task_or_ask_question*** is registered to allow the **GiphyAgent** to ask questions or present completed tasks after receiving data from the **WebSurferAgent**.
+
+```python
+{! docs_src/tutorial/giphy/main.py [ln:95-102] !}
+```
+
+We specify which Giphy API functions can be used by the **GiphyAgent**: *random_gif*, *search_gifs*, and *trending_gifs*. These functions allow the agent to generate GIFs based on user input or trending content.
+```python
+{! docs_src/tutorial/giphy/main.py [ln:104-110] !}
+```
+
+### Initiating the Chat
+
+We initiate the conversation between the user, **WebSurferAgent**, and **GiphyAgent**. The user’s initial message is provided, and the system is configured to handle up to 10 turns of interaction. The conversation is summarized using the ***reflection_with_llm*** method, which uses a language model to summarize the chat.
+
+Once the conversation ends, the summary is returned to the user, wrapping up the session.
+
+```python
+{! docs_src/tutorial/giphy/main.py [ln:112-119] !}
+```
+
+### Starting the Application
+
+The FastAgency app is created, using the registered workflows (***wf***) and web-based user interface (***MesopUI***). This makes the conversation between agents and the user interactive.
+
+```python
+{! docs_src/tutorial/giphy/main.py [ln:122] !}
+```
+
+For more information, visit [**Mesop User Guide**](../../user-guide/ui/mesop/basics){target="_blank"}.
+
+## Running the Application
+
+Once the workflow is set up, you can run the application using the **FastAgency CLI**. Navigate to the directory where the script is located and run the following command:
+
+```bash
+fastagency run
+```
+
+```console
+ ╭─ Python package file structure ──╮
+ │                                  │
+ │  📁 docs                         │
+ │  ├── 🐍 __init__.py              │
+ │  └── 📁 docs_src                 │
+ │      ├── 🐍 __init__.py          │
+ │      └── 📁 tutorial             │
+ │          ├── 🐍 __init__.py      │
+ │          └── 📁 giphy            │
+ │              ├── 🐍 __init__.py  │
+ │              └── 🐍 main.py      │
+ │                                  │
+ ╰──────────────────────────────────╯
+
+/home/vscode/.local/lib/python3.10/site-packages/pydantic/_internal/_config.py:341: UserWarning: Valid config keys have changed in V2:
+* 'keep_untouched' has been renamed to 'ignored_types'
+  warnings.warn(message, UserWarning)
+ [INFO] Importing autogen.base.py
+/home/vscode/.local/lib/python3.10/site-packages/pydantic/main.py:214: UserWarning: A custom validator is returning a value other than `self`.
+Returning anything other than `self` from a top level model validator isn't supported when validating via `__init__`.
+See the `model_validator` docs (https://docs.pydantic.dev/latest/concepts/validators/#model-validators) for more details.
+  warnings.warn(
+
+ ╭───────────── Importable FastAgency app ─────────────╮
+ │                                                     │
+ │  from docs.docs_src.tutorial.giphy.main import app  │
+ │                                                     │
+ ╰─────────────────────────────────────────────────────╯
+
+ [INFO] Creating MesopUI with import string: docs.docs_src.tutorial.giphy.main:app
+ [INFO] Starting MesopUI: import_string=docs.docs_src.tutorial.giphy.main:app, main_path=/tmp/tmpfi8uxdgv/main.py
+Running with hot reload:
+
+Running server on: http://localhost:32123
+ * Serving Flask app 'mesop.server.server'
+ * Debug mode: off
+```
+
+The command will launch a web interface where users can input their requests and interact with the agents (in this case ***http://localhost:32123***)
+
+!!! note
+    Ensure that your OpenAI API key is set in the environment, as the agents rely on it to interact using GPT-4o. If the API key is not correctly configured, the application may fail to retrieve LLM-powered responses.
+
+## Chat Example
+In this scenario, the user instructs the agents to scrape [BBC Sport](https://www.bbc.com/sport) for the latest sports news.
+
+![Initial message](./images/initial_message.png)
+
+Upon receiving the request, **WebSurferAgent** initiates the process by scraping the webpage for relevant updates.
+
+![Scraping 1](./images/scraping1.png)
+
+![Scraping 2](./images/scraping2.png)
+
+Once the scraping is complete, the agents deliver their findings to the user.
+In the final step, the user asks for a few *Premier League* GIFs, which **GiphyAgent** promptly provides.
+
+![Scraped Info](./images/scraped_info.png)
+
+![Gifs](./images/gifs.png)
+
+## Conclusion
+
+In this tutorial, we walked through how to create a simple chatbot using **FastAgency** that can scrape web content and provide relevant GIFs. By integrating the **WebSurferAgent** and **GiphyAgent**, we built a tool that lets users gather information from the web and request GIFs all in one conversation.
+
+You’ve learned how to:
+
+- Set up and connect external APIs, like Giphy, to your project.
+- Handle API key security.
+- Build an interactive workflow where users can scrape content and get personalized responses.
+- Offer dynamic, engaging conversations with added visuals like GIFs.
+- With these skills, you now have the foundation to expand and add more features to your chatbot, making it even more interactive and useful.
diff --git a/docs/docs/navigation_template.txt b/docs/docs/navigation_template.txt
@@ -20,6 +20,8 @@ search:
         - [Security](user-guide/api/security.md)
     - [Testing](user-guide/testing/index.md)
     - [CLI](user-guide/cli/index.md)
+- Tutorial
+    - [Giphy API & WebSurfer](tutorial/giphy/index.md)
 - Reference
 {api}
 {cli}

diff --git a/docs/docs_src/tutorial/__init__.py b/docs/docs_src/tutorial/__init__.py
diff --git a/docs/docs_src/tutorial/giphy/__init__.py b/docs/docs_src/tutorial/giphy/__init__.py