agentexec 0.1.6__tar.gz → 0.1.7__tar.gz

{agentexec-0.1.6 → agentexec-0.1.7}/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## v0.1.7
+
+### New Features
+
+**Scheduled tasks with cron expressions**
+- `@pool.schedule("task_name", "*/5 * * * *")` decorator registers and schedules a task in one step
+- `pool.add_schedule()` for imperative scheduling of already-registered tasks
+- Cron expressions evaluated in configurable timezone (`AGENTEXEC_SCHEDULER_TIMEZONE`, default UTC)
+- Repeat budget: `-1` for forever (default), `0` for one-shot, `N` for N more executions
+- Scheduler runs automatically inside `pool.run()` — no extra setup needed
+- Idempotent registration: keyed by task name, so restarts and multiple pool instances overwrite instead of duplicating
+- Clock-drift resilient: next run computed from intended anchor time, not wall clock
+- Skips missed intervals after downtime instead of enqueuing a burst of catch-up tasks
+- New `croniter` dependency for cron expression parsing
+
+### Improvements
+
+**State backend sorted set operations**
+- Added `zadd()`, `zrangebyscore()`, `zrem()` to `StateBackend` protocol and Redis implementation
+- Used internally by the scheduler for efficient due-task polling
+
 ## v0.1.6
 
 ### New Features

{agentexec-0.1.6 → agentexec-0.1.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentexec
-Version: 0.1.6
+Version: 0.1.7
 Summary: Production-ready orchestration for OpenAI Agents with Redis-backed coordination, activity tracking, and workflow management
 Project-URL: Homepage, https://github.com/Agent-CI/agentexec
 Project-URL: Documentation, https://github.com/Agent-CI/agentexec#readme
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.12
+Requires-Dist: croniter>=6.0.0
 Requires-Dist: openai-agents>=0.1.0
 Requires-Dist: pydantic-settings>=2.5.0
 Requires-Dist: pydantic>=2.12.0
@@ -233,6 +234,31 @@ The lock TTL (`AGENTEXEC_LOCK_TTL`, default 1800s) is a safety net for worker pr
 
 **Note:** When a task is requeued due to a held lock, it goes to the back of the queue. This means strict FIFO ordering is not guaranteed between tasks sharing the same lock key — if tasks T2 and T3 are both waiting on T1's lock, either could run next after T1 completes.
 
+### Scheduled Tasks
+
+Run tasks on a recurring interval using cron expressions:
+
+```python
+# Decorator — registers the task and schedules it in one step
+@pool.schedule("refresh_cache", "*/5 * * * *")
+async def refresh(agent_id: UUID, context: RefreshContext):
+    ...
+
+# With context and repeat limit
+@pool.schedule("sync_users", "0 * * * *", context=SyncContext(full=True), repeat=3)
+async def sync(agent_id: UUID, context: SyncContext):
+    ...
+```
+
+For tasks registered separately, use `pool.add_schedule()`:
+
+```python
+pool.add_schedule("refresh_cache", "*/5 * * * *", RefreshContext(scope="all"))
+pool.add_schedule("refresh_cache", "0 * * * *", RefreshContext(scope="users"), repeat=3)
+```
+
+The scheduler runs automatically inside `pool.run()`. Cron expressions are evaluated in the configured timezone (`AGENTEXEC_SCHEDULER_TIMEZONE`, default UTC) so schedules read naturally regardless of server timezone. Next-run times are computed from the intended anchor time, not wall clock, to prevent cumulative drift.
+
 ### Priority Queue
 
 Control task execution order:
@@ -642,7 +668,12 @@ async def handler(agent_id: UUID, context: MyContext) -> None: ...
 @pool.task("name", lock_key="user:{user_id}")  # Sequential per user
 async def locked(agent_id: UUID, context: MyContext) -> None: ...
 
-pool.run()       # Blocking - runs workers
+@pool.schedule("name", "*/5 * * * *")  # Register + schedule in one step
+async def scheduled(agent_id: UUID, context: MyContext) -> None: ...
+
+pool.add_schedule("name", "0 * * * *", MyContext(), repeat=3)  # Schedule separately
+
+pool.run()       # Blocking - runs workers + scheduler
 pool.start()     # Non-blocking - starts workers in background
 pool.shutdown()  # Graceful shutdown
 ```
@@ -745,6 +776,9 @@ AGENTEXEC_RESULT_TTL=3600
 # Task locking
 AGENTEXEC_LOCK_TTL=1800
 
+# Scheduling
+AGENTEXEC_SCHEDULER_TIMEZONE=UTC
+
 # State backend
 AGENTEXEC_STATE_BACKEND=agentexec.state.redis_backend
 AGENTEXEC_KEY_PREFIX=agentexec

{agentexec-0.1.6 → agentexec-0.1.7}/README.md

@@ -208,6 +208,31 @@ The lock TTL (`AGENTEXEC_LOCK_TTL`, default 1800s) is a safety net for worker pr
 
 **Note:** When a task is requeued due to a held lock, it goes to the back of the queue. This means strict FIFO ordering is not guaranteed between tasks sharing the same lock key — if tasks T2 and T3 are both waiting on T1's lock, either could run next after T1 completes.
 
+### Scheduled Tasks
+
+Run tasks on a recurring interval using cron expressions:
+
+```python
+# Decorator — registers the task and schedules it in one step
+@pool.schedule("refresh_cache", "*/5 * * * *")
+async def refresh(agent_id: UUID, context: RefreshContext):
+    ...
+
+# With context and repeat limit
+@pool.schedule("sync_users", "0 * * * *", context=SyncContext(full=True), repeat=3)
+async def sync(agent_id: UUID, context: SyncContext):
+    ...
+```
+
+For tasks registered separately, use `pool.add_schedule()`:
+
+```python
+pool.add_schedule("refresh_cache", "*/5 * * * *", RefreshContext(scope="all"))
+pool.add_schedule("refresh_cache", "0 * * * *", RefreshContext(scope="users"), repeat=3)
+```
+
+The scheduler runs automatically inside `pool.run()`. Cron expressions are evaluated in the configured timezone (`AGENTEXEC_SCHEDULER_TIMEZONE`, default UTC) so schedules read naturally regardless of server timezone. Next-run times are computed from the intended anchor time, not wall clock, to prevent cumulative drift.
+
 ### Priority Queue
 
 Control task execution order:
@@ -617,7 +642,12 @@ async def handler(agent_id: UUID, context: MyContext) -> None: ...
 @pool.task("name", lock_key="user:{user_id}")  # Sequential per user
 async def locked(agent_id: UUID, context: MyContext) -> None: ...
 
-pool.run()       # Blocking - runs workers
+@pool.schedule("name", "*/5 * * * *")  # Register + schedule in one step
+async def scheduled(agent_id: UUID, context: MyContext) -> None: ...
+
+pool.add_schedule("name", "0 * * * *", MyContext(), repeat=3)  # Schedule separately
+
+pool.run()       # Blocking - runs workers + scheduler
 pool.start()     # Non-blocking - starts workers in background
 pool.shutdown()  # Graceful shutdown
 ```
@@ -720,6 +750,9 @@ AGENTEXEC_RESULT_TTL=3600
 # Task locking
 AGENTEXEC_LOCK_TTL=1800
 
+# Scheduling
+AGENTEXEC_SCHEDULER_TIMEZONE=UTC
+
 # State backend
 AGENTEXEC_STATE_BACKEND=agentexec.state.redis_backend
 AGENTEXEC_KEY_PREFIX=agentexec

{agentexec-0.1.6 → agentexec-0.1.7}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentexec"
-version = "0.1.6"
+version = "0.1.7"
 description = "Production-ready orchestration for OpenAI Agents with Redis-backed coordination, activity tracking, and workflow management"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -25,6 +25,7 @@ dependencies = [
     "pydantic-settings>=2.5.0",
     "sqlalchemy>=2.0.44",
     "openai-agents>=0.1.0",
+    "croniter>=6.0.0",
 ]
 
 

{agentexec-0.1.6 → agentexec-0.1.7}/src/agentexec/config.py

@@ -1,3 +1,5 @@
+from zoneinfo import ZoneInfo
+
 from pydantic import AliasChoices, Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
@@ -86,6 +88,14 @@ class Config(BaseSettings):
         validation_alias="AGENTEXEC_KEY_PREFIX",
     )
 
+    scheduler_timezone: str = Field(
+        default="UTC",
+        description=(
+            "IANA timezone for cron schedule evaluation (e.g. 'America/New_York', 'UTC'). "
+            "Set this so cron expressions read naturally in your local time."
+        ),
+        validation_alias="AGENTEXEC_SCHEDULER_TIMEZONE",
+    )
     lock_ttl: int = Field(
         default=1800,
         description=(
@@ -99,4 +109,10 @@ class Config(BaseSettings):
     )
 
 
+    @property
+    def scheduler_tz(self) -> ZoneInfo:
+        """Resolved ZoneInfo for the configured scheduler timezone."""
+        return ZoneInfo(self.scheduler_timezone)
+
+
 CONF = Config()

agentexec-0.1.7/src/agentexec/schedule.py

@@ -0,0 +1,144 @@
+from __future__ import annotations
+
+import time
+from datetime import datetime
+from typing import Any
+from croniter import croniter
+from pydantic import BaseModel, Field, ValidationError
+
+from agentexec import state
+from agentexec.config import CONF
+from agentexec.core.logging import get_logger
+from agentexec.core.queue import enqueue
+
+logger = get_logger(__name__)
+
+__all__ = [
+    "register",
+    "tick",
+]
+
+REPEAT_FOREVER: int = -1
+
+
+class ScheduledTask(BaseModel):
+    """A task scheduled to run on a recurring interval.
+
+    Stored in Redis with a sorted-set index for efficient due-time polling.
+    Each time it fires, a fresh Task (with its own agent_id) is enqueued
+    for the worker pool. Stays in Redis until its repeat budget is exhausted.
+    """
+
+    task_name: str
+    context: bytes
+    cron: str
+    repeat: int = REPEAT_FOREVER
+    next_run: float = 0
+    created_at: float = Field(default_factory=lambda: time.time())
+    metadata: dict[str, Any] | None = None
+
+    def model_post_init(self, __context: Any) -> None:
+        """Compute next_run from cron if not explicitly set."""
+        if self.next_run == 0:
+            self.next_run = self._next_after(self.created_at)
+
+    def advance(self) -> None:
+        """Advance next_run to the next future cron occurrence.
+
+        Skips past any missed intervals so we don't enqueue a burst of
+        catch-up tasks after downtime. Decrements repeat for each skipped
+        interval (finite schedules only; -1 stays unchanged).
+        """
+        now = time.time()
+        while True:
+            self.next_run = self._next_after(self.next_run)
+            if self.repeat >= 0:
+                self.repeat -= 1
+            if self.next_run > now or self.repeat == 0:
+                break
+
+    def _next_after(self, anchor: float) -> float:
+        """Compute the next cron occurrence after anchor."""
+        dt = datetime.fromtimestamp(anchor, tz=CONF.scheduler_tz)
+        return float(croniter(self.cron, dt).get_next(float))
+
+
+def _schedule_key(schedule_id: str) -> str:
+    """Redis key for a schedule definition."""
+    return state.backend.format_key(*state.KEY_SCHEDULE, schedule_id)
+
+
+def _queue_key() -> str:
+    """Redis sorted-set key that indexes schedules by next_run."""
+    return state.backend.format_key(*state.KEY_SCHEDULE_QUEUE)
+
+
+def register(
+    task_name: str,
+    every: str,
+    context: BaseModel,
+    *,
+    repeat: int = REPEAT_FOREVER,
+    metadata: dict[str, Any] | None = None,
+) -> None:
+    """Register a new scheduled task in Redis.
+
+    The task will first fire at the next cron occurrence from now.
+
+    Args:
+        task_name: Name of the registered task to enqueue on each tick.
+        every: Schedule expression (cron syntax: min hour dom mon dow).
+        context: Pydantic context payload passed to the handler each time.
+        repeat: How many additional executions after the first.
+            -1 = forever (default), 0 = one-shot, N = N more times.
+        metadata: Optional metadata dict (e.g. for multi-tenancy).
+    """
+    task = ScheduledTask(
+        task_name=task_name,
+        context=state.backend.serialize(context),
+        cron=every,
+        repeat=repeat,
+        metadata=metadata,
+    )
+
+    state.backend.set(
+        _schedule_key(task_name),
+        task.model_dump_json().encode(),
+    )
+    state.backend.zadd(_queue_key(), {task_name: task.next_run})
+    logger.info(f"Scheduled {task_name}")
+
+
+async def tick() -> None:
+    """Process all scheduled tasks that are due right now.
+
+    For each due task, enqueues it into the normal task queue. If repeats
+    remain, advances to the next run time. Otherwise removes the schedule.
+    """
+    for _task_name in await state.backend.zrangebyscore(_queue_key(), 0, time.time()):
+        task_name = _task_name.decode("utf-8")
+
+        try:
+            data = state.backend.get(_schedule_key(task_name))
+            task = ScheduledTask.model_validate_json(data)
+        except ValidationError:
+            logger.warning(f"Failed to load schedule {task_name}, skipping")
+            continue
+
+        await enqueue(
+            task.task_name,
+            context=state.backend.deserialize(task.context),
+            metadata=task.metadata,
+        )
+
+        if task.repeat == 0:
+            state.backend.zrem(_queue_key(), task_name)
+            state.backend.delete(_schedule_key(task_name))
+            logger.info(f"Schedule for '{task_name}' exhausted")
+        else:
+            task.advance()
+            state.backend.set(
+                _schedule_key(task_name),
+                task.model_dump_json().encode(),
+            )
+            state.backend.zadd(_queue_key(), {task_name: task.next_run})

{agentexec-0.1.6 → agentexec-0.1.7}/src/agentexec/state/__init__.py

@@ -12,6 +12,8 @@ from agentexec.state.backend import StateBackend
 KEY_RESULT = (CONF.key_prefix, "result")
 KEY_EVENT = (CONF.key_prefix, "event")
 KEY_LOCK = (CONF.key_prefix, "lock")
+KEY_SCHEDULE = (CONF.key_prefix, "schedule")
+KEY_SCHEDULE_QUEUE = (CONF.key_prefix, "schedule_queue")
 CHANNEL_LOGS = (CONF.key_prefix, "logs")
 
 __all__ = [

{agentexec-0.1.6 → agentexec-0.1.7}/src/agentexec/state/backend.py

@@ -281,6 +281,49 @@ class StateBackend(Protocol):
         """
         ...
 
+    # Sorted set operations
+    @staticmethod
+    def zadd(key: str, mapping: dict[str, float]) -> int:
+        """Add members to a sorted set with scores.
+
+        Args:
+            key: Sorted set key
+            mapping: Dict of {member: score}
+
+        Returns:
+            Number of new members added
+        """
+        ...
+
+    @staticmethod
+    async def zrangebyscore(
+        key: str, min_score: float, max_score: float
+    ) -> list[bytes]:
+        """Get members with scores between min and max.
+
+        Args:
+            key: Sorted set key
+            min_score: Minimum score (inclusive)
+            max_score: Maximum score (inclusive)
+
+        Returns:
+            List of members as bytes
+        """
+        ...
+
+    @staticmethod
+    def zrem(key: str, *members: str) -> int:
+        """Remove members from a sorted set.
+
+        Args:
+            key: Sorted set key
+            *members: Members to remove
+
+        Returns:
+            Number of members removed
+        """
+        ...
+
     # Cleanup operations
     @staticmethod
     def clear_keys() -> int:

{agentexec-0.1.6 → agentexec-0.1.7}/src/agentexec/state/redis_backend.py

@@ -27,6 +27,9 @@ __all__ = [
     "publish",
     "subscribe",
     "close",
+    "zadd",
+    "zrangebyscore",
+    "zrem",
     "clear_keys",
 ]
 
@@ -410,6 +413,51 @@ async def subscribe(channel: str) -> AsyncGenerator[str, None]:
         _pubsub = None
 
 
+def zadd(key: str, mapping: dict[str, float]) -> int:
+    """Add members to a sorted set with scores.
+
+    Args:
+        key: Sorted set key
+        mapping: Dict of {member: score}
+
+    Returns:
+        Number of new members added
+    """
+    client = _get_sync_client()
+    return client.zadd(key, mapping)  # type: ignore[return-value]
+
+
+async def zrangebyscore(
+    key: str, min_score: float, max_score: float
+) -> list[bytes]:
+    """Get members with scores between min and max.
+
+    Args:
+        key: Sorted set key
+        min_score: Minimum score (inclusive)
+        max_score: Maximum score (inclusive)
+
+    Returns:
+        List of members as bytes
+    """
+    client = _get_async_client()
+    return await client.zrangebyscore(key, min_score, max_score)  # type: ignore[return-value]
+
+
+def zrem(key: str, *members: str) -> int:
+    """Remove members from a sorted set.
+
+    Args:
+        key: Sorted set key
+        *members: Members to remove
+
+    Returns:
+        Number of members removed
+    """
+    client = _get_sync_client()
+    return client.zrem(key, *members)  # type: ignore[return-value]
+
+
 def clear_keys() -> int:
     """Clear all Redis keys managed by this application.
 

{agentexec-0.1.6 → agentexec-0.1.7}/src/agentexec/worker/pool.py

@@ -4,7 +4,7 @@ import asyncio
 import logging
 import multiprocessing as mp
 from dataclasses import dataclass
-from typing import Callable
+from typing import Any, Callable
 from uuid import uuid4
 
 from pydantic import BaseModel
@@ -15,6 +15,7 @@ from agentexec.config import CONF
 from agentexec.core.db import remove_global_session, set_global_session
 from agentexec.core.queue import dequeue, requeue
 from agentexec.core.task import Task, TaskDefinition, TaskHandler
+from agentexec import schedule
 from agentexec.worker.event import StateEvent
 from agentexec.worker.logging import (
     DEFAULT_FORMAT,
@@ -28,6 +29,12 @@ __all__ = [
 ]
 
 
+class _EmptyContext(BaseModel):
+    """Default context for scheduled tasks that don't need one."""
+
+    pass
+
+
 def _get_pool_id() -> str:
     """Get a unique pool ID for shutdown event keys."""
     return str(uuid4())
@@ -275,6 +282,98 @@ class Pool:
         )
         self._context.tasks[name] = definition
 
+    def schedule(
+        self,
+        name: str,
+        every: str,
+        *,
+        context: BaseModel | None = None,
+        repeat: int = -1,
+        lock_key: str | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> Callable[[TaskHandler], TaskHandler]:
+        """Decorator to register and schedule a task in one step.
+
+        Combines ``@pool.task()`` and ``pool.add_schedule()`` — registers the
+        handler as a task and schedules it to run on the given interval.
+
+        Args:
+            name: Task name used when enqueueing and for worker routing.
+            every: Schedule expression (cron syntax: min hour dom mon dow).
+            context: Pydantic context payload passed to the handler each time.
+                Defaults to an empty BaseModel if not provided.
+            repeat: How many additional executions after the first.
+                -1 = forever (default), 0 = one-shot, N = N more times.
+            lock_key: Optional string template for distributed locking.
+            metadata: Optional metadata dict (e.g. for multi-tenancy).
+
+        Returns:
+            Decorator function that returns the handler.
+
+        Example:
+            @pool.schedule("refresh_cache", "*/5 * * * *")
+            async def refresh(agent_id: UUID, context: RefreshContext):
+                ...
+
+            @pool.schedule("sync_users", "0 * * * *", context=SyncContext(full=True), repeat=3)
+            async def sync(agent_id: UUID, context: SyncContext):
+                ...
+        """
+
+        def decorator(func: TaskHandler) -> TaskHandler:
+            self.add_task(name, func, lock_key=lock_key)
+            self.add_schedule(
+                name, every, context or _EmptyContext(),
+                repeat=repeat, metadata=metadata,
+            )
+            return func
+
+        return decorator
+
+    def add_schedule(
+        self,
+        task_name: str,
+        every: str,
+        context: BaseModel,
+        *,
+        repeat: int = -1,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        """Schedule a registered task to run on a recurring interval.
+
+        The task must already be registered via ``@pool.task()`` or
+        ``pool.add_task()``.  The scheduler loop runs automatically
+        inside ``pool.run()`` — no extra setup needed.
+
+        Args:
+            task_name: Name of a registered task.
+            every: Schedule expression (cron syntax: min hour dom mon dow).
+            context: Pydantic context payload passed to the handler each time.
+            repeat: How many additional executions after the first.
+                -1 = forever (default), 0 = one-shot, N = N more times.
+            metadata: Optional metadata dict (e.g. for multi-tenancy).
+
+        Raises:
+            ValueError: If the task name is not registered with this pool.
+
+        Example:
+            pool.add_schedule("refresh_cache", "*/5 * * * *", RefreshContext(scope="all"))
+            pool.add_schedule("refresh_cache", "0 * * * *", RefreshContext(scope="users"), repeat=3)
+        """
+        if task_name not in self._context.tasks:
+            raise ValueError(
+                f"Task '{task_name}' is not registered. "
+                f"Use @pool.task() or pool.add_task() first."
+            )
+
+        schedule.register(
+            task_name=task_name,
+            every=every,
+            context=context,
+            repeat=repeat,
+            metadata=metadata,
+        )
+
     def start(self) -> None:
         """Start worker processes (non-blocking).
 
@@ -301,6 +400,9 @@ class Pool:
 
         Spawns worker processes and runs an async event loop in the main
         process that collects logs from workers via Redis pubsub.
+        The scheduler loop also runs automatically alongside the workers,
+        polling for due scheduled tasks and enqueuing them.
+
         Blocks until all workers exit or KeyboardInterrupt, then shuts
         down gracefully.
         """
@@ -335,16 +437,17 @@ class Pool:
             print(f"Started worker {worker_id} (PID: {process.pid})")
 
     async def _collect_logs(self) -> None:
-        """Listen for log messages from workers via state backend pubsub."""
+        """Listen for log messages from workers and run scheduler ticks."""
         assert self._log_handler, "Log handler not initialized"
 
         # Create task to subscribe to logs
         log_task = asyncio.create_task(self._process_log_stream())
 
         try:
-            # Poll worker processes
+            # Poll worker processes and run scheduler
             while any(p.is_alive() for p in self._processes):
                 await asyncio.sleep(0.1)
+                await schedule.tick()
         finally:
             log_task.cancel()
             try: