avtomatika 1.0b5__tar.gz → 1.0b7__tar.gz

{avtomatika-1.0b5/src/avtomatika.egg-info → avtomatika-1.0b7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avtomatika
-Version: 1.0b5
+Version: 1.0b7
 Summary: A state-machine based orchestrator for long-running AI and other jobs.
 Project-URL: Homepage, https://github.com/avtomatika-ai/avtomatika
 Project-URL: Bug Tracker, https://github.com/avtomatika-ai/avtomatika/issues
@@ -12,7 +12,6 @@ Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: aiohttp~=3.12
-Requires-Dist: aiocache~=0.12
 Requires-Dist: python-json-logger~=4.0
 Requires-Dist: graphviz~=0.21
 Requires-Dist: zstandard~=0.24
@@ -60,6 +59,8 @@ This document serves as a comprehensive guide for developers looking to build pi
   - [Delegating Tasks to Workers (dispatch_task)](#delegating-tasks-to-workers-dispatch_task)
   - [Parallel Execution and Aggregation (Fan-out/Fan-in)](#parallel-execution-and-aggregation-fan-outfan-in)
   - [Dependency Injection (DataStore)](#dependency-injection-datastore)
+  - [Native Scheduler](#native-scheduler)
+  - [Webhook Notifications](#webhook-notifications)
 - [Production Configuration](#production-configuration)
   - [Fault Tolerance](#fault-tolerance)
   - [Storage Backend](#storage-backend)
@@ -74,7 +75,17 @@ The project is based on a simple yet powerful architectural pattern that separat
 
 *   **Orchestrator (OrchestratorEngine)** — The Director. It manages the entire process from start to finish, tracks state, handles errors, and decides what should happen next. It does not perform business tasks itself.
 *   **Blueprints (Blueprint)** — The Script. Each blueprint is a detailed plan (a state machine) for a specific business process. It describes the steps (states) and the rules for transitioning between them.
-*   **Workers (Worker)** — The Team of Specialists. These are independent, specialized executors. Each worker knows how to perform a specific set of tasks (e.g., "process video," "send email") and reports back to the Orchestrator.## Installation
+*   **Workers (Worker)** — The Team of Specialists. These are independent, specialized executors. Each worker knows how to perform a specific set of tasks (e.g., "process video," "send email") and reports back to the Orchestrator.
+
+## Ecosystem
+
+Avtomatika is part of a larger ecosystem:
+
+*   **[Avtomatika Worker SDK](https://github.com/avtomatika-ai/avtomatika-worker)**: The official Python SDK for building workers that connect to this engine.
+*   **[RCA Protocol](https://github.com/avtomatika-ai/rca)**: The architectural specification and manifesto behind the system.
+*   **[Full Example](https://github.com/avtomatika-ai/avtomatika-full-example)**: A complete reference project demonstrating the engine and workers in action.
+
+## Installation
 
 *   **Install the core engine only:**
     ```bash
@@ -146,7 +157,13 @@ async def end_handler(context):
 engine = OrchestratorEngine(storage, config)
 engine.register_blueprint(my_blueprint)
 
-# 4. Define the main entrypoint to run the server
+# 4. Accessing Components (Optional)
+# You can access the internal aiohttp app and core components using AppKeys
+# from avtomatika.app_keys import ENGINE_KEY, DISPATCHER_KEY
+# app = engine.app
+# dispatcher = app[DISPATCHER_KEY]
+
+# 5. Define the main entrypoint to run the server
 async def main():
     await engine.start()
     
@@ -328,6 +345,56 @@ async def cache_handler(data_stores):
     user_data = await data_stores.cache.get("user:123")
     print(f"User from cache: {user_data}")
 ```
+
+### 5. Native Scheduler
+
+Avtomatika includes a built-in distributed scheduler. It allows you to trigger blueprints periodically (interval, daily, weekly, monthly) without external tools like cron.
+
+*   **Configuration:** Defined in `schedules.toml`.
+*   **Timezone Aware:** Supports global timezone configuration (e.g., `TZ="Europe/Moscow"`).
+*   **Distributed Locking:** Safe to run with multiple orchestrator instances; jobs are guaranteed to run only once per interval using distributed locks (Redis/Memory).
+
+```toml
+# schedules.toml example
+[nightly_backup]
+blueprint = "backup_flow"
+daily_at = "02:00"
+```
+
+### 6. Webhook Notifications
+
+The orchestrator can send asynchronous notifications to an external system when a job completes, fails, or is quarantined. This eliminates the need for clients to constantly poll the API for status updates.
+
+*   **Usage:** Pass a `webhook_url` in the request body when creating a job.
+*   **Events:**
+    *   `job_finished`: The job reached a final success state.
+    *   `job_failed`: The job failed (e.g., due to an error or invalid input).
+    *   `job_quarantined`: The job was moved to quarantine after repeated failures.
+
+**Example Request:**
+```json
+POST /api/v1/jobs/my_flow
+{
+    "initial_data": {
+        "video_url": "..."
+    },
+    "webhook_url": "https://my-app.com/webhooks/avtomatika"
+}
+```
+
+**Example Webhook Payload:**
+```json
+{
+    "event": "job_finished",
+    "job_id": "123e4567-e89b-12d3-a456-426614174000",
+    "status": "finished",
+    "result": {
+        "output_path": "/videos/result.mp4"
+    },
+    "error": null
+}
+```
+
 ## Production Configuration
 
 The orchestrator's behavior can be configured through environment variables. Additionally, any configuration parameter loaded from environment variables can be programmatically overridden in your application code after the `Config` object has been initialized. This provides flexibility for different deployment and testing scenarios.
@@ -349,6 +416,12 @@ To manage access and worker settings securely, Avtomatika uses TOML configuratio
     [gpu-worker-01]
     token = "worker-secret-456"
     ```
+-   **`schedules.toml`**: Defines periodic tasks (CRON-like) for the native scheduler.
+    ```toml
+    [nightly_backup]
+    blueprint = "backup_flow"
+    daily_at = "02:00"
+    ```
 
 For detailed specifications and examples, please refer to the [**Configuration Guide**](docs/configuration.md).
 

{avtomatika-1.0b5 → avtomatika-1.0b7}/README.md

@@ -14,6 +14,8 @@ This document serves as a comprehensive guide for developers looking to build pi
   - [Delegating Tasks to Workers (dispatch_task)](#delegating-tasks-to-workers-dispatch_task)
   - [Parallel Execution and Aggregation (Fan-out/Fan-in)](#parallel-execution-and-aggregation-fan-outfan-in)
   - [Dependency Injection (DataStore)](#dependency-injection-datastore)
+  - [Native Scheduler](#native-scheduler)
+  - [Webhook Notifications](#webhook-notifications)
 - [Production Configuration](#production-configuration)
   - [Fault Tolerance](#fault-tolerance)
   - [Storage Backend](#storage-backend)
@@ -28,7 +30,17 @@ The project is based on a simple yet powerful architectural pattern that separat
 
 *   **Orchestrator (OrchestratorEngine)** — The Director. It manages the entire process from start to finish, tracks state, handles errors, and decides what should happen next. It does not perform business tasks itself.
 *   **Blueprints (Blueprint)** — The Script. Each blueprint is a detailed plan (a state machine) for a specific business process. It describes the steps (states) and the rules for transitioning between them.
-*   **Workers (Worker)** — The Team of Specialists. These are independent, specialized executors. Each worker knows how to perform a specific set of tasks (e.g., "process video," "send email") and reports back to the Orchestrator.## Installation
+*   **Workers (Worker)** — The Team of Specialists. These are independent, specialized executors. Each worker knows how to perform a specific set of tasks (e.g., "process video," "send email") and reports back to the Orchestrator.
+
+## Ecosystem
+
+Avtomatika is part of a larger ecosystem:
+
+*   **[Avtomatika Worker SDK](https://github.com/avtomatika-ai/avtomatika-worker)**: The official Python SDK for building workers that connect to this engine.
+*   **[RCA Protocol](https://github.com/avtomatika-ai/rca)**: The architectural specification and manifesto behind the system.
+*   **[Full Example](https://github.com/avtomatika-ai/avtomatika-full-example)**: A complete reference project demonstrating the engine and workers in action.
+
+## Installation
 
 *   **Install the core engine only:**
     ```bash
@@ -100,7 +112,13 @@ async def end_handler(context):
 engine = OrchestratorEngine(storage, config)
 engine.register_blueprint(my_blueprint)
 
-# 4. Define the main entrypoint to run the server
+# 4. Accessing Components (Optional)
+# You can access the internal aiohttp app and core components using AppKeys
+# from avtomatika.app_keys import ENGINE_KEY, DISPATCHER_KEY
+# app = engine.app
+# dispatcher = app[DISPATCHER_KEY]
+
+# 5. Define the main entrypoint to run the server
 async def main():
     await engine.start()
     
@@ -282,6 +300,56 @@ async def cache_handler(data_stores):
     user_data = await data_stores.cache.get("user:123")
     print(f"User from cache: {user_data}")
 ```
+
+### 5. Native Scheduler
+
+Avtomatika includes a built-in distributed scheduler. It allows you to trigger blueprints periodically (interval, daily, weekly, monthly) without external tools like cron.
+
+*   **Configuration:** Defined in `schedules.toml`.
+*   **Timezone Aware:** Supports global timezone configuration (e.g., `TZ="Europe/Moscow"`).
+*   **Distributed Locking:** Safe to run with multiple orchestrator instances; jobs are guaranteed to run only once per interval using distributed locks (Redis/Memory).
+
+```toml
+# schedules.toml example
+[nightly_backup]
+blueprint = "backup_flow"
+daily_at = "02:00"
+```
+
+### 6. Webhook Notifications
+
+The orchestrator can send asynchronous notifications to an external system when a job completes, fails, or is quarantined. This eliminates the need for clients to constantly poll the API for status updates.
+
+*   **Usage:** Pass a `webhook_url` in the request body when creating a job.
+*   **Events:**
+    *   `job_finished`: The job reached a final success state.
+    *   `job_failed`: The job failed (e.g., due to an error or invalid input).
+    *   `job_quarantined`: The job was moved to quarantine after repeated failures.
+
+**Example Request:**
+```json
+POST /api/v1/jobs/my_flow
+{
+    "initial_data": {
+        "video_url": "..."
+    },
+    "webhook_url": "https://my-app.com/webhooks/avtomatika"
+}
+```
+
+**Example Webhook Payload:**
+```json
+{
+    "event": "job_finished",
+    "job_id": "123e4567-e89b-12d3-a456-426614174000",
+    "status": "finished",
+    "result": {
+        "output_path": "/videos/result.mp4"
+    },
+    "error": null
+}
+```
+
 ## Production Configuration
 
 The orchestrator's behavior can be configured through environment variables. Additionally, any configuration parameter loaded from environment variables can be programmatically overridden in your application code after the `Config` object has been initialized. This provides flexibility for different deployment and testing scenarios.
@@ -303,6 +371,12 @@ To manage access and worker settings securely, Avtomatika uses TOML configuratio
     [gpu-worker-01]
     token = "worker-secret-456"
     ```
+-   **`schedules.toml`**: Defines periodic tasks (CRON-like) for the native scheduler.
+    ```toml
+    [nightly_backup]
+    blueprint = "backup_flow"
+    daily_at = "02:00"
+    ```
 
 For detailed specifications and examples, please refer to the [**Configuration Guide**](docs/configuration.md).
 

{avtomatika-1.0b5 → avtomatika-1.0b7}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "avtomatika"
-version = "1.0b5"
+version = "1.0b7"
 description = "A state-machine based orchestrator for long-running AI and other jobs."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -16,7 +16,6 @@ classifiers = [
 ]
 dependencies = [
     "aiohttp~=3.12",
-    "aiocache~=0.12",
     "python-json-logger~=4.0",
     "graphviz~=0.21",
     "zstandard~=0.24",