{"id":25625055,"url":"https://github.com/getsimpletool/simpletool-python","last_synced_at":"2026-06-05T03:30:17.943Z","repository":{"id":270635757,"uuid":"910939999","full_name":"getsimpletool/simpletool-python","owner":"getsimpletool","description":"Agent Tool Type Definision","archived":false,"fork":false,"pushed_at":"2025-01-21T22:28:44.000Z","size":75,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-20T05:17:42.505Z","etag":null,"topics":["ai","ai-agent","ai-agents","ai-toolkit","ai-tools","pydentic","python3"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/getsimpletool.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-01-01T21:10:57.000Z","updated_at":"2025-01-21T22:25:06.000Z","dependencies_parsed_at":"2025-01-02T03:04:56.972Z","dependency_job_id":null,"html_url":"https://github.com/getsimpletool/simpletool-python","commit_stats":null,"previous_names":["nchekwa/simpletool-python"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fsimpletool-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fsimpletool-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fsimpletool-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/getsimpletool%2Fsimpletool-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/getsimpletool","download_url":"https://codeload.github.com/getsimpletool/simpletool-python/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240178750,"owners_count":19760613,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agent","ai-agents","ai-toolkit","ai-tools","pydentic","python3"],"created_at":"2025-02-22T13:25:58.228Z","updated_at":"2026-06-05T03:30:17.900Z","avatar_url":"https://github.com/getsimpletool.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Simpletool\n\nSimpleTool 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\".\n\n## ⚠️ Disclaimer [2025-01]\n\n* 🛠️ __Under active development__: Expect frequent updates, bugs, and breaking changes.\n* 🤓 __Check the release notes__: Always check the [release notes](./CHANGELOG.md) to verify if there are any breaking changes.\n\n## 💡 Overview\n\nSimpletool is a powerful SDK that provides a structured approach to building tools with:\n- Standardized input and output content types\n- Automatic JSON schema generation\n- Async support\n- Environment variable handling\n- Timeout management (def. 60s)\n\n\n\n## 💬 Example\nCheck out the [tool_example.py](./tool_example.py) to see how to use Simpletool to create a simple, type-safe tool.\n\n## ⚡️ Architecture Overview\n\n```mermaid\n\nclassDiagram\n    class Content {\n        \u003c\u003cabstract\u003e\u003e\n        +type: Literal[\"text\", \"image\", \"file\", \"error\"]\n        AutoValidation\n    }\n    \n    class TextContent {\n        +text: str\n    }\n    \n    class ImageContent {\n        +data: str\n        +description: str\n        +mime_type: str\n    }\n    \n    class FileContent {\n        +data: str\n        +file_name: str\n        +mime_type: str\n        AutoValidation\n    }\n    \n    class ErrorContent {\n        +code: int\n        +message: str\n        +data: Any\n    }\n    \n    class SimpleTool {\n        \u003c\u003cabstract\u003e\u003e\n        +name: str\n        +description: str\n        +input_model: Type[SimpleInputModel]\n        +input_schema: Dict (auto generated)\n        +output_schema: Dict (auto generated)\n        +get_env(arguments: dict, prefix: str)\n        +run(arguments: dict) Sequence[Content]\n    }\n    \n    class SimpleInputModel {\n        \u003c\u003cinterface\u003e\u003e\n        AutoValidation\n    }\n    \n    SimpleTool \u003c-- SimpleInputModel: arguments (Dict[str, Any])\n    SimpleTool \u003c-- SimpleInputModel: input_model (Type[SimpleInputModel])_\n\n    Content --|\u003e TextContent\n    Content --|\u003e ImageContent\n    Content --|\u003e FileContent\n    Content --|\u003e ErrorContent\n    \n    SimpleTool --\u003e Content: returns Sequence[Content]\n```\n\n## 💻 Core Components\n\n### `SimpleTool` Base Class and Key Features\n\nThe `SimpleTool` class provides a robust framework for building tools with the following key features:\n\n- **Input Validation**: \n  - Uses Pydantic models for strict input validation (SimpleInputModel)\n  - Automatic type checking and conversion based on Pydantic models\n  - SimpleInputModel have own model_json_schema (removes `titles` and `descriptions` from the schema) for easy dump to text schema\n\n- **Output Type Management**: \n  - Supports multiple content types (text, image, file, resource, error) for flexible output representation\n  - Strict output type checking allow List or Seqence of Content Types Objects\n\n- **Dynamic Schema Generation**: \n\n  - Input model needs to be defined as child of `SimpleInputModel` Type and assign to `input_model` attribute inside `SimpleTool` - them magic begins and automaticly:\n    - Automatically creates output JSON schemas (`output_schema` / `output_model`) based on the defined `run` method typing \n    - Automatically creates input JSON schemas (`input_schem`a) based on the input model\n\n- **Async Execution**: \n  - Native async/await support\n  - Configurable timeout management\n  - Contex manager for easy resource management release\n\n- **Environment Integration**: \n  - Easy retrieval of environment variables (`get_env`)\n  - Support for random API key selection from provided list (`get_env`)\n\n### Content Types\n\nSimpletool defines several content types to standardize tool inputs and outputs:\n\n- `TextContent`: Represents text-based content\n- `ImageContent`: Handles base64 encoded images with optional metadata\n- `FileContent`: Represents files with base64 encoded data\n- `ResourceContent`: Manages external resource references\n- `ErrorContent`: Provides structured error reporting\n- `BoolContents`: Simple boolean content type\n\n## 📦 Installation\n\nInstall the package using pip:\n\n```bash\npip install simpletool\n```\n\n## 🔄 Quick Start\n\n### 🛠️ Creating a Tool\n\n```python\nfrom simpletool import SimpleTool, SimpleInputModel, Sequence, Field\nfrom simpletool.types import TextContent\n\nclass InputModel(SimpleInputModel):\n    name: str = Field(description=\"Name to greet\")\n\nclass MyTool(SimpleTool):\n    name = \"greeting_tool\"\n    description = \"A simple greeting tool\"\n    input_model = InputModel\n\n    async def run(self, arguments: dict) -\u003e Sequence[TextContent]:\n        # Validation and parsing of input arguments\n        arg: InputModel = InputModel(**arguments)\n\n        return [TextContent(text=f\"Hello, {arg.name}!\")]\n```\n\n## 📝 Development Guidelines\n\n- Inherit Tool model from `SimpleTool`\n- Define an `input_model` using Pydantic (`SimpleInputModel`)\n- Implement the `run` method\n- Return a list/sequence of content types\n- Use async/await for asynchronous operations\n\n\n## 📝 Contributing\n\nContributions are welcome! Please follow Python best practices and maintain the existing code style.\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n\n## 📞 Contact\n\nContributions are welcome! Please submit a pull request with your changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsimpletool%2Fsimpletool-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgetsimpletool%2Fsimpletool-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgetsimpletool%2Fsimpletool-python/lists"}