| Name | agentils JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | AI Agent Utilities - Powerful toolkit for building AI agents with LLM integration and decorators |
| upload_time | 2025-08-16 03:38:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.9 |
| license | MIT |
| keywords |
agents
ai
decorators
gemini
llm
utilities
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Agentils - AI Agent Utilities
A powerful Python toolkit for building AI agents with LLM integration, decorators for easy function calling, and utility functions.
## Features
- 🤖 **Easy LLM Integration**: Simple decorators for Google Gemini API
- 🛠️ **Function Calling**: Automatic tool integration with Python functions
- 📝 **JSON/Text Output**: Flexible output formatting
- 🔧 **Utility Functions**: JSON parsing, file operations, and more
- 🎯 **Type Safe**: Full type hints for better development experience
- 🚀 **Simple API**: Minimal setup, maximum productivity
## Installation
```bash
pip install agentils
```
## Development Setup
1. Clone the repository
2. Copy `.env.example` to `.env` and fill in your credentials
3. Run the setup script:
```bash
python setup_dev.py
```
## Publishing (for maintainers)
**⚠️ Security Note**: Never commit credentials to version control!
### Quick Publishing
```bash
# Publish to both PyPI and private repo
python publish.py
# Publish to PyPI only
python publish.py --target pypi
# Publish to private repo only
python publish.py --target repoflow
# Windows users
publish.bat both
```
### First-time PyPI Setup
1. Create PyPI account and API token
2. Add credentials to `.env` file
3. See [PYPI_SETUP.md](PYPI_SETUP.md) for detailed instructions
### Installation from Different Sources
```bash
# From PyPI (public)
pip install agentils
# From private repository
pip install agentils --index-url https://api.repoflow.io/pypi/eric-4092/erpy/simple/
```
## Quick Start
### Basic Usage
```python
from agentils import AgentsUtils
import os
# Set your API key
os.environ['GOOGLE_API_KEY'] = 'your-api-key-here'
# Simple text generation
@AgentsUtils.execute_llm(output="text")
def generate_story():
return "Write a short story about a robot learning to paint."
story = generate_story()
print(story)
```
### JSON Output
```python
@AgentsUtils.execute_llm(output="json")
def analyze_sentiment():
return """
Analyze the sentiment of this text and return JSON with 'sentiment' and 'confidence':
"I love this new AI assistant!"
"""
result = analyze_sentiment()
print(result) # {'sentiment': 'positive', 'confidence': 0.95}
```
### Function Calling with Tools
```python
def get_weather(location: str) -> str:
"""Get the current weather for a location."""
return f"The weather in {location} is sunny and 72°F"
@AgentsUtils.execute_llm_with_tools(
tools=[get_weather], # Pass Python functions directly!
automatic_function_calling=True
)
def weather_assistant():
return "What's the weather like in San Francisco?"
response = weather_assistant()
print(response)
```
### Advanced Configuration
```python
@AgentsUtils.execute_llm_with_tools(
model_name="gemini-2.0-flash-001",
temperature=0.7,
max_output_tokens=1000,
system_instruction="You are a helpful coding assistant",
tools=[get_weather],
output="json"
)
def advanced_task():
return "Help me plan a coding project with weather considerations"
```
### Chat Sessions
```python
# Create a chat session for multi-turn conversations
chat = AgentsUtils.create_chat_session(
system_instruction="You are a helpful assistant",
tools=[get_weather]
)
response1 = chat.send_message("Hello!")
response2 = chat.send_message("What's the weather in Tokyo?")
```
## Utility Functions
```python
from agentils import Utils
# JSON operations
data = Utils.string_to_dict('{"key": "value"}')
json_str = Utils.dict_to_string({"key": "value"})
# File operations
Utils.save_dict_to_file(data, "data.json")
loaded_data = Utils.load_dict_from_file("data.json")
```
## API Reference
### AgentsUtils
#### `execute_llm(**kwargs)`
Simple decorator for LLM calls without tools.
**Parameters:**
- `model_name` (str): Model to use (default: "gemini-2.0-flash-001")
- `output` (str): "json" or "text"
- `api_key` (str, optional): API key (uses GOOGLE_API_KEY env var)
- `system_instruction` (str, optional): System instruction
- `temperature` (float, optional): Temperature setting
- `max_output_tokens` (int, optional): Max output tokens
#### `execute_llm_with_tools(**kwargs)`
Advanced decorator with tools support.
**Additional Parameters:**
- `tools` (list): List of Python functions or Tool objects
- `automatic_function_calling` (bool): Enable automatic function calling
- `max_function_calls` (int): Maximum number of function calls
#### `create_chat_session(**kwargs)`
Create a chat session for multi-turn conversations.
### Utils
#### `string_to_dict(s: str) -> dict`
Convert JSON string to dictionary.
#### `dict_to_string(d: dict) -> str`
Convert dictionary to JSON string.
#### `save_dict_to_file(d: dict, filename: str)`
Save dictionary to JSON file.
#### `load_dict_from_file(filename: str) -> dict`
Load dictionary from JSON file.
## Environment Variables
- `GOOGLE_API_KEY`: Your Google AI API key (required)
- `GEMINI_API_KEY`: Alternative API key variable name
## Requirements
- Python 3.8+
- google-genai >= 0.3.0
- pydantic >= 2.11.7
## License
MIT License - see LICENSE file for details.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## Support
If you encounter any issues or have questions, please open an issue on GitHub.
Raw data
{
"_id": null,
"home_page": null,
"name": "agentils",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "agents, ai, decorators, gemini, llm, utilities",
"author": null,
"author_email": "aggreyeric <ericaggrey@outlook.com>",
"download_url": "https://files.pythonhosted.org/packages/91/5a/edcc236fc27405592ed0a9d5b85f20ac1771eb079fa5e2b45bc92ce98752/agentils-0.1.0.tar.gz",
"platform": null,
"description": "# Agentils - AI Agent Utilities\n\nA powerful Python toolkit for building AI agents with LLM integration, decorators for easy function calling, and utility functions.\n\n## Features\n\n- \ud83e\udd16 **Easy LLM Integration**: Simple decorators for Google Gemini API\n- \ud83d\udee0\ufe0f **Function Calling**: Automatic tool integration with Python functions\n- \ud83d\udcdd **JSON/Text Output**: Flexible output formatting\n- \ud83d\udd27 **Utility Functions**: JSON parsing, file operations, and more\n- \ud83c\udfaf **Type Safe**: Full type hints for better development experience\n- \ud83d\ude80 **Simple API**: Minimal setup, maximum productivity\n\n## Installation\n\n```bash\npip install agentils\n```\n\n## Development Setup\n\n1. Clone the repository\n2. Copy `.env.example` to `.env` and fill in your credentials\n3. Run the setup script:\n ```bash\n python setup_dev.py\n ```\n\n## Publishing (for maintainers)\n\n**\u26a0\ufe0f Security Note**: Never commit credentials to version control!\n\n### Quick Publishing\n\n```bash\n# Publish to both PyPI and private repo\npython publish.py\n\n# Publish to PyPI only\npython publish.py --target pypi\n\n# Publish to private repo only\npython publish.py --target repoflow\n\n# Windows users\npublish.bat both\n```\n\n### First-time PyPI Setup\n\n1. Create PyPI account and API token\n2. Add credentials to `.env` file\n3. See [PYPI_SETUP.md](PYPI_SETUP.md) for detailed instructions\n\n### Installation from Different Sources\n\n```bash\n# From PyPI (public)\npip install agentils\n\n# From private repository\npip install agentils --index-url https://api.repoflow.io/pypi/eric-4092/erpy/simple/\n```\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom agentils import AgentsUtils\nimport os\n\n# Set your API key\nos.environ['GOOGLE_API_KEY'] = 'your-api-key-here'\n\n# Simple text generation\n@AgentsUtils.execute_llm(output=\"text\")\ndef generate_story():\n return \"Write a short story about a robot learning to paint.\"\n\nstory = generate_story()\nprint(story)\n```\n\n### JSON Output\n\n```python\n@AgentsUtils.execute_llm(output=\"json\")\ndef analyze_sentiment():\n return \"\"\"\n Analyze the sentiment of this text and return JSON with 'sentiment' and 'confidence':\n \"I love this new AI assistant!\"\n \"\"\"\n\nresult = analyze_sentiment()\nprint(result) # {'sentiment': 'positive', 'confidence': 0.95}\n```\n\n### Function Calling with Tools\n\n```python\ndef get_weather(location: str) -> str:\n \"\"\"Get the current weather for a location.\"\"\"\n return f\"The weather in {location} is sunny and 72\u00b0F\"\n\n@AgentsUtils.execute_llm_with_tools(\n tools=[get_weather], # Pass Python functions directly!\n automatic_function_calling=True\n)\ndef weather_assistant():\n return \"What's the weather like in San Francisco?\"\n\nresponse = weather_assistant()\nprint(response)\n```\n\n### Advanced Configuration\n\n```python\n@AgentsUtils.execute_llm_with_tools(\n model_name=\"gemini-2.0-flash-001\",\n temperature=0.7,\n max_output_tokens=1000,\n system_instruction=\"You are a helpful coding assistant\",\n tools=[get_weather],\n output=\"json\"\n)\ndef advanced_task():\n return \"Help me plan a coding project with weather considerations\"\n```\n\n### Chat Sessions\n\n```python\n# Create a chat session for multi-turn conversations\nchat = AgentsUtils.create_chat_session(\n system_instruction=\"You are a helpful assistant\",\n tools=[get_weather]\n)\n\nresponse1 = chat.send_message(\"Hello!\")\nresponse2 = chat.send_message(\"What's the weather in Tokyo?\")\n```\n\n## Utility Functions\n\n```python\nfrom agentils import Utils\n\n# JSON operations\ndata = Utils.string_to_dict('{\"key\": \"value\"}')\njson_str = Utils.dict_to_string({\"key\": \"value\"})\n\n# File operations\nUtils.save_dict_to_file(data, \"data.json\")\nloaded_data = Utils.load_dict_from_file(\"data.json\")\n```\n\n## API Reference\n\n### AgentsUtils\n\n#### `execute_llm(**kwargs)`\nSimple decorator for LLM calls without tools.\n\n**Parameters:**\n- `model_name` (str): Model to use (default: \"gemini-2.0-flash-001\")\n- `output` (str): \"json\" or \"text\"\n- `api_key` (str, optional): API key (uses GOOGLE_API_KEY env var)\n- `system_instruction` (str, optional): System instruction\n- `temperature` (float, optional): Temperature setting\n- `max_output_tokens` (int, optional): Max output tokens\n\n#### `execute_llm_with_tools(**kwargs)`\nAdvanced decorator with tools support.\n\n**Additional Parameters:**\n- `tools` (list): List of Python functions or Tool objects\n- `automatic_function_calling` (bool): Enable automatic function calling\n- `max_function_calls` (int): Maximum number of function calls\n\n#### `create_chat_session(**kwargs)`\nCreate a chat session for multi-turn conversations.\n\n### Utils\n\n#### `string_to_dict(s: str) -> dict`\nConvert JSON string to dictionary.\n\n#### `dict_to_string(d: dict) -> str`\nConvert dictionary to JSON string.\n\n#### `save_dict_to_file(d: dict, filename: str)`\nSave dictionary to JSON file.\n\n#### `load_dict_from_file(filename: str) -> dict`\nLoad dictionary from JSON file.\n\n## Environment Variables\n\n- `GOOGLE_API_KEY`: Your Google AI API key (required)\n- `GEMINI_API_KEY`: Alternative API key variable name\n\n## Requirements\n\n- Python 3.8+\n- google-genai >= 0.3.0\n- pydantic >= 2.11.7\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## Support\n\nIf you encounter any issues or have questions, please open an issue on GitHub.",
"bugtrack_url": null,
"license": "MIT",
"summary": "AI Agent Utilities - Powerful toolkit for building AI agents with LLM integration and decorators",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/aggreyeric/agentils#readme",
"Homepage": "https://github.com/aggreyeric/agentils",
"Issues": "https://github.com/aggreyeric/agentils/issues",
"Repository": "https://github.com/aggreyeric/agentils"
},
"split_keywords": [
"agents",
" ai",
" decorators",
" gemini",
" llm",
" utilities"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "30f551bb9ae7e7612bb0bb04d3e858cf03403301fb1ea4f230765cf1e027e280",
"md5": "c87c79fcb5a34f3ccf57dfe5b1ff768a",
"sha256": "8bb5b971458ca05becad1a1d3555c266893497ac3c920a24624d1faecc652f56"
},
"downloads": -1,
"filename": "agentils-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c87c79fcb5a34f3ccf57dfe5b1ff768a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 7954,
"upload_time": "2025-08-16T03:38:22",
"upload_time_iso_8601": "2025-08-16T03:38:22.150026Z",
"url": "https://files.pythonhosted.org/packages/30/f5/51bb9ae7e7612bb0bb04d3e858cf03403301fb1ea4f230765cf1e027e280/agentils-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "915aedcc236fc27405592ed0a9d5b85f20ac1771eb079fa5e2b45bc92ce98752",
"md5": "a5a3a3e47ce356513a9c421c43f7111c",
"sha256": "c1bc0cf126d998db0b8f5005f7d91d9bbee37c2e175f874d248bfdc6cecb0b6a"
},
"downloads": -1,
"filename": "agentils-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "a5a3a3e47ce356513a9c421c43f7111c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 7454,
"upload_time": "2025-08-16T03:38:23",
"upload_time_iso_8601": "2025-08-16T03:38:23.532245Z",
"url": "https://files.pythonhosted.org/packages/91/5a/edcc236fc27405592ed0a9d5b85f20ac1771eb079fa5e2b45bc92ce98752/agentils-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-16 03:38:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "aggreyeric",
"github_project": "agentils#readme",
"github_not_found": true,
"lcname": "agentils"
}
