edgebrain 0.1.1

An open-source agentic framework for building AI agents with Ollama-based models

EdgeBrain: Ollama Agentic Framework

A powerful, extensible framework for building autonomous AI agents using Ollama-based language models. This framework provides a complete solution for creating, orchestrating, and managing AI agents that can work independently or collaboratively to solve complex tasks.

🌟 Features

Core Capabilities

• Multi-Agent Orchestration: Coordinate multiple agents working together on complex tasks
• Flexible Agent Architecture: Create specialized agents with custom roles, capabilities, and behaviors
• Tool Integration: Extensible tool system for web search, file operations, calculations, and custom tools
• Memory Management: Persistent memory system with semantic search capabilities
• Workflow Engine: Define and execute complex multi-step workflows with dependencies
• Inter-Agent Communication: Built-in messaging system for agent collaboration
• Ollama Integration: Native support for all Ollama models with automatic model management

Advanced Features

• Asynchronous Processing: Full async/await support for high-performance operations
• Vector Memory: Semantic memory storage with embedding-based retrieval
• Task Scheduling: Priority-based task queue with automatic assignment
• Error Handling: Robust error handling and recovery mechanisms
• Extensible Architecture: Plugin-based system for easy customization and extension
• Comprehensive Testing: Full test suite with mock integrations for development

🚀 Quick Start

Prerequisites

• Python 3.11 or higher
• Ollama installed and running
• SQLite (included with Python)

Installation

1. Clone the repository:

git clone https://github.com/madnansultandotme/ollama-agentic-framework.git
cd ollama-agentic-framework

2. Install dependencies:

pip install -r requirements.txt

3. Install the framework:

pip install -e .

Basic Usage

Here's a simple example to get you started:

import asyncio
from src.core.orchestrator import AgentOrchestrator
from src.integration.ollama_client import OllamaIntegrationLayer
from src.tools.tool_registry import ToolRegistry
from src.memory.memory_manager import MemoryManager

async def main():
    # Initialize components
    ollama_integration = OllamaIntegrationLayer()
    await ollama_integration.initialize()
    
    tool_registry = ToolRegistry()
    memory_manager = MemoryManager()
    
    # Create orchestrator
    orchestrator = AgentOrchestrator(
        ollama_integration=ollama_integration,
        tool_registry=tool_registry,
        memory_manager=memory_manager
    )
    
    # Create an agent
    agent = orchestrator.register_agent(
        agent_id="researcher_001",
        role="Research Specialist",
        description="Conducts research and analysis",
        model="llama3.1"
    )
    
    # Start the orchestrator
    await orchestrator.start()
    
    # Create and assign a task
    task_id = await orchestrator.create_task(
        description="Research the latest trends in artificial intelligence"
    )
    
    await orchestrator.assign_task_to_agent(task_id, agent.agent_id)
    
    # Monitor execution
    # ... (see examples for complete implementation)
    
    await orchestrator.stop()

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

📚 Documentation

Core Components

Agent Orchestrator

The central control unit that manages agents, tasks, and workflows. It handles:

• Agent lifecycle management
• Task distribution and execution
• Inter-agent communication
• Workflow orchestration

Agents

Autonomous entities with specific roles and capabilities. Each agent has:

• Unique identity and role
• Custom capabilities and tools
• Memory and learning systems
• Goal-oriented behavior

Tool Registry

Extensible system for managing tools that agents can use:

• Built-in tools (web search, file operations, calculations)
• Custom tool development
• Tool discovery and validation
• Secure tool execution

Memory Manager

Persistent storage system for agent knowledge:

• Short-term context memory
• Long-term knowledge storage
• Semantic search capabilities
• Memory importance scoring

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Agent Orchestrator                       │
├─────────────────────────────────────────────────────────────┤
│  Task Management  │  Agent Lifecycle  │  Communication     │
│  Workflow Engine  │  Resource Mgmt    │  Event Handling    │
└─────────────────────────────────────────────────────────────┘
           │                    │                    │
           ▼                    ▼                    ▼
┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│     Agents      │  │  Tool Registry  │  │ Memory Manager  │
│                 │  │                 │  │                 │
│ • Research      │  │ • Web Search    │  │ • Vector Store  │
│ • Writing       │  │ • File Ops      │  │ • Semantic      │
│ • Analysis      │  │ • Calculator    │  │   Search        │
│ • Custom        │  │ • Custom Tools  │  │ • Persistence   │
└─────────────────┘  └─────────────────┘  └─────────────────┘
           │                    │                    │
           └────────────────────┼────────────────────┘
                               ▼
                    ┌─────────────────┐
                    │ Ollama Client   │
                    │                 │
                    │ • Model Mgmt    │
                    │ • Generation    │
                    │ • Tool Calling  │
                    │ • Streaming     │
                    └─────────────────┘

🛠️ Examples

The framework includes several comprehensive examples:

1. Simple Research Agent

A basic agent that conducts research and provides summaries.

python examples/simple_research_agent.py

2. Multi-Agent Collaboration

Multiple agents working together to create a technical blog post.

python examples/multi_agent_collaboration.py

3. Code Generation Agent

An agent specialized in software development and code generation.

python examples/code_generation_agent.py

4. Comprehensive Demo

A full demonstration of all framework capabilities.

python examples/comprehensive_demo.py

🔧 Configuration

Ollama Configuration

The framework automatically detects and configures Ollama models. You can customize the configuration:

ollama_integration = OllamaIntegrationLayer(
    base_url="http://localhost:11434",  # Ollama server URL
    default_model="llama3.1",           # Default model to use
    timeout=30                          # Request timeout
)

Memory Configuration

Configure the memory system for your needs:

memory_manager = MemoryManager(
    db_path="agent_memory.db",    # Database file path
    embedding_dim=384             # Embedding vector dimension
)

Tool Configuration

Add custom tools to extend agent capabilities:

from src.tools.tool_registry import BaseTool

class CustomTool(BaseTool):
    def __init__(self):
        super().__init__(
            name="custom_tool",
            description="My custom tool",
            category="custom"
        )
    
    async def execute(self, param: str) -> dict:
        # Tool implementation
        return {"result": f"Processed: {param}"}

# Register the tool
tool_registry.register_tool(CustomTool())

🧪 Testing

Run the test suite to ensure everything is working correctly:

# Run all tests
python -m pytest tests/ -v

# Run specific test files
python -m pytest tests/test_ollama_integration.py -v
python -m pytest tests/test_tool_registry.py -v

# Run with coverage
python -m pytest tests/ --cov=src --cov-report=html

📦 Project Structure

ollama_agentic_framework/
├── src/                          # Source code
│   ├── core/                     # Core framework components
│   │   ├── agent.py             # Agent implementation
│   │   └── orchestrator.py      # Orchestrator implementation
│   ├── integration/              # External integrations
│   │   └── ollama_client.py     # Ollama integration
│   ├── tools/                    # Tool system
│   │   └── tool_registry.py     # Tool registry and built-in tools
│   ├── memory/                   # Memory management
│   │   └── memory_manager.py    # Memory system implementation
│   └── __init__.py
├── tests/                        # Test suite
│   ├── test_ollama_integration.py
│   ├── test_tool_registry.py
│   └── __init__.py
├── examples/                     # Usage examples
│   ├── simple_research_agent.py
│   ├── multi_agent_collaboration.py
│   ├── code_generation_agent.py
│   └── comprehensive_demo.py
├── docs/                         # Documentation
├── requirements.txt              # Dependencies
├── setup.py                      # Package setup
└── README.md                     # This file

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create a virtual environment
3. Install development dependencies:

   pip install -r requirements.txt
   pip install -e .
   

4. Run tests to ensure everything works
5. Make your changes
6. Add tests for new functionality
7. Submit a pull request

Code Style

• Follow PEP 8 guidelines
• Use type hints for all functions
• Add docstrings for all public methods
• Maintain test coverage above 90%

📄 License

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

🙏 Acknowledgments

• Ollama for providing the foundation for local LLM inference
• The open-source AI community for inspiration and best practices
• Contributors and users who help improve this framework

📞 Support

• Documentation: Full documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [e-mail]

🗺️ Roadmap

Version 1.0 (Current)

• ✅ Core agent framework
• ✅ Ollama integration
• ✅ Basic tool system
• ✅ Memory management
• ✅ Multi-agent orchestration

Version 1.1 (Planned)

• 🔄 Enhanced tool ecosystem
• 🔄 Web interface for agent management
• 🔄 Advanced workflow templates
• 🔄 Performance optimizations

Version 2.0 (Future)

• 🔮 Multi-modal agent support
• 🔮 Distributed agent networks
• 🔮 Advanced learning algorithms
• 🔮 Enterprise features

---

Built with ❤️ by the Muhammad Adnan Sultan