Metadata-Version: 2.4
Name: avtomatika-worker
Version: 1.0b14
Summary: Worker SDK for the Avtomatika orchestrator.
Author-email: Dmitrii Gagarin <madgagarin@gmail.com>
Project-URL: Homepage, https://github.com/avtomatika-ai/avtomatika-worker
Project-URL: Bug Tracker, https://github.com/avtomatika-ai/avtomatika-worker/issues
Keywords: worker,sdk,orchestrator,distributed,task-queue,rxon,hln
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: rxon>=1.0b10
Requires-Dist: aiohttp~=3.13.5
Requires-Dist: python-json-logger~=4.1.0
Requires-Dist: aiofiles~=25.1.0
Requires-Dist: orjson>=3.10.0
Provides-Extra: s3
Requires-Dist: obstore~=0.9.2; extra == "s3"
Provides-Extra: pydantic
Requires-Dist: pydantic~=2.12; extra == "pydantic"
Provides-Extra: metrics
Requires-Dist: opentelemetry-api~=1.30.0; extra == "metrics"
Requires-Dist: opentelemetry-sdk~=1.30.0; extra == "metrics"
Requires-Dist: opentelemetry-semantic-conventions~=0.50b0; extra == "metrics"
Requires-Dist: opentelemetry-exporter-prometheus~=0.50b0; extra == "metrics"
Provides-Extra: test
Requires-Dist: avtomatika-worker[pydantic,s3]; extra == "test"
Requires-Dist: pytest; extra == "test"
Requires-Dist: pytest-asyncio; extra == "test"
Requires-Dist: aioresponses; extra == "test"
Requires-Dist: pytest-mock; extra == "test"
Requires-Dist: types-aiofiles; extra == "test"
Provides-Extra: dev
Requires-Dist: avtomatika-worker[test]; extra == "dev"
Requires-Dist: watchdog; extra == "dev"
Dynamic: license-file

# Avtomatika Worker SDK

Official SDK for building workers compatible with the **Avtomatika** orchestrator. It automates low-level tasks: polling, heartbeats, S3 payload management, and graceful shutdown.

## 🚀 Key Features

- **Language:** Python 3.11+
- **Protocol:** Based on **RXON** (Reverse Axon Protocol) for Hierarchical Logic Networks (Holarchy).
- **Communication Model:**
  - **PULL:** Workers poll tasks from orchestrators (works behind NAT/Firewall).
  - **WebSocket:** Real-time command channel (cancellation, custom commands).
- **Zero Trust Security:**
  - Mandatory HMAC SHA256 signing for all messages using `WORKER_TOKEN`.
  - Identity Chain and Origin Worker ID support for provenance tracking.
  - Replay protection with timestamp validation.
- **Traffic Optimization:**
  - **3-Tier Skills:** *Supported* (catalog), *Available* (dynamic limits), and *Hot* (cached).
  - **Stable Hashing:** Sends full skill catalog only when changed, using `skills_hash` for light heartbeats.
- **S3 Streaming:** High-performance data transfer using `obstore`. No OOM on large files.
- **Hardware Awareness:** Built-in monitoring for CPU, RAM, and NVIDIA GPUs (via `psutil` and `GPUtil`).

## 🛡 Resilience & Connectivity

- **Independent Managers:** Connection to each orchestrator is managed by a separate background task. One server failure doesn't affect others.
- **Infinite Retries:** Exponential backoff for registration if the orchestrator is unavailable.
- **Non-blocking Startup:** The worker starts polling as soon as it registers successfully with at least one orchestrator.
- **Graceful Shutdown:** Handles `SIGTERM` and `SIGINT` properly, waiting for active tasks to finish.

## 🛠 Installation

```bash
pip install avtomatika-worker[s3,pydantic]
```

For development:
```bash
pip install -e .[test,dev]
```

## 💻 Quick Start

```python
from avtomatika_worker import Worker, TaskFiles

worker = Worker()

@worker.skill("hello_world")
async def my_skill(params: dict, files: TaskFiles):
    """Simple skill that says hello."""
    return {"message": f"Hello, {params.get('name', 'World')}!"}

@worker.on_command("reboot")
async def handle_reboot(command):
    print("Rebooting worker...")

if __name__ == "__main__":
    worker.run()
```

## ⚙️ Configuration

Controlled via environment variables:
- `ORCHESTRATORS_CONFIG`: JSON list of orchestrator configs (URLs, priorities, weights).
- `ORCHESTRATOR_URL`: Simple fallback if only one orchestrator is used (default: `http://localhost:8080`).
- `WORKER_TOKEN`: Secret for HMAC signing (Zero Trust).
- `S3_ENDPOINT_URL`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `S3_DEFAULT_BUCKET`: Storage settings for large payloads.
- `STRICT_EVENT_VALIDATION`: (Default: `True`) Validates events against schemas before emitting.
- `LOG_LEVEL`: Logging verbosity (DEBUG, INFO, WARNING, ERROR).
- `MAX_CONCURRENT_TASKS`: Global limit for concurrent task execution.

## 📜 License

Mozilla Public License v. 2.0.
