Metadata-Version: 2.4
Name: vizra
Version: 0.1.0
Summary: A simple AI agent framework for Python
Home-page: https://github.com/yourusername/vizra
Author: Your Name
Author-email: Aaron Lumsden <aaronlumsden@me.com>
Maintainer-email: Aaron Lumsden <aaronlumsden@me.com>
License: MIT
Project-URL: Homepage, https://github.com/yourusername/vizra
Project-URL: Repository, https://github.com/yourusername/vizra.git
Project-URL: Issues, https://github.com/yourusername/vizra/issues
Project-URL: Documentation, https://vizra.readthedocs.io
Keywords: ai,agents,llm,openai,anthropic,litellm,framework
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: litellm>=1.0.0
Requires-Dist: openai>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs>=1.5.0; extra == "docs"
Requires-Dist: mkdocs-material>=9.0.0; extra == "docs"
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 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
