agentaxis 0.3.0
A production-ready, extensible multi-LLM AI Agent Framework with LiteLLM support
License: MIT
Requires Python: >=3.10
Keywords: agent, ai, automation, chatbot, litellm, llm, orchestration, rag

# 🤖 AgentAxis

A production-ready, extensible AI Agent Framework for Python. Built with Clean Architecture, it supports multi-provider LLM orchestration (via LiteLLM), memory management, and tool usage.

## 🚀 Features

-   **Multi-Provider Support**: Switch between OpenAI, Anthropic, Gemini, and local models seamlessly using LiteLLM.
-   **HTTP Endpoint Support**: Connect to any custom LLM endpoint with Bearer token authentication.
-   **System Prompts**: Configure agent behavior with built-in system prompt support.
-   **Intelligent Routing**: Architecture designed for dynamic model selection.
-   **Tooling System**: Register Python functions as tools with automatic JSON schema generation + MCP Support.
-   **Memory Management**: Pluggable memory backends (In-Memory provided, Extensible to Redis/Postgres).
-   **Vector Store / RAG**: Built-in adapter for ChromaDB.
-   **Clean Architecture**: Strictly decoupled core logic from infrastructure.

## 📦 Installation

```bash
pip install agentaxis
```

## ⚡ Quick Start

### 1. Basic Agent with System Prompt

```python
from agentaxis import AgentService, AgentEntity, InMemoryMemory, AIEngine
from agentaxis.adapters.tools import ToolRegistry
import asyncio

async def main():
    # 1. Setup AI Engine with system prompt
    llm = AIEngine(
        model="gpt-4o", 
        api_key="sk-...",
        system_prompt="You are a helpful assistant that speaks like a pirate."
    )
    memory = InMemoryMemory()
    registry = ToolRegistry()
    
    # 2. Register Tools
    @registry.register
    def get_time(timezone: str) -> str:
        """Returns current time in timezone."""
        return "12:00 PM"

    # 3. Create Agent
    entity = AgentEntity(id="bot-1", name="Helper", role_description="Assistant")
    agent = AgentService(agent_entity=entity, llm=llm, memory=memory, tool_registry=registry)

    # 4. Chat
    response = await agent.chat("What time is it in NY?")
    print(response)

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

### 2. Using Custom HTTP Endpoint

```python
from agentaxis import HTTPEngine

# Connect to any LLM endpoint
llm = HTTPEngine(
    url="https://your-llm-endpoint.com/v1/chat/completions",
    auth_token="your-bearer-token",
    model="custom-model",
    system_prompt="You are an expert coding assistant."
)
```

### 3. Switching LLM Providers

```python
# OpenAI
llm = AIEngine(model="gpt-4", api_key="sk-...")

# Anthropic
llm = AIEngine(model="claude-3-opus-20240229", api_key="sk-ant-...")

# Google Gemini
llm = AIEngine(model="gemini/gemini-pro", api_key="...")

# Local models
llm = AIEngine(model="ollama/llama2", api_base="http://localhost:11434")
```

### 4. Connecting to MCP Servers via HTTP

```python
from agentaxis import AIEngine, AgentService, AgentEntity, InMemoryMemory
from agentaxis.adapters.tools import HTTPMCPAdapter, ToolRegistry

async def main():
    # Connect to HTTP MCP server
    mcp = HTTPMCPAdapter(
        base_url="http://localhost:3000",
        auth_token="your-token"  # Optional
    )
    
    await mcp.connect()
    tools = await mcp.list_tools()
    
    # Register MCP tools
    registry = ToolRegistry()
    for tool in tools:
        registry.register_tool(tool)
    
    # Create agent with MCP tools
    llm = AIEngine(model="gpt-4", api_key="sk-...")
    entity = AgentEntity(id="bot", name="MCP Agent", role_description="Assistant")
    agent = AgentService(entity, llm, InMemoryMemory(), registry)
    
    response = await agent.chat("Use the MCP tools to help me")
    print(response)
```

## 🆕 What's New in v0.3.0

- **HTTP MCP Adapter** - Connect to MCP servers via HTTP endpoints
- **Web Search** - Optional web search using DuckDuckGo (default: OFF, no API key needed)
  - Enable with `enable_web_search=True` parameter

## What's New in v0.2.0

- **Renamed `LiteLLMAdapter` to `AIEngine`** - More intuitive naming
- **Added `HTTPEngine`** - Support for generic HTTP LLM endpoints
- **System Prompt Support** - Configure agent personality via `system_prompt` parameter
- **Google Cloud Support** - Added `litellm[google]` for Vertex AI compatibility

## 🏗️ Architecture

The framework follows **Hexagonal Architecture**:

-   **Core/Domain**: Pure business entities (`Agent`, `Message`).
-   **Core/Ports**: Interfaces for external dependencies (`BaseLLM`, `MemoryPort`).
-   **Adapters**: Concrete implementations (`AIEngine`, `HTTPEngine`, `ChromaAdapter`).

## 🛠️ Development

1.  Clone the repository.
2.  Install dependencies: `pip install -e .[dev]`
3.  Run tests: `pytest`

## 🤝 Contribution

Contributions are welcome! Please follow the Clean Architecture patterns.

## 📄 License

MIT License - see LICENSE file for details.