mirascope 1.22.2__tar.gz → 1.22.4__tar.gz

{mirascope-1.22.2 → mirascope-1.22.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mirascope
-Version: 1.22.2
+Version: 1.22.4
 Summary: LLM abstractions that aren't obstructions
 Project-URL: Homepage, https://mirascope.com
 Project-URL: Documentation, https://mirascope.com/WELCOME

{mirascope-1.22.2 → mirascope-1.22.4}/docs/generate_provider_examples.py

@@ -20,7 +20,7 @@ PROVIDER_INFO: dict[Provider, ProviderInfo] = {
     ),
     "google": ProviderInfo(provider="google", title="Google", model="gemini-2.0-flash"),
     "groq": ProviderInfo(
-        provider="groq", title="Groq", model="llama-3.1-70b-versatile"
+        provider="groq", title="Groq", model="llama-3.3-70b-versatile"
     ),
     "xai": ProviderInfo(provider="xai", title="xAI", model="grok-3"),
     "mistral": ProviderInfo(

mirascope-1.22.4/docs/tutorials/agents/qwant_search_agent_with_sources.ipynb

@@ -0,0 +1,628 @@
+{
+  "cells": [
+    {
+      "cell_type": "markdown",
+      "id": "72942cd210501f07",
+      "metadata": {
+        "id": "72942cd210501f07"
+      },
+      "source": [
+        "# Qwant Search Agent with Sources\n",
+        "\n",
+        "This notebook tutorial walks through the implementation of a web agent that uses Large Language Models (LLMs) to perform intelligent web searches and extract relevant information. We'll use the Groq API for our LLM calls and the Qwant search engine for web queries.\n",
+        "\n",
+        "<div class=\"admonition tip\">\n",
+        "<p class=\"admonition-title\">Mirascope Concepts Used</p>\n",
+        "<ul>\n",
+        "<li><a href=\"../../../learn/prompts/\">Prompts</a></li>\n",
+        "<li><a href=\"../../../learn/calls/\">Calls</a></li>\n",
+        "<li><a href=\"../../../learn/tools/\">Tools</a></li>\n",
+        "<li><a href=\"../../../learn/chaining/\">Chaining</a></li>\n",
+        "<li><a href=\"../../../learn/response_models/\">Response Model</a></li>\n",
+        "</ul>\n",
+        "</div>\n",
+        "\n",
+        "<div class=\"admonition note\">\n",
+        "<p class=\"admonition-title\">Background</p>\n",
+        "When generating information using LLMs, it's important to note that the generated outputs can often be hallucinated. This remains true even when supplying information from searching the web to the LLM as context for its generation. This makes it extremely important to maintain and include sources alongside the generated output so that the output can be better verified.\n",
+        "</p>\n",
+        "</div>"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "265d41a4",
+      "metadata": {
+        "id": "265d41a4"
+      },
+      "source": [
+        "## Setup\n",
+        "\n",
+        "First, let's install the necessary packages:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "0900d46c",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "0900d46c",
+        "outputId": "1536a4c8-7872-4247-d2c1-5583abcfbaea"
+      },
+      "outputs": [],
+      "source": [
+        "!pip install \"mirascope[groq]\" requests beautifulsoup4 python-dotenv tenacity"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "8bZKRTFK9a1A",
+      "metadata": {
+        "id": "8bZKRTFK9a1A"
+      },
+      "source": [
+        "Now, let's import the required libraries and load our environment variables:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "12637a6d",
+      "metadata": {
+        "id": "12637a6d"
+      },
+      "outputs": [],
+      "source": [
+        "import os\n",
+        "\n",
+        "os.environ[\"GROQ_API_KEY\"] = \"gsk_...\"\n",
+        "# Set the appropriate API key for the provider you're using"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "5046a7fabf14856d",
+      "metadata": {
+        "id": "5046a7fabf14856d"
+      },
+      "outputs": [],
+      "source": [
+        "import re\n",
+        "import time\n",
+        "from typing import Any, Callable\n",
+        "\n",
+        "import requests\n",
+        "from bs4 import BeautifulSoup\n",
+        "from pydantic import BaseModel, Field\n",
+        "from tenacity import retry, stop_after_attempt, wait_exponential\n",
+        "\n",
+        "from mirascope.core import prompt_template\n",
+        "from mirascope.core.groq import groq_call"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "cefac0cfbe3ed78d",
+      "metadata": {
+        "id": "cefac0cfbe3ed78d"
+      },
+      "source": [
+        "\n",
+        "Now that we have created our tool, it’s time to create our LLM call."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "f5f017b5cc3a9433",
+      "metadata": {
+        "id": "f5f017b5cc3a9433"
+      },
+      "source": [
+        "## Qwant API Implementation\n",
+        "\n",
+        "Let's implement the Qwant API class for performing web searches:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "a4da1facf8110830",
+      "metadata": {
+        "id": "a4da1facf8110830"
+      },
+      "outputs": [],
+      "source": [
+        "class QwantApi:\n",
+        "    BASE_URL = \"https://api.qwant.com/v3\"\n",
+        "\n",
+        "    def __init__(self) -> None:\n",
+        "        self.session = requests.Session()\n",
+        "        self.session.headers.update(\n",
+        "            {\n",
+        "                \"User-Agent\": \"Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/117.0.0.0 Safari/537.36\"\n",
+        "            }\n",
+        "        )\n",
+        "\n",
+        "    def search(\n",
+        "        self,\n",
+        "        q: str,\n",
+        "        search_type: str = \"web\",\n",
+        "        locale: str = \"en_US\",\n",
+        "        offset: int = 0,\n",
+        "        safesearch: int = 1,\n",
+        "    ) -> dict[str, Any]:\n",
+        "        params = {\"q\": q, \"locale\": locale, \"offset\": offset, \"safesearch\": safesearch}\n",
+        "        url = f\"{self.BASE_URL}/search/{search_type}\"\n",
+        "        response = self.session.get(url, params=params)\n",
+        "        return response.json() if response.status_code == 200 else None"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "d50ce29b7bb2f566",
+      "metadata": {
+        "id": "d50ce29b7bb2f566"
+      },
+      "source": [
+        "This class encapsulates the functionality to interact with the Qwant search API. It allows us to perform searches of different types (web, news, images, videos) and handles the API request details.\n",
+        "\n",
+        "## Data Models\n",
+        "\n",
+        "Next, let's define our data models using Pydantic:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "9547aff227a1c855",
+      "metadata": {
+        "id": "9547aff227a1c855"
+      },
+      "outputs": [],
+      "source": [
+        "class SearchResponse(BaseModel):\n",
+        "    answer: str = Field(description=\"The answer to the question\")\n",
+        "    sources: list[str] = Field(description=\"The sources used to generate the answer\")\n",
+        "\n",
+        "\n",
+        "class SearchType(BaseModel):\n",
+        "    search_type: str = Field(\n",
+        "        description=\"The type of search to perform (web, news, images, videos)\"\n",
+        "    )\n",
+        "    reasoning: str = Field(description=\"The reasoning behind the search type selection\")\n",
+        "\n",
+        "\n",
+        "class OptimizedQuery(BaseModel):\n",
+        "    query: str = Field(description=\"The optimized search query\")\n",
+        "    reasoning: str = Field(description=\"The reasoning behind the query optimization\")"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "cf7fdb4d371864d7",
+      "metadata": {
+        "id": "cf7fdb4d371864d7"
+      },
+      "source": [
+        "These Pydantic models define the structure for our data:\n",
+        "- `SearchResponse`: Represents the final answer and its sources\n",
+        "- `SearchType`: Represents the chosen search type and the reasoning behind it\n",
+        "- `OptimizedQuery`: Represents an optimized search query and the reasoning for the optimization\n",
+        "\n"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "t5r5S34LEqgy",
+      "metadata": {
+        "id": "t5r5S34LEqgy"
+      },
+      "source": [
+        "## Implement Throttling\n",
+        "\n",
+        "Let's create a decorator for throttling our API calls:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "AulUbUvDEoXL",
+      "metadata": {
+        "id": "AulUbUvDEoXL"
+      },
+      "outputs": [],
+      "source": [
+        "def throttle(calls_per_minute: int) -> Callable:\n",
+        "    min_interval = 60.0 / calls_per_minute\n",
+        "    last_called: list[float] = [0.0]\n",
+        "\n",
+        "    def decorator(func: Callable) -> Callable:\n",
+        "        def wrapper(*args: Any, **kwargs: Any) -> Any:\n",
+        "            elapsed = time.time() - last_called[0]\n",
+        "            left_to_wait = min_interval - elapsed\n",
+        "            if left_to_wait > 0:\n",
+        "                time.sleep(left_to_wait)\n",
+        "            ret = func(*args, **kwargs)\n",
+        "            last_called[0] = time.time()\n",
+        "            return ret\n",
+        "\n",
+        "        return wrapper\n",
+        "\n",
+        "    return decorator\n",
+        "\n",
+        "\n",
+        "# Modify the groq_call decorator to include throttling and retrying\n",
+        "def throttled_groq_call(*args: Any, **kwargs: Any) -> Any:\n",
+        "    @retry(\n",
+        "        wait=wait_exponential(multiplier=1, min=4, max=10), stop=stop_after_attempt(5)\n",
+        "    )\n",
+        "    @throttle(calls_per_minute=6)  # Adjust this value based on your rate limit\n",
+        "    def wrapped_call(*call_args, **call_kwargs):\n",
+        "        return groq_call(*args, **kwargs)(*call_args, **call_kwargs)\n",
+        "\n",
+        "    return wrapped_call"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "-sNNcSg9EzcV",
+      "metadata": {
+        "id": "-sNNcSg9EzcV"
+      },
+      "source": [
+        "## Determine Search Type\n",
+        "\n",
+        "Now, let's implement the function to determine the most appropriate search type:\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "zIAxRLSs_awu",
+      "metadata": {
+        "id": "zIAxRLSs_awu"
+      },
+      "outputs": [],
+      "source": [
+        "@throttled_groq_call(\n",
+        "    \"llama-3.3-70b-versatile\", response_model=SearchType, json_mode=True\n",
+        ")\n",
+        "@prompt_template(\n",
+        "    \"\"\"\n",
+        "SYSTEM:\n",
+        "You are an expert at determining the most appropriate type of search for a given query. Your task is to analyze the user's question and decide which Qwant search type to use: web, news, images, or videos.\n",
+        "\n",
+        "Follow these strict guidelines:\n",
+        "1. For general information queries, use 'web'.\n",
+        "2. For recent events, breaking news, or time-sensitive information, use 'news'.\n",
+        "3. For queries explicitly asking for images or visual content, use 'images'.\n",
+        "4. For queries about video content or asking for video results, use 'videos'.\n",
+        "5. If unsure, default to 'web'.\n",
+        "\n",
+        "Provide your decision in a structured format with the search type and a brief explanation of your reasoning.\n",
+        "\n",
+        "USER:\n",
+        "Determine the most appropriate search type for the following question:\n",
+        "{question}\n",
+        "\n",
+        "ASSISTANT:\n",
+        "Based on the question, I will determine the most appropriate search type and provide my reasoning.\n",
+        "\"\"\"\n",
+        ")\n",
+        "def determine_search_type(question: str) -> SearchType:\n",
+        "    \"\"\"\n",
+        "    Determine the most appropriate search type for the given question.\n",
+        "    \"\"\"\n",
+        "    ..."
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "7N3A3Omn_kwX",
+      "metadata": {
+        "id": "7N3A3Omn_kwX"
+      },
+      "source": [
+        "This function uses the Groq API to determine the most appropriate search type based on the user's question. It uses a prompt template to guide the LLM in making this decision.\n",
+        "\n",
+        "## Web Search Function\n",
+        "\n",
+        "Let's implement the function to perform the actual web search using Qwant:\n"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "ehaHwHhD_atf",
+      "metadata": {
+        "id": "ehaHwHhD_atf"
+      },
+      "outputs": [],
+      "source": [
+        "def qwant_search(query: str, search_type: str, max_results: int = 5) -> dict[str, str]:\n",
+        "    \"\"\"\n",
+        "    Use Qwant to get information about the query using the specified search type.\n",
+        "    \"\"\"\n",
+        "    print(f\"Searching Qwant for '{query}' using {search_type} search...\")\n",
+        "    search_results = {}\n",
+        "    qwant = QwantApi()\n",
+        "    results = qwant.search(query, search_type=search_type)\n",
+        "\n",
+        "    if (\n",
+        "        results\n",
+        "        and \"data\" in results\n",
+        "        and \"result\" in results[\"data\"]\n",
+        "        and \"items\" in results[\"data\"][\"result\"]\n",
+        "    ):\n",
+        "        items = results[\"data\"][\"result\"][\"items\"]\n",
+        "        if isinstance(items, dict) and \"mainline\" in items:\n",
+        "            items = items[\"mainline\"]\n",
+        "\n",
+        "        count = 0\n",
+        "        for item in items:\n",
+        "            if \"url\" in item:\n",
+        "                url = item[\"url\"]\n",
+        "                print(f\"Fetching content from {url}...\")\n",
+        "                content = get_content(url)\n",
+        "                search_results[url] = content\n",
+        "                count += 1\n",
+        "                if count >= max_results:\n",
+        "                    break\n",
+        "            elif isinstance(item, dict) and \"items\" in item:\n",
+        "                for subitem in item[\"items\"]:\n",
+        "                    if \"url\" in subitem:\n",
+        "                        url = subitem[\"url\"]\n",
+        "                        print(f\"Fetching content from {url}...\")\n",
+        "                        content = get_content(url)\n",
+        "                        search_results[url] = content\n",
+        "                        count += 1\n",
+        "                        if count >= max_results:\n",
+        "                            break\n",
+        "                if count >= max_results:\n",
+        "                    break\n",
+        "\n",
+        "    return search_results\n",
+        "\n",
+        "\n",
+        "def get_content(url: str) -> str:\n",
+        "    \"\"\"\n",
+        "    Fetch and parse content from a URL.\n",
+        "    \"\"\"\n",
+        "    data = []\n",
+        "    try:\n",
+        "        response = requests.get(url)\n",
+        "        content = response.content\n",
+        "        soup = BeautifulSoup(content, \"html.parser\")\n",
+        "        paragraphs = soup.find_all(\"p\")\n",
+        "        for paragraph in paragraphs:\n",
+        "            data.append(paragraph.text)\n",
+        "    except Exception as e:\n",
+        "        print(f\"Error fetching content from {url}: {e}\")\n",
+        "    return \"\\n\".join(data)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "VTi5G9Ze_wWK",
+      "metadata": {
+        "id": "VTi5G9Ze_wWK"
+      },
+      "source": [
+        "These functions handle the web search process:\n",
+        "- `qwant_search`: Performs the search using the Qwant API and fetches content from the resulting URLs\n",
+        "- `get_content`: Fetches and parses the content from a given URL using BeautifulSoup\n",
+        "\n",
+        "## Search and Extract Functions\n",
+        "\n",
+        "Now, let's implement the functions to process the search results and extract the final answer:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "lzHfWYDy_aql",
+      "metadata": {
+        "id": "lzHfWYDy_aql"
+      },
+      "outputs": [],
+      "source": [
+        "@groq_call(\"llama-3.3-70b-versatile\")\n",
+        "@prompt_template(\n",
+        "    \"\"\"\n",
+        "SYSTEM:\n",
+        "You are an expert at finding information on the web.\n",
+        "Use the provided search results to answer the question.\n",
+        "Rewrite the question as needed to better find information on the web.\n",
+        "Search results:\n",
+        "{search_results}\n",
+        "\n",
+        "USER:\n",
+        "{question}\n",
+        "\"\"\"\n",
+        ")\n",
+        "def search(question: str, search_results: dict[str, str]) -> str:\n",
+        "    \"\"\"\n",
+        "    Use the search results to answer the user's question.\n",
+        "    \"\"\"\n",
+        "    # The model will return an answer based on the search results and question\n",
+        "    ...\n",
+        "\n",
+        "\n",
+        "@throttled_groq_call(\n",
+        "    \"llama-3.3-70b-versatile\", response_model=SearchResponse, json_mode=True\n",
+        ")  # Changed response_model from SearchType to SearchResponse\n",
+        "@prompt_template(\n",
+        "    \"\"\"\n",
+        "SYSTEM:\n",
+        "Extract the answer to the question based on the search results.\n",
+        "Provide the sources used to answer the question in a structured format.\n",
+        "Search results:\n",
+        "{results}\n",
+        "\n",
+        "USER:\n",
+        "{question}\n",
+        "\"\"\"\n",
+        ")\n",
+        "def extract(\n",
+        "    question: str, results: dict[str, str]\n",
+        ") -> SearchResponse:  # This function should return SearchResponse, not SearchType\n",
+        "    \"\"\"\n",
+        "    Extract a concise answer from the search results and include sources.\n",
+        "    \"\"\"\n",
+        "    ...\n",
+        "\n",
+        "\n",
+        "def clean_text(text: str) -> str:\n",
+        "    \"\"\"\n",
+        "    Clean the text data for better formatting and readability.\n",
+        "    \"\"\"\n",
+        "    # Removing extra spaces and special characters\n",
+        "    return re.sub(r\"\\s+\", \" \", text).strip()"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "TqBdXgx6AN6C",
+      "metadata": {
+        "id": "TqBdXgx6AN6C"
+      },
+      "source": [
+        "These functions process the search results:\n",
+        "- `search`: Uses the Groq API to generate an answer based on the search results\n",
+        "- `extract`: Extracts a concise answer and the sources used from the search results\n",
+        "- `clean_text`: Cleans the text output for better readability\n",
+        "\n",
+        "## Main Execution Function\n",
+        "\n",
+        "Finally, let's implement the main execution function that orchestrates the entire process:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "MENSypsI_adf",
+      "metadata": {
+        "id": "MENSypsI_adf"
+      },
+      "outputs": [],
+      "source": [
+        "def run(question: str) -> SearchResponse:\n",
+        "    \"\"\"\n",
+        "    Orchestrate the search and extraction process to answer the user's question.\n",
+        "    \"\"\"\n",
+        "    print(f\"Processing question: '{question}'\")\n",
+        "\n",
+        "    # Step 1: Determine the appropriate search type\n",
+        "    search_type_result = determine_search_type(question)\n",
+        "    print(f\"Selected search type: {search_type_result.search_type}\")\n",
+        "    print(f\"Reasoning: {search_type_result.reasoning}\")\n",
+        "\n",
+        "    # Step 2: Search the web using Qwant with the determined search type\n",
+        "    search_results = qwant_search(question, search_type_result.search_type)\n",
+        "\n",
+        "    # Step 3: Use Groq Llama model to summarize search results\n",
+        "    response = search(question, search_results)\n",
+        "    print(f\"Search response: {response}\")\n",
+        "\n",
+        "    # Step 4: Extract the final answer and structured sources\n",
+        "    result = extract(question, search_results)\n",
+        "\n",
+        "    # Step 5: Clean the output for readability\n",
+        "    result.answer = clean_text(result.answer)\n",
+        "    print(f\"Final result: {result}\")\n",
+        "\n",
+        "    return result"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "5aS7xS8tAY-g",
+      "metadata": {
+        "id": "5aS7xS8tAY-g"
+      },
+      "source": [
+        "This `run` function orchestrates the entire process:\n",
+        "1. Determines the appropriate search type\n",
+        "2. Performs the web search\n",
+        "3. Summarizes the search results\n",
+        "4. Extracts the final answer and sources\n",
+        "5. Cleans the output for readability\n",
+        "\n",
+        "## Usage Example\n",
+        "\n",
+        "Let's add an example usage of our web agent:"
+      ]
+    },
+    {
+      "cell_type": "code",
+      "execution_count": null,
+      "id": "lE9AgrS8AeBw",
+      "metadata": {
+        "colab": {
+          "base_uri": "https://localhost:8080/"
+        },
+        "id": "lE9AgrS8AeBw",
+        "outputId": "28403e08-8d0e-4724-d507-fb6e4078f9e8"
+      },
+      "outputs": [],
+      "source": [
+        "if __name__ == \"__main__\":\n",
+        "    print(\"Example usage:\")\n",
+        "    response = run(\"what is the latest on donald trump and elon musk?\")\n",
+        "    print(response)"
+      ]
+    },
+    {
+      "cell_type": "markdown",
+      "id": "W9gAg2IFAjgR",
+      "metadata": {
+        "id": "W9gAg2IFAjgR"
+      },
+      "source": [
+        "This example demonstrates how to use the `run` function to process a question and get a response.\n",
+        "\n",
+        "## Conclusion\n",
+        "\n",
+        "This notebook tutorial has walked through the implementation of a web agent that uses LLMs to perform intelligent web searches and extract relevant information. The agent determines the most appropriate search type, performs the search, processes the results, and provides a structured response with sources.\n",
+        "\n",
+        "Key components of this implementation include:\n",
+        "1. Qwant API integration for web searches\n",
+        "2. Groq API integration for LLM-powered decision making and information extraction\n",
+        "3. Pydantic models for structured data handling\n",
+        "4. Implemented retry logic with exponential backoff using the tenacity library.\n",
+        "5. BeautifulSoup for web scraping\n",
+        "6. Prompt engineering for guiding LLM behavior\n",
+        "\n",
+        "This web agent can be extended and customized for various applications, such as research assistants, fact-checking tools, or automated information gathering systems."
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "provenance": []
+    },
+    "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
+}