![\"License\"](\"https://img.shields.io/github/license/huggingface/smolagents.svg?color=blue\")
\n ![\"Documentation\"](\"https://img.shields.io/website/http/huggingface.co/docs/smolagents/index.html.svg?down_color=red&down_message=offline&up_message=online\")
\n ![\"GitHub](\"https://img.shields.io/github/release/huggingface/smolagents.svg\")
\n ![\"Contributor](\"https://img.shields.io/badge/Contributor%20Covenant-v2.0%20adopted-ff69b4.svg\"){kind=icon}
\n ![\"Ask](\"https://deepwiki.com/badge.svg\"){kind=icon}
\n\n \n \n \n \n \n \n
![\"Hugging](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/smolagents.png\")
\n Agents that think in code!
\n\n ![\"benchmark](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/benchmark_code_agents.jpeg\")
\n
![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/Agent_ManimCE.gif\"/)
\n![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/code_vs_json_actions.png\")
\n\nWriting actions in code rather than JSON-like snippets provides better:\n\n- **Composability:** could you nest JSON actions within each other, or define a set of JSON actions to re-use later, the same way you could just define a python function?\n- **Object management:** how do you store the output of an action like `generate_image` in JSON?\n- **Generality:** code is built to express simply anything you can have a computer do.\n- **Representation in LLM training data:** plenty of quality code actions are already included in LLMs’ training data which means they’re already trained for this!\n"
},
{
"path": "docs/source/en/conceptual_guides/react.md",
"content": "# How do multi-step agents work?\n\nThe ReAct framework ([Yao et al., 2022](https://huggingface.co/papers/2210.03629)) is currently the main approach to building agents.\n\nThe name is based on the concatenation of two words, \"Reason\" and \"Act.\" Indeed, agents following this architecture will solve their task in as many steps as needed, each step consisting of a Reasoning step, then an Action step where it formulates tool calls that will bring it closer to solving the task at hand.\n\nAll agents in `smolagents` are based on singular `MultiStepAgent` class, which is an abstraction of ReAct framework.\n\nOn a basic level, this class performs actions on a cycle of following steps, where existing variables and knowledge is incorporated into the agent logs like below: \n\nInitialization: the system prompt is stored in a `SystemPromptStep`, and the user query is logged into a `TaskStep` .\n\nWhile loop (ReAct loop):\n\n- Use `agent.write_memory_to_messages()` to write the agent logs into a list of LLM-readable [chat messages](https://huggingface.co/docs/transformers/en/chat_templating).\n- Send these messages to a `Model` object to get its completion. Parse the completion to get the action (a JSON blob for `ToolCallingAgent`, a code snippet for `CodeAgent`).\n- Execute the action and logs result into memory (an `ActionStep`).\n- At the end of each step, we run all callback functions defined in `agent.step_callbacks` .\n\nOptionally, when planning is activated, a plan can be periodically revised and stored in a `PlanningStep` . This includes feeding facts about the task at hand to the memory.\n\nFor a `CodeAgent`, it looks like the figure below.\n\n![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/license_to_call.png\")
\nLearn the basics and become familiar with using Agents. Start here if you are using Agents for the first time!
\n \nPractical guides to help you achieve a specific goal: create an agent to generate and test SQL queries!
\n \nHigh-level explanations for building a better understanding of important topics.
\n \nHorizontal tutorials that cover important aspects of building agents.
\n \n![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/inspect_run_phoenix.gif\"/)
\n![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/inspect_run_phoenix.png\")
\n\nYou can see that the CodeAgent called its managed ToolCallingAgent (by the way, the managed agent could have been a CodeAgent as well) to ask it to run the web search for the U.S. 2024 growth rate. Then the managed agent returned its report and the manager agent acted upon it to calculate the economy doubling time! Sweet, isn't it?\n\n## Setting up telemetry with MLflow\n\nMLflow has one-line autologging for Smolagents: it tracks runs, spans, inputs/outputs, and token usage in the MLflow UI.\n\nInstall MLflow, enable autologging, then run your agent with a couple of tools:\n\n```python\n%pip install mlflow smolagents\n\nimport mlflow\nfrom smolagents import CodeAgent, ToolCallingAgent, WebSearchTool, VisitWebpageTool, InferenceClientModel\n\nmlflow.smolagents.autolog() # start tracing everything below\n\nmodel = InferenceClientModel()\nbrowser = ToolCallingAgent(\n tools=[WebSearchTool(), VisitWebpageTool()],\n model=model,\n name=\"search_agent\",\n description=\"Web search helper\",\n)\nmanager = CodeAgent(model=model, managed_agents=[browser])\nmanager.run(\"Find the latest US GDP growth rate and estimate when it would double.\")\n```\n\nStart the UI to inspect traces, then open the Traces view in your browser:\n\n```shell\nmlflow server --port 5000\n```\n\n## Setting up telemetry with 🪢 Langfuse\n\nThis part shows how to monitor and debug your Hugging Face **smolagents** with **Langfuse** using the `SmolagentsInstrumentor`.\n\n> **What is Langfuse?** [Langfuse](https://langfuse.com) is an open-source platform for LLM engineering. It provides tracing and monitoring capabilities for AI agents, helping developers debug, analyze, and optimize their products. Langfuse integrates with various tools and frameworks via native integrations, OpenTelemetry, and SDKs.\n\n### Step 1: Install Dependencies\n\n```python\n%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents\n```\n\n### Step 2: Set Up Environment Variables\n\nSet your Langfuse API keys and configure the OpenTelemetry endpoint to send traces to Langfuse. Get your Langfuse API keys by signing up for [Langfuse Cloud](https://cloud.langfuse.com) or [self-hosting Langfuse](https://langfuse.com/self-hosting).\n\nAlso, add your [Hugging Face token](https://huggingface.co/settings/tokens) (`HF_TOKEN`) as an environment variable.\n\n```python\nimport os\n# Get keys for your project from the project settings page: https://cloud.langfuse.com\nos.environ[\"LANGFUSE_PUBLIC_KEY\"] = \"pk-lf-...\" \nos.environ[\"LANGFUSE_SECRET_KEY\"] = \"sk-lf-...\" \nos.environ[\"LANGFUSE_HOST\"] = \"https://cloud.langfuse.com\" # 🇪🇺 EU region\n# os.environ[\"LANGFUSE_HOST\"] = \"https://us.cloud.langfuse.com\" # 🇺🇸 US region\n \n# your Hugging Face token\nos.environ[\"HF_TOKEN\"] = \"hf_...\"\n```\n\nWith the environment variables set, we can now initialize the Langfuse client. `get_client()` initializes the Langfuse client using the credentials provided in the environment variables.\n\n```python\nfrom langfuse import get_client\n \nlangfuse = get_client()\n \n# Verify connection\nif langfuse.auth_check():\n print(\"Langfuse client is authenticated and ready!\")\nelse:\n print(\"Authentication failed. Please check your credentials and host.\")\n```\n\n### Step 3: Initialize the `SmolagentsInstrumentor`\n\nInitialize the `SmolagentsInstrumentor` before your application code. \n\n\n```python\nfrom openinference.instrumentation.smolagents import SmolagentsInstrumentor\n \nSmolagentsInstrumentor().instrument()\n```\n\n### Step 4: Run your smolagent\n\n```python\nfrom smolagents import (\n CodeAgent,\n ToolCallingAgent,\n WebSearchTool,\n VisitWebpageTool,\n InferenceClientModel,\n)\n\nmodel = InferenceClientModel(\n model_id=\"deepseek-ai/DeepSeek-R1-Distill-Qwen-32B\"\n)\n\nsearch_agent = ToolCallingAgent(\n tools=[WebSearchTool(), VisitWebpageTool()],\n model=model,\n name=\"search_agent\",\n description=\"This is an agent that can do web search.\",\n)\n\nmanager_agent = CodeAgent(\n tools=[],\n model=model,\n managed_agents=[search_agent],\n)\nmanager_agent.run(\n \"How can Langfuse be used to monitor and improve the reasoning and decision-making of smolagents when they execute multi-step tasks, like dynamically adjusting a recipe based on user feedback or available ingredients?\"\n)\n```\n\n### Step 5: View Traces in Langfuse\n\nAfter running the agent, you can view the traces generated by your smolagents application in [Langfuse](https://cloud.langfuse.com). You should see detailed steps of the LLM interactions, which can help you debug and optimize your AI agent.\n\n\n\n_[Public example trace in Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_\n"
},
{
"path": "docs/source/en/tutorials/memory.md",
"content": "# 📚 Manage your agent's memory\n\n[[open-in-colab]]\n\nIn the end, an agent can be defined by simple components: it has tools, prompts.\nAnd most importantly, it has a memory of past steps, drawing a history of planning, execution, and errors.\n\n### Replay your agent's memory\n\nWe propose several features to inspect a past agent run.\n\nYou can instrument the agent's run to display it in a great UI that lets you zoom in/out on specific steps, as highlighted in the [instrumentation guide](./inspect_runs).\n\nYou can also use `agent.replay()`, as follows:\n\nAfter the agent has run:\n```py\nfrom smolagents import InferenceClientModel, CodeAgent\n\nagent = CodeAgent(tools=[], model=InferenceClientModel(), verbosity_level=0)\n\nresult = agent.run(\"What's the 20th Fibonacci number?\")\n```\n\nIf you want to replay this last run, just use:\n```py\nagent.replay()\n```\n\n### Dynamically change the agent's memory\n\nMany advanced use cases require dynamic modification of the agent's memory.\n\nYou can access the agent's memory using:\n\n```py\nfrom smolagents import ActionStep\n\nsystem_prompt_step = agent.memory.system_prompt\nprint(\"The system prompt given to the agent was:\")\nprint(system_prompt_step.system_prompt)\n\ntask_step = agent.memory.steps[0]\nprint(\"\\n\\nThe first task step was:\")\nprint(task_step.task)\n\nfor step in agent.memory.steps:\n if isinstance(step, ActionStep):\n if step.error is not None:\n print(f\"\\nStep {step.step_number} got this error:\\n{step.error}\\n\")\n else:\n print(f\"\\nStep {step.step_number} got these observations:\\n{step.observations}\\n\")\n```\n\nUse `agent.memory.get_full_steps()` to get full steps as dictionaries.\n\nYou can also use step callbacks to dynamically change the agent's memory.\n\nStep callbacks can access the `agent` itself in their arguments, so they can access any memory step as highlighted above, and change it if needed. For instance, let's say you are observing screenshots of each step performed by a web browser agent. You want to log the newest screenshot, and remove the images from ancient steps to save on token costs.\n\nYou could run something like the following.\n_Note: this code is incomplete, some imports and object definitions have been removed for the sake of concision, visit [the original script](https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py) to get the full working code._\n\n```py\nimport helium\nfrom PIL import Image\nfrom io import BytesIO\nfrom time import sleep\n\ndef update_screenshot(memory_step: ActionStep, agent: CodeAgent) -> None:\n sleep(1.0) # Let JavaScript animations happen before taking the screenshot\n driver = helium.get_driver()\n latest_step = memory_step.step_number\n for previous_memory_step in agent.memory.steps: # Remove previous screenshots from logs for lean processing\n if isinstance(previous_memory_step, ActionStep) and previous_memory_step.step_number <= latest_step - 2:\n previous_memory_step.observations_images = None\n png_bytes = driver.get_screenshot_as_png()\n image = Image.open(BytesIO(png_bytes))\n memory_step.observations_images = [image.copy()]\n```\n\nThen you should pass this function in the `step_callbacks` argument upon initialization of your agent:\n\n```py\nCodeAgent(\n tools=[WebSearchTool(), go_back, close_popups, search_item_ctrl_f],\n model=model,\n additional_authorized_imports=[\"helium\"],\n step_callbacks=[update_screenshot],\n max_steps=20,\n verbosity_level=2,\n)\n```\n\nHead to our [vision web browser code](https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py) to see the full working example.\n\n### Run agents one step at a time\n\nThis can be useful in case you have tool calls that take days: you can just run your agents step by step.\nThis will also let you update the memory on each step.\n\n```py\nfrom smolagents import InferenceClientModel, CodeAgent, ActionStep, TaskStep\n\nagent = CodeAgent(tools=[], model=InferenceClientModel(), verbosity_level=1)\nagent.python_executor.send_tools({**agent.tools})\nprint(agent.memory.system_prompt)\n\ntask = \"What is the 20th Fibonacci number?\"\n\n# You could modify the memory as needed here by inputting the memory of another agent.\n# agent.memory.steps = previous_agent.memory.steps\n\n# Let's start a new task!\nagent.memory.steps.append(TaskStep(task=task, task_images=[]))\n\nfinal_answer = None\nstep_number = 1\nwhile final_answer is None and step_number <= 10:\n memory_step = ActionStep(\n step_number=step_number,\n observations_images=[],\n )\n # Run one step.\n final_answer = agent.step(memory_step)\n agent.memory.steps.append(memory_step)\n step_number += 1\n\n # Change the memory as you please!\n # For instance to update the latest step:\n # agent.memory.steps[-1] = ...\n\nprint(\"The final answer is:\", final_answer)\n```\n"
},
{
"path": "docs/source/en/tutorials/secure_code_execution.md",
"content": "# Secure code execution\n\n[[open-in-colab]]\n\n> [!TIP]\n> If you're new to building agents, make sure to first read the [intro to agents](../conceptual_guides/intro_agents) and the [guided tour of smolagents](../guided_tour).\n\n### Code agents\n\n[Multiple](https://huggingface.co/papers/2402.01030) [research](https://huggingface.co/papers/2411.01747) [papers](https://huggingface.co/papers/2401.00812) have shown that having the LLM write its actions (the tool calls) in code is much better than the current standard format for tool calling, which is across the industry different shades of \"writing actions as a JSON of tools names and arguments to use\".\n\nWhy is code better? Well, because we crafted our code languages specifically to be great at expressing actions performed by a computer. If JSON snippets were a better way, this package would have been written in JSON snippets and the devil would be laughing at us.\n\nCode is just a better way to express actions on a computer. It has better:\n- **Composability:** could you nest JSON actions within each other, or define a set of JSON actions to re-use later, the same way you could just define a python function?\n- **Object management:** how do you store the output of an action like `generate_image` in JSON?\n- **Generality:** code is built to express simply anything you can have a computer do.\n- **Representation in LLM training corpus:** why not leverage this benediction of the sky that plenty of quality actions have already been included in LLM training corpus?\n\nThis is illustrated on the figure below, taken from [Executable Code Actions Elicit Better LLM Agents](https://huggingface.co/papers/2402.01030).\n\n\n\nThis is why we put emphasis on proposing code agents, in this case python agents, which meant putting higher effort on building secure python interpreters.\n\n### Local code execution??\n\nBy default, the `CodeAgent` runs LLM-generated code in your environment.\n\nThis is inherently risky, LLM-generated code could be harmful to your environment.\n\nMalicious code execution can occur in several ways:\n- **Plain LLM error:** LLMs are still far from perfect and may unintentionally generate harmful commands while attempting to be helpful. While this risk is low, instances have been observed where an LLM attempted to execute potentially dangerous code. \n- **Supply chain attack:** Running an untrusted or compromised LLM could expose a system to harmful code generation. While this risk is extremely low when using well-known models on secure inference infrastructure, it remains a theoretical possibility. \n- **Prompt injection:** an agent browsing the web could arrive on a malicious website that contains harmful instructions, thus injecting an attack into the agent's memory\n- **Exploitation of publicly accessible agents:** Agents exposed to the public can be misused by malicious actors to execute harmful code. Attackers may craft adversarial inputs to exploit the agent's execution capabilities, leading to unintended consequences.\nOnce malicious code is executed, whether accidentally or intentionally, it can damage the file system, exploit local or cloud-based resources, abuse API services, and even compromise network security.\n\nOne could argue that on the [spectrum of agency](../conceptual_guides/intro_agents), code agents give much higher agency to the LLM on your system than other less agentic setups: this goes hand-in-hand with higher risk.\n\nSo you need to be very mindful of security.\n\nTo improve safety, we propose a range of measures that propose elevated levels of security, at a higher setup cost.\n\nWe advise you to keep in mind that no solution will be 100% safe.\n\n![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/code_execution_safety_diagram.png\")
\n\n### Our local Python executor\n\nTo add a first layer of security, code execution in `smolagents` is not performed by the vanilla Python interpreter.\nWe have re-built a more secure `LocalPythonExecutor` from the ground up.\n\nTo be precise, this interpreter works by loading the Abstract Syntax Tree (AST) from your Code and executes it operation by operation, making sure to always follow certain rules:\n- By default, imports are disallowed unless they have been explicitly added to an authorization list by the user.\n- Furthermore, access to submodules is disabled by default, and each must be explicitly authorized in the import list as well, or you can pass for instance `numpy.*` to allow both `numpy` and all its subpackags, like `numpy.random` or `numpy.a.b`.\n - Note that some seemingly innocuous packages like `random` can give access to potentially harmful submodules, as in `random._os`.\n- The total count of elementary operations processed is capped to prevent infinite loops and resource bloating.\n- Any operation that has not been explicitly defined in our custom interpreter will raise an error.\n\nYou could try these safeguards as follows:\n\n```py\nfrom smolagents.local_python_executor import LocalPythonExecutor\n\n# Set up custom executor, authorize package \"numpy\"\ncustom_executor = LocalPythonExecutor([\"numpy\"])\n\n# Utility for pretty printing errors\ndef run_capture_exception(command: str):\n try:\n custom_executor(harmful_command)\n except Exception as e:\n print(\"ERROR:\\n\", e)\n\n# Undefined command just do not work\nharmful_command=\"!echo Bad command\"\nrun_capture_exception(harmful_command)\n# >>> ERROR: invalid syntax (\n ![\"sandboxed](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/smolagents/sandboxed_execution.png\")
\n
![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/sunny_beach.webp\")
\n\nThen you can use this tool just like any other tool. For example, let's improve the prompt `a rabbit wearing a space suit` and generate an image of it. This example also shows how you can pass additional arguments to the agent.\n\n```python\nfrom smolagents import CodeAgent, InferenceClientModel\n\nmodel = InferenceClientModel(model_id=\"Qwen/Qwen3-Next-80B-A3B-Thinking\")\nagent = CodeAgent(tools=[image_generation_tool], model=model)\n\nagent.run(\n \"Improve this prompt, then generate an image of it.\", additional_args={'user_prompt': 'A rabbit wearing a space suit'}\n)\n```\n\n```text\n=== Agent thoughts:\nimproved_prompt could be \"A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background\"\n\nNow that I have improved the prompt, I can use the image generator tool to generate an image based on this prompt.\n>>> Agent is executing the code below:\nimage = image_generator(prompt=\"A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background\")\nfinal_answer(image)\n```\n\n![](\"https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/rabbit_spacesuit_flux.webp\")
\n\nHow cool is this? 🤩\n\n### Use LangChain tools\n\nWe love Langchain and think it has a very compelling suite of tools.\nTo import a tool from LangChain, use the `from_langchain()` method.\n\nHere is how you can use it to recreate the intro's search result using a LangChain web search tool.\nThis tool will need `pip install langchain google-search-results -q` to work properly.\n```python\nfrom langchain.agents import load_tools\n\nsearch_tool = Tool.from_langchain(load_tools([\"serpapi\"])[0])\n\nagent = CodeAgent(tools=[search_tool], model=model)\n\nagent.run(\"How many more blocks (also denoted as layers) are in BERT base encoder compared to the encoder from the architecture proposed in Attention is All You Need?\")\n```\n\n### Manage your agent's toolbox\n\nYou can manage an agent's toolbox by adding or replacing a tool in attribute `agent.tools`, since it is a standard dictionary.\n\nLet's add the `model_download_tool` to an existing agent initialized with only the default toolbox.\n\n```python\nfrom smolagents import InferenceClientModel\n\nmodel = InferenceClientModel(model_id=\"Qwen/Qwen3-Next-80B-A3B-Thinking\")\n\nagent = CodeAgent(tools=[], model=model, add_base_tools=True)\nagent.tools[model_download_tool.name] = model_download_tool\n```\nNow we can leverage the new tool:\n\n```python\nagent.run(\n \"Can you give me the name of the model that has the most downloads in the 'text-to-video' task on the Hugging Face Hub but reverse the letters?\"\n)\n```\n\n\n> [!TIP]\n> Beware of not adding too many tools to an agent: this can overwhelm weaker LLM engines.\n\n\n### Use a collection of tools\n\nYou can leverage tool collections by using [`ToolCollection`]. It supports loading either a collection from the Hub or an MCP server tools.\n\n\n#### Tool Collection from any MCP server\n\nLeverage tools from the hundreds of MCP servers available on [glama.ai](https://glama.ai/mcp/servers) or [smithery.ai](https://smithery.ai/).\n\nThe MCP servers tools can be loaded with [`ToolCollection.from_mcp`].\n\n> [!WARNING]\n> **Security Warning:** Always verify the source and integrity of any MCP server before connecting to it, especially for production environments.\n> Using MCP servers comes with security risks:\n> - **Trust is essential:** Only use MCP servers from trusted sources. Malicious servers can execute harmful code on your machine.\n> - **Stdio-based MCP servers** will always execute code on your machine (that's their intended functionality).\n> - **Streamable HTTP-based MCP servers:** While remote MCP servers will not execute code on your machine, still proceed with caution.\n\nFor stdio-based MCP servers, pass the server parameters as an instance of `mcp.StdioServerParameters`:\n```py\nfrom smolagents import ToolCollection, CodeAgent\nfrom mcp import StdioServerParameters\n\nserver_parameters = StdioServerParameters(\n command=\"uvx\",\n args=[\"--quiet\", \"pubmedmcp@0.1.3\"],\n env={\"UV_PYTHON\": \"3.12\", **os.environ},\n)\n\nwith ToolCollection.from_mcp(server_parameters, trust_remote_code=True) as tool_collection:\n agent = CodeAgent(tools=[*tool_collection.tools], model=model, add_base_tools=True)\n agent.run(\"Please find a remedy for hangover.\")\n```\n\nTo enable structured output support with ToolCollection, add the `structured_output=True` parameter:\n```py\nwith ToolCollection.from_mcp(server_parameters, trust_remote_code=True, structured_output=True) as tool_collection:\n agent = CodeAgent(tools=[*tool_collection.tools], model=model, add_base_tools=True)\n agent.run(\"Please find a remedy for hangover.\")\n```\n\nFor Streamable HTTP-based MCP servers, simply pass a dict with parameters to `mcp.client.streamable_http.streamablehttp_client` and add the key `transport` with the value `\"streamable-http\"`:\n```py\nfrom smolagents import ToolCollection, CodeAgent\n\nwith ToolCollection.from_mcp({\"url\": \"http://127.0.0.1:8000/mcp\", \"transport\": \"streamable-http\"}, trust_remote_code=True) as tool_collection:\n agent = CodeAgent(tools=[*tool_collection.tools], add_base_tools=True)\n agent.run(\"Please find a remedy for hangover.\")\n```\n\n#### Tool Collection from a collection in the Hub\n\nYou can leverage it with the slug of the collection you want to use.\nThen pass them as a list to initialize your agent, and start using them!\n\n```py\nfrom smolagents import ToolCollection, CodeAgent\n\nimage_tool_collection = ToolCollection.from_hub(\n collection_slug=\"huggingface-tools/diffusion-tools-6630bb19a942c2306a2cdb6f\",\n token=\"\nDomina los conceptos básicos y aprende a manejar agentes. Empieza aquí si nunca los has utilizado.
\n \nEjemplos prácticos para guiarte en diferentes proyectos. ¡Desarrolla un agente que genere y valide consultas SQL!
\n \nConceptos avanzados para profundizar en la comprensión de temas clave.
\n \nTutoriales completos que cubren aspectos clave para el desarrollo de agentes.
\n \n\n\nJSON जैसे स्निपेट्स की बजाय कोड में क्रियाएं लिखने से बेहतर प्राप्त होता है:\n\n- **कम्पोजेबिलिटी:** क्या आप JSON क्रियाओं को एक-दूसरे के भीतर नेस्ट कर सकते हैं, या बाद में पुन: उपयोग करने के लिए JSON क्रियाओं का एक सेट परिभाषित कर सकते हैं, उसी तरह जैसे आप बस एक पायथन फंक्शन परिभाषित कर सकते हैं?\n- **ऑब्जेक्ट प्रबंधन:** आप `generate_image` जैसी क्रिया के आउटपुट को JSON में कैसे स्टोर करते हैं?\n- **सामान्यता:** कोड को सरल रूप से कुछ भी व्यक्त करने के लिए बनाया गया है जो आप कंप्यूटर से करवा सकते हैं।\n- **LLM प्रशिक्षण डेटा में प्रतिनिधित्व:** बहुत सारी गुणवत्तापूर्ण कोड क्रियाएं पहले से ही LLM के ट्रेनिंग डेटा में शामिल हैं जिसका मतलब है कि वे इसके लिए पहले से ही प्रशिक्षित हैं!"
},
{
"path": "docs/source/hi/conceptual_guides/react.md",
"content": "# मल्टी-स्टेप एजेंट्स कैसे काम करते हैं?\n\nReAct फ्रेमवर्क ([Yao et al., 2022](https://huggingface.co/papers/2210.03629)) वर्तमान में एजेंट्स बनाने का मुख्य दृष्टिकोण है।\n\nनाम दो शब्दों, \"Reason\" (तर्क) और \"Act\" (क्रिया) के संयोजन पर आधारित है। वास्तव में, इस आर्किटेक्चर का पालन करने वाले एजेंट अपने कार्य को उतने चरणों में हल करेंगे जितने आवश्यक हों, प्रत्येक चरण में एक Reasoning कदम होगा, फिर एक Action कदम होगा, जहाँ यह टूल कॉल्स तैयार करेगा जो उसे कार्य को हल करने के करीब ले जाएंगे।\n\nReAct प्रक्रिया में पिछले चरणों की मेमोरी रखना शामिल है।\n\n> [!TIP]\n> मल्टी-स्टेप एजेंट्स के बारे में अधिक जानने के लिए [Open-source LLMs as LangChain Agents](https://huggingface.co/blog/open-source-llms-as-agents) ब्लॉग पोस्ट पढ़ें।\n\nयहाँ एक वीडियो ओवरव्यू है कि यह कैसे काम करता है:\n\n\nबेसिक्स सीखें और एजेंट्स का उपयोग करने में परिचित हों। यदि आप पहली बार एजेंट्स का उपयोग कर रहे हैं तो यहाँ से शुरू करें!
\n \nएक विशिष्ट लक्ष्य प्राप्त करने में मदद के लिए गाइड: SQL क्वेरी जनरेट और टेस्ट करने के लिए एजेंट बनाएं!
\n \nमहत्वपूर्ण विषयों की बेहतर समझ बनाने के लिए उच्च-स्तरीय व्याख्याएं।
\n \nएजेंट्स बनाने के महत्वपूर्ण पहलुओं को कवर करने वाले क्ट्यूटोरियल्स।
\n \n\n\nआप देख सकते हैं कि CodeAgent ने अपने मैनेज्ड ToolCallingAgent को (वैसे, मैनेज्ड एजेंट एक CodeAgent भी हो सकता था) U.S. 2024 ग्रोथ रेट के लिए वेब सर्च चलाने के लिए कॉल किया। फिर मैनेज्ड एजेंट ने अपनी रिपोर्ट लौटाई और मैनेजर एजेंट ने अर्थव्यवस्था के दोगुना होने का समय गणना करने के लिए उस पर कार्य किया! अच्छा है, है ना?"
},
{
"path": "docs/source/hi/tutorials/secure_code_execution.md",
"content": "# सुरक्षित कोड एक्जीक्यूशन\n\n[[open-in-colab]]\n\n> [!TIP]\n> यदि आप एजेंट्स बनाने में नए हैं, तो सबसे पहले [एजेंट्स का परिचय](../conceptual_guides/intro_agents) और [smolagents की गाइडेड टूर](../guided_tour) पढ़ना सुनिश्चित करें।\n\n### कोड Agents\n\n[कई](https://huggingface.co/papers/2402.01030) [शोध](https://huggingface.co/papers/2411.01747) [पत्रों](https://huggingface.co/papers/2401.00812) ने दिखाया है कि LLM द्वारा अपनी क्रियाओं (टूल कॉल्स) को कोड में लिखना, टूल कॉलिंग के वर्तमान मानक प्रारूप से बहुत बेहतर है, जो industry में \"टूल्स नेम्स और आर्ग्यूमेंट्स को JSON के रूप में लिखने\" के विभिन्न रूप हैं।\n\nकोड बेहतर क्यों है? क्योंकि हमने अपनी कोड भाषाओं को विशेष रूप से कंप्यूटर द्वारा की जाने वाली क्रियाओं को व्यक्त करने के लिए तैयार किया है। यदि JSON स्निपेट्स एक बेहतर तरीका होता, तो यह पैकेज JSON स्निपेट्स में लिखा गया होता और शैतान हम पर हंस रहा होता।\n\nकोड कंप्यूटर पर क्रियाएँ व्यक्त करने का बेहतर तरीका है। इसमें बेहतर है:\n- **कंपोज़ेबिलिटी:** क्या आप JSON क्रियाओं को एक-दूसरे के भीतर नेस्ट कर सकते हैं, या बाद में पुन: उपयोग करने के लिए JSON क्रियाओं का एक सेट परिभाषित कर सकते हैं, जैसे आप बस एक पायथन फ़ंक्शन परिभाषित कर सकते हैं?\n- **ऑब्जेक्ट प्रबंधन:** JSON में `generate_image` जैसी क्रिया का आउटपुट कैसे स्टोर करें?\n- **सामान्यता:** कोड किसी भी कंप्यूटर कार्य को व्यक्त करने के लिए बनाया गया है।\n- **LLM प्रशिक्षण कॉर्पस में प्रतिनिधित्व:** क्यों न इस आशीर्वाद का लाभ उठाएं कि उच्च गुणवत्ता वाले कोड उदाहरण पहले से ही LLM प्रशिक्षण डेटा में शामिल हैं?\n\nयह नीचे दी गई छवि में दर्शाया गया है, जो [Executable Code Actions Elicit Better LLM Agents](https://huggingface.co/papers/2402.01030) से ली गई है।\n\n\n\nयही कारण है कि हमने कोड एजेंट्स, इस मामले में पायथन एजेंट्स पर जोर दिया, जिसका मतलब सुरक्षित पायथन इंटरप्रेटर बनाने पर अधिक प्रयास करना था।\n\n### लोकल पायथन इंटरप्रेटर\n\nडिफ़ॉल्ट रूप से, `CodeAgent` LLM-जनरेटेड कोड को आपके एनवायरनमेंट में चलाता है।\nयह एक्जीक्यूशन वैनिला पायथन इंटरप्रेटर द्वारा नहीं किया जाता: हमने एक अधिक सुरक्षित `LocalPythonExecutor` को शुरू से फिर से बनाया है।\nयह इंटरप्रेटर सुरक्षा के लिए डिज़ाइन किया गया है:\n - इम्पोर्ट्स को उपयोगकर्ता द्वारा स्पष्ट रूप से पास की गई सूची तक सीमित करना\n - इनफिनिट लूप्स और रिसोर्स ब्लोटिंग को रोकने के लिए ऑपरेशंस की संख्या को कैप करना\n - कोई भी ऐसा ऑपरेशन नहीं करेगा जो पूर्व-परिभाषित नहीं है\n\nहमने इसे कई उपयोग मामलों में इस्तेमाल किया है, और कभी भी एनवायरनमेंट को कोई नुकसान नहीं देखा। \n\nहालांकि यह समाधान पूरी तरह से सुरक्षित नहीं है: कोई ऐसे अवसरों की कल्पना कर सकता है जहां दुर्भावनापूर्ण कार्यों के लिए फाइन-ट्यून किए गए LLM अभी भी आपके एनवायरनमेंट को नुकसान पहुंचा सकते हैं। उदाहरण के लिए यदि आपने छवियों को प्रोसेस करने के लिए `Pillow` जैसे मासूम पैकेज की अनुमति दी है, तो LLM आपकी हार्ड ड्राइव को ब्लोट करने के लिए हजारों छवियों को सेव कर सकता है।\nयदि आपने खुद LLM इंजन चुना है तो यह निश्चित रूप से संभावित नहीं है, लेकिन यह हो सकता है।\n\nतो यदि आप अतिरिक्त सावधानी बरतना चाहते हैं, तो आप नीचे वर्णित रिमोट कोड एक्जीक्यूशन विकल्प का उपयोग कर सकते हैं।\n\n### E2B कोड एक्जीक्यूटर\n\nअधिकतम सुरक्षा के लिए, आप कोड को सैंडबॉक्स्ड एनवायरनमेंट में चलाने के लिए E2B के साथ हमारे एकीकरण का उपयोग कर सकते हैं। यह एक रिमोट एक्जीक्यूशन सेवा है जो आपके कोड को एक आइसोलेटेड कंटेनर में चलाती है, जिससे कोड का आपके स्थानीय एनवायरनमेंट को प्रभावित करना असंभव हो जाता है।\n\nइसके लिए, आपको अपना E2B अकाउंट सेटअप करने और अपने एनवायरनमेंट वेरिएबल्स में अपना `E2B_API_KEY` सेट करने की आवश्यकता होगी। अधिक जानकारी के लिए [E2B की क्विकस्टार्ट डॉक्यूमेंटेशन](https://e2b.dev/docs/quickstart) पर जाएं।\n\nफिर आप इसे `pip install e2b-code-interpreter python-dotenv` के साथ इंस्टॉल कर सकते हैं।\n\nअब आप तैयार हैं!\n\nकोड एक्जीक्यूटर को E2B पर सेट करने के लिए, बस अपने `CodeAgent` को इनिशियलाइज़ करते समय `executor_type=\"e2b\"` फ्लैग पास करें।\nध्यान दें कि आपको `additional_authorized_imports` में सभी टूल की डिपेंडेंसीज़ जोड़नी चाहिए, ताकि एक्जीक्यूटर उन्हें इंस्टॉल करे।\n\n```py\nfrom smolagents import CodeAgent, VisitWebpageTool, InferenceClientModel\nagent = CodeAgent(\n tools = [VisitWebpageTool()],\n model=InferenceClientModel(),\n additional_authorized_imports=[\"requests\", \"markdownify\"],\n executor_type=\"e2b\"\n)\n\nagent.run(\"What was Abraham Lincoln's preferred pet?\")\n```\n\nE2B कोड एक्जीक्यूशन वर्तमान में मल्टी-एजेंट्स के साथ काम नहीं करता है - क्योंकि कोड ब्लॉब में एक एजेंट कॉल करना जो रिमोटली एक्जीक्यूट किया जाना चाहिए, यह एक गड़बड़ है। लेकिन हम इसे जोड़ने पर काम कर रहे हैं!\n"
},
{
"path": "docs/source/hi/tutorials/tools.md",
"content": "# Tools\n\n[[open-in-colab]]\n\nयहाँ, हम एडवांस्ड tools उपयोग देखेंगे।\n\n> [!TIP]\n> यदि आप एजेंट्स बनाने में नए हैं, तो सबसे पहले [एजेंट्स का परिचय](../conceptual_guides/intro_agents) और [smolagents की गाइडेड टूर](../guided_tour) पढ़ना सुनिश्चित करें।\n\n- [Tools](#tools)\n - [टूल क्या है, और इसे कैसे बनाएं?](#टूल-क्या-है-और-इसे-कैसे-बनाएं)\n - [अपना टूल हब पर शेयर करें](#अपना-टूल-हब-पर-शेयर-करें)\n - [स्पेस को टूल के रूप में इम्पोर्ट करें](#स्पेस-को-टूल-के-रूप-में-इम्पोर्ट-करें)\n - [LangChain टूल्स का उपयोग करें](#LangChain-टूल्स-का-उपयोग-करें)\n - [अपने एजेंट के टूलबॉक्स को मैनेज करें](#अपने-एजेंट-के-टूलबॉक्स-को-मैनेज-करें)\n - [टूल्स का कलेक्शन उपयोग करें](#टूल्स-का-कलेक्शन-उपयोग-करें)\n\n### टूल क्या है और इसे कैसे बनाएं\n\nटूल मुख्य रूप से एक फ़ंक्शन है जिसे एक LLM एजेंटिक सिस्टम में उपयोग कर सकता है।\n\nलेकिन इसका उपयोग करने के लिए, LLM को एक API दी जाएगी: नाम, टूल विवरण, इनपुट प्रकार और विवरण, आउटपुट प्रकार।\n\nइसलिए यह केवल एक फ़ंक्शन नहीं हो सकता। यह एक क्लास होनी चाहिए।\n\nतो मूल रूप से, टूल एक क्लास है जो एक फ़ंक्शन को मेटाडेटा के साथ रैप करती है जो LLM को समझने में मदद करती है कि इसका उपयोग कैसे करें।\n\nयह कैसा दिखता है:\n\n```python\nfrom smolagents import Tool\n\nclass HFModelDownloadsTool(Tool):\n name = \"model_download_counter\"\n description = \"\"\"\n This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub.\n It returns the name of the checkpoint.\"\"\"\n inputs = {\n \"task\": {\n \"type\": \"string\",\n \"description\": \"the task category (such as text-classification, depth-estimation, etc)\",\n }\n }\n output_type = \"string\"\n\n def forward(self, task: str):\n from huggingface_hub import list_models\n\n model = next(iter(list_models(filter=task, sort=\"downloads\", direction=-1)))\n return model.id\n\nmodel_downloads_tool = HFModelDownloadsTool()\n```\n\nकस्टम टूल `Tool` को सबक्लास करता है उपयोगी मेथड्स को इनहेरिट करने के लिए। चाइल्ड क्लास भी परिभाषित करती है:\n- एक `name` एट्रिब्यूट, जो टूल के नाम से संबंधित है। नाम आमतौर पर बताता है कि टूल क्या करता है। चूंकि कोड एक टास्क के लिए सबसे अधिक डाउनलोड वाले मॉडल को रिटर्न करता है, इसलिए इसे `model_download_counter` नाम दें।\n- एक `description` एट्रिब्यूट एजेंट के सिस्टम प्रॉम्प्ट को पॉपुलेट करने के लिए उपयोग किया जाता है।\n- एक `inputs` एट्रिब्यूट, जो `\"type\"` और `\"description\"` keys वाला डिक्शनरी है। इसमें जानकारी होती है जो पायथन इंटरप्रेटर को इनपुट के बारे में शिक्षित विकल्प चुनने में मदद करती है।\n- एक `output_type` एट्रिब्यूट, जो आउटपुट टाइप को निर्दिष्ट करता है। `inputs` और `output_type` दोनों के लिए टाइप [Pydantic formats](https://docs.pydantic.dev/latest/concepts/json_schema/#generating-json-schema) होने चाहिए, वे इनमें से कोई भी हो सकते हैं: `[\"string\", \"boolean\",\"integer\", \"number\", \"image\", \"audio\", \"array\", \"object\", \"any\", \"null\"]`।\n- एक `forward` मेथड जिसमें एक्जीक्यूट किया जाने वाला इन्फरेंस कोड होता है।\n\nएजेंट में उपयोग किए जाने के लिए इतना ही चाहिए!\n\nटूल बनाने का एक और तरीका है। [guided_tour](../guided_tour) में, हमने `@tool` डेकोरेटर का उपयोग करके एक टूल को लागू किया। [`tool`] डेकोरेटर सरल टूल्स को परिभाषित करने का अनुशंसित तरीका है, लेकिन कभी-कभी आपको इससे अधिक की आवश्यकता होती है: अधिक स्पष्टता के लिए एक क्लास में कई मेथड्स का उपयोग करना, या अतिरिक्त क्लास एट्रिब्यूट्स का उपयोग करना।\n\nइस स्थिति में, आप ऊपर बताए अनुसार [`Tool`] को सबक्लास करके अपना टूल बना सकते हैं।\n\n### अपना टूल हब पर शेयर करें\n\nआप टूल पर [`~Tool.push_to_hub`] को कॉल करके अपना कस्टम टूल हब पर शेयर कर सकते हैं। सुनिश्चित करें कि आपने हब पर इसके लिए एक रिपॉजिटरी बनाई है और आप रीड एक्सेस वाला टोकन उपयोग कर रहे हैं।\n\n```python\nmodel_downloads_tool.push_to_hub(\"{your_username}/hf-model-downloads\", token=\"\n\nफिर आप इस टूल का उपयोग किसी अन्य टूल की तरह कर सकते हैं। उदाहरण के लिए, चलिए प्रॉम्प्ट `a rabbit wearing a space suit` को सुधारें और इसकी एक इमेज जनरेट करें। यह उदाहरण यह भी दिखाता है कि आप एजेंट को अतिरिक्त आर्ग्यूमेंट्स कैसे पास कर सकते हैं।\n\n```python\nfrom smolagents import CodeAgent, InferenceClientModel\n\nmodel = InferenceClientModel(model_id=\"Qwen/Qwen3-Next-80B-A3B-Thinking\")\nagent = CodeAgent(tools=[image_generation_tool], model=model)\n\nagent.run(\n \"Improve this prompt, then generate an image of it.\", additional_args={'user_prompt': 'A rabbit wearing a space suit'}\n)\n```\n\n```text\n=== Agent thoughts:\nimproved_prompt could be \"A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background\"\n\nNow that I have improved the prompt, I can use the image generator tool to generate an image based on this prompt.\n>>> Agent is executing the code below:\nimage = image_generator(prompt=\"A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background\")\nfinal_answer(image)\n```\n\n\n\nयह कितना कूल है? 🤩\n\n### LangChain टूल्स का उपयोग करें\n\nहम LangChain को पसंद करते हैं और मानते हैं कि इसके पास टूल्स का एक बहुत आकर्षक संग्रह है।\nLangChain से एक टूल इम्पोर्ट करने के लिए, `from_langchain()` मेथड का उपयोग करें।\n\nयहाँ बताया गया है कि आप LangChain वेब सर्च टूल का उपयोग करके परिचय के सर्च रिजल्ट को कैसे फिर से बना सकते हैं।\nइस टूल को काम करने के लिए `pip install langchain google-search-results -q` की आवश्यकता होगी।\n```python\nfrom langchain.agents import load_tools\n\nsearch_tool = Tool.from_langchain(load_tools([\"serpapi\"])[0])\n\nagent = CodeAgent(tools=[search_tool], model=model)\n\nagent.run(\"How many more blocks (also denoted as layers) are in BERT base encoder compared to the encoder from the architecture proposed in Attention is All You Need?\")\n```\n\n### अपने एजेंट के टूलबॉक्स को मैनेज करें\n\nआप एजेंट के टूलबॉक्स को `agent.tools` एट्रिब्यूट में एक टूल जोड़कर या बदलकर मैनेज कर सकते हैं, क्योंकि यह एक स्टैंडर्ड डिक्शनरी है।\n\nचलिए केवल डिफ़ॉल्ट टूलबॉक्स के साथ इनिशियलाइज़ किए गए मौजूदा एजेंट में `model_download_tool` जोड़ें।\n\n```python\nfrom smolagents import InferenceClientModel\n\nmodel = InferenceClientModel(model_id=\"Qwen/Qwen3-Next-80B-A3B-Thinking\")\n\nagent = CodeAgent(tools=[], model=model, add_base_tools=True)\nagent.tools[model_download_tool.name] = model_download_tool\n```\nअब हम नए टूल का लाभ उठा सकते हैं।\n\n```python\nagent.run(\n \"Can you give me the name of the model that has the most downloads in the 'text-to-video' task on the Hugging Face Hub but reverse the letters?\"\n)\n```\n\n\n> [!TIP]\n> एजेंट में बहुत अधिक टूल्स न जोड़ने से सावधान रहें: यह कमजोर LLM इंजन को ओवरव्हेल्म कर सकता है।\n\n\n### टूल्स का कलेक्शन उपयोग करें\n\nआप `ToolCollection` ऑब्जेक्ट का उपयोग करके टूल कलेक्शंस का लाभ उठा सकते हैं। यह या तो हब से एक कलेक्शन या MCP सर्वर टूल्स को लोड करने का समर्थन करता है।\n\n#### हब में कलेक्शन से टूल कलेक्शन\n\nआप उस कलेक्शन के स्लग के साथ इसका लाभ उठा सकते हैं जिसका आप उपयोग करना चाहते हैं।\nफिर उन्हें अपने एजेंट को इनिशियलाइज़ करने के लिए एक लिस्ट के रूप में पास करें, और उनका उपयोग शुरू करें!\n\n```py\nfrom smolagents import ToolCollection, CodeAgent\n\nimage_tool_collection = ToolCollection.from_hub(\n collection_slug=\"huggingface-tools/diffusion-tools-6630bb19a942c2306a2cdb6f\",\n token=\"\n\n\n\nCodeAgent가 관리하는 ToolCallingAgent를 호출하여(참고로 관리되는 에이전트는 CodeAgent가 될 수도 있습니다) 미국 2024년 성장률을 웹에서 검색하도록 요청한 것을 확인할 수 있습니다. 이후 관리되는 에이전트가 결과를 보고하면, 관리자 에이전트가 이 정보를 활용하여 경제 배증 시간을 계산했습니다! 흥미롭죠?\n\n## 🪢 Langfuse로 텔레메트리 설정[[setting-up-telemetry-with-🪢-langfuse]]\n\n이 부분은 `SmolagentsInstrumentor`를 사용하여 **Langfuse**로 Hugging Face **smolagents**를 모니터링하고 디버깅하는 방법을 보여줍니다.\n\n> **Langfuse란?** [Langfuse](https://langfuse.com)는 LLM 엔지니어링을 위한 오픈소스 플랫폼입니다. AI 에이전트를 위한 추적 및 모니터링 기능을 제공하여 개발자가 제품을 디버깅하고, 분석하고, 최적화할 수 있도록 도와줍니다. Langfuse는 네이티브 통합, OpenTelemetry, SDK를 통해 다양한 도구와 프레임워크와 통합됩니다.\n\n### 1단계: 의존성 설치[[step-1:-install-dependencies]]\n\n```python\n%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents\n```\n\n### 2단계: 환경 변수 설정[[step-2:-set-up-environment-variables]]\n\nLangfuse API 키를 설정하고 Langfuse로 추적을 보내도록 OpenTelemetry 엔드포인트를 구성하세요. [Langfuse Cloud](https://cloud.langfuse.com)에 가입하거나 [Langfuse를 자체 호스팅](https://langfuse.com/self-hosting)하여 Langfuse API 키를 얻으세요.\n\n또한 [Hugging Face 토큰](https://huggingface.co/settings/tokens) (`HF_TOKEN`)을 환경 변수로 추가하세요.\n\n```python\nimport os\n# 프로젝트 설정 페이지(https://cloud.langfuse.com)에서 프로젝트 키를 가져옵니다. \nos.environ[\"LANGFUSE_PUBLIC_KEY\"] = \"pk-lf-...\" \nos.environ[\"LANGFUSE_SECRET_KEY\"] = \"sk-lf-...\" \nos.environ[\"LANGFUSE_HOST\"] = \"https://cloud.langfuse.com\" # 🇪🇺 유럽 지역\n# os.environ[\"LANGFUSE_HOST\"] = \"https://us.cloud.langfuse.com\" # 🇺🇸 미국 지역\n \n# Hugging Face 토큰을 입력합니다.\nos.environ[\"HF_TOKEN\"] = \"hf_...\"\n```\n\n환경 변수가 설정되면 이제 Langfuse 클라이언트를 초기화할 수 있습니다. `get_client()`는 환경 변수에 제공된 자격 증명을 사용하여 Langfuse 클라이언트를 초기화합니다.\n\n```python\nfrom langfuse import get_client\n \nlangfuse = get_client()\n \n# 연결을 확인합니다.\nif langfuse.auth_check():\n print(\"Langfuse client is authenticated and ready!\")\nelse:\n print(\"Authentication failed. Please check your credentials and host.\")\n```\n\n### 3단계: `SmolagentsInstrumentor` 초기화[[step-3:-initialize-the-`smolagentsinstrumentor`]]\n\n애플리케이션 코드를 실행하기 전에 `SmolagentsInstrumentor`를 초기화하세요.\n\n```python\nfrom openinference.instrumentation.smolagents import SmolagentsInstrumentor\n \nSmolagentsInstrumentor().instrument()\n```\n\n### 4단계: smolagent 실행[[step-4:-run-your-smolagent]]\n\n```python\nfrom smolagents import (\n CodeAgent,\n ToolCallingAgent,\n WebSearchTool,\n VisitWebpageTool,\n InferenceClientModel,\n)\n\nmodel = InferenceClientModel(\n model_id=\"deepseek-ai/DeepSeek-R1-Distill-Qwen-32B\"\n)\n\nsearch_agent = ToolCallingAgent(\n tools=[WebSearchTool(), VisitWebpageTool()],\n model=model,\n name=\"search_agent\",\n description=\"This is an agent that can do web search.\",\n)\n\nmanager_agent = CodeAgent(\n tools=[],\n model=model,\n managed_agents=[search_agent],\n)\nmanager_agent.run(\n \"How can Langfuse be used to monitor and improve the reasoning and decision-making of smolagents when they execute multi-step tasks, like dynamically adjusting a recipe based on user feedback or available ingredients?\"\n)\n```\n\n### 5단계: Langfuse에서 추적 보기[[step-5:-view-traces-in-langfuse]]\n\n에이전트를 실행한 후, Langfuse의 smolagents 애플리케이션에서 생성된 추적 정보를 확인할 수 있습니다. AI 에이전트의 디버깅과 최적화에 도움이 되는 LLM 상호작용의 상세한 세부 과정을 살펴볼 수 있습니다.\n\n\n\n_[Langfuse의 추적 예시](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_\n"
},
{
"path": "docs/source/ko/tutorials/memory.md",
"content": "# 📚 에이전트 메모리 관리[[-manage-your-agents-memory]]\n\n[[open-in-colab]]\n\n결국 에이전트는 도구와 프롬프트로 이루어진 단순한 구성요소로 정의됩니다.\n그리고 무엇보다 중요한 것은 에이전트가 과거 단계의 메모리를 가지고 있어 계획, 실행, 오류의 이력을 추적한다는 점입니다.\n\n### 에이전트 메모리 재생[[replay-your-agents-memory]]\n\n과거 실행된 에이전트를 확인하기 위한 몇 가지 기능을 제공합니다.\n\n[계측 가이드](./inspect_runs)에서 언급한 바와 같이, 에이전트 실행을 계측하여 특정 단계를 확대하거나 축소할 수 있는 우수한 UI로 시각화할 수 있습니다.\n\n또한 다음과 같이 `agent.replay()`를 사용할 수도 있습니다.\n\n에이전트를 실행한 후,\n```py\nfrom smolagents import InferenceClientModel, CodeAgent\n\nagent = CodeAgent(tools=[], model=InferenceClientModel(), verbosity_level=0)\n\nresult = agent.run(\"What's the 20th Fibonacci number?\")\n```\n\n이 마지막 실행을 다시 재생하고 싶다면, 다음 코드를 사용하면 됩니다.\n```py\nagent.replay()\n```\n\n### 에이전트 메모리 동적 변경[[dynamically-change-the-agents-memory]]\n\n많은 고급 사용 사례에서는 에이전트의 메모리를 동적으로 수정해야 합니다.\n\n에이전트의 메모리는 다음과 같이 접근할 수 있습니다.\n\n\n```py\nfrom smolagents import ActionStep\n\nsystem_prompt_step = agent.memory.system_prompt\nprint(\"The system prompt given to the agent was:\")\nprint(system_prompt_step.system_prompt)\n\ntask_step = agent.memory.steps[0]\nprint(\"\\n\\nThe first task step was:\")\nprint(task_step.task)\n\nfor step in agent.memory.steps:\n if isinstance(step, ActionStep):\n if step.error is not None:\n print(f\"\\nStep {step.step_number} got this error:\\n{step.error}\\n\")\n else:\n print(f\"\\nStep {step.step_number} got these observations:\\n{step.observations}\\n\")\n```\n\n`agent.memory.get_full_steps()`를 사용하여 전체 단계를 딕셔너리 형태로 가져올 수 있습니다.\n\n또한 단계 콜백을 사용하여 에이전트의 메모리를 동적으로 변경할 수도 있습니다.\n\n단계 콜백은 인자로 `agent` 객체 자체에 접근할 수 있으므로, 위에서 설명한 것처럼 모든 메모리 단계에 접근하여 필요한 경우 수정할 수 있습니다. 예를 들어, 웹 브라우저 에이전트가 수행하는 각 단계의 스크린샷을 관찰하고 있다고 가정해 보겠습니다. 이 경우 최신 스크린샷은 유지하면서 토큰 비용을 절약하기 위해 이전 단계의 이미지를 메모리에서 제거할 수 있습니다.\n\n이 경우 다음과 같은 코드를 사용할 수 있습니다.\n_주의: 이 코드는 간결함을 위해 일부 임포트 및 객체 정의가 생략된 불완전한 예시입니다. 전체 작동 버전의 코드는 [원본 스크립트](https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py)에서 확인하세요._\n\n```py\nimport helium\nfrom PIL import Image\nfrom io import BytesIO\nfrom time import sleep\n\ndef update_screenshot(memory_step: ActionStep, agent: CodeAgent) -> None:\n sleep(1.0) # JavaScript 애니메이션이 완료된 후에 스크린샷을 찍도록 합니다.\n driver = helium.get_driver()\n latest_step = memory_step.step_number\n for previous_memory_step in agent.memory.steps: # 이전 스크린샷을 로그에서 제거하여 처리 과정을 간소화합니다.\n if isinstance(previous_memory_step, ActionStep) and previous_memory_step.step_number <= latest_step - 2:\n previous_memory_step.observations_images = None\n png_bytes = driver.get_screenshot_as_png()\n image = Image.open(BytesIO(png_bytes))\n memory_step.observations_images = [image.copy()]\n```\n\n그 다음 에이전트를 초기화할 때 이 함수를 다음과 같이 `step_callbacks` 인수에 전달해야 합니다.\n\n```py\nCodeAgent(\n tools=[WebSearchTool(), go_back, close_popups, search_item_ctrl_f],\n model=model,\n additional_authorized_imports=[\"helium\"],\n step_callbacks=[update_screenshot],\n max_steps=20,\n verbosity_level=2,\n)\n```\n\n전체 작동 예시는 [비전 웹 브라우저 코드](https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py)에서 확인할 수 있습니다.\n\n### 에이전트를 단계별로 실행[[run-agents-one-step-at-a-time]]\n\n이 기능은 도구 호출에 오랜 시간이 걸리는 경우에 유용합니다.\n에이전트를 한 단계씩 실행하면서 각 단계에서 메모리를 업데이트할 수 있습니다.\n\n```py\nfrom smolagents import InferenceClientModel, CodeAgent, ActionStep, TaskStep\n\nagent = CodeAgent(tools=[], model=InferenceClientModel(), verbosity_level=1)\nagent.python_executor.send_tools({**agent.tools})\nprint(agent.memory.system_prompt)\n\ntask = \"What is the 20th Fibonacci number?\"\n\n# 필요에 따라 다른 에이전트의 메모리를 불러와 메모리를 수정할 수 있습니다.\n# agent.memory.steps = previous_agent.memory.steps\n\n# 새로운 작업을 시작합니다!\nagent.memory.steps.append(TaskStep(task=task, task_images=[]))\n\nfinal_answer = None\nstep_number = 1\nwhile final_answer is None and step_number <= 10:\n memory_step = ActionStep(\n step_number=step_number,\n observations_images=[],\n )\n # 한 단계를 실행합니다.\n final_answer = agent.step(memory_step)\n agent.memory.steps.append(memory_step)\n step_number += 1\n\n # 필요한 경우 메모리를 수정할 수도 있습니다\n # 예를 들어 최신 단계를 업데이트 하려면 다음과 같이 처리합니다:\n # agent.memory.steps[-1] = ...\n\nprint(\"The final answer is:\", final_answer)\n```\n"
},
{
"path": "docs/source/zh/_config.py",
"content": "# docstyle-ignore\nINSTALL_CONTENT = \"\"\"\n# Installation\n! pip install smolagents\n# To install from source instead of the last release, comment the command above and uncomment the following one.\n# ! pip install git+https://github.com/huggingface/smolagents.git\n\"\"\"\n\nnotebook_first_cells = [{\"type\": \"code\", \"content\": INSTALL_CONTENT}]\nblack_avoid_patterns = {\n \"{processor_class}\": \"FakeProcessorClass\",\n \"{model_class}\": \"FakeModelClass\",\n \"{object_class}\": \"FakeObjectClass\",\n}\n"
},
{
"path": "docs/source/zh/_toctree.yml",
"content": "- title: 起步\n sections:\n - local: index\n title: 🤗 Agents\n - local: guided_tour\n title: 导览\n- title: Tutorials\n sections:\n - local: tutorials/building_good_agents\n title: ✨ 构建好用的 agents\n - local: tutorials/inspect_runs\n title: 📊 监控 Agent 的运行\n - local: tutorials/tools\n title: 🛠️ 工具 - 深度指南\n - local: tutorials/secure_code_execution\n title: 🛡️ 使用 E2B 保护你的代码执行\n - local: tutorials/memory\n title: 📚 管理 Agent 的记忆\n- title: Conceptual guides\n sections:\n - local: conceptual_guides/intro_agents\n title: 🤖 Agent 化系统介绍\n - local: conceptual_guides/react\n title: 🤔 多步骤 Agent 是如何工作的？\n- title: Examples\n sections:\n - local: examples/text_to_sql\n title: 自我修正 Text-to-SQL\n - local: examples/rag\n title: 借助 agentic RAG 掌控知识库\n - local: examples/multiagents\n title: 编排 multi-agent 系统\n - local: examples/web_browser\n title: 基于视觉模型构建能够浏览网页的agent\n- title: Reference\n sections:\n - local: reference/agents\n title: Agent-related objects\n - local: reference/models\n title: Model-related objects\n - local: reference/tools\n title: Tool-related objects\n"
},
{
"path": "docs/source/zh/conceptual_guides/intro_agents.md",
"content": "# Agent 简介\n\n> [!TIP]\n> 译者注：Agent 的业内术语是“智能体”。本译文将保留 agent，不作翻译，以带来更高效的阅读体验。(在中文为主的文章中，It's easier to 注意到英文。Attention Is All You Need!)\n\n## 🤔 什么是 agent？\n\n任何使用 AI 的高效系统都需要为 LLM 提供某种访问现实世界的方式：例如调用搜索工具获取外部信息，或者操作某些程序以完成任务。换句话说，LLM 应该具有 **_Agent 能力_**。Agent 程序是 LLM 通往外部世界的门户。\n\n> [!TIP]\n> AI agent 是 **LLM 输出控制工作流的程序**。\n\n任何利用 LLM 的系统都会将 LLM 输出集成到代码中。LLM 输入对代码工作流的影响程度就是 LLM 在系统中的 agent 能力级别。\n\n请注意，根据这个定义，\"Agent\" 不是一个离散的、非 0 即 1 的定义：相反，\"Agent 能力\" 是一个连续谱系，随着你在工作流中给予 LLM 更多或更少的权力而变化。\n\n请参见下表中 agent 能力在不同系统中的变化：\n\n| Agent 能力级别 | 描述 | 名称 | 示例模式 |\n| ------------ | ---------------------------------------------- | ---------- | -------------------------------------------------- |\n| ☆☆☆ | LLM 输出对程序流程没有影响 | 简单处理器 | `process_llm_output(llm_response)` |\n| ★☆☆ | LLM 输出决定 if/else 分支 | 路由 | `if llm_decision(): path_a() else: path_b()` |\n| ★★☆ | LLM 输出决定函数执行 | 工具调用者 | `run_function(llm_chosen_tool, llm_chosen_args)` |\n| ★★★ | LLM 输出控制迭代和程序继续 | 多步 Agent | `while llm_should_continue(): execute_next_step()` |\n| ★★★ | 一个 agent 工作流可以启动另一个 agent 工作流 | 多 Agent | `if llm_trigger(): execute_agent()` |\n\n多步 agent 具有以下代码结构：\n\n```python\nmemory = [user_defined_task]\nwhile llm_should_continue(memory): # 这个循环是多步部分\n action = llm_get_next_action(memory) # 这是工具调用部分\n observations = execute_action(action)\n memory += [action, observations]\n```\n\n这个 agent 系统在一个循环中运行，每一步执行一个新动作（该动作可能涉及调用一些预定义的 *工具*，这些工具只是函数），直到其观察结果表明已达到解决给定任务的满意状态。以下是一个多步 agent 如何解决简单数学问题的示例：\n\n\n\n\n与 JSON 片段相比，用代码编写动作提供了更好的：\n\n- **可组合性：** 你能像定义 python 函数一样，将 JSON 动作嵌套在一起，或定义一组 JSON 动作以供重用吗？\n- **对象管理：** 你如何在 JSON 中存储像 `generate_image` 这样的动作的输出？\n- **通用性：** 代码被构建为简单地表达任何你可以让计算机做的事情。\n- **LLM 训练数据中的表示：** 大量高质量的代码动作已经包含在 LLM 的训练数据中，这意味着它们已经为此进行了训练！\n"
},
{
"path": "docs/source/zh/conceptual_guides/react.md",
"content": "# 多步骤 agent 是如何工作的？\n\nReAct 框架（[Yao et al., 2022](https://huggingface.co/papers/2210.03629)）是目前构建 agent 的主要方法。\n\n该名称基于两个词的组合：\"Reason\" （推理）和 \"Act\" （行动）。实际上，遵循此架构的 agent 将根据需要尽可能多的步骤来解决其任务，每个步骤包括一个推理步骤，然后是一个行动步骤，在该步骤中，它制定工具调用，使其更接近解决手头的任务。\n\nReAct 过程涉及保留过去步骤的记忆。\n\n> [!TIP]\n> 阅读 [Open-source LLMs as LangChain Agents](https://huggingface.co/blog/open-source-llms-as-agents) 博客文章以了解更多关于多步 agent 的信息。\n\n以下是其工作原理的视频概述：\n\n\n\n\n如图所示，CodeAgent 调用了其托管的 ToolCallingAgent（注：托管Agent也可以是另一个 CodeAgent）执行美国2024年经济增长率的网络搜索。托管Agent返回报告后，管理Agent根据结果计算出经济翻倍周期！是不是很智能？\n\n## 使用 🪢 Langfuse 配置遥测\n\n本部分演示如何通过 `SmolagentsInstrumentor` 使用 **Langfuse** 监控和调试 Hugging Face **smolagents**。\n\n> **Langfuse 是什么？** [Langfuse](https://langfuse.com) 是面向LLM工程的开源平台，提供AI Agent的追踪与监控功能，帮助开发者调试、分析和优化产品。该平台通过原生集成、OpenTelemetry 和 SDKs 与各类工具框架对接。\n\n### 步骤 1: 安装依赖\n\n```python\n%pip install langfuse 'smolagents[telemetry]' openinference-instrumentation-smolagents\n```\n\n### 步骤 2: 配置环境变量\n\n设置 Langfuse API 密钥，并配置 OpenTelemetry 端点将追踪数据发送至 Langfuse。通过注册 [Langfuse Cloud](https://cloud.langfuse.com) 或 [自托管 Langfuse](https://langfuse.com/self-hosting) 获取 API 密钥。\n\n同时需添加 [Hugging Face 令牌](https://huggingface.co/settings/tokens) (`HF_TOKEN`) 作为环境变量：\n```python\nimport os\n# Get keys for your project from the project settings page: https://cloud.langfuse.com\nos.environ[\"LANGFUSE_PUBLIC_KEY\"] = \"pk-lf-...\" \nos.environ[\"LANGFUSE_SECRET_KEY\"] = \"sk-lf-...\" \nos.environ[\"LANGFUSE_HOST\"] = \"https://cloud.langfuse.com\" # 🇪🇺 EU region\n# os.environ[\"LANGFUSE_HOST\"] = \"https://us.cloud.langfuse.com\" # 🇺🇸 US region\n \n# your Hugging Face token\nos.environ[\"HF_TOKEN\"] = \"hf_...\"\n```\n\n```python\nfrom langfuse import get_client\n \nlangfuse = get_client()\n \n# Verify connection\nif langfuse.auth_check():\n print(\"Langfuse client is authenticated and ready!\")\nelse:\n print(\"Authentication failed. Please check your credentials and host.\")\n```\n\n### 步骤 3: 初始化 `SmolagentsInstrumentor`\n\n在应用程序代码执行前初始化 `SmolagentsInstrumentor`。\n\n\n```python\nfrom openinference.instrumentation.smolagents import SmolagentsInstrumentor\n \nSmolagentsInstrumentor().instrument()\n```\n\n### 步骤 4: 运行 smolagent\n\n```python\nfrom smolagents import (\n CodeAgent,\n ToolCallingAgent,\n WebSearchTool,\n VisitWebpageTool,\n InferenceClientModel,\n)\n\nmodel = InferenceClientModel(\n model_id=\"deepseek-ai/DeepSeek-R1-Distill-Qwen-32B\"\n)\n\nsearch_agent = ToolCallingAgent(\n tools=[WebSearchTool(), VisitWebpageTool()],\n model=model,\n name=\"search_agent\",\n description=\"This is an agent that can do web search.\",\n)\n\nmanager_agent = CodeAgent(\n tools=[],\n model=model,\n managed_agents=[search_agent],\n)\nmanager_agent.run(\n \"How can Langfuse be used to monitor and improve the reasoning and decision-making of smolagents when they execute multi-step tasks, like dynamically adjusting a recipe based on user feedback or available ingredients?\"\n)\n```\n\n### 步骤 5: 在 Langfuse 中查看追踪记录\n\n运行Agent后，您可以在 [Langfuse](https://cloud.langfuse.com) 平台查看 smolagents 应用生成的追踪记录。这些记录会详细展示LLM的交互步骤，帮助您调试和优化AI代理。\n\n\n\n_[Langfuse 公开示例追踪](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/ce5160f9bfd5a6cd63b07d2bfcec6f54?timestamp=2025-02-11T09%3A25%3A45.163Z&display=details)_"
},
{
"path": "docs/source/zh/tutorials/memory.md",
"content": "# 📚 管理Agent的记忆\n\n[[open-in-colab]]\n\n归根结底，Agent可以定义为由几个简单组件构成：它拥有工具、提示词。最重要的是，它具备对过往步骤的记忆，能够追溯完整的规划、执行和错误历史。\n\n### 回放Agent的记忆\n\n我们提供了多项功能来审查Agent的过往运行记录。\n\n您可以通过插装（instrumentation）在可视化界面中查看Agent的运行过程，该界面支持对特定步骤进行缩放操作，具体方法参见[插装指南](./inspect_runs)。\n\n您也可以使用`agent.replay()`方法实现回放：\n\n当Agent完成运行后：\n```py\nfrom smolagents import InferenceClientModel, CodeAgent\n\nagent = CodeAgent(tools=[], model=InferenceClientModel(), verbosity_level=0)\n\nresult = agent.run(\"What's the 20th Fibonacci number?\")\n```\n\n若要回放最近一次运行，只需使用：\n```py\nagent.replay()\n```\n\n### 动态修改Agent的记忆\n\n许多高级应用场景需要对Agent的记忆进行动态修改。\n\n您可以通过以下方式访问Agent的记忆：\n\n```py\nfrom smolagents import ActionStep\n\nsystem_prompt_step = agent.memory.system_prompt\nprint(\"The system prompt given to the agent was:\")\nprint(system_prompt_step.system_prompt)\n\ntask_step = agent.memory.steps[0]\nprint(\"\\n\\nThe first task step was:\")\nprint(task_step.task)\n\nfor step in agent.memory.steps:\n if isinstance(step, ActionStep):\n if step.error is not None:\n print(f\"\\nStep {step.step_number} got this error:\\n{step.error}\\n\")\n else:\n print(f\"\\nStep {step.step_number} got these observations:\\n{step.observations}\\n\")\n```\n\n使用`agent.memory.get_full_steps()`可获取完整步骤字典数据。\n\n您还可以通过步骤回调（step callbacks）实现记忆的动态修改。\n\n步骤回调函数可通过参数直接访问`agent`对象，因此能够访问所有记忆步骤并根据需要进行修改。例如，假设您正在监控网页浏览Agent每个步骤的屏幕截图，希望保留最新截图同时删除旧步骤的图片以节省token消耗。\n\n可参考以下代码示例：\n_注：此代码片段不完整，部分导入语句和对象定义已精简，完整代码请访问[原始脚本](https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py)_\n\n```py\nimport helium\nfrom PIL import Image\nfrom io import BytesIO\nfrom time import sleep\n\ndef update_screenshot(memory_step: ActionStep, agent: CodeAgent) -> None:\n sleep(1.0) # Let JavaScript animations happen before taking the screenshot\n driver = helium.get_driver()\n latest_step = memory_step.step_number\n for previous_memory_step in agent.memory.steps: # Remove previous screenshots from logs for lean processing\n if isinstance(previous_memory_step, ActionStep) and previous_memory_step.step_number <= latest_step - 2:\n previous_memory_step.observations_images = None\n png_bytes = driver.get_screenshot_as_png()\n image = Image.open(BytesIO(png_bytes))\n memory_step.observations_images = [image.copy()]\n```\n\n最后在初始化Agent时，将此函数传入`step_callbacks`参数：\n\n```py\nCodeAgent(\n tools=[WebSearchTool(), go_back, close_popups, search_item_ctrl_f],\n model=model,\n additional_authorized_imports=[\"helium\"],\n step_callbacks=[update_screenshot],\n max_steps=20,\n verbosity_level=2,\n)\n```\n\n请访问我们的 [vision web browser code](https://github.com/huggingface/smolagents/blob/main/src/smolagents/vision_web_browser.py) 查看完整可运行示例。\n\n### 分步运行 Agents\n\n当您需要处理耗时数天的工具调用时，这种方式特别有用：您可以逐步执行Agents。这还允许您在每一步更新记忆。\n\n```py\nfrom smolagents import InferenceClientModel, CodeAgent, ActionStep, TaskStep\n\nagent = CodeAgent(tools=[], model=InferenceClientModel(), verbosity_level=1)\nprint(agent.memory.system_prompt)\n\ntask = \"What is the 20th Fibonacci number?\"\n\n# You could modify the memory as needed here by inputting the memory of another agent.\n# agent.memory.steps = previous_agent.memory.steps\n\n# Let's start a new task!\nagent.memory.steps.append(TaskStep(task=task, task_images=[]))\n\nfinal_answer = None\nstep_number = 1\nwhile final_answer is None and step_number <= 10:\n memory_step = ActionStep(\n step_number=step_number,\n observations_images=[],\n )\n # Run one step.\n final_answer = agent.step(memory_step)\n agent.memory.steps.append(memory_step)\n step_number += 1\n\n # Change the memory as you please!\n # For instance to update the latest step:\n # agent.memory.steps[-1] = ...\n\nprint(\"The final answer is:\", final_answer)\n```"
},
{
"path": "docs/source/zh/tutorials/secure_code_execution.md",
"content": "# 安全代码执行\n\n[[open-in-colab]]\n\n> [!TIP]\n> 如果你是第一次构建 agent，请先阅读 [agent 介绍](../conceptual_guides/intro_agents) 和 [smolagents 导览](../guided_tour)。\n\n### 代码智能体\n\n[多项](https://huggingface.co/papers/2402.01030) [研究](https://huggingface.co/papers/2411.01747) [表明](https://huggingface.co/papers/2401.00812)，让大语言模型用代码编写其动作（工具调用）比当前标准的工具调用格式要好得多，目前行业标准是 \"将动作写成包含工具名称和参数的 JSON\" 的各种变体。\n\n为什么代码更好？因为我们专门为计算机执行的动作而设计编程语言。如果 JSON 片段是更好的方式，那么这个工具包就应该是用 JSON 片段编写的，魔鬼就会嘲笑我们。\n\n代码就是表达计算机动作的更好方式。它具有更好的：\n- **组合性**：你能像定义 Python 函数那样，在 JSON 动作中嵌套其他 JSON 动作，或者定义一组 JSON 动作以便以后重用吗？\n- **对象管理**：你如何在 JSON 中存储像 `generate_image` 这样的动作的输出？\n- **通用性**：代码是为了简单地表达任何可以让计算机做的事情而构建的。\n- **在 LLM 训练语料库中的表示**：天赐良机，为什么不利用已经包含在 LLM 训练语料库中的大量高质量动作呢？\n\n下图展示了这一点，取自 [可执行代码动作引出更好的 LLM 智能体](https://huggingface.co/papers/2402.01030)。\n\n\n\n这就是为什么我们强调提出代码智能体，在本例中是 Python 智能体，这意味着我们要在构建安全的 Python 解释器上投入更多精力。\n\n### 本地 Python 解释器\n\n默认情况下，`CodeAgent` 会在你的环境中运行 LLM 生成的代码。\n这个执行不是由普通的 Python 解释器完成的：我们从零开始重新构建了一个更安全的 `LocalPythonExecutor`。\n这个解释器通过以下方式设计以确保安全：\n - 将导入限制为用户显式传递的列表\n - 限制操作次数以防止无限循环和资源膨胀\n - 不会执行任何未预定义的操作\n\n我们已经在许多用例中使用了这个解释器，从未观察到对环境造成任何损害。\n\n然而，这个解决方案并不是万无一失的：可以想象，如果 LLM 被微调用于恶意操作，仍然可能损害你的环境。例如，如果你允许像 `Pillow` 这样无害的包处理图像，LLM 可能会生成数千张图像保存以膨胀你的硬盘。\n如果你自己选择了 LLM 引擎，这当然不太可能，但它可能会发生。\n\n所以如果你想格外谨慎，可以使用下面描述的远程代码执行选项。\n\n### E2B 代码执行器\n\n为了最大程度的安全性，你可以使用我们与 E2B 的集成在沙盒环境中运行代码。这是一个远程执行服务，可以在隔离的容器中运行你的代码，使代码无法影响你的本地环境。\n\n为此，你需要设置你的 E2B 账户并在环境变量中设置 `E2B_API_KEY`。请前往 [E2B 快速入门文档](https://e2b.dev/docs/quickstart) 了解更多信息。\n\n然后你可以通过 `pip install e2b-code-interpreter python-dotenv` 安装它。\n\n现在你已经准备好了！\n\n要将代码执行器设置为 E2B，只需在初始化 `CodeAgent` 时传递标志 `executor_type=\"e2b\"`。\n请注意，你应该将所有工具的依赖项添加到 `additional_authorized_imports` 中，以便执行器安装它们。\n\n```py\nfrom smolagents import CodeAgent, VisitWebpageTool, InferenceClientModel\nagent = CodeAgent(\n tools = [VisitWebpageTool()],\n model=InferenceClientModel(),\n additional_authorized_imports=[\"requests\", \"markdownify\"],\n executor_type=\"e2b\"\n)\n\nagent.run(\"What was Abraham Lincoln's preferred pet?\")\n```\n\n目前 E2B 代码执行暂不兼容多 agent——因为把 agent 调用放在应该在远程执行的代码块里，是非常混乱的。但我们正在努力做到这件事！\n"
},
{
"path": "docs/source/zh/tutorials/tools.md",
"content": "# 工具\n\n[[open-in-colab]]\n\n在这里，我们将学习高级工具的使用。\n\n> [!TIP]\n> 如果你是构建 agent 的新手，请确保先阅读 [agent 介绍](../conceptual_guides/intro_agents) 和 [smolagents 导览](../guided_tour)。\n\n- [工具](#工具)\n - [什么是工具，如何构建一个工具？](#什么是工具如何构建一个工具)\n - [将你的工具分享到 Hub](#将你的工具分享到-hub)\n - [将 Space 导入为工具](#将-space-导入为工具)\n - [使用 LangChain 工具](#使用-langchain-工具)\n - [管理你的 agent 工具箱](#管理你的-agent-工具箱)\n - [使用工具集合](#使用工具集合)\n\n### 什么是工具，如何构建一个工具？\n\n工具主要是 LLM 可以在 agent 系统中使用的函数。\n\n但要使用它，LLM 需要被提供一个 API：名称、工具描述、输入类型和描述、输出类型。\n\n所以它不能仅仅是一个函数。它应该是一个类。\n\n因此，核心上，工具是一个类，它包装了一个函数，并带有帮助 LLM 理解如何使用它的元数据。\n\n以下是它的结构：\n\n```python\nfrom smolagents import Tool\n\nclass HFModelDownloadsTool(Tool):\n name = \"model_download_counter\"\n description = \"\"\"\n This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub.\n It returns the name of the checkpoint.\"\"\"\n inputs = {\n \"task\": {\n \"type\": \"string\",\n \"description\": \"the task category (such as text-classification, depth-estimation, etc)\",\n }\n }\n output_type = \"string\"\n\n def forward(self, task: str):\n from huggingface_hub import list_models\n\n model = next(iter(list_models(filter=task, sort=\"downloads\", direction=-1)))\n return model.id\n\nmodel_downloads_tool = HFModelDownloadsTool()\n```\n\n自定义工具继承 [`Tool`] 以继承有用的方法。子类还定义了：\n- 一个属性 `name`，对应于工具本身的名称。名称通常描述工具的功能。由于代码返回任务中下载量最多的模型，我们将其命名为 `model_download_counter`。\n- 一个属性 `description`，用于填充 agent 的系统提示。\n- 一个 `inputs` 属性，它是一个带有键 `\"type\"` 和 `\"description\"` 的字典。它包含帮助 Python 解释器对输入做出明智选择的信息。\n- 一个 `output_type` 属性，指定输出类型。`inputs` 和 `output_type` 的类型应为 [Pydantic 格式](https://docs.pydantic.dev/latest/concepts/json_schema/#generating-json-schema)，它们可以是以下之一：`[\"string\", \"boolean\",\"integer\", \"number\", \"image\", \"audio\", \"array\", \"object\", \"any\", \"null\"]`。\n- 一个 `forward` 方法，包含要执行的推理代码。\n\n这就是它在 agent 中使用所需的全部内容！\n\n还有另一种构建工具的方法。在 [guided_tour](../guided_tour) 中，我们使用 `@tool` 装饰器实现了一个工具。[`tool`] 装饰器是定义简单工具的推荐方式，但有时你需要更多：在类中使用多个方法以获得更清晰的代码，或使用额外的类属性。\n\n在这种情况下，你可以通过如上所述继承 [`Tool`] 来构建你的工具。\n\n### 将你的工具分享到 Hub\n\n你可以通过调用 [`~Tool.push_to_hub`] 将你的自定义工具分享到 Hub。确保你已经在 Hub 上为其创建了一个仓库，并且使用的是具有读取权限的 token。\n\n```python\nmodel_downloads_tool.push_to_hub(\"{your_username}/hf-model-downloads\", token=\"\n\n然后你可以像使用任何其他工具一样使用这个工具。例如，让我们改进提示 `A rabbit wearing a space suit` 并生成它的图片。\n\n```python\nfrom smolagents import CodeAgent, InferenceClientModel\n\nmodel = InferenceClientModel(model_id=\"Qwen/Qwen3-Next-80B-A3B-Thinking\")\nagent = CodeAgent(tools=[image_generation_tool], model=model)\n\nagent.run(\n \"Improve this prompt, then generate an image of it.\", additional_args={'user_prompt': 'A rabbit wearing a space suit'}\n)\n```\n\n```text\n=== Agent thoughts:\nimproved_prompt could be \"A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background\"\n\nNow that I have improved the prompt, I can use the image generator tool to generate an image based on this prompt.\n>>> Agent is executing the code below:\nimage = image_generator(prompt=\"A bright blue space suit wearing rabbit, on the surface of the moon, under a bright orange sunset, with the Earth visible in the background\")\nfinal_answer(image)\n```\n\n\n\n这得有多酷？🤩\n\n### 使用 LangChain 工具\n\n我们喜欢 Langchain，并认为它有一套非常吸引人的工具。\n要从 LangChain 导入工具，请使用 `from_langchain()` 方法。\n\n以下是如何使用它来重现介绍中的搜索结果，使用 LangChain 的 web 搜索工具。\n这个工具需要 `pip install langchain google-search-results -q` 才能正常工作。\n```python\nfrom langchain.agents import load_tools\n\nsearch_tool = Tool.from_langchain(load_tools([\"serpapi\"])[0])\n\nagent = CodeAgent(tools=[search_tool], model=model)\n\nagent.run(\"How many more blocks (also denoted as layers) are in BERT base encoder compared to the encoder from the architecture proposed in Attention is All You Need?\")\n```\n\n### 管理你的 agent 工具箱\n\n你可以通过添加或替换工具来管理 agent 的工具箱。\n\n让我们将 `model_download_tool` 添加到一个仅使用默认工具箱初始化的现有 agent 中。\n\n```python\nfrom smolagents import InferenceClientModel\n\nmodel = InferenceClientModel(model_id=\"Qwen/Qwen3-Next-80B-A3B-Thinking\")\n\nagent = CodeAgent(tools=[], model=model, add_base_tools=True)\nagent.tools[model_download_tool.name] = model_download_tool\n```\n现在我们可以利用新工具：\n\n```python\nagent.run(\n \"Can you give me the name of the model that has the most downloads in the 'text-to-video' task on the Hugging Face Hub but reverse the letters?\"\n)\n```\n\n\n> [!TIP]\n> 注意不要向 agent 添加太多工具：这可能会让较弱的 LLM 引擎不堪重负。\n\n\n### 使用工具集合\n\n你可以通过使用 ToolCollection 对象来利用工具集合，使用你想要使用的集合的 slug。\n然后将它们作为列表传递给 agent 初始化，并开始使用它们！\n\n```py\nfrom smolagents import ToolCollection, CodeAgent\n\nimage_tool_collection = ToolCollection.from_hub(\n collection_slug=\"huggingface-tools/diffusion-tools-6630bb19a942c2306a2cdb6f\",\n token=\"| \" + html.escape(cell.text) + \" | \"\n else:\n html_table += \"\" + html.escape(cell.text) + \" | \"\n html_table += \"
|---|
\", \"\").\n **kwargs: Additional keyword arguments.\n \"\"\"\n\n def __init__(\n self,\n tools: list[Tool],\n model: Model,\n prompt_templates: PromptTemplates | None = None,\n additional_authorized_imports: list[str] | None = None,\n planning_interval: int | None = None,\n executor: PythonExecutor = None,\n executor_type: Literal[\"local\", \"blaxel\", \"e2b\", \"modal\", \"docker\", \"wasm\"] = \"local\",\n executor_kwargs: dict[str, Any] | None = None,\n max_print_outputs_length: int | None = None,\n stream_outputs: bool = False,\n use_structured_outputs_internally: bool = False,\n code_block_tags: str | tuple[str, str] | None = None,\n **kwargs,\n ):\n self.additional_authorized_imports = additional_authorized_imports if additional_authorized_imports else []\n self.authorized_imports = sorted(set(BASE_BUILTIN_MODULES) | set(self.additional_authorized_imports))\n self.max_print_outputs_length = max_print_outputs_length\n self._use_structured_outputs_internally = use_structured_outputs_internally\n if self._use_structured_outputs_internally:\n prompt_templates = prompt_templates or yaml.safe_load(\n importlib.resources.files(\"smolagents.prompts\").joinpath(\"structured_code_agent.yaml\").read_text()\n )\n else:\n prompt_templates = prompt_templates or yaml.safe_load(\n importlib.resources.files(\"smolagents.prompts\").joinpath(\"code_agent.yaml\").read_text()\n )\n\n if isinstance(code_block_tags, str) and not code_block_tags == \"markdown\":\n raise ValueError(\"Only 'markdown' is supported for a string argument to `code_block_tags`.\")\n self.code_block_tags = (\n code_block_tags\n if isinstance(code_block_tags, tuple)\n else (\"```python\", \"```\")\n if code_block_tags == \"markdown\"\n else (\"\", \"\")\n )\n\n super().__init__(\n tools=tools,\n model=model,\n prompt_templates=prompt_templates,\n planning_interval=planning_interval,\n **kwargs,\n )\n self.stream_outputs = stream_outputs\n if self.stream_outputs and not hasattr(self.model, \"generate_stream\"):\n raise ValueError(\n \"`stream_outputs` is set to True, but the model class implements no `generate_stream` method.\"\n )\n if \"*\" in self.additional_authorized_imports:\n self.logger.log(\n \"Caution: you set an authorization for all imports, meaning your agent can decide to import any package it deems necessary. This might raise issues if the package is not installed in your environment.\",\n level=LogLevel.INFO,\n )\n self.executor_type = executor_type\n self.executor_kwargs: dict[str, Any] = executor_kwargs or {}\n self.python_executor = executor or self.create_python_executor()\n\n def __enter__(self):\n return self\n\n def __exit__(self, exc_type, exc_value, traceback):\n self.cleanup()\n\n def cleanup(self):\n \"\"\"Clean up resources used by the agent, such as the remote Python executor.\"\"\"\n if hasattr(self.python_executor, \"cleanup\"):\n self.python_executor.cleanup()\n\n def create_python_executor(self) -> PythonExecutor:\n if self.executor_type not in {\"local\", \"blaxel\", \"e2b\", \"modal\", \"docker\", \"wasm\"}:\n raise ValueError(f\"Unsupported executor type: {self.executor_type}\")\n\n if self.executor_type == \"local\":\n return LocalPythonExecutor(\n self.additional_authorized_imports,\n **{\"max_print_outputs_length\": self.max_print_outputs_length} | self.executor_kwargs,\n )\n else:\n if self.managed_agents:\n raise Exception(\"Managed agents are not yet supported with remote code execution.\")\n remote_executors = {\n \"blaxel\": BlaxelExecutor,\n \"e2b\": E2BExecutor,\n \"docker\": DockerExecutor,\n \"wasm\": WasmExecutor,\n \"modal\": ModalExecutor,\n }\n return remote_executors[self.executor_type](\n self.additional_authorized_imports, self.logger, **self.executor_kwargs\n )\n\n def initialize_system_prompt(self) -> str:\n system_prompt = populate_template(\n self.prompt_templates[\"system_prompt\"],\n variables={\n \"tools\": self.tools,\n \"managed_agents\": self.managed_agents,\n \"authorized_imports\": (\n \"You can import from any package you want.\"\n if \"*\" in self.authorized_imports\n else str(self.authorized_imports)\n ),\n \"custom_instructions\": self.instructions,\n \"code_block_opening_tag\": self.code_block_tags[0],\n \"code_block_closing_tag\": self.code_block_tags[1],\n },\n )\n return system_prompt\n\n def _step_stream(\n self, memory_step: ActionStep\n ) -> Generator[ChatMessageStreamDelta | ToolCall | ToolOutput | ActionOutput]:\n \"\"\"\n Perform one step in the ReAct framework: the agent thinks, acts, and observes the result.\n Yields ChatMessageStreamDelta during the run if streaming is enabled.\n At the end, yields either None if the step is not final, or the final answer.\n \"\"\"\n memory_messages = self.write_memory_to_messages()\n\n input_messages = memory_messages.copy()\n ### Generate model output ###\n memory_step.model_input_messages = input_messages\n stop_sequences = [\"Observation:\", \"Calling tools:\"]\n if self.code_block_tags[1] not in self.code_block_tags[0]:\n # If the closing tag is contained in the opening tag, adding it as a stop sequence would cut short any code generation\n stop_sequences.append(self.code_block_tags[1])\n try:\n additional_args: dict[str, Any] = {}\n if self._use_structured_outputs_internally:\n additional_args[\"response_format\"] = CODEAGENT_RESPONSE_FORMAT\n if self.stream_outputs:\n output_stream = self.model.generate_stream(\n input_messages,\n stop_sequences=stop_sequences,\n **additional_args,\n )\n chat_message_stream_deltas: list[ChatMessageStreamDelta] = []\n with Live(\"\", console=self.logger.console, vertical_overflow=\"visible\") as live:\n for event in output_stream:\n chat_message_stream_deltas.append(event)\n live.update(\n Markdown(agglomerate_stream_deltas(chat_message_stream_deltas).render_as_markdown())\n )\n yield event\n chat_message = agglomerate_stream_deltas(chat_message_stream_deltas)\n memory_step.model_output_message = chat_message\n output_text = chat_message.content\n else:\n chat_message: ChatMessage = self.model.generate(\n input_messages,\n stop_sequences=stop_sequences,\n **additional_args,\n )\n memory_step.model_output_message = chat_message\n output_text = chat_message.content\n self.logger.log_markdown(\n content=output_text or \"\",\n title=\"Output message of the LLM:\",\n level=LogLevel.DEBUG,\n )\n\n if not self._use_structured_outputs_internally:\n # This adds the end code sequence (i.e. the closing code block tag) to the history.\n # This will nudge subsequent LLM calls to finish with this end code sequence, thus efficiently stopping generation.\n if output_text and not output_text.strip().endswith(self.code_block_tags[1]):\n output_text += self.code_block_tags[1]\n memory_step.model_output_message.content = output_text\n\n memory_step.token_usage = chat_message.token_usage\n memory_step.model_output = output_text\n except Exception as e:\n raise AgentGenerationError(f\"Error in generating model output:\\n{e}\", self.logger) from e\n\n ### Parse output ###\n try:\n if self._use_structured_outputs_internally:\n code_action = json.loads(output_text)[\"code\"]\n code_action = extract_code_from_text(code_action, self.code_block_tags) or code_action\n else:\n code_action = parse_code_blobs(output_text, self.code_block_tags)\n code_action = fix_final_answer_code(code_action)\n memory_step.code_action = code_action\n except Exception as e:\n error_msg = f\"Error in code parsing:\\n{e}\\nMake sure to provide correct code blobs.\"\n raise AgentParsingError(error_msg, self.logger)\n\n tool_call = ToolCall(\n name=\"python_interpreter\",\n arguments=code_action,\n id=f\"call_{len(self.memory.steps)}\",\n )\n yield tool_call\n memory_step.tool_calls = [tool_call]\n\n ### Execute action ###\n self.logger.log_code(title=\"Executing parsed code:\", content=code_action, level=LogLevel.INFO)\n try:\n code_output = self.python_executor(code_action)\n execution_outputs_console = []\n if len(code_output.logs) > 0:\n execution_outputs_console += [\n Text(\"Execution logs:\", style=\"bold\"),\n Text(code_output.logs),\n ]\n observation = \"Execution logs:\\n\" + code_output.logs\n except Exception as e:\n if hasattr(self.python_executor, \"state\") and \"_print_outputs\" in self.python_executor.state:\n execution_logs = str(self.python_executor.state[\"_print_outputs\"])\n if len(execution_logs) > 0:\n execution_outputs_console = [\n Text(\"Execution logs:\", style=\"bold\"),\n Text(execution_logs),\n ]\n memory_step.observations = \"Execution logs:\\n\" + execution_logs\n self.logger.log(Group(*execution_outputs_console), level=LogLevel.INFO)\n error_msg = str(e)\n if \"Import of \" in error_msg and \" is not allowed\" in error_msg:\n self.logger.log(\n \"[bold red]Warning to user: Code execution failed due to an unauthorized import - Consider passing said import under `additional_authorized_imports` when initializing your CodeAgent.\",\n level=LogLevel.INFO,\n )\n raise AgentExecutionError(error_msg, self.logger)\n\n truncated_output = truncate_content(str(code_output.output))\n observation += \"Last output from code snippet:\\n\" + truncated_output\n memory_step.observations = observation\n\n if not code_output.is_final_answer:\n execution_outputs_console += [\n Text(\n f\"Out: {truncated_output}\",\n ),\n ]\n self.logger.log(Group(*execution_outputs_console), level=LogLevel.INFO)\n memory_step.action_output = code_output.output\n yield ActionOutput(output=code_output.output, is_final_answer=code_output.is_final_answer)\n\n def to_dict(self) -> dict[str, Any]:\n \"\"\"Convert the agent to a dictionary representation.\n\n Returns:\n `dict`: Dictionary representation of the agent.\n \"\"\"\n agent_dict = super().to_dict()\n agent_dict[\"authorized_imports\"] = self.authorized_imports\n agent_dict[\"executor_type\"] = self.executor_type\n agent_dict[\"executor_kwargs\"] = self.executor_kwargs\n agent_dict[\"max_print_outputs_length\"] = self.max_print_outputs_length\n return agent_dict\n\n @classmethod\n def from_dict(cls, agent_dict: dict[str, Any], **kwargs) -> \"CodeAgent\":\n \"\"\"Create CodeAgent from a dictionary representation.\n\n Args:\n agent_dict (`dict[str, Any]`): Dictionary representation of the agent.\n **kwargs: Additional keyword arguments that will override agent_dict values.\n\n Returns:\n `CodeAgent`: Instance of the CodeAgent class.\n \"\"\"\n # Add CodeAgent-specific parameters to kwargs\n code_agent_kwargs = {\n \"additional_authorized_imports\": agent_dict.get(\"authorized_imports\"),\n \"executor_type\": agent_dict.get(\"executor_type\"),\n \"executor_kwargs\": agent_dict.get(\"executor_kwargs\"),\n \"max_print_outputs_length\": agent_dict.get(\"max_print_outputs_length\"),\n \"code_block_tags\": agent_dict.get(\"code_block_tags\"),\n }\n # Filter out None values\n code_agent_kwargs = {k: v for k, v in code_agent_kwargs.items() if v is not None}\n # Update with any additional kwargs\n code_agent_kwargs.update(kwargs)\n # Call the parent class's from_dict method\n return super().from_dict(agent_dict, **code_agent_kwargs)\n\n\n# Agent Registry for secure deserialization\n# This registry maps agent class names to their actual classes.\n# Only classes listed here can be instantiated during deserialization (from_dict/from_folder).\n# This prevents arbitrary code execution via importlib-based dynamic loading.\nAGENT_REGISTRY = {\n \"ToolCallingAgent\": ToolCallingAgent,\n \"CodeAgent\": CodeAgent,\n}\n"
},
{
"path": "src/smolagents/cli.py",
"content": "#!/usr/bin/env python\n# coding=utf-8\n\n# Copyright 2025 The HuggingFace Inc. team. All rights reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nimport argparse\nimport os\n\nfrom dotenv import load_dotenv\nfrom rich.console import Console\nfrom rich.panel import Panel\nfrom rich.prompt import Confirm, Prompt\nfrom rich.rule import Rule\nfrom rich.table import Table\n\nfrom smolagents import (\n CodeAgent,\n InferenceClientModel,\n LiteLLMModel,\n Model,\n OpenAIModel,\n Tool,\n ToolCallingAgent,\n TransformersModel,\n)\nfrom smolagents.default_tools import TOOL_MAPPING\n\n\nconsole = Console()\n\nleopard_prompt = \"How many seconds would it take for a leopard at full speed to run through Pont des Arts?\"\n\n\ndef parse_arguments():\n parser = argparse.ArgumentParser(description=\"Run a CodeAgent with all specified parameters\")\n parser.add_argument(\n \"prompt\",\n type=str,\n nargs=\"?\",\n default=None,\n help=\"The prompt to run with the agent. If no prompt is provided, interactive mode will be launched to guide user through agent setup\",\n )\n parser.add_argument(\n \"--model-type\",\n type=str,\n default=\"InferenceClientModel\",\n help=\"The model type to use (e.g., InferenceClientModel, OpenAIModel, LiteLLMModel, TransformersModel)\",\n )\n parser.add_argument(\n \"--action-type\",\n type=str,\n default=\"code\",\n help=\"The action type to use (e.g., code, tool_calling)\",\n )\n parser.add_argument(\n \"--model-id\",\n type=str,\n default=\"Qwen/Qwen3-Next-80B-A3B-Thinking\",\n help=\"The model ID to use for the specified model type\",\n )\n parser.add_argument(\n \"--imports\",\n nargs=\"*\", # accepts zero or more arguments\n default=[],\n help=\"Space-separated list of imports to authorize (e.g., 'numpy pandas')\",\n )\n parser.add_argument(\n \"--tools\",\n nargs=\"*\",\n default=[\"web_search\"],\n help=\"Space-separated list of tools that the agent can use (e.g., 'tool1 tool2 tool3')\",\n )\n parser.add_argument(\n \"--verbosity-level\",\n type=int,\n default=1,\n help=\"The verbosity level, as an int in [0, 1, 2].\",\n )\n group = parser.add_argument_group(\"api options\", \"Options for API-based model types\")\n group.add_argument(\n \"--provider\",\n type=str,\n default=None,\n help=\"The inference provider to use for the model\",\n )\n group.add_argument(\n \"--api-base\",\n type=str,\n help=\"The base URL for the model\",\n )\n group.add_argument(\n \"--api-key\",\n type=str,\n help=\"The API key for the model\",\n )\n return parser.parse_args()\n\n\ndef interactive_mode():\n \"\"\"Run the CLI in interactive mode\"\"\"\n console.print(\n Panel.fit(\n \"[bold magenta]🤖 SmolaGents CLI[/]\\n[dim]Intelligent agents at your service[/]\", border_style=\"magenta\"\n )\n )\n\n console.print(\"\\n[bold yellow]Welcome to smolagents![/] Let's set up your agent step by step.\\n\")\n\n # Get user input step by step\n console.print(Rule(\"[bold yellow]⚙️ Configuration\", style=\"bold yellow\"))\n\n # Get agent action type\n action_type = Prompt.ask(\n \"[bold white]What action type would you like to use? 'code' or 'tool_calling'?[/]\",\n default=\"code\",\n choices=[\"code\", \"tool_calling\"],\n )\n\n # Show available tools\n tools_table = Table(title=\"[bold yellow]🛠️ Available Tools\", show_header=True, header_style=\"bold yellow\")\n tools_table.add_column(\"Tool Name\", style=\"bold yellow\")\n tools_table.add_column(\"Description\", style=\"white\")\n\n for tool_name, tool_class in TOOL_MAPPING.items():\n # Get description from the tool class if available\n try:\n tool_instance = tool_class()\n description = getattr(tool_instance, \"description\", \"No description available\")\n except Exception:\n description = \"Built-in tool\"\n tools_table.add_row(tool_name, description)\n\n console.print(tools_table)\n console.print(\n \"\\n[dim]You can also use HuggingFace Spaces by providing the full path (e.g., 'username/spacename')[/]\"\n )\n\n console.print(\"[dim]Enter tool names separated by spaces (e.g., 'web_search python_interpreter')[/]\")\n tools_input = Prompt.ask(\"[bold white]Select tools for your agent[/]\", default=\"web_search\")\n tools = tools_input.split()\n\n # Get model configuration\n console.print(\"\\n[bold yellow]Model Configuration:[/]\")\n model_type = Prompt.ask(\n \"[bold]Model type[/]\",\n default=\"InferenceClientModel\",\n choices=[\"InferenceClientModel\", \"OpenAIServerModel\", \"LiteLLMModel\", \"TransformersModel\"],\n )\n\n model_id = Prompt.ask(\"[bold white]Model ID[/]\", default=\"Qwen/Qwen2.5-Coder-32B-Instruct\")\n\n # Optional configurations\n provider = None\n api_base = None\n api_key = None\n imports = []\n action_type = \"code\"\n\n if Confirm.ask(\"\\n[bold white]Configure advanced options?[/]\", default=False):\n if model_type in [\"InferenceClientModel\", \"OpenAIServerModel\", \"LiteLLMModel\"]:\n provider = Prompt.ask(\"[bold white]Provider[/]\", default=\"\")\n api_base = Prompt.ask(\"[bold white]API Base URL[/]\", default=\"\")\n api_key = Prompt.ask(\"[bold white]API Key[/]\", default=\"\", password=True)\n\n imports_input = Prompt.ask(\"[bold white]Additional imports (space-separated)[/]\", default=\"\")\n if imports_input:\n imports = imports_input.split()\n\n # Get prompt\n prompt = Prompt.ask(\n \"[bold white]Now the final step; what task would you like the agent to perform?[/]\", default=leopard_prompt\n )\n\n return prompt, tools, model_type, model_id, provider, api_base, api_key, imports, action_type\n\n\ndef load_model(\n model_type: str,\n model_id: str,\n api_base: str | None = None,\n api_key: str | None = None,\n provider: str | None = None,\n) -> Model:\n if model_type == \"OpenAIModel\":\n return OpenAIModel(\n api_key=api_key or os.getenv(\"FIREWORKS_API_KEY\"),\n api_base=api_base or \"https://api.fireworks.ai/inference/v1\",\n model_id=model_id,\n )\n elif model_type == \"LiteLLMModel\":\n return LiteLLMModel(\n model_id=model_id,\n api_key=api_key,\n api_base=api_base,\n )\n elif model_type == \"TransformersModel\":\n return TransformersModel(model_id=model_id, device_map=\"auto\")\n elif model_type == \"InferenceClientModel\":\n return InferenceClientModel(\n model_id=model_id,\n token=api_key or os.getenv(\"HF_API_KEY\"),\n provider=provider,\n )\n else:\n raise ValueError(f\"Unsupported model type: {model_type}\")\n\n\ndef run_smolagent(\n prompt: str,\n tools: list[str],\n model_type: str,\n model_id: str,\n api_base: str | None = None,\n api_key: str | None = None,\n imports: list[str] | None = None,\n provider: str | None = None,\n action_type: str = \"code\",\n) -> None:\n load_dotenv()\n\n model = load_model(model_type, model_id, api_base=api_base, api_key=api_key, provider=provider)\n\n available_tools = []\n\n for tool_name in tools:\n if \"/\" in tool_name:\n space_name = tool_name.split(\"/\")[-1].lower().replace(\"-\", \"_\").replace(\".\", \"_\")\n description = f\"Tool loaded from Hugging Face Space: {tool_name}\"\n available_tools.append(Tool.from_space(space_id=tool_name, name=space_name, description=description))\n else:\n if tool_name in TOOL_MAPPING:\n available_tools.append(TOOL_MAPPING[tool_name]())\n else:\n raise ValueError(f\"Tool {tool_name} is not recognized either as a default tool or a Space.\")\n\n if action_type == \"code\":\n agent = CodeAgent(\n tools=available_tools,\n model=model,\n additional_authorized_imports=imports,\n stream_outputs=True,\n )\n elif action_type == \"tool_calling\":\n agent = ToolCallingAgent(tools=available_tools, model=model, stream_outputs=True)\n else:\n raise ValueError(f\"Unsupported action type: {action_type}\")\n\n agent.run(prompt)\n\n\ndef main() -> None:\n args = parse_arguments()\n\n # Check if we should run in interactive mode\n # Interactive mode is triggered when no prompt is provided\n if args.prompt is None:\n prompt, tools, model_type, model_id, provider, api_base, api_key, imports, action_type = interactive_mode()\n else:\n prompt = args.prompt\n tools = args.tools\n model_type = args.model_type\n model_id = args.model_id\n provider = args.provider\n api_base = args.api_base\n api_key = args.api_key\n imports = args.imports\n action_type = args.action_type\n\n run_smolagent(\n prompt,\n tools,\n model_type,\n model_id,\n provider=provider,\n api_base=api_base,\n api_key=api_key,\n imports=imports,\n action_type=action_type,\n )\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "src/smolagents/default_tools.py",
"content": "#!/usr/bin/env python\n# coding=utf-8\n\n# Copyright 2024 The HuggingFace Inc. team. All rights reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nfrom dataclasses import dataclass\nfrom typing import Any\n\nfrom .local_python_executor import (\n BASE_BUILTIN_MODULES,\n BASE_PYTHON_TOOLS,\n MAX_EXECUTION_TIME_SECONDS,\n evaluate_python_code,\n)\nfrom .tools import PipelineTool, Tool\n\n\n@dataclass\nclass PreTool:\n name: str\n inputs: dict[str, str]\n output_type: type\n task: str\n description: str\n repo_id: str\n\n\nclass PythonInterpreterTool(Tool):\n name = \"python_interpreter\"\n description = \"This is a tool that evaluates python code. It can be used to perform calculations.\"\n inputs = {\n \"code\": {\n \"type\": \"string\",\n \"description\": \"The python code to run in interpreter\",\n }\n }\n output_type = \"string\"\n\n def __init__(self, *args, authorized_imports=None, timeout_seconds=MAX_EXECUTION_TIME_SECONDS, **kwargs):\n if authorized_imports is None:\n self.authorized_imports = list(set(BASE_BUILTIN_MODULES))\n else:\n self.authorized_imports = list(set(BASE_BUILTIN_MODULES) | set(authorized_imports))\n self.inputs = {\n \"code\": {\n \"type\": \"string\",\n \"description\": (\n \"The code snippet to evaluate. All variables used in this snippet must be defined in this same snippet, \"\n f\"else you will get an error. This code can only import the following python libraries: {self.authorized_imports}.\"\n ),\n }\n }\n self.base_python_tools = BASE_PYTHON_TOOLS\n self.python_evaluator = evaluate_python_code\n self.timeout_seconds = timeout_seconds\n super().__init__(*args, **kwargs)\n\n def forward(self, code: str) -> str:\n state = {}\n output = str(\n self.python_evaluator(\n code,\n state=state,\n static_tools=self.base_python_tools,\n authorized_imports=self.authorized_imports,\n timeout_seconds=self.timeout_seconds,\n )[0] # The second element is boolean is_final_answer\n )\n return f\"Stdout:\\n{str(state['_print_outputs'])}\\nOutput: {output}\"\n\n\nclass FinalAnswerTool(Tool):\n name = \"final_answer\"\n description = \"Provides a final answer to the given problem.\"\n inputs = {\"answer\": {\"type\": \"any\", \"description\": \"The final answer to the problem\"}}\n output_type = \"any\"\n\n def forward(self, answer: Any) -> Any:\n return answer\n\n\nclass UserInputTool(Tool):\n name = \"user_input\"\n description = \"Asks for user's input on a specific question\"\n inputs = {\"question\": {\"type\": \"string\", \"description\": \"The question to ask the user\"}}\n output_type = \"string\"\n\n def forward(self, question):\n user_input = input(f\"{question} => Type your answer here:\")\n return user_input\n\n\nclass DuckDuckGoSearchTool(Tool):\n \"\"\"Web search tool that performs searches using the DuckDuckGo search engine.\n\n Args:\n max_results (`int`, default `10`): Maximum number of search results to return.\n rate_limit (`float`, default `1.0`): Maximum queries per second. Set to `None` to disable rate limiting.\n **kwargs: Additional keyword arguments for the `DDGS` client.\n\n Examples:\n ```python\n >>> from smolagents import DuckDuckGoSearchTool\n >>> web_search_tool = DuckDuckGoSearchTool(max_results=5, rate_limit=2.0)\n >>> results = web_search_tool(\"Hugging Face\")\n >>> print(results)\n ```\n \"\"\"\n\n name = \"web_search\"\n description = \"\"\"Performs a duckduckgo web search based on your query (think a Google search) then returns the top search results.\"\"\"\n inputs = {\"query\": {\"type\": \"string\", \"description\": \"The search query to perform.\"}}\n output_type = \"string\"\n\n def __init__(self, max_results: int = 10, rate_limit: float | None = 1.0, **kwargs):\n super().__init__()\n self.max_results = max_results\n self.rate_limit = rate_limit\n self._min_interval = 1.0 / rate_limit if rate_limit else 0.0\n self._last_request_time = 0.0\n try:\n from ddgs import DDGS\n except ImportError as e:\n raise ImportError(\n \"You must install package `ddgs` to run this tool: for instance run `pip install ddgs`.\"\n ) from e\n self.ddgs = DDGS(**kwargs)\n\n def forward(self, query: str) -> str:\n self._enforce_rate_limit()\n results = self.ddgs.text(query, max_results=self.max_results)\n if len(results) == 0:\n raise Exception(\"No results found! Try a less restrictive/shorter query.\")\n postprocessed_results = [f\"[{result['title']}]({result['href']})\\n{result['body']}\" for result in results]\n return \"## Search Results\\n\\n\" + \"\\n\\n\".join(postprocessed_results)\n\n def _enforce_rate_limit(self) -> None:\n import time\n\n # No rate limit enforced\n if not self.rate_limit:\n return\n\n now = time.time()\n elapsed = now - self._last_request_time\n if elapsed < self._min_interval:\n time.sleep(self._min_interval - elapsed)\n self._last_request_time = time.time()\n\n\nclass GoogleSearchTool(Tool):\n name = \"web_search\"\n description = \"\"\"Performs a google web search for your query then returns a string of the top search results.\"\"\"\n inputs = {\n \"query\": {\"type\": \"string\", \"description\": \"The search query to perform.\"},\n \"filter_year\": {\n \"type\": \"integer\",\n \"description\": \"Optionally restrict results to a certain year\",\n \"nullable\": True,\n },\n }\n output_type = \"string\"\n\n def __init__(self, provider: str = \"serpapi\"):\n super().__init__()\n import os\n\n self.provider = provider\n if provider == \"serpapi\":\n self.organic_key = \"organic_results\"\n api_key_env_name = \"SERPAPI_API_KEY\"\n else:\n self.organic_key = \"organic\"\n api_key_env_name = \"SERPER_API_KEY\"\n self.api_key = os.getenv(api_key_env_name)\n if self.api_key is None:\n raise ValueError(f\"Missing API key. Make sure you have '{api_key_env_name}' in your env variables.\")\n\n def forward(self, query: str, filter_year: int | None = None) -> str:\n import requests\n\n if self.provider == \"serpapi\":\n params = {\n \"q\": query,\n \"api_key\": self.api_key,\n \"engine\": \"google\",\n \"google_domain\": \"google.com\",\n }\n base_url = \"https://serpapi.com/search.json\"\n else:\n params = {\n \"q\": query,\n \"api_key\": self.api_key,\n }\n base_url = \"https://google.serper.dev/search\"\n if filter_year is not None:\n params[\"tbs\"] = f\"cdr:1,cd_min:01/01/{filter_year},cd_max:12/31/{filter_year}\"\n\n response = requests.get(base_url, params=params)\n\n if response.status_code == 200:\n results = response.json()\n else:\n raise ValueError(response.json())\n\n if self.organic_key not in results.keys():\n if filter_year is not None:\n raise Exception(\n f\"No results found for query: '{query}' with filtering on year={filter_year}. Use a less restrictive query or do not filter on year.\"\n )\n else:\n raise Exception(f\"No results found for query: '{query}'. Use a less restrictive query.\")\n if len(results[self.organic_key]) == 0:\n year_filter_message = f\" with filter year={filter_year}\" if filter_year is not None else \"\"\n return f\"No results found for '{query}'{year_filter_message}. Try with a more general query, or remove the year filter.\"\n\n web_snippets = []\n if self.organic_key in results:\n for idx, page in enumerate(results[self.organic_key]):\n date_published = \"\"\n if \"date\" in page:\n date_published = \"\\nDate published: \" + page[\"date\"]\n\n source = \"\"\n if \"source\" in page:\n source = \"\\nSource: \" + page[\"source\"]\n\n snippet = \"\"\n if \"snippet\" in page:\n snippet = \"\\n\" + page[\"snippet\"]\n\n redacted_version = f\"{idx}. [{page['title']}]({page['link']}){date_published}{source}\\n{snippet}\"\n web_snippets.append(redacted_version)\n\n return \"## Search Results\\n\" + \"\\n\\n\".join(web_snippets)\n\n\nclass ApiWebSearchTool(Tool):\n \"\"\"Web search tool that performs API-based searches.\n By default, it uses the Brave Search API.\n\n This tool implements a rate limiting mechanism to ensure compliance with API usage policies.\n By default, it limits requests to 1 query per second.\n\n Args:\n endpoint (`str`): API endpoint URL. Defaults to Brave Search API.\n api_key (`str`): API key for authentication.\n api_key_name (`str`): Environment variable name containing the API key. Defaults to \"BRAVE_API_KEY\".\n headers (`dict`, *optional*): Headers for API requests.\n params (`dict`, *optional*): Parameters for API requests.\n rate_limit (`float`, default `1.0`): Maximum queries per second. Set to `None` to disable rate limiting.\n\n Examples:\n ```python\n >>> from smolagents import ApiWebSearchTool\n >>> web_search_tool = ApiWebSearchTool(rate_limit=50.0)\n >>> results = web_search_tool(\"Hugging Face\")\n >>> print(results)\n ```\n \"\"\"\n\n name = \"web_search\"\n description = \"Performs a web search for a query and returns a string of the top search results formatted as markdown with titles, URLs, and descriptions.\"\n inputs = {\"query\": {\"type\": \"string\", \"description\": \"The search query to perform.\"}}\n output_type = \"string\"\n\n def __init__(\n self,\n endpoint: str = \"\",\n api_key: str = \"\",\n api_key_name: str = \"\",\n headers: dict = None,\n params: dict = None,\n rate_limit: float | None = 1.0,\n ):\n import os\n\n super().__init__()\n self.endpoint = endpoint or \"https://api.search.brave.com/res/v1/web/search\"\n self.api_key_name = api_key_name or \"BRAVE_API_KEY\"\n self.api_key = api_key or os.getenv(self.api_key_name)\n self.headers = headers or {\"X-Subscription-Token\": self.api_key}\n self.params = params or {\"count\": 10}\n self.rate_limit = rate_limit\n self._min_interval = 1.0 / rate_limit if rate_limit else 0.0\n self._last_request_time = 0.0\n\n def _enforce_rate_limit(self) -> None:\n import time\n\n # No rate limit enforced\n if not self.rate_limit:\n return\n\n now = time.time()\n elapsed = now - self._last_request_time\n if elapsed < self._min_interval:\n time.sleep(self._min_interval - elapsed)\n self._last_request_time = time.time()\n\n def forward(self, query: str) -> str:\n import requests\n\n self._enforce_rate_limit()\n params = {**self.params, \"q\": query}\n response = requests.get(self.endpoint, headers=self.headers, params=params)\n response.raise_for_status()\n data = response.json()\n results = self.extract_results(data)\n return self.format_markdown(results)\n\n def extract_results(self, data: dict) -> list:\n results = []\n for result in data.get(\"web\", {}).get(\"results\", []):\n results.append(\n {\"title\": result[\"title\"], \"url\": result[\"url\"], \"description\": result.get(\"description\", \"\")}\n )\n return results\n\n def format_markdown(self, results: list) -> str:\n if not results:\n return \"No results found.\"\n return \"## Search Results\\n\\n\" + \"\\n\\n\".join(\n [\n f\"{idx}. [{result['title']}]({result['url']})\\n{result['description']}\"\n for idx, result in enumerate(results, start=1)\n ]\n )\n\n\nclass WebSearchTool(Tool):\n name = \"web_search\"\n description = \"Performs a web search for a query and returns a string of the top search results formatted as markdown with titles, links, and descriptions.\"\n inputs = {\"query\": {\"type\": \"string\", \"description\": \"The search query to perform.\"}}\n output_type = \"string\"\n\n def __init__(self, max_results: int = 10, engine: str = \"duckduckgo\"):\n super().__init__()\n self.max_results = max_results\n self.engine = engine\n\n def forward(self, query: str) -> str:\n results = self.search(query)\n if len(results) == 0:\n raise Exception(\"No results found! Try a less restrictive/shorter query.\")\n return self.parse_results(results)\n\n def search(self, query: str) -> list:\n if self.engine == \"duckduckgo\":\n return self.search_duckduckgo(query)\n elif self.engine == \"bing\":\n return self.search_bing(query)\n else:\n raise ValueError(f\"Unsupported engine: {self.engine}\")\n\n def parse_results(self, results: list) -> str:\n return \"## Search Results\\n\\n\" + \"\\n\\n\".join(\n [f\"[{result['title']}]({result['link']})\\n{result['description']}\" for result in results]\n )\n\n def search_duckduckgo(self, query: str) -> list:\n import requests\n\n response = requests.get(\n \"https://lite.duckduckgo.com/lite/\",\n params={\"q\": query},\n headers={\"User-Agent\": \"Mozilla/5.0\"},\n )\n response.raise_for_status()\n parser = self._create_duckduckgo_parser()\n parser.feed(response.text)\n return parser.results\n\n def _create_duckduckgo_parser(self):\n from html.parser import HTMLParser\n\n class SimpleResultParser(HTMLParser):\n def __init__(self):\n super().__init__()\n self.results = []\n self.current = {}\n self.capture_title = False\n self.capture_description = False\n self.capture_link = False\n\n def handle_starttag(self, tag, attrs):\n attrs = dict(attrs)\n if tag == \"a\" and attrs.get(\"class\") == \"result-link\":\n self.capture_title = True\n elif tag == \"td\" and attrs.get(\"class\") == \"result-snippet\":\n self.capture_description = True\n elif tag == \"span\" and attrs.get(\"class\") == \"link-text\":\n self.capture_link = True\n\n def handle_endtag(self, tag):\n if tag == \"a\" and self.capture_title:\n self.capture_title = False\n elif tag == \"td\" and self.capture_description:\n self.capture_description = False\n elif tag == \"span\" and self.capture_link:\n self.capture_link = False\n elif tag == \"tr\":\n # Store current result if all parts are present\n if {\"title\", \"description\", \"link\"} <= self.current.keys():\n self.current[\"description\"] = \" \".join(self.current[\"description\"])\n self.results.append(self.current)\n self.current = {}\n\n def handle_data(self, data):\n if self.capture_title:\n self.current[\"title\"] = data.strip()\n elif self.capture_description:\n self.current.setdefault(\"description\", [])\n self.current[\"description\"].append(data.strip())\n elif self.capture_link:\n self.current[\"link\"] = \"https://\" + data.strip()\n\n return SimpleResultParser()\n\n def search_bing(self, query: str) -> list:\n import xml.etree.ElementTree as ET\n\n import requests\n\n response = requests.get(\n \"https://www.bing.com/search\",\n params={\"q\": query, \"format\": \"rss\"},\n )\n response.raise_for_status()\n root = ET.fromstring(response.text)\n items = root.findall(\".//item\")\n results = [\n {\n \"title\": item.findtext(\"title\"),\n \"link\": item.findtext(\"link\"),\n \"description\": item.findtext(\"description\"),\n }\n for item in items[: self.max_results]\n ]\n return results\n\n\nclass VisitWebpageTool(Tool):\n name = \"visit_webpage\"\n description = (\n \"Visits a webpage at the given url and reads its content as a markdown string. Use this to browse webpages.\"\n )\n inputs = {\n \"url\": {\n \"type\": \"string\",\n \"description\": \"The url of the webpage to visit.\",\n }\n }\n output_type = \"string\"\n\n def __init__(self, max_output_length: int = 40000):\n super().__init__()\n self.max_output_length = max_output_length\n\n def _truncate_content(self, content: str, max_length: int) -> str:\n if len(content) <= max_length:\n return content\n return (\n content[:max_length] + f\"\\n..._This content has been truncated to stay below {max_length} characters_...\\n\"\n )\n\n def forward(self, url: str) -> str:\n try:\n import re\n\n import requests\n from markdownify import markdownify\n from requests.exceptions import RequestException\n except ImportError as e:\n raise ImportError(\n \"You must install packages `markdownify` and `requests` to run this tool: for instance run `pip install markdownify requests`.\"\n ) from e\n try:\n # Send a GET request to the URL with a 20-second timeout\n response = requests.get(url, timeout=20)\n response.raise_for_status() # Raise an exception for bad status codes\n\n # Convert the HTML content to Markdown\n markdown_content = markdownify(response.text).strip()\n\n # Remove multiple line breaks\n markdown_content = re.sub(r\"\\n{3,}\", \"\\n\\n\", markdown_content)\n\n return self._truncate_content(markdown_content, self.max_output_length)\n\n except requests.exceptions.Timeout:\n return \"The request timed out. Please try again later or check the URL.\"\n except RequestException as e:\n return f\"Error fetching the webpage: {str(e)}\"\n except Exception as e:\n return f\"An unexpected error occurred: {str(e)}\"\n\n\nclass WikipediaSearchTool(Tool):\n \"\"\"\n Search Wikipedia and return the summary or full text of the requested article, along with the page URL.\n\n Attributes:\n user_agent (`str`): Custom user-agent string to identify the project. This is required as per Wikipedia API policies.\n See: https://foundation.wikimedia.org/wiki/Policy:Wikimedia_Foundation_User-Agent_Policy\n language (`str`, default `\"en\"`): Language in which to retrieve Wikipedia article.\n See: http://meta.wikimedia.org/wiki/List_of_Wikipedias\n content_type (`Literal[\"summary\", \"text\"]`, default `\"text\"`): Type of content to fetch. Can be \"summary\" for a short summary or \"text\" for the full article.\n extract_format (`Literal[\"HTML\", \"WIKI\"]`, default `\"WIKI\"`): Extraction format of the output. Can be `\"WIKI\"` or `\"HTML\"`.\n\n Example:\n ```python\n >>> from smolagents import CodeAgent, InferenceClientModel, WikipediaSearchTool\n >>> agent = CodeAgent(\n >>> tools=[\n >>> WikipediaSearchTool(\n >>> user_agent=\"MyResearchBot (myemail@example.com)\",\n >>> language=\"en\",\n >>> content_type=\"summary\", # or \"text\"\n >>> extract_format=\"WIKI\",\n >>> )\n >>> ],\n >>> model=InferenceClientModel(),\n >>> )\n >>> agent.run(\"Python_(programming_language)\")\n ```\n \"\"\"\n\n name = \"wikipedia_search\"\n description = \"Searches Wikipedia and returns a summary or full text of the given topic, along with the page URL.\"\n inputs = {\n \"query\": {\n \"type\": \"string\",\n \"description\": \"The topic to search on Wikipedia.\",\n }\n }\n output_type = \"string\"\n\n def __init__(\n self,\n user_agent: str = \"Smolagents (myemail@example.com)\",\n language: str = \"en\",\n content_type: str = \"text\",\n extract_format: str = \"WIKI\",\n ):\n super().__init__()\n try:\n import wikipediaapi\n except ImportError as e:\n raise ImportError(\n \"You must install `wikipedia-api` to run this tool: for instance run `pip install wikipedia-api`\"\n ) from e\n if not user_agent:\n raise ValueError(\"User-agent is required. Provide a meaningful identifier for your project.\")\n\n self.user_agent = user_agent\n self.language = language\n self.content_type = content_type\n\n # Map string format to wikipediaapi.ExtractFormat\n extract_format_map = {\n \"WIKI\": wikipediaapi.ExtractFormat.WIKI,\n \"HTML\": wikipediaapi.ExtractFormat.HTML,\n }\n\n if extract_format not in extract_format_map:\n raise ValueError(\"Invalid extract_format. Choose between 'WIKI' or 'HTML'.\")\n\n self.extract_format = extract_format_map[extract_format]\n\n self.wiki = wikipediaapi.Wikipedia(\n user_agent=self.user_agent, language=self.language, extract_format=self.extract_format\n )\n\n def forward(self, query: str) -> str:\n try:\n page = self.wiki.page(query)\n\n if not page.exists():\n return f\"No Wikipedia page found for '{query}'. Try a different query.\"\n\n title = page.title\n url = page.fullurl\n\n if self.content_type == \"summary\":\n text = page.summary\n elif self.content_type == \"text\":\n text = page.text\n else:\n return \"⚠️ Invalid `content_type`. Use either 'summary' or 'text'.\"\n\n return f\"✅ **Wikipedia Page:** {title}\\n\\n**Content:** {text}\\n\\n🔗 **Read more:** {url}\"\n\n except Exception as e:\n return f\"Error fetching Wikipedia summary: {str(e)}\"\n\n\nclass SpeechToTextTool(PipelineTool):\n default_checkpoint = \"openai/whisper-large-v3-turbo\"\n description = \"This is a tool that transcribes an audio into text. It returns the transcribed text.\"\n name = \"transcriber\"\n inputs = {\n \"audio\": {\n \"type\": \"audio\",\n \"description\": \"The audio to transcribe. Can be a local path, an url, or a tensor.\",\n }\n }\n output_type = \"string\"\n\n def __new__(cls, *args, **kwargs):\n from transformers.models.whisper import WhisperForConditionalGeneration, WhisperProcessor\n\n cls.pre_processor_class = WhisperProcessor\n cls.model_class = WhisperForConditionalGeneration\n return super().__new__(cls)\n\n def encode(self, audio):\n from .agent_types import AgentAudio\n\n audio = AgentAudio(audio).to_raw()\n return self.pre_processor(audio, return_tensors=\"pt\")\n\n def forward(self, inputs):\n return self.model.generate(inputs[\"input_features\"])\n\n def decode(self, outputs):\n return self.pre_processor.batch_decode(outputs, skip_special_tokens=True)[0]\n\n\nTOOL_MAPPING = {\n tool_class.name: tool_class\n for tool_class in [\n PythonInterpreterTool,\n DuckDuckGoSearchTool,\n VisitWebpageTool,\n ]\n}\n\n__all__ = [\n \"ApiWebSearchTool\",\n \"PythonInterpreterTool\",\n \"FinalAnswerTool\",\n \"UserInputTool\",\n \"WebSearchTool\",\n \"DuckDuckGoSearchTool\",\n \"GoogleSearchTool\",\n \"VisitWebpageTool\",\n \"WikipediaSearchTool\",\n \"SpeechToTextTool\",\n]\n"
},
{
"path": "src/smolagents/gradio_ui.py",
"content": "#!/usr/bin/env python\n# coding=utf-8\n# Copyright 2024 The HuggingFace Inc. team. All rights reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nimport os\nimport re\nimport shutil\nfrom pathlib import Path\nfrom typing import Generator\n\nfrom smolagents.agent_types import AgentAudio, AgentImage, AgentText\nfrom smolagents.agents import MultiStepAgent, PlanningStep\nfrom smolagents.memory import ActionStep, FinalAnswerStep\nfrom smolagents.models import ChatMessageStreamDelta, MessageRole, agglomerate_stream_deltas\nfrom smolagents.utils import _is_package_available\n\n\ndef get_step_footnote_content(step_log: ActionStep | PlanningStep, step_name: str) -> str:\n \"\"\"Get a footnote string for a step log with duration and token information\"\"\"\n step_footnote = f\"**{step_name}**\"\n if step_log.token_usage is not None:\n step_footnote += f\" | Input tokens: {step_log.token_usage.input_tokens:,} | Output tokens: {step_log.token_usage.output_tokens:,}\"\n step_footnote += f\" | Duration: {round(float(step_log.timing.duration), 2)}s\" if step_log.timing.duration else \"\"\n step_footnote_content = f\"\"\"{step_footnote} \"\"\"\n return step_footnote_content\n\n\ndef _clean_model_output(model_output: str) -> str:\n \"\"\"\n Clean up model output by removing trailing tags and extra backticks.\n\n Args:\n model_output (`str`): Raw model output.\n\n Returns:\n `str`: Cleaned model output.\n \"\"\"\n if not model_output:\n return \"\"\n model_output = model_output.strip()\n # Remove any trailing \ngo_to('github.com/trending')\n\n\nYou can directly click clickable elements by inputting the text that appears on them.\n\nclick(\"Top products\")\n\n\nIf it's a link:\n\nclick(Link(\"Top products\"))\n\n\nIf you try to interact with an element and it's not found, you'll get a LookupError.\nIn general stop your action after each button click to see what happens on your screenshot.\nNever try to login in a page.\n\nTo scroll up or down, use scroll_down or scroll_up with as an argument the number of pixels to scroll from.\n\nscroll_down(num_pixels=1200) # This will scroll one viewport down\n\n\nWhen you have pop-ups with a cross icon to close, don't try to click the close icon by finding its element or targeting an 'X' element (this most often fails).\nJust use your built-in tool `close_popups` to close them:\n\nclose_popups()\n\n\nYou can use .exists() to check for the existence of an element. For example:\n\nif Text('Accept cookies?').exists():\n click('I accept')\n\n\nProceed in several steps rather than trying to solve the task in one shot.\nAnd at the end, only when you have your answer, return your final answer.\n\nfinal_answer(\"YOUR_ANSWER_HERE\")\n\n\nIf pages seem stuck on loading, you might have to wait, for instance `import time` and run `time.sleep(5.0)`. But don't overuse this!\nTo list elements on page, DO NOT try code-based element searches like 'contributors = find_all(S(\"ol > li\"))': just look at the latest screenshot you have and read it visually, or use your tool search_item_ctrl_f.\nOf course, you can act on buttons like a user would do when navigating.\nAfter each code blob you write, you will be automatically provided with an updated screenshot of the browser and the current browser url.\nBut beware that the screenshot will only be taken at the end of the whole action, it won't see intermediate states.\nDon't kill the browser.\nWhen you have modals or cookie banners on screen, you should get rid of them before you can click anything else.\n\"\"\"\n\n\ndef run_webagent(\n prompt: str,\n model_type: str,\n model_id: str,\n provider: str | None = None,\n api_base: str | None = None,\n api_key: str | None = None,\n) -> None:\n # Load environment variables\n load_dotenv()\n\n # Initialize the model based on the provided arguments\n model = load_model(model_type, model_id, provider=provider, api_base=api_base, api_key=api_key)\n\n global driver\n driver = initialize_driver()\n agent = initialize_agent(model)\n\n # Run the agent with the provided prompt\n agent.python_executor(\"from helium import *\")\n agent.run(prompt + helium_instructions)\n\n\ndef main() -> None:\n # Parse command line arguments\n args = parse_arguments()\n run_webagent(args.prompt, args.model_type, args.model_id, args.provider, args.api_base, args.api_key)\n\n\nif __name__ == \"__main__\":\n main()\n"
},
{
"path": "tests/__init__.py",
"content": ""
},
{
"path": "tests/conftest.py",
"content": "from unittest.mock import patch\n\nimport pytest\n\nfrom smolagents.agents import MultiStepAgent\nfrom smolagents.monitoring import LogLevel\n\n\n# Import fixture modules as plugins\npytest_plugins = [\"tests.fixtures.agents\", \"tests.fixtures.tools\"]\n\noriginal_multi_step_agent_init = MultiStepAgent.__init__\n\n\n@pytest.fixture(autouse=True)\ndef patch_multi_step_agent_with_suppressed_logging():\n with patch.object(MultiStepAgent, \"__init__\", autospec=True) as mock_init:\n\n def init_with_suppressed_logging(self, *args, verbosity_level=LogLevel.OFF, **kwargs):\n original_multi_step_agent_init(self, *args, verbosity_level=verbosity_level, **kwargs)\n\n mock_init.side_effect = init_with_suppressed_logging\n yield\n"
},
{
"path": "tests/fixtures/agents.py",
"content": "import pytest\n\n\nAGENT_DICTS = {\n \"v1.9\": {\n \"tools\": [],\n \"model\": {\n \"class\": \"InferenceClientModel\",\n \"data\": {\n \"last_input_token_count\": None,\n \"last_output_token_count\": None,\n \"model_id\": \"Qwen/Qwen2.5-Coder-32B-Instruct\",\n \"provider\": None,\n },\n },\n \"managed_agents\": {},\n \"prompt_templates\": {\n \"system_prompt\": \"dummy system prompt\",\n \"planning\": {\n \"initial_facts\": \"dummy planning initial facts\",\n \"initial_plan\": \"dummy planning initial plan\",\n \"update_facts_pre_messages\": \"dummy planning update facts pre messages\",\n \"update_facts_post_messages\": \"dummy planning update facts post messages\",\n \"update_plan_pre_messages\": \"dummy planning update plan pre messages\",\n \"update_plan_post_messages\": \"dummy planning update plan post messages\",\n },\n \"managed_agent\": {\n \"task\": \"dummy managed agent task\",\n \"report\": \"dummy managed agent report\",\n },\n \"final_answer\": {\n \"pre_messages\": \"dummy final answer pre messages\",\n \"post_messages\": \"dummy final answer post messages\",\n },\n },\n \"max_steps\": 10,\n \"verbosity_level\": 2,\n \"grammar\": None,\n \"planning_interval\": 2,\n \"name\": \"test_agent\",\n \"description\": \"dummy description\",\n \"requirements\": [\"smolagents\"],\n \"authorized_imports\": [\"pandas\"],\n },\n # Added: executor_type, executor_kwargs, max_print_outputs_length\n \"v1.10\": {\n \"tools\": [],\n \"model\": {\n \"class\": \"InferenceClientModel\",\n \"data\": {\n \"last_input_token_count\": None,\n \"last_output_token_count\": None,\n \"model_id\": \"Qwen/Qwen2.5-Coder-32B-Instruct\",\n \"provider\": None,\n },\n },\n \"managed_agents\": {},\n \"prompt_templates\": {\n \"system_prompt\": \"dummy system prompt\",\n \"planning\": {\n \"initial_facts\": \"dummy planning initial facts\",\n \"initial_plan\": \"dummy planning initial plan\",\n \"update_facts_pre_messages\": \"dummy planning update facts pre messages\",\n \"update_facts_post_messages\": \"dummy planning update facts post messages\",\n \"update_plan_pre_messages\": \"dummy planning update plan pre messages\",\n \"update_plan_post_messages\": \"dummy planning update plan post messages\",\n },\n \"managed_agent\": {\n \"task\": \"dummy managed agent task\",\n \"report\": \"dummy managed agent report\",\n },\n \"final_answer\": {\n \"pre_messages\": \"dummy final answer pre messages\",\n \"post_messages\": \"dummy final answer post messages\",\n },\n },\n \"max_steps\": 10,\n \"verbosity_level\": 2,\n \"grammar\": None,\n \"planning_interval\": 2,\n \"name\": \"test_agent\",\n \"description\": \"dummy description\",\n \"requirements\": [\"smolagents\"],\n \"authorized_imports\": [\"pandas\"],\n \"executor_type\": \"local\",\n \"executor_kwargs\": {},\n \"max_print_outputs_length\": None,\n },\n # Removed: grammar, last_input_token_count, last_output_token_count\n \"v1.20\": {\n \"tools\": [],\n \"model\": {\n \"class\": \"InferenceClientModel\",\n \"data\": {\n \"model_id\": \"Qwen/Qwen2.5-Coder-32B-Instruct\",\n \"provider\": None,\n },\n },\n \"managed_agents\": {},\n \"prompt_templates\": {\n \"system_prompt\": \"dummy system prompt\",\n \"planning\": {\n \"initial_facts\": \"dummy planning initial facts\",\n \"initial_plan\": \"dummy planning initial plan\",\n \"update_facts_pre_messages\": \"dummy planning update facts pre messages\",\n \"update_facts_post_messages\": \"dummy planning update facts post messages\",\n \"update_plan_pre_messages\": \"dummy planning update plan pre messages\",\n \"update_plan_post_messages\": \"dummy planning update plan post messages\",\n },\n \"managed_agent\": {\n \"task\": \"dummy managed agent task\",\n \"report\": \"dummy managed agent report\",\n },\n \"final_answer\": {\n \"pre_messages\": \"dummy final answer pre messages\",\n \"post_messages\": \"dummy final answer post messages\",\n },\n },\n \"max_steps\": 10,\n \"verbosity_level\": 2,\n \"planning_interval\": 2,\n \"name\": \"test_agent\",\n \"description\": \"dummy description\",\n \"requirements\": [\"smolagents\"],\n \"authorized_imports\": [\"pandas\"],\n \"executor_type\": \"local\",\n \"executor_kwargs\": {},\n \"max_print_outputs_length\": None,\n },\n}\n\n\n@pytest.fixture\ndef get_agent_dict():\n def _get_agent_dict(agent_dict_key):\n return AGENT_DICTS[agent_dict_key]\n\n return _get_agent_dict\n"
},
{
"path": "tests/fixtures/tools.py",
"content": "import pytest\n\nfrom smolagents.tools import Tool, tool\n\n\n@pytest.fixture\ndef test_tool():\n class TestTool(Tool):\n name = \"test_tool\"\n description = \"A test tool\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"Input value\"}}\n output_type = \"string\"\n\n def forward(self, input):\n if input == \"error\":\n raise ValueError(\"Tool execution error\")\n return f\"Processed: {input}\"\n\n return TestTool()\n\n\n@pytest.fixture\ndef no_input_tool():\n class NoInputTool(Tool):\n name = \"no_input_tool\"\n description = \"Tool with no inputs\"\n inputs = {}\n output_type = \"string\"\n\n def forward(self):\n return \"test\"\n\n return NoInputTool()\n\n\n@pytest.fixture\ndef single_input_tool():\n class SingleInputTool(Tool):\n name = \"single_input_tool\"\n description = \"Tool with one input\"\n inputs = {\"text\": {\"type\": \"string\", \"description\": \"Input text\"}}\n output_type = \"string\"\n\n def forward(self, text):\n return \"test\"\n\n return SingleInputTool()\n\n\n@pytest.fixture\ndef multi_input_tool():\n class MultiInputTool(Tool):\n name = \"multi_input_tool\"\n description = \"Tool with multiple inputs\"\n inputs = {\n \"text\": {\"type\": \"string\", \"description\": \"Text input\"},\n \"count\": {\"type\": \"integer\", \"description\": \"Number count\"},\n }\n output_type = \"object\"\n\n def forward(self, text, count):\n return \"test\"\n\n return MultiInputTool()\n\n\n@pytest.fixture\ndef multiline_description_tool():\n class MultilineDescriptionTool(Tool):\n name = \"multiline_description_tool\"\n description = \"This is a tool with\\nmultiple lines\\nin the description\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"Some input\"}}\n output_type = \"string\"\n\n def forward(self, input):\n return \"test\"\n\n return MultilineDescriptionTool()\n\n\n@pytest.fixture\ndef example_tool():\n @tool\n def valid_tool_function(input: str) -> str:\n \"\"\"A valid tool function.\n\n Args:\n input (str): Input string.\n \"\"\"\n return input.upper()\n\n return valid_tool_function\n\n\n@pytest.fixture\ndef boolean_default_tool_class():\n class BooleanDefaultTool(Tool):\n name = \"boolean_default_tool\"\n description = \"A tool with a boolean default parameter\"\n inputs = {\n \"text\": {\"type\": \"string\", \"description\": \"Input text\"},\n \"flag\": {\"type\": \"boolean\", \"description\": \"Boolean flag with default value\", \"nullable\": True},\n }\n output_type = \"string\"\n\n def forward(self, text: str, flag: bool = False) -> str:\n return f\"Text: {text}, Flag: {flag}\"\n\n return BooleanDefaultTool()\n\n\n@pytest.fixture\ndef boolean_default_tool_function():\n @tool\n def boolean_default_tool(text: str, flag: bool = False) -> str:\n \"\"\"\n A tool with a boolean default parameter.\n\n Args:\n text: Input text\n flag: Boolean flag with default value\n \"\"\"\n return f\"Text: {text}, Flag: {flag}\"\n\n return boolean_default_tool\n\n\n@pytest.fixture\ndef optional_input_tool_class():\n class OptionalInputTool(Tool):\n name = \"optional_input_tool\"\n description = \"A tool with an optional input parameter\"\n inputs = {\n \"required_text\": {\"type\": \"string\", \"description\": \"Required input text\"},\n \"optional_text\": {\"type\": \"string\", \"description\": \"Optional input text\", \"nullable\": True},\n }\n output_type = \"string\"\n\n def forward(self, required_text: str, optional_text: str | None = None) -> str:\n if optional_text:\n return f\"{required_text} + {optional_text}\"\n return required_text\n\n return OptionalInputTool()\n\n\n@pytest.fixture\ndef optional_input_tool_function():\n @tool\n def optional_input_tool(required_text: str, optional_text: str | None = None) -> str:\n \"\"\"\n A tool with an optional input parameter.\n\n Args:\n required_text: Required input text\n optional_text: Optional input text\n \"\"\"\n if optional_text:\n return f\"{required_text} + {optional_text}\"\n return required_text\n\n return optional_input_tool\n"
},
{
"path": "tests/test_agents.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nimport io\nimport json\nimport os\nimport re\nimport tempfile\nimport uuid\nfrom collections.abc import Generator\nfrom contextlib import nullcontext as does_not_raise\nfrom dataclasses import dataclass\nfrom pathlib import Path\nfrom textwrap import dedent\nfrom typing import Optional\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\nfrom huggingface_hub import (\n ChatCompletionOutputFunctionDefinition,\n ChatCompletionOutputMessage,\n ChatCompletionOutputToolCall,\n)\nfrom rich.console import Console\n\nfrom smolagents import EMPTY_PROMPT_TEMPLATES\nfrom smolagents.agent_types import AgentImage, AgentText\nfrom smolagents.agents import (\n AgentError,\n AgentMaxStepsError,\n AgentToolCallError,\n CodeAgent,\n MultiStepAgent,\n RunResult,\n ToolCall,\n ToolCallingAgent,\n ToolOutput,\n populate_template,\n)\nfrom smolagents.default_tools import DuckDuckGoSearchTool, FinalAnswerTool, PythonInterpreterTool, VisitWebpageTool\nfrom smolagents.memory import (\n ActionStep,\n CallbackRegistry,\n FinalAnswerStep,\n MemoryStep,\n PlanningStep,\n SystemPromptStep,\n TaskStep,\n)\nfrom smolagents.models import (\n ChatMessage,\n ChatMessageToolCall,\n ChatMessageToolCallFunction,\n InferenceClientModel,\n MessageRole,\n Model,\n TransformersModel,\n)\nfrom smolagents.monitoring import AgentLogger, LogLevel, Timing, TokenUsage\nfrom smolagents.tools import Tool, tool\nfrom smolagents.utils import (\n BASE_BUILTIN_MODULES,\n AgentExecutionError,\n AgentGenerationError,\n AgentToolExecutionError,\n)\n\n\n@dataclass\nclass ChoiceDeltaToolCallFunction:\n arguments: Optional[str] = None\n name: Optional[str] = None\n\n\n@dataclass\nclass ChoiceDeltaToolCall:\n index: Optional[int] = None\n id: Optional[str] = None\n function: Optional[ChoiceDeltaToolCallFunction] = None\n type: Optional[str] = None\n\n\n@dataclass\nclass ChoiceDelta:\n content: Optional[str] = None\n function_call: Optional[str] = None\n refusal: Optional[str] = None\n role: Optional[str] = None\n tool_calls: Optional[list] = None\n\n\ndef get_new_path(suffix=\"\") -> str:\n directory = tempfile.mkdtemp()\n return os.path.join(directory, str(uuid.uuid4()) + suffix)\n\n\n@pytest.fixture\ndef agent_logger():\n return AgentLogger(\n LogLevel.DEBUG, console=Console(record=True, no_color=True, force_terminal=False, file=io.StringIO())\n )\n\n\nclass FakeToolCallModel(Model):\n def generate(self, messages, tools_to_call_from=None, stop_sequences=None):\n if len(messages) < 3:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"I will call the python interpreter.\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"python_interpreter\", arguments={\"code\": \"2*3.6452\"}\n ),\n )\n ],\n )\n else:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"I will return the final answer.\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"final_answer\", arguments={\"answer\": \"7.2904\"}),\n )\n ],\n )\n\n\nclass FakeToolCallModelImage(Model):\n def generate(self, messages, tools_to_call_from=None, stop_sequences=None):\n if len(messages) < 3:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"fake_image_generation_tool\",\n arguments={\"prompt\": \"An image of a cat\"},\n ),\n )\n ],\n )\n else:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"final_answer\", arguments=\"image.png\"),\n )\n ],\n )\n\n\nclass FakeToolCallModelVL(Model):\n def generate(self, messages, tools_to_call_from=None, stop_sequences=None):\n if len(messages) < 3:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"fake_image_understanding_tool\",\n arguments={\n \"prompt\": \"What is in this image?\",\n \"image\": \"image.png\",\n },\n ),\n )\n ],\n )\n else:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"final_answer\", arguments=\"The image is a cat.\"),\n )\n ],\n )\n\n\nclass FakeCodeModel(Model):\n def generate(self, messages, stop_sequences=None):\n prompt = str(messages)\n if \"special_marker\" not in prompt:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I should multiply 2 by 3.6452. special_marker\n\nresult = 2**3.6452\n\n\"\"\",\n )\n else: # We're at step 2\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I can now answer the initial question\n\nfinal_answer(7.2904)\n\n\"\"\",\n )\n\n\nclass FakeCodeModelImageGeneration(Model):\n def generate(self, messages, stop_sequences=None):\n prompt = str(messages)\n if \"special_marker\" not in prompt:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I should generate an image. special_marker\n\nimage = image_generation_tool()\n\n\"\"\",\n )\n else: # We're at step 2\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I can now answer the initial question\n\nfinal_answer(image)\n\n\"\"\",\n )\n\n\nclass FakeCodeModelPlanning(Model):\n def generate(self, messages, stop_sequences=None):\n prompt = str(messages)\n if \"planning_marker\" not in prompt:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"llm plan update planning_marker\",\n token_usage=TokenUsage(input_tokens=10, output_tokens=10),\n )\n elif \"action_marker\" not in prompt:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I should multiply 2 by 3.6452. action_marker\n\nresult = 2**3.6452\n\n\"\"\",\n token_usage=TokenUsage(input_tokens=10, output_tokens=10),\n )\n else:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"llm plan again\",\n token_usage=TokenUsage(input_tokens=10, output_tokens=10),\n )\n\n\nclass FakeCodeModelError(Model):\n def generate(self, messages, stop_sequences=None):\n prompt = str(messages)\n if \"special_marker\" not in prompt:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I should multiply 2 by 3.6452. special_marker\n\nprint(\"Flag!\")\ndef error_function():\n raise ValueError(\"error\")\n\nerror_function()\n\n\"\"\",\n )\n else: # We're at step 2\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I faced an error in the previous step.\n\nfinal_answer(\"got an error\")\n\n\"\"\",\n )\n\n\nclass FakeCodeModelSyntaxError(Model):\n def generate(self, messages, stop_sequences=None):\n prompt = str(messages)\n if \"special_marker\" not in prompt:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I should multiply 2 by 3.6452. special_marker\n\na = 2\nb = a * 2\n print(\"Failing due to unexpected indent\")\nprint(\"Ok, calculation done!\")\n\n\"\"\",\n )\n else: # We're at step 2\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I can now answer the initial question\n\nfinal_answer(\"got an error\")\n\n\"\"\",\n )\n\n\nclass FakeCodeModelImport(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I can answer the question\n\nimport numpy as np\nfinal_answer(\"got an error\")\n\n\"\"\",\n )\n\n\nclass FakeCodeModelFunctionDef(Model):\n def generate(self, messages, stop_sequences=None):\n prompt = str(messages)\n if \"special_marker\" not in prompt:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: Let's define the function. special_marker\n\nimport numpy as np\n\ndef moving_average(x, w):\n return np.convolve(x, np.ones(w), 'valid') / w\n\n \"\"\",\n )\n else: # We're at step 2\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I can now answer the initial question\n\nx, w = [0, 1, 2, 3, 4, 5], 2\nres = moving_average(x, w)\nfinal_answer(res)\n\n\"\"\",\n )\n\n\nclass FakeCodeModelSingleStep(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I should multiply 2 by 3.6452. special_marker\n\nresult = python_interpreter(code=\"2*3.6452\")\nfinal_answer(result)\n```\n\"\"\",\n )\n\n\nclass FakeCodeModelNoReturn(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: I should multiply 2 by 3.6452. special_marker\n\nresult = python_interpreter(code=\"2*3.6452\")\nprint(result)\n```\n\"\"\",\n )\n\n\nclass TestAgent:\n def test_fake_toolcalling_agent(self):\n agent = ToolCallingAgent(tools=[PythonInterpreterTool()], model=FakeToolCallModel())\n output = agent.run(\"What is 2 multiplied by 3.6452?\")\n assert isinstance(output, str)\n assert \"7.2904\" in output\n assert agent.memory.steps[0].task == \"What is 2 multiplied by 3.6452?\"\n assert \"7.2904\" in agent.memory.steps[1].observations\n assert agent.memory.steps[2].model_output == \"I will return the final answer.\"\n\n def test_toolcalling_agent_handles_image_tool_outputs(self, shared_datadir):\n import PIL.Image\n\n @tool\n def fake_image_generation_tool(prompt: str) -> PIL.Image.Image:\n \"\"\"Tool that generates an image.\n\n Args:\n prompt: The prompt\n \"\"\"\n\n import PIL.Image\n\n return PIL.Image.open(shared_datadir / \"000000039769.png\")\n\n agent = ToolCallingAgent(tools=[fake_image_generation_tool], model=FakeToolCallModelImage())\n output = agent.run(\"Make me an image.\")\n assert isinstance(output, AgentImage)\n assert isinstance(agent.state[\"image.png\"], PIL.Image.Image)\n\n def test_toolcalling_agent_handles_image_inputs(self, shared_datadir):\n import PIL.Image\n\n image = PIL.Image.open(shared_datadir / \"000000039769.png\") # dummy input\n\n @tool\n def fake_image_understanding_tool(prompt: str, image: PIL.Image.Image) -> str:\n \"\"\"Tool that creates a caption for an image.\n\n Args:\n prompt: The prompt\n image: The image\n \"\"\"\n return \"The image is a cat.\"\n\n agent = ToolCallingAgent(tools=[fake_image_understanding_tool], model=FakeToolCallModelVL())\n output = agent.run(\"Caption this image.\", images=[image])\n assert output == \"The image is a cat.\"\n\n def test_fake_code_agent(self):\n agent = CodeAgent(tools=[PythonInterpreterTool()], model=FakeCodeModel(), verbosity_level=10)\n output = agent.run(\"What is 2 multiplied by 3.6452?\")\n assert isinstance(output, float)\n assert output == 7.2904\n assert agent.memory.steps[0].task == \"What is 2 multiplied by 3.6452?\"\n assert agent.memory.steps[2].tool_calls == [\n ToolCall(name=\"python_interpreter\", arguments=\"final_answer(7.2904)\", id=\"call_2\")\n ]\n\n def test_additional_args_added_to_task(self):\n agent = CodeAgent(tools=[], model=FakeCodeModel())\n agent.run(\n \"What is 2 multiplied by 3.6452?\",\n additional_args={\"instruction\": \"Remember this.\"},\n )\n assert \"Remember this\" in agent.task\n\n def test_reset_conversations(self):\n agent = CodeAgent(tools=[PythonInterpreterTool()], model=FakeCodeModel())\n output = agent.run(\"What is 2 multiplied by 3.6452?\", reset=True)\n assert output == 7.2904\n assert len(agent.memory.steps) == 3\n\n output = agent.run(\"What is 2 multiplied by 3.6452?\", reset=False)\n assert output == 7.2904\n assert len(agent.memory.steps) == 5\n\n output = agent.run(\"What is 2 multiplied by 3.6452?\", reset=True)\n assert output == 7.2904\n assert len(agent.memory.steps) == 3\n\n def test_setup_agent_with_empty_toolbox(self):\n ToolCallingAgent(model=FakeToolCallModel(), tools=[])\n\n def test_fails_max_steps(self):\n agent = CodeAgent(\n tools=[PythonInterpreterTool()],\n model=FakeCodeModelNoReturn(), # use this callable because it never ends\n max_steps=5,\n )\n answer = agent.run(\"What is 2 multiplied by 3.6452?\")\n assert len(agent.memory.steps) == 7 # Task step + 5 action steps + Final answer\n assert type(agent.memory.steps[-1].error) is AgentMaxStepsError\n assert isinstance(answer, str)\n\n agent = CodeAgent(\n tools=[PythonInterpreterTool()],\n model=FakeCodeModelNoReturn(), # use this callable because it never ends\n max_steps=5,\n )\n answer = agent.run(\"What is 2 multiplied by 3.6452?\", max_steps=3)\n assert len(agent.memory.steps) == 5 # Task step + 3 action steps + Final answer\n assert type(agent.memory.steps[-1].error) is AgentMaxStepsError\n assert isinstance(answer, str)\n\n def test_tool_descriptions_get_baked_in_system_prompt(self):\n tool = PythonInterpreterTool()\n tool.name = \"fake_tool_name\"\n tool.description = \"fake_tool_description\"\n agent = CodeAgent(tools=[tool], model=FakeCodeModel())\n agent.run(\"Empty task\")\n assert agent.system_prompt is not None\n assert f\"def {tool.name}(\" in agent.system_prompt\n assert f'\"\"\"{tool.description}' in agent.system_prompt\n\n def test_module_imports_get_baked_in_system_prompt(self):\n agent = CodeAgent(tools=[], model=FakeCodeModel())\n agent.run(\"Empty task\")\n for module in BASE_BUILTIN_MODULES:\n assert module in agent.system_prompt\n\n def test_init_agent_with_different_toolsets(self):\n toolset_1 = []\n agent = CodeAgent(tools=toolset_1, model=FakeCodeModel())\n assert len(agent.tools) == 1 # when no tools are provided, only the final_answer tool is added by default\n\n toolset_2 = [PythonInterpreterTool(), PythonInterpreterTool()]\n with pytest.raises(ValueError) as e:\n agent = CodeAgent(tools=toolset_2, model=FakeCodeModel())\n assert \"Each tool or managed_agent should have a unique name!\" in str(e)\n\n with pytest.raises(ValueError) as e:\n agent.name = \"python_interpreter\"\n agent.description = \"empty\"\n CodeAgent(tools=[PythonInterpreterTool()], model=FakeCodeModel(), managed_agents=[agent])\n assert \"Each tool or managed_agent should have a unique name!\" in str(e)\n\n # check that python_interpreter base tool does not get added to CodeAgent\n agent = CodeAgent(tools=[], model=FakeCodeModel(), add_base_tools=True)\n assert len(agent.tools) == 3 # added final_answer tool + search + visit_webpage\n\n # check that python_interpreter base tool gets added to ToolCallingAgent\n agent = ToolCallingAgent(tools=[], model=FakeCodeModel(), add_base_tools=True)\n assert len(agent.tools) == 4 # added final_answer tool + search + visit_webpage\n\n def test_function_persistence_across_steps(self):\n agent = CodeAgent(\n tools=[],\n model=FakeCodeModelFunctionDef(),\n max_steps=2,\n additional_authorized_imports=[\"numpy\"],\n )\n res = agent.run(\"ok\")\n assert res[0] == 0.5\n\n def test_init_managed_agent(self):\n agent = CodeAgent(tools=[], model=FakeCodeModelFunctionDef(), name=\"managed_agent\", description=\"Empty\")\n assert agent.name == \"managed_agent\"\n assert agent.description == \"Empty\"\n\n def test_agent_description_gets_correctly_inserted_in_system_prompt(self):\n managed_agent = CodeAgent(\n tools=[], model=FakeCodeModelFunctionDef(), name=\"managed_agent\", description=\"Empty\"\n )\n manager_agent = CodeAgent(\n tools=[],\n model=FakeCodeModelFunctionDef(),\n managed_agents=[managed_agent],\n )\n assert \"You can also give tasks to team members.\" not in managed_agent.system_prompt\n assert \"{{managed_agents_descriptions}}\" not in managed_agent.system_prompt\n assert \"You can also give tasks to team members.\" in manager_agent.system_prompt\n\n def test_replay_shows_logs(self, agent_logger):\n agent = CodeAgent(\n tools=[],\n model=FakeCodeModelImport(),\n verbosity_level=0,\n additional_authorized_imports=[\"numpy\"],\n logger=agent_logger,\n )\n agent.run(\"Count to 3\")\n\n str_output = agent_logger.console.export_text()\n\n assert \"New run\" in str_output\n assert 'final_answer(\"got' in str_output\n assert \"\" in str_output\n\n agent = ToolCallingAgent(tools=[PythonInterpreterTool()], model=FakeToolCallModel(), verbosity_level=0)\n agent.logger = agent_logger\n\n agent.run(\"What is 2 multiplied by 3.6452?\")\n agent.replay()\n\n str_output = agent_logger.console.export_text()\n assert \"arguments\" in str_output\n\n def test_code_nontrivial_final_answer_works(self):\n class FakeCodeModelFinalAnswer(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\ndef nested_answer():\n final_answer(\"Correct!\")\n\nnested_answer()\n\"\"\",\n )\n\n agent = CodeAgent(tools=[], model=FakeCodeModelFinalAnswer())\n\n output = agent.run(\"Count to 3\")\n assert output == \"Correct!\"\n\n def test_transformers_toolcalling_agent(self):\n @tool\n def weather_api(location: str, celsius: str = \"\") -> str:\n \"\"\"\n Gets the weather in the next days at given location.\n Secretly this tool does not care about the location, it hates the weather everywhere.\n\n Args:\n location: the location\n celsius: the temperature type\n \"\"\"\n return \"The weather is UNGODLY with torrential rains and temperatures below -10°C\"\n\n model = TransformersModel(\n model_id=\"HuggingFaceTB/SmolLM2-360M-Instruct\",\n max_new_tokens=100,\n device_map=\"auto\",\n do_sample=False,\n )\n agent = ToolCallingAgent(model=model, tools=[weather_api], max_steps=1)\n task = \"What is the weather in Paris? \"\n agent.run(task)\n assert agent.memory.steps[0].task == task\n assert agent.memory.steps[1].tool_calls[0].name == \"weather_api\"\n step_memory_dict = agent.memory.get_succinct_steps()[1]\n assert step_memory_dict[\"model_output_message\"][\"tool_calls\"][0][\"function\"][\"name\"] == \"weather_api\"\n assert step_memory_dict[\"model_output_message\"][\"raw\"][\"completion_kwargs\"][\"max_new_tokens\"] == 100\n assert \"model_input_messages\" in agent.memory.get_full_steps()[1]\n assert step_memory_dict[\"token_usage\"][\"total_tokens\"] > 100\n assert step_memory_dict[\"timing\"][\"duration\"] > 0.1\n\n def test_final_answer_checks(self):\n error_string = \"failed with error\"\n\n def check_always_fails(final_answer, memory, agent):\n assert False, \"Error raised in check\"\n\n agent = CodeAgent(model=FakeCodeModel(), tools=[], final_answer_checks=[check_always_fails])\n agent.run(\"Dummy task.\")\n assert error_string in str(agent.write_memory_to_messages())\n assert \"Error raised in check\" in str(agent.write_memory_to_messages())\n\n agent = CodeAgent(\n model=FakeCodeModel(),\n tools=[],\n final_answer_checks=[lambda x, memory, agent: x == 7.2904],\n verbosity_level=1000,\n )\n output = agent.run(\"Dummy task.\")\n assert output == 7.2904 # Check that output is correct\n assert len([step for step in agent.memory.steps if isinstance(step, ActionStep)]) == 2\n assert error_string not in str(agent.write_memory_to_messages())\n\n def test_final_answer_checks_with_agent_access(self):\n \"\"\"Test that final answer checks can access agent properties.\"\"\"\n\n def check_uses_agent_properties(final_answer, memory, agent):\n # Access agent properties to validate the final answer\n assert hasattr(agent, \"memory\"), \"Agent should have memory attribute\"\n assert hasattr(agent, \"state\"), \"Agent should have state attribute\"\n assert hasattr(agent, \"task\"), \"Agent should have task attribute\"\n\n # Check that the final answer is related to the task\n if isinstance(final_answer, str):\n return len(final_answer) > 0\n return True\n\n def check_uses_agent_state(final_answer, memory, agent):\n # Use agent state to validate the answer\n if \"expected_answer\" in agent.state:\n return final_answer == agent.state[\"expected_answer\"]\n return True\n\n # Test with a check that uses agent properties\n agent = CodeAgent(model=FakeCodeModel(), tools=[], final_answer_checks=[check_uses_agent_properties])\n output = agent.run(\"Dummy task.\")\n assert output == 7.2904 # Should pass the check\n\n # Test with a check that uses agent state\n agent = CodeAgent(model=FakeCodeModel(), tools=[], final_answer_checks=[check_uses_agent_state])\n agent.state[\"expected_answer\"] = 7.2904\n output = agent.run(\"Dummy task.\")\n assert output == 7.2904 # Should pass the check\n\n # Test with a check that fails due to state mismatch\n agent = CodeAgent(\n model=FakeCodeModel(),\n tools=[],\n final_answer_checks=[check_uses_agent_state],\n max_steps=3, # Limit steps to avoid long test run\n )\n agent.state[\"expected_answer\"] = \"wrong answer\"\n output = agent.run(\"Dummy task.\")\n\n # The agent should have reached max steps and provided a final answer anyway\n assert output is not None\n # Check that there were failed validation attempts in the memory\n failed_steps = [step for step in agent.memory.steps if hasattr(step, \"error\") and step.error is not None]\n assert len(failed_steps) > 0, \"Expected some steps to have validation errors\"\n\n # Check that at least one error message contains our check function name\n error_messages = [str(step.error) for step in failed_steps if step.error is not None]\n assert any(\"check_uses_agent_state failed\" in msg for msg in error_messages), (\n \"Expected to find validation error message\"\n )\n\n def test_generation_errors_are_raised(self):\n class FakeCodeModel(Model):\n def generate(self, messages, stop_sequences=None):\n assert False, \"Generation failed\"\n\n agent = CodeAgent(model=FakeCodeModel(), tools=[])\n with pytest.raises(AgentGenerationError) as e:\n agent.run(\"Dummy task.\")\n assert len(agent.memory.steps) == 2\n assert \"Generation failed\" in str(e)\n\n def test_planning_step_with_injected_memory(self):\n \"\"\"Test that agent properly uses update plan prompts when memory is injected before a run.\n\n This test verifies:\n 1. Planning steps are created with the correct frequency\n 2. Injected memory is included in planning context\n 3. Messages are properly formatted with expected roles and content\n \"\"\"\n planning_interval = 1\n max_steps = 4\n task = \"Continuous task\"\n previous_task = \"Previous user request\"\n\n # Create agent with planning capability\n agent = CodeAgent(\n tools=[],\n planning_interval=planning_interval,\n model=FakeCodeModelPlanning(),\n max_steps=max_steps,\n )\n\n # Inject memory before run to simulate existing conversation history\n previous_step = TaskStep(task=previous_task)\n agent.memory.steps.append(previous_step)\n\n # Run the agent\n agent.run(task, reset=False)\n\n # Extract and validate planning steps\n planning_steps = [step for step in agent.memory.steps if isinstance(step, PlanningStep)]\n assert len(planning_steps) > 2, \"Expected multiple planning steps to be generated\"\n\n # Verify first planning step incorporates injected memory\n first_planning_step = planning_steps[0]\n input_messages = first_planning_step.model_input_messages\n\n # Check message structure and content\n assert len(input_messages) == 4, (\n \"First planning step should have 4 messages: system-plan-pre-update + memory + task + user-plan-post-update\"\n )\n\n # Verify system message contains current task\n system_message = input_messages[0]\n assert system_message.role == \"system\", \"First message should have system role\"\n assert task in system_message.content[0][\"text\"], f\"System message should contain the current task: '{task}'\"\n\n # Verify memory message contains previous task\n memory_message = input_messages[1]\n assert previous_task in memory_message.content[0][\"text\"], (\n f\"Memory message should contain previous task: '{previous_task}'\"\n )\n\n # Verify task message contains current task\n task_message = input_messages[2]\n assert task in task_message.content[0][\"text\"], f\"Task message should contain current task: '{task}'\"\n\n # Verify user message for planning\n user_message = input_messages[3]\n assert user_message.role == \"user\", \"Fourth message should have user role\"\n\n # Verify second planning step has more context from first agent actions\n second_planning_step = planning_steps[1]\n second_messages = second_planning_step.model_input_messages\n\n # Check that conversation history is growing appropriately\n assert len(second_messages) == 6, \"Second planning step should have 6 messages including tool interactions\"\n\n # Verify all conversation elements are present\n conversation_text = \"\".join([msg.content[0][\"text\"] for msg in second_messages if hasattr(msg, \"content\")])\n assert previous_task in conversation_text, \"Previous task should be included in the conversation history\"\n assert task in conversation_text, \"Current task should be included in the conversation history\"\n assert \"tools\" in conversation_text, \"Tool interactions should be included in the conversation history\"\n\n\nclass CustomFinalAnswerTool(FinalAnswerTool):\n def forward(self, answer) -> str:\n return answer + \"CUSTOM\"\n\n\nclass MockTool(Tool):\n def __init__(self, name):\n self.name = name\n self.description = \"Mock tool description\"\n self.inputs = {}\n self.output_type = \"string\"\n\n def forward(self):\n return \"Mock tool output\"\n\n\nclass MockAgent:\n def __init__(self, name, tools, description=\"Mock agent description\"):\n self.name = name\n self.tools = {t.name: t for t in tools}\n self.description = description\n\n\nclass DummyMultiStepAgent(MultiStepAgent):\n def step(self, memory_step: ActionStep) -> Generator[None]:\n yield None\n\n def initialize_system_prompt(self):\n pass\n\n\nclass FakeLLMModel(Model):\n def __init__(self, give_token_usage: bool = True):\n self.give_token_usage = give_token_usage\n\n def generate(self, prompt, tools_to_call_from=None, **kwargs):\n if tools_to_call_from is not None:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"I will call the final_answer tool.\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"fake_id\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"final_answer\", arguments={\"answer\": \"This is the final answer.\"}\n ),\n )\n ],\n token_usage=TokenUsage(input_tokens=10, output_tokens=20) if self.give_token_usage else None,\n )\n else:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nfinal_answer('This is the final answer.')\n\"\"\",\n token_usage=TokenUsage(input_tokens=10, output_tokens=20) if self.give_token_usage else None,\n )\n\n\nclass TestRunResult:\n def test_backward_compatibility(self):\n \"\"\"Test that RunResult handles deprecated 'messages' parameter correctly.\"\"\"\n\n # Test 1: Using new 'steps' parameter (should work without warning)\n result1 = RunResult(\n output=\"test output\",\n state=\"success\",\n steps=[{\"type\": \"test\", \"content\": \"step1\"}],\n token_usage=None,\n timing=Timing(start_time=0.0, end_time=1.0),\n )\n assert result1.steps == [{\"type\": \"test\", \"content\": \"step1\"}]\n\n # Test property access warning\n with pytest.warns(FutureWarning, match=\"deprecated\"):\n messages = result1.messages\n assert messages == [{\"type\": \"test\", \"content\": \"step1\"}]\n\n # Test 2: Using deprecated 'messages' parameter (should show deprecation warning)\n with pytest.warns(FutureWarning, match=\"deprecated\"):\n result2 = RunResult(\n output=\"test output\",\n state=\"success\",\n messages=[{\"type\": \"test\", \"content\": \"message1\"}],\n token_usage=None,\n timing=Timing(start_time=0.0, end_time=1.0),\n )\n assert result2.steps == [{\"type\": \"test\", \"content\": \"message1\"}]\n\n # Test 3: Using both 'steps' and 'messages' (should raise ValueError)\n with pytest.raises(ValueError, match=\"Cannot specify both\"):\n RunResult(\n output=\"test output\",\n state=\"success\",\n steps=[{\"type\": \"test\", \"content\": \"step1\"}],\n messages=[{\"type\": \"test\", \"content\": \"message1\"}],\n token_usage=None,\n timing=Timing(start_time=0.0, end_time=1.0),\n )\n\n @pytest.mark.parametrize(\"agent_class\", [CodeAgent, ToolCallingAgent])\n def test_no_token_usage(self, agent_class):\n agent = agent_class(\n tools=[],\n model=FakeLLMModel(give_token_usage=False),\n max_steps=1,\n return_full_result=True,\n )\n\n result = agent.run(\"Fake task\")\n\n assert isinstance(result, RunResult)\n assert result.output == \"This is the final answer.\"\n assert result.state == \"success\"\n assert result.token_usage is None\n assert isinstance(result.steps, list)\n assert result.timing.duration > 0\n\n @pytest.mark.parametrize(\n \"init_return_full_result,run_return_full_result,expect_runresult\",\n [\n (True, None, True),\n (False, None, False),\n (True, False, False),\n (False, True, True),\n ],\n )\n def test_full_result(self, init_return_full_result, run_return_full_result, expect_runresult):\n agent = ToolCallingAgent(\n tools=[],\n model=FakeLLMModel(),\n max_steps=1,\n return_full_result=init_return_full_result,\n )\n result = agent.run(\"Fake task\", return_full_result=run_return_full_result)\n\n if expect_runresult:\n assert isinstance(result, RunResult)\n assert result.output == \"This is the final answer.\"\n assert result.state == \"success\"\n assert result.token_usage == TokenUsage(input_tokens=10, output_tokens=20)\n assert isinstance(result.steps, list)\n assert result.timing.duration > 0\n else:\n assert isinstance(result, str)\n\n\nclass TestMultiStepAgent:\n def test_instantiation_disables_logging_to_terminal(self):\n fake_model = MagicMock()\n agent = DummyMultiStepAgent(tools=[], model=fake_model)\n assert agent.logger.level == -1, \"logging to terminal should be disabled for testing using a fixture\"\n\n def test_instantiation_with_prompt_templates(self, prompt_templates):\n agent = DummyMultiStepAgent(tools=[], model=MagicMock(), prompt_templates=prompt_templates)\n assert agent.prompt_templates == prompt_templates\n assert agent.prompt_templates[\"system_prompt\"] == \"This is a test system prompt.\"\n assert \"managed_agent\" in agent.prompt_templates\n assert agent.prompt_templates[\"managed_agent\"][\"task\"] == \"Task for {{name}}: {{task}}\"\n assert agent.prompt_templates[\"managed_agent\"][\"report\"] == \"Report for {{name}}: {{final_answer}}\"\n\n @pytest.mark.parametrize(\n \"tools, expected_final_answer_tool\",\n [([], FinalAnswerTool), ([CustomFinalAnswerTool()], CustomFinalAnswerTool)],\n )\n def test_instantiation_with_final_answer_tool(self, tools, expected_final_answer_tool):\n agent = DummyMultiStepAgent(tools=tools, model=MagicMock())\n assert \"final_answer\" in agent.tools\n assert isinstance(agent.tools[\"final_answer\"], expected_final_answer_tool)\n\n def test_system_prompt_property(self):\n \"\"\"Test that system_prompt property is read-only and calls initialize_system_prompt.\"\"\"\n\n class SimpleAgent(MultiStepAgent):\n def initialize_system_prompt(self) -> str:\n return \"Test system prompt\"\n\n def step(self, memory_step: ActionStep) -> Generator[None]:\n yield None\n\n # Create a simple agent with mocked model\n model = MagicMock()\n agent = SimpleAgent(tools=[], model=model)\n\n # Test reading the property works and calls initialize_system_prompt\n assert agent.system_prompt == \"Test system prompt\"\n\n # Test setting the property raises AttributeError with correct message\n with pytest.raises(\n AttributeError,\n match=re.escape(\n \"\"\"The 'system_prompt' property is read-only. Use 'self.prompt_templates[\"system_prompt\"]' instead.\"\"\"\n ),\n ):\n agent.system_prompt = \"New system prompt\"\n\n # assert \"read-only\" in str(exc_info.value)\n # assert \"Use 'self.prompt_templates[\\\"system_prompt\\\"]' instead\" in str(exc_info.value)\n\n @pytest.mark.parametrize(\n \"step_callbacks, expected_registry_state\",\n [\n # Case 0: None as input (initializes empty registry)\n (\n None,\n {\n \"MemoryStep\": 0,\n \"ActionStep\": 1,\n \"PlanningStep\": 0,\n \"TaskStep\": 0,\n \"SystemPromptStep\": 0,\n \"FinalAnswerStep\": 0,\n }, # Only monitor.update_metrics is registered for ActionStep\n ),\n # Case 1: List of callbacks (registers only for ActionStep: backward compatibility)\n (\n [MagicMock(), MagicMock()],\n {\n \"MemoryStep\": 0,\n \"ActionStep\": 3,\n \"PlanningStep\": 0,\n \"TaskStep\": 0,\n \"SystemPromptStep\": 0,\n \"FinalAnswerStep\": 0,\n },\n ),\n # Case 2: Dict mapping specific step types to callbacks\n (\n {ActionStep: MagicMock(), PlanningStep: MagicMock()},\n {\n \"MemoryStep\": 0,\n \"ActionStep\": 2,\n \"PlanningStep\": 1,\n \"TaskStep\": 0,\n \"SystemPromptStep\": 0,\n \"FinalAnswerStep\": 0,\n },\n ),\n # Case 3: Dict with list of callbacks for a step type\n (\n {ActionStep: [MagicMock(), MagicMock()]},\n {\n \"MemoryStep\": 0,\n \"ActionStep\": 3,\n \"PlanningStep\": 0,\n \"TaskStep\": 0,\n \"SystemPromptStep\": 0,\n \"FinalAnswerStep\": 0,\n },\n ),\n # Case 4: Dict with mixed single and list callbacks\n (\n {ActionStep: MagicMock(), MemoryStep: [MagicMock(), MagicMock()]},\n {\n \"MemoryStep\": 2,\n \"ActionStep\": 2,\n \"PlanningStep\": 0,\n \"TaskStep\": 0,\n \"SystemPromptStep\": 0,\n \"FinalAnswerStep\": 0,\n },\n ),\n ],\n )\n def test_setup_step_callbacks(self, step_callbacks, expected_registry_state):\n \"\"\"Test that _setup_step_callbacks correctly sets up the callback registry.\"\"\"\n # Create a dummy agent\n agent = DummyMultiStepAgent(tools=[], model=MagicMock())\n # Mock the monitor\n agent.monitor = MagicMock()\n\n # Call the method\n agent._setup_step_callbacks(step_callbacks)\n\n # Check that step_callbacks is a CallbackRegistry\n assert isinstance(agent.step_callbacks, CallbackRegistry)\n\n # Count callbacks for each step type\n actual_registry_state = {}\n for step_type in [MemoryStep, ActionStep, PlanningStep, TaskStep, SystemPromptStep, FinalAnswerStep]:\n callbacks = agent.step_callbacks._callbacks.get(step_type, [])\n actual_registry_state[step_type.__name__] = len(callbacks)\n\n # Verify registry state matches expected\n assert actual_registry_state == expected_registry_state\n\n def test_finalize_step_callbacks_with_list(self):\n # Create mock callbacks\n callback1 = MagicMock()\n callback2 = MagicMock()\n\n # Create a test agent with a list of callbacks\n agent = DummyMultiStepAgent(tools=[], model=MagicMock(), step_callbacks=[callback1, callback2])\n\n # Create steps of different types\n action_step = ActionStep(step_number=1, timing=Timing(start_time=0.0))\n planning_step = PlanningStep(\n timing=Timing(start_time=1.0),\n model_input_messages=[],\n model_output_message=ChatMessage(role=\"assistant\", content=\"Test plan\"),\n plan=\"Test planning step\",\n )\n\n # Test with ActionStep\n agent._finalize_step(action_step)\n\n # Verify all callbacks were called\n callback1.assert_called_once_with(action_step, agent=agent)\n callback2.assert_called_once_with(action_step, agent=agent)\n\n # Reset mocks\n callback1.reset_mock()\n callback2.reset_mock()\n\n # Test with PlanningStep\n agent._finalize_step(planning_step)\n\n # Verify all callbacks were called again with the planning step\n callback1.assert_not_called()\n callback2.assert_not_called()\n\n def test_finalize_step_callbacks_by_type(self):\n # Create mock callbacks for different step types\n action_step_callback = MagicMock()\n action_step_callback_2 = MagicMock()\n planning_step_callback = MagicMock()\n step_callback = MagicMock()\n final_answer_step_callback = MagicMock()\n\n # Register callbacks for different step types\n step_callbacks = {\n ActionStep: [action_step_callback, action_step_callback_2],\n PlanningStep: planning_step_callback,\n MemoryStep: step_callback,\n FinalAnswerStep: final_answer_step_callback,\n }\n agent = DummyMultiStepAgent(tools=[], model=MagicMock(), step_callbacks=step_callbacks)\n\n # Create steps of different types\n action_step = ActionStep(step_number=1, timing=Timing(start_time=0.0))\n planning_step = PlanningStep(\n timing=Timing(start_time=1.0),\n model_input_messages=[],\n model_output_message=ChatMessage(role=\"assistant\", content=\"Test plan\"),\n plan=\"Test planning step\",\n )\n final_answer_step = FinalAnswerStep(output=\"Sample output\")\n\n # Test with ActionStep\n agent._finalize_step(action_step)\n\n # Verify correct callbacks were called\n action_step_callback.assert_called_once_with(action_step, agent=agent)\n action_step_callback_2.assert_called_once_with(action_step, agent=agent)\n step_callback.assert_called_once_with(action_step, agent=agent)\n planning_step_callback.assert_not_called()\n final_answer_step_callback.assert_not_called()\n\n # Reset mocks\n action_step_callback.reset_mock()\n action_step_callback_2.reset_mock()\n planning_step_callback.reset_mock()\n step_callback.reset_mock()\n final_answer_step_callback.reset_mock()\n\n # Test with PlanningStep\n agent._finalize_step(planning_step)\n\n # Verify correct callbacks were called\n planning_step_callback.assert_called_once_with(planning_step, agent=agent)\n step_callback.assert_called_once_with(planning_step, agent=agent)\n action_step_callback.assert_not_called()\n action_step_callback_2.assert_not_called()\n final_answer_step_callback.assert_not_called()\n\n # Reset mocks\n action_step_callback.reset_mock()\n action_step_callback_2.reset_mock()\n planning_step_callback.reset_mock()\n step_callback.reset_mock()\n final_answer_step_callback.reset_mock()\n\n # Test with PlanningStep\n agent._finalize_step(final_answer_step)\n\n # Verify correct callbacks were called\n planning_step_callback.assert_not_called()\n step_callback.assert_called_once_with(final_answer_step, agent=agent)\n action_step_callback.assert_not_called()\n action_step_callback_2.assert_not_called()\n final_answer_step_callback.assert_called_once_with(final_answer_step, agent=agent)\n\n def test_logs_display_thoughts_even_if_error(self):\n class FakeJsonModelNoCall(Model):\n def generate(self, messages, stop_sequences=None, tools_to_call_from=None):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"I don't want to call tools today\"\"\",\n tool_calls=None,\n raw=\"\"\"I don't want to call tools today\"\"\",\n )\n\n agent_toolcalling = ToolCallingAgent(model=FakeJsonModelNoCall(), tools=[], max_steps=1, verbosity_level=10)\n with agent_toolcalling.logger.console.capture() as capture:\n agent_toolcalling.run(\"Dummy task\")\n assert \"don't\" in capture.get() and \"want\" in capture.get()\n\n class FakeCodeModelNoCall(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"I don't want to write an action today\"\"\",\n )\n\n agent_code = CodeAgent(model=FakeCodeModelNoCall(), tools=[], max_steps=1, verbosity_level=10)\n with agent_code.logger.console.capture() as capture:\n agent_code.run(\"Dummy task\")\n assert \"don't\" in capture.get() and \"want\" in capture.get()\n\n def test_step_number(self):\n fake_model = MagicMock()\n fake_model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"Model output.\",\n tool_calls=None,\n raw=\"Model output.\",\n token_usage=None,\n )\n max_steps = 2\n agent = CodeAgent(tools=[], model=fake_model, max_steps=max_steps)\n assert hasattr(agent, \"step_number\"), \"step_number attribute should be defined\"\n assert agent.step_number == 0, \"step_number should be initialized to 0\"\n agent.run(\"Test task\")\n assert hasattr(agent, \"step_number\"), \"step_number attribute should be defined\"\n assert agent.step_number == max_steps + 1, \"step_number should be max_steps + 1 after run method is called\"\n\n @pytest.mark.parametrize(\n \"step, expected_messages_list\",\n [\n (\n 1,\n [\n [\n ChatMessage(\n role=MessageRole.USER, content=[{\"type\": \"text\", \"text\": \"INITIAL_PLAN_USER_PROMPT\"}]\n ),\n ],\n ],\n ),\n (\n 2,\n [\n [\n ChatMessage(\n role=MessageRole.SYSTEM,\n content=[{\"type\": \"text\", \"text\": \"UPDATE_PLAN_SYSTEM_PROMPT\"}],\n ),\n ChatMessage(\n role=MessageRole.USER,\n content=[{\"type\": \"text\", \"text\": \"UPDATE_PLAN_USER_PROMPT\"}],\n ),\n ],\n ],\n ),\n ],\n )\n def test_planning_step(self, step, expected_messages_list):\n fake_model = MagicMock()\n agent = CodeAgent(\n tools=[],\n model=fake_model,\n )\n task = \"Test task\"\n\n planning_step = list(agent._generate_planning_step(task, is_first_step=(step == 1), step=step))[-1]\n expected_message_texts = {\n \"INITIAL_PLAN_USER_PROMPT\": populate_template(\n agent.prompt_templates[\"planning\"][\"initial_plan\"],\n variables=dict(\n task=task,\n tools=agent.tools,\n managed_agents=agent.managed_agents,\n answer_facts=planning_step.model_output_message.content,\n ),\n ),\n \"UPDATE_PLAN_SYSTEM_PROMPT\": populate_template(\n agent.prompt_templates[\"planning\"][\"update_plan_pre_messages\"], variables=dict(task=task)\n ),\n \"UPDATE_PLAN_USER_PROMPT\": populate_template(\n agent.prompt_templates[\"planning\"][\"update_plan_post_messages\"],\n variables=dict(\n task=task,\n tools=agent.tools,\n managed_agents=agent.managed_agents,\n facts_update=planning_step.model_output_message.content,\n remaining_steps=agent.max_steps - step,\n ),\n ),\n }\n for expected_messages in expected_messages_list:\n for expected_message in expected_messages:\n expected_message.content[0][\"text\"] = expected_message_texts[expected_message.content[0][\"text\"]]\n assert isinstance(planning_step, PlanningStep)\n expected_model_input_messages = expected_messages_list[0]\n model_input_messages = planning_step.model_input_messages\n assert isinstance(model_input_messages, list)\n assert len(model_input_messages) == len(expected_model_input_messages) # 2\n for message, expected_message in zip(model_input_messages, expected_model_input_messages):\n assert isinstance(message, ChatMessage)\n assert message.role in MessageRole.__members__.values()\n assert message.role == expected_message.role\n assert isinstance(message.content, list)\n for content, expected_content in zip(message.content, expected_message.content):\n assert content == expected_content\n # Test calls to model\n assert len(fake_model.generate.call_args_list) == 1\n for call_args, expected_messages in zip(fake_model.generate.call_args_list, expected_messages_list):\n assert len(call_args.args) == 1\n messages = call_args.args[0]\n assert isinstance(messages, list)\n assert len(messages) == len(expected_messages)\n for message, expected_message in zip(messages, expected_messages):\n assert isinstance(message, ChatMessage)\n assert message.role in MessageRole.__members__.values()\n assert message.role == expected_message.role\n assert isinstance(message.content, list)\n for content, expected_content in zip(message.content, expected_message.content):\n assert content == expected_content\n\n @pytest.mark.parametrize(\n \"expected_messages_list\",\n [\n [\n [\n ChatMessage(\n role=MessageRole.SYSTEM,\n content=[{\"type\": \"text\", \"text\": \"FINAL_ANSWER_SYSTEM_PROMPT\"}],\n ),\n ChatMessage(\n role=MessageRole.USER,\n content=[{\"type\": \"text\", \"text\": \"FINAL_ANSWER_USER_PROMPT\"}],\n ),\n ]\n ],\n [\n [\n ChatMessage(\n role=MessageRole.SYSTEM,\n content=[\n {\"type\": \"text\", \"text\": \"FINAL_ANSWER_SYSTEM_PROMPT\"},\n {\"type\": \"image\", \"image\": \"image1.png\"},\n ],\n ),\n ChatMessage(\n role=MessageRole.USER,\n content=[{\"type\": \"text\", \"text\": \"FINAL_ANSWER_USER_PROMPT\"}],\n ),\n ]\n ],\n ],\n )\n def test_provide_final_answer(self, expected_messages_list):\n fake_model = MagicMock()\n fake_model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"Final answer.\",\n tool_calls=None,\n raw=\"Final answer.\",\n token_usage=None,\n )\n agent = CodeAgent(\n tools=[],\n model=fake_model,\n )\n task = \"Test task\"\n final_answer = agent.provide_final_answer(task).content\n expected_message_texts = {\n \"FINAL_ANSWER_SYSTEM_PROMPT\": agent.prompt_templates[\"final_answer\"][\"pre_messages\"],\n \"FINAL_ANSWER_USER_PROMPT\": populate_template(\n agent.prompt_templates[\"final_answer\"][\"post_messages\"], variables=dict(task=task)\n ),\n }\n for expected_messages in expected_messages_list:\n for expected_message in expected_messages:\n for expected_content in expected_message.content:\n if \"text\" in expected_content:\n expected_content[\"text\"] = expected_message_texts[expected_content[\"text\"]]\n assert final_answer == \"Final answer.\"\n # Test calls to model\n assert len(fake_model.generate.call_args_list) == 1\n for call_args, expected_messages in zip(fake_model.generate.call_args_list, expected_messages_list):\n assert len(call_args.args) == 1\n messages = call_args.args[0]\n assert isinstance(messages, list)\n assert len(messages) == len(expected_messages)\n for message, expected_message in zip(messages, expected_messages):\n assert isinstance(message, ChatMessage)\n assert message.role in MessageRole.__members__.values()\n assert message.role == expected_message.role\n assert isinstance(message.content, list)\n for content, expected_content in zip(message.content, expected_message.content):\n assert content == expected_content\n\n def test_interrupt(self):\n fake_model = MagicMock()\n fake_model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"Model output.\",\n tool_calls=None,\n raw=\"Model output.\",\n token_usage=None,\n )\n\n def interrupt_callback(memory_step, agent):\n agent.interrupt()\n\n agent = CodeAgent(\n tools=[],\n model=fake_model,\n step_callbacks=[interrupt_callback],\n )\n with pytest.raises(AgentError) as e:\n agent.run(\"Test task\")\n assert \"Agent interrupted\" in str(e)\n\n @pytest.mark.parametrize(\n \"tools, managed_agents, name, expectation\",\n [\n # Valid case: no duplicates\n (\n [MockTool(\"tool1\"), MockTool(\"tool2\")],\n [MockAgent(\"agent1\", [MockTool(\"tool3\")])],\n \"test_agent\",\n does_not_raise(),\n ),\n # Invalid case: duplicate tool names\n ([MockTool(\"tool1\"), MockTool(\"tool1\")], [], \"test_agent\", pytest.raises(ValueError)),\n # Invalid case: tool name same as managed agent name\n (\n [MockTool(\"tool1\")],\n [MockAgent(\"tool1\", [MockTool(\"final_answer\")])],\n \"test_agent\",\n pytest.raises(ValueError),\n ),\n # Valid case: tool name same as managed agent's tool name\n ([MockTool(\"tool1\")], [MockAgent(\"agent1\", [MockTool(\"tool1\")])], \"test_agent\", does_not_raise()),\n # Invalid case: duplicate managed agent name and managed agent tool name\n ([MockTool(\"tool1\")], [], \"tool1\", pytest.raises(ValueError)),\n # Valid case: duplicate tool names across managed agents\n (\n [MockTool(\"tool1\")],\n [\n MockAgent(\"agent1\", [MockTool(\"tool2\"), MockTool(\"final_answer\")]),\n MockAgent(\"agent2\", [MockTool(\"tool2\"), MockTool(\"final_answer\")]),\n ],\n \"test_agent\",\n does_not_raise(),\n ),\n ],\n )\n def test_validate_tools_and_managed_agents(self, tools, managed_agents, name, expectation):\n fake_model = MagicMock()\n with expectation:\n DummyMultiStepAgent(\n tools=tools,\n model=fake_model,\n name=name,\n managed_agents=managed_agents,\n )\n\n def test_from_dict(self):\n # Create a test agent dictionary\n agent_dict = {\n \"model\": {\"class\": \"TransformersModel\", \"data\": {\"model_id\": \"test/model\"}},\n \"tools\": [\n {\n \"name\": \"valid_tool_function\",\n \"code\": 'from smolagents import Tool\\nfrom typing import Any, Optional\\n\\nclass SimpleTool(Tool):\\n name = \"valid_tool_function\"\\n description = \"A valid tool function.\"\\n inputs = {\"input\":{\"type\":\"string\",\"description\":\"Input string.\"}}\\n output_type = \"string\"\\n\\n def forward(self, input: str) -> str:\\n \"\"\"A valid tool function.\\n\\n Args:\\n input (str): Input string.\\n \"\"\"\\n return input.upper()',\n \"requirements\": {\"smolagents\"},\n }\n ],\n \"managed_agents\": {},\n \"prompt_templates\": EMPTY_PROMPT_TEMPLATES,\n \"max_steps\": 15,\n \"verbosity_level\": 2,\n \"planning_interval\": 3,\n \"name\": \"test_agent\",\n \"description\": \"Test agent description\",\n }\n\n # Call from_dict: mock the MODEL_REGISTRY to return a mock model class\n mock_model_class = MagicMock()\n mock_model_instance = MagicMock()\n mock_model_class.from_dict.return_value = mock_model_instance\n\n with patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"TransformersModel\": mock_model_class}):\n agent = DummyMultiStepAgent.from_dict(agent_dict)\n\n # Verify the agent was created correctly\n assert agent.model == mock_model_instance\n assert mock_model_class.from_dict.call_args.args[0] == {\"model_id\": \"test/model\"}\n assert agent.max_steps == 15\n assert agent.logger.level == 2\n assert agent.planning_interval == 3\n assert agent.name == \"test_agent\"\n assert agent.description == \"Test agent description\"\n # Verify the tool was created correctly\n assert sorted(agent.tools.keys()) == [\"final_answer\", \"valid_tool_function\"]\n assert agent.tools[\"valid_tool_function\"].name == \"valid_tool_function\"\n assert agent.tools[\"valid_tool_function\"].description == \"A valid tool function.\"\n assert agent.tools[\"valid_tool_function\"].inputs == {\n \"input\": {\"type\": \"string\", \"description\": \"Input string.\"}\n }\n assert agent.tools[\"valid_tool_function\"](\"test\") == \"TEST\"\n\n # Test overriding with kwargs\n with patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"TransformersModel\": mock_model_class}):\n agent = DummyMultiStepAgent.from_dict(agent_dict, max_steps=30)\n assert agent.max_steps == 30\n\n def test_multiagent_to_dict_from_dict_roundtrip(self):\n \"\"\"Test that to_dict() and from_dict() work correctly for agents with managed agents.\"\"\"\n # Create a managed agent\n managed_agent = CodeAgent(\n tools=[], model=MagicMock(), name=\"managed_agent\", description=\"A managed agent for testing\", max_steps=5\n )\n\n # Create a main agent with the managed agent\n main_agent = ToolCallingAgent(\n tools=[],\n managed_agents=[managed_agent],\n model=MagicMock(),\n name=\"main_agent\",\n description=\"Main agent with managed agents\",\n max_steps=10,\n )\n\n # Convert to dict\n agent_dict = main_agent.to_dict()\n\n # Verify managed_agents structure in dict\n assert \"managed_agents\" in agent_dict\n assert isinstance(agent_dict[\"managed_agents\"], list)\n assert len(agent_dict[\"managed_agents\"]) == 1\n\n managed_agent_dict = agent_dict[\"managed_agents\"][0]\n assert managed_agent_dict[\"name\"] == \"managed_agent\"\n assert managed_agent_dict[\"class\"] == \"CodeAgent\"\n assert managed_agent_dict[\"description\"] == \"A managed agent for testing\"\n assert managed_agent_dict[\"max_steps\"] == 5\n\n # Test round-trip: from_dict should recreate the agent\n # Mock the model class for the test\n mock_model_class = MagicMock()\n mock_model_instance = MagicMock()\n mock_model_class.from_dict.return_value = mock_model_instance\n\n with patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"MagicMock\": mock_model_class}):\n recreated_agent = ToolCallingAgent.from_dict(agent_dict)\n\n # Verify the recreated agent has the same structure\n assert recreated_agent.name == \"main_agent\"\n assert recreated_agent.description == \"Main agent with managed agents\"\n assert recreated_agent.max_steps == 10\n assert len(recreated_agent.managed_agents) == 1\n\n recreated_managed_agent = list(recreated_agent.managed_agents.values())[0]\n assert recreated_managed_agent.name == \"managed_agent\"\n assert recreated_managed_agent.description == \"A managed agent for testing\"\n assert recreated_managed_agent.max_steps == 5\n\n def test_from_dict_invalid_model_class(self):\n \"\"\"Test that from_dict raises ValueError with helpful message for invalid model class.\"\"\"\n agent_dict = {\n \"class\": \"CodeAgent\",\n \"model\": {\"class\": \"InvalidModelClass\", \"data\": {}},\n \"tools\": [],\n \"managed_agents\": [],\n }\n\n with pytest.raises(ValueError) as exc_info:\n CodeAgent.from_dict(agent_dict)\n\n error_message = str(exc_info.value)\n assert \"InvalidModelClass\" in error_message\n assert \"Unknown model class\" in error_message\n assert \"Supported models:\" in error_message\n\n def test_from_dict_invalid_agent_class(self):\n \"\"\"Test that from_dict raises ValueError with helpful message for invalid agent class.\"\"\"\n # Create a valid agent first\n agent = CodeAgent(tools=[], model=MagicMock(), name=\"test_agent\")\n agent_dict = agent.to_dict()\n\n # Add a managed agent with invalid class\n agent_dict[\"managed_agents\"] = [\n {\n \"class\": \"InvalidAgentClass\",\n \"model\": {\"class\": \"MagicMock\", \"data\": {}},\n \"tools\": [],\n \"managed_agents\": [],\n }\n ]\n\n # Mock the model registry to allow the main agent's model and managed agent's model\n mock_model_class = MagicMock()\n mock_model_instance = MagicMock()\n mock_model_class.from_dict.return_value = mock_model_instance\n\n with patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"MagicMock\": mock_model_class}):\n with pytest.raises(ValueError) as exc_info:\n CodeAgent.from_dict(agent_dict)\n\n error_message = str(exc_info.value)\n assert \"InvalidAgentClass\" in error_message\n assert \"Unknown agent class\" in error_message\n assert \"Supported agents:\" in error_message\n\n\nclass TestToolCallingAgent:\n def test_toolcalling_agent_instructions(self):\n agent = ToolCallingAgent(tools=[], model=MagicMock(), instructions=\"Test instructions\")\n assert agent.instructions == \"Test instructions\"\n assert \"Test instructions\" in agent.system_prompt\n\n def test_toolcalling_agent_passes_both_tools_and_managed_agents(self, test_tool):\n \"\"\"Test that both tools and managed agents are passed to the model.\"\"\"\n managed_agent = MagicMock()\n managed_agent.name = \"managed_agent\"\n model = MagicMock()\n model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"test_tool\", arguments={\"input\": \"test_value\"}),\n )\n ],\n )\n agent = ToolCallingAgent(tools=[test_tool], managed_agents=[managed_agent], model=model)\n # Run the agent one step to trigger the model call\n next(agent.run(\"Test task\", stream=True))\n # Check that the model was called with both tools and managed agents:\n # - Get all tool_to_call_from names passed to the model\n tools_to_call_from_names = [tool.name for tool in model.generate.call_args.kwargs[\"tools_to_call_from\"]]\n # - Verify both regular tools and managed agents are included\n assert \"test_tool\" in tools_to_call_from_names # The regular tool\n assert \"managed_agent\" in tools_to_call_from_names # The managed agent\n assert \"final_answer\" in tools_to_call_from_names # The final_answer tool (added by default)\n\n @patch(\"huggingface_hub.InferenceClient\")\n def test_toolcalling_agent_api(self, mock_inference_client):\n mock_client = mock_inference_client.return_value\n mock_response = mock_client.chat_completion.return_value\n mock_response.choices[0].message = ChatCompletionOutputMessage(\n role=MessageRole.ASSISTANT,\n content='{\"name\": \"weather_api\", \"arguments\": {\"location\": \"Paris\", \"date\": \"today\"}}',\n )\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 20\n\n model = InferenceClientModel(model_id=\"test-model\")\n\n from smolagents import tool\n\n @tool\n def weather_api(location: str, date: str) -> str:\n \"\"\"\n Gets the weather in the next days at given location.\n Args:\n location: the location\n date: the date\n \"\"\"\n return f\"The weather in {location} on date:{date} is sunny.\"\n\n agent = ToolCallingAgent(model=model, tools=[weather_api], max_steps=1)\n agent.run(\"What's the weather in Paris?\")\n assert agent.memory.steps[0].task == \"What's the weather in Paris?\"\n assert agent.memory.steps[1].tool_calls[0].name == \"weather_api\"\n assert agent.memory.steps[1].tool_calls[0].arguments == {\"location\": \"Paris\", \"date\": \"today\"}\n assert agent.memory.steps[1].observations == \"The weather in Paris on date:today is sunny.\"\n\n mock_response.choices[0].message = ChatCompletionOutputMessage(\n role=MessageRole.ASSISTANT,\n content=None,\n tool_calls=[\n ChatCompletionOutputToolCall(\n function=ChatCompletionOutputFunctionDefinition(\n name=\"weather_api\", arguments='{\"location\": \"Paris\", \"date\": \"today\"}'\n ),\n id=\"call_0\",\n type=\"function\",\n )\n ],\n )\n\n agent.run(\"What's the weather in Paris?\")\n assert agent.memory.steps[0].task == \"What's the weather in Paris?\"\n assert agent.memory.steps[1].tool_calls[0].name == \"weather_api\"\n assert agent.memory.steps[1].tool_calls[0].arguments == {\"location\": \"Paris\", \"date\": \"today\"}\n assert agent.memory.steps[1].observations == \"The weather in Paris on date:today is sunny.\"\n\n @patch(\"openai.OpenAI\")\n def test_toolcalling_agent_stream_logs_multiple_tool_calls_observations(self, mock_openai_client, test_tool):\n \"\"\"Test that ToolCallingAgent with stream_outputs=True logs the observations of all tool calls when multiple are called.\"\"\"\n mock_client = mock_openai_client.return_value\n from smolagents import OpenAIModel\n\n # Mock streaming response with multiple tool calls\n mock_deltas = [\n ChoiceDelta(role=MessageRole.ASSISTANT),\n ChoiceDelta(\n tool_calls=[\n ChoiceDeltaToolCall(\n index=0,\n id=\"call_1\",\n function=ChoiceDeltaToolCallFunction(name=\"test_tool\"),\n type=\"function\",\n )\n ]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=0, function=ChoiceDeltaToolCallFunction(arguments='{\"in'))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=0, function=ChoiceDeltaToolCallFunction(arguments='put\"'))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=0, function=ChoiceDeltaToolCallFunction(arguments=': \"out'))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=0, function=ChoiceDeltaToolCallFunction(arguments=\"put1\"))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=0, function=ChoiceDeltaToolCallFunction(arguments='\"}'))]\n ),\n ChoiceDelta(\n tool_calls=[\n ChoiceDeltaToolCall(\n index=1,\n id=\"call_2\",\n function=ChoiceDeltaToolCallFunction(name=\"test_tool\"),\n type=\"function\",\n )\n ]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=1, function=ChoiceDeltaToolCallFunction(arguments='{\"in'))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=1, function=ChoiceDeltaToolCallFunction(arguments='put\"'))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=1, function=ChoiceDeltaToolCallFunction(arguments=': \"out'))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=1, function=ChoiceDeltaToolCallFunction(arguments=\"put2\"))]\n ),\n ChoiceDelta(\n tool_calls=[ChoiceDeltaToolCall(index=1, function=ChoiceDeltaToolCallFunction(arguments='\"}'))]\n ),\n ]\n\n class MockChoice:\n def __init__(self, delta):\n self.delta = delta\n\n class MockChunk:\n def __init__(self, delta):\n self.choices = [MockChoice(delta)]\n self.usage = None\n\n mock_client.chat.completions.create.return_value = (MockChunk(delta) for delta in mock_deltas)\n\n # Mock usage for non-streaming fallback\n mock_usage = MagicMock()\n mock_usage.prompt_tokens = 10\n mock_usage.completion_tokens = 20\n\n model = OpenAIModel(model_id=\"fakemodel\")\n\n agent = ToolCallingAgent(model=model, tools=[test_tool], max_steps=1, stream_outputs=True)\n agent.run(\"Dummy task\")\n assert agent.memory.steps[1].model_output_message.tool_calls[0].function.name == \"test_tool\"\n assert agent.memory.steps[1].model_output_message.tool_calls[1].function.name == \"test_tool\"\n assert agent.memory.steps[1].observations == \"Processed: output1\\nProcessed: output2\"\n\n @patch(\"openai.OpenAI\")\n def test_toolcalling_agent_final_answer_cannot_be_called_with_parallel_tool_calls(\n self, mock_openai_client, test_tool\n ):\n \"\"\"Test that ToolCallingAgent with stream_outputs=True returns the all tool calls when multiple are called.\"\"\"\n mock_client = mock_openai_client.return_value\n\n from smolagents import OpenAIModel\n\n class ExtendedChatMessage(ChatMessage):\n def __init__(self, *args, usage, **kwargs):\n super().__init__(*args, **kwargs)\n\n def model_dump(self, include=None):\n return super().model_dump_json()\n\n class MockChoice:\n def __init__(self, chat_message):\n self.message = chat_message\n\n class MockChatCompletion:\n def __init__(self, chat_message):\n self.choices = [MockChoice(chat_message)]\n self.usage = MockTokenUsage(prompt_tokens=10, completion_tokens=20)\n\n class MockTokenUsage:\n def __init__(self, prompt_tokens, completion_tokens):\n self.prompt_tokens = prompt_tokens\n self.completion_tokens = completion_tokens\n\n from dataclasses import asdict\n\n class ExtendedChatCompletionOutputMessage(ChatCompletionOutputMessage):\n def __init__(self, *args, usage, **kwargs):\n super().__init__(*args, **kwargs)\n self.usage = usage\n\n def model_dump(self, include=None):\n print(\"TOOL CALLS\", self.tool_calls)\n return {\n \"role\": self.role,\n \"content\": self.content,\n \"tool_calls\": [asdict(tc) for tc in self.tool_calls],\n }\n\n mock_client.chat.completions.create.return_value = MockChatCompletion(\n ExtendedChatCompletionOutputMessage(\n role=MessageRole.ASSISTANT,\n content=None,\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"test_tool\", arguments={\"input\": \"out1\"}),\n ),\n ChatMessageToolCall(\n id=\"1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"final_answer\", arguments={\"answer\": \"out1\"}),\n ),\n ],\n usage=MockTokenUsage(prompt_tokens=10, completion_tokens=20),\n )\n )\n\n model = OpenAIModel(model_id=\"fakemodel\")\n\n agent = ToolCallingAgent(model=model, tools=[test_tool], max_steps=1)\n agent.run(\"Dummy task\")\n assert agent.memory.steps[1].error is not None\n assert (\n \"do not perform any other tool calls than the final answer tool call!\"\n in agent.memory.steps[1].error.message\n )\n\n @patch(\"huggingface_hub.InferenceClient\")\n def test_toolcalling_agent_api_misformatted_output(self, mock_inference_client):\n \"\"\"Test that even misformatted json blobs don't interrupt the run for a ToolCallingAgent.\"\"\"\n mock_client = mock_inference_client.return_value\n mock_response = mock_client.chat_completion.return_value\n mock_response.choices[0].message = ChatCompletionOutputMessage(\n role=MessageRole.ASSISTANT,\n content='{\"name\": weather_api\", \"arguments\": {\"location\": \"Paris\", \"date\": \"today\"}}',\n )\n\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 20\n\n model = InferenceClientModel(model_id=\"test-model\")\n\n logger = AgentLogger(console=Console(markup=False, no_color=True))\n\n agent = ToolCallingAgent(model=model, tools=[], max_steps=2, verbosity_level=1, logger=logger)\n with agent.logger.console.capture() as capture:\n agent.run(\"What's the weather in Paris?\")\n assert agent.memory.steps[0].task == \"What's the weather in Paris?\"\n assert agent.memory.steps[1].tool_calls is None\n assert \"The JSON blob you used is invalid\" in agent.memory.steps[1].error.message\n assert \"Error while parsing\" in capture.get()\n assert len(agent.memory.steps) == 4\n\n @pytest.mark.skip(\n reason=\"Test is not properly implemented (GH-1255) because fake_tools should have the same name. \"\n \"Additionally, it uses CodeAgent instead of ToolCallingAgent (GH-1409)\"\n )\n def test_change_tools_after_init(self):\n from smolagents import tool\n\n @tool\n def fake_tool_1() -> str:\n \"\"\"Fake tool\"\"\"\n return \"1\"\n\n @tool\n def fake_tool_2() -> str:\n \"\"\"Fake tool\"\"\"\n return \"2\"\n\n class FakeCodeModel(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(role=MessageRole.ASSISTANT, content=\"\\nfinal_answer(fake_tool_1())\\n\")\n\n agent = CodeAgent(tools=[fake_tool_1], model=FakeCodeModel())\n\n agent.tools[\"final_answer\"] = CustomFinalAnswerTool()\n agent.tools[\"fake_tool_1\"] = fake_tool_2\n\n answer = agent.run(\"Fake task.\")\n assert answer == \"2CUSTOM\"\n\n def test_custom_final_answer_with_custom_inputs(self, test_tool):\n class CustomFinalAnswerToolWithCustomInputs(FinalAnswerTool):\n inputs = {\n \"answer1\": {\"type\": \"string\", \"description\": \"First part of the answer.\"},\n \"answer2\": {\"type\": \"string\", \"description\": \"Second part of the answer.\"},\n }\n\n def forward(self, answer1: str, answer2: str) -> str:\n return answer1 + \" and \" + answer2\n\n model = MagicMock()\n model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT,\n content=None,\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"final_answer\", arguments={\"answer1\": \"1\", \"answer2\": \"2\"}\n ),\n ),\n ],\n )\n agent = ToolCallingAgent(tools=[test_tool, CustomFinalAnswerToolWithCustomInputs()], model=model)\n answer = agent.run(\"Fake task.\")\n assert answer == \"1 and 2\"\n assert agent.memory.steps[-1].model_output_message.tool_calls[0].function.name == \"final_answer\"\n\n @pytest.mark.parametrize(\n \"test_case\",\n [\n # Case 0: Single valid tool call\n {\n \"tool_calls\": [\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"test_tool\", arguments={\"input\": \"test_value\"}),\n )\n ],\n \"expected_observations\": \"Processed: test_value\",\n \"expected_final_outputs\": [\"Processed: test_value\"],\n \"expected_error\": None,\n },\n # Case 1: Multiple tool calls\n {\n \"tool_calls\": [\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"test_tool\", arguments={\"input\": \"value1\"}),\n ),\n ChatMessageToolCall(\n id=\"call_2\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"test_tool\", arguments={\"input\": \"value2\"}),\n ),\n ],\n \"expected_observations\": \"Processed: value1\\nProcessed: value2\",\n \"expected_final_outputs\": [\"Processed: value1\", \"Processed: value2\"],\n \"expected_error\": None,\n },\n # Case 2: Invalid tool name\n {\n \"tool_calls\": [\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"nonexistent_tool\", arguments={\"input\": \"test\"}),\n )\n ],\n \"expected_error\": AgentToolExecutionError,\n },\n # Case 3: Tool execution error\n {\n \"tool_calls\": [\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"test_tool\", arguments={\"input\": \"error\"}),\n )\n ],\n \"expected_error\": AgentToolExecutionError,\n },\n # Case 4: Empty tool calls list\n {\n \"tool_calls\": [],\n \"expected_observations\": \"\",\n \"expected_final_outputs\": [],\n \"expected_error\": None,\n },\n # Case 5: Final answer call\n {\n \"tool_calls\": [\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"final_answer\", arguments={\"answer\": \"This is the final answer\"}\n ),\n )\n ],\n \"expected_observations\": \"This is the final answer\",\n \"expected_final_outputs\": [\"This is the final answer\"],\n \"expected_error\": None,\n },\n # Case 6: Invalid arguments\n {\n \"tool_calls\": [\n ChatMessageToolCall(\n id=\"call_1\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"test_tool\", arguments={\"wrong_param\": \"value\"}),\n )\n ],\n \"expected_error\": AgentToolCallError,\n },\n ],\n )\n def test_process_tool_calls(self, test_case, test_tool):\n # Create a ToolCallingAgent instance with the test tool\n agent = ToolCallingAgent(tools=[test_tool], model=MagicMock())\n # Create chat message with the specified tool calls for process_tool_calls\n chat_message = ChatMessage(role=MessageRole.ASSISTANT, content=\"\", tool_calls=test_case[\"tool_calls\"])\n # Create a memory step for process_tool_calls\n memory_step = ActionStep(step_number=10, timing=\"mock_timing\", model_output=\"\")\n\n # Process tool calls\n if test_case[\"expected_error\"]:\n with pytest.raises(test_case[\"expected_error\"]):\n list(agent.process_tool_calls(chat_message, memory_step))\n else:\n final_outputs = list(agent.process_tool_calls(chat_message, memory_step))\n assert memory_step.model_output == \"\"\n assert memory_step.observations == test_case[\"expected_observations\"]\n assert [\n final_output.output for final_output in final_outputs if isinstance(final_output, ToolOutput)\n ] == test_case[\"expected_final_outputs\"]\n # Verify memory step tool calls were updated correctly\n if test_case[\"tool_calls\"]:\n assert memory_step.tool_calls == [\n ToolCall(name=tool_call.function.name, arguments=tool_call.function.arguments, id=tool_call.id)\n for tool_call in test_case[\"tool_calls\"]\n ]\n\n\nclass TestCodeAgent:\n def test_code_agent_instructions(self):\n agent = CodeAgent(tools=[], model=MagicMock(), instructions=\"Test instructions\")\n assert agent.instructions == \"Test instructions\"\n assert \"Test instructions\" in agent.system_prompt\n\n agent = CodeAgent(\n tools=[], model=MagicMock(), instructions=\"Test instructions\", use_structured_outputs_internally=True\n )\n assert agent.instructions == \"Test instructions\"\n assert \"Test instructions\" in agent.system_prompt\n\n @pytest.mark.parametrize(\"provide_run_summary\", [False, True])\n def test_call_with_provide_run_summary(self, provide_run_summary):\n agent = CodeAgent(tools=[], model=MagicMock(), provide_run_summary=provide_run_summary)\n assert agent.provide_run_summary is provide_run_summary\n agent.name = \"test_agent\"\n agent.run = MagicMock(return_value=\"Test output\")\n agent.write_memory_to_messages = MagicMock(\n return_value=[ChatMessage(role=MessageRole.ASSISTANT, content=\"Test summary\")]\n )\n\n result = agent(\"Test request\")\n expected_summary = \"Here is the final answer from your managed agent 'test_agent':\\nTest output\"\n if provide_run_summary:\n expected_summary += (\n \"\\n\\nFor more detail, find below a summary of this agent's work:\\n\"\n \"\\n\\nTest summary\\n---\\n \"\n )\n assert result == expected_summary\n\n def test_code_agent_image_output(self):\n from PIL import Image\n\n from smolagents import tool\n\n @tool\n def image_generation_tool():\n \"\"\"Generate an image\"\"\"\n return Image.new(\"RGB\", (100, 100), color=\"red\")\n\n agent = CodeAgent(tools=[image_generation_tool], model=FakeCodeModelImageGeneration(), verbosity_level=1)\n output = agent.run(\"Make me an image from the latest trend on google trends.\")\n assert isinstance(output, Image.Image)\n\n def test_errors_logging(self):\n class FakeCodeModel(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(role=MessageRole.ASSISTANT, content=\"\\nsecret=3;['1', '2'][secret]\\n\")\n\n agent = CodeAgent(tools=[], model=FakeCodeModel(), verbosity_level=1)\n\n with agent.logger.console.capture() as capture:\n agent.run(\"Test request\")\n # Verify [secret] is rendered literally, not interpreted as Rich markup (which would\n # inject ANSI reset/re-apply codes like \\x1b[0m\\x1b[1;31m in place of the brackets).\n assert \"[secret]\" in capture.get()\n\n def test_missing_import_triggers_advice_in_error_log(self):\n # Set explicit verbosity level to 1 to override the default verbosity level of -1 set in CI fixture\n agent = CodeAgent(tools=[], model=FakeCodeModelImport(), verbosity_level=1)\n\n with agent.logger.console.capture() as capture:\n agent.run(\"Count to 3\")\n str_output = capture.get()\n assert \"`additional_authorized_imports`\" in str_output.replace(\"\\n\", \"\")\n\n def test_errors_show_offending_line_and_error(self):\n agent = CodeAgent(tools=[PythonInterpreterTool()], model=FakeCodeModelError())\n output = agent.run(\"What is 2 multiplied by 3.6452?\")\n assert isinstance(output, AgentText)\n assert output == \"got an error\"\n assert \"Code execution failed at line 'error_function()'\" in str(agent.memory.steps[1].error)\n assert \"ValueError\" in str(agent.memory.steps)\n\n def test_error_saves_previous_print_outputs(self):\n agent = CodeAgent(tools=[PythonInterpreterTool()], model=FakeCodeModelError())\n agent.run(\"What is 2 multiplied by 3.6452?\")\n assert \"Flag!\" in str(agent.memory.steps[1].observations)\n\n def test_syntax_error_show_offending_lines(self):\n agent = CodeAgent(tools=[PythonInterpreterTool()], model=FakeCodeModelSyntaxError())\n output = agent.run(\"What is 2 multiplied by 3.6452?\")\n assert isinstance(output, AgentText)\n assert output == \"got an error\"\n assert ' print(\"Failing due to unexpected indent\")' in str(agent.memory.steps)\n assert isinstance(agent.memory.steps[-2], ActionStep)\n assert agent.memory.steps[-2].code_action == dedent(\"\"\"a = 2\nb = a * 2\n print(\"Failing due to unexpected indent\")\nprint(\"Ok, calculation done!\")\"\"\")\n\n def test_end_code_appending(self):\n # Checking original output message\n orig_output = FakeCodeModelNoReturn().generate([])\n assert not orig_output.content.endswith(\"\")\n\n # Checking the step output\n agent = CodeAgent(\n tools=[PythonInterpreterTool()],\n model=FakeCodeModelNoReturn(),\n max_steps=1,\n )\n answer = agent.run(\"What is 2 multiplied by 3.6452?\")\n assert answer\n\n memory_steps = agent.memory.steps\n actions_steps = [s for s in memory_steps if isinstance(s, ActionStep)]\n\n outputs = [s.model_output for s in actions_steps if s.model_output]\n assert outputs\n assert all(o.endswith(\" \") for o in outputs)\n\n messages = [s.model_output_message for s in actions_steps if s.model_output_message]\n assert messages\n assert all(m.content.endswith(\"\") for m in messages)\n\n @pytest.mark.skip(\n reason=\"Test is not properly implemented (GH-1255) because fake_tools should have the same name. \"\n )\n def test_change_tools_after_init(self):\n from smolagents import tool\n\n @tool\n def fake_tool_1() -> str:\n \"\"\"Fake tool\"\"\"\n return \"1\"\n\n @tool\n def fake_tool_2() -> str:\n \"\"\"Fake tool\"\"\"\n return \"2\"\n\n class FakeCodeModel(Model):\n def generate(self, messages, stop_sequences=None):\n return ChatMessage(role=MessageRole.ASSISTANT, content=\"\\nfinal_answer(fake_tool_1())\\n\")\n\n agent = CodeAgent(tools=[fake_tool_1], model=FakeCodeModel())\n\n agent.tools[\"final_answer\"] = CustomFinalAnswerTool()\n agent.tools[\"fake_tool_1\"] = fake_tool_2\n\n answer = agent.run(\"Fake task.\")\n assert answer == \"2CUSTOM\"\n\n def test_local_python_executor_with_custom_functions(self):\n model = MagicMock()\n model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=None,\n raw=\"\",\n token_usage=None,\n )\n agent = CodeAgent(tools=[], model=model, executor_kwargs={\"additional_functions\": {\"open\": open}})\n agent.run(\"Test run\")\n assert \"open\" in agent.python_executor.static_tools\n\n @pytest.mark.parametrize(\"agent_dict_version\", [\"v1.9\", \"v1.10\", \"v1.20\"])\n def test_from_folder(self, agent_dict_version, get_agent_dict):\n agent_dict = get_agent_dict(agent_dict_version)\n mock_model_class = MagicMock()\n mock_model_instance = MagicMock()\n mock_model_instance.model_id = \"Qwen/Qwen2.5-Coder-32B-Instruct\"\n mock_model_class.from_dict.return_value = mock_model_instance\n\n with (\n patch(\"smolagents.agents.Path\") as mock_path,\n patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"InferenceClientModel\": mock_model_class}),\n ):\n import json\n\n mock_path.return_value.__truediv__.return_value.read_text.return_value = json.dumps(agent_dict)\n agent = CodeAgent.from_folder(\"ignored_dummy_folder\")\n assert isinstance(agent, CodeAgent)\n assert agent.name == \"test_agent\"\n assert agent.description == \"dummy description\"\n assert agent.max_steps == 10\n assert agent.planning_interval == 2\n assert agent.additional_authorized_imports == [\"pandas\"]\n assert \"pandas\" in agent.authorized_imports\n assert agent.executor_type == \"local\"\n assert agent.executor_kwargs == {}\n assert agent.max_print_outputs_length is None\n assert agent.managed_agents == {}\n assert set(agent.tools.keys()) == {\"final_answer\"}\n assert agent.model == mock_model_instance\n assert mock_model_class.from_dict.call_args.args[0][\"model_id\"] == \"Qwen/Qwen2.5-Coder-32B-Instruct\"\n assert agent.model.model_id == \"Qwen/Qwen2.5-Coder-32B-Instruct\"\n assert agent.logger.level == 2\n assert agent.prompt_templates[\"system_prompt\"] == \"dummy system prompt\"\n\n def test_from_dict(self):\n # Create a test agent dictionary\n agent_dict = {\n \"model\": {\"class\": \"InferenceClientModel\", \"data\": {\"model_id\": \"Qwen/Qwen2.5-Coder-32B-Instruct\"}},\n \"tools\": [\n {\n \"name\": \"valid_tool_function\",\n \"code\": 'from smolagents import Tool\\nfrom typing import Any, Optional\\n\\nclass SimpleTool(Tool):\\n name = \"valid_tool_function\"\\n description = \"A valid tool function.\"\\n inputs = {\"input\":{\"type\":\"string\",\"description\":\"Input string.\"}}\\n output_type = \"string\"\\n\\n def forward(self, input: str) -> str:\\n \"\"\"A valid tool function.\\n\\n Args:\\n input (str): Input string.\\n \"\"\"\\n return input.upper()',\n \"requirements\": {\"smolagents\"},\n }\n ],\n \"managed_agents\": {},\n \"prompt_templates\": EMPTY_PROMPT_TEMPLATES,\n \"max_steps\": 15,\n \"verbosity_level\": 2,\n \"use_structured_output\": False,\n \"planning_interval\": 3,\n \"name\": \"test_code_agent\",\n \"description\": \"Test code agent description\",\n \"authorized_imports\": [\"pandas\", \"numpy\"],\n \"executor_type\": \"local\",\n \"executor_kwargs\": {\"max_print_outputs_length\": 10_000},\n \"max_print_outputs_length\": 1000,\n }\n\n # Call from_dict\n mock_model_class = MagicMock()\n mock_model_instance = MagicMock()\n mock_model_class.from_dict.return_value = mock_model_instance\n\n with patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"InferenceClientModel\": mock_model_class}):\n agent = CodeAgent.from_dict(agent_dict)\n\n # Verify the agent was created correctly with CodeAgent-specific parameters\n assert agent.model == mock_model_instance\n assert agent.additional_authorized_imports == [\"pandas\", \"numpy\"]\n assert agent.executor_type == \"local\"\n assert agent.executor_kwargs == {\"max_print_outputs_length\": 10_000}\n assert agent.max_print_outputs_length == 1000\n\n # Test with missing optional parameters\n minimal_agent_dict = {\n \"model\": {\"class\": \"InferenceClientModel\", \"data\": {\"model_id\": \"Qwen/Qwen2.5-Coder-32B-Instruct\"}},\n \"tools\": [],\n \"managed_agents\": {},\n }\n\n with patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"InferenceClientModel\": mock_model_class}):\n agent = CodeAgent.from_dict(minimal_agent_dict)\n # Verify defaults are used\n assert agent.max_steps == 20 # default from MultiStepAgent.__init__\n\n # Test overriding with kwargs\n with patch.dict(\"smolagents.models.MODEL_REGISTRY\", {\"InferenceClientModel\": mock_model_class}):\n agent = CodeAgent.from_dict(\n agent_dict,\n additional_authorized_imports=[\"requests\"],\n executor_kwargs={\"max_print_outputs_length\": 5_000},\n )\n assert agent.additional_authorized_imports == [\"requests\"]\n assert agent.executor_kwargs == {\"max_print_outputs_length\": 5_000}\n\n def test_custom_final_answer_with_custom_inputs(self):\n class CustomFinalAnswerToolWithCustomInputs(FinalAnswerTool):\n inputs = {\n \"answer1\": {\"type\": \"string\", \"description\": \"First part of the answer.\"},\n \"answer2\": {\"type\": \"string\", \"description\": \"Second part of the answer.\"},\n }\n\n def forward(self, answer1: str, answer2: str) -> str:\n return answer1 + \"CUSTOM\" + answer2\n\n model = MagicMock()\n model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT, content=\"\\nfinal_answer(answer1='1', answer2='2')\\n\"\n )\n agent = CodeAgent(tools=[CustomFinalAnswerToolWithCustomInputs()], model=model)\n answer = agent.run(\"Fake task.\")\n assert answer == \"1CUSTOM2\"\n\n def test_use_structured_outputs_internally(self):\n expected_code = \"print('Hello, world!')\"\n model = MagicMock()\n # mock structured output generation\n model.generate.return_value = ChatMessage(\n role=MessageRole.ASSISTANT,\n content=json.dumps({\"thought\": \"LLM-generated thought\", \"code\": expected_code}),\n )\n agent = CodeAgent(\n tools=[], model=model, use_structured_outputs_internally=True\n ) # Use structured outputs internally\n tool_call: ToolCall = next(\n agent._step_stream(ActionStep(step_number=1, timing=\"mock_timing\", model_output=\"\"))\n )\n assert tool_call.arguments == expected_code\n\n\nclass TestMultiAgents:\n def test_multiagents_save(self, tmp_path):\n model = InferenceClientModel(model_id=\"Qwen/Qwen2.5-Coder-32B-Instruct\", max_tokens=2096, temperature=0.5)\n\n web_agent = ToolCallingAgent(\n model=model,\n tools=[DuckDuckGoSearchTool(max_results=2), VisitWebpageTool()],\n name=\"web_agent\",\n description=\"does web searches\",\n )\n code_agent = CodeAgent(model=model, tools=[], name=\"useless\", description=\"does nothing in particular\")\n\n agent = CodeAgent(\n model=model,\n tools=[],\n additional_authorized_imports=[\"pandas\", \"datetime\"],\n managed_agents=[web_agent, code_agent],\n max_print_outputs_length=1000,\n executor_type=\"local\",\n executor_kwargs={\"max_print_outputs_length\": 10_000},\n )\n agent.save(tmp_path)\n\n expected_structure = {\n \"managed_agents\": {\n \"useless\": {\"tools\": {\"files\": [\"final_answer.py\"]}, \"files\": [\"agent.json\", \"prompts.yaml\"]},\n \"web_agent\": {\n \"tools\": {\"files\": [\"final_answer.py\", \"visit_webpage.py\", \"web_search.py\"]},\n \"files\": [\"agent.json\", \"prompts.yaml\"],\n },\n },\n \"tools\": {\"files\": [\"final_answer.py\"]},\n \"files\": [\"app.py\", \"requirements.txt\", \"agent.json\", \"prompts.yaml\"],\n }\n\n def verify_structure(current_path: Path, structure: dict):\n for dir_name, contents in structure.items():\n if dir_name != \"files\":\n # For directories, verify they exist and recurse into them\n dir_path = current_path / dir_name\n assert dir_path.exists(), f\"Directory {dir_path} does not exist\"\n assert dir_path.is_dir(), f\"{dir_path} is not a directory\"\n verify_structure(dir_path, contents)\n else:\n # For files, verify each exists in the current path\n for file_name in contents:\n file_path = current_path / file_name\n assert file_path.exists(), f\"File {file_path} does not exist\"\n assert file_path.is_file(), f\"{file_path} is not a file\"\n\n verify_structure(tmp_path, expected_structure)\n\n # Test that re-loaded agents work as expected.\n agent2 = CodeAgent.from_folder(tmp_path, planning_interval=5)\n assert agent2.planning_interval == 5 # Check that kwargs are used\n assert set(agent2.authorized_imports) == set([\"pandas\", \"datetime\"] + BASE_BUILTIN_MODULES)\n assert agent2.max_print_outputs_length == 1000\n assert agent2.executor_type == \"local\"\n assert agent2.executor_kwargs == {\"max_print_outputs_length\": 10_000}\n assert (\n agent2.managed_agents[\"web_agent\"].tools[\"web_search\"].max_results == 10\n ) # For now tool init parameters are forgotten\n assert agent2.model.kwargs[\"temperature\"] == pytest.approx(0.5)\n\n def test_multiagents(self):\n class FakeModelMultiagentsManagerAgent(Model):\n model_id = \"fake_model\"\n\n def generate(\n self,\n messages,\n stop_sequences=None,\n tools_to_call_from=None,\n ):\n if tools_to_call_from is not None:\n if len(messages) < 3:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"search_agent\",\n arguments=\"Who is the current US president?\",\n ),\n )\n ],\n )\n else:\n assert \"Report on the current US president\" in str(messages)\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"final_answer\", arguments=\"Final report.\"\n ),\n )\n ],\n )\n else:\n if len(messages) < 3:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: Let's call our search agent.\n\nresult = search_agent(\"Who is the current US president?\")\n\n\"\"\",\n )\n else:\n assert \"Report on the current US president\" in str(messages)\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nThought: Let's return the report.\n\nfinal_answer(\"Final report.\")\n\n\"\"\",\n )\n\n manager_model = FakeModelMultiagentsManagerAgent()\n\n class FakeModelMultiagentsManagedAgent(Model):\n model_id = \"fake_model\"\n\n def generate(\n self,\n messages,\n tools_to_call_from=None,\n stop_sequences=None,\n ):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"Here is the secret content: FLAG1\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"call_0\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"final_answer\",\n arguments=\"Report on the current US president\",\n ),\n )\n ],\n )\n\n managed_model = FakeModelMultiagentsManagedAgent()\n\n web_agent = ToolCallingAgent(\n tools=[],\n model=managed_model,\n max_steps=10,\n name=\"search_agent\",\n description=\"Runs web searches for you. Give it your request as an argument. Make the request as detailed as needed, you can ask for thorough reports\",\n verbosity_level=2,\n )\n\n manager_code_agent = CodeAgent(\n tools=[],\n model=manager_model,\n managed_agents=[web_agent],\n additional_authorized_imports=[\"time\", \"numpy\", \"pandas\"],\n )\n\n report = manager_code_agent.run(\"Fake question.\")\n assert report == \"Final report.\"\n\n manager_toolcalling_agent = ToolCallingAgent(\n tools=[],\n model=manager_model,\n managed_agents=[web_agent],\n )\n\n with web_agent.logger.console.capture() as capture:\n report = manager_toolcalling_agent.run(\"Fake question.\")\n assert report == \"Final report.\"\n assert \"FLAG1\" in capture.get() # Check that managed agent's output is properly logged\n\n # Test that visualization works\n with manager_toolcalling_agent.logger.console.capture() as capture:\n manager_toolcalling_agent.visualize()\n assert \"├──\" in capture.get()\n\n\n@pytest.fixture\ndef prompt_templates():\n return {\n \"system_prompt\": \"This is a test system prompt.\",\n \"managed_agent\": {\"task\": \"Task for {{name}}: {{task}}\", \"report\": \"Report for {{name}}: {{final_answer}}\"},\n \"planning\": {\n \"initial_plan\": \"The plan.\",\n \"update_plan_pre_messages\": \"custom\",\n \"update_plan_post_messages\": \"custom\",\n },\n \"final_answer\": {\"pre_messages\": \"custom\", \"post_messages\": \"custom\"},\n }\n\n\n@pytest.mark.parametrize(\n \"arguments\",\n [\n {},\n {\"arg\": \"bar\"},\n {None: None},\n [1, 2, 3],\n ],\n)\ndef test_tool_calling_agents_raises_tool_call_error_being_invoked_with_wrong_arguments(arguments):\n @tool\n def _sample_tool(prompt: str) -> str:\n \"\"\"Tool that returns same string\n Args:\n prompt: The string to return\n Returns:\n The same string\n \"\"\"\n\n return prompt\n\n agent = ToolCallingAgent(model=FakeToolCallModel(), tools=[_sample_tool])\n with pytest.raises(AgentToolCallError):\n agent.execute_tool_call(_sample_tool.name, arguments)\n\n\ndef test_tool_calling_agents_raises_agent_execution_error_when_tool_raises():\n @tool\n def _sample_tool(_: str) -> float:\n \"\"\"Tool that fails\n\n Args:\n _: The pointless string\n Returns:\n Some number\n \"\"\"\n\n return 1 / 0\n\n agent = ToolCallingAgent(model=FakeToolCallModel(), tools=[_sample_tool])\n with pytest.raises(AgentExecutionError):\n agent.execute_tool_call(_sample_tool.name, \"sample\")\n"
},
{
"path": "tests/test_all_docs.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport ast\nimport os\nimport re\nimport shutil\nimport subprocess\nimport tempfile\nimport traceback\nfrom pathlib import Path\n\nimport pytest\nfrom dotenv import load_dotenv\n\nfrom .utils.markers import require_run_all\n\n\nclass SubprocessCallException(Exception):\n pass\n\n\ndef run_command(command: list[str], return_stdout=False, env=None):\n \"\"\"\n Runs command with subprocess.check_output and returns stdout if requested.\n Properly captures and handles errors during command execution.\n \"\"\"\n for i, c in enumerate(command):\n if isinstance(c, Path):\n command[i] = str(c)\n\n if env is None:\n env = os.environ.copy()\n\n try:\n output = subprocess.check_output(command, stderr=subprocess.STDOUT, env=env)\n if return_stdout:\n if hasattr(output, \"decode\"):\n output = output.decode(\"utf-8\")\n return output\n except subprocess.CalledProcessError as e:\n raise SubprocessCallException(\n f\"Command `{' '.join(command)}` failed with the following error:\\n\\n{e.output.decode()}\"\n ) from e\n\n\nclass DocCodeExtractor:\n \"\"\"Handles extraction and validation of Python code from markdown files.\"\"\"\n\n @staticmethod\n def extract_python_code(content: str) -> list[str]:\n \"\"\"Extract Python code blocks from markdown content.\"\"\"\n pattern = r\"```(?:python|py)\\n(.*?)\\n```\"\n matches = re.finditer(pattern, content, re.DOTALL)\n return [match.group(1).strip() for match in matches]\n\n @staticmethod\n def create_test_script(code_blocks: list[str], tmp_dir: str) -> Path:\n \"\"\"Create a temporary Python script from code blocks.\"\"\"\n combined_code = \"\\n\\n\".join(code_blocks)\n assert len(combined_code) > 0, \"Code is empty!\"\n tmp_file = Path(tmp_dir) / \"test_script.py\"\n\n with open(tmp_file, \"w\", encoding=\"utf-8\") as f:\n f.write(combined_code)\n\n return tmp_file\n\n\n# Skip: slow tests + require API keys\n@require_run_all\nclass TestDocs:\n \"\"\"Test case for documentation code testing.\"\"\"\n\n @classmethod\n def setup_class(cls):\n cls._tmpdir = tempfile.mkdtemp()\n cls.launch_args = [\"python3\"]\n cls.docs_dir = Path(__file__).parent.parent / \"docs\" / \"source\" / \"en\"\n cls.extractor = DocCodeExtractor()\n\n if not cls.docs_dir.exists():\n raise ValueError(f\"Docs directory not found at {cls.docs_dir}\")\n\n load_dotenv()\n\n cls.md_files = list(cls.docs_dir.rglob(\"*.md\")) + list(cls.docs_dir.rglob(\"*.mdx\"))\n if not cls.md_files:\n raise ValueError(f\"No markdown files found in {cls.docs_dir}\")\n\n @classmethod\n def teardown_class(cls):\n shutil.rmtree(cls._tmpdir)\n\n @pytest.mark.timeout(100)\n def test_single_doc(self, doc_path: Path):\n \"\"\"Test a single documentation file.\"\"\"\n with open(doc_path, \"r\", encoding=\"utf-8\") as f:\n content = f.read()\n\n code_blocks = self.extractor.extract_python_code(content)\n excluded_snippets = [\n \"ToolCollection\",\n \"image_generation_tool\", # We don't want to run this expensive operation\n \"from_langchain\", # Langchain is not a dependency\n \"while llm_should_continue(memory):\", # This is pseudo code\n \"ollama_chat/llama3.2\", # Exclude ollama building in guided tour\n \"model = TransformersModel(model_id=model_id)\", # Exclude testing with transformers model\n \"SmolagentsInstrumentor\", # Exclude telemetry since it needs additional installs\n ]\n code_blocks = [\n block\n for block in code_blocks\n if not any(\n [snippet in block for snippet in excluded_snippets]\n ) # Exclude these tools that take longer to run and add dependencies\n ]\n if len(code_blocks) == 0:\n pytest.skip(f\"No Python code blocks found in {doc_path.name}\")\n\n # Validate syntax of each block individually by parsing it\n for i, block in enumerate(code_blocks, 1):\n ast.parse(block)\n\n # Create and execute test script\n print(\"\\n\\nCollected code block:==========\\n\".join(code_blocks))\n try:\n code_blocks = [\n (\n block.replace(\"world!\"\n stop_sequences = [\"\"]\n removed_content = remove_content_after_stop_sequences(content, stop_sequences)\n assert removed_content == \"Hello\"\n\n\ndef test_remove_content_after_stop_sequences_handles_none():\n # Test with None stop sequence\n content = \"Hello world!\"\n removed_content = remove_content_after_stop_sequences(content, None)\n assert removed_content == content\n\n # Test with None content\n removed_content = remove_content_after_stop_sequences(None, [\"\"])\n assert removed_content is None\n\n\n@pytest.mark.parametrize(\n \"convert_images_to_image_urls, expected_clean_message\",\n [\n (\n False,\n dict(\n role=MessageRole.USER,\n content=[\n {\"type\": \"image\", \"image\": \"encoded_image\"},\n {\"type\": \"image\", \"image\": \"second_encoded_image\"},\n ],\n ),\n ),\n (\n True,\n dict(\n role=MessageRole.USER,\n content=[\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,encoded_image\"}},\n {\"type\": \"image_url\", \"image_url\": {\"url\": \"data:image/png;base64,second_encoded_image\"}},\n ],\n ),\n ),\n ],\n)\ndef test_get_clean_message_list_image_encoding(convert_images_to_image_urls, expected_clean_message):\n message = ChatMessage(\n role=MessageRole.USER,\n content=[{\"type\": \"image\", \"image\": b\"image_data\"}, {\"type\": \"image\", \"image\": b\"second_image_data\"}],\n )\n with patch(\"smolagents.models.encode_image_base64\") as mock_encode:\n mock_encode.side_effect = [\"encoded_image\", \"second_encoded_image\"]\n result = get_clean_message_list([message], convert_images_to_image_urls=convert_images_to_image_urls)\n mock_encode.assert_any_call(b\"image_data\")\n mock_encode.assert_any_call(b\"second_image_data\")\n assert len(result) == 1\n assert result[0] == expected_clean_message\n\n\ndef test_get_clean_message_list_flatten_messages_as_text():\n messages = [\n ChatMessage(role=MessageRole.USER, content=[{\"type\": \"text\", \"text\": \"Hello!\"}]),\n ChatMessage(role=MessageRole.USER, content=[{\"type\": \"text\", \"text\": \"How are you?\"}]),\n ]\n result = get_clean_message_list(messages, flatten_messages_as_text=True)\n assert len(result) == 1\n assert result[0][\"role\"] == \"user\"\n assert result[0][\"content\"] == \"Hello!\\nHow are you?\"\n\n\n@pytest.mark.parametrize(\n \"model_class, model_kwargs, patching, expected_flatten_messages_as_text\",\n [\n (AzureOpenAIModel, {}, (\"openai.AzureOpenAI\", {}), False),\n (InferenceClientModel, {}, (\"huggingface_hub.InferenceClient\", {}), False),\n (LiteLLMModel, {}, None, False),\n (LiteLLMModel, {\"model_id\": \"ollama\"}, None, True),\n (LiteLLMModel, {\"model_id\": \"groq\"}, None, True),\n (LiteLLMModel, {\"model_id\": \"cerebras\"}, None, True),\n (MLXModel, {}, (\"mlx_lm.load\", {\"return_value\": (MagicMock(), MagicMock())}), True),\n (OpenAIModel, {}, (\"openai.OpenAI\", {}), False),\n (OpenAIModel, {\"flatten_messages_as_text\": True}, (\"openai.OpenAI\", {}), True),\n (\n TransformersModel,\n {},\n [\n (\n \"transformers.AutoModelForImageTextToText.from_pretrained\",\n {\"side_effect\": ValueError(\"Unrecognized configuration class\")},\n ),\n (\"transformers.AutoModelForCausalLM.from_pretrained\", {}),\n (\"transformers.AutoTokenizer.from_pretrained\", {}),\n ],\n True,\n ),\n (\n TransformersModel,\n {},\n [\n (\"transformers.AutoModelForImageTextToText.from_pretrained\", {}),\n (\"transformers.AutoProcessor.from_pretrained\", {}),\n ],\n False,\n ),\n ],\n)\ndef test_flatten_messages_as_text_for_all_models(\n model_class, model_kwargs, patching, expected_flatten_messages_as_text\n):\n with ExitStack() as stack:\n if isinstance(patching, list):\n for target, kwargs in patching:\n stack.enter_context(patch(target, **kwargs))\n elif patching:\n target, kwargs = patching\n stack.enter_context(patch(target, **kwargs))\n\n model = model_class(**{\"model_id\": \"test-model\", **model_kwargs})\n assert model.flatten_messages_as_text is expected_flatten_messages_as_text, f\"{model_class.__name__} failed\"\n\n\n@pytest.mark.parametrize(\n \"model_id,expected\",\n [\n # Unsupported base models\n (\"o3\", False),\n (\"o4-mini\", False),\n (\"gpt-5.1\", False),\n (\"gpt-5.2\", False),\n (\"gpt-5\", False),\n (\"gpt-5-mini\", False),\n (\"gpt-5-nano\", False),\n (\"gpt-5-turbo\", False),\n (\"gpt-5.2-mini\", False),\n (\"grok-4\", False),\n (\"grok-4-latest\", False),\n (\"grok-4.1\", False),\n (\"grok-3\", False),\n (\"grok-3-mini\", False),\n (\"grok-code-fast-1\", False),\n # Unsupported versioned models\n (\"o4-mini-2025-04-16\", False),\n (\"gpt-5-2025-01-01\", False),\n # Unsupported models with path prefixes\n (\"openai/o3\", False),\n (\"openai/o4-mini\", False),\n (\"openai/o3-2025-04-16\", False),\n (\"openai/o4-mini-2025-04-16\", False),\n (\"openai/gpt-5.2\", False),\n (\"openai/gpt-5.2-mini\", False),\n (\"openai/gpt-5.2-2025-01-01\", False),\n (\"oci/xai.grok-4\", False),\n (\"oci/xai.grok-3-mini\", False),\n # Supported models\n (\"o3-mini\", True),\n (\"gpt-4\", True),\n (\"claude-3-5-sonnet\", True),\n (\"mistral-large\", True),\n # Supported models with path prefixes\n (\"openai/gpt-4\", True),\n (\"anthropic/claude-3-5-sonnet\", True),\n (\"anthropic/claude-opus-4-5\", True),\n (\"mistralai/mistral-large\", True),\n # Edge cases\n (\"\", True), # Empty string doesn't match pattern\n (\"o3x\", True), # Not exactly o3\n (\"o4x\", True), # Not exactly o4\n (\"gpt-5x\", False),\n (\"gpt-50\", False),\n (\"o3_mini\", True), # Not o3-mini format\n (\"prefix-o3\", True), # o3 not at start\n ],\n)\ndef test_supports_stop_parameter(model_id, expected):\n \"\"\"Test the supports_stop_parameter function with various model IDs\"\"\"\n assert supports_stop_parameter(model_id) == expected, f\"Failed for model_id: {model_id}\"\n\n\nclass TestGetToolCallFromText:\n @pytest.fixture(autouse=True)\n def mock_uuid4(self):\n with patch(\"uuid.uuid4\", return_value=\"test-uuid\"):\n yield\n\n def test_get_tool_call_from_text_basic(self):\n text = '{\"name\": \"weather_tool\", \"arguments\": \"New York\"}'\n result = get_tool_call_from_text(text, \"name\", \"arguments\")\n assert isinstance(result, ChatMessageToolCall)\n assert result.id == \"test-uuid\"\n assert result.type == \"function\"\n assert result.function.name == \"weather_tool\"\n assert result.function.arguments == \"New York\"\n\n def test_get_tool_call_from_text_name_key_missing(self):\n text = '{\"action\": \"weather_tool\", \"arguments\": \"New York\"}'\n with pytest.raises(ValueError) as exc_info:\n get_tool_call_from_text(text, \"name\", \"arguments\")\n error_msg = str(exc_info.value)\n assert \"Tool call needs to have a key 'name'\" in error_msg\n assert \"'action', 'arguments'\" in error_msg\n\n def test_get_tool_call_from_text_json_object_args(self):\n text = '{\"name\": \"weather_tool\", \"arguments\": {\"city\": \"New York\"}}'\n result = get_tool_call_from_text(text, \"name\", \"arguments\")\n assert result.function.arguments == {\"city\": \"New York\"}\n\n def test_get_tool_call_from_text_json_string_args(self):\n text = '{\"name\": \"weather_tool\", \"arguments\": \"{\\\\\"city\\\\\": \\\\\"New York\\\\\"}\"}'\n result = get_tool_call_from_text(text, \"name\", \"arguments\")\n assert result.function.arguments == {\"city\": \"New York\"}\n\n def test_get_tool_call_from_text_missing_args(self):\n text = '{\"name\": \"weather_tool\"}'\n result = get_tool_call_from_text(text, \"name\", \"arguments\")\n assert result.function.arguments is None\n\n def test_get_tool_call_from_text_custom_keys(self):\n text = '{\"tool\": \"weather_tool\", \"params\": \"New York\"}'\n result = get_tool_call_from_text(text, \"tool\", \"params\")\n assert result.function.name == \"weather_tool\"\n assert result.function.arguments == \"New York\"\n\n def test_get_tool_call_from_text_numeric_args(self):\n text = '{\"name\": \"calculator\", \"arguments\": 42}'\n result = get_tool_call_from_text(text, \"name\", \"arguments\")\n assert result.function.name == \"calculator\"\n assert result.function.arguments == 42\n\n\n@pytest.mark.parametrize(\n \"model_class,model_id\",\n [\n (LiteLLMModel, \"gpt-4o-mini\"),\n (OpenAIModel, \"gpt-4o-mini\"),\n ],\n)\ndef test_tool_calls_json_serialization(model_class, model_id):\n \"\"\"Test that tool_calls from various API models (Pydantic, dataclass, dict) are properly converted to dataclasses and can be JSON serialized.\n This tests the horizontal fix that ensures all models (LiteLLM, OpenAI, InferenceClient, AmazonBedrock)\n properly convert tool_calls to dataclasses regardless of the source format (Pydantic models, dataclasses, or dicts).\n \"\"\"\n tool_arguments = \"test_result\"\n messages = [\n ChatMessage(\n role=MessageRole.USER,\n content=[\n {\n \"type\": \"text\",\n \"text\": \"Hello! Please return the final answer 'hi there' in a tool call\",\n }\n ],\n ),\n ]\n\n if model_class == OpenAIModel:\n from openai.types.chat.chat_completion import ChatCompletion, Choice\n from openai.types.chat.chat_completion_message import ChatCompletionMessage\n from openai.types.chat.chat_completion_message_tool_call import ChatCompletionMessageToolCall, Function\n from openai.types.completion_usage import CompletionUsage\n\n response = ChatCompletion(\n id=\"chatcmpl-test\",\n created=0,\n model=\"gpt-4o-mini-2024-07-18\",\n object=\"chat.completion\",\n choices=[\n Choice(\n finish_reason=\"tool_calls\",\n index=0,\n logprobs=None,\n message=ChatCompletionMessage(\n role=\"assistant\",\n content=None,\n tool_calls=[\n ChatCompletionMessageToolCall(\n id=\"call_test\",\n type=\"function\",\n function=Function(name=\"final_answer\", arguments=tool_arguments),\n )\n ],\n ),\n )\n ],\n usage=CompletionUsage(prompt_tokens=69, completion_tokens=15, total_tokens=84),\n )\n client = MagicMock()\n client.chat.completions.create.return_value = response\n create_call = client.chat.completions.create\n patch_target = \"smolagents.models.OpenAIModel.create_client\"\n elif model_class == LiteLLMModel:\n from litellm.types.utils import ChatCompletionMessageToolCall, Choices, Function, Message, ModelResponse, Usage\n\n response = ModelResponse(\n id=\"chatcmpl-test\",\n created=0,\n object=\"chat.completion\",\n choices=[\n Choices(\n finish_reason=\"tool_calls\",\n index=0,\n message=Message(\n role=\"assistant\",\n content=None,\n tool_calls=[\n ChatCompletionMessageToolCall(\n id=\"call_test\",\n type=\"function\",\n function=Function(name=\"final_answer\", arguments=tool_arguments),\n )\n ],\n function_call=None,\n provider_specific_fields={\"refusal\": None, \"annotations\": []},\n ),\n )\n ],\n usage=Usage(prompt_tokens=69, completion_tokens=15, total_tokens=84),\n model=\"gpt-4o-mini-2024-07-18\",\n )\n client = MagicMock()\n client.completion.return_value = response\n create_call = client.completion\n patch_target = \"smolagents.models.LiteLLMModel.create_client\"\n else:\n raise ValueError(f\"Unexpected model class: {model_class}\")\n\n with patch(patch_target, return_value=client):\n model = model_class(model_id=model_id)\n result = model.generate(messages, tools_to_call_from=[FinalAnswerTool()])\n\n assert create_call.call_count == 1\n\n # Verify tool_calls are converted to dataclasses\n assert result.tool_calls is not None\n assert len(result.tool_calls) > 0\n assert isinstance(result.tool_calls[0], ChatMessageToolCall)\n\n # The critical test: verify JSON serialization works\n json_str = result.model_dump_json()\n data = json.loads(json_str)\n assert \"tool_calls\" in data\n assert len(data[\"tool_calls\"]) > 0\n assert data[\"tool_calls\"][0][\"function\"][\"name\"] == \"final_answer\"\n assert data[\"tool_calls\"][0][\"function\"][\"arguments\"] == \"test_result\"\n"
},
{
"path": "tests/test_monitoring.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\nimport unittest\n\nimport PIL.Image\nimport pytest\nfrom rich.console import Console\n\nfrom smolagents import (\n CodeAgent,\n ToolCallingAgent,\n stream_to_gradio,\n)\nfrom smolagents.memory import ActionStep, AgentMemory\nfrom smolagents.models import (\n ChatMessage,\n ChatMessageToolCall,\n ChatMessageToolCallFunction,\n MessageRole,\n Model,\n)\nfrom smolagents.monitoring import AgentLogger, TokenUsage\n\n\nclass FakeLLMModel(Model):\n def generate(self, prompt, tools_to_call_from=None, **kwargs):\n if tools_to_call_from is not None:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"I will call the final_answer tool.\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"fake_id\",\n type=\"function\",\n function=ChatMessageToolCallFunction(\n name=\"final_answer\", arguments={\"answer\": \"This is the final answer.\"}\n ),\n )\n ],\n token_usage=TokenUsage(input_tokens=10, output_tokens=20),\n )\n else:\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"\"\"\nfinal_answer('This is the final answer.')\n\"\"\",\n token_usage=TokenUsage(input_tokens=10, output_tokens=20),\n )\n\n\nclass MonitoringTester(unittest.TestCase):\n def test_code_agent_metrics_max_steps(self):\n class FakeLLMModelMalformedAnswer(Model):\n def generate(self, prompt, **kwargs):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"Malformed answer\",\n token_usage=TokenUsage(input_tokens=10, output_tokens=20),\n )\n\n agent = CodeAgent(\n tools=[],\n model=FakeLLMModelMalformedAnswer(),\n max_steps=1,\n )\n\n agent.run(\"Fake task\")\n\n self.assertEqual(agent.monitor.total_input_token_count, 20)\n self.assertEqual(agent.monitor.total_output_token_count, 40)\n\n def test_code_agent_metrics_generation_error(self):\n class FakeLLMModelGenerationException(Model):\n def generate(self, prompt, **kwargs):\n raise Exception(\"Cannot generate\")\n\n agent = CodeAgent(\n tools=[],\n model=FakeLLMModelGenerationException(),\n max_steps=1,\n )\n with pytest.raises(Exception) as e:\n agent.run(\"Fake task\")\n assert \"Cannot generate\" in str(e.value)\n\n def test_streaming_agent_text_output(self):\n agent = CodeAgent(\n tools=[],\n model=FakeLLMModel(),\n max_steps=1,\n planning_interval=2,\n )\n\n # Use stream_to_gradio to capture the output\n outputs = list(stream_to_gradio(agent, task=\"Test task\"))\n\n self.assertEqual(len(outputs), 11)\n plan_message = outputs[1]\n self.assertEqual(plan_message.role, \"assistant\")\n self.assertIn(\"\", plan_message.content)\n final_message = outputs[-1]\n self.assertEqual(final_message.role, \"assistant\")\n self.assertIn(\"This is the final answer.\", final_message.content)\n\n def test_streaming_agent_image_output(self):\n class FakeLLMModelImage(Model):\n def generate(self, prompt, **kwargs):\n return ChatMessage(\n role=MessageRole.ASSISTANT,\n content=\"I will call the final_answer tool.\",\n tool_calls=[\n ChatMessageToolCall(\n id=\"fake_id\",\n type=\"function\",\n function=ChatMessageToolCallFunction(name=\"final_answer\", arguments={\"answer\": \"image\"}),\n )\n ],\n )\n\n agent = ToolCallingAgent(\n tools=[],\n model=FakeLLMModelImage(),\n max_steps=1,\n verbosity_level=100,\n )\n\n # Use stream_to_gradio to capture the output\n outputs = list(\n stream_to_gradio(\n agent,\n task=\"Test task\",\n additional_args=dict(image=PIL.Image.new(\"RGB\", (100, 100))),\n )\n )\n\n self.assertEqual(len(outputs), 7)\n final_message = outputs[-1]\n self.assertEqual(final_message.role, \"assistant\")\n self.assertIsInstance(final_message.content, dict)\n self.assertEqual(final_message.content[\"mime_type\"], \"image/png\")\n\n def test_streaming_with_agent_error(self):\n class DummyModel(Model):\n def generate(self, prompt, **kwargs):\n return ChatMessage(role=MessageRole.ASSISTANT, content=\"Malformed call\")\n\n agent = CodeAgent(\n tools=[],\n model=DummyModel(),\n max_steps=1,\n )\n\n # Use stream_to_gradio to capture the output\n outputs = list(stream_to_gradio(agent, task=\"Test task\"))\n\n self.assertEqual(len(outputs), 11)\n final_message = outputs[-1]\n self.assertEqual(final_message.role, \"assistant\")\n self.assertIn(\"Malformed call\", final_message.content)\n\n\n@pytest.mark.parametrize(\"agent_class\", [CodeAgent, ToolCallingAgent])\ndef test_code_agent_metrics(agent_class):\n agent = agent_class(\n tools=[],\n model=FakeLLMModel(),\n max_steps=1,\n )\n agent.run(\"Fake task\")\n\n assert agent.monitor.total_input_token_count == 10\n assert agent.monitor.total_output_token_count == 20\n\n\nclass ReplayTester(unittest.TestCase):\n def test_replay_with_chatmessage(self):\n \"\"\"Regression test for dict(message) to message.dict() fix\"\"\"\n logger = AgentLogger()\n memory = AgentMemory(system_prompt=\"test\")\n step = ActionStep(step_number=1, timing=0)\n step.model_input_messages = [ChatMessage(role=MessageRole.USER, content=\"Hello\")]\n memory.steps.append(step)\n\n try:\n memory.replay(logger, detailed=True)\n except TypeError as e:\n self.fail(f\"Replay raised an error: {e}\")\n\n\nclass AgentLoggerLogTaskTester(unittest.TestCase):\n def test_logger_log_task_does_not_crash_on_stray_markup_or_control_chars(self):\n \"\"\"\n Rich Panels parse `title`/`subtitle` as markup when passed as strings.\n `AgentLogger.log_task()` must be resilient to arbitrary content/subtitle strings\n (e.g. tool logs, binary-ish payloads, or stray bracket sequences).\n \"\"\"\n console = Console(record=True, width=120, highlight=False)\n logger = AgentLogger(console=console)\n\n # These inputs would crash Rich markup parsing if passed through as markup strings.\n content = b\"hello [/bad]\\x00\\x1b world [bold]bold[/bold]\"\n subtitle = \"sub[/bad]title\"\n\n logger.log_task(content=content, subtitle=subtitle, title=None)\n\n rendered = console.export_text()\n self.assertIn(\"hello [/bad]\", rendered)\n # Control chars are made visible as escape sequences.\n self.assertIn(\"\\\\x00\", rendered)\n self.assertIn(\"\\\\x1b\", rendered)\n self.assertIn(\"sub[/bad]title\", rendered)\n self.assertIn(\"bold\", rendered)\n\n def test_logger_log_task_accepts_non_string_payloads(self):\n console = Console(record=True, width=120, highlight=False)\n logger = AgentLogger(console=console)\n\n logger.log_task(content={\"k\": [\"v\", 1]}, subtitle={\"also\": \"dict\"}, title=\"Run\")\n rendered = console.export_text()\n self.assertIn(\"k\", rendered)\n self.assertIn(\"also\", rendered)\n"
},
{
"path": "tests/test_remote_executors.py",
"content": "import importlib\nimport io\nfrom textwrap import dedent\nfrom unittest.mock import MagicMock, patch\n\nimport docker\nimport PIL.Image\nimport pytest\nfrom rich.console import Console\n\nfrom smolagents.default_tools import FinalAnswerTool, WikipediaSearchTool\nfrom smolagents.local_python_executor import CodeOutput\nfrom smolagents.monitoring import AgentLogger, LogLevel\nfrom smolagents.remote_executors import (\n BlaxelExecutor,\n DockerExecutor,\n E2BExecutor,\n ModalExecutor,\n RemotePythonExecutor,\n WasmExecutor,\n)\nfrom smolagents.serialization import SerializationError\nfrom smolagents.utils import AgentError\n\nfrom .utils.markers import require_run_all\n\n\nclass TestRemotePythonExecutor:\n def test_send_tools_empty_tools(self):\n executor = RemotePythonExecutor(additional_imports=[], logger=MagicMock())\n executor.run_code_raise_errors = MagicMock()\n executor.send_tools({})\n assert executor.run_code_raise_errors.call_count == 1\n # No new packages should be installed\n assert \"!pip install\" not in executor.run_code_raise_errors.call_args.args[0]\n\n def test_send_variables_with_empty_dict_is_noop(self):\n executor = RemotePythonExecutor(additional_imports=[], logger=MagicMock())\n executor.run_code_raise_errors = MagicMock()\n executor.send_variables({})\n assert executor.run_code_raise_errors.call_count == 0\n\n def test_send_variables_non_empty_generates_executable_deserializer_code(self):\n executor = RemotePythonExecutor(additional_imports=[], logger=MagicMock(), allow_pickle=False)\n executor.run_code_raise_errors = MagicMock()\n\n variables = {\n \"counter\": 1,\n \"tags\": (\"a\", \"b\"),\n \"blob\": b\"binary\",\n }\n executor.send_variables(variables)\n\n sent_code = executor.run_code_raise_errors.call_args.args[0]\n remote_scope = {}\n exec(sent_code, remote_scope, remote_scope)\n\n assert remote_scope[\"counter\"] == 1\n assert remote_scope[\"tags\"] == (\"a\", \"b\")\n assert remote_scope[\"blob\"] == b\"binary\"\n\n def test_send_variables_allow_pickle_handles_prefixed_payload(self):\n executor = RemotePythonExecutor(additional_imports=[], logger=MagicMock(), allow_pickle=True)\n executor.run_code_raise_errors = MagicMock()\n\n variables = {\"error\": ValueError(\"boom\")}\n executor.send_variables(variables)\n\n sent_code = executor.run_code_raise_errors.call_args.args[0]\n remote_scope = {}\n exec(sent_code, remote_scope, remote_scope)\n\n assert isinstance(remote_scope[\"error\"], ValueError)\n assert str(remote_scope[\"error\"]) == \"boom\"\n\n def test_deserialize_final_answer_rejects_unprefixed_payload(self):\n with pytest.raises(SerializationError, match=\"Unknown final answer format\"):\n RemotePythonExecutor._deserialize_final_answer(\"legacy-unprefixed-payload\", allow_pickle=True)\n\n @require_run_all\n def test_send_tools_with_default_wikipedia_search_tool(self):\n tool = WikipediaSearchTool()\n executor = RemotePythonExecutor(additional_imports=[], logger=MagicMock())\n executor.run_code_raise_errors = MagicMock()\n executor.send_tools({\"wikipedia_search\": tool})\n assert executor.run_code_raise_errors.call_count == 2\n assert \"!pip install wikipedia-api\" == executor.run_code_raise_errors.call_args_list[0].args[0]\n assert \"class WikipediaSearchTool(Tool)\" in executor.run_code_raise_errors.call_args_list[1].args[0]\n\n\nclass TestE2BExecutorUnit:\n def test_e2b_executor_instantiation(self):\n logger = MagicMock()\n with patch(\"e2b_code_interpreter.Sandbox\") as mock_sandbox:\n mock_sandbox.return_value.commands.run.return_value.error = None\n mock_sandbox.return_value.run_code.return_value.error = None\n # Also set up v2 path in case Sandbox.create is used\n mock_sandbox.create.return_value.commands.run.return_value.error = None\n mock_sandbox.create.return_value.run_code.return_value.error = None\n executor = E2BExecutor(\n additional_imports=[], logger=logger, api_key=\"dummy-api-key\", template=\"dummy-template-id\", timeout=60\n )\n assert isinstance(executor, E2BExecutor)\n assert executor.logger == logger\n # Support both e2b v1 (Sandbox(...)) and v2 (Sandbox.create(...))\n if mock_sandbox.create.called:\n sandbox_obj = mock_sandbox.create.return_value\n called_ctor = mock_sandbox.create\n else:\n sandbox_obj = mock_sandbox.return_value\n called_ctor = mock_sandbox\n assert executor.sandbox == sandbox_obj\n assert called_ctor.call_count == 1\n assert called_ctor.call_args.kwargs == {\n \"api_key\": \"dummy-api-key\",\n \"template\": \"dummy-template-id\",\n \"timeout\": 60,\n }\n\n def test_cleanup(self):\n \"\"\"Test that the cleanup method properly shuts down the sandbox\"\"\"\n logger = MagicMock()\n with patch(\"e2b_code_interpreter.Sandbox\") as mock_sandbox:\n # Setup mock\n mock_sandbox.return_value.kill = MagicMock()\n # Also set up v2 path in case Sandbox.create is used\n mock_sandbox.create.return_value.kill = MagicMock()\n\n # Create executor\n executor = E2BExecutor(additional_imports=[], logger=logger, api_key=\"dummy-api-key\")\n\n # Call cleanup\n executor.cleanup()\n\n # Verify sandbox was killed\n if mock_sandbox.create.called:\n mock_sandbox.create.return_value.kill.assert_called_once()\n else:\n mock_sandbox.return_value.kill.assert_called_once()\n assert logger.log.call_count >= 2 # Should log start and completion messages\n\n\n@pytest.fixture\ndef e2b_executor():\n executor = E2BExecutor(\n additional_imports=[\"pillow\", \"numpy\"],\n logger=AgentLogger(LogLevel.INFO, Console(force_terminal=False, file=io.StringIO())),\n )\n yield executor\n executor.cleanup()\n\n\n@require_run_all\nclass TestE2BExecutorIntegration:\n @pytest.fixture(autouse=True)\n def set_executor(self, e2b_executor):\n self.executor = e2b_executor\n\n @pytest.mark.parametrize(\n \"code_action, expected_result\",\n [\n (\n dedent('''\n final_answer(\"\"\"This is\n a multiline\n final answer\"\"\")\n '''),\n \"This is\\na multiline\\nfinal answer\",\n ),\n (\n dedent(\"\"\"\n text = '''Text containing\n final_answer(5)\n '''\n final_answer(text)\n \"\"\"),\n \"Text containing\\nfinal_answer(5)\\n\",\n ),\n (\n dedent(\"\"\"\n num = 2\n if num == 1:\n final_answer(\"One\")\n elif num == 2:\n final_answer(\"Two\")\n \"\"\"),\n \"Two\",\n ),\n ],\n )\n def test_final_answer_patterns(self, code_action, expected_result):\n self.executor.send_tools({\"final_answer\": FinalAnswerTool()})\n code_output = self.executor(code_action)\n assert code_output.is_final_answer is True\n assert code_output.output == expected_result\n\n def test_custom_final_answer(self):\n class CustomFinalAnswerTool(FinalAnswerTool):\n def forward(self, answer: str) -> str:\n return \"CUSTOM\" + answer\n\n self.executor.send_tools({\"final_answer\": CustomFinalAnswerTool()})\n code_action = dedent(\"\"\"\n final_answer(answer=\"_answer\")\n \"\"\")\n code_output = self.executor(code_action)\n assert code_output.is_final_answer is True\n assert code_output.output == \"CUSTOM_answer\"\n\n def test_custom_final_answer_with_custom_inputs(self):\n class CustomFinalAnswerToolWithCustomInputs(FinalAnswerTool):\n inputs = {\n \"answer1\": {\"type\": \"string\", \"description\": \"First part of the answer.\"},\n \"answer2\": {\"type\": \"string\", \"description\": \"Second part of the answer.\"},\n }\n\n def forward(self, answer1: str, answer2: str) -> str:\n return answer1 + \"CUSTOM\" + answer2\n\n self.executor.send_tools({\"final_answer\": CustomFinalAnswerToolWithCustomInputs()})\n code_action = dedent(\"\"\"\n final_answer(\n answer1=\"answer1_\",\n answer2=\"_answer2\"\n )\n \"\"\")\n code_output = self.executor(code_action)\n assert code_output.is_final_answer is True\n assert code_output.output == \"answer1_CUSTOM_answer2\"\n\n\nclass TestDockerExecutorUnit:\n def test_cleanup(self):\n \"\"\"Test that cleanup properly stops and removes the container\"\"\"\n logger = MagicMock()\n with (\n patch(\"docker.from_env\") as mock_docker_client,\n patch(\"requests.get\") as mock_get,\n patch(\"requests.post\") as mock_post,\n patch(\"websocket.create_connection\"),\n ):\n # Setup mocks\n mock_container = MagicMock()\n mock_container.status = \"running\"\n mock_container.short_id = \"test123\"\n\n mock_docker_client.return_value.containers.run.return_value = mock_container\n mock_docker_client.return_value.images.get.return_value = MagicMock()\n\n mock_get.return_value.status_code = 200\n mock_post.return_value.status_code = 201\n mock_post.return_value.json.return_value = {\"id\": \"test-kernel-id\"}\n\n # Create executor\n executor = DockerExecutor(additional_imports=[], logger=logger, build_new_image=False)\n\n # Call cleanup\n executor.cleanup()\n\n # Verify container was stopped and removed\n mock_container.stop.assert_called_once()\n mock_container.remove.assert_called_once()\n\n\nclass CommonDockerExecutorIntegration:\n @pytest.fixture(autouse=True)\n def set_executor(self, custom_executor):\n self.executor = custom_executor\n\n def test_state_persistence(self):\n \"\"\"Test that variables and imports form one snippet persist in the next\"\"\"\n code_action = \"import numpy as np; a = 2\"\n self.executor(code_action)\n\n code_action = \"print(np.sqrt(a))\"\n code_output = self.executor(code_action)\n assert \"1.41421\" in code_output.logs\n\n def test_execute_output(self):\n \"\"\"Test execution that returns a string\"\"\"\n self.executor.send_tools({\"final_answer\": FinalAnswerTool()})\n code_action = 'final_answer(\"This is the final answer\")'\n code_output = self.executor(code_action)\n assert code_output.output == \"This is the final answer\", \"Result should be 'This is the final answer'\"\n\n def test_execute_multiline_output(self):\n \"\"\"Test execution that returns a string\"\"\"\n self.executor.send_tools({\"final_answer\": FinalAnswerTool()})\n code_action = 'result = \"This is the final answer\"\\nfinal_answer(result)'\n code_output = self.executor(code_action)\n assert code_output.output == \"This is the final answer\", \"Result should be 'This is the final answer'\"\n\n def test_execute_image_output(self):\n \"\"\"Test execution that returns a base64 image\"\"\"\n self.executor.send_tools({\"final_answer\": FinalAnswerTool()})\n code_action = dedent(\"\"\"\n import base64\n from PIL import Image\n from io import BytesIO\n image = Image.new(\"RGB\", (10, 10), (255, 0, 0))\n final_answer(image)\n \"\"\")\n code_output = self.executor(code_action)\n assert isinstance(code_output.output, PIL.Image.Image), \"Result should be a PIL Image\"\n\n def test_syntax_error_handling(self):\n \"\"\"Test handling of syntax errors\"\"\"\n code_action = 'print(\"Missing Parenthesis' # Syntax error\n with pytest.raises(AgentError) as exception_info:\n self.executor(code_action)\n assert \"SyntaxError\" in str(exception_info.value), \"Should raise a syntax error\"\n\n @pytest.mark.parametrize(\n \"code_action, expected_result\",\n [\n (\n dedent('''\n final_answer(\"\"\"This is\n a multiline\n final answer\"\"\")\n '''),\n \"This is\\na multiline\\nfinal answer\",\n ),\n (\n dedent(\"\"\"\n text = '''Text containing\n final_answer(5)\n '''\n final_answer(text)\n \"\"\"),\n \"Text containing\\nfinal_answer(5)\\n\",\n ),\n (\n dedent(\"\"\"\n num = 2\n if num == 1:\n final_answer(\"One\")\n elif num == 2:\n final_answer(\"Two\")\n \"\"\"),\n \"Two\",\n ),\n ],\n )\n def test_final_answer_patterns(self, code_action, expected_result):\n self.executor.send_tools({\"final_answer\": FinalAnswerTool()})\n code_output = self.executor(code_action)\n assert code_output.is_final_answer is True\n assert code_output.output == expected_result\n\n def test_custom_final_answer(self):\n class CustomFinalAnswerTool(FinalAnswerTool):\n def forward(self, answer: str) -> str:\n return \"CUSTOM\" + answer\n\n self.executor.send_tools({\"final_answer\": CustomFinalAnswerTool()})\n code_action = dedent(\"\"\"\n final_answer(answer=\"_answer\")\n \"\"\")\n code_output = self.executor(code_action)\n assert code_output.is_final_answer is True\n assert code_output.output == \"CUSTOM_answer\"\n\n def test_custom_final_answer_with_custom_inputs(self):\n class CustomFinalAnswerToolWithCustomInputs(FinalAnswerTool):\n inputs = {\n \"answer1\": {\"type\": \"string\", \"description\": \"First part of the answer.\"},\n \"answer2\": {\"type\": \"string\", \"description\": \"Second part of the answer.\"},\n }\n\n def forward(self, answer1: str, answer2: str) -> str:\n return answer1 + \"CUSTOM\" + answer2\n\n self.executor.send_tools({\"final_answer\": CustomFinalAnswerToolWithCustomInputs()})\n code_action = dedent(\"\"\"\n final_answer(\n answer1=\"answer1_\",\n answer2=\"_answer2\"\n )\n \"\"\")\n code_output = self.executor(code_action)\n assert code_output.is_final_answer is True\n assert code_output.output == \"answer1_CUSTOM_answer2\"\n\n\n@require_run_all\nclass TestDockerExecutorIntegration(CommonDockerExecutorIntegration):\n @pytest.fixture\n def custom_executor(self):\n executor = DockerExecutor(\n additional_imports=[\"pillow\", \"numpy\"],\n logger=AgentLogger(LogLevel.INFO, Console(force_terminal=False, file=io.StringIO())),\n )\n yield executor\n executor.delete()\n\n def test_initialization(self):\n \"\"\"Check if DockerExecutor initializes without errors\"\"\"\n assert self.executor.container is not None, \"Container should be initialized\"\n\n def test_cleanup_on_deletion(self):\n \"\"\"Test if Docker container stops and removes on deletion\"\"\"\n container_id = self.executor.container.id\n self.executor.delete() # Trigger cleanup\n\n client = docker.from_env()\n containers = [c.id for c in client.containers.list(all=True)]\n assert container_id not in containers, \"Container should be removed\"\n\n\n@require_run_all\nclass TestModalExecutorIntegration(CommonDockerExecutorIntegration):\n @pytest.fixture\n def custom_executor(self):\n executor = ModalExecutor(\n additional_imports=[\"pillow\", \"numpy\"],\n logger=AgentLogger(LogLevel.INFO, Console(force_terminal=False, file=io.StringIO())),\n )\n yield executor\n executor.delete()\n\n\nclass TestModalExecutorUnit:\n @patch(\"smolagents.remote_executors._websocket_run_code_raise_errors\")\n @patch(\"requests.post\")\n @patch(\"requests.get\")\n @patch(\"websocket.create_connection\")\n @patch(\"modal.App.lookup\")\n @patch(\"modal.Sandbox.create\")\n def test_sandbox_lifecycle(\n self, mock_sandbox_create, mock_app_lookup, mock_create_connection, mock_get, mock_post, mock_run_code_raises\n ):\n \"\"\"Test that sandbox is created with the correct kwargs and cleaned up correctly.\"\"\"\n modal = pytest.importorskip(\"modal\")\n port = 8889\n\n logger = MagicMock()\n mock_sandbox = MagicMock()\n tunnel_mock = MagicMock()\n tunnel_mock.host = \"r4234.modal.host\"\n mock_sandbox.tunnels.return_value = {port: tunnel_mock}\n\n mock_get.return_value.status_code = 200\n mock_post.return_value.status_code = 201\n mock_post.return_value.json.return_value = {\"id\": \"test-kernel-id\"}\n mock_run_code_raises.return_value = CodeOutput(output=\"3\", logs=\"\", is_final_answer=False)\n mock_sandbox_create.return_value = mock_sandbox\n\n executor = ModalExecutor(\n additional_imports=[],\n logger=logger,\n app_name=\"my-custom-app-name\",\n port=port,\n create_kwargs={\n \"secrets\": [modal.Secret.from_dict({\"MY_SECRET\": \"ABC\"})],\n \"timeout\": 100,\n \"cpu\": 2,\n },\n )\n\n create_call = mock_sandbox_create.mock_calls[0]\n assert create_call.args == (\n \"jupyter\",\n \"kernelgateway\",\n \"--KernelGatewayApp.ip=0.0.0.0\",\n f\"--KernelGatewayApp.port={port}\",\n )\n assert create_call.kwargs[\"timeout\"] == 100\n assert create_call.kwargs[\"cpu\"] == 2\n assert len(create_call.kwargs[\"secrets\"]) == 2\n mock_app_lookup.assert_called_with(\"my-custom-app-name\", create_if_missing=True)\n\n executor.run_code_raise_errors(\"1 + 2\")\n executor.cleanup()\n mock_sandbox.terminate.assert_called()\n\n\nclass TestWasmExecutorUnit:\n def test_wasm_executor_instantiation(self):\n logger = MagicMock()\n\n # Mock subprocess.run to simulate Deno being installed\n with (\n patch(\"subprocess.run\") as mock_run,\n patch(\"subprocess.Popen\") as mock_popen,\n patch(\"smolagents.remote_executors.requests.Session\") as mock_session_cls,\n patch(\"time.sleep\"),\n ):\n # Configure mocks\n mock_run.return_value.returncode = 0\n mock_process = MagicMock()\n mock_process.poll.return_value = None\n mock_popen.return_value = mock_process\n mock_session = MagicMock()\n mock_session.get.return_value.status_code = 200\n mock_session_cls.return_value = mock_session\n\n # Create the executor\n executor = WasmExecutor(additional_imports=[\"numpy\", \"pandas\"], logger=logger, timeout=30)\n\n # Verify the executor was created correctly\n assert isinstance(executor, WasmExecutor)\n assert executor.logger == logger\n assert executor.timeout == 30\n assert \"numpy\" in executor.installed_packages\n assert \"pandas\" in executor.installed_packages\n\n # Verify Deno was checked\n assert mock_run.call_count == 1\n assert mock_run.call_args.args[0][0] == \"deno\"\n assert mock_run.call_args.args[0][1] == \"--version\"\n\n # Verify server was started\n assert mock_popen.call_count == 1\n assert mock_popen.call_args.args[0][0] == \"deno\"\n assert mock_popen.call_args.args[0][1] == \"run\"\n assert (\n \"--allow-net=127.0.0.1:8000,cdn.jsdelivr.net:443,pypi.org:443,files.pythonhosted.org:443\"\n in (mock_popen.call_args.args[0])\n )\n\n # Clean up\n with patch(\"shutil.rmtree\"):\n executor.cleanup()\n\n\n@require_run_all\nclass TestWasmExecutorIntegration:\n \"\"\"\n Integration tests for WasmExecutor.\n\n These tests require Deno to be installed on the system.\n Skip these tests if you don't have Deno installed.\n \"\"\"\n\n @pytest.fixture(autouse=True)\n def setup_and_teardown(self):\n \"\"\"Setup and teardown for each test.\"\"\"\n try:\n # Check if Deno is installed\n import subprocess\n\n subprocess.run([\"deno\", \"--version\"], capture_output=True, check=True)\n\n # Create the executor\n self.executor = WasmExecutor(\n additional_imports=[\"numpy\", \"pandas\"],\n logger=AgentLogger(LogLevel.INFO, Console(force_terminal=False, file=io.StringIO())),\n timeout=60,\n )\n yield\n # Clean up\n self.executor.cleanup()\n except (subprocess.SubprocessError, FileNotFoundError):\n pytest.skip(\"Deno is not installed, skipping integration tests\")\n\n def test_basic_execution(self):\n \"\"\"Test basic code execution.\"\"\"\n code = \"a = 2 + 2; print(f'Result: {a}')\"\n code_output = self.executor(code)\n assert \"Result: 4\" in code_output.logs\n\n def test_state_persistence(self):\n \"\"\"Test that variables persist between executions.\"\"\"\n # Define a variable\n self.executor(\"x = 42\")\n\n # Use the variable in a subsequent execution\n code_output = self.executor(\"print(x)\")\n assert \"42\" in code_output.logs\n\n def test_final_answer(self):\n \"\"\"Test returning a final answer.\"\"\"\n self.executor.send_tools({\"final_answer\": FinalAnswerTool()})\n code = 'final_answer(\"This is the final answer\")'\n code_output = self.executor(code)\n assert code_output.output == \"This is the final answer\"\n assert code_output.is_final_answer is True\n\n def test_numpy_execution(self):\n \"\"\"Test execution with NumPy.\"\"\"\n code = \"\"\"\n import numpy as np\n arr = np.array([1, 2, 3, 4, 5])\n print(f\"Mean: {np.mean(arr)}\")\n \"\"\"\n code_output = self.executor(code)\n assert \"Mean: 3.0\" in code_output.logs\n\n def test_error_handling(self):\n \"\"\"Test handling of Python errors.\"\"\"\n code = \"1/0\" # Division by zero\n with pytest.raises(AgentError) as excinfo:\n self.executor(code)\n assert \"ZeroDivisionError\" in str(excinfo.value)\n\n def test_syntax_error_handling(self):\n \"\"\"Test handling of syntax errors.\"\"\"\n code = \"print('Missing parenthesis\" # Missing closing parenthesis\n with pytest.raises(AgentError) as excinfo:\n self.executor(code)\n assert \"SyntaxError\" in str(excinfo.value)\n\n\nclass TestBlaxelExecutorUnit:\n def test_blaxel_executor_instantiation_without_blaxel_sdk(self):\n \"\"\"Test that BlaxelExecutor raises appropriate error when blaxel SDK is not installed.\"\"\"\n logger = MagicMock()\n with patch.dict(\"sys.modules\", {\"blaxel.core\": None}):\n with pytest.raises(ModuleNotFoundError) as excinfo:\n BlaxelExecutor(additional_imports=[], logger=logger)\n assert \"Please install 'blaxel' extra\" in str(excinfo.value)\n\n @patch(\"smolagents.remote_executors._create_kernel_http\")\n @patch(\"blaxel.core.SandboxInstance\")\n @patch(\"blaxel.core.settings\")\n def test_blaxel_executor_instantiation_with_blaxel_sdk(\n self, mock_settings, mock_sandbox_instance, mock_create_kernel\n ):\n \"\"\"Test BlaxelExecutor instantiation with mocked Blaxel SDK.\"\"\"\n\n # patch manually for Python 3.10 compatibility\n from unittest.mock import patch\n\n mod = importlib.import_module(\"blaxel.core.client.api.compute\")\n patcher = patch.object(mod, \"create_sandbox\")\n mock_create_sandbox = patcher.start()\n\n logger = MagicMock()\n mock_settings.headers = {}\n\n # Mock sandbox response\n mock_response = MagicMock()\n mock_create_sandbox.sync.return_value = mock_response\n\n # Mock SandboxInstance\n mock_sandbox = MagicMock()\n mock_metadata = MagicMock()\n mock_metadata.url = \"https://test-sandbox.bl.run\"\n mock_sandbox.metadata = mock_metadata\n mock_sandbox_instance.return_value = mock_sandbox\n\n # Mock kernel creation\n mock_create_kernel.return_value = \"kernel-123\"\n\n executor = BlaxelExecutor(additional_imports=[], logger=logger)\n\n patcher.stop()\n\n assert executor.sandbox_name.startswith(\"smolagent-executor-\")\n assert executor.image == \"blaxel/jupyter-notebook\"\n assert executor.memory == 4096\n assert executor.region is None\n\n @patch(\"smolagents.remote_executors.BlaxelExecutor.install_packages\")\n @patch(\"smolagents.remote_executors._create_kernel_http\")\n @patch(\"blaxel.core.SandboxInstance\")\n @patch(\"blaxel.core.settings\")\n def test_blaxel_executor_custom_parameters(\n self, mock_settings, mock_sandbox_instance, mock_create_kernel, mock_install_packages\n ):\n \"\"\"Test BlaxelExecutor with custom parameters.\"\"\"\n logger = MagicMock()\n mock_settings.headers = {}\n mock_install_packages.return_value = [\"numpy\"]\n\n # Mock sandbox response\n mock_response = MagicMock()\n\n # patch manually for Python 3.10 compatibility\n mod = importlib.import_module(\"blaxel.core.client.api.compute\")\n create_sandbox_patcher = patch.object(mod, \"create_sandbox\")\n mock_create_sandbox = create_sandbox_patcher.start()\n mock_create_sandbox.sync.return_value = mock_response\n\n # Mock SandboxInstance\n mock_sandbox = MagicMock()\n mock_metadata = MagicMock()\n mock_metadata.url = \"https://test-sandbox.us-was-1.bl.run\"\n mock_sandbox.metadata = mock_metadata\n mock_sandbox_instance.return_value = mock_sandbox\n\n # Mock kernel creation\n mock_create_kernel.return_value = \"kernel-123\"\n\n executor = BlaxelExecutor(\n additional_imports=[\"numpy\"],\n logger=logger,\n sandbox_name=\"test-sandbox\",\n image=\"custom-image:latest\",\n memory=8192,\n region=\"us-was-1\",\n )\n\n create_sandbox_patcher.stop()\n\n assert executor.sandbox_name == \"test-sandbox\"\n assert executor.image == \"custom-image:latest\"\n assert executor.memory == 8192\n assert executor.region == \"us-was-1\"\n assert mock_install_packages.called\n\n @patch(\"smolagents.remote_executors._create_kernel_http\")\n @patch(\"blaxel.core.SandboxInstance\")\n @patch(\"blaxel.core.settings\")\n def test_blaxel_executor_cleanup(self, mock_settings, mock_sandbox_instance, mock_create_kernel):\n \"\"\"Test BlaxelExecutor cleanup method.\"\"\"\n\n # patch manually for Python 3.10 compatibility\n from unittest.mock import patch\n\n mod = importlib.import_module(\"blaxel.core.client.api.compute\")\n create_sandbox_patcher = patch.object(mod, \"create_sandbox\")\n mock_create_sandbox = create_sandbox_patcher.start()\n delete_sandbox_patcher = patch.object(mod, \"delete_sandbox\")\n mock_delete_sandbox = delete_sandbox_patcher.start()\n\n logger = MagicMock()\n mock_settings.headers = {}\n\n # Mock sandbox response\n mock_response = MagicMock()\n mock_create_sandbox.sync.return_value = mock_response\n\n # Mock SandboxInstance\n mock_sandbox = MagicMock()\n mock_metadata = MagicMock()\n mock_metadata.url = \"https://test-sandbox.bl.run\"\n mock_sandbox.metadata = mock_metadata\n mock_sandbox_instance.return_value = mock_sandbox\n\n # Mock kernel creation\n mock_create_kernel.return_value = \"kernel-123\"\n\n executor = BlaxelExecutor(additional_imports=[], logger=logger)\n\n # Test cleanup\n executor.cleanup()\n create_sandbox_patcher.stop()\n delete_sandbox_patcher.stop()\n\n # Verify that delete_sandbox.sync was called\n assert mock_delete_sandbox.sync.called\n # Verify sandbox reference was cleaned up\n assert not hasattr(executor, \"sandbox\")\n"
},
{
"path": "tests/test_search.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\nfrom smolagents import DuckDuckGoSearchTool\n\nfrom .test_tools import ToolTesterMixin\nfrom .utils.markers import require_run_all\n\n\nclass TestDuckDuckGoSearchTool(ToolTesterMixin):\n def setup_method(self):\n self.tool = DuckDuckGoSearchTool()\n self.tool.setup()\n\n @require_run_all\n def test_exact_match_arg(self):\n result = self.tool(\"Agents\")\n assert isinstance(result, str)\n\n @require_run_all\n def test_agent_type_output(self):\n super().test_agent_type_output()\n"
},
{
"path": "tests/test_serialization.py",
"content": "#!/usr/bin/env python\n# coding=utf-8\n\n# Copyright 2024 The HuggingFace Inc. team. All rights reserved.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n\"\"\"\nComprehensive tests for SafeSerializer covering edge cases, error handling,\nperformance, and integration scenarios.\n\"\"\"\n\nimport base64\nimport json\nimport pickle\nimport warnings\nfrom datetime import datetime, timedelta\nfrom decimal import Decimal\nfrom pathlib import Path\n\nimport pytest\n\nfrom smolagents.serialization import SafeSerializer, SerializationError\n\n\n# Module-level class for pickle tests (local classes can't be pickled)\nclass PicklableCustomClass:\n \"\"\"A simple class that can be pickled.\"\"\"\n\n def __init__(self):\n self.value = 42\n\n\nclass TestSafeSerializationSecurity:\n \"\"\"Test that safe mode properly blocks pickle.\"\"\"\n\n def test_safe_mode_blocks_custom_classes(self):\n \"\"\"Verify custom classes cannot be serialized in safe mode.\"\"\"\n\n class CustomClass:\n def __init__(self):\n self.value = 42\n\n obj = CustomClass()\n\n # Should raise SerializationError in safe mode\n with pytest.raises(SerializationError, match=\"Cannot safely serialize\"):\n SafeSerializer.dumps(obj, allow_pickle=False)\n\n def test_safe_mode_blocks_pickle_deserialization(self):\n \"\"\"Verify pickle data is rejected in safe mode.\"\"\"\n\n # Create pickle data (no \"safe:\" prefix)\n pickle_data = base64.b64encode(pickle.dumps({\"test\": \"data\"})).decode()\n\n # Should raise error in safe mode\n with pytest.raises(SerializationError, match=\"Pickle data rejected\"):\n SafeSerializer.loads(pickle_data, allow_pickle=False)\n\n def test_pickle_fallback_with_warning(self):\n \"\"\"Verify pickle fallback works but warns in legacy mode.\"\"\"\n\n obj = PicklableCustomClass()\n\n # Should work but emit warning\n with warnings.catch_warnings(record=True) as w:\n warnings.simplefilter(\"always\")\n serialized = SafeSerializer.dumps(obj, allow_pickle=True)\n\n # Check warning was raised\n assert len(w) == 1\n assert issubclass(w[0].category, FutureWarning)\n assert \"insecure pickle\" in str(w[0].message).lower()\n\n # Should deserialize successfully (with warning)\n with warnings.catch_warnings(record=True) as w:\n warnings.simplefilter(\"always\")\n result = SafeSerializer.loads(serialized, allow_pickle=True)\n\n assert result.value == 42\n assert len(w) == 1\n assert \"pickle data\" in str(w[0].message).lower()\n\n\nclass TestSafeSerializationRoundtrip:\n \"\"\"Test that safe types serialize and deserialize correctly.\"\"\"\n\n def test_primitives(self):\n \"\"\"Test basic Python types.\"\"\"\n test_cases = [\n None,\n True,\n False,\n 42,\n 3.14,\n \"hello\",\n b\"bytes\",\n complex(1, 2),\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n assert serialized.startswith(\"safe:\")\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_collections(self):\n \"\"\"Test collections.\"\"\"\n test_cases = [\n [1, 2, 3],\n {\"key\": \"value\", \"nested\": {\"a\": 1}},\n (1, 2, 3),\n {1, 2, 3},\n frozenset([1, 2, 3]),\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_datetime_types(self):\n \"\"\"Test datetime module types.\"\"\"\n now = datetime.now()\n test_cases = [\n now,\n now.date(),\n now.time(),\n timedelta(days=1, hours=2, minutes=3),\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_special_types(self):\n \"\"\"Test Decimal and Path.\"\"\"\n test_cases = [\n Decimal(\"3.14159\"),\n Path(\"/tmp/test.txt\"),\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_complex_nested_structure(self):\n \"\"\"Test deeply nested structures.\"\"\"\n obj = {\n \"primitives\": [1, 2.5, \"string\", None, True],\n \"collections\": {\n \"list\": [1, 2, 3],\n \"tuple\": (4, 5, 6),\n \"set\": {7, 8, 9},\n },\n \"datetime\": datetime.now(),\n \"path\": Path(\"/tmp\"),\n \"bytes\": b\"binary data\",\n }\n\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n assert serialized.startswith(\"safe:\")\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n # Check structure is preserved\n assert result[\"primitives\"] == obj[\"primitives\"]\n assert result[\"collections\"][\"list\"] == obj[\"collections\"][\"list\"]\n assert result[\"datetime\"] == obj[\"datetime\"]\n assert result[\"path\"] == obj[\"path\"]\n assert result[\"bytes\"] == obj[\"bytes\"]\n\n\nclass TestBackwardCompatibility:\n \"\"\"Test that legacy pickle data can still be read when explicitly allowed.\"\"\"\n\n def test_read_legacy_pickle_data(self):\n \"\"\"Verify we can read old pickle data when allow_insecure=True.\"\"\"\n\n # Simulate legacy pickle data (no \"safe:\" prefix)\n legacy_data = {\"key\": \"value\", \"number\": 42}\n pickle_encoded = base64.b64encode(pickle.dumps(legacy_data)).decode()\n\n # Should work with allow_pickle=True\n with warnings.catch_warnings(record=True) as w:\n warnings.simplefilter(\"always\")\n result = SafeSerializer.loads(pickle_encoded, allow_pickle=True)\n\n assert result == legacy_data\n assert len(w) == 1 # Warning emitted\n assert \"pickle data\" in str(w[0].message).lower()\n\n def test_safe_data_is_preferred(self):\n \"\"\"Verify safe serialization is used even when pickle is allowed.\"\"\"\n\n # Basic dict should use safe serialization\n obj = {\"key\": [1, 2, 3]}\n\n with warnings.catch_warnings(record=True) as w:\n warnings.simplefilter(\"always\")\n serialized = SafeSerializer.dumps(obj, allow_pickle=True)\n\n # Should use safe format (no warning)\n assert serialized.startswith(\"safe:\")\n assert len(w) == 0 # No warning because safe was used\n\n\nclass TestDefaultBehavior:\n \"\"\"Test that defaults are secure.\"\"\"\n\n def test_dumps_defaults_to_safe(self):\n \"\"\"Verify dumps defaults to safe mode.\"\"\"\n obj = {\"key\": \"value\"}\n\n # Call without safe_serialization parameter - should default to True\n serialized = SafeSerializer.dumps(obj)\n assert serialized.startswith(\"safe:\")\n\n # Should be deserializable in safe mode\n result = SafeSerializer.loads(serialized)\n assert result == obj\n\n def test_loads_defaults_to_safe(self):\n \"\"\"Verify loads defaults to safe mode.\"\"\"\n # Create safe data\n obj = {\"key\": \"value\"}\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n\n # Call without safe_serialization parameter - should default to True\n result = SafeSerializer.loads(serialized)\n assert result == obj\n\n # Create pickle data\n pickle_data = base64.b64encode(pickle.dumps(obj)).decode()\n\n # Should reject pickle data by default\n with pytest.raises(SerializationError, match=\"Pickle data rejected\"):\n SafeSerializer.loads(pickle_data)\n\n\nclass TestEdgeCases:\n \"\"\"Test edge cases and boundary conditions.\"\"\"\n\n def test_empty_data(self):\n \"\"\"Test serialization of empty collections.\"\"\"\n test_cases = [\n [],\n {},\n (),\n set(),\n frozenset(),\n \"\",\n b\"\",\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_nested_empty_structures(self):\n \"\"\"Test deeply nested empty structures.\"\"\"\n obj = {\n \"empty_list\": [],\n \"empty_dict\": {},\n \"nested\": {\n \"empty_tuple\": (),\n \"empty_set\": set(),\n \"deeply_nested\": {\"still_empty\": []},\n },\n }\n\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_very_large_numbers(self):\n \"\"\"Test handling of very large integers and floats.\"\"\"\n test_cases = [\n 10**100, # Very large int\n -(10**100), # Very large negative int\n 1.7976931348623157e308, # Near max float\n 2.2250738585072014e-308, # Near min positive float\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_special_float_values(self):\n \"\"\"Test special float values (infinity, nan).\"\"\"\n import math\n\n # Note: NaN != NaN, so we handle it specially\n test_cases = [\n (float(\"inf\"), float(\"inf\")),\n (float(\"-inf\"), float(\"-inf\")),\n ]\n\n for obj, expected in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == expected\n\n # NaN special case\n nan_obj = float(\"nan\")\n serialized = SafeSerializer.dumps(nan_obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert math.isnan(result)\n\n def test_unicode_strings(self):\n \"\"\"Test handling of various unicode strings.\"\"\"\n test_cases = [\n \"Hello 世界\", # Mixed ASCII and Chinese\n \"🚀🎉💎\", # Emojis\n \"Ñoño\", # Accented characters\n \"\\u0000\", # Null character\n \"Line1\\nLine2\\tTabbed\", # Escape sequences\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_very_long_strings(self):\n \"\"\"Test handling of very long strings.\"\"\"\n long_string = \"a\" * 1_000_000 # 1MB string\n\n serialized = SafeSerializer.dumps(long_string, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == long_string\n\n def test_deeply_nested_structures(self):\n \"\"\"Test deeply nested data structures.\"\"\"\n # Create nested structure\n obj = {\"level\": 0}\n current = obj\n for i in range(1, 100): # 100 levels deep\n current[\"nested\"] = {\"level\": i}\n current = current[\"nested\"]\n\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_dict_with_tuple_keys(self):\n \"\"\"Test dictionaries with tuple keys.\"\"\"\n obj = {\n (1, 2): \"tuple_key\",\n (3, 4, 5): \"longer_tuple\",\n (\"a\", \"b\"): \"string_tuple\",\n }\n\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_dict_with_integer_keys(self):\n \"\"\"Test dictionaries with non-string keys.\"\"\"\n obj = {\n 1: \"one\",\n 2: \"two\",\n 100: \"hundred\",\n }\n\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_mixed_collection_types(self):\n \"\"\"Test mixed collection types in one structure.\"\"\"\n obj = {\n \"list\": [1, 2, 3],\n \"tuple\": (4, 5, 6),\n \"set\": {7, 8, 9},\n \"frozenset\": frozenset([10, 11, 12]),\n \"nested_list\": [[1, 2], [3, 4]],\n \"list_of_tuples\": [(1, 2), (3, 4)],\n }\n\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n # Compare each field\n assert result[\"list\"] == obj[\"list\"]\n assert result[\"tuple\"] == obj[\"tuple\"]\n assert result[\"set\"] == obj[\"set\"]\n assert result[\"frozenset\"] == obj[\"frozenset\"]\n assert result[\"nested_list\"] == obj[\"nested_list\"]\n assert result[\"list_of_tuples\"] == obj[\"list_of_tuples\"]\n\n\nclass TestErrorHandling:\n \"\"\"Test error handling and malformed data.\"\"\"\n\n def test_invalid_json_data(self):\n \"\"\"Test handling of invalid JSON data.\"\"\"\n with pytest.raises((json.JSONDecodeError, SerializationError)):\n SafeSerializer.loads(\"safe:invalid json\", allow_pickle=False)\n\n def test_corrupted_safe_prefix(self):\n \"\"\"Test handling of data with safe prefix but invalid JSON.\"\"\"\n with pytest.raises((json.JSONDecodeError, SerializationError)):\n SafeSerializer.loads(\"safe:{broken\", allow_pickle=False)\n\n def test_missing_type_field(self):\n \"\"\"Test handling of malformed type markers.\"\"\"\n # Valid JSON but missing required fields\n malformed = \"safe:\" + json.dumps({\"data\": [1, 2, 3]}) # Missing __type__\n\n # Should still work as regular dict\n result = SafeSerializer.loads(malformed, allow_pickle=False)\n assert result == {\"data\": [1, 2, 3]}\n\n def test_unknown_type_marker(self):\n \"\"\"Test handling of unknown type markers.\"\"\"\n unknown_type = \"safe:\" + json.dumps({\"__type__\": \"unknown_type\", \"data\": \"something\"})\n\n # Should return as dict with type marker\n result = SafeSerializer.loads(unknown_type, allow_pickle=False)\n assert \"__type__\" in result\n\n def test_invalid_base64_in_bytes(self):\n \"\"\"Test handling of invalid base64 in bytes type.\"\"\"\n invalid_bytes = \"safe:\" + json.dumps({\"__type__\": \"bytes\", \"data\": \"not-valid-base64!!!\"})\n\n with pytest.raises(Exception): # Will raise base64 decode error\n SafeSerializer.loads(invalid_bytes, allow_pickle=False)\n\n def test_serialization_of_none_type(self):\n \"\"\"Test that None type is handled correctly.\"\"\"\n obj = None\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result is None\n\n def test_serialization_of_function(self):\n \"\"\"Test that functions cannot be serialized safely.\"\"\"\n\n def my_function():\n pass\n\n with pytest.raises(SerializationError):\n SafeSerializer.dumps(my_function, allow_pickle=False)\n\n def test_serialization_of_class(self):\n \"\"\"Test that classes cannot be serialized safely.\"\"\"\n\n class MyClass:\n pass\n\n with pytest.raises(SerializationError):\n SafeSerializer.dumps(MyClass, allow_pickle=False)\n\n def test_serialization_of_module(self):\n \"\"\"Test that modules cannot be serialized safely.\"\"\"\n import os\n\n with pytest.raises(SerializationError):\n SafeSerializer.dumps(os, allow_pickle=False)\n\n\nclass TestTypeCoverage:\n \"\"\"Test all supported types comprehensively.\"\"\"\n\n def test_all_datetime_types(self):\n \"\"\"Test all datetime module types.\"\"\"\n from datetime import date, datetime, time\n\n test_cases = [\n datetime(2024, 1, 1, 12, 30, 45),\n date(2024, 1, 1),\n time(12, 30, 45),\n timedelta(days=5, hours=3, minutes=30, seconds=15),\n datetime.min,\n datetime.max,\n date.min,\n date.max,\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_decimal_precision(self):\n \"\"\"Test Decimal type with various precisions.\"\"\"\n from decimal import getcontext\n\n # Set high precision\n getcontext().prec = 50\n\n test_cases = [\n Decimal(\"3.14159265358979323846264338327950288419716939937510\"),\n Decimal(\"0.1\") + Decimal(\"0.2\"), # Famous float precision issue\n Decimal(\"1e-100\"),\n Decimal(\"1e100\"),\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_pathlib_types(self):\n \"\"\"Test various Path types.\"\"\"\n\n test_cases = [\n Path(\"/tmp/test.txt\"),\n Path(\"relative/path/file.py\"),\n Path(\"/\"),\n Path(\".\"),\n Path(\"..\"),\n Path(\"/path/with spaces/file.txt\"),\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_complex_numbers(self):\n \"\"\"Test complex number handling.\"\"\"\n test_cases = [\n complex(1, 2),\n complex(0, 0),\n complex(-5, 10),\n complex(3.14, 2.71),\n 1 + 2j,\n -5 + 10j,\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_bytes_types(self):\n \"\"\"Test various bytes objects.\"\"\"\n test_cases = [\n b\"hello\",\n b\"\\x00\\x01\\x02\\x03\",\n b\"Binary\\xff\\xfe\\xfd\",\n bytes(range(256)), # All byte values\n b\"\", # Empty bytes\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n\nclass TestNumpySupport:\n \"\"\"Test numpy array serialization (optional, skip if not installed).\"\"\"\n\n def test_numpy_array(self):\n \"\"\"Test numpy array roundtrip.\"\"\"\n pytest.importorskip(\"numpy\")\n import numpy as np\n\n arr = np.array([[1, 2], [3, 4]], dtype=np.float32)\n\n serialized = SafeSerializer.dumps(arr, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n np.testing.assert_array_equal(result, arr)\n assert result.dtype == arr.dtype\n\n def test_numpy_scalars(self):\n \"\"\"Test numpy scalar types.\"\"\"\n pytest.importorskip(\"numpy\")\n import numpy as np\n\n test_cases = [\n np.int32(42),\n np.float64(3.14),\n ]\n\n for obj in test_cases:\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj.item()\n\n def test_numpy_various_dtypes(self):\n \"\"\"Test numpy arrays with various dtypes.\"\"\"\n pytest.importorskip(\"numpy\")\n import numpy as np\n\n # Test numeric dtypes (non-complex)\n dtypes = [\n np.int8,\n np.int16,\n np.int32,\n np.int64,\n np.uint8,\n np.uint16,\n np.uint32,\n np.uint64,\n np.float16,\n np.float32,\n np.float64,\n np.bool_,\n ]\n\n for dtype in dtypes:\n arr = np.array([1, 2, 3], dtype=dtype)\n serialized = SafeSerializer.dumps(arr, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n np.testing.assert_array_equal(result, arr)\n assert result.dtype == arr.dtype\n\n # Complex dtypes need special handling - test separately\n # Note: numpy complex arrays are not fully supported in safe mode\n # as they require custom complex number serialization\n\n def test_numpy_multidimensional(self):\n \"\"\"Test multidimensional numpy arrays.\"\"\"\n pytest.importorskip(\"numpy\")\n import numpy as np\n\n test_cases = [\n np.array([[1, 2], [3, 4]]), # 2D\n np.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]]), # 3D\n np.zeros((10, 10, 10)), # Large 3D\n np.ones((5, 5)), # 2D ones\n ]\n\n for arr in test_cases:\n serialized = SafeSerializer.dumps(arr, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n np.testing.assert_array_equal(result, arr)\n\n def test_numpy_empty_array(self):\n \"\"\"Test empty numpy array.\"\"\"\n pytest.importorskip(\"numpy\")\n import numpy as np\n\n arr = np.array([])\n serialized = SafeSerializer.dumps(arr, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n np.testing.assert_array_equal(result, arr)\n\n\nclass TestPILSupport:\n \"\"\"Test PIL Image serialization (optional, skip if not installed).\"\"\"\n\n def test_pil_image(self):\n \"\"\"Test PIL Image roundtrip.\"\"\"\n pytest.importorskip(\"PIL\")\n from PIL import Image\n\n # Create a simple test image\n img = Image.new(\"RGB\", (10, 10), color=\"red\")\n\n serialized = SafeSerializer.dumps(img, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert isinstance(result, Image.Image)\n assert result.size == img.size\n assert result.mode == img.mode\n\n def test_pil_various_modes(self):\n \"\"\"Test PIL images in various modes.\"\"\"\n pytest.importorskip(\"PIL\")\n from PIL import Image\n\n modes = [\"RGB\", \"RGBA\", \"L\", \"1\"] # Color, Alpha, Grayscale, Binary\n\n for mode in modes:\n img = Image.new(mode, (10, 10), color=\"red\" if mode != \"1\" else 1)\n serialized = SafeSerializer.dumps(img, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert isinstance(result, Image.Image)\n assert result.mode == img.mode\n assert result.size == img.size\n\n def test_pil_various_sizes(self):\n \"\"\"Test PIL images of various sizes.\"\"\"\n pytest.importorskip(\"PIL\")\n from PIL import Image\n\n sizes = [(1, 1), (100, 100), (500, 300)]\n\n for size in sizes:\n img = Image.new(\"RGB\", size, color=\"blue\")\n serialized = SafeSerializer.dumps(img, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert result.size == img.size\n\n\nclass TestDataclasses:\n \"\"\"Test dataclass serialization.\"\"\"\n\n def test_simple_dataclass(self):\n \"\"\"Test simple dataclass.\"\"\"\n from dataclasses import dataclass\n\n @dataclass\n class Person:\n name: str\n age: int\n\n person = Person(name=\"Alice\", age=30)\n serialized = SafeSerializer.dumps(person, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n # Result is a dict representation\n assert result[\"__dataclass__\"] == \"Person\"\n assert result[\"name\"] == \"Alice\"\n assert result[\"age\"] == 30\n\n def test_nested_dataclass(self):\n \"\"\"Test nested dataclasses.\"\"\"\n from dataclasses import dataclass\n\n @dataclass\n class Address:\n street: str\n city: str\n\n @dataclass\n class Person:\n name: str\n address: Address\n\n person = Person(name=\"Bob\", address=Address(street=\"123 Main St\", city=\"NYC\"))\n serialized = SafeSerializer.dumps(person, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert result[\"name\"] == \"Bob\"\n assert result[\"address\"][\"street\"] == \"123 Main St\"\n\n\nclass TestPerformance:\n \"\"\"Performance tests for large data.\"\"\"\n\n def test_large_list(self):\n \"\"\"Test serialization of large list.\"\"\"\n large_list = list(range(100_000))\n\n serialized = SafeSerializer.dumps(large_list, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert result == large_list\n\n def test_large_dict(self):\n \"\"\"Test serialization of large dictionary.\"\"\"\n large_dict = {f\"key_{i}\": i for i in range(10_000)}\n\n serialized = SafeSerializer.dumps(large_dict, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert result == large_dict\n\n def test_deeply_nested_performance(self):\n \"\"\"Test performance with deeply nested structures.\"\"\"\n obj = {\"level\": 0}\n current = obj\n for i in range(1, 100): # 100 levels (avoid recursion limit)\n current[\"nested\"] = {\"level\": i}\n current = current[\"nested\"]\n\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert result == obj\n\n\nclass TestPrefixHandling:\n \"\"\"Test handling of different prefix formats.\"\"\"\n\n def test_safe_prefix_detection(self):\n \"\"\"Test detection of safe: prefix.\"\"\"\n obj = {\"test\": \"data\"}\n serialized = SafeSerializer.dumps(obj, allow_pickle=False)\n\n assert serialized.startswith(\"safe:\")\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == obj\n\n def test_pickle_prefix_with_allow_pickle(self):\n \"\"\"Test pickle: prefix when pickle is allowed.\"\"\"\n # Create an object that needs pickle\n obj = PicklableCustomClass()\n serialized = SafeSerializer.dumps(obj, allow_pickle=True)\n\n # Should have pickle prefix\n assert serialized.startswith(\"pickle:\")\n\n result = SafeSerializer.loads(serialized, allow_pickle=True)\n assert result.value == 42\n\n def test_legacy_format_detection(self):\n \"\"\"Test detection and handling of legacy format (no prefix).\"\"\"\n # Simulate legacy pickle data (no prefix)\n legacy_data = {\"key\": \"value\"}\n legacy_encoded = base64.b64encode(pickle.dumps(legacy_data)).decode()\n\n # Should work with allow_pickle=True\n result = SafeSerializer.loads(legacy_encoded, allow_pickle=True)\n assert result == legacy_data\n\n\nclass TestRealWorldScenarios:\n \"\"\"Test real-world usage scenarios.\"\"\"\n\n def test_agent_variables_scenario(self):\n \"\"\"Test typical agent variables scenario.\"\"\"\n import numpy as np\n from PIL import Image\n\n # Typical variables an agent might use\n variables = {\n \"search_results\": [\"result1\", \"result2\", \"result3\"],\n \"config\": {\n \"temperature\": 0.7,\n \"max_tokens\": 100,\n \"model\": \"gpt-4\",\n },\n \"data_array\": np.array([1.0, 2.0, 3.0]),\n \"image\": Image.new(\"RGB\", (50, 50)),\n \"timestamp\": datetime.now(),\n \"status\": \"running\",\n \"counter\": 42,\n }\n\n serialized = SafeSerializer.dumps(variables, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n\n assert result[\"search_results\"] == variables[\"search_results\"]\n assert result[\"config\"] == variables[\"config\"]\n assert result[\"status\"] == variables[\"status\"]\n assert result[\"counter\"] == variables[\"counter\"]\n\n def test_final_answer_scenario(self):\n \"\"\"Test typical final answer serialization.\"\"\"\n final_answers = [\n \"Simple string answer\",\n {\"answer\": \"structured\", \"confidence\": 0.95},\n [\"multiple\", \"results\", \"returned\"],\n 42,\n 3.14159,\n True,\n ]\n\n for answer in final_answers:\n serialized = SafeSerializer.dumps(answer, allow_pickle=False)\n result = SafeSerializer.loads(serialized, allow_pickle=False)\n assert result == answer\n\n\nclass TestGeneratedDeserializerCode:\n \"\"\"Regression tests for generated deserializer code used by remote executors.\"\"\"\n\n def test_generated_deserializer_executes_for_safe_payload(self):\n code = SafeSerializer.get_deserializer_code(allow_pickle=False)\n namespace = {}\n exec(code, namespace, namespace)\n\n payload = SafeSerializer.dumps(\n {\n \"count\": 3,\n \"items\": (1, 2, 3),\n \"raw\": b\"bytes\",\n },\n allow_pickle=False,\n )\n result = namespace[\"_deserialize\"](payload)\n assert result == {\"count\": 3, \"items\": (1, 2, 3), \"raw\": b\"bytes\"}\n\n def test_generated_deserializer_handles_pickle_prefix_when_enabled(self):\n code = SafeSerializer.get_deserializer_code(allow_pickle=True)\n namespace = {}\n exec(code, namespace, namespace)\n\n payload = \"pickle:\" + base64.b64encode(pickle.dumps({\"hello\": \"world\"})).decode()\n result = namespace[\"_deserialize\"](payload)\n assert result == {\"hello\": \"world\"}\n\n\nclass TestConcurrency:\n \"\"\"Test thread safety and concurrent access.\"\"\"\n\n def test_concurrent_serialization(self):\n \"\"\"Test concurrent serialization operations.\"\"\"\n import threading\n\n results = []\n errors = []\n\n def serialize_data(data, index):\n try:\n serialized = SafeSerializer.dumps(data, allow_pickle=False)\n deserialized = SafeSerializer.loads(serialized, allow_pickle=False)\n results.append((index, deserialized == data))\n except Exception as e:\n errors.append((index, e))\n\n threads = []\n test_data = [{\"thread\": i, \"data\": list(range(100))} for i in range(10)]\n\n for i, data in enumerate(test_data):\n thread = threading.Thread(target=serialize_data, args=(data, i))\n threads.append(thread)\n thread.start()\n\n for thread in threads:\n thread.join()\n\n assert len(errors) == 0, f\"Errors occurred: {errors}\"\n assert len(results) == 10\n assert all(success for _, success in results)\n"
},
{
"path": "tests/test_telemetry.py",
"content": "# coding=utf-8\n# Copyright 2025 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\n# Source: https://github.com/Arize-ai/openinference/blob/main/python/instrumentation/openinference-instrumentation-smolagents/tests/openinference/instrumentation/smolagents/test_instrumentor.py\n\nfrom typing import Generator\n\nimport pytest\n\nfrom .utils.markers import require_run_all\n\n\n# Add this at the module level to skip all tests if OpenTelemetry is not available\npytest.importorskip(\"opentelemetry\", reason=\"requires opentelemetry\")\npytest.importorskip(\n \"openinference.instrumentation.smolagents\", reason=\"requires openinference.instrumentation.smolagents\"\n)\n\nfrom openinference.instrumentation.smolagents import SmolagentsInstrumentor\nfrom opentelemetry import trace as trace_api\nfrom opentelemetry.sdk import trace as trace_sdk\nfrom opentelemetry.sdk.resources import Resource\nfrom opentelemetry.sdk.trace.export import SimpleSpanProcessor\nfrom opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter\n\nfrom smolagents.models import InferenceClientModel\n\n\n@pytest.fixture\ndef in_memory_span_exporter() -> InMemorySpanExporter:\n return InMemorySpanExporter()\n\n\n@pytest.fixture\ndef tracer_provider(in_memory_span_exporter: InMemorySpanExporter) -> trace_api.TracerProvider:\n resource = Resource(attributes={})\n tracer_provider = trace_sdk.TracerProvider(resource=resource)\n span_processor = SimpleSpanProcessor(span_exporter=in_memory_span_exporter)\n tracer_provider.add_span_processor(span_processor=span_processor)\n return tracer_provider\n\n\n@pytest.fixture(autouse=True)\ndef instrument(\n tracer_provider: trace_api.TracerProvider,\n in_memory_span_exporter: InMemorySpanExporter,\n) -> Generator[None, None, None]:\n SmolagentsInstrumentor().instrument(tracer_provider=tracer_provider, skip_dep_check=True)\n yield\n SmolagentsInstrumentor().uninstrument()\n in_memory_span_exporter.clear()\n\n\n@require_run_all\nclass TestOpenTelemetry:\n def test_model(self, in_memory_span_exporter: InMemorySpanExporter):\n model = InferenceClientModel()\n _ = model(\n messages=[\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Who won the World Cup in 2018? Answer in one word with no punctuation.\",\n }\n ],\n }\n ]\n )\n spans = in_memory_span_exporter.get_finished_spans()\n assert len(spans) == 1\n span = spans[0]\n assert span.name == \"InferenceClientModel.generate\"\n assert span.status.is_ok\n assert span.attributes\n"
},
{
"path": "tests/test_tool_validation.py",
"content": "import ast\nfrom textwrap import dedent\n\nimport pytest\n\nfrom smolagents.default_tools import (\n DuckDuckGoSearchTool,\n GoogleSearchTool,\n SpeechToTextTool,\n VisitWebpageTool,\n WebSearchTool,\n)\nfrom smolagents.tool_validation import MethodChecker, validate_tool_attributes\nfrom smolagents.tools import Tool, tool\n\n\nUNDEFINED_VARIABLE = \"undefined_variable\"\n\n\n@pytest.mark.parametrize(\n \"tool_class\", [DuckDuckGoSearchTool, GoogleSearchTool, SpeechToTextTool, VisitWebpageTool, WebSearchTool]\n)\ndef test_validate_tool_attributes_with_default_tools(tool_class):\n assert validate_tool_attributes(tool_class) is None, f\"failed for {tool_class.name} tool\"\n\n\nclass ValidTool(Tool):\n name = \"valid_tool\"\n description = \"A valid tool\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n simple_attr = \"string\"\n dict_attr = {\"key\": \"value\"}\n\n def __init__(self, optional_param=\"default\"):\n super().__init__()\n self.param = optional_param\n\n def forward(self, input: str) -> str:\n return input.upper()\n\n\n@tool\ndef valid_tool_function(input: str) -> str:\n \"\"\"A valid tool function.\n\n Args:\n input (str): Input string.\n \"\"\"\n return input.upper()\n\n\n@pytest.mark.parametrize(\"tool_class\", [ValidTool, valid_tool_function.__class__])\ndef test_validate_tool_attributes_valid(tool_class):\n assert validate_tool_attributes(tool_class) is None\n\n\nclass InvalidToolName(Tool):\n name = \"invalid tool name\"\n description = \"Tool with invalid name\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n\n def __init__(self):\n super().__init__()\n\n def forward(self, input: str) -> str:\n return input\n\n\nclass InvalidToolComplexAttrs(Tool):\n name = \"invalid_tool\"\n description = \"Tool with complex class attributes\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n complex_attr = [x for x in range(3)] # Complex class attribute\n\n def __init__(self):\n super().__init__()\n\n def forward(self, input: str) -> str:\n return input\n\n\nclass InvalidToolRequiredParams(Tool):\n name = \"invalid_tool\"\n description = \"Tool with required params\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n\n def __init__(self, required_param, kwarg1=1): # No default value\n super().__init__()\n self.param = required_param\n\n def forward(self, input: str) -> str:\n return input\n\n\nclass InvalidToolNonLiteralDefaultParam(Tool):\n name = \"invalid_tool\"\n description = \"Tool with non-literal default parameter value\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n\n def __init__(self, default_param=UNDEFINED_VARIABLE): # UNDEFINED_VARIABLE as default is non-literal\n super().__init__()\n self.default_param = default_param\n\n def forward(self, input: str) -> str:\n return input\n\n\nclass InvalidToolUndefinedNames(Tool):\n name = \"invalid_tool\"\n description = \"Tool with undefined names\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n\n def forward(self, input: str) -> str:\n return UNDEFINED_VARIABLE # Undefined name\n\n\n@pytest.mark.parametrize(\n \"tool_class, expected_error\",\n [\n (\n InvalidToolName,\n \"Class attribute 'name' must be a valid Python identifier and not a reserved keyword, found 'invalid tool name'\",\n ),\n (InvalidToolComplexAttrs, \"Complex attributes should be defined in __init__, not as class attributes\"),\n (InvalidToolRequiredParams, \"Parameters in __init__ must have default values, found required parameters\"),\n (\n InvalidToolNonLiteralDefaultParam,\n \"Parameters in __init__ must have literal default values, found non-literal defaults\",\n ),\n (InvalidToolUndefinedNames, \"Name 'UNDEFINED_VARIABLE' is undefined\"),\n ],\n)\ndef test_validate_tool_attributes_exceptions(tool_class, expected_error):\n with pytest.raises(ValueError, match=expected_error):\n validate_tool_attributes(tool_class)\n\n\nclass MultipleAssignmentsTool(Tool):\n name = \"multiple_assignments_tool\"\n description = \"Tool with multiple assignments\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n\n def __init__(self):\n super().__init__()\n\n def forward(self, input: str) -> str:\n a, b = \"1\", \"2\"\n return a + b\n\n\ndef test_validate_tool_attributes_multiple_assignments():\n validate_tool_attributes(MultipleAssignmentsTool)\n\n\n@tool\ndef tool_function_with_multiple_assignments(input: str) -> str:\n \"\"\"A valid tool function.\n\n Args:\n input (str): Input string.\n \"\"\"\n a, b = \"1\", \"2\"\n return input.upper() + a + b\n\n\n@pytest.mark.parametrize(\"tool_instance\", [MultipleAssignmentsTool(), tool_function_with_multiple_assignments])\ndef test_tool_to_dict_validation_with_multiple_assignments(tool_instance):\n tool_instance.to_dict()\n\n\nclass TestMethodChecker:\n def test_multiple_assignments(self):\n source_code = dedent(\n \"\"\"\n def forward(self) -> str:\n a, b = \"1\", \"2\"\n return a + b\n \"\"\"\n )\n method_checker = MethodChecker(set())\n method_checker.visit(ast.parse(source_code))\n assert method_checker.errors == []\n"
},
{
"path": "tests/test_tools.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nimport inspect\nimport os\nimport warnings\nfrom textwrap import dedent\nfrom typing import Any, Literal\nfrom unittest.mock import MagicMock, patch\n\nimport mcp\nimport numpy as np\nimport PIL.Image\nimport pytest\n\nfrom smolagents.agent_types import _AGENT_TYPE_MAPPING\nfrom smolagents.tools import AUTHORIZED_TYPES, Tool, ToolCollection, launch_gradio_demo, tool, validate_tool_arguments\n\nfrom .utils.markers import require_run_all\n\n\nclass ToolTesterMixin:\n def test_inputs_output(self):\n assert hasattr(self.tool, \"inputs\")\n assert hasattr(self.tool, \"output_type\")\n\n inputs = self.tool.inputs\n assert isinstance(inputs, dict)\n\n for _, input_spec in inputs.items():\n assert \"type\" in input_spec\n assert \"description\" in input_spec\n assert input_spec[\"type\"] in AUTHORIZED_TYPES\n assert isinstance(input_spec[\"description\"], str)\n\n output_type = self.tool.output_type\n assert output_type in AUTHORIZED_TYPES\n\n def test_common_attributes(self):\n assert hasattr(self.tool, \"description\")\n assert hasattr(self.tool, \"name\")\n assert hasattr(self.tool, \"inputs\")\n assert hasattr(self.tool, \"output_type\")\n\n def test_agent_type_output(self, create_inputs):\n inputs = create_inputs(self.tool.inputs)\n output = self.tool(**inputs, sanitize_inputs_outputs=True)\n if self.tool.output_type != \"any\":\n agent_type = _AGENT_TYPE_MAPPING[self.tool.output_type]\n assert isinstance(output, agent_type)\n\n @pytest.fixture\n def create_inputs(self, shared_datadir):\n def _create_inputs(tool_inputs: dict[str, dict[str | type, str]]) -> dict[str, Any]:\n inputs = {}\n\n for input_name, input_desc in tool_inputs.items():\n input_type = input_desc[\"type\"]\n\n if input_type == \"string\":\n inputs[input_name] = \"Text input\"\n elif input_type == \"image\":\n inputs[input_name] = PIL.Image.open(shared_datadir / \"000000039769.png\").resize((512, 512))\n elif input_type == \"audio\":\n inputs[input_name] = np.ones(3000)\n else:\n raise ValueError(f\"Invalid type requested: {input_type}\")\n\n return inputs\n\n return _create_inputs\n\n\nclass TestTool:\n @pytest.mark.parametrize(\n \"type_value, should_raise_error, error_contains\",\n [\n # Valid cases\n (\"string\", False, None),\n ([\"string\", \"number\"], False, None),\n # Invalid cases\n (\"invalid_type\", ValueError, \"must be one of\"),\n ([\"string\", \"invalid_type\"], ValueError, \"must be one of\"),\n ([123, \"string\"], TypeError, \"when type is a list, all elements must be strings\"),\n (123, TypeError, \"must be a string or list of strings\"),\n ],\n )\n def test_tool_input_type_validation(self, type_value, should_raise_error, error_contains):\n \"\"\"Test the validation of the type property in tool inputs.\"\"\"\n\n # Define a tool class with the test type value\n def create_tool():\n class TestTool(Tool):\n name = \"test_tool\"\n description = \"A tool for testing type validation\"\n inputs = {\"text\": {\"type\": type_value, \"description\": \"Some input\"}}\n output_type = \"string\"\n\n def forward(self, text) -> str:\n return text\n\n return TestTool()\n\n # Check if we expect this to raise an exception\n if should_raise_error:\n with pytest.raises(should_raise_error) as exc_info:\n create_tool()\n # Verify the error message contains expected text\n assert error_contains in str(exc_info.value)\n else:\n # Should not raise an exception\n tool = create_tool()\n assert isinstance(tool, Tool)\n\n @pytest.mark.parametrize(\n \"tool_fixture, expected_output\",\n [\n (\"no_input_tool\", 'def no_input_tool() -> string:\\n \"\"\"Tool with no inputs\\n \"\"\"'),\n (\n \"single_input_tool\",\n 'def single_input_tool(text: string) -> string:\\n \"\"\"Tool with one input\\n\\n Args:\\n text: Input text\\n \"\"\"',\n ),\n (\n \"multi_input_tool\",\n 'def multi_input_tool(text: string, count: integer) -> object:\\n \"\"\"Tool with multiple inputs\\n\\n Args:\\n text: Text input\\n count: Number count\\n \"\"\"',\n ),\n (\n \"multiline_description_tool\",\n 'def multiline_description_tool(input: string) -> string:\\n \"\"\"This is a tool with\\n multiple lines\\n in the description\\n\\n Args:\\n input: Some input\\n \"\"\"',\n ),\n ],\n )\n def test_tool_to_code_prompt_output_format(self, tool_fixture, expected_output, request):\n \"\"\"Test that to_code_prompt generates properly formatted and indented output.\"\"\"\n tool = request.getfixturevalue(tool_fixture)\n code_prompt = tool.to_code_prompt()\n assert code_prompt == expected_output\n\n @pytest.mark.parametrize(\n \"tool_fixture, expected_output\",\n [\n (\n \"no_input_tool\",\n \"no_input_tool: Tool with no inputs\\n Takes inputs: {}\\n Returns an output of type: string\",\n ),\n (\n \"single_input_tool\",\n \"single_input_tool: Tool with one input\\n Takes inputs: {'text': {'type': 'string', 'description': 'Input text'}}\\n Returns an output of type: string\",\n ),\n (\n \"multi_input_tool\",\n \"multi_input_tool: Tool with multiple inputs\\n Takes inputs: {'text': {'type': 'string', 'description': 'Text input'}, 'count': {'type': 'integer', 'description': 'Number count'}}\\n Returns an output of type: object\",\n ),\n (\n \"multiline_description_tool\",\n \"multiline_description_tool: This is a tool with\\nmultiple lines\\nin the description\\n Takes inputs: {'input': {'type': 'string', 'description': 'Some input'}}\\n Returns an output of type: string\",\n ),\n ],\n )\n def test_tool_to_tool_calling_prompt_output_format(self, tool_fixture, expected_output, request):\n \"\"\"Test that to_tool_calling_prompt generates properly formatted output.\"\"\"\n tool = request.getfixturevalue(tool_fixture)\n tool_calling_prompt = tool.to_tool_calling_prompt()\n assert tool_calling_prompt == expected_output\n\n def test_tool_init_with_decorator(self):\n @tool\n def coolfunc(a: str, b: int) -> float:\n \"\"\"Cool function\n\n Args:\n a: The first argument\n b: The second one\n \"\"\"\n return b + 2, a\n\n assert coolfunc.output_type == \"number\"\n\n def test_tool_init_vanilla(self):\n class HFModelDownloadsTool(Tool):\n name = \"model_download_counter\"\n description = \"\"\"\n This is a tool that returns the most downloaded model of a given task on the Hugging Face Hub.\n It returns the name of the checkpoint.\"\"\"\n\n inputs = {\n \"task\": {\n \"type\": \"string\",\n \"description\": \"the task category (such as text-classification, depth-estimation, etc)\",\n }\n }\n output_type = \"string\"\n\n def forward(self, task: str) -> str:\n return \"best model\"\n\n tool = HFModelDownloadsTool()\n assert list(tool.inputs.keys())[0] == \"task\"\n\n def test_tool_init_decorator_raises_issues(self):\n with pytest.raises(Exception) as e:\n\n @tool\n def coolfunc(a: str, b: int):\n \"\"\"Cool function\n\n Args:\n a: The first argument\n b: The second one\n \"\"\"\n return a + b\n\n assert coolfunc.output_type == \"number\"\n assert \"Tool return type not found\" in str(e)\n\n with pytest.raises(Exception) as e:\n\n @tool\n def coolfunc(a: str, b: int) -> int:\n \"\"\"Cool function\n\n Args:\n a: The first argument\n \"\"\"\n return b + a\n\n assert coolfunc.output_type == \"number\"\n assert \"docstring has no description for the argument\" in str(e)\n\n def test_saving_tool_raises_error_imports_outside_function(self, tmp_path):\n with pytest.raises(Exception) as e:\n import numpy as np\n\n @tool\n def get_current_time() -> str:\n \"\"\"\n Gets the current time.\n \"\"\"\n return str(np.random.random())\n\n get_current_time.save(tmp_path)\n\n assert \"np\" in str(e)\n\n # Also test with classic definition\n with pytest.raises(Exception) as e:\n\n class GetCurrentTimeTool(Tool):\n name = \"get_current_time_tool\"\n description = \"Gets the current time\"\n inputs = {}\n output_type = \"string\"\n\n def forward(self):\n return str(np.random.random())\n\n get_current_time = GetCurrentTimeTool()\n get_current_time.save(tmp_path)\n\n assert \"np\" in str(e)\n\n def test_tool_definition_raises_no_error_imports_in_function(self):\n @tool\n def get_current_time() -> str:\n \"\"\"\n Gets the current time.\n \"\"\"\n from datetime import datetime\n\n return str(datetime.now())\n\n class GetCurrentTimeTool(Tool):\n name = \"get_current_time_tool\"\n description = \"Gets the current time\"\n inputs = {}\n output_type = \"string\"\n\n def forward(self):\n from datetime import datetime\n\n return str(datetime.now())\n\n def test_tool_to_dict_allows_no_arg_in_init(self):\n \"\"\"Test that a tool cannot be saved with required args in init\"\"\"\n\n class FailTool(Tool):\n name = \"specific\"\n description = \"test description\"\n inputs = {\"string_input\": {\"type\": \"string\", \"description\": \"input description\"}}\n output_type = \"string\"\n\n def __init__(self, url):\n super().__init__(self)\n self.url = url\n\n def forward(self, string_input: str) -> str:\n return self.url + string_input\n\n fail_tool = FailTool(\"dummy_url\")\n with pytest.raises(Exception) as e:\n fail_tool.to_dict()\n assert \"Parameters in __init__ must have default values, found required parameters\" in str(e)\n\n class PassTool(Tool):\n name = \"specific\"\n description = \"test description\"\n inputs = {\"string_input\": {\"type\": \"string\", \"description\": \"input description\"}}\n output_type = \"string\"\n\n def __init__(self, url: str | None = \"none\"):\n super().__init__(self)\n self.url = url\n\n def forward(self, string_input: str) -> str:\n return self.url + string_input\n\n fail_tool = PassTool()\n fail_tool.to_dict()\n\n def test_saving_tool_allows_no_imports_from_outside_methods(self, tmp_path):\n # Test that using imports from outside functions fails\n import numpy as np\n\n class FailTool(Tool):\n name = \"specific\"\n description = \"test description\"\n inputs = {\"string_input\": {\"type\": \"string\", \"description\": \"input description\"}}\n output_type = \"string\"\n\n def useless_method(self):\n self.client = np.random.random()\n return \"\"\n\n def forward(self, string_input):\n return self.useless_method() + string_input\n\n fail_tool = FailTool()\n with pytest.raises(Exception) as e:\n fail_tool.save(tmp_path)\n assert \"'np' is undefined\" in str(e)\n\n # Test that putting these imports inside functions works\n class SuccessTool(Tool):\n name = \"specific\"\n description = \"test description\"\n inputs = {\"string_input\": {\"type\": \"string\", \"description\": \"input description\"}}\n output_type = \"string\"\n\n def useless_method(self):\n import numpy as np\n\n self.client = np.random.random()\n return \"\"\n\n def forward(self, string_input):\n return self.useless_method() + string_input\n\n success_tool = SuccessTool()\n success_tool.save(tmp_path)\n\n def test_tool_missing_class_attributes_raises_error(self):\n with pytest.raises(Exception) as e:\n\n class GetWeatherTool(Tool):\n name = \"get_weather\"\n description = \"Get weather in the next days at given location.\"\n inputs = {\n \"location\": {\"type\": \"string\", \"description\": \"the location\"},\n \"celsius\": {\n \"type\": \"string\",\n \"description\": \"the temperature type\",\n },\n }\n\n def forward(self, location: str, celsius: bool | None = False) -> str:\n return \"The weather is UNGODLY with torrential rains and temperatures below -10°C\"\n\n GetWeatherTool()\n assert \"You must set an attribute output_type\" in str(e)\n\n def test_tool_from_decorator_optional_args(self):\n @tool\n def get_weather(location: str, celsius: bool | None = False) -> str:\n \"\"\"\n Get weather in the next days at given location.\n Secretly this tool does not care about the location, it hates the weather everywhere.\n\n Args:\n location: the location\n celsius: the temperature type\n \"\"\"\n return \"The weather is UNGODLY with torrential rains and temperatures below -10°C\"\n\n assert \"nullable\" in get_weather.inputs[\"celsius\"]\n assert get_weather.inputs[\"celsius\"][\"nullable\"]\n assert \"nullable\" not in get_weather.inputs[\"location\"]\n\n def test_tool_mismatching_nullable_args_raises_error(self):\n with pytest.raises(Exception) as e:\n\n class GetWeatherTool(Tool):\n name = \"get_weather\"\n description = \"Get weather in the next days at given location.\"\n inputs = {\n \"location\": {\"type\": \"string\", \"description\": \"the location\"},\n \"celsius\": {\n \"type\": \"string\",\n \"description\": \"the temperature type\",\n },\n }\n output_type = \"string\"\n\n def forward(self, location: str, celsius: bool | None = False) -> str:\n return \"The weather is UNGODLY with torrential rains and temperatures below -10°C\"\n\n GetWeatherTool()\n assert \"Nullable\" in str(e)\n\n with pytest.raises(Exception) as e:\n\n class GetWeatherTool2(Tool):\n name = \"get_weather\"\n description = \"Get weather in the next days at given location.\"\n inputs = {\n \"location\": {\"type\": \"string\", \"description\": \"the location\"},\n \"celsius\": {\n \"type\": \"string\",\n \"description\": \"the temperature type\",\n },\n }\n output_type = \"string\"\n\n def forward(self, location: str, celsius: bool = False) -> str:\n return \"The weather is UNGODLY with torrential rains and temperatures below -10°C\"\n\n GetWeatherTool2()\n assert \"Nullable\" in str(e)\n\n with pytest.raises(Exception) as e:\n\n class GetWeatherTool3(Tool):\n name = \"get_weather\"\n description = \"Get weather in the next days at given location.\"\n inputs = {\n \"location\": {\"type\": \"string\", \"description\": \"the location\"},\n \"celsius\": {\n \"type\": \"string\",\n \"description\": \"the temperature type\",\n \"nullable\": True,\n },\n }\n output_type = \"string\"\n\n def forward(self, location, celsius: str) -> str:\n return \"The weather is UNGODLY with torrential rains and temperatures below -10°C\"\n\n GetWeatherTool3()\n assert \"Nullable\" in str(e)\n\n def test_tool_default_parameters_is_nullable(self):\n @tool\n def get_weather(location: str, celsius: bool = False) -> str:\n \"\"\"\n Get weather in the next days at given location.\n\n Args:\n location: The location to get the weather for.\n celsius: is the temperature given in celsius?\n \"\"\"\n return \"The weather is UNGODLY with torrential rains and temperatures below -10°C\"\n\n assert get_weather.inputs[\"celsius\"][\"nullable\"]\n\n def test_tool_supports_any_none(self, tmp_path):\n @tool\n def get_weather(location: Any) -> None:\n \"\"\"\n Get weather in the next days at given location.\n\n Args:\n location: The location to get the weather for.\n \"\"\"\n return\n\n get_weather.save(tmp_path)\n assert get_weather.inputs[\"location\"][\"type\"] == \"any\"\n assert get_weather.output_type == \"null\"\n\n def test_tool_supports_array(self):\n @tool\n def get_weather(locations: list[str], months: tuple[str, str] | None = None) -> dict[str, float]:\n \"\"\"\n Get weather in the next days at given locations.\n\n Args:\n locations: The locations to get the weather for.\n months: The months to get the weather for\n \"\"\"\n return\n\n assert get_weather.inputs[\"locations\"][\"type\"] == \"array\"\n assert get_weather.inputs[\"months\"][\"type\"] == \"array\"\n\n def test_tool_supports_string_literal(self):\n @tool\n def get_weather(unit: Literal[\"celsius\", \"fahrenheit\"] = \"celsius\") -> None:\n \"\"\"\n Get weather in the next days at given location.\n\n Args:\n unit: The unit of temperature\n \"\"\"\n return\n\n assert get_weather.inputs[\"unit\"][\"type\"] == \"string\"\n assert get_weather.inputs[\"unit\"][\"enum\"] == [\"celsius\", \"fahrenheit\"]\n\n def test_tool_supports_numeric_literal(self):\n @tool\n def get_choice(choice: Literal[1, 2, 3]) -> None:\n \"\"\"\n Get choice based on the provided numeric literal.\n\n Args:\n choice: The numeric choice to be made.\n \"\"\"\n return\n\n assert get_choice.inputs[\"choice\"][\"type\"] == \"integer\"\n assert get_choice.inputs[\"choice\"][\"enum\"] == [1, 2, 3]\n\n def test_tool_supports_nullable_literal(self):\n @tool\n def get_choice(choice: Literal[1, 2, 3, None]) -> None:\n \"\"\"\n Get choice based on the provided value.\n\n Args:\n choice: The numeric choice to be made.\n \"\"\"\n return\n\n assert get_choice.inputs[\"choice\"][\"type\"] == \"integer\"\n assert get_choice.inputs[\"choice\"][\"nullable\"] is True\n assert get_choice.inputs[\"choice\"][\"enum\"] == [1, 2, 3]\n\n def test_saving_tool_produces_valid_pyhon_code_with_multiline_description(self, tmp_path):\n @tool\n def get_weather(location: Any) -> None:\n \"\"\"\n Get weather in the next days at given location.\n And works pretty well.\n\n Args:\n location: The location to get the weather for.\n \"\"\"\n return\n\n get_weather.save(tmp_path)\n with open(os.path.join(tmp_path, \"tool.py\"), \"r\", encoding=\"utf-8\") as f:\n source_code = f.read()\n compile(source_code, f.name, \"exec\")\n\n @pytest.mark.parametrize(\"fixture_name\", [\"boolean_default_tool_class\", \"boolean_default_tool_function\"])\n def test_to_dict_boolean_default_input(self, fixture_name, request):\n \"\"\"Test that boolean input parameter with default value is correctly represented in to_dict output\"\"\"\n tool = request.getfixturevalue(fixture_name)\n result = tool.to_dict()\n # Check that the boolean default annotation is preserved\n assert \"flag: bool = False\" in result[\"code\"]\n # Check nullable attribute is set for the parameter with default value\n assert \"'nullable': True\" in result[\"code\"]\n\n @pytest.mark.parametrize(\"fixture_name\", [\"optional_input_tool_class\", \"optional_input_tool_function\"])\n def test_to_dict_optional_input(self, fixture_name, request):\n \"\"\"Test that Optional/nullable input parameter is correctly represented in to_dict output\"\"\"\n tool = request.getfixturevalue(fixture_name)\n result = tool.to_dict()\n # Check the Optional type annotation is preserved\n assert \"optional_text: str | None = None\" in result[\"code\"]\n # Check that the input is marked as nullable in the code\n assert \"'nullable': True\" in result[\"code\"]\n\n def test_from_dict_roundtrip(self, example_tool):\n # Convert to dict\n tool_dict = example_tool.to_dict()\n # Create from dict\n recreated_tool = Tool.from_dict(tool_dict)\n # Verify properties\n assert recreated_tool.name == example_tool.name\n assert recreated_tool.description == example_tool.description\n assert recreated_tool.inputs == example_tool.inputs\n assert recreated_tool.output_type == example_tool.output_type\n # Verify functionality\n test_input = \"Hello, world!\"\n assert recreated_tool(test_input) == test_input.upper()\n\n def test_tool_from_dict_invalid(self):\n # Missing code key\n with pytest.raises(ValueError) as e:\n Tool.from_dict({\"name\": \"invalid_tool\"})\n assert \"must contain 'code' key\" in str(e)\n\n def test_tool_decorator_preserves_original_function(self):\n # Define a test function with type hints and docstring\n def test_function(items: list[str]) -> str:\n \"\"\"Join a list of strings.\n Args:\n items: A list of strings to join\n Returns:\n The joined string\n \"\"\"\n return \", \".join(items)\n\n # Store original function signature, name, and source\n original_signature = inspect.signature(test_function)\n original_name = test_function.__name__\n original_docstring = test_function.__doc__\n\n # Create a tool from the function\n test_tool = tool(test_function)\n\n # Check that the original function is unchanged\n assert original_signature == inspect.signature(test_function)\n assert original_name == test_function.__name__\n assert original_docstring == test_function.__doc__\n\n # Verify that the tool's forward method has a different signature (it has 'self')\n tool_forward_sig = inspect.signature(test_tool.forward)\n assert list(tool_forward_sig.parameters.keys())[0] == \"self\"\n\n # Original function should not have 'self' parameter\n assert \"self\" not in original_signature.parameters\n\n def test_tool_with_union_type_return(self):\n @tool\n def union_type_return_tool_function(param: int) -> str | bool:\n \"\"\"\n Tool with output union type.\n\n Args:\n param: Input parameter.\n \"\"\"\n return str(param) if param > 0 else False\n\n assert isinstance(union_type_return_tool_function, Tool)\n assert union_type_return_tool_function.output_type == \"any\"\n\n\nclass TestToolDecorator:\n def test_tool_decorator_source_extraction_with_multiple_decorators(self):\n \"\"\"Test that @tool correctly extracts source code with multiple decorators.\"\"\"\n\n def dummy_decorator(func):\n return func\n\n with pytest.warns(UserWarning, match=\"has decorators other than @tool\"):\n\n @tool\n @dummy_decorator\n def multi_decorator_tool(text: str) -> str:\n \"\"\"Tool with multiple decorators.\n\n Args:\n text: Input text\n \"\"\"\n return text.upper()\n\n # Verify the tool works\n assert isinstance(multi_decorator_tool, Tool)\n assert multi_decorator_tool.name == \"multi_decorator_tool\"\n assert multi_decorator_tool(\"hello\") == \"HELLO\"\n\n # Verify the source code extraction is correct\n forward_source = multi_decorator_tool.forward.__source__\n assert \"def forward(self, text: str) -> str:\" in forward_source\n assert \"return text.upper()\" in forward_source\n # Should not contain decorator lines\n assert \"@tool\" not in forward_source\n assert \"@dummy_decorator\" not in forward_source\n # Should not contain definition line\n assert \"def multi_decorator_tool\" not in forward_source\n\n def test_tool_decorator_source_extraction_with_multiline_signature(self):\n \"\"\"Test that @tool correctly extracts source code with multiline function signatures.\"\"\"\n\n with warnings.catch_warnings():\n warnings.simplefilter(\"error\")\n\n @tool\n def multiline_signature_tool(\n text: str,\n count: int = 1,\n uppercase: bool = False,\n multiline_parameter_1: int = 1_000,\n multiline_parameter_2: int = 2_000,\n ) -> str:\n \"\"\"Tool with multiline signature.\n\n Args:\n text: Input text\n count: Number of repetitions\n uppercase: Whether to convert to uppercase\n multiline_parameter_1: Dummy parameter\n multiline_parameter_2: Dummy parameter\n \"\"\"\n result = text * count\n return result.upper() if uppercase else result\n\n # Verify the tool works\n assert isinstance(multiline_signature_tool, Tool)\n assert multiline_signature_tool.name == \"multiline_signature_tool\"\n assert multiline_signature_tool(\"hello\", 2, True) == \"HELLOHELLO\"\n\n # Verify the source code extraction is correct\n forward_source = multiline_signature_tool.forward.__source__\n assert (\n \"def forward(self, text: str, count: int=1, uppercase: bool=False, multiline_parameter_1: int=1000, multiline_parameter_2: int=2000) -> str:\"\n in forward_source\n or \"def forward(self, text: str, count: int = 1, uppercase: bool = False, multiline_parameter_1: int = 1000, multiline_parameter_2: int = 2000) -> str:\"\n in forward_source\n )\n assert \"result = text * count\" in forward_source\n assert \"return result.upper() if uppercase else result\" in forward_source\n # Should not contain the original multiline function definition\n assert \"def multiline_signature_tool(\" not in forward_source\n # Should not contain leftover lines from the original multiline function definition\n assert \" count: int = 1,\" not in forward_source\n assert \" count: int=1,\" not in forward_source\n\n def test_tool_decorator_source_extraction_with_multiple_decorators_and_multiline(self):\n \"\"\"Test that @tool works with both multiple decorators and multiline signatures.\"\"\"\n\n def dummy_decorator_1(func):\n return func\n\n def dummy_decorator_2(func):\n return func\n\n with pytest.warns(UserWarning, match=\"has decorators other than @tool\"):\n\n @tool\n @dummy_decorator_1\n @dummy_decorator_2\n def complex_tool(\n text: str,\n multiplier: int = 2,\n separator: str = \" \",\n multiline_parameter_1: int = 1_000,\n multiline_parameter_2: int = 2_000,\n ) -> str:\n \"\"\"Complex tool with multiple decorators and multiline signature.\n\n Args:\n text: Input text\n multiplier: How many times to repeat\n separator: What to use between repetitions\n multiline_parameter_1: Dummy parameter\n multiline_parameter_2: Dummy parameter\n \"\"\"\n parts = [text] * multiplier\n return separator.join(parts)\n\n # Verify the tool works\n assert isinstance(complex_tool, Tool)\n assert complex_tool.name == \"complex_tool\"\n assert complex_tool(\"hello\", 3, \"-\") == \"hello-hello-hello\"\n\n # Verify the source code extraction is correct\n forward_source = complex_tool.forward.__source__\n assert (\n \"def forward(self, text: str, multiplier: int=2, separator: str=' ', multiline_parameter_1: int=1000, multiline_parameter_2: int=2000) -> str:\"\n in forward_source\n or \"def forward(self, text: str, multiplier: int = 2, separator: str = ' ', multiline_parameter_1: int = 1000, multiline_parameter_2: int = 2000) -> str:\"\n in forward_source\n )\n assert \"parts = [text] * multiplier\" in forward_source\n assert \"return separator.join(parts)\" in forward_source\n # Should not contain any decorator lines\n assert \"@tool\" not in forward_source\n assert \"@dummy_decorator_1\" not in forward_source\n assert \"@dummy_decorator_2\" not in forward_source\n # Should not contain leftover lines from the original multiline function definition\n assert \" multiplier: int = 2,\" not in forward_source\n assert \" multiplier: int=2,\" not in forward_source\n\n\n@pytest.fixture\ndef mock_server_parameters():\n return MagicMock()\n\n\n@pytest.fixture\ndef mock_mcp_adapt():\n with patch(\"mcpadapt.core.MCPAdapt\") as mock:\n mock.return_value.__enter__.return_value = [\"tool1\", \"tool2\"]\n mock.return_value.__exit__.return_value = None\n yield mock\n\n\n@pytest.fixture\ndef mock_smolagents_adapter():\n with patch(\"mcpadapt.smolagents_adapter.SmolAgentsAdapter\") as mock:\n yield mock\n\n\n# Ignore FutureWarning about structured_output default value change: this test intentionally uses default behavior\n@pytest.mark.filterwarnings(\"ignore:.*structured_output:FutureWarning\")\nclass TestToolCollection:\n def test_from_mcp(self, mock_server_parameters, mock_mcp_adapt, mock_smolagents_adapter):\n with ToolCollection.from_mcp(mock_server_parameters, trust_remote_code=True) as tool_collection:\n assert isinstance(tool_collection, ToolCollection)\n assert len(tool_collection.tools) == 2\n assert \"tool1\" in tool_collection.tools\n assert \"tool2\" in tool_collection.tools\n\n @require_run_all\n def test_integration_from_mcp(self):\n # define the most simple mcp server with one tool that echoes the input text\n mcp_server_script = dedent(\"\"\"\\\n from mcp.server.fastmcp import FastMCP\n\n mcp = FastMCP(\"Echo Server\")\n\n @mcp.tool()\n def echo_tool(text: str) -> str:\n return text\n\n mcp.run()\n \"\"\").strip()\n\n mcp_server_params = mcp.StdioServerParameters(\n command=\"python\",\n args=[\"-c\", mcp_server_script],\n )\n\n with ToolCollection.from_mcp(mcp_server_params, trust_remote_code=True) as tool_collection:\n assert len(tool_collection.tools) == 1, \"Expected 1 tool\"\n assert tool_collection.tools[0].name == \"echo_tool\", \"Expected tool name to be 'echo_tool'\"\n assert tool_collection.tools[0](text=\"Hello\") == \"Hello\", \"Expected tool to echo the input text\"\n\n def test_integration_from_mcp_with_streamable_http(self):\n import subprocess\n import time\n\n # define the most simple mcp server with one tool that echoes the input text\n mcp_server_script = dedent(\"\"\"\\\n from mcp.server.fastmcp import FastMCP\n\n mcp = FastMCP(\"Echo Server\", host=\"127.0.0.1\", port=8000)\n\n @mcp.tool()\n def echo_tool(text: str) -> str:\n return text\n\n mcp.run(transport=\"streamable-http\")\n \"\"\").strip()\n\n # start the SSE mcp server in a subprocess\n server_process = subprocess.Popen(\n [\"python\", \"-c\", mcp_server_script],\n )\n\n # wait for the server to start\n time.sleep(1)\n\n try:\n with ToolCollection.from_mcp(\n {\"url\": \"http://127.0.0.1:8000/mcp\", \"transport\": \"streamable-http\"}, trust_remote_code=True\n ) as tool_collection:\n assert len(tool_collection.tools) == 1, \"Expected 1 tool\"\n assert tool_collection.tools[0].name == \"echo_tool\", \"Expected tool name to be 'echo_tool'\"\n assert tool_collection.tools[0](text=\"Hello\") == \"Hello\", \"Expected tool to echo the input text\"\n finally:\n # clean up the process when test is done\n server_process.kill()\n server_process.wait()\n\n def test_integration_from_mcp_with_sse(self):\n import subprocess\n import time\n\n # define the most simple mcp server with one tool that echoes the input text\n mcp_server_script = dedent(\"\"\"\\\n from mcp.server.fastmcp import FastMCP\n\n mcp = FastMCP(\"Echo Server\", host=\"127.0.0.1\", port=8000)\n\n @mcp.tool()\n def echo_tool(text: str) -> str:\n return text\n\n mcp.run(\"sse\")\n \"\"\").strip()\n\n # start the SSE mcp server in a subprocess\n server_process = subprocess.Popen(\n [\"python\", \"-c\", mcp_server_script],\n )\n\n # wait for the server to start\n time.sleep(1)\n\n try:\n with ToolCollection.from_mcp(\n {\"url\": \"http://127.0.0.1:8000/sse\", \"transport\": \"sse\"}, trust_remote_code=True\n ) as tool_collection:\n assert len(tool_collection.tools) == 1, \"Expected 1 tool\"\n assert tool_collection.tools[0].name == \"echo_tool\", \"Expected tool name to be 'echo_tool'\"\n assert tool_collection.tools[0](text=\"Hello\") == \"Hello\", \"Expected tool to echo the input text\"\n finally:\n # clean up the process when test is done\n server_process.kill()\n server_process.wait()\n\n\n@pytest.mark.parametrize(\"tool_fixture_name\", [\"boolean_default_tool_class\"])\ndef test_launch_gradio_demo_does_not_raise(tool_fixture_name, request):\n tool = request.getfixturevalue(tool_fixture_name)\n with patch(\"gradio.Interface.launch\") as mock_launch:\n launch_gradio_demo(tool)\n assert mock_launch.call_count == 1\n\n\n@pytest.mark.parametrize(\n \"tool_input_type, expected_input, expects_error\",\n [\n (bool, True, False),\n (str, \"b\", False),\n (int, 1, False),\n (float, 1, False),\n (list, [\"a\", \"b\"], False),\n (list[str], [\"a\", \"b\"], False),\n (dict[str, str], {\"a\": \"b\"}, False),\n (dict[str, str], \"b\", True),\n (bool, \"b\", True),\n (str | int, \"a\", False),\n (str | int, 1, False),\n (str | int, None, True),\n (str | int, True, True),\n ],\n)\ndef test_validate_tool_arguments(tool_input_type, expected_input, expects_error):\n @tool\n def test_tool(argument_a: tool_input_type) -> str:\n \"\"\"Fake tool\n\n Args:\n argument_a: The input\n \"\"\"\n return argument_a\n\n if expects_error:\n with pytest.raises((ValueError, TypeError)):\n validate_tool_arguments(test_tool, {\"argument_a\": expected_input})\n\n else:\n # Should not raise any exception\n validate_tool_arguments(test_tool, {\"argument_a\": expected_input})\n\n\n@pytest.mark.parametrize(\n \"scenario, type_hint, default, input_value, expected_error_message\",\n [\n # Required parameters (no default)\n # - Valid input\n (\"required_unsupported_none\", str, ..., \"text\", None),\n # - None not allowed\n (\"required_unsupported_none\", str, ..., None, \"Argument param has type 'null' but should be 'string'\"),\n # - Missing required parameter is not allowed\n (\"required_unsupported_none\", str, ..., ..., \"Argument param is required\"),\n #\n # Required parameters but supports None\n # - Valid input\n (\"required_supported_none\", str | None, ..., \"text\", None),\n # - None allowed\n (\"required_supported_none\", str | None, ..., None, None),\n # - Missing required parameter is not allowed\n # TODO: Fix this test case: property is marked as nullable because it can be None, but it can't be missing because it is required\n # (\"required_supported_none\", str | None, ..., ..., \"Argument param is required\"),\n pytest.param(\n \"required_supported_none\",\n str | None,\n ...,\n ...,\n \"Argument param is required\",\n marks=pytest.mark.skip(reason=\"TODO: Fix this test case\"),\n ),\n #\n # Optional parameters (has default, doesn't support None)\n # - Valid input\n (\"optional_unsupported_none\", str, \"default\", \"text\", None),\n # - None not allowed\n # TODO: Fix this test case: property is marked as nullable because it has a default value, but it can't be None\n # (\"optional_unsupported_none\", str, \"default\", None, \"Argument param has type 'null' but should be 'string'\"),\n pytest.param(\n \"optional_unsupported_none\",\n str,\n \"default\",\n None,\n \"Argument param has type 'null' but should be 'string'\",\n marks=pytest.mark.skip(reason=\"TODO: Fix this test case\"),\n ),\n # - Missing optional parameter is allowed\n (\"optional_unsupported_none\", str, \"default\", ..., None),\n #\n # Optional and supports None parameters with string default\n # - Valid input\n (\"optional_supported_none_str_default\", str | None, \"default\", \"text\", None),\n # - None allowed\n (\"optional_supported_none_str_default\", str | None, \"default\", None, None),\n # - Missing optional parameter is allowed\n (\"optional_supported_none_str_default\", str | None, \"default\", ..., None),\n #\n # Optional and supports None parameters with None default\n # - Valid input\n (\"optional_supported_none_none_default\", str | None, None, \"text\", None),\n # - None allowed\n (\"optional_supported_none_none_default\", str | None, None, None, None),\n # - Missing optional parameter is allowed\n (\"optional_supported_none_none_default\", str | None, None, ..., None),\n ],\n)\ndef test_validate_tool_arguments_nullable(scenario, type_hint, default, input_value, expected_error_message):\n \"\"\"Test validation of tool arguments with focus on nullable properties: optional (with default value) and supporting None value.\"\"\"\n\n # Create a tool with the appropriate signature\n if default is ...: # Using Ellipsis to indicate no default value\n\n @tool\n def test_tool(param: type_hint) -> str:\n \"\"\"Test tool.\n\n Args:\n param: Input param\n \"\"\"\n return str(param) if param is not None else \"NULL\"\n else:\n\n @tool\n def test_tool(param: type_hint = default) -> str:\n \"\"\"Test tool.\n\n Args:\n param: Input param.\n \"\"\"\n return str(param) if param is not None else \"NULL\"\n\n # Test with the input dictionary\n input_dict = {\"param\": input_value} if input_value is not ... else {}\n\n if expected_error_message:\n with pytest.raises((ValueError, TypeError), match=expected_error_message):\n validate_tool_arguments(test_tool, input_dict)\n else:\n # Should not raise any exception\n validate_tool_arguments(test_tool, input_dict)\n"
},
{
"path": "tests/test_types.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nimport os\nimport tempfile\nimport unittest\nimport uuid\n\nimport PIL.Image\n\nfrom smolagents.agent_types import AgentAudio, AgentImage, AgentText\n\nfrom .utils.markers import require_soundfile, require_torch\n\n\ndef get_new_path(suffix=\"\") -> str:\n directory = tempfile.mkdtemp()\n return os.path.join(directory, str(uuid.uuid4()) + suffix)\n\n\n@require_soundfile\n@require_torch\nclass AgentAudioTests(unittest.TestCase):\n def test_from_tensor(self):\n import soundfile as sf\n import torch\n\n tensor = torch.rand(12, dtype=torch.float64) - 0.5\n agent_type = AgentAudio(tensor)\n path = str(agent_type.to_string())\n\n # Ensure that the tensor and the agent_type's tensor are the same\n self.assertTrue(torch.allclose(tensor, agent_type.to_raw(), atol=1e-4))\n\n del agent_type\n\n # Ensure the path remains even after the object deletion\n self.assertTrue(os.path.exists(path))\n\n # Ensure that the file contains the same value as the original tensor\n new_tensor, _ = sf.read(path)\n self.assertTrue(torch.allclose(tensor, torch.tensor(new_tensor), atol=1e-4))\n\n def test_from_string(self):\n import soundfile as sf\n import torch\n\n tensor = torch.rand(12, dtype=torch.float64) - 0.5\n path = get_new_path(suffix=\".wav\")\n sf.write(path, tensor, 16000)\n\n agent_type = AgentAudio(path)\n\n self.assertTrue(torch.allclose(tensor, agent_type.to_raw(), atol=1e-4))\n self.assertEqual(agent_type.to_string(), path)\n\n\n@require_torch\nclass TestAgentImage:\n def test_from_tensor(self):\n import torch\n\n tensor = torch.randint(0, 256, (64, 64, 3))\n agent_type = AgentImage(tensor)\n path = str(agent_type.to_string())\n\n # Ensure that the tensor and the agent_type's tensor are the same\n assert torch.allclose(tensor, agent_type._tensor, atol=1e-4)\n\n assert isinstance(agent_type.to_raw(), PIL.Image.Image)\n\n # Ensure the path remains even after the object deletion\n del agent_type\n assert os.path.exists(path)\n\n def test_from_string(self, shared_datadir):\n path = shared_datadir / \"000000039769.png\"\n image = PIL.Image.open(path)\n agent_type = AgentImage(path)\n\n assert path.samefile(agent_type.to_string())\n assert image == agent_type.to_raw()\n\n # Ensure the path remains even after the object deletion\n del agent_type\n assert os.path.exists(path)\n\n def test_from_image(self, shared_datadir):\n path = shared_datadir / \"000000039769.png\"\n image = PIL.Image.open(path)\n agent_type = AgentImage(image)\n\n assert not path.samefile(agent_type.to_string())\n assert image == agent_type.to_raw()\n\n # Ensure the path remains even after the object deletion\n del agent_type\n assert os.path.exists(path)\n\n\nclass AgentTextTests(unittest.TestCase):\n def test_from_string(self):\n string = \"Hey!\"\n agent_type = AgentText(string)\n\n self.assertEqual(string, agent_type.to_string())\n self.assertEqual(string, agent_type.to_raw())\n"
},
{
"path": "tests/test_utils.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\nimport inspect\nimport os\nimport textwrap\nimport unittest\n\nimport pytest\nfrom IPython.core.interactiveshell import InteractiveShell\n\nfrom smolagents import Tool\nfrom smolagents.tools import tool\nfrom smolagents.utils import (\n create_agent_gradio_app_template,\n get_source,\n instance_to_source,\n is_valid_name,\n parse_code_blobs,\n parse_json_blob,\n)\n\n\nclass ValidTool(Tool):\n name = \"valid_tool\"\n description = \"A valid tool\"\n inputs = {\"input\": {\"type\": \"string\", \"description\": \"input\"}}\n output_type = \"string\"\n simple_attr = \"string\"\n dict_attr = {\"key\": \"value\"}\n\n def __init__(self, optional_param=\"default\"):\n super().__init__()\n self.param = optional_param\n\n def forward(self, input: str) -> str:\n return input.upper()\n\n\n@tool\ndef valid_tool_function(input: str) -> str:\n \"\"\"A valid tool function.\n\n Args:\n input (str): Input string.\n \"\"\"\n return input.upper()\n\n\nVALID_TOOL_SOURCE = \"\"\"\\\nfrom smolagents.tools import Tool\n\nclass ValidTool(Tool):\n name = \"valid_tool\"\n description = \"A valid tool\"\n inputs = {'input': {'type': 'string', 'description': 'input'}}\n output_type = \"string\"\n simple_attr = \"string\"\n dict_attr = {'key': 'value'}\n\n def __init__(self, optional_param=\"default\"):\n super().__init__()\n self.param = optional_param\n\n def forward(self, input: str) -> str:\n return input.upper()\n\"\"\"\n\nVALID_TOOL_FUNCTION_SOURCE = '''\\\nfrom smolagents.tools import Tool\n\nclass SimpleTool(Tool):\n name = \"valid_tool_function\"\n description = \"A valid tool function.\"\n inputs = {'input': {'type': 'string', 'description': 'Input string.'}}\n output_type = \"string\"\n\n def __init__(self):\n self.is_initialized = True\n\n def forward(self, input: str) -> str:\n \"\"\"A valid tool function.\n\n Args:\n input (str): Input string.\n \"\"\"\n return input.upper()\n'''\n\n\nclass AgentTextTests(unittest.TestCase):\n def test_parse_code_blobs(self):\n with pytest.raises(ValueError):\n parse_code_blobs(\"Wrong blob!\", (\"\", \"\"))\n\n # Parsing mardkwon with code blobs should work\n output = parse_code_blobs(\n \"\"\"\nHere is how to solve the problem:\n\nimport numpy as np\n\n\"\"\",\n (\"\", \"\"),\n )\n assert output == \"import numpy as np\"\n\n # Parsing pure python code blobs should work\n code_blob = \"import numpy as np\"\n output = parse_code_blobs(code_blob, (\"```python\", \"```\"))\n assert output == code_blob\n\n # Allow whitespaces after header\n output = parse_code_blobs(\" \\ncode_a\\n\", (\"\", \"\"))\n assert output == \"code_a\"\n\n # Parsing markdown with code blobs should work\n output = parse_code_blobs(\n \"\"\"\nHere is how to solve the problem:\n```python\nimport numpy as np\n```\n\"\"\",\n (\"\", \"\"),\n )\n assert output == \"import numpy as np\"\n\n def test_multiple_code_blobs(self):\n test_input = \"\\nFoo\\n\\n\\n\\ncode_a\\n\\n\\n\\ncode_b\\n\"\n result = parse_code_blobs(test_input, (\"\", \"\"))\n assert result == \"Foo\\n\\ncode_a\\n\\ncode_b\"\n\n\n@pytest.fixture(scope=\"function\")\ndef ipython_shell():\n \"\"\"Reset IPython shell before and after each test.\"\"\"\n shell = InteractiveShell.instance()\n shell.reset() # Clean before test\n yield shell\n shell.reset() # Clean after test\n\n\n@pytest.mark.parametrize(\n \"obj_name, code_blob\",\n [\n (\"test_func\", \"def test_func():\\n return 42\"),\n (\"TestClass\", \"class TestClass:\\n ...\"),\n ],\n)\ndef test_get_source_ipython(ipython_shell, obj_name, code_blob):\n ipython_shell.run_cell(code_blob, store_history=True)\n obj = ipython_shell.user_ns[obj_name]\n assert get_source(obj) == code_blob\n\n\ndef test_get_source_standard_class():\n class TestClass: ...\n\n source = get_source(TestClass)\n assert source == \"class TestClass: ...\"\n assert source == textwrap.dedent(inspect.getsource(TestClass)).strip()\n\n\ndef test_get_source_standard_function():\n def test_func(): ...\n\n source = get_source(test_func)\n assert source == \"def test_func(): ...\"\n assert source == textwrap.dedent(inspect.getsource(test_func)).strip()\n\n\ndef test_get_source_ipython_errors_empty_cells(ipython_shell):\n test_code = textwrap.dedent(\"\"\"class TestClass:\\n ...\"\"\").strip()\n ipython_shell.user_ns[\"In\"] = [\"\"]\n ipython_shell.run_cell(test_code, store_history=True)\n with pytest.raises(ValueError, match=\"No code cells found in IPython session\"):\n get_source(ipython_shell.user_ns[\"TestClass\"])\n\n\ndef test_get_source_ipython_errors_definition_not_found(ipython_shell):\n test_code = textwrap.dedent(\"\"\"class TestClass:\\n ...\"\"\").strip()\n ipython_shell.user_ns[\"In\"] = [\"\", \"print('No class definition here')\"]\n ipython_shell.run_cell(test_code, store_history=True)\n with pytest.raises(ValueError, match=\"Could not find source code for TestClass in IPython history\"):\n get_source(ipython_shell.user_ns[\"TestClass\"])\n\n\ndef test_get_source_ipython_errors_type_error():\n with pytest.raises(TypeError, match=\"Expected class or callable\"):\n get_source(None)\n\n\n@pytest.mark.parametrize(\n \"tool, expected_tool_source\", [(ValidTool(), VALID_TOOL_SOURCE), (valid_tool_function, VALID_TOOL_FUNCTION_SOURCE)]\n)\ndef test_instance_to_source(tool, expected_tool_source):\n tool_source = instance_to_source(tool, base_cls=Tool)\n assert tool_source == expected_tool_source\n\n\ndef test_e2e_class_tool_save(tmp_path):\n class TestTool(Tool):\n name = \"test_tool\"\n description = \"Test tool description\"\n inputs = {\n \"task\": {\n \"type\": \"string\",\n \"description\": \"tool input\",\n }\n }\n output_type = \"string\"\n\n def forward(self, task: str):\n import IPython # noqa: F401\n\n return task\n\n test_tool = TestTool()\n test_tool.save(tmp_path, make_gradio_app=True)\n assert set(os.listdir(tmp_path)) == {\"requirements.txt\", \"app.py\", \"tool.py\"}\n assert (tmp_path / \"tool.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from typing import Any, Optional\n from smolagents.tools import Tool\n import IPython\n\n class TestTool(Tool):\n name = \"test_tool\"\n description = \"Test tool description\"\n inputs = {'task': {'type': 'string', 'description': 'tool input'}}\n output_type = \"string\"\n\n def forward(self, task: str):\n import IPython # noqa: F401\n\n return task\n\n def __init__(self, *args, **kwargs):\n self.is_initialized = False\n \"\"\"\n )\n requirements = set((tmp_path / \"requirements.txt\").read_text().split())\n assert requirements == {\"IPython\", \"smolagents\"}\n assert (tmp_path / \"app.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from smolagents import launch_gradio_demo\n from tool import TestTool\n\n tool = TestTool()\n launch_gradio_demo(tool)\n \"\"\"\n )\n\n\ndef test_e2e_ipython_class_tool_save(tmp_path):\n shell = InteractiveShell.instance()\n code_blob = textwrap.dedent(\n f\"\"\"\\\n from smolagents.tools import Tool\n class TestTool(Tool):\n name = \"test_tool\"\n description = \"Test tool description\"\n inputs = {{\"task\": {{\"type\": \"string\",\n \"description\": \"tool input\",\n }}\n }}\n output_type = \"string\"\n\n def forward(self, task: str):\n import IPython # noqa: F401\n\n return task\n TestTool().save(\"{tmp_path}\", make_gradio_app=True)\n \"\"\"\n )\n assert shell.run_cell(code_blob, store_history=True).success\n assert set(os.listdir(tmp_path)) == {\"requirements.txt\", \"app.py\", \"tool.py\"}\n assert (tmp_path / \"tool.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from typing import Any, Optional\n from smolagents.tools import Tool\n import IPython\n\n class TestTool(Tool):\n name = \"test_tool\"\n description = \"Test tool description\"\n inputs = {'task': {'type': 'string', 'description': 'tool input'}}\n output_type = \"string\"\n\n def forward(self, task: str):\n import IPython # noqa: F401\n\n return task\n\n def __init__(self, *args, **kwargs):\n self.is_initialized = False\n \"\"\"\n )\n requirements = set((tmp_path / \"requirements.txt\").read_text().split())\n assert requirements == {\"IPython\", \"smolagents\"}\n assert (tmp_path / \"app.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from smolagents import launch_gradio_demo\n from tool import TestTool\n\n tool = TestTool()\n launch_gradio_demo(tool)\n \"\"\"\n )\n\n\ndef test_e2e_function_tool_save(tmp_path):\n @tool\n def test_tool(task: str) -> str:\n \"\"\"\n Test tool description\n\n Args:\n task: tool input\n \"\"\"\n import IPython # noqa: F401\n\n return task\n\n test_tool.save(tmp_path, make_gradio_app=True)\n assert set(os.listdir(tmp_path)) == {\"requirements.txt\", \"app.py\", \"tool.py\"}\n assert (tmp_path / \"tool.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from smolagents import Tool\n from typing import Any, Optional\n\n class SimpleTool(Tool):\n name = \"test_tool\"\n description = \"Test tool description\"\n inputs = {'task': {'type': 'string', 'description': 'tool input'}}\n output_type = \"string\"\n\n def forward(self, task: str) -> str:\n \\\"\"\"\n Test tool description\n\n Args:\n task: tool input\n \\\"\"\"\n import IPython # noqa: F401\n\n return task\"\"\"\n )\n requirements = set((tmp_path / \"requirements.txt\").read_text().split())\n assert requirements == {\"smolagents\"} # FIXME: IPython should be in the requirements\n assert (tmp_path / \"app.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from smolagents import launch_gradio_demo\n from tool import SimpleTool\n\n tool = SimpleTool()\n launch_gradio_demo(tool)\n \"\"\"\n )\n\n\ndef test_e2e_ipython_function_tool_save(tmp_path):\n shell = InteractiveShell.instance()\n code_blob = textwrap.dedent(\n f\"\"\"\n from smolagents import tool\n\n @tool\n def test_tool(task: str) -> str:\n \\\"\"\"\n Test tool description\n\n Args:\n task: tool input\n \\\"\"\"\n import IPython # noqa: F401\n\n return task\n\n test_tool.save(\"{tmp_path}\", make_gradio_app=True)\n \"\"\"\n )\n assert shell.run_cell(code_blob, store_history=True).success\n assert set(os.listdir(tmp_path)) == {\"requirements.txt\", \"app.py\", \"tool.py\"}\n assert (tmp_path / \"tool.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from smolagents import Tool\n from typing import Any, Optional\n\n class SimpleTool(Tool):\n name = \"test_tool\"\n description = \"Test tool description\"\n inputs = {'task': {'type': 'string', 'description': 'tool input'}}\n output_type = \"string\"\n\n def forward(self, task: str) -> str:\n \\\"\"\"\n Test tool description\n\n Args:\n task: tool input\n \\\"\"\"\n import IPython # noqa: F401\n\n return task\"\"\"\n )\n requirements = set((tmp_path / \"requirements.txt\").read_text().split())\n assert requirements == {\"smolagents\"} # FIXME: IPython should be in the requirements\n assert (tmp_path / \"app.py\").read_text() == textwrap.dedent(\n \"\"\"\\\n from smolagents import launch_gradio_demo\n from tool import SimpleTool\n\n tool = SimpleTool()\n launch_gradio_demo(tool)\n \"\"\"\n )\n\n\n@pytest.mark.parametrize(\n \"raw_json, expected_data, expected_blob\",\n [\n (\n \"\"\"{}\"\"\",\n {},\n \"\",\n ),\n (\n \"\"\"Text{}\"\"\",\n {},\n \"Text\",\n ),\n (\n \"\"\"{\"simple\": \"json\"}\"\"\",\n {\"simple\": \"json\"},\n \"\",\n ),\n (\n \"\"\"With text here{\"simple\": \"json\"}\"\"\",\n {\"simple\": \"json\"},\n \"With text here\",\n ),\n (\n \"\"\"{\"simple\": \"json\"}With text after\"\"\",\n {\"simple\": \"json\"},\n \"\",\n ),\n (\n \"\"\"With text before{\"simple\": \"json\"}And text after\"\"\",\n {\"simple\": \"json\"},\n \"With text before\",\n ),\n ],\n)\ndef test_parse_json_blob_with_valid_json(raw_json, expected_data, expected_blob):\n data, blob = parse_json_blob(raw_json)\n\n assert data == expected_data\n assert blob == expected_blob\n\n\n@pytest.mark.parametrize(\n \"raw_json\",\n [\n \"\"\"simple\": \"json\"}\"\"\",\n \"\"\"With text here\"simple\": \"json\"}\"\"\",\n \"\"\"{\"simple\": \"\"json\"}With text after\"\"\",\n \"\"\"{\"simple\": \"json\"With text after\"\"\",\n \"}}\",\n ],\n)\ndef test_parse_json_blob_with_invalid_json(raw_json):\n with pytest.raises(Exception):\n parse_json_blob(raw_json)\n\n\n@pytest.mark.parametrize(\n \"name,expected\",\n [\n # Valid identifiers\n (\"valid_name\", True),\n (\"ValidName\", True),\n (\"valid123\", True),\n (\"_private\", True),\n # Invalid identifiers\n (\"\", False),\n (\"123invalid\", False),\n (\"invalid-name\", False),\n (\"invalid name\", False),\n (\"invalid.name\", False),\n # Python keywords\n (\"if\", False),\n (\"for\", False),\n (\"class\", False),\n (\"return\", False),\n # Non-string inputs\n (123, False),\n (None, False),\n ([], False),\n ({}, False),\n ],\n)\ndef test_is_valid_name(name, expected):\n \"\"\"Test the is_valid_name function with various inputs.\"\"\"\n assert is_valid_name(name) is expected\n\n\ndef test_agent_gradio_app_template_excludes_class_keyword():\n \"\"\"Test that the AGENT_GRADIO_APP_TEMPLATE excludes 'class' from agent kwargs.\"\"\"\n\n # Mock agent_dict with 'class' key that should be excluded\n agent_dict = {\n \"model\": {\"class\": \"CodeAgent\", \"data\": {}},\n \"class\": \"CodeAgent\", # This should be excluded to prevent SyntaxError\n \"some_valid_attr\": \"value\",\n \"tools\": [],\n \"managed_agents\": {},\n \"requirements\": [],\n \"prompt_templates\": {},\n }\n\n template = create_agent_gradio_app_template()\n result = template.render(\n agent_name=\"test_agent\",\n class_name=\"CodeAgent\",\n agent_dict=agent_dict,\n tools={},\n managed_agents={},\n managed_agent_relative_path=\"\",\n )\n\n # Should contain valid attribute but not 'class=' as a keyword argument\n assert \"some_valid_attr='value',\" in result\n assert \"class=\" not in result\n\n # Verify the generated code is syntactically valid Python\n import ast\n\n try:\n ast.parse(result)\n except SyntaxError as e:\n pytest.fail(f\"Generated app.py contains syntax error: {e}\")\n"
},
{
"path": "tests/test_vision_web_browser.py",
"content": "\"\"\"Test XPath injection vulnerability fix in vision_web_browser.py\"\"\"\n\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom smolagents.vision_web_browser import _escape_xpath_string, search_item_ctrl_f\n\n\n@pytest.fixture\ndef mock_driver():\n \"\"\"Mock Selenium WebDriver\"\"\"\n driver = Mock()\n driver.find_elements.return_value = [Mock()] # Mock found elements\n driver.execute_script.return_value = None\n return driver\n\n\nclass TestXPathEscaping:\n \"\"\"Test XPath string escaping functionality\"\"\"\n\n @pytest.mark.parametrize(\n \"input_text,expected_pattern\",\n [\n (\"normal text\", \"'normal text'\"),\n (\"text with 'quote'\", \"\\\"text with 'quote'\\\"\"),\n ('text with \"quote\"', \"'text with \\\"quote\\\"'\"),\n (\"text with one single'quote\", '\"text with one single\\'quote\"'),\n ('text with one double\"quote', \"'text with one double\\\"quote'\"),\n (\n \"text with both 'single' and \\\"double\\\" quotes\",\n \"concat('text with both ', \\\"'\\\", 'single', \\\"'\\\", ' and \\\"double\\\" quotes')\",\n ),\n (\"\", \"''\"),\n (\"'\", '\"\\'\"'),\n ('\"', \"'\\\"'\"),\n ],\n )\n def test_escape_xpath_string_basic(self, input_text, expected_pattern):\n \"\"\"Test basic XPath escaping cases\"\"\"\n result = _escape_xpath_string(input_text)\n assert result == expected_pattern\n\n @pytest.mark.parametrize(\n \"input_text\",\n [\n \"text with both 'single' and \\\"double\\\" quotes\",\n 'it\\'s a \"test\" case',\n \"'mixed\\\" quotes'\",\n ],\n )\n def test_escape_xpath_string_mixed_quotes(self, input_text):\n \"\"\"Test XPath escaping with mixed quotes uses concat()\"\"\"\n result = _escape_xpath_string(input_text)\n assert result.startswith(\"concat(\")\n assert result.endswith(\")\")\n\n @pytest.mark.parametrize(\n \"malicious_input\",\n [\n \"')] | //script[@src='evil.js'] | foo[contains(text(), '\",\n \"') or 1=1 or ('\",\n \"')] | //user[contains(@role,'admin')] | foo[contains(text(), '\",\n \"') and substring(//user[1]/password,1,1)='a\",\n ],\n )\n def test_escape_prevents_injection(self, malicious_input):\n \"\"\"Test that malicious XPath injection attempts are safely escaped\"\"\"\n result = _escape_xpath_string(malicious_input)\n # Should either be wrapped in quotes or use concat()\n assert (\n (result.startswith(\"'\") and result.endswith(\"'\"))\n or (result.startswith('\"') and result.endswith('\"'))\n or result.startswith(\"concat(\")\n )\n\n\nclass TestSearchItemCtrlF:\n \"\"\"Test the search_item_ctrl_f function with XPath injection protection\"\"\"\n\n @pytest.mark.parametrize(\n \"search_text\",\n [\n \"normal search\",\n \"search with 'quotes'\",\n 'search with \"quotes\"',\n \"')] | //script[@src='evil.js'] | foo[contains(text(), '\",\n \"') or 1=1 or ('\",\n ],\n )\n def test_search_item_prevents_injection(self, search_text, mock_driver):\n \"\"\"Test that search_item_ctrl_f prevents XPath injection\"\"\"\n with patch(\"smolagents.vision_web_browser.driver\", mock_driver, create=True):\n # Call the function\n result = search_item_ctrl_f(search_text)\n\n # Verify driver.find_elements was called\n mock_driver.find_elements.assert_called_once()\n\n # Get the actual XPath query that was generated\n call_args = mock_driver.find_elements.call_args\n xpath_query = call_args[0][1] # Second positional argument\n\n # Verify the query doesn't contain unescaped injection\n if \"')] | //\" in search_text:\n # For injection attempts, verify they're properly escaped\n # The query should either use concat() or be properly quoted\n is_concat = \"concat(\" in xpath_query\n is_properly_quoted = xpath_query.count('\"') >= 2 or xpath_query.count(\"'\") >= 2\n assert is_concat or is_properly_quoted, f\"XPath injection not prevented: {xpath_query}\"\n\n # Verify we got a result\n assert \"Found\" in result\n\n def test_search_item_nth_result(self, mock_driver):\n \"\"\"Test nth_result parameter works correctly\"\"\"\n mock_driver.find_elements.return_value = [Mock(), Mock(), Mock()] # 3 elements\n\n with patch(\"smolagents.vision_web_browser.driver\", mock_driver, create=True):\n result = search_item_ctrl_f(\"test\", nth_result=2)\n\n # Should find 3 matches and focus on element 2\n assert \"Found 3 matches\" in result\n assert \"Focused on element 2 of 3\" in result\n\n def test_search_item_not_found(self, mock_driver):\n \"\"\"Test exception when nth_result exceeds available matches\"\"\"\n mock_driver.find_elements.return_value = [Mock()] # Only 1 element\n\n with patch(\"smolagents.vision_web_browser.driver\", mock_driver, create=True):\n with pytest.raises(Exception, match=\"Match n°3 not found\"):\n search_item_ctrl_f(\"test\", nth_result=3)\n"
},
{
"path": "tests/utils/markers.py",
"content": "# coding=utf-8\n# Copyright 2024 HuggingFace Inc.\n#\n# Licensed under the Apache License, Version 2.0 (the \"License\");\n# you may not use this file except in compliance with the License.\n# You may obtain a copy of the License at\n#\n# http://www.apache.org/licenses/LICENSE-2.0\n#\n# Unless required by applicable law or agreed to in writing, software\n# distributed under the License is distributed on an \"AS IS\" BASIS,\n# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n# See the License for the specific language governing permissions and\n# limitations under the License.\n\"\"\"Markers for tests .\"\"\"\n\nimport os\nfrom importlib.util import find_spec\n\nimport pytest\n\n\nrequire_run_all = pytest.mark.skipif(not os.getenv(\"RUN_ALL\"), reason=\"requires RUN_ALL environment variable\")\nrequire_soundfile = pytest.mark.skipif(find_spec(\"soundfile\") is None, reason=\"requires soundfile\")\nrequire_torch = pytest.mark.skipif(find_spec(\"torch\") is None, reason=\"requires torch\")\n"
}
]