avtomatika 1.0b4__tar.gz → 1.0b5__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: avtomatika
-Version: 1.0b4
+Version: 1.0b5
 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
@@ -17,13 +17,13 @@ Requires-Dist: python-json-logger~=4.0
 Requires-Dist: graphviz~=0.21
 Requires-Dist: zstandard~=0.24
 Requires-Dist: aioprometheus~=23.12
+Requires-Dist: msgpack~=1.1
+Requires-Dist: orjson~=3.11
 Provides-Extra: redis
 Requires-Dist: redis~=7.1; extra == "redis"
-Requires-Dist: orjson~=3.11; extra == "redis"
 Provides-Extra: history
 Requires-Dist: aiosqlite~=0.22; extra == "history"
 Requires-Dist: asyncpg~=0.30; extra == "history"
-Requires-Dist: orjson~=3.11; extra == "history"
 Provides-Extra: telemetry
 Requires-Dist: opentelemetry-api~=1.39; extra == "telemetry"
 Requires-Dist: opentelemetry-sdk~=1.39; extra == "telemetry"
@@ -360,18 +360,25 @@ The orchestrator has built-in mechanisms for handling failures based on the `err
 *   **PERMANENT_ERROR**: A permanent error (e.g., a corrupted file). The task will be immediately sent to quarantine for manual investigation.
 *   **INVALID_INPUT_ERROR**: An error in the input data. The entire pipeline (Job) will be immediately moved to the failed state.
 
+### Concurrency & Performance
+
+To prevent system overload during high traffic, the Orchestrator implements a backpressure mechanism for its internal job processing logic.
+
+*   **`EXECUTOR_MAX_CONCURRENT_JOBS`**: Limits the number of job handlers running simultaneously within the Orchestrator process (default: `100`). If this limit is reached, new jobs remain in the Redis queue until a slot becomes available. This ensures the event loop remains responsive even with a massive backlog of pending jobs.
+
 ### High Availability & Distributed Locking
 
 The architecture supports horizontal scaling. Multiple Orchestrator instances can run behind a load balancer.
 
 *   **Stateless API:** The API is stateless; all state is persisted in Redis.
+*   **Instance Identity:** Each instance should have a unique `INSTANCE_ID` (defaults to hostname) for correct handling of Redis Streams consumer groups.
 *   **Distributed Locking:** Background processes (`Watcher`, `ReputationCalculator`) use distributed locks (via Redis `SET NX`) to coordinate and prevent race conditions when multiple instances are active.
 
 ### Storage Backend
 
 By default, the engine uses in-memory storage. For production, you must configure persistent storage via environment variables.
 
-*   **Redis (StorageBackend)**: For storing current job states.
+*   **Redis (StorageBackend)**: For storing current job states (serialized with `msgpack`) and managing task queues (using Redis Streams with consumer groups).
     *   Install:
         ```bash
         pip install "avtomatika[redis]"

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

@@ -314,18 +314,25 @@ The orchestrator has built-in mechanisms for handling failures based on the `err
 *   **PERMANENT_ERROR**: A permanent error (e.g., a corrupted file). The task will be immediately sent to quarantine for manual investigation.
 *   **INVALID_INPUT_ERROR**: An error in the input data. The entire pipeline (Job) will be immediately moved to the failed state.
 
+### Concurrency & Performance
+
+To prevent system overload during high traffic, the Orchestrator implements a backpressure mechanism for its internal job processing logic.
+
+*   **`EXECUTOR_MAX_CONCURRENT_JOBS`**: Limits the number of job handlers running simultaneously within the Orchestrator process (default: `100`). If this limit is reached, new jobs remain in the Redis queue until a slot becomes available. This ensures the event loop remains responsive even with a massive backlog of pending jobs.
+
 ### High Availability & Distributed Locking
 
 The architecture supports horizontal scaling. Multiple Orchestrator instances can run behind a load balancer.
 
 *   **Stateless API:** The API is stateless; all state is persisted in Redis.
+*   **Instance Identity:** Each instance should have a unique `INSTANCE_ID` (defaults to hostname) for correct handling of Redis Streams consumer groups.
 *   **Distributed Locking:** Background processes (`Watcher`, `ReputationCalculator`) use distributed locks (via Redis `SET NX`) to coordinate and prevent race conditions when multiple instances are active.
 
 ### Storage Backend
 
 By default, the engine uses in-memory storage. For production, you must configure persistent storage via environment variables.
 
-*   **Redis (StorageBackend)**: For storing current job states.
+*   **Redis (StorageBackend)**: For storing current job states (serialized with `msgpack`) and managing task queues (using Redis Streams with consumer groups).
     *   Install:
         ```bash
         pip install "avtomatika[redis]"

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "avtomatika"
-version = "1.0b4"
+version = "1.0b5"
 description = "A state-machine based orchestrator for long-running AI and other jobs."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -21,11 +21,13 @@ dependencies = [
     "graphviz~=0.21",
     "zstandard~=0.24",
     "aioprometheus~=23.12",
+    "msgpack~=1.1",
+    "orjson~=3.11",
 ]
 
 [project.optional-dependencies]
-redis = ["redis~=7.1", "orjson~=3.11"]
-history = ["aiosqlite~=0.22", "asyncpg~=0.30", "orjson~=3.11"]
+redis = ["redis~=7.1"]
+history = ["aiosqlite~=0.22", "asyncpg~=0.30"]
 telemetry = [
     "opentelemetry-api~=1.39",
     "opentelemetry-sdk~=1.39",

{avtomatika-1.0b4 → avtomatika-1.0b5}/src/avtomatika/__init__.py

@@ -4,7 +4,7 @@
 This module exposes the primary classes for building and running state-driven automations.
 """
 
-import contextlib
+from contextlib import suppress
 from importlib.metadata import version
 
 __version__ = version("avtomatika")
@@ -23,7 +23,7 @@ __all__ = [
     "StorageBackend",
 ]
 
-with contextlib.suppress(ImportError):
+with suppress(ImportError):
     from .storage.redis import RedisStorage  # noqa: F401
 
     __all__.append("RedisStorage")

{avtomatika-1.0b4 → avtomatika-1.0b5}/src/avtomatika/blueprint.py

@@ -1,6 +1,6 @@
 from operator import eq, ge, gt, le, lt, ne
 from re import compile as re_compile
-from typing import Any, Callable, Dict, NamedTuple, Optional
+from typing import Any, Callable, NamedTuple
 
 from .datastore import AsyncDictStore
 
@@ -99,8 +99,6 @@ class HandlerDecorator:
 
     def when(self, condition_str: str) -> Callable:
         def decorator(func: Callable) -> Callable:
-            # We still register the base handler to ensure the state is known,
-            # but we can make it a no-op if only conditional handlers exist for a state.
             if self._state not in self._blueprint.handlers:
                 self._blueprint.handlers[self._state] = lambda: None  # Placeholder
 
@@ -115,8 +113,8 @@ class StateMachineBlueprint:
     def __init__(
         self,
         name: str,
-        api_endpoint: Optional[str] = None,
-        api_version: Optional[str] = None,
+        api_endpoint: str | None = None,
+        api_version: str | None = None,
         data_stores: Any = None,
     ):
         """Initializes a new blueprint.
@@ -132,14 +130,14 @@ class StateMachineBlueprint:
         self.name = name
         self.api_endpoint = api_endpoint
         self.api_version = api_version
-        self.data_stores: Dict[str, AsyncDictStore] = data_stores if data_stores is not None else {}
-        self.handlers: Dict[str, Callable] = {}
-        self.aggregator_handlers: Dict[str, Callable] = {}
+        self.data_stores: dict[str, AsyncDictStore] = data_stores if data_stores is not None else {}
+        self.handlers: dict[str, Callable] = {}
+        self.aggregator_handlers: dict[str, Callable] = {}
         self.conditional_handlers: list[ConditionalHandler] = []
-        self.start_state: Optional[str] = None
+        self.start_state: str | None = None
         self.end_states: set[str] = set()
 
-    def add_data_store(self, name: str, initial_data: Dict[str, Any]):
+    def add_data_store(self, name: str, initial_data: dict[str, Any]):
         """Adds a named data store to the blueprint."""
         if name in self.data_stores:
             raise ValueError(f"Data store with name '{name}' already exists.")
@@ -174,7 +172,7 @@ class StateMachineBlueprint:
             f"No suitable handler found for state '{state}' in blueprint '{self.name}' for the given context.",
         )
 
-    def render_graph(self, output_filename: Optional[str] = None, output_format: str = "png"):
+    def render_graph(self, output_filename: str | None = None, output_format: str = "png"):
         import ast
         import inspect
         import logging

{avtomatika-1.0b4 → avtomatika-1.0b5}/src/avtomatika/config.py

@@ -1,4 +1,5 @@
 from os import getenv
+from socket import gethostname
 
 
 class Config:
@@ -7,6 +8,9 @@ class Config:
     """
 
     def __init__(self):
+        # Instance identity
+        self.INSTANCE_ID: str = getenv("INSTANCE_ID", gethostname())
+
         # Redis settings
         self.REDIS_HOST: str = getenv("REDIS_HOST", "")
         self.REDIS_PORT: int = int(getenv("REDIS_PORT", 6379))
@@ -45,6 +49,9 @@ class Config:
         self.WATCHER_INTERVAL_SECONDS: int = int(
             getenv("WATCHER_INTERVAL_SECONDS", 20),
         )
+        self.EXECUTOR_MAX_CONCURRENT_JOBS: int = int(
+            getenv("EXECUTOR_MAX_CONCURRENT_JOBS", 100),
+        )
 
         # History storage settings
         self.HISTORY_DATABASE_URI: str = getenv("HISTORY_DATABASE_URI", "")

{avtomatika-1.0b4 → avtomatika-1.0b5}/src/avtomatika/context.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict, List, Optional
+from typing import Any
 
 
 class ActionFactory:
@@ -6,10 +6,10 @@ class ActionFactory:
 
     def __init__(self, job_id: str):
         self._job_id = job_id
-        self._next_state_val: Optional[str] = None
-        self._task_to_dispatch_val: Optional[Dict[str, Any]] = None
-        self._sub_blueprint_to_run_val: Optional[Dict[str, Any]] = None
-        self._parallel_tasks_to_dispatch_val: Optional[Dict[str, Any]] = None
+        self._next_state_val: str | None = None
+        self._task_to_dispatch_val: dict[str, Any] | None = None
+        self._sub_blueprint_to_run_val: dict[str, Any] | None = None
+        self._parallel_tasks_to_dispatch_val: dict[str, Any] | None = None
 
     def _check_for_existing_action(self):
         """
@@ -30,22 +30,22 @@ class ActionFactory:
             )
 
     @property
-    def next_state(self) -> Optional[str]:
+    def next_state(self) -> str | None:
         return self._next_state_val
 
     @property
-    def task_to_dispatch(self) -> Optional[Dict[str, Any]]:
+    def task_to_dispatch(self) -> dict[str, Any] | None:
         return self._task_to_dispatch_val
 
     @property
-    def sub_blueprint_to_run(self) -> Optional[Dict[str, Any]]:
+    def sub_blueprint_to_run(self) -> dict[str, Any] | None:
         return self._sub_blueprint_to_run_val
 
     @property
-    def parallel_tasks_to_dispatch(self) -> Optional[Dict[str, Any]]:
+    def parallel_tasks_to_dispatch(self) -> dict[str, Any] | None:
         return self._parallel_tasks_to_dispatch_val
 
-    def dispatch_parallel(self, tasks: List[Dict[str, Any]], aggregate_into: str) -> None:
+    def dispatch_parallel(self, tasks: dict[str, Any] | None, aggregate_into: str) -> None:
         """
         Dispatches multiple tasks for parallel execution.
         """
@@ -65,12 +65,12 @@ class ActionFactory:
     def dispatch_task(
         self,
         task_type: str,
-        params: Dict[str, Any],
-        transitions: Dict[str, str],
+        params: dict[str, Any],
+        transitions: dict[str, str],
         dispatch_strategy: str = "default",
-        resource_requirements: Optional[Dict[str, Any]] = None,
-        timeout_seconds: Optional[int] = None,
-        max_cost: Optional[float] = None,
+        resource_requirements: dict[str, Any] | None = None,
+        timeout_seconds: int | None = None,
+        max_cost: float | None = None,
         priority: float = 0.0,
     ) -> None:
         """Dispatches a task to a worker for execution."""
@@ -91,7 +91,7 @@ class ActionFactory:
         self,
         integration: str,
         message: str,
-        transitions: Dict[str, str],
+        transitions: dict[str, str],
     ) -> None:
         """Pauses the pipeline until an external signal (human approval) is received."""
         self._check_for_existing_action()
@@ -106,8 +106,8 @@ class ActionFactory:
     def run_blueprint(
         self,
         blueprint_name: str,
-        initial_data: Dict[str, Any],
-        transitions: Dict[str, str],
+        initial_data: dict[str, Any],
+        transitions: dict[str, str],
     ) -> None:
         """Runs a child blueprint and waits for its result."""
         self._check_for_existing_action()

{avtomatika-1.0b4 → avtomatika-1.0b5}/src/avtomatika/data_types.py

@@ -1,4 +1,4 @@
-from typing import TYPE_CHECKING, Any, Dict, NamedTuple, Optional
+from typing import TYPE_CHECKING, Any, NamedTuple
 
 if TYPE_CHECKING:
     from .context import ActionFactory
@@ -9,8 +9,7 @@ class ClientConfig(NamedTuple):
 
     token: str
     plan: str
-    # Use Dict to support any custom fields
-    params: Dict[str, Any]
+    params: dict[str, Any]
 
 
 class JobContext(NamedTuple):
@@ -18,13 +17,13 @@ class JobContext(NamedTuple):
 
     job_id: str
     current_state: str
-    initial_data: Dict[str, Any]
-    state_history: Dict[str, Any]
+    initial_data: dict[str, Any]
+    state_history: dict[str, Any]
     client: ClientConfig
     actions: "ActionFactory"
     data_stores: Any = None
-    tracing_context: Dict[str, Any] = {}
-    aggregation_results: Optional[Dict[str, Any]] = None
+    tracing_context: dict[str, Any] = {}
+    aggregation_results: dict[str, Any] | None = None
 
 
 class GPUInfo(NamedTuple):

{avtomatika-1.0b4 → avtomatika-1.0b5}/src/avtomatika/datastore.py

@@ -1,4 +1,4 @@
-from typing import Any, Dict
+from typing import Any
 
 
 class AsyncDictStore:
@@ -6,7 +6,7 @@ class AsyncDictStore:
     Simulates the behavior of a persistent store for use in blueprints.
     """
 
-    def __init__(self, initial_data: Dict[str, Any]):
+    def __init__(self, initial_data: dict[str, Any]):
         self._data = initial_data.copy()
 
     async def get(self, key: str) -> Any:

{avtomatika-1.0b4 → avtomatika-1.0b5}/src/avtomatika/dispatcher.py

@@ -1,7 +1,7 @@
 from collections import defaultdict
 from logging import getLogger
 from random import choice
-from typing import Any, Dict, List
+from typing import Any
 from uuid import uuid4
 
 try:
@@ -26,12 +26,12 @@ class Dispatcher:
     def __init__(self, storage: StorageBackend, config: Config):
         self.storage = storage
         self.config = config
-        self._round_robin_indices: Dict[str, int] = defaultdict(int)
+        self._round_robin_indices: dict[str, int] = defaultdict(int)
 
     @staticmethod
     def _is_worker_compliant(
-        worker: Dict[str, Any],
-        requirements: Dict[str, Any],
+        worker: dict[str, Any],
+        requirements: dict[str, Any],
     ) -> bool:
         """Checks if a worker meets the specified resource requirements."""
         if required_gpu := requirements.get("gpu_info"):
@@ -58,9 +58,9 @@ class Dispatcher:
 
     @staticmethod
     def _select_default(
-        workers: List[Dict[str, Any]],
+        workers: list[dict[str, Any]],
         task_type: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Default strategy: first selects "warm" workers (those that have the
         task in their cache), and then selects the cheapest among them.
 
@@ -80,9 +80,9 @@ class Dispatcher:
 
     def _select_round_robin(
         self,
-        workers: List[Dict[str, Any]],
+        workers: list[dict[str, Any]],
         task_type: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """ "Round Robin" strategy: distributes tasks sequentially among all
         available workers.
         """
@@ -93,9 +93,9 @@ class Dispatcher:
 
     @staticmethod
     def _select_least_connections(
-        workers: List[Dict[str, Any]],
+        workers: list[dict[str, Any]],
         task_type: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """ "Least Connections" strategy: selects the worker with the fewest
         active tasks (based on the `load` field).
         """
@@ -103,14 +103,14 @@ class Dispatcher:
 
     @staticmethod
     def _select_cheapest(
-        workers: List[Dict[str, Any]],
+        workers: list[dict[str, Any]],
         task_type: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Selects the cheapest worker based on 'cost_per_second'."""
         return min(workers, key=lambda w: w.get("cost_per_second", float("inf")))
 
     @staticmethod
-    def _get_best_value_score(worker: Dict[str, Any]) -> float:
+    def _get_best_value_score(worker: dict[str, Any]) -> float:
         """Calculates a "score" for a worker using the formula cost / reputation.
         The lower the score, the better.
         """
@@ -122,13 +122,13 @@ class Dispatcher:
 
     def _select_best_value(
         self,
-        workers: List[Dict[str, Any]],
+        workers: list[dict[str, Any]],
         task_type: str,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """Selects the worker with the best price-quality (reputation) ratio."""
         return min(workers, key=self._get_best_value_score)
 
-    async def dispatch(self, job_state: Dict[str, Any], task_info: Dict[str, Any]):
+    async def dispatch(self, job_state: dict[str, Any], task_info: dict[str, Any]):
         job_id = job_state["id"]
         task_type = task_info.get("type")
         if not task_type:
@@ -142,7 +142,6 @@ class Dispatcher:
         if not all_workers:
             raise RuntimeError("No available workers")
 
-        # 1. Filter by 'idle' status
         # A worker is considered available if its status is 'idle' or not specified (for backward compatibility)
         logger.debug(f"All available workers: {[w['worker_id'] for w in all_workers]}")
         idle_workers = [w for w in all_workers if w.get("status", "idle") == "idle"]
@@ -157,13 +156,13 @@ class Dispatcher:
                 )
             raise RuntimeError("No idle workers (all are 'busy')")
 
-        # 2. Filter by task type
+        # Filter by task type
         capable_workers = [w for w in idle_workers if task_type in w.get("supported_tasks", [])]
         logger.debug(f"Capable workers for task '{task_type}': {[w['worker_id'] for w in capable_workers]}")
         if not capable_workers:
             raise RuntimeError(f"No suitable workers for task type '{task_type}'")
 
-        # 3. Filter by resource requirements
+        # Filter by resource requirements
         if resource_requirements:
             compliant_workers = [w for w in capable_workers if self._is_worker_compliant(w, resource_requirements)]
             logger.debug(
@@ -176,7 +175,7 @@ class Dispatcher:
                 )
             capable_workers = compliant_workers
 
-        # 4. Filter by maximum cost
+        # Filter by maximum cost
         max_cost = task_info.get("max_cost")
         if max_cost is not None:
             cost_compliant_workers = [w for w in capable_workers if w.get("cost_per_second", float("inf")) <= max_cost]
@@ -189,7 +188,7 @@ class Dispatcher:
                 )
             capable_workers = cost_compliant_workers
 
-        # 5. Select worker according to strategy
+        # Select worker according to strategy
         if dispatch_strategy == "round_robin":
             selected_worker = self._select_round_robin(capable_workers, task_type)
         elif dispatch_strategy == "least_connections":