# EggAI Multi-Agent Framework 🤖

[![Python 3.x](https://img.shields.io/badge/python-3.x-blue?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green?style=for-the-badge&logo=opensourceinitiative&logoColor=white)](https://opensource.org/licenses/MIT)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge&logo=github&logoColor=white)](https://github.com/eggai-tech/eggai/pulls)
[![GitHub Issues](https://img.shields.io/github/issues/eggai-tech/eggai?style=for-the-badge&logo=github&logoColor=white)](https://github.com/eggai-tech/eggai/issues)
[![GitHub Stars](https://img.shields.io/github/stars/eggai-tech/eggai?style=for-the-badge&logo=github&logoColor=white)](https://github.com/eggai-tech/eggai/stargazers)

`EggAI Multi-Agent Framework` is an async-first framework for building, deploying, and scaling multi-agent systems for modern enterprise environments.

---

## Table of Contents

[Overview](#overview) •
[Features](#features) •
[Installation](#installation) •
[Quick Start](#quick-start) •
[Core Concepts](#core-concepts) •
[Examples](#examples) •
[Development](#development) •
[License](#license)

---

## 🌟 Overview

`EggAI` is a Python library that simplifies the development of multi-agent systems by providing a high-level abstraction over Kafka. It allows developers to focus on business logic by handling the complexities of Kafka producers and consumers.

---

## ✨ Features

- **Event-Driven Architecture**: Build systems that react to events in real-time.
- **Agent Orchestration**: Manage multiple agents with ease.
- **Kafka Integration**: Seamlessly integrate with Kafka topics.
- **Async-First Design**: Utilize Python's async features for high performance.
- **Minimal Boilerplate**: Focus on business logic without worrying about Kafka details.

---

## Installation

Install `EggAI` via pip:

```bash
pip install eggai
```

---

## Quick Start

Here's how you can quickly set up an agent to handle events in an event-driven system:

```python
import asyncio

from eggai.agent import Agent
from eggai.channel import Channel

CHANNEL_NAME = "events"

agent = Agent("OrderAgent")

@agent.subscribe(channel_name=CHANNEL_NAME, event_name="order_requested")
async def handle_order_requested(event):
    print(f"[ORDER AGENT]: Received order request. Event: {event}")
    await Channel(name=CHANNEL_NAME).publish({"event_name": "order_created", "payload": event})


@agent.subscribe(channel_name=CHANNEL_NAME, event_name="order_created")
async def handle_order_created(event):
    print(f"[ORDER AGENT]: Order created. Event: {event}")


async def main():
    task = agent.start()
    await asyncio.sleep(2)

    await Channel(CHANNEL_NAME).publish({
        "event_name": "order_requested",
        "payload": {
            "product": "Laptop",
            "quantity": 1
        }
    })

    await asyncio.sleep(2)
    task.cancel()
    await Channel.stop()


if __name__ == "__main__":
    try:
        asyncio.run(main())
    except KeyboardInterrupt:
        print("Shutting down...")

```

This code demonstrates how to define an `Agent` and use it to process events from Kafka topics.

This repository contains a few applications you can use as a reference:

---

## Core Concepts

### Agent

An `Agent` is responsible for subscribing to Kafka topics, processing events, and orchestrating tasks using user-defined handlers. The key features of the `Agent` class include:

- **Event Subscription**: Bind event handlers to specific events using the `subscribe` decorator.
- **Lifecycle Management**: Manage producer and consumer lifecycles seamlessly.
- **Minimal Boilerplate**: Focus on business logic without worrying about Kafka details.

### Channel

A `Channel` abstracts the Kafka producer interface to publish events to specific Kafka topics. Key features include:

- **Event Publishing**: Send events to Kafka topics easily.
- **Singleton Producers**: Manage Kafka producers efficiently across multiple channels.

---

## Examples

For detailed examples, please refer to [examples](examples).

---

## Development

### Setting Up

Clone the repository and install the development dependencies:

```bash
git clone https://github.com/eggai-tech/eggai.git
cd eggai
pip install -r requirements.txt
```

### Running Tests

Run the tests using:

```bash
pytest
```

---

## License

This project is licensed under the MIT License. See the [LICENSE.md](LICENSE.md) file for details.
