# Vizra - Simple AI Agent Framework for Python
A lightweight, class-based AI agent framework for Python that uses litellm for LLM integration.
## Installation
```bash
pip install vizra
```
## Quick Start
### Define an Agent
```python
from vizra import BaseAgent
class CustomerSupportAgent(BaseAgent):
name = 'customer_support'
description = 'Helps customers with their inquiries'
instructions = 'You are a friendly customer support assistant.'
model = 'gpt-4o'
tools = [OrderLookupTool, RefundProcessorTool]
# Or load instructions from a file
class AdvancedSupportAgent(BaseAgent):
name = 'advanced_support'
description = 'Advanced support agent with complex instructions'
instructions_file = 'prompts/advanced_support.md' # Path relative to your project
model = 'gpt-4o'
tools = [OrderLookupTool, RefundProcessorTool]
```
### Run the Agent
```python
from my_agents import CustomerSupportAgent # Import your agent
# Simple usage
response = CustomerSupportAgent.run('How do I reset my password?')
# With context for conversation continuity
from vizra import AgentContext
context = AgentContext()
agent_runner = CustomerSupportAgent.with_context(context)
response1 = agent_runner.run("Hi, I need help")
response2 = agent_runner.run("Can you check my order?")
```
### Define Tools
```python
from vizra import ToolInterface, AgentContext
import json
class OrderLookupTool(ToolInterface):
def definition(self) -> dict:
return {
'name': 'order_lookup',
'description': 'Look up order information by order ID',
'parameters': {
'type': 'object',
'properties': {
'order_id': {
'type': 'string',
'description': 'The order ID to look up',
},
},
'required': ['order_id'],
},
}
def execute(self, arguments: dict, context: AgentContext) -> str:
order_id = arguments['order_id']
# Your implementation here
return json.dumps({"order_id": order_id, "status": "shipped"})
```
## Features
- Class-based agent definition
- Tool integration with automatic execution loop (max 3 iterations)
- Context management for conversation history
- Support for multiple LLM providers via litellm
- Hook methods for monitoring and customization
- File-based instruction loading
- Simple and intuitive API
## Hooks
Agents can override hook methods to add custom behavior:
```python
class MonitoredAgent(BaseAgent):
def before_llm_call(self, messages, tools):
print(f"Making LLM call with {len(messages)} messages")
def after_llm_response(self, response, messages):
print(f"Response received with {response.usage.total_tokens} tokens")
def before_tool_call(self, tool_name, arguments, context):
print(f"Calling tool: {tool_name}")
def after_tool_result(self, tool_name, result, context):
print(f"Tool {tool_name} returned: {result}")
```
## License
MIT
Raw data
{
"_id": null,
"home_page": "https://github.com/yourusername/vizra",
"name": "vizra",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Aaron Lumsden <aaronlumsden@me.com>",
"keywords": "ai, agents, llm, openai, anthropic, litellm, framework",
"author": "Your Name",
"author_email": "Aaron Lumsden <aaronlumsden@me.com>",
"download_url": "https://files.pythonhosted.org/packages/e5/6a/fb5a11f70c4a513e134ff81a82c176bbbdbd6b24dea8d097109ffa6e950a/vizra-0.1.0.tar.gz",
"platform": null,
"description": "# Vizra - Simple AI Agent Framework for Python\n\nA lightweight, class-based AI agent framework for Python that uses litellm for LLM integration.\n\n## Installation\n\n```bash\npip install vizra\n```\n\n## Quick Start\n\n### Define an Agent\n\n```python\nfrom vizra import BaseAgent\n\nclass CustomerSupportAgent(BaseAgent):\n name = 'customer_support'\n description = 'Helps customers with their inquiries'\n instructions = 'You are a friendly customer support assistant.'\n model = 'gpt-4o'\n tools = [OrderLookupTool, RefundProcessorTool]\n\n# Or load instructions from a file\nclass AdvancedSupportAgent(BaseAgent):\n name = 'advanced_support'\n description = 'Advanced support agent with complex instructions'\n instructions_file = 'prompts/advanced_support.md' # Path relative to your project\n model = 'gpt-4o'\n tools = [OrderLookupTool, RefundProcessorTool]\n```\n\n### Run the Agent\n\n```python\nfrom my_agents import CustomerSupportAgent # Import your agent\n\n# Simple usage\nresponse = CustomerSupportAgent.run('How do I reset my password?')\n\n# With context for conversation continuity\nfrom vizra import AgentContext\n\ncontext = AgentContext()\nagent_runner = CustomerSupportAgent.with_context(context)\n\nresponse1 = agent_runner.run(\"Hi, I need help\")\nresponse2 = agent_runner.run(\"Can you check my order?\")\n```\n\n### Define Tools\n\n```python\nfrom vizra import ToolInterface, AgentContext\nimport json\n\nclass OrderLookupTool(ToolInterface):\n def definition(self) -> dict:\n return {\n 'name': 'order_lookup',\n 'description': 'Look up order information by order ID',\n 'parameters': {\n 'type': 'object',\n 'properties': {\n 'order_id': {\n 'type': 'string',\n 'description': 'The order ID to look up',\n },\n },\n 'required': ['order_id'],\n },\n }\n\n def execute(self, arguments: dict, context: AgentContext) -> str:\n order_id = arguments['order_id']\n # Your implementation here\n return json.dumps({\"order_id\": order_id, \"status\": \"shipped\"})\n```\n\n## Features\n\n- Class-based agent definition\n- Tool integration with automatic execution loop (max 3 iterations)\n- Context management for conversation history\n- Support for multiple LLM providers via litellm\n- Hook methods for monitoring and customization\n- File-based instruction loading\n- Simple and intuitive API\n\n## Hooks\n\nAgents can override hook methods to add custom behavior:\n\n```python\nclass MonitoredAgent(BaseAgent):\n def before_llm_call(self, messages, tools):\n print(f\"Making LLM call with {len(messages)} messages\")\n \n def after_llm_response(self, response, messages):\n print(f\"Response received with {response.usage.total_tokens} tokens\")\n \n def before_tool_call(self, tool_name, arguments, context):\n print(f\"Calling tool: {tool_name}\")\n \n def after_tool_result(self, tool_name, result, context):\n print(f\"Tool {tool_name} returned: {result}\")\n```\n\n## License\n\nMIT\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A simple AI agent framework for Python",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://vizra.readthedocs.io",
"Homepage": "https://github.com/yourusername/vizra",
"Issues": "https://github.com/yourusername/vizra/issues",
"Repository": "https://github.com/yourusername/vizra.git"
},
"split_keywords": [
"ai",
" agents",
" llm",
" openai",
" anthropic",
" litellm",
" framework"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "21c6b54168fa2d8cbee91f7dcffa4e24a022338e0e5d6811d1f7383d36fdb4d4",
"md5": "f2ae1e61f4b51af88ebacf7c6239367f",
"sha256": "0dcad7c37405e24d52ccbeeb0503f65dfd713f814adf609daa992f64d219e49f"
},
"downloads": -1,
"filename": "vizra-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f2ae1e61f4b51af88ebacf7c6239367f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7348,
"upload_time": "2025-08-02T15:21:49",
"upload_time_iso_8601": "2025-08-02T15:21:49.671619Z",
"url": "https://files.pythonhosted.org/packages/21/c6/b54168fa2d8cbee91f7dcffa4e24a022338e0e5d6811d1f7383d36fdb4d4/vizra-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e56afb5a11f70c4a513e134ff81a82c176bbbdbd6b24dea8d097109ffa6e950a",
"md5": "8a4f1a702d910d5f09445ba3a028985f",
"sha256": "93c0eeeb1dd320726147ff397382a7bffcf582c86a27b69675596e0b60db8818"
},
"downloads": -1,
"filename": "vizra-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8a4f1a702d910d5f09445ba3a028985f",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 15234,
"upload_time": "2025-08-02T15:21:50",
"upload_time_iso_8601": "2025-08-02T15:21:50.720658Z",
"url": "https://files.pythonhosted.org/packages/e5/6a/fb5a11f70c4a513e134ff81a82c176bbbdbd6b24dea8d097109ffa6e950a/vizra-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-02 15:21:50",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "yourusername",
"github_project": "vizra",
"github_not_found": true,
"lcname": "vizra"
}
JSON
