diff --git a/docs/docs/integrations/providers/ads4gpts.mdx b/docs/docs/integrations/providers/ads4gpts.mdx new file mode 100644 index 00000000000..fd82f96f8eb --- /dev/null +++ b/docs/docs/integrations/providers/ads4gpts.mdx @@ -0,0 +1,82 @@ +# ADS4GPTs + +> [ADS4GPTs](https://www.ads4gpts.com/) is building the open monetization backbone of the AI-Native internet. It helps AI applications monetize through advertising with a UX and Privacy first approach. + +## Installation and Setup + +### Using pip +You can install the package directly from PyPI: + +```bash +pip install ads4gpts-langchain +``` + +### From Source +Alternatively, install from source: + +```bash +git clone https://github.com/ADS4GPTs/ads4gpts.git +cd ads4gpts/libs/python-sdk/ads4gpts-langchain +pip install . +``` + +## Prerequisites + +- Python 3.11+ +- ADS4GPTs API Key ([Obtain API Key](https://www.ads4gpts.com)) + +## Environment Variables +Set the following environment variables for API authentication: + +```bash +export ADS4GPTS_API_KEY='your-ads4gpts-api-key' +``` + +Alternatively, API keys can be passed directly when initializing classes or stored in a `.env` file. + +## Tools + +ADS4GPTs provides two main tools for monetization: + +### Ads4gptsInlineSponsoredResponseTool +This tool fetches native, sponsored responses that can be seamlessly integrated within your AI application's outputs. + +```python +from ads4gpts_langchain import Ads4gptsInlineSponsoredResponseTool +``` + +### Ads4gptsSuggestedPromptTool +Generates sponsored prompt suggestions to enhance user engagement and provide monetization opportunities. + +```python +from ads4gpts_langchain import Ads4gptsSuggestedPromptTool +``` +### Ads4gptsInlineConversationalTool +Delivers conversational sponsored content that naturally fits within chat interfaces and dialogs. + +```python +from ads4gpts_langchain import Ads4gptsInlineConversationalTool +``` + +### Ads4gptsInlineBannerTool +Provides inline banner advertisements that can be displayed within your AI application's response. + +```python +from ads4gpts_langchain import Ads4gptsInlineBannerTool +``` + +### Ads4gptsSuggestedBannerTool +Generates banner advertisement suggestions that can be presented to users as recommended content. + +```python +from ads4gpts_langchain import Ads4gptsSuggestedBannerTool +``` + +## Toolkit + +The `Ads4gptsToolkit` combines these tools for convenient access in LangChain applications. + +```python +from ads4gpts_langchain import Ads4gptsToolkit +``` + diff --git a/docs/docs/integrations/tools/ads4gpts.ipynb b/docs/docs/integrations/tools/ads4gpts.ipynb new file mode 100644 index 00000000000..b04fdd51957 --- /dev/null +++ b/docs/docs/integrations/tools/ads4gpts.ipynb @@ -0,0 +1,365 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "# ADS4GPTs\n", + "\n", + "Integrate AI native advertising into your Agentic application.\n" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Overview" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "This notebook outlines how to use the ADS4GPTs Tools and Toolkit in LangChain directly. In your LangGraph application though you will most likely use our prebuilt LangGraph agents." + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Setup" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Install ADS4GPTs Package\n", + "Install the ADS4GPTs package using pip." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Install ADS4GPTs Package\n", + "# Install the ADS4GPTs package using pip\n", + "!pip install ads4gpts-langchain" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Set up the environment variables for API authentication ([Obtain API Key](https://www.ads4gpts.com))." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Setup Environment Variables\n", + "# Prompt the user to enter their ADS4GPTs API key securely\n", + "if not os.environ.get(\"ADS4GPTS_API_KEY\"):\n", + " os.environ[\"ADS4GPTS_API_KEY\"] = getpass(\"Enter your ADS4GPTS API key: \")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Instantiation" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Import the necessary libraries, including ADS4GPTs tools and toolkit.\n", + "\n", + "Initialize the ADS4GPTs tools such as Ads4gptsInlineSponsoredResponseTool. We are going to work with one tool because the process is the same for every other tool we provide." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Import Required Libraries\n", + "\n", + "import os\n", + "from getpass import getpass\n", + "\n", + "from ads4gpts_langchain import Ads4gptsInlineSponsoredResponseTool, Ads4gptsToolkit" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# Initialize ADS4GPTs Tools\n", + "# Initialize the Ads4gptsInlineSponsoredResponseTool\n", + "inline_sponsored_response_tool = Ads4gptsInlineSponsoredResponseTool(\n", + " ads4gpts_api_key=os.environ[\"ADS4GPTS_API_KEY\"],\n", + ")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Toolkit Instantiation\n", + "Initialize the Ads4gptsToolkit with the required parameters." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Initialized tool: Ads4gptsInlineSponsoredResponseTool\n", + "Initialized tool: Ads4gptsSuggestedPromptTool\n" + ] + } + ], + "source": [ + "# Toolkit Initialization\n", + "# Initialize the Ads4gptsToolkit with the required parameters\n", + "toolkit = Ads4gptsToolkit(\n", + " ads4gpts_api_key=os.environ[\"ADS4GPTS_API_KEY\"],\n", + ")\n", + "\n", + "# Retrieve tools from the toolkit\n", + "tools = toolkit.get_tools()\n", + "\n", + "# Print the initialized tools\n", + "for tool in tools:\n", + " print(f\"Initialized tool: {tool.__class__.__name__}\")" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Invocation" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "Run the ADS4GPTs tools with sample inputs and display the results." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Inline Sponsored Response Result: {'ad_text': '<- Promoted Content ->\\n\\nLearn the sartorial ways and get your handmade tailored suit by the masters themselves with Bespoke Tailors. [Subscribe now](https://youtube.com/@bespoketailorsdubai?si=9iH587ujoWKkueFa)\\n\\n<->'}\n" + ] + } + ], + "source": [ + "# Run ADS4GPTs Tools\n", + "# Sample input data for the tools\n", + "sample_input = {\n", + " \"id\": \"test_id\",\n", + " \"user_gender\": \"female\",\n", + " \"user_age\": \"25-34\",\n", + " \"user_persona\": \"test_persona\",\n", + " \"ad_recommendation\": \"test_recommendation\",\n", + " \"undesired_ads\": \"test_undesired_ads\",\n", + " \"context\": \"test_context\",\n", + " \"num_ads\": 1,\n", + " \"style\": \"neutral\",\n", + "}\n", + "\n", + "# Run Ads4gptsInlineSponsoredResponseTool\n", + "inline_sponsored_response_result = inline_sponsored_response_tool._run(\n", + " **sample_input, ad_format=\"INLINE_SPONSORED_RESPONSE\"\n", + ")\n", + "print(\"Inline Sponsored Response Result:\", inline_sponsored_response_result)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Async Run ADS4GPTs Tools\n", + "Run the ADS4GPTs tools asynchronously with sample inputs and display the results." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Async Inline Sponsored Response Result: {'ad_text': '<- Promoted Content ->\\n\\nGet the best tailoring content from Jonathan Farley. Learn to tie 100 knots and more! [Subscribe now](https://www.youtube.com/channel/UCx5hk4LN3p02jcUt3j_cexQ)\\n\\n<->'}\n" + ] + } + ], + "source": [ + "import asyncio\n", + "\n", + "\n", + "# Define an async function to run the tools asynchronously\n", + "async def run_ads4gpts_tools_async():\n", + " # Run Ads4gptsInlineSponsoredResponseTool asynchronously\n", + " inline_sponsored_response_result = await inline_sponsored_response_tool._arun(\n", + " **sample_input, ad_format=\"INLINE_SPONSORED_RESPONSE\"\n", + " )\n", + " print(\"Async Inline Sponsored Response Result:\", inline_sponsored_response_result)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "### Toolkit Invocation\n", + "Use the Ads4gptsToolkit to get and run tools." + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Result from Ads4gptsInlineSponsoredResponseTool: {'ad_text': '<- Promoted Content ->\\n\\nLearn the sartorial ways and get your handmade tailored suit by the masters themselves with Bespoke Tailors. [Subscribe now](https://youtube.com/@bespoketailorsdubai?si=9iH587ujoWKkueFa)\\n\\n<->'}\n", + "Async result from Ads4gptsInlineSponsoredResponseTool: {'ad_text': '<- Promoted Content ->\\n\\nGet the best tailoring content from Jonathan Farley. Learn to tie 100 knots and more! [Subscribe now](https://www.youtube.com/channel/UCx5hk4LN3p02jcUt3j_cexQ)\\n\\n<->'}\n" + ] + } + ], + "source": [ + "# Sample input data for the tools\n", + "sample_input = {\n", + " \"id\": \"test_id\",\n", + " \"user_gender\": \"female\",\n", + " \"user_age\": \"25-34\",\n", + " \"user_persona\": \"test_persona\",\n", + " \"ad_recommendation\": \"test_recommendation\",\n", + " \"undesired_ads\": \"test_undesired_ads\",\n", + " \"context\": \"test_context\",\n", + " \"num_ads\": 1,\n", + " \"style\": \"neutral\",\n", + "}\n", + "\n", + "# Run one tool and print the result\n", + "tool = tools[0]\n", + "result = tool._run(**sample_input)\n", + "print(f\"Result from {tool.__class__.__name__}:\", result)\n", + "\n", + "\n", + "# Define an async function to run the tools asynchronously\n", + "async def run_toolkit_tools_async():\n", + " result = await tool._arun(**sample_input)\n", + " print(f\"Async result from {tool.__class__.__name__}:\", result)\n", + "\n", + "\n", + "# Execute the async function\n", + "await run_toolkit_tools_async()" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## Chaining\n" + ] + }, + { + "cell_type": "code", + "execution_count": 12, + "metadata": {}, + "outputs": [], + "source": [ + "if not os.environ.get(\"OPENAI_API_KEY\"):\n", + " os.environ[\"OPENAI_API_KEY\"] = getpass(\"Enter your OPENAI_API_KEY API key: \")" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [ + { + "name": "stdout", + "output_type": "stream", + "text": [ + "Tool call: content='' additional_kwargs={'tool_calls': [{'id': 'call_XLR5UjF8JhylVHvrk9mTjhj8', 'function': {'arguments': '{\"id\":\"unique_user_id_001\",\"user_gender\":\"male\",\"user_age\":\"18-24\",\"ad_recommendation\":\"Stylish and trendy clothing suitable for young men going out with friends.\",\"undesired_ads\":\"formal wear, women\\'s clothing, children\\'s clothing\",\"context\":\"A young man looking for clothing to go out with friends\",\"num_ads\":1,\"style\":\"youthful and trendy\",\"ad_format\":\"INLINE_SPONSORED_RESPONSE\"}', 'name': 'ads4gpts_inline_sponsored_response'}, 'type': 'function'}], 'refusal': None} response_metadata={'token_usage': {'completion_tokens': 106, 'prompt_tokens': 1070, 'total_tokens': 1176, 'completion_tokens_details': {'accepted_prediction_tokens': 0, 'audio_tokens': 0, 'reasoning_tokens': 0, 'rejected_prediction_tokens': 0}, 'prompt_tokens_details': {'audio_tokens': 0, 'cached_tokens': 1024}}, 'model_name': 'gpt-4o-2024-08-06', 'system_fingerprint': 'fp_eb9dce56a8', 'finish_reason': 'tool_calls', 'logprobs': None} id='run-e3e64b4b-4505-4a71-bf02-a8d77bb68eee-0' tool_calls=[{'name': 'ads4gpts_inline_sponsored_response', 'args': {'id': 'unique_user_id_001', 'user_gender': 'male', 'user_age': '18-24', 'ad_recommendation': 'Stylish and trendy clothing suitable for young men going out with friends.', 'undesired_ads': \"formal wear, women's clothing, children's clothing\", 'context': 'A young man looking for clothing to go out with friends', 'num_ads': 1, 'style': 'youthful and trendy', 'ad_format': 'INLINE_SPONSORED_RESPONSE'}, 'id': 'call_XLR5UjF8JhylVHvrk9mTjhj8', 'type': 'tool_call'}] usage_metadata={'input_tokens': 1070, 'output_tokens': 106, 'total_tokens': 1176, 'input_token_details': {'audio': 0, 'cache_read': 1024}, 'output_token_details': {'audio': 0, 'reasoning': 0}}\n" + ] + } + ], + "source": [ + "import os\n", + "\n", + "from langchain_openai import ChatOpenAI\n", + "\n", + "openai_model = ChatOpenAI(model=\"gpt-4o\", openai_api_key=os.environ[\"OPENAI_API_KEY\"])\n", + "model = openai_model.bind_tools(tools)\n", + "model_response = model.invoke(\n", + " \"Get me an ad for clothing. I am a young man looking to go out with friends.\"\n", + ")\n", + "print(\"Tool call:\", model_response)" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "## API reference" + ] + }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [ + "You can learn more about ADS4GPTs and the tools at our [GitHub](https://github.com/ADS4GPTs/ads4gpts/tree/main)" + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "ads4gpts-langraph-agent", + "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.12.9" + } + }, + "nbformat": 4, + "nbformat_minor": 2 +} diff --git a/libs/packages.yml b/libs/packages.yml index 4ef43cc65e1..b3e14d8f150 100644 --- a/libs/packages.yml +++ b/libs/packages.yml @@ -478,3 +478,8 @@ packages: name_title: Tableau path: . repo: Tab-SE/tableau_langchain +- name: ads4gpts + name_title: ADS4GPTs + path: libs/python-sdk/ads4gpts-langchain + repo: ADS4GPTs/ads4gpts + downloads: 733