h-message-bus 0.0.3__tar.gz

h_message_bus-0.0.3/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: h_message_bus
+Version: 0.0.3
+Summary: Message bus integration for HAI
+Author-email: shoebill <shoebill.hai@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: python-dotenv~=1.1.0
+Requires-Dist: nats-py~=2.10.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# H Message Bus
+
+A message bus integration for HAI applications based on NATS.io
+
+## Overview
+
+H Message Bus provides a robust, asynchronous messaging infrastructure built on NATS.io for HAI applications. It enables seamless communication between components through a publish-subscribe pattern, supporting both fire-and-forget messaging and request-response patterns.
+
+## Features
+
+- **Asynchronous Communication**: Built for modern, non-blocking I/O operations
+- **Flexible Message Routing**: Publish and subscribe to specific topics
+- **High Reliability**: Automatic reconnection handling and configurable timeouts
+- **Simple API**: Focus on core messaging functionality with minimal dependencies
+
+## Installation
+
+```bash
+pip install h_message_bus
+```
+
+## Requirements
+
+- Python 3.10+
+- NATS.io server (can be run via Docker)
+
+## Topics
+
+H Message Bus includes predefined topics following the convention: `hai.[source].[destination].[action]`
+
+Available topics:
+
+| Topic Constant                  | Topic String           | Description                         |
+|---------------------------------|------------------------|-------------------------------------|
+| `Topic.AI_SEND_TG_CHAT_MESSAGE` | `hai.ai.tg.chat.send`  | AI sending message to Telegram chat |
+| `Topic.AI_VECTORS_SAVE`         | `hai.ai.vectors.save`  | AI saving data to vector database   |
+| `Topic.AI_VECTORS_QUERY`        | `hai.ai.vectors.query` | AI querying vector database         |
+| `Topic.TG_SEND_AI_CHAT_MESSAGE` | `hai.tg.ai.chat.send`  | Telegram sending message to AI      |
+
+You can use these predefined topics or create your own topic strings.
+
+## Quick Start
+
+### Start a NATS Server
+
+The easiest way to get started is with Docker:
+
+```bash
+docker-compose up -d
+```
+
+### Create a Publisher
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsPublisherAdapter, HaiMessage, Topic
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create publisher adapter
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await publisher.connect()
+    
+    # Create and publish a message using a predefined topic
+    message = HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="service-a",
+        topic=Topic.TG_SEND_AI_CHAT_MESSAGE,
+        payload={"text": "Hello AI, this is a message from Telegram", "chat_id": 12345}
+    )
+    
+    # Publish message
+    await publisher.publish(message)
+    
+    # Clean up
+    await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Create a Subscriber
+
+```python
+import asyncio
+from h_message_bus import NatsConfig, NatsSubscriberAdapter, HaiMessage, Topic
+
+async def message_handler(message: HaiMessage):
+    print(f"Received message: {message.message_id}")
+    print(f"From: {message.sender}")
+    print(f"Topic: {message.topic}")
+    print(f"Payload: {message.payload}")
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create subscriber
+    subscriber = NatsSubscriberAdapter(config)
+    
+    # Connect to NATS
+    await subscriber.connect()
+    
+    # Subscribe to a topic
+    await subscriber.subscribe(Topic.TG_SEND_AI_CHAT_MESSAGE, message_handler)
+    
+    # Keep the application running
+    try:
+        print("Subscriber running. Press Ctrl+C to exit.")
+        while True:
+            await asyncio.sleep(1)
+    except KeyboardInterrupt:
+        # Clean up
+        await subscriber.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Request-Response Pattern
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsPublisherAdapter, HaiMessage, Topic
+
+async def main():
+    config = NatsConfig(server="nats://localhost:4222")
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await publisher.connect()
+    
+    request_message = HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="client-service",
+        topic=Topic.AI_VECTORS_QUERY,
+        payload={"query": "find similar documents", "limit": 10}
+    )
+    
+    # Send request and wait for response (with timeout)
+    response = await publisher.request(request_message, timeout=5.0)
+    
+    if response:
+        print(f"Received response: {response.payload}")
+    else:
+        print("Request timed out")
+    
+    await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Creating a Service with Request Handler
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsSubscriberAdapter, NatsPublisherAdapter, HaiMessage, Topic
+
+async def request_handler(request: HaiMessage):
+    print(f"Received request: {request.message_id}")
+    print(f"Payload: {request.payload}")
+    
+    # Process the request
+    result = {"status": "success", "data": {"result": 42}}
+    
+    # Create a response message
+    return HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="service-b",
+        topic=f"{request.topic}.response",
+        payload=result,
+        correlation_id=request.message_id
+    )
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create subscriber for handling requests
+    subscriber = NatsSubscriberAdapter(config)
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await subscriber.connect()
+    await publisher.connect()
+    
+    # Register request handler for vector database queries
+    await subscriber.subscribe_with_response(Topic.AI_VECTORS_QUERY, request_handler, publisher)
+    
+    # Keep the application running
+    try:
+        print("Service running. Press Ctrl+C to exit.")
+        while True:
+            await asyncio.sleep(1)
+    except KeyboardInterrupt:
+        # Clean up
+        await subscriber.close()
+        await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration Options
+
+The `NatsConfig` class allows you to customize your NATS connection:
+
+| Parameter                | Description                                  | Default       |
+|--------------------------|----------------------------------------------|---------------|
+| `server`                 | NATS server address                          | Required      |
+| `max_reconnect_attempts` | Maximum reconnection attempts                | 10            |
+| `reconnect_time_wait`    | Time between reconnection attempts (seconds) | 2             |
+| `connection_timeout`     | Connection timeout (seconds)                 | 2             |
+| `ping_interval`          | Interval for ping frames (seconds)           | 20            |
+| `max_outstanding_pings`  | Maximum unanswered pings before disconnect   | 5             |
+| `max_payload`            | Maximum size of the payload in bytes         | 1048576 (1MB) |
+
+## API Reference
+
+### Exported Classes
+
+The following classes are exported directly from the package:
+
+- `NatsConfig` - Configuration for the NATS connection
+- `HaiMessage` - Message structure for HAI communication
+- `NatsPublisherAdapter` - Adapter for publishing messages
+- `NatsSubscriberAdapter` - Adapter for subscribing to messages
+- `MessageProcessor` - Processing incoming messages
+- `NatsClientRepository` - Low-level NATS client operations
+- `Topic` - Enumeration of predefined topic strings
+
+### HaiMessage Structure
+
+The `HaiMessage` class is the core data structure used for all messaging:
+
+```python
+class HaiMessage:
+    message_id: str       # Unique identifier for the message
+    sender: str           # Identifier of the sender
+    topic: str            # The topic or channel for the message
+    payload: dict         # Actual message data
+    correlation_id: str = None  # Optional reference to a related message
+    timestamp: float = None     # Optional message creation timestamp
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

h_message_bus-0.0.3/README.md

@@ -0,0 +1,262 @@
+# H Message Bus
+
+A message bus integration for HAI applications based on NATS.io
+
+## Overview
+
+H Message Bus provides a robust, asynchronous messaging infrastructure built on NATS.io for HAI applications. It enables seamless communication between components through a publish-subscribe pattern, supporting both fire-and-forget messaging and request-response patterns.
+
+## Features
+
+- **Asynchronous Communication**: Built for modern, non-blocking I/O operations
+- **Flexible Message Routing**: Publish and subscribe to specific topics
+- **High Reliability**: Automatic reconnection handling and configurable timeouts
+- **Simple API**: Focus on core messaging functionality with minimal dependencies
+
+## Installation
+
+```bash
+pip install h_message_bus
+```
+
+## Requirements
+
+- Python 3.10+
+- NATS.io server (can be run via Docker)
+
+## Topics
+
+H Message Bus includes predefined topics following the convention: `hai.[source].[destination].[action]`
+
+Available topics:
+
+| Topic Constant                  | Topic String           | Description                         |
+|---------------------------------|------------------------|-------------------------------------|
+| `Topic.AI_SEND_TG_CHAT_MESSAGE` | `hai.ai.tg.chat.send`  | AI sending message to Telegram chat |
+| `Topic.AI_VECTORS_SAVE`         | `hai.ai.vectors.save`  | AI saving data to vector database   |
+| `Topic.AI_VECTORS_QUERY`        | `hai.ai.vectors.query` | AI querying vector database         |
+| `Topic.TG_SEND_AI_CHAT_MESSAGE` | `hai.tg.ai.chat.send`  | Telegram sending message to AI      |
+
+You can use these predefined topics or create your own topic strings.
+
+## Quick Start
+
+### Start a NATS Server
+
+The easiest way to get started is with Docker:
+
+```bash
+docker-compose up -d
+```
+
+### Create a Publisher
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsPublisherAdapter, HaiMessage, Topic
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create publisher adapter
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await publisher.connect()
+    
+    # Create and publish a message using a predefined topic
+    message = HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="service-a",
+        topic=Topic.TG_SEND_AI_CHAT_MESSAGE,
+        payload={"text": "Hello AI, this is a message from Telegram", "chat_id": 12345}
+    )
+    
+    # Publish message
+    await publisher.publish(message)
+    
+    # Clean up
+    await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Create a Subscriber
+
+```python
+import asyncio
+from h_message_bus import NatsConfig, NatsSubscriberAdapter, HaiMessage, Topic
+
+async def message_handler(message: HaiMessage):
+    print(f"Received message: {message.message_id}")
+    print(f"From: {message.sender}")
+    print(f"Topic: {message.topic}")
+    print(f"Payload: {message.payload}")
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create subscriber
+    subscriber = NatsSubscriberAdapter(config)
+    
+    # Connect to NATS
+    await subscriber.connect()
+    
+    # Subscribe to a topic
+    await subscriber.subscribe(Topic.TG_SEND_AI_CHAT_MESSAGE, message_handler)
+    
+    # Keep the application running
+    try:
+        print("Subscriber running. Press Ctrl+C to exit.")
+        while True:
+            await asyncio.sleep(1)
+    except KeyboardInterrupt:
+        # Clean up
+        await subscriber.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Request-Response Pattern
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsPublisherAdapter, HaiMessage, Topic
+
+async def main():
+    config = NatsConfig(server="nats://localhost:4222")
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await publisher.connect()
+    
+    request_message = HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="client-service",
+        topic=Topic.AI_VECTORS_QUERY,
+        payload={"query": "find similar documents", "limit": 10}
+    )
+    
+    # Send request and wait for response (with timeout)
+    response = await publisher.request(request_message, timeout=5.0)
+    
+    if response:
+        print(f"Received response: {response.payload}")
+    else:
+        print("Request timed out")
+    
+    await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Creating a Service with Request Handler
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsSubscriberAdapter, NatsPublisherAdapter, HaiMessage, Topic
+
+async def request_handler(request: HaiMessage):
+    print(f"Received request: {request.message_id}")
+    print(f"Payload: {request.payload}")
+    
+    # Process the request
+    result = {"status": "success", "data": {"result": 42}}
+    
+    # Create a response message
+    return HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="service-b",
+        topic=f"{request.topic}.response",
+        payload=result,
+        correlation_id=request.message_id
+    )
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create subscriber for handling requests
+    subscriber = NatsSubscriberAdapter(config)
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await subscriber.connect()
+    await publisher.connect()
+    
+    # Register request handler for vector database queries
+    await subscriber.subscribe_with_response(Topic.AI_VECTORS_QUERY, request_handler, publisher)
+    
+    # Keep the application running
+    try:
+        print("Service running. Press Ctrl+C to exit.")
+        while True:
+            await asyncio.sleep(1)
+    except KeyboardInterrupt:
+        # Clean up
+        await subscriber.close()
+        await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration Options
+
+The `NatsConfig` class allows you to customize your NATS connection:
+
+| Parameter                | Description                                  | Default       |
+|--------------------------|----------------------------------------------|---------------|
+| `server`                 | NATS server address                          | Required      |
+| `max_reconnect_attempts` | Maximum reconnection attempts                | 10            |
+| `reconnect_time_wait`    | Time between reconnection attempts (seconds) | 2             |
+| `connection_timeout`     | Connection timeout (seconds)                 | 2             |
+| `ping_interval`          | Interval for ping frames (seconds)           | 20            |
+| `max_outstanding_pings`  | Maximum unanswered pings before disconnect   | 5             |
+| `max_payload`            | Maximum size of the payload in bytes         | 1048576 (1MB) |
+
+## API Reference
+
+### Exported Classes
+
+The following classes are exported directly from the package:
+
+- `NatsConfig` - Configuration for the NATS connection
+- `HaiMessage` - Message structure for HAI communication
+- `NatsPublisherAdapter` - Adapter for publishing messages
+- `NatsSubscriberAdapter` - Adapter for subscribing to messages
+- `MessageProcessor` - Processing incoming messages
+- `NatsClientRepository` - Low-level NATS client operations
+- `Topic` - Enumeration of predefined topic strings
+
+### HaiMessage Structure
+
+The `HaiMessage` class is the core data structure used for all messaging:
+
+```python
+class HaiMessage:
+    message_id: str       # Unique identifier for the message
+    sender: str           # Identifier of the sender
+    topic: str            # The topic or channel for the message
+    payload: dict         # Actual message data
+    correlation_id: str = None  # Optional reference to a related message
+    timestamp: float = None     # Optional message creation timestamp
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

h_message_bus-0.0.3/pyproject.toml

@@ -0,0 +1,28 @@
+   [build-system]
+   requires = ["setuptools>=61.0"]
+   build-backend = "setuptools.build_meta"
+
+   [project]
+   name = "h_message_bus"
+   version = "0.0.3"
+   authors = [
+       {name = "shoebill", email = "shoebill.hai@gmail.com"},
+   ]
+   description = "Message bus integration for HAI"
+   readme = "README.md"
+   requires-python = ">=3.10"
+   classifiers = [
+       "Programming Language :: Python :: 3",
+       "License :: OSI Approved :: MIT License",  # Choose appropriate license
+       "Operating System :: OS Independent",
+   ]
+   dependencies = [
+       "python-dotenv~=1.1.0",
+       "nats-py~=2.10.0",
+   ]
+
+   [project.optional-dependencies]
+   dev = [
+       "pytest",
+       # Other development dependencies
+   ]

h_message_bus-0.0.3/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

h_message_bus-0.0.3/src/h_message_bus/__init__.py

@@ -0,0 +1,11 @@
+from .adapters.nats_publisher_adapter import NatsPublisherAdapter
+from .adapters.nats_subscriber_adapter import NatsSubscriberAdapter
+from .application.message_processor import MessageProcessor
+from .infrastructure.nats_client_repository import NatsClientRepository
+from .infrastructure.nats_config import NatsConfig
+from .domain.hai_message import HaiMessage
+
+
+__all__ = ['NatsConfig', 'HaiMessage', 'MessageProcessor', 'NatsClientRepository', 'NatsSubscriberAdapter', 'NatsPublisherAdapter']
+
+

h_message_bus-0.0.3/src/h_message_bus/adapters/nats_message_adapter.py

@@ -0,0 +1,36 @@
+from nats.aio.msg import Msg as NatsMsg
+
+from src.h_message_bus.application.message_processor import MessageProcessor
+from src.h_message_bus.domain.hai_message import HaiMessage
+
+
+class NatsMessageAdapter:
+    """
+    Adapter class to handle incoming NATS messages and process them using
+    a message processor.
+
+    The class serves as a bridge between NATS messaging and a domain-specific
+    message processor. It listens for incoming messages, converts them into
+    the appropriate domain object, processes them with the provided message
+    processor, and optionally sends a response if required.
+
+    :ivar processor: Instance of the message processor used to process domain
+        messages.
+    :type processor: MessageProcessor
+    """
+    def __init__(self, message_processor: MessageProcessor):
+        self.processor = message_processor
+
+    async def handle_nats_message(self, msg: NatsMsg) -> None:
+        """Handle incoming NATS message."""
+        try:
+            domain_message = HaiMessage.from_json(msg.data.decode())
+
+            response = await self.processor.process(domain_message)
+
+            # If there's a reply subject and a response, send it back
+            if msg.reply and response:
+                await msg.respond(response.to_json().encode())
+
+        except Exception as e:
+            print(f"Error processing message: {e}")

h_message_bus-0.0.3/src/h_message_bus/adapters/nats_publisher_adapter.py

@@ -0,0 +1,46 @@
+from typing import Optional
+
+from src.h_message_bus.application.message_publisher import MessagePublisher
+from src.h_message_bus.domain.hai_message import HaiMessage
+from src.h_message_bus.infrastructure.nats_client_repository import NatsClientRepository
+
+
+class NatsPublisherAdapter(MessagePublisher):
+    """
+    Adapter for publishing and requesting messages using a NATS client.
+
+    This class interacts with a NATS client to publish messages to specified
+    topics or send requests and wait for responses. It is designed to work
+    with the `HaiMessage` format for message objects. The adapter encapsulates
+    underlying communication details and provides an easy-to-use interface
+    for message-based interactions.
+
+    :ivar nats_client: Instance of NatsClientRepository used for interacting
+                       with the NATS system.
+    :type nats_client: NatsClientRepository
+    """
+
+    def __init__(self, nats_client: NatsClientRepository):
+        self.nats_client = nats_client
+
+    async def publish(self, message: HaiMessage) -> None:
+        """Publish a message to NATS."""
+        await self.nats_client.publish(
+            message.topic,
+            message.to_json().encode()
+        )
+
+    async def request(self, message: HaiMessage, timeout: float = 2.0) -> Optional[HaiMessage]:
+        """Send a request and wait for a response."""
+        try:
+            response = await self.nats_client.request(
+                message.topic,
+                message.to_json().encode(),
+                timeout=timeout
+            )
+            if response:
+                return HaiMessage.from_json(response.decode())
+            return None
+        except Exception as e:
+            print(f"Request failed: {e}")
+            return None

h_message_bus-0.0.3/src/h_message_bus/adapters/nats_subscriber_adapter.py

@@ -0,0 +1,53 @@
+from typing import Dict
+
+from src.h_message_bus.adapters.nats_message_adapter import NatsMessageAdapter
+from src.h_message_bus.application.message_processor import MessageProcessor
+from src.h_message_bus.application.message_subcriber import MessageSubscriber
+from src.h_message_bus.infrastructure.nats_client_repository import NatsClientRepository
+
+
+class NatsSubscriberAdapter(MessageSubscriber):
+    """
+    Handles subscription to message topics using a NATS client.
+
+    The class provides methods to subscribe to specific topics with a
+    message processor and to manage subscriptions by unsubscribing from
+    all topics. It works with a NATS client repository and acts as a
+    bridge between the messaging system and the application.
+
+    :ivar nats_client: The NATS client repository used for managing
+        subscriptions.
+    :type nats_client: NatsClientRepository
+    :ivar subscriptions: A list of active subscription objects.
+    :type subscriptions: list
+    :ivar adapters: A dictionary mapping topic names to their respective
+        message adapters.
+    :type adapters: Dict[str, NatsMessageAdapter]
+    """
+
+    def __init__(self, nats_client: NatsClientRepository):
+        self.nats_client = nats_client
+        self.subscriptions = []
+        self.adapters: Dict[str, NatsMessageAdapter] = {}
+
+    async def subscribe(self, topic: str, processor: MessageProcessor) -> None:
+        """Subscribe to a topic with a message handler."""
+        # Create an adapter for this use case
+        message_adapter = NatsMessageAdapter(processor)
+        self.adapters[topic] = message_adapter
+
+        # Subscribe to the topic
+        subscription = await self.nats_client.subscribe(
+            topic,
+            callback=message_adapter.handle_nats_message
+        )
+
+        self.subscriptions.append(subscription)
+
+    async def unsubscribe_all(self) -> None:
+        """Unsubscribe from all subscriptions."""
+        for subscription in self.subscriptions:
+            await subscription.unsubscribe()
+
+        self.subscriptions = []
+        self.adapters = {}

h_message_bus-0.0.3/src/h_message_bus/application/message_processor.py

@@ -0,0 +1,21 @@
+from abc import abstractmethod, ABC
+from typing import Optional
+
+from src.h_message_bus.domain.hai_message import HaiMessage
+
+
+class MessageProcessor(ABC):
+    """
+    Defines an abstract base class for processing messages.
+
+    This class serves as a blueprint for creating message processing
+    implementations. It enforces a concrete implementation of the
+    'process' method, which is expected to handle a given message
+    and optionally return a response. The specific logic of
+    processing must be defined in derived subclasses.
+    """
+
+    @abstractmethod
+    async def process(self, message: HaiMessage) -> Optional[HaiMessage]:
+        """Process a message and optionally return a response."""
+        pass

h_message_bus-0.0.3/src/h_message_bus/application/message_publisher.py

@@ -0,0 +1,25 @@
+from abc import abstractmethod, ABC
+from typing import Optional
+
+from src.h_message_bus.domain.hai_message import HaiMessage
+
+
+class MessagePublisher(ABC):
+    """
+    Represents an abstract base class for a message publishing mechanism.
+
+    This class serves as a template for creating message publishing systems
+    that can either publish messages asynchronously or handle request-response
+    patterns with optional timeouts. Subclasses must implement the abstract
+    methods to provide specific functionality.
+    """
+
+    @abstractmethod
+    async def publish(self, message: HaiMessage) -> None:
+        """Publish a message."""
+        pass
+
+    @abstractmethod
+    async def request(self, message: HaiMessage, timeout: float) -> Optional[HaiMessage]:
+        """Send a request and wait for response."""
+        pass

h_message_bus-0.0.3/src/h_message_bus/application/message_subcriber.py

@@ -0,0 +1,24 @@
+from abc import ABC, abstractmethod
+from typing import Callable
+
+
+class MessageSubscriber(ABC):
+    """
+    Abstract base class representing a message subscriber.
+
+    This class defines the contract for subscribing to and unsubscribing from
+    message topics. Subclasses are required to implement the methods for
+    subscribing to topics with message handlers and unsubscribing from all
+    active subscriptions.
+
+    """
+
+    @abstractmethod
+    async def subscribe(self, topic: str, handler: Callable) -> None:
+        """Subscribe to a topic with a message handler."""
+        pass
+
+    @abstractmethod
+    async def unsubscribe_all(self) -> None:
+        """Unsubscribe from all subscriptions."""
+        pass

h_message_bus-0.0.3/src/h_message_bus/domain/hai_message.py

@@ -0,0 +1,65 @@
+import json
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Dict, Any
+
+
+@dataclass
+class HaiMessage:
+    """
+    Represents a domain message with metadata and payload.
+
+    This class is used for handling messages with a specific topic and payload,
+    along with metadata such as an identifier and a timestamp. It provides
+    functionality for creation, serialization to JSON, and deserialization from JSON.
+
+    :ivar id: Unique identifier for the message.
+    :type id: str
+    :ivar topic: The topic associated with the message.
+    :type topic: str
+    :ivar payload: The payload of the message, represented as a dictionary.
+    :type payload: Dict[Any, Any]
+    :ivar timestamp: The timestamp indicating when the message was created.
+    :type timestamp: str
+    """
+    id: str
+    topic: str
+    payload: Dict[Any, Any]
+    timestamp: str = None
+
+    def __post_init__(self):
+        if not self.id:
+            self.id = str(uuid.uuid4())
+        if not self.timestamp:
+            self.timestamp = datetime.utcnow().isoformat()
+
+    @classmethod
+    def create(cls, topic: str, payload: Dict[Any, Any]) -> 'HaiMessage':
+        """Factory method to create a new domain message."""
+        return cls(
+            id=str(uuid.uuid4()),
+            topic=topic,
+            payload=payload,
+            timestamp=datetime.utcnow().isoformat()
+        )
+
+    def to_json(self) -> str:
+        """Convert message to JSON string."""
+        return json.dumps({
+            "id": self.id,
+            "topic": self.topic,
+            "payload": self.payload,
+            "timestamp": self.timestamp
+        })
+
+    @classmethod
+    def from_json(cls, json_str: str) -> 'HaiMessage':
+        """Create message from JSON string."""
+        data = json.loads(json_str)
+        return cls(
+            id=data.get("id", str(uuid.uuid4())),
+            topic=data["topic"],
+            payload=data["payload"],
+            timestamp=data.get("timestamp", datetime.utcnow().isoformat())
+        )

h_message_bus-0.0.3/src/h_message_bus/domain/topics.py

@@ -0,0 +1,24 @@
+from enum import Enum
+
+
+class Topic(str, Enum):
+    """
+    Represents a collection of predefined topics as an enumeration.
+
+    This class is an enumeration that defines constant string values for use
+    as topic identifiers. These topics represent specific actions or messages
+    within a messaging or vector database management context. It ensures
+    consistent usage of these predefined topics across the application.
+
+    syntax: [hai].[source].[destination].[action]
+
+    """
+    # AI to Telegram
+    AI_SEND_TG_CHAT_MESSAGE = "hai.ai.tg.chat.send"
+
+    # AI to vector database
+    AI_VECTORS_SAVE = "hai.ai.vectors.save"
+    AI_VECTORS_QUERY = "hai.ai.vectors.query"
+
+    # TG to AI
+    TG_SEND_AI_CHAT_MESSAGE = "hai.tg.ai.chat.send"

h_message_bus-0.0.3/src/h_message_bus/infrastructure/nats_client_repository.py

@@ -0,0 +1,86 @@
+from typing import Optional, Callable, Any
+
+import nats
+from nats.aio.client import Client as NatsClient
+
+from src.h_message_bus.infrastructure.nats_config import NatsConfig
+
+
+class NatsClientRepository:
+    """
+    Repository for managing connection and interaction with a NATS server.
+
+    This class provides methods to establish a connection with a NATS server,
+    publish and subscribe to subjects, send requests and handle responses, and
+    cleanly disconnect from the server. It abstracts the connection and ensures
+    seamless communication with the NATS server.
+
+    :ivar config: Configuration details for the NATS client, including server
+        connection parameters, timeouts, and limits.
+    :type config: NatsConfig
+    :ivar client: Instance of the NATS client used for communication. Initialized
+        as None and assigned upon connecting to a NATS server.
+    :type client: Optional[NatsClient]
+    :ivar subscriptions: List of active subscriptions for NATS subjects.
+    :type subscriptions: list
+    """
+
+    def __init__(self, config: NatsConfig):
+        self.config = config
+        self.client: NatsClient | None = None
+
+        self.subscriptions = []
+
+    async def connect(self) -> None:
+        """Connect to NATS server."""
+        if self.client and self.client.is_connected:
+            return
+
+        self.client = await nats.connect(
+            servers=self.config.server,
+            max_reconnect_attempts=self.config.max_reconnect_attempts,
+            reconnect_time_wait=self.config.reconnect_time_wait,
+            connect_timeout=self.config.connection_timeout,
+            ping_interval=self.config.ping_interval,
+            max_outstanding_pings=self.config.max_outstanding_pings
+        )
+
+    async def publish(self, subject: str, payload: bytes) -> None:
+        """Publish raw message to NATS."""
+        if not self.client or not self.client.is_connected:
+            await self.connect()
+
+        await self.client.publish(subject, payload)
+
+    async def subscribe(self, subject: str, callback: Callable) -> Any:
+        """Subscribe to a subject with a callback."""
+        if not self.client or not self.client.is_connected:
+            await self.connect()
+
+        subscription = await self.client.subscribe(subject, cb=callback)
+        self.subscriptions.append(subscription)
+        return subscription
+
+    async def request(self, subject: str, payload: bytes, timeout: float = 2.0) -> Optional[bytes]:
+        """Send a request and get raw response."""
+        if not self.client or not self.client.is_connected:
+            await self.connect()
+
+        try:
+            response = await self.client.request(subject, payload, timeout=timeout)
+            return response.data
+        except Exception as e:
+            print(f"NATS request failed: {e}")
+            return None
+
+    async def close(self) -> None:
+        """Close all subscriptions and NATS connection."""
+        if self.client and self.client.is_connected:
+            # Unsubscribe from all subscriptions
+            for sub in self.subscriptions:
+                await sub.unsubscribe()
+
+            # Drain and close connection
+            await self.client.drain()
+            self.client = None
+            self.subscriptions = []

h_message_bus-0.0.3/src/h_message_bus/infrastructure/nats_config.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class NatsConfig:
+    """
+    Configuration class for NATS client.
+
+    This class encapsulates the configuration options required for connecting and
+    interacting with a NATS (NATS.io) server. It includes options for setting
+    server details, reconnection behavior, timeouts, and ping settings.
+
+    :ivar server: The address of the NATS server to connect to.
+    :type server: str
+    :ivar max_reconnect_attempts: The maximum number of reconnection attempts allowed.
+    :type max_reconnect_attempts: int
+    :ivar reconnect_time_wait: The time duration to wait between reconnection attempts, in seconds.
+    :type reconnect_time_wait: int
+    :ivar connection_timeout: The timeout duration for establishing a connection, in seconds.
+    :type connection_timeout: int
+    :ivar ping_interval: The interval for sending ping frames to the server, in seconds.
+    :type ping_interval: int
+    :ivar max_outstanding_pings: The maximum number of ping requests allowed without receiving a response.
+    :type max_outstanding_pings: int
+    """
+    server: str
+    max_reconnect_attempts: int = 10
+    reconnect_time_wait: int = 2
+    connection_timeout: int = 2
+    ping_interval: int = 20
+    max_outstanding_pings: int = 5

h_message_bus-0.0.3/src/h_message_bus.egg-info/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: h_message_bus
+Version: 0.0.3
+Summary: Message bus integration for HAI
+Author-email: shoebill <shoebill.hai@gmail.com>
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: python-dotenv~=1.1.0
+Requires-Dist: nats-py~=2.10.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+
+# H Message Bus
+
+A message bus integration for HAI applications based on NATS.io
+
+## Overview
+
+H Message Bus provides a robust, asynchronous messaging infrastructure built on NATS.io for HAI applications. It enables seamless communication between components through a publish-subscribe pattern, supporting both fire-and-forget messaging and request-response patterns.
+
+## Features
+
+- **Asynchronous Communication**: Built for modern, non-blocking I/O operations
+- **Flexible Message Routing**: Publish and subscribe to specific topics
+- **High Reliability**: Automatic reconnection handling and configurable timeouts
+- **Simple API**: Focus on core messaging functionality with minimal dependencies
+
+## Installation
+
+```bash
+pip install h_message_bus
+```
+
+## Requirements
+
+- Python 3.10+
+- NATS.io server (can be run via Docker)
+
+## Topics
+
+H Message Bus includes predefined topics following the convention: `hai.[source].[destination].[action]`
+
+Available topics:
+
+| Topic Constant                  | Topic String           | Description                         |
+|---------------------------------|------------------------|-------------------------------------|
+| `Topic.AI_SEND_TG_CHAT_MESSAGE` | `hai.ai.tg.chat.send`  | AI sending message to Telegram chat |
+| `Topic.AI_VECTORS_SAVE`         | `hai.ai.vectors.save`  | AI saving data to vector database   |
+| `Topic.AI_VECTORS_QUERY`        | `hai.ai.vectors.query` | AI querying vector database         |
+| `Topic.TG_SEND_AI_CHAT_MESSAGE` | `hai.tg.ai.chat.send`  | Telegram sending message to AI      |
+
+You can use these predefined topics or create your own topic strings.
+
+## Quick Start
+
+### Start a NATS Server
+
+The easiest way to get started is with Docker:
+
+```bash
+docker-compose up -d
+```
+
+### Create a Publisher
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsPublisherAdapter, HaiMessage, Topic
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create publisher adapter
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await publisher.connect()
+    
+    # Create and publish a message using a predefined topic
+    message = HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="service-a",
+        topic=Topic.TG_SEND_AI_CHAT_MESSAGE,
+        payload={"text": "Hello AI, this is a message from Telegram", "chat_id": 12345}
+    )
+    
+    # Publish message
+    await publisher.publish(message)
+    
+    # Clean up
+    await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Create a Subscriber
+
+```python
+import asyncio
+from h_message_bus import NatsConfig, NatsSubscriberAdapter, HaiMessage, Topic
+
+async def message_handler(message: HaiMessage):
+    print(f"Received message: {message.message_id}")
+    print(f"From: {message.sender}")
+    print(f"Topic: {message.topic}")
+    print(f"Payload: {message.payload}")
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create subscriber
+    subscriber = NatsSubscriberAdapter(config)
+    
+    # Connect to NATS
+    await subscriber.connect()
+    
+    # Subscribe to a topic
+    await subscriber.subscribe(Topic.TG_SEND_AI_CHAT_MESSAGE, message_handler)
+    
+    # Keep the application running
+    try:
+        print("Subscriber running. Press Ctrl+C to exit.")
+        while True:
+            await asyncio.sleep(1)
+    except KeyboardInterrupt:
+        # Clean up
+        await subscriber.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Advanced Usage
+
+### Request-Response Pattern
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsPublisherAdapter, HaiMessage, Topic
+
+async def main():
+    config = NatsConfig(server="nats://localhost:4222")
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await publisher.connect()
+    
+    request_message = HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="client-service",
+        topic=Topic.AI_VECTORS_QUERY,
+        payload={"query": "find similar documents", "limit": 10}
+    )
+    
+    # Send request and wait for response (with timeout)
+    response = await publisher.request(request_message, timeout=5.0)
+    
+    if response:
+        print(f"Received response: {response.payload}")
+    else:
+        print("Request timed out")
+    
+    await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+### Creating a Service with Request Handler
+
+```python
+import asyncio
+import uuid
+from h_message_bus import NatsConfig, NatsSubscriberAdapter, NatsPublisherAdapter, HaiMessage, Topic
+
+async def request_handler(request: HaiMessage):
+    print(f"Received request: {request.message_id}")
+    print(f"Payload: {request.payload}")
+    
+    # Process the request
+    result = {"status": "success", "data": {"result": 42}}
+    
+    # Create a response message
+    return HaiMessage(
+        message_id=str(uuid.uuid4()),
+        sender="service-b",
+        topic=f"{request.topic}.response",
+        payload=result,
+        correlation_id=request.message_id
+    )
+
+async def main():
+    # Configure NATS connection
+    config = NatsConfig(server="nats://localhost:4222")
+    
+    # Create subscriber for handling requests
+    subscriber = NatsSubscriberAdapter(config)
+    publisher = NatsPublisherAdapter(config)
+    
+    # Connect to NATS
+    await subscriber.connect()
+    await publisher.connect()
+    
+    # Register request handler for vector database queries
+    await subscriber.subscribe_with_response(Topic.AI_VECTORS_QUERY, request_handler, publisher)
+    
+    # Keep the application running
+    try:
+        print("Service running. Press Ctrl+C to exit.")
+        while True:
+            await asyncio.sleep(1)
+    except KeyboardInterrupt:
+        # Clean up
+        await subscriber.close()
+        await publisher.close()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+## Configuration Options
+
+The `NatsConfig` class allows you to customize your NATS connection:
+
+| Parameter                | Description                                  | Default       |
+|--------------------------|----------------------------------------------|---------------|
+| `server`                 | NATS server address                          | Required      |
+| `max_reconnect_attempts` | Maximum reconnection attempts                | 10            |
+| `reconnect_time_wait`    | Time between reconnection attempts (seconds) | 2             |
+| `connection_timeout`     | Connection timeout (seconds)                 | 2             |
+| `ping_interval`          | Interval for ping frames (seconds)           | 20            |
+| `max_outstanding_pings`  | Maximum unanswered pings before disconnect   | 5             |
+| `max_payload`            | Maximum size of the payload in bytes         | 1048576 (1MB) |
+
+## API Reference
+
+### Exported Classes
+
+The following classes are exported directly from the package:
+
+- `NatsConfig` - Configuration for the NATS connection
+- `HaiMessage` - Message structure for HAI communication
+- `NatsPublisherAdapter` - Adapter for publishing messages
+- `NatsSubscriberAdapter` - Adapter for subscribing to messages
+- `MessageProcessor` - Processing incoming messages
+- `NatsClientRepository` - Low-level NATS client operations
+- `Topic` - Enumeration of predefined topic strings
+
+### HaiMessage Structure
+
+The `HaiMessage` class is the core data structure used for all messaging:
+
+```python
+class HaiMessage:
+    message_id: str       # Unique identifier for the message
+    sender: str           # Identifier of the sender
+    topic: str            # The topic or channel for the message
+    payload: dict         # Actual message data
+    correlation_id: str = None  # Optional reference to a related message
+    timestamp: float = None     # Optional message creation timestamp
+```
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.

h_message_bus-0.0.3/src/h_message_bus.egg-info/SOURCES.txt

@@ -0,0 +1,22 @@
+README.md
+pyproject.toml
+src/h_message_bus/__init__.py
+src/h_message_bus.egg-info/PKG-INFO
+src/h_message_bus.egg-info/SOURCES.txt
+src/h_message_bus.egg-info/dependency_links.txt
+src/h_message_bus.egg-info/requires.txt
+src/h_message_bus.egg-info/top_level.txt
+src/h_message_bus/adapters/__init__.py
+src/h_message_bus/adapters/nats_message_adapter.py
+src/h_message_bus/adapters/nats_publisher_adapter.py
+src/h_message_bus/adapters/nats_subscriber_adapter.py
+src/h_message_bus/application/__init__.py
+src/h_message_bus/application/message_processor.py
+src/h_message_bus/application/message_publisher.py
+src/h_message_bus/application/message_subcriber.py
+src/h_message_bus/domain/__init__.py
+src/h_message_bus/domain/hai_message.py
+src/h_message_bus/domain/topics.py
+src/h_message_bus/infrastructure/__init__.py
+src/h_message_bus/infrastructure/nats_client_repository.py
+src/h_message_bus/infrastructure/nats_config.py

h_message_bus-0.0.3/src/h_message_bus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

h_message_bus-0.0.3/src/h_message_bus.egg-info/requires.txt

@@ -0,0 +1,5 @@
+python-dotenv~=1.1.0
+nats-py~=2.10.0
+
+[dev]
+pytest

h_message_bus-0.0.3/src/h_message_bus.egg-info/top_level.txt

@@ -0,0 +1 @@
+h_message_bus