Skip to content

getsimpletool/simpletool-python

Repository files navigation

Simpletool

SimpleTool is a lightweight, async-first Python framework designed for creating simple, strict, and explicit type-safe tools with minimal complexity. It embodies some of the Python design Zen principles, such as "Simple is better than complex" and "Explicit is better than implicit".

⚠️ Disclaimer [2025-01]

  • 🛠️ Under active development: Expect frequent updates, bugs, and breaking changes.
  • 🤓 Check the release notes: Always check the release notes to verify if there are any breaking changes.

💡 Overview

Simpletool is a powerful SDK that provides a structured approach to building tools with:

  • Standardized input and output content types
  • Automatic JSON schema generation
  • Async support
  • Environment variable handling
  • Timeout management (def. 60s)

💬 Example

Check out the tool_example.py to see how to use Simpletool to create a simple, type-safe tool.

⚡️ Architecture Overview

classDiagram
    class Content {
        <<abstract>>
        +type: Literal["text", "image", "file", "error"]
        AutoValidation
    }
    
    class TextContent {
        +text: str
    }
    
    class ImageContent {
        +data: str
        +description: str
        +mime_type: str
    }
    
    class FileContent {
        +data: str
        +file_name: str
        +mime_type: str
        AutoValidation
    }
    
    class ErrorContent {
        +code: int
        +message: str
        +data: Any
    }
    
    class SimpleTool {
        <<abstract>>
        +name: str
        +description: str
        +input_model: Type[SimpleInputModel]
        +input_schema: Dict (auto generated)
        +output_schema: Dict (auto generated)
        +get_env(arguments: dict, prefix: str)
        +run(arguments: dict) Sequence[Content]
    }
    
    class SimpleInputModel {
        <<interface>>
        AutoValidation
    }
    
    SimpleTool <-- SimpleInputModel: arguments (Dict[str, Any])
    SimpleTool <-- SimpleInputModel: input_model (Type[SimpleInputModel])_

    Content --|> TextContent
    Content --|> ImageContent
    Content --|> FileContent
    Content --|> ErrorContent
    
    SimpleTool --> Content: returns Sequence[Content]
Loading

💻 Core Components

SimpleTool Base Class and Key Features

The SimpleTool class provides a robust framework for building tools with the following key features:

  • Input Validation:

    • Uses Pydantic models for strict input validation (SimpleInputModel)
    • Automatic type checking and conversion based on Pydantic models
    • SimpleInputModel have own model_json_schema (removes titles and descriptions from the schema) for easy dump to text schema
  • Output Type Management:

    • Supports multiple content types (text, image, file, resource, error) for flexible output representation
    • Strict output type checking allow List or Seqence of Content Types Objects
  • Dynamic Schema Generation:

    • Input model needs to be defined as child of SimpleInputModel Type and assign to input_model attribute inside SimpleTool - them magic begins and automaticly:
      • Automatically creates output JSON schemas (output_schema / output_model) based on the defined run method typing
      • Automatically creates input JSON schemas (input_schema) based on the input model
  • Async Execution:

    • Native async/await support
    • Configurable timeout management
    • Contex manager for easy resource management release
  • Environment Integration:

    • Easy retrieval of environment variables (get_env)
    • Support for random API key selection from provided list (get_env)

Content Types

Simpletool defines several content types to standardize tool inputs and outputs:

  • TextContent: Represents text-based content
  • ImageContent: Handles base64 encoded images with optional metadata
  • FileContent: Represents files with base64 encoded data
  • ResourceContent: Manages external resource references
  • ErrorContent: Provides structured error reporting
  • BoolContents: Simple boolean content type

📦 Installation

Install the package using pip:

pip install simpletool

🔄 Quick Start

🛠️ Creating a Tool

from simpletool import SimpleTool, SimpleInputModel, Sequence, Field
from simpletool.types import TextContent

class InputModel(SimpleInputModel):
    name: str = Field(description="Name to greet")

class MyTool(SimpleTool):
    name = "greeting_tool"
    description = "A simple greeting tool"
    input_model = InputModel

    async def run(self, arguments: dict) -> Sequence[TextContent]:
        # Validation and parsing of input arguments
        arg: InputModel = InputModel(**arguments)

        return [TextContent(text=f"Hello, {arg.name}!")]

📝 Development Guidelines

  • Inherit Tool model from SimpleTool
  • Define an input_model using Pydantic (SimpleInputModel)
  • Implement the run method
  • Return a list/sequence of content types
  • Use async/await for asynchronous operations

📝 Contributing

Contributions are welcome! Please follow Python best practices and maintain the existing code style.

📄 License

This project is licensed under the MIT License.

📞 Contact

Contributions are welcome! Please submit a pull request with your changes.