eggai 0.1.5__tar.gz

eggai-0.1.5/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 EggAI Technologies GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

eggai-0.1.5/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.1
+Name: eggai
+Version: 0.1.5
+Summary: 
+Author: Stefano Tucci
+Author-email: stefanotucci89@gmail.com
+Requires-Python: >=3.10,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: aiokafka (>=0.12.0,<0.13.0)
+Description-Content-Type: text/markdown
+
+# 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.
+

eggai-0.1.5/README.md

@@ -0,0 +1,157 @@
+# 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.

eggai-0.1.5/eggai/agent.py

@@ -0,0 +1,129 @@
+import asyncio
+import json
+from typing import Dict, List, Callable
+
+from aiokafka import AIOKafkaProducer, AIOKafkaConsumer
+
+from eggai.constants import DEFAULT_CHANNEL_NAME
+from eggai.settings.kafka import KafkaSettings
+
+class Agent:
+    """
+    A message-based agent for subscribing to events and handling messages with user-defined functions.
+    """
+
+    def __init__(self, name: str):
+        """
+        Initialize the Agent.
+
+        Args:
+            name (str): The name of the agent.
+        """
+        self.name = name
+        self.kafka_settings = KafkaSettings()
+        self.producer = None
+        self.consumer = None
+        self.handlers: Dict[str, List[Callable]] = {}  # Maps channel:event_name to list of handlers
+        self.channels = set()  # Keep track of all subscribed channels
+        self.running_task = None  # Task to manage the lifecycle of the agent
+
+    def subscribe(self, event_name: str, channel_name: str = DEFAULT_CHANNEL_NAME):
+        """
+        Decorator for subscribing to a channel and binding a handler to an event name.
+
+        Args:
+            event_name (str): Name of the event within the channel.
+            channel_name (str): The name of the channel.
+
+        Returns:
+            Callable: The decorator for wrapping the handler function.
+        """
+        def decorator(func: Callable):
+            topic_event = f"{channel_name}:{event_name}"
+            if topic_event not in self.handlers:
+                self.handlers[topic_event] = []
+            self.handlers[topic_event].append(func)  # Allow multiple handlers for the same event
+            self.channels.add(channel_name)  # Register the channel name
+            return func
+        return decorator
+
+    async def _start_producer(self):
+        """
+        Start the message producer.
+        """
+        self.producer = AIOKafkaProducer(
+            bootstrap_servers=self.kafka_settings.BOOTSTRAP_SERVERS
+        )
+        await self.producer.start()
+
+    async def _start_consumer(self):
+        """
+        Start the message consumer and process incoming messages.
+        """
+        self.consumer = AIOKafkaConsumer(
+            *self.channels,  # Use the registered channels
+            bootstrap_servers=self.kafka_settings.BOOTSTRAP_SERVERS,
+            #group_id=f"{self.name}_group",
+            auto_offset_reset="latest",
+        )
+        await self.consumer.start()
+
+        print(f"Agent '{self.name}' is ready to receive messages. Channels: {self.channels}")
+
+        try:
+            async for msg in self.consumer:
+                channel_name = msg.topic
+                try:
+                    message = json.loads(msg.value.decode("utf-8"))
+                    event_name = message.get("event_name")
+                    payload = message.get("payload")
+
+                    topic_event = f"{channel_name}:{event_name}"
+                    if topic_event in self.handlers:
+                        # Call all handlers for this event
+                        for handler in self.handlers[topic_event]:
+                            await handler(payload)
+                except Exception as e:
+                    print(f"Failed to process message from {channel_name}: {e}")
+        except asyncio.CancelledError:
+            pass
+        finally:
+            print(f"Stopping agent '{self.name}'...")
+            await self.consumer.stop()
+            print(f"Agent '{self.name}' stopped.")
+
+    async def _lifecycle(self):
+        """
+        Internal lifecycle management for the agent.
+        """
+        try:
+            await self._start_producer()
+            await self._start_consumer()
+        finally:
+            await self.producer.stop()
+
+    async def run(self):
+        """
+        Run the agent lifecycle, blocking until it is stopped.
+        """
+        if self.running_task:
+            raise RuntimeError("Agent is already running.")
+        try:
+            self.running_task = asyncio.create_task(self._lifecycle())
+            await self.running_task  # Block until the lifecycle completes
+        except asyncio.CancelledError:
+            print("Agent lifecycle was cancelled.")
+        finally:
+            self.running_task = None
+
+    async def stop(self):
+        """
+        Stop the agent gracefully by cancelling the running task.
+        """
+        if not self.running_task:
+            raise RuntimeError("Agent is not running.")
+        self.running_task.cancel()
+        try:
+            await self.running_task  # Ensure the task finishes
+        except asyncio.CancelledError:
+            pass  # Task was cancelled

eggai-0.1.5/eggai/channel.py

@@ -0,0 +1,58 @@
+import asyncio
+import json
+from aiokafka import AIOKafkaProducer
+
+from eggai.constants import DEFAULT_CHANNEL_NAME
+from eggai.settings.kafka import KafkaSettings
+
+
+class Channel:
+    """
+    A standalone class to send events to Kafka channels.
+    """
+
+    _producers = {}  # Singleton dictionary to hold producers for each channel
+
+    def __init__(self, name: str = DEFAULT_CHANNEL_NAME):
+        """
+        Initialize the Channel.
+
+        Args:
+            name (str): The name of the Kafka channel (topic).
+        """
+        self.name = name
+        self.kafka_settings = KafkaSettings()
+
+    async def _get_producer(self):
+        """
+        Get or create a Kafka producer for the channel.
+
+        Returns:
+            AIOKafkaProducer: Kafka producer for the channel.
+        """
+        if self.name not in Channel._producers:
+            producer = AIOKafkaProducer(
+                bootstrap_servers=self.kafka_settings.BOOTSTRAP_SERVERS,
+            )
+            await producer.start()
+            Channel._producers[self.name] = producer
+        return Channel._producers[self.name]
+
+    async def publish(self, event: dict):
+        """
+        Publish an event to the Kafka channel.
+
+        Args:
+            event (dict): The event payload.
+        """
+        producer = await self._get_producer()
+        await producer.send_and_wait(self.name, json.dumps(event).encode("utf-8"))
+
+    @staticmethod
+    async def stop():
+        """
+        Close all Kafka producers in the singleton list.
+        """
+        for producer in Channel._producers.values():
+            await producer.stop()
+        Channel._producers.clear()

eggai-0.1.5/eggai/constants.py

@@ -0,0 +1 @@
+DEFAULT_CHANNEL_NAME = "eggai.events"

eggai-0.1.5/eggai/settings/kafka.py

@@ -0,0 +1,9 @@
+import os
+from dataclasses import dataclass
+
+
+@dataclass
+class KafkaSettings:
+    BOOTSTRAP_SERVERS: str = os.getenv("KAFKA_BOOTSTRAP_SERVERS", "localhost:19092")
+    USE_SSL: bool = os.getenv("KAFKA_USE_SSL", False)
+    CA_CONTENT: str | None = os.getenv("KAFKA_CA_CONTENT", None)

eggai-0.1.5/eggai/utils/ssl_context.py

@@ -0,0 +1,10 @@
+import ssl
+from aiokafka.helpers import create_ssl_context
+
+def create_ssl_context_from_settings(ca_content: str) -> ssl.SSLContext:
+    context = create_ssl_context()
+    context.check_hostname = False
+    context.verify_mode = ssl.CERT_NONE
+
+    context.load_verify_locations(cadata=ca_content)
+    return context

eggai-0.1.5/pyproject.toml

@@ -0,0 +1,18 @@
+[tool.poetry]
+name = "eggai"
+version = "0.1.5"
+description = ""
+authors = ["Stefano Tucci <stefanotucci89@gmail.com>"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+aiokafka = "^0.12.0"
+
+
+[tool.poetry.group.dev.dependencies]
+twine = "^6.0.1"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"