Building AI agents, atomically
Enhance Calculator and YouTube Transcript Tool readmes and improve youtube transcript scraper schema
KennyVaneetveldef0868d60aa96
diff --git a/atomic-forge/atomic_tools/calculator/README.md b/atomic-forge/atomic_tools/calculator/README.mdindex 4359eb6..9405842 100644--- a/atomic-forge/atomic_tools/calculator/README.md+++ b/atomic-forge/atomic_tools/calculator/README.md@@ -1,20 +1,53 @@# Calculator Tool## Overview-The Calculator Tool is a Python-based utility designed for performing a variety of mathematical calculations. It supports basic arithmetic operations such as addition, subtraction, multiplication, and division, as well as more complex operations including exponentiation and trigonometric functions. This tool is built using the Pydantic library for input validation and the SymPy library for expression evaluation.+The Calculator Tool is a Python-based utility within the Atomic Agents ecosystem designed for performing a variety of mathematical calculations. It supports basic arithmetic operations such as addition, subtraction, multiplication, and division, as well as more complex operations including exponentiation and trigonometric functions.-## Features-- Evaluate mathematical expressions.-- Support for basic and complex arithmetic operations.-- Input validation using Pydantic.-- User-friendly output formatting with Rich.+## Installation+You can install the tool using any of the following options:-## Example Usage+1. Using the CLI tool that comes with Atomic Agents. Simply run `atomic` and select the tool from the list of available tools. After doing so you will be asked for a target directory to download the tool into.+2. Good old fashioned copy/paste: Just like any other tool inside the Atomic Forge, you can copy the code from this repo directly into your own project, provided you already have atomic-agents installed according to the instructions in the main [README](/README.md).++## Input & Output Structure++### Input Schema+- `expression` (str): Mathematical expression to evaluate. For example, '2 + 2'.++### Output Schema+- `result` (str): Result of the calculation.++## Usage++Here's an example of how to use the Calculator Tool:```python-from calculator_tool import CalculatorTool+from tool.calculator import CalculatorTool, CalculatorToolConfig++# Initialize the tool+calculator = CalculatorTool(config=CalculatorToolConfig())++# Define input data+input_data = CalculatorTool.input_schema(+ expression="sin(pi/2) + cos(pi/4)"+)-calculator = CalculatorTool()-result = calculator.run(expression="sin(pi/2) + cos(pi/4)")-print(result) # Output: 1.853981633974483+# Perform the calculation+result = calculator.run(input_data)+print(result) # Expected output: {"result":"1.70710678118655"}```++## Contributing++Contributions are welcome! To contribute:++1. Fork the repository.+2. Create a new feature branch.+3. Commit your changes with clear messages.+4. Open a pull request detailing your changes.++Please ensure you follow the project's coding standards and include tests for any new features or bug fixes.++## License++This project is licensed under the same license as the main Atomic Agents project. See the [LICENSE](LICENSE) file in the repository root for more details.diff --git a/atomic-forge/atomic_tools/calculator/requirements.txt b/atomic-forge/atomic_tools/calculator/requirements.txtnew file mode 100644index 0000000..06f7f35--- /dev/null+++ b/atomic-forge/atomic_tools/calculator/requirements.txt@@ -0,0 +1,3 @@+atomic-agents>=1.0.0,<2.0.0+pydantic>=2.8.2,<3.0.0+sympy>=1.12,<2.0.0diff --git a/atomic-forge/atomic_tools/youtube_transcript_scraper/README.md b/atomic-forge/atomic_tools/youtube_transcript_scraper/README.mdindex 8972d96..bc9267e 100644--- a/atomic-forge/atomic_tools/youtube_transcript_scraper/README.md+++ b/atomic-forge/atomic_tools/youtube_transcript_scraper/README.md@@ -6,7 +6,8 @@ The **YouTube Transcript Scraper Tool** is a tool within the Atomic Agents ecosy## InstallationYou can install the tool using any of the following options:-1. Good old fashioned copy/paste: Just like any other tool inside the Atomic Forge, you can copy the code from this repo directly into your own project, provided you already have atomic-agents installed according to the instructions in the main [README](/README.md).+1. Using the CLI tool that comes with Atomic Agents. Simply run `atomic` and select the tool from the list of available tools. After doing so you will be asked for a target directory to download the tool into.+2. Good old fashioned copy/paste: Just like any other tool inside the Atomic Forge, you can copy the code from this repo directly into your own project, provided you already have atomic-agents installed according to the instructions in the main [README](/README.md).## Configuration@@ -32,7 +33,17 @@ To use this tool, you'll need a YouTube API key. Follow these steps to obtain on- Click on "Create Credentials" and select "API Key."- Copy the generated API key and add it to your `.env` file as shown above.-> **Note:** Keep your API key secure and avoid sharing it publicly.+## Input & Output Structure++### Input Schema+- `video_url` (str): URL of the YouTube video to fetch the transcript for.+- `language` (Optional[str]): Language code for the transcript (e.g., `'en'` for English).++### Output Schema+- `transcript` (str): Transcript of the YouTube video.+- `duration` (float): Duration of the YouTube video.+- `comments` (List[str]): Comments on the YouTube video.+- `metadata` (dict): Metadata of the YouTube video.## Usage@@ -56,25 +67,6 @@ result = transcript_tool.run(input_data)print(result)```-## Input & Output Structure--### Input Schema-- `video_url` (str): URL of the YouTube video to fetch the transcript for.-- `language` (Optional[str]): Language code for the transcript (e.g., `'en'` for English).--### Output Schema-- `transcript` (str): Transcript of the YouTube video.-- `duration` (float): Duration of the YouTube video.-- `comments` (List[str]): Comments on the YouTube video.-- `metadata` (dict): Metadata of the YouTube video.--## Error Handling--The tool includes comprehensive error handling to manage common issues such as:-- Invalid video URLs.-- Missing transcripts in the specified language.-- API rate limits and authentication errors.-## ContributingContributions are welcome! To contribute:diff --git a/atomic-forge/atomic_tools/youtube_transcript_scraper/example.env b/atomic-forge/atomic_tools/youtube_transcript_scraper/example.envdeleted file mode 100644index fdd25c2..0000000--- a/atomic-forge/atomic_tools/youtube_transcript_scraper/example.env+++ /dev/null@@ -1 +0,0 @@-YOUTUBE_API_KEY=1234567890diff --git a/atomic-forge/atomic_tools/youtube_transcript_scraper/poetry.lock b/atomic-forge/atomic_tools/youtube_transcript_scraper/poetry.lockindex a19fd5b..099379a 100644--- a/atomic-forge/atomic_tools/youtube_transcript_scraper/poetry.lock+++ b/atomic-forge/atomic_tools/youtube_transcript_scraper/poetry.lock@@ -1789,4 +1789,4 @@ requests = "*"[metadata]lock-version = "2.0"python-versions = ">=3.12,<4"-content-hash = "402613e4bc0971df5a0cdd5e8c5fa391be379a1f9d9917c512b52bd7510356a2"+content-hash = "68ac8186d64465d028554b51f68b72ee4422e652da5d161aab47b31f616a7b5f"diff --git a/atomic-forge/atomic_tools/youtube_transcript_scraper/requirements.txt b/atomic-forge/atomic_tools/youtube_transcript_scraper/requirements.txtnew file mode 100644index 0000000..a5174c2--- /dev/null+++ b/atomic-forge/atomic_tools/youtube_transcript_scraper/requirements.txt@@ -0,0 +1,4 @@+atomic-agents>=1.0.0,<2.0.0+google-api-python-client>=2.118.0,<3.0.0+pydantic>=2.8.2,<3.0.0+youtube-transcript-api>=0.6.2,<1.0.0diff --git a/atomic-forge/atomic_tools/youtube_transcript_scraper/tool/youtube_transcript_scraper.py b/atomic-forge/atomic_tools/youtube_transcript_scraper/tool/youtube_transcript_scraper.pyindex 8a937d4..0ee5a0f 100644--- a/atomic-forge/atomic_tools/youtube_transcript_scraper/tool/youtube_transcript_scraper.py+++ b/atomic-forge/atomic_tools/youtube_transcript_scraper/tool/youtube_transcript_scraper.py@@ -1,8 +1,9 @@import osfrom typing import List, Optional+from pydantic import Field, BaseModel+from datetime import datetimefrom googleapiclient.discovery import build-from pydantic import Fieldfrom youtube_transcript_api import (NoTranscriptFound,TranscriptsDisabled,@@ -29,15 +30,24 @@ class YouTubeTranscriptToolInputSchema(BaseIOSchema):################## OUTPUT SCHEMA ##################+class VideoMetadata(BaseModel):+ """Schema for YouTube video metadata."""++ id: str = Field(..., description="The YouTube video ID.")+ title: str = Field(..., description="The title of the YouTube video.")+ channel: str = Field(..., description="The name of the YouTube channel.")+ published_at: datetime = Field(..., description="The publication date and time of the video.")++class YouTubeTranscriptToolOutputSchema(BaseIOSchema):"""Output schema for the YouTubeTranscriptTool. Contains the transcript text, duration, comments, and metadata."""transcript: str = Field(..., description="Transcript of the YouTube video.")- duration: float = Field(..., description="Duration of the YouTube video.")- comments: List[str] = Field(..., description="Comments on the YouTube video.")- metadata: dict = Field(..., description="Metadata of the YouTube video.")+ duration: float = Field(..., description="Duration of the YouTube video in seconds.")+ comments: List[str] = Field(default_factory=list, description="Comments on the YouTube video.")+ metadata: VideoMetadata = Field(..., description="Metadata of the YouTube video.")#################@@ -122,7 +132,7 @@ class YouTubeTranscriptTool(BaseTool):"""return url.split("v=")[-1].split("&")[0]- def fetch_video_metadata(self, video_id: str) -> dict:+ def fetch_video_metadata(self, video_id: str) -> VideoMetadata:"""Fetches metadata for a YouTube video.@@ -130,7 +140,10 @@ class YouTubeTranscriptTool(BaseTool):video_id (str): The YouTube video ID.Returns:- dict: The metadata of the video.+ VideoMetadata: The metadata of the video.++ Raises:+ Exception: If no metadata is found for the video."""youtube = build("youtube", "v3", developerKey=self.api_key)request = youtube.videos().list(part="snippet", id=video_id)@@ -140,13 +153,12 @@ class YouTubeTranscriptTool(BaseTool):raise Exception(f"No metadata found for video '{video_id}'")video_info = response["items"][0]["snippet"]- metadata = {- "id": video_id,- "title": video_info["title"],- "channel": video_info["channelTitle"],- "published_at": video_info["publishedAt"],- }- return metadata+ return VideoMetadata(+ id=video_id,+ title=video_info["title"],+ channel=video_info["channelTitle"],+ published_at=datetime.fromisoformat(video_info["publishedAt"].rstrip("Z")),+ )#################diff --git a/atomic-forge/docs/tool_structure.md b/atomic-forge/docs/tool_structure.mdindex 488dae2..4dc42c1 100644--- a/atomic-forge/docs/tool_structure.md+++ b/atomic-forge/docs/tool_structure.md@@ -5,7 +5,8 @@This guide aims to explain the anatomy of an **Atomic Tool** within the **Atomic Agents** framework and help you get started adding your own tools, either to your own project or to the repository to share with others. We'll walk through the entire process step-by-step, using a mock **Pizza Ordering Tool** as our running example.## Prerequisites-- **uv**: Install the [uv](https://docs.astral.sh/uv/) dependency manager.++Set up the main Atomic Agents library for development by following the instructions in the [development setup guide](/guides/dev-setup.md).## The Principles@@ -23,6 +24,7 @@ An **Atomic Tool** should always be self-contained and modular. This means it sh## Anatomy of an Atomic Tool### Folder Structure+Each tool should be placed in its own folder with the following structure:```@@ -31,7 +33,7 @@ tool_name/│ pyproject.toml│ README.md│ requirements.txt-│ uv.lock+│ poetry.lock│├── tool/│ │ tool_name.py@@ -44,12 +46,64 @@ tool_name/│ test_another_util_file.py```-In order to keep things modular and organized, you should place your tool code in the `tool/` folder and your test code in the `tests/` folder. Other than that, there are the following files to consider:-- `pyproject.toml`: This is the Python project file that contains metadata about your project and its dependencies. It is used by [`uv`](https://docs.astral.sh/uv/) to install dependencies and run the tool. Remember to run `uv venv` before starting development to make sure you are working in a clean stand-alone environment.-- `README.md`: This is the readme file that contains information about your tool. This is where you will add information about how to use your tool, its purpose, environment variables, etc. Be sure to look at existing READMEs for examples.-- `requirements.txt`: This is the requirements file that contains just the runtime dependencies for your tool. These should match exactly the dependencies in `pyproject.toml` without any development dependencies.-- `.coveragerc`: This is the coverage configuration file that contains the configuration for the coverage tool. This file is the same accross all tools and should always be included.-- `uv.lock`: This is the lock file that contains the exact versions of the dependencies that were installed when `uv sync` was last run. This file should be committed as well.+To keep things modular and organized, you should place your tool code in the `tool/` folder and your test code in the `tests/` folder. Let's go over the important files:++- **`pyproject.toml`:** This is the Python project file that contains metadata about your project and its dependencies. It is used by [Poetry](https://python-poetry.org/) to install dependencies and manage the tool. Remember to run `poetry install` before starting development to ensure you are working in a clean, stand-alone environment.++- **`README.md`:** This file contains information about your tool, including how to use it, its purpose, environment variables, etc. Be sure to look at existing READMEs for examples.++- **`requirements.txt`:** This file lists just the runtime dependencies for your tool. These should match exactly the non-development dependencies in `pyproject.toml`, excluding the `python` version specification. **You should create this file manually** to ensure it is clean and contains only the necessary runtime dependencies.++- **`.coveragerc`:** This is the coverage configuration file that contains the configuration for the coverage tool. This file is the same across all tools and should always be included.++- **`poetry.lock`:** This is the lock file that contains the exact versions of the dependencies that were installed when `poetry install` was last run. This file should be committed as well to ensure consistency across different environments.++#### Creating `requirements.txt`++Since exporting `requirements.txt` using `poetry export` can sometimes include unnecessary details or development dependencies, it's recommended to create this file manually. Your `requirements.txt` should include all the non-development dependencies specified in your `pyproject.toml`, excluding the `python` version.++**Example `pyproject.toml`:**++```toml+[tool.poetry]+name = "pizza-ordering-tool"+version = "1.0"+description = "A tool for placing and processing pizza orders"+authors = ["Your Name <[email protected]>"]+readme = "README.md"+package-mode = false++[tool.poetry.dependencies]+python = ">=3.9,<4.0"+atomic-agents = {path = "../../../", develop = true}+pydantic = ">=2.8.2,<3.0.0"+requests = ">=2.28.0,<3.0.0"++[tool.poetry.group.dev.dependencies]+coverage = ">=7.0.0,<8.0.0"+pytest = ">=8.0.0,<9.0.0"+pytest-cov = ">=5.0.0,<6.0.0"+python-dotenv = ">=1.0.0,<2.0.0"+rich = ">=13.7.0,<14.0.0"++[build-system]+requires = ["poetry-core"]+build-backend = "poetry.core.masonry.api"+```++**Corresponding `requirements.txt`:**++```+atomic-agents>=1.0.0,<2.0.0+pydantic>=2.8.2,<3.0.0+requests>=2.28.0,<3.0.0+```++**Explanation:**++- The `requirements.txt` includes all the runtime dependencies specified under `[tool.poetry.dependencies]` in `pyproject.toml`, excluding `python`.+- It does **not** include any of the development dependencies specified under `[tool.poetry.group.dev.dependencies]`.+- This manual approach ensures that `requirements.txt` is clean and only contains the necessary packages for running your tool.### Inheritance and Base Classes@@ -63,11 +117,11 @@ By adhering to these inheritance rules upfront, you guarantee that your tool ali#### Overriding Title and Description-The `BaseToolConfig` allows you to override the default title and description of your tool. By default, the title and description are derived from the input schema's title and description, so usually you will not need to set them.+The `BaseToolConfig` allows you to override the default title and description of your tool. By default, the title and description are derived from the input schema's title and description, so usually, you will not need to set them.-However there are certain edge cases where you may want to override the title and description, such as when the default title and description are not descriptive or clear enough for your agent.+However, there are certain edge cases where you may want to override the title and description, such as when the default title and description are not descriptive or clear enough for your agent.-One example of this could be when you have a tool that performs a web search, and another that performs a search in a vector DB filled with internal company documents. You may want to override the title and description of these tools to make them more clear to the LLM that if a question is asked about the company's internal documents, the vector search tool is the appropriate tool to use and not the web search tool.+One example of this could be when you have a tool that performs a web search and another that performs a search in a vector DB filled with internal company documents. You may want to override the title and description of these tools to make it clearer to the LLM that if a question is asked about the company's internal documents, the vector search tool is the appropriate tool to use and not the web search tool.### Modularity@@ -124,6 +178,7 @@ All necessary imports should be placed at the top of your script. This includesimport osfrom enum import Enumfrom typing import List, Optional+from pydantic import BaseModel, Fieldfrom atomic_agents.agents.base_agent import BaseIOSchema@@ -419,6 +474,7 @@ if __name__ == "__main__":## Best Practices and Guidelines### Do's+- **Keep Imports at the Top:** Place all import statements at the beginning of your script without a section comment block.- **Follow the Standard Structure:** Adhere to the prescribed order and format for consistency.- **Use Clear and Descriptive Names:** Make your code self-explanatory.@@ -426,13 +482,17 @@ if __name__ == "__main__":- **Validate Inputs Thoroughly:** Use Pydantic's features to enforce data integrity.- **Handle Errors Gracefully:** Provide informative error messages and handle exceptions where appropriate.- **Keep Functions Small and Focused:** Break down complex logic into helper methods.+- **Commit `poetry.lock`:** Ensure you commit your `poetry.lock` file to maintain consistent dependencies across environments.+- **Manually Create `requirements.txt`:** Ensure your `requirements.txt` file matches the non-development dependencies in your `pyproject.toml`, excluding `python`, and create it manually for clarity.### Don'ts+- **Don't Hardcode Values:** Use configuration parameters or environment variables instead.- **Avoid Global Variables:** Keep the state within your tool's scope.- **Don't Overcomplicate:** Stick to the tool's single responsibility; avoid adding unrelated features.- **Don't Ignore Security:** Be cautious with sensitive information like API keys; use environment variables.- **Don't Neglect Performance:** Optimize your code, especially when dealing with large datasets or external API calls.- **Don't Skip Input Validation:** Never assume inputs are valid; always validate.+- **Don't Auto-Generate `requirements.txt`:** Avoid using automated tools that may include unnecessary or development dependencies; manually specify only the required runtime dependencies.Best of luck creating your own Atomic Tools!diff --git a/guides/dev-setup.md b/guides/dev-setup.mdnew file mode 100644index 0000000..e69de29