Metadata-Version: 2.4
Name: edgebrain
Version: 0.1.1
Summary: An open-source agentic framework for building AI agents with Ollama-based models
Home-page: https://github.com/madnansultandotme/ollama-agentic-framework
Author: Muhammad Adnan Sultan
Author-email: info.adnansultan@gmail.com
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: asyncio
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: chromadb>=0.4.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pytest>=7.0.0
Requires-Dist: pytest-asyncio>=0.21.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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:**
```bash
git clone https://github.com/madnansultandotme/ollama-agentic-framework.git
cd ollama-agentic-framework
```

2. **Install dependencies:**
```bash
pip install -r requirements.txt
```

3. **Install the framework:**
```bash
pip install -e .
```

### Basic Usage

Here's a simple example to get you started:

```python
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.

```bash
python examples/simple_research_agent.py
```

### 2. Multi-Agent Collaboration
Multiple agents working together to create a technical blog post.

```bash
python examples/multi_agent_collaboration.py
```

### 3. Code Generation Agent
An agent specialized in software development and code generation.

```bash
python examples/code_generation_agent.py
```

### 4. Comprehensive Demo
A full demonstration of all framework capabilities.

```bash
python examples/comprehensive_demo.py
```

## 🔧 Configuration

### Ollama Configuration

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

```python
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:

```python
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:

```python
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:

```bash
# 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](CONTRIBUTING.md) for details.

### Development Setup

1. Fork the repository
2. Create a virtual environment
3. Install development dependencies:
   ```bash
   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](LICENSE) file for details.

## 🙏 Acknowledgments

- [Ollama](https://ollama.com/) 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](docs/)
- **Issues**: [GitHub Issues](https://github.com/madnansultandotme/ollama-agentic-framework/issues)
- **Discussions**: [GitHub Discussions](https://github.com/madnansultandotme/ollama-agentic-framework/discussions)
- **Email**: info.adnansultan@gmail.com

## 🗺️ 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**

