applications-hub-lib 0.1.1
Python client library for HUB Central integration
Requires Python: >=3.8

# Hub Library

The **Hub Library** is a high-performance asynchronous Python client for connecting services to **HUB Central**. It provides a powerful RPC-like system to expose and call functions across different services seamlessly.

## 🚀 Features

-   **Async-Native**: Built on top of `asyncio`, `aiohttp`, and `websockets`.
-   **RPC Architecture**: Easily expose local functions and call remote ones.
-   **Automatic Discovery**: Exposed functions are automatically registered with HUB Central.
-   **Auto-Reconnection**: Built-in exponential backoff for persistent connections.
-   **Schema Validation**: Every message is validated using Pydantic models.
-   **Standardized Protocol**: Seamlessly route messages between any connected services.

## 📦 Installation

Install the library in editable mode for development:

```bash
pip install -e .
```

Requires Python 3.8+ and the following dependencies:
- `aiohttp`
- `websockets`
- `pydantic`

## 🛠️ Quick Start

### 1. Expose a Function (Provider)
Create a service that offers functionality to others.

```python
import asyncio
from hub import HubClient

# Initialize the client
client = HubClient(
    base_url="http://localhost:8000",
    api_key="your_api_key",
    api_secret="your_api_secret"
)

# Expose a function
@client.expose
async def get_system_status(service_id: str):
    """Returns the status of a specific system component."""
    return {"status": "operational", "load": 0.45, "id": service_id}

async def main():
    # Connect and start the loop
    await client.connect()

if __name__ == "__main__":
    asyncio.run(main())
```

### 2. Call a Remote Function (Consumer)
Call functions from other services as if they were local.

```python
import asyncio
from hub import HubClient

client = HubClient(base_url="http://localhost:8000", api_key="consumer_key", api_secret="consumer_secret")

async def main():
    asyncio.create_task(client.connect())
    await asyncio.sleep(2) # Wait for connection

    # Call a function on another service
    result = await client.call(
        target="status-service",
        function_name="get_system_status",
        service_id="node-01"
    )
    print(f"Result: {result}")

if __name__ == "__main__":
    asyncio.run(main())
```

## 📖 API Reference

### `HubClient`

- `HubClient(base_url, api_key, api_secret)`: Create a new client instance.
- `@expose`: Decorator to make a function available to be called by other services. Supports both sync and async functions.
- `await call(target, function_name, timeout=30, **kwargs)`: Calls a function on another service.
- `await connect()`: Authenticate and establish the WebSocket connection. This method runs the main loop.
- `stop()`: Gracefully stop the client.

### `HubMessage` Model

Internal communication uses the `HubMessage` Pydantic model:

| Field | Description |
|---|---|
| `target` | The service name of the recipient. |
| `sender` | The service name of the sender. |
| `action` | The type of message (`call`, `call_response`, etc). |
| `payload` | A dictionary containing the message data. |

---

© 2026 Hub Team