mihrab-ai-agent 0.2.0

A flexible framework for building and deploying LLM-powered agents with multiple provider support, inspired by the mihrab that guides prayer in a mosque

MihrabAI

A flexible and extensible framework for building AI agents powered by large language models (LLMs). Like the mihrab that guides prayer in a mosque, this framework provides direction and guidance through seamless integration with multiple LLM providers, intelligent provider fallback, and memory-enabled agents.

Features

• Multi-Provider Support: Seamlessly integrate with OpenAI, Anthropic, Groq, and other LLM providers through a unified interface
• Automatic Fallback: Gracefully handle API errors with configurable fallback strategies
• Cost Optimization: Intelligently select providers based on cost, performance, or reliability
• Memory-Enabled Agents: Build agents with persistent memory for contextual conversations
• Streaming Support: Stream responses for real-time interaction
• Tool Integration: Easily extend agents with custom tools and functions
• Provider Statistics: Track usage, costs, and performance across providers

New in Version 0.2.0

• Command-Line Interface: Interact with agents directly from the terminal
• Memory Task Agents: Enhanced agents with built-in memory capabilities
• Improved Factory Functions: Easily create specialized agents with a single function call
• Extended Provider Support: Better integration with more LLM providers, including Groq
• Enhanced Documentation: More examples and clearer usage instructions
• Groq Integration: Full support for Groq's high-performance LLM models, including Llama 3

Installation

pip install mihrab-ai-agent

Quick Start

Basic Agent

import asyncio
import os
from mihrabai.core.agent import SimpleAgent
from mihrabai.models import create_model
from mihrabai.runtime.runner import AgentRunner

async def main():
    # Create a model using OpenAI
    model = await create_model(
        provider_name="openai",
        model_name="gpt-3.5-turbo",
        api_key=os.environ.get("OPENAI_API_KEY")
    )
    
    # Create a simple agent
    agent = SimpleAgent(model=model)
    
    # Create a runner
    runner = AgentRunner(agent=agent)
    
    # Run a conversation
    response = await runner.run("Hello, who are you?")
    print(response.content)

if __name__ == "__main__":
    asyncio.run(main())

Multi-Provider Agent

import asyncio
import os
from mihrabai.models.multi_provider import MultiProviderModel, OptimizationStrategy
from mihrabai.core.agent import SimpleAgent
from mihrabai.runtime.runner import AgentRunner

async def main():
    # Create a multi-provider model
    model = await MultiProviderModel.create(
        primary_model="gpt-3.5-turbo",
        fallback_models=["claude-3-sonnet", "llama2-70b-4096"],
        required_capabilities={"chat"},
        optimize_for=OptimizationStrategy.COST,
        api_keys={
            "openai": os.environ.get("OPENAI_API_KEY"),
            "anthropic": os.environ.get("ANTHROPIC_API_KEY"),
            "groq": os.environ.get("GROQ_API_KEY")
        }
    )
    
    # Create an agent with the multi-provider model
    agent = SimpleAgent(model=model)
    
    # Create a runner
    runner = AgentRunner(agent=agent)
    
    # Run a conversation
    response = await runner.run("What's the capital of Morocco?")
    print(f"Response from {model.current_provider}: {response.content}")

if __name__ == "__main__":
    asyncio.run(main())

Memory-Enabled Agent

import asyncio
import os
from mihrabai.core.memory_task_agent import MemoryEnabledTaskAgent
from mihrabai.models import create_model
from mihrabai.runtime.memory_runner import MemoryAgentRunner

async def main():
    # Create a model
    model = await create_model(
        provider_name="anthropic",
        model_name="claude-3-sonnet",
        api_key=os.environ.get("ANTHROPIC_API_KEY")
    )
    
    # Create a memory-enabled agent
    agent = MemoryEnabledTaskAgent(
        model=model,
        system_message="You are a helpful assistant with memory like the ancient scholars of the House of Wisdom.",
        max_memory_items=50,
        memory_retrieval_count=5
    )
    
    # Create a memory runner
    runner = MemoryAgentRunner(
        agent=agent,
        memory_persistence_path="./manuscripts"
    )
    
    # Start a conversation with a session ID
    session_id = "scholar123"
    
    # First interaction
    await runner.run("My name is Hassan", session_id=session_id)
    
    # Save memory
    await runner.save_memory(session_id)
    
    # Later interaction (memory will be loaded automatically)
    response = await runner.run("What's my name?", session_id=session_id)
    print(response.content)  # Should remember the name "Hassan"

if __name__ == "__main__":
    asyncio.run(main())

Architecture

The framework is built around a modular architecture like the geometric patterns of Islamic art:

• Core: Base classes for agents, messages, and memory
• Models: Provider integrations and model abstractions
• Runtime: Execution environment for agents
• Utils: Logging, tracing, and other utilities

Supported Providers

• OpenAI: GPT-3.5, GPT-4, and other models
• Anthropic: Claude 3 Opus, Claude 3 Sonnet, and other models
• Groq: Llama 3-70B, Llama 3-8B, Llama 2-70B, Mixtral, and other models
  • High-performance inference with low latency
  • Cost-effective alternative to other providers
  • See our Groq Integration Guide for details
• Easily extensible to other providers

Advanced Usage

Custom Tools

from mihrabai.core.task_agent import TaskAgent, ToolConfig
from mihrabai.core.message import Message, MessageRole

# Define a tool function
def get_weather(params):
    location = params.get("location", "Marrakech")
    return f"The weather in {location} is sunny and 85°F"

# Create a tool configuration
weather_tool = ToolConfig(
    name="get_weather",
    description="Get the current weather for a location",
    function=get_weather,
    parameters={
        "type": "object",
        "properties": {
            "location": {
                "type": "string",
                "description": "The city and country, e.g. Marrakech, Morocco"
            }
        },
        "required": ["location"]
    }
)

# Create an agent with the tool
agent = TaskAgent(
    model=model,
    system_message="You are a helpful assistant that can check the weather.",
    tools=[weather_tool]
)

Provider Statistics

from mihrabai.models.provider_stats import ProviderStatsManager

# Create a stats manager
stats_manager = ProviderStatsManager()

# Record usage
stats_manager.record_request(
    provider="openai",
    model="gpt-4",
    prompt_tokens=500,
    completion_tokens=200,
    cost=0.01
)

# Get usage report
report = stats_manager.get_usage_report()
print(f"Total cost: ${report['total_cost']}")
print(f"Total tokens: {report['total_tokens']}")

Configuration

You can configure the framework using environment variables:

# API Keys
export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"
export GROQ_API_KEY="your-groq-key"

# Logging
export LOG_LEVEL="INFO"
export LOG_FILE="logs/mihrabai.log"

# Runtime configuration
export MAX_RETRIES=3
export RETRY_DELAY=2
export REQUEST_TIMEOUT=30

Documentation

Comprehensive documentation is available in the src/mihrabai/docs directory:

• Quick Start Guide
• Using Mihrab with Tools
• API Reference
• Creating Custom Tools
• Using Groq Provider
• Multi-Agent Systems
• Handoff System

Development

Setup

# Clone the repository
git clone https://github.com/yourusername/mihrabai.git
cd mihrabai

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e ".[dev]"

Running Tests

# Run all tests
pytest

# Run specific tests
pytest tests/unit/
pytest tests/integration/

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Thanks to all the LLM providers for their amazing models
• Inspired by LangChain, AutoGPT, and other agent frameworks
• Named after the mihrab, the niche in a mosque that indicates the direction of prayer, symbolizing guidance and direction