# Avachain
A lightweight, efficient library for creating and running AI agents with tools. Avachain focuses on OpenAI-compatible APIs and provides a minimal interface for building powerful AI agents with tool-calling capabilities.
## ✨ Features
- 🚀 **Lightweight & Fast**: Minimal dependencies, maximum performance
- 🔧 **Tool Integration**: Easy tool creation and management
- 💬 **Conversation Memory**: Intelligent context management
- 🎯 **Streaming Support**: Real-time response streaming
- 📊 **Callback System**: Monitor and handle agent events
- 🎨 **Colored Output**: Beautiful console output with print_color
- 🔄 **Function/Tool Calling**: Support for both modern and legacy function calling
- 📝 **Context Management**: Advanced message trimming and context preservation
- 🛠️ **Tool Creator**: Built-in tool creation and management utilities
- 👤 **Persona Creator**: Agent persona creation and management system
## 🏗️ Architecture Overview
Avachain follows a modular architecture designed for flexibility and extensibility:
```
avachain/
├── avachain.py # Core classes: BaseTool, LLM, OpenaiLLM, CallbackHandler
├── avachain_executor.py # Main AvaAgent orchestrator and execution engine
├── avachain_utils.py # Utility functions for resource management
├── tool_creator.py # Tool creation and JSON conversion utilities
└── persona_creator.py # Agent persona management system
```
## 📦 Dependencies
Avachain keeps dependencies minimal for maximum compatibility:
- **pydantic (≥2.6.1)**: Data validation and settings management
- **requests (≥2.31.0)**: HTTP client for API calls
- **tokenizers (==0.19.1)**: Text tokenization utilities
- **openai (==1.63.0)**: OpenAI API client
- **numpy**: Numerical computing support
- **print_color**: Colored console output
## Api Keys
To use Avachain, you need API keys for the services you want to integrate. Follow these steps to set up your API keys:
1. **Ava API Key**: Sign up at [AvaConsole](https://console.ava.pathor.in/) and create an API key.
Store your API keys in a secure location and reference them in your code as needed.
## Prerequisites
Ensure you have the following installed on your system:
- Python (3.10 or higher recommended)
- Git
- pip (Python package installer)
## 🚀 Quick Start
### 1. Clone the Repository
```bash
git clone https://github.com/OnlinePage/Avachain.git
cd Avachain
```
### 2. Install the Package
```bash
# For basic installation
python setup.py sdist
# For development (includes linting tools):
pip install -e ".[dev]"
# For testing (includes pytest):
pip install -e ".[test]"
```
### 3. Basic Usage
```python
from avachain.avachain_executor import AvaAgent
from avachain import OpenaiLLM, BaseTool
from pydantic import BaseModel, Field
# Initialize the LLM
llm = OpenaiLLM(
model="gpt-4o-mini",
api_key="your-ava-api-key", # Visit https://console.ava.pathor.in/
base_url="https://api.ava.pathor.in/v1",
temperature=0.7
)
class SearchArgs(BaseModel):
query: str = Field(description="Search query")
status: str = Field(
description="What are you doing in first person format as status. Should be casual, personalized addressing user friendly!",
)
# Define a custom tool
class SearchTool(BaseTool):
name: str = "web_search"
description: str = "Search the web for information"
args_schema: Type[BaseModel] = SearchArgs
def _run(self, query: str):
# Your search implementation here
return f"Search results for: {query}"
# Create the agent with comprehensive configuration
agent = AvaAgent(
sys_prompt="You are a helpful assistant with web search capabilities.",
ava_llm=llm,
tools_list=[SearchTool()],
logging=True,
pickup_mes_count=10,
)
# Chat with the agent using the run method
response = agent.run("Search for Python tutorials")
print(response)
```
### Plugin Creator Module
Advanced tool creation and management utilities.
```python
from avachain.tool_creator import convert_tool_to_json
# Convert tool with metadata for external systems
tool_json = convert_tool_to_json(
tool=my_tool,
tool_id="unique_id",
human_description="User-friendly description",
public_name="Display Name",
logo="path/to/logo.png",
isAnonymous=False,
authentication_required=True,
tags=["search", "web", "utility"],
supports_android=False,
supports_windows=True
)
```
### Persona Creator Module
Agent persona creation and management system.
```python
from avachain import persona_creator, validate_logo_path
# Create and manage agent personas
persona_creator = PersonaCreator()
# Validate logo file
logo_path = validate_logo_path("path/to/logo.png")
# Create persona with tools and configuration
persona_data = {
"name": "Research Assistant",
"description": "AI assistant specialized in research tasks",
"system_prompt": "You are a research assistant...",
"tools": [search_tool, analysis_tool],
"logo_path": logo_path
}
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to contribute to Avachain, including development setup, coding standards, and submission guidelines.
## � Security Considerations
- **API Key Management**: Never hardcode API keys in your code. Use environment variables or secure configuration files.
- **Tool Security**: Validate all tool inputs and sanitize outputs. Be cautious with tools that execute system commands.
- **Input Validation**: Always validate user inputs before processing.
- **Error Handling**: Don't expose sensitive information in error messages.
```python
import os
from avachain import OpenaiLLM, AvaAgent
# Secure API key handling
api_key = os.getenv("OPENAI_API_KEY")
if not api_key:
raise ValueError("OPENAI_API_KEY environment variable not set")
llm = OpenaiLLM(api_key=api_key, model="gpt-3.5-turbo")
```
## 🚀 Performance Tips
1. **Context Management**: Use appropriate `pickup_mes_count` to balance context and performance
2. **Tool Optimization**: Keep tool execution time minimal
3. **Streaming**: Use streaming for better perceived performance in interactive applications
4. **Caching**: Implement caching in tools for frequently accessed data
5. **Async Operations**: Consider async patterns for I/O heavy tools
## 📊 Monitoring and Logging
### Built-in Logging
```python
# Enable comprehensive logging
agent = AvaAgent(
sys_prompt="Your system prompt",
ava_llm=llm,
logging=True,
deeper_logs=True, # More detailed logs
agent_name_identifier="MyAgent"
)
```
## 📝 License
This project is licensed under the MIT License - see the LICENSE file for details.
**Made with ❤️ for the AI community**
Raw data
{
"_id": null,
"home_page": "https://github.com/OnlinePage/Avachain",
"name": "avachain",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, agent, llm, openai, tools, chatbot, automation, artificial-intelligence, machine-learning, nlp, conversational-ai, function-calling, streaming, claude, mistral, gpt",
"author": "Salo Soja Edwin",
"author_email": "salosoja@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/27/1d/fe9f467418b904c18635808246283d77f07c99645d982d41400b9bff1166/avachain-2.0.8.tar.gz",
"platform": null,
"description": "# Avachain\n\nA lightweight, efficient library for creating and running AI agents with tools. Avachain focuses on OpenAI-compatible APIs and provides a minimal interface for building powerful AI agents with tool-calling capabilities.\n\n## \u2728 Features\n\n- \ud83d\ude80 **Lightweight & Fast**: Minimal dependencies, maximum performance\n- \ud83d\udd27 **Tool Integration**: Easy tool creation and management\n- \ud83d\udcac **Conversation Memory**: Intelligent context management\n- \ud83c\udfaf **Streaming Support**: Real-time response streaming\n- \ud83d\udcca **Callback System**: Monitor and handle agent events\n- \ud83c\udfa8 **Colored Output**: Beautiful console output with print_color\n- \ud83d\udd04 **Function/Tool Calling**: Support for both modern and legacy function calling\n- \ud83d\udcdd **Context Management**: Advanced message trimming and context preservation\n- \ud83d\udee0\ufe0f **Tool Creator**: Built-in tool creation and management utilities\n- \ud83d\udc64 **Persona Creator**: Agent persona creation and management system\n\n## \ud83c\udfd7\ufe0f Architecture Overview\n\nAvachain follows a modular architecture designed for flexibility and extensibility:\n\n```\navachain/\n\u251c\u2500\u2500 avachain.py # Core classes: BaseTool, LLM, OpenaiLLM, CallbackHandler\n\u251c\u2500\u2500 avachain_executor.py # Main AvaAgent orchestrator and execution engine\n\u251c\u2500\u2500 avachain_utils.py # Utility functions for resource management\n\u251c\u2500\u2500 tool_creator.py # Tool creation and JSON conversion utilities\n\u2514\u2500\u2500 persona_creator.py # Agent persona management system\n```\n\n## \ud83d\udce6 Dependencies\n\nAvachain keeps dependencies minimal for maximum compatibility:\n\n- **pydantic (\u22652.6.1)**: Data validation and settings management\n- **requests (\u22652.31.0)**: HTTP client for API calls\n- **tokenizers (==0.19.1)**: Text tokenization utilities\n- **openai (==1.63.0)**: OpenAI API client\n- **numpy**: Numerical computing support\n- **print_color**: Colored console output\n\n## Api Keys\n\nTo use Avachain, you need API keys for the services you want to integrate. Follow these steps to set up your API keys:\n\n1. **Ava API Key**: Sign up at [AvaConsole](https://console.ava.pathor.in/) and create an API key.\n\nStore your API keys in a secure location and reference them in your code as needed.\n\n## Prerequisites\n\nEnsure you have the following installed on your system:\n- Python (3.10 or higher recommended)\n- Git\n- pip (Python package installer)\n\n## \ud83d\ude80 Quick Start\n\n### 1. Clone the Repository\n```bash\ngit clone https://github.com/OnlinePage/Avachain.git\ncd Avachain\n```\n\n### 2. Install the Package\n```bash\n# For basic installation\npython setup.py sdist\n\n# For development (includes linting tools):\npip install -e \".[dev]\"\n\n# For testing (includes pytest):\npip install -e \".[test]\"\n```\n\n### 3. Basic Usage\n\n```python\nfrom avachain.avachain_executor import AvaAgent\nfrom avachain import OpenaiLLM, BaseTool\nfrom pydantic import BaseModel, Field\n\n# Initialize the LLM\nllm = OpenaiLLM(\n model=\"gpt-4o-mini\",\n api_key=\"your-ava-api-key\", # Visit https://console.ava.pathor.in/\n base_url=\"https://api.ava.pathor.in/v1\",\n temperature=0.7\n)\n\nclass SearchArgs(BaseModel):\n query: str = Field(description=\"Search query\")\n status: str = Field(\n description=\"What are you doing in first person format as status. Should be casual, personalized addressing user friendly!\",\n )\n\n# Define a custom tool\nclass SearchTool(BaseTool):\n name: str = \"web_search\"\n description: str = \"Search the web for information\"\n args_schema: Type[BaseModel] = SearchArgs\n\n def _run(self, query: str):\n # Your search implementation here\n return f\"Search results for: {query}\"\n\n\n# Create the agent with comprehensive configuration\nagent = AvaAgent(\n sys_prompt=\"You are a helpful assistant with web search capabilities.\",\n ava_llm=llm,\n tools_list=[SearchTool()],\n logging=True,\n pickup_mes_count=10,\n)\n\n# Chat with the agent using the run method\nresponse = agent.run(\"Search for Python tutorials\")\nprint(response)\n```\n\n\n\n### Plugin Creator Module\n\nAdvanced tool creation and management utilities.\n\n```python\nfrom avachain.tool_creator import convert_tool_to_json\n\n# Convert tool with metadata for external systems\ntool_json = convert_tool_to_json(\n tool=my_tool,\n tool_id=\"unique_id\",\n human_description=\"User-friendly description\",\n public_name=\"Display Name\",\n logo=\"path/to/logo.png\",\n isAnonymous=False,\n authentication_required=True,\n tags=[\"search\", \"web\", \"utility\"],\n supports_android=False,\n supports_windows=True\n)\n```\n\n### Persona Creator Module\n\nAgent persona creation and management system.\n\n```python\nfrom avachain import persona_creator, validate_logo_path\n\n# Create and manage agent personas\npersona_creator = PersonaCreator()\n\n# Validate logo file\nlogo_path = validate_logo_path(\"path/to/logo.png\")\n\n# Create persona with tools and configuration\npersona_data = {\n \"name\": \"Research Assistant\",\n \"description\": \"AI assistant specialized in research tasks\",\n \"system_prompt\": \"You are a research assistant...\",\n \"tools\": [search_tool, analysis_tool],\n \"logo_path\": logo_path\n}\n```\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for detailed information on how to contribute to Avachain, including development setup, coding standards, and submission guidelines.\n\n## \ufffd Security Considerations\n\n- **API Key Management**: Never hardcode API keys in your code. Use environment variables or secure configuration files.\n- **Tool Security**: Validate all tool inputs and sanitize outputs. Be cautious with tools that execute system commands.\n- **Input Validation**: Always validate user inputs before processing.\n- **Error Handling**: Don't expose sensitive information in error messages.\n\n```python\nimport os\nfrom avachain import OpenaiLLM, AvaAgent\n\n# Secure API key handling\napi_key = os.getenv(\"OPENAI_API_KEY\")\nif not api_key:\n raise ValueError(\"OPENAI_API_KEY environment variable not set\")\n\nllm = OpenaiLLM(api_key=api_key, model=\"gpt-3.5-turbo\")\n```\n\n## \ud83d\ude80 Performance Tips\n\n1. **Context Management**: Use appropriate `pickup_mes_count` to balance context and performance\n2. **Tool Optimization**: Keep tool execution time minimal\n3. **Streaming**: Use streaming for better perceived performance in interactive applications\n4. **Caching**: Implement caching in tools for frequently accessed data\n5. **Async Operations**: Consider async patterns for I/O heavy tools\n\n## \ud83d\udcca Monitoring and Logging\n\n### Built-in Logging\n\n```python\n# Enable comprehensive logging\nagent = AvaAgent(\n sys_prompt=\"Your system prompt\",\n ava_llm=llm,\n logging=True,\n deeper_logs=True, # More detailed logs\n agent_name_identifier=\"MyAgent\"\n)\n```\n\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n\n**Made with \u2764\ufe0f for the AI community**\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A lightweight library for creating and running AI agents with tools, supporting OpenAI-compatible APIs",
"version": "2.0.8",
"project_urls": {
"Bug Reports": "https://github.com/OnlinePage/Avachain/issues",
"Documentation": "https://github.com/OnlinePage/Avachain#readme",
"Homepage": "https://github.com/OnlinePage/Avachain",
"Source": "https://github.com/OnlinePage/Avachain"
},
"split_keywords": [
"ai",
" agent",
" llm",
" openai",
" tools",
" chatbot",
" automation",
" artificial-intelligence",
" machine-learning",
" nlp",
" conversational-ai",
" function-calling",
" streaming",
" claude",
" mistral",
" gpt"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "58ccb6729daa3c4dfaca2df9b9000ea0f9d1805d88bf1931de4f05f551fab7e2",
"md5": "0abc8eaa217f5eee8aeaa64a66393eaa",
"sha256": "d846efb03c7effdf344a5320b6ab93b525cec5a2e8f0d09c0025f4b2f1ec4e7f"
},
"downloads": -1,
"filename": "avachain-2.0.8-py3-none-any.whl",
"has_sig": false,
"md5_digest": "0abc8eaa217f5eee8aeaa64a66393eaa",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 29340,
"upload_time": "2025-08-14T17:32:32",
"upload_time_iso_8601": "2025-08-14T17:32:32.033820Z",
"url": "https://files.pythonhosted.org/packages/58/cc/b6729daa3c4dfaca2df9b9000ea0f9d1805d88bf1931de4f05f551fab7e2/avachain-2.0.8-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "271dfe9f467418b904c18635808246283d77f07c99645d982d41400b9bff1166",
"md5": "df679b2b04171aa403fa408758d47091",
"sha256": "dc0d91b6ba0e36b59dc8f9640d8515355b28b1ab4ef614034b5870359ae4f164"
},
"downloads": -1,
"filename": "avachain-2.0.8.tar.gz",
"has_sig": false,
"md5_digest": "df679b2b04171aa403fa408758d47091",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 39337,
"upload_time": "2025-08-14T17:32:33",
"upload_time_iso_8601": "2025-08-14T17:32:33.586426Z",
"url": "https://files.pythonhosted.org/packages/27/1d/fe9f467418b904c18635808246283d77f07c99645d982d41400b9bff1166/avachain-2.0.8.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-14 17:32:33",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "OnlinePage",
"github_project": "Avachain",
"github_not_found": true,
"lcname": "avachain"
}
JSON
