Metadata-Version: 2.4
Name: hydra-router
Version: 0.2.3
Summary: A ZeroMQ messaging router and client
License: GPL-3.0
License-File: LICENSE
Keywords: ZeroMQ,Messaging Framework
Author: Nadim-Daniel Ghaznavi
Author-email: nghaznavi@gmail.com
Requires-Python: >=3.11,<3.15
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Games/Entertainment :: Puzzle Games
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: dev
Provides-Extra: docs
Provides-Extra: server
Provides-Extra: tui
Provides-Extra: viz
Requires-Dist: aiohttp (>=3.8.0) ; extra == "server"
Requires-Dist: black (>=23.0.0) ; extra == "dev"
Requires-Dist: flake8 (>=6.0.0) ; extra == "dev"
Requires-Dist: hypothesis (>=6.0.0)
Requires-Dist: hypothesis (>=6.0.0) ; extra == "dev"
Requires-Dist: isort (>=5.12.0) ; extra == "dev"
Requires-Dist: matplotlib (>=3.7.0) ; extra == "viz"
Requires-Dist: mypy (>=1.0.0) ; extra == "dev"
Requires-Dist: myst-parser (>=2.0.0) ; extra == "docs"
Requires-Dist: pillow (>=10.0.0) ; extra == "viz"
Requires-Dist: psutil (>=5.9.0)
Requires-Dist: pytest (>=7.0.0)
Requires-Dist: pytest (>=7.0.0) ; extra == "dev"
Requires-Dist: pytest-asyncio (>=0.21.0) ; extra == "dev"
Requires-Dist: pytest-cov (>=4.0.0) ; extra == "dev"
Requires-Dist: pytest-mock (>=3.15.0) ; extra == "dev"
Requires-Dist: pytest-timeout (>=2.1.0) ; extra == "dev"
Requires-Dist: python-daemon (>=3.0.0) ; extra == "server"
Requires-Dist: pyyaml (>=6.0)
Requires-Dist: pyzmq (>=25.0.0)
Requires-Dist: rich (>=13.0.0) ; extra == "tui"
Requires-Dist: sphinx (>=7.0.0) ; extra == "docs"
Requires-Dist: sphinx-rtd-theme (>=1.3.0) ; extra == "docs"
Requires-Dist: tensorboard (>=2.13.0) ; extra == "viz"
Requires-Dist: textual (>=0.41.0) ; extra == "tui"
Project-URL: Bug Tracker, https://github.com/NadimGhaznavi/hydra_router/issues
Project-URL: Documentation, https://hydra-router.readthedocs.io/en/latest/
Project-URL: Source, https://github.com/NadimGhaznavi/hydra_router
Description-Content-Type: text/markdown

# Hydra Router

A standalone ZeroMQ-based message routing system that provides reliable communication between multiple clients and a single server.

## Features

- **Centralized Message Routing**: Routes messages between multiple clients and a single server
- **Message Format Conversion**: Automatic conversion between internal and router message formats
- **Heartbeat Monitoring**: Automatic client health monitoring and connection tracking
- **Comprehensive Error Handling**: Detailed validation and error reporting
- **Simple Examples**: Includes simple client/server examples for quick testing
- **Client Registry Query**: Query router for connected client information

## Installation

```bash
pip install hydra-router
```

## Quick Start

### Start the Router

```bash
# Basic usage
hydra-router

# Custom configuration
hydra-router --address 0.0.0.0 --port 5556 --log-level INFO
```

### Simple Client/Server Demo

```bash
# Terminal 1: Start the router
hydra-router --log-level DEBUG

# Terminal 2: Start the simple server
hydra-server_simple --router tcp://localhost:5556

# Terminal 3: Start the simple client
hydra-client_simple --router tcp://localhost:5556
# Then enter numbers to see their squares calculated by the server
```

### Using the MQClient Library

```python
from hydra_router import MQClient, RouterConstants

# Create a client
client = MQClient(
    router_address="tcp://localhost:5556",
    client_type=RouterConstants.HYDRA_CLIENT,
    client_id="my-client-001"
)

# Connect and send messages
await client.connect()
await client.send_message(my_message)

# Query connected clients
client_table = await client.request_client_registry()
print("Connected clients:", client_table)
```

## Architecture

The Hydra Router system consists of:

- **HydraRouter**: Central message routing component
- **MQClient**: Generic client library for applications
- **RouterConstants**: Message format definitions and constants
- **SimpleClient/SimpleServer**: Example applications

## Configuration

The router supports the following command-line options:

- `--address, -a`: IP address to bind to (default: 0.0.0.0)
- `--port, -p`: Port to bind to (default: 5556)
- `--log-level`: Logging level (DEBUG, INFO, WARNING, ERROR, default: INFO)
- `--help, -h`: Show help message

## Requirements

- Python 3.11+
- ZeroMQ (pyzmq)

## License

GPL-3.0

## Contributing

This project follows the specification-driven development methodology. See the `.kiro/specs/` directory for detailed requirements, design, and implementation tasks.

