nat-engine 1__py3-none-any.whl

mannf/product/scheduling/__init__.py

@@ -0,0 +1,57 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Scheduled scan infrastructure for NAT.
+
+Provides recurring scan scheduling (cron-based) for Pro tier and above.
+
+Usage::
+
+    from mannf.product.scheduling import ScanSchedule, ScheduleStore, SchedulerEngine
+    from mannf.product.scheduling.cron_utils import next_run_after, validate_cron
+
+    # Validate a cron expression
+    validate_cron("0 2 * * *")  # 2am daily
+
+    # Create a schedule store
+    store = ScheduleStore()
+
+    # Start the engine
+    engine = SchedulerEngine(store=store)
+    await engine.start()
+"""
+
+from mannf.product.scheduling.cron_utils import next_run_after, validate_cron
+from mannf.product.scheduling.engine import SchedulerEngine
+from mannf.product.scheduling.models import ScanSchedule
+from mannf.product.scheduling.queue import (
+    InMemoryJobQueue,
+    Job,
+    JobQueue,
+    QueueStats,
+    RedisJobQueue,
+    SQLiteJobQueue,
+    create_job_queue,
+    get_default_queue,
+    set_default_queue,
+)
+from mannf.product.scheduling.store import ScheduleStore
+
+__all__ = [
+    "ScanSchedule",
+    "ScheduleStore",
+    "SchedulerEngine",
+    "next_run_after",
+    "validate_cron",
+    # Job queue
+    "Job",
+    "JobQueue",
+    "QueueStats",
+    "InMemoryJobQueue",
+    "SQLiteJobQueue",
+    "RedisJobQueue",
+    "create_job_queue",
+    "get_default_queue",
+    "set_default_queue",
+]

mannf/product/scheduling/cron_utils.py

@@ -0,0 +1,251 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+
+"""Cron expression parser, validator, and next-run calculator.
+
+Supports standard 5-field cron expressions::
+
+    ┌─────── minute       (0-59)
+    │ ┌───── hour         (0-23)
+    │ │ ┌─── day-of-month (1-31)
+    │ │ │ ┌─ month        (1-12)
+    │ │ │ │ ┌ day-of-week (0-6, Sun=0)
+    │ │ │ │ │
+    * * * * *
+
+Supported field syntax:
+
+- ``*``      — every value
+- ``5``      — exact value
+- ``1-5``    — inclusive range
+- ``*/15``   — step (every N)
+- ``1,3,5``  — list of values
+
+Usage::
+
+    from mannf.product.scheduling.cron_utils import validate_cron, next_run_after
+    from datetime import datetime, timezone
+
+    validate_cron("0 2 * * *")          # raises ValueError on bad input
+    nxt = next_run_after("0 2 * * *", datetime.now(timezone.utc))
+    print(nxt.isoformat())
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta, timezone
+from typing import Iterable
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+# ---------------------------------------------------------------------------
+# Field constraints
+# ---------------------------------------------------------------------------
+
+_FIELD_RANGES: tuple[tuple[int, int], ...] = (
+    (0, 59),   # minute
+    (0, 23),   # hour
+    (1, 31),   # day-of-month
+    (1, 12),   # month
+    (0, 6),    # day-of-week (0=Sun, 6=Sat)
+)
+
+_FIELD_NAMES: tuple[str, ...] = (
+    "minute",
+    "hour",
+    "day-of-month",
+    "month",
+    "day-of-week",
+)
+
+
+# ---------------------------------------------------------------------------
+# Low-level field parser
+# ---------------------------------------------------------------------------
+
+def _parse_field(token: str, lo: int, hi: int, field_name: str) -> frozenset[int]:
+    """Parse a single cron field token into a frozenset of matching integers.
+
+    Args:
+        token: The cron field token (e.g. ``"*"``, ``"0-5"``, ``"*/15"``).
+        lo: Minimum allowed value (inclusive).
+        hi: Maximum allowed value (inclusive).
+        field_name: Human-readable name used in error messages.
+
+    Returns:
+        A :class:`frozenset` of integers representing all matching values.
+
+    Raises:
+        ValueError: When the token is syntactically invalid or out-of-range.
+    """
+    def _check(v: int) -> int:
+        if not (lo <= v <= hi):
+            raise ValueError(
+                f"Cron field '{field_name}': value {v} out of range [{lo}, {hi}]"
+            )
+        return v
+
+    def _expand(token_part: str) -> Iterable[int]:
+        if "-" in token_part:
+            parts = token_part.split("-", 1)
+            if len(parts) != 2:
+                raise ValueError(
+                    f"Cron field '{field_name}': invalid range '{token_part}'"
+                )
+            try:
+                start, end = int(parts[0]), int(parts[1])
+            except ValueError:
+                raise ValueError(
+                    f"Cron field '{field_name}': non-integer range '{token_part}'"
+                )
+            _check(start)
+            _check(end)
+            if start > end:
+                raise ValueError(
+                    f"Cron field '{field_name}': range start {start} > end {end}"
+                )
+            return range(start, end + 1)
+        else:
+            try:
+                return [_check(int(token_part))]
+            except ValueError as exc:
+                raise ValueError(
+                    f"Cron field '{field_name}': non-integer value '{token_part}'"
+                ) from exc
+
+    values: set[int] = set()
+
+    # Step syntax: */N or base/N (base can be a range or single value)
+    if "/" in token:
+        parts = token.split("/", 1)
+        if len(parts) != 2:
+            raise ValueError(f"Cron field '{field_name}': invalid step syntax '{token}'")
+        base_part, step_part = parts
+        try:
+            step = int(step_part)
+        except ValueError:
+            raise ValueError(
+                f"Cron field '{field_name}': non-integer step '{step_part}'"
+            )
+        if step <= 0:
+            raise ValueError(
+                f"Cron field '{field_name}': step must be positive, got {step}"
+            )
+        if base_part == "*":
+            base_values = range(lo, hi + 1)
+        else:
+            base_values = sorted(_expand(base_part))
+        for i, v in enumerate(base_values):
+            if i % step == 0:
+                values.add(v)
+        return frozenset(values)
+
+    # List syntax: a,b,c  (each element may itself be a range)
+    for part in token.split(","):
+        part = part.strip()
+        if not part:
+            raise ValueError(
+                f"Cron field '{field_name}': empty element in list '{token}'"
+            )
+        if part == "*":
+            values.update(range(lo, hi + 1))
+        else:
+            values.update(_expand(part))
+
+    return frozenset(values)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def validate_cron(expression: str) -> None:
+    """Validate a 5-field cron expression.
+
+    Args:
+        expression: The cron string to validate (exactly 5 whitespace-separated
+            fields).
+
+    Raises:
+        ValueError: When the expression has the wrong number of fields, contains
+            invalid syntax, or has out-of-range values.
+    """
+    _parse_cron(expression)  # raises on error; result is discarded
+
+
+def _parse_cron(expression: str) -> tuple[frozenset[int], ...]:
+    """Parse all 5 fields and return them as a tuple of frozensets."""
+    if not isinstance(expression, str):
+        raise ValueError("Cron expression must be a string")
+    fields = expression.strip().split()
+    if len(fields) != 5:
+        raise ValueError(
+            f"Cron expression must have exactly 5 fields, got {len(fields)}: {expression!r}"
+        )
+    result = []
+    for token, (lo, hi), name in zip(fields, _FIELD_RANGES, _FIELD_NAMES):
+        result.append(_parse_field(token, lo, hi, name))
+    return tuple(result)
+
+
+def next_run_after(
+    expression: str,
+    after: datetime,
+    tz: str = "UTC",
+) -> datetime:
+    """Return the next datetime when *expression* would fire after *after*.
+
+    The algorithm advances minute-by-minute from ``after + 1 min`` until a
+    matching point is found (capped at 4 years to guard against impossible
+    expressions like ``"31 2 30 2 *"``).
+
+    Args:
+        expression: A valid 5-field cron string.
+        after: The reference :class:`~datetime.datetime`.  If it is
+            timezone-naive it is treated as UTC.
+        tz: IANA timezone name used to evaluate the cron fields.  Defaults to
+            ``"UTC"``.
+
+    Returns:
+        A timezone-aware :class:`~datetime.datetime` (in *tz*) of the next
+        matching instant.  The seconds / microseconds components are always 0.
+
+    Raises:
+        ValueError: When *expression* is invalid or *tz* is an unknown IANA
+            timezone name.
+        RuntimeError: When no matching time is found within ~4 years (most
+            likely an impossible expression).
+    """
+    try:
+        zone = ZoneInfo(tz)
+    except (ZoneInfoNotFoundError, KeyError):
+        raise ValueError(f"Unknown timezone: {tz!r}")
+
+    minutes, hours, doms, months, dows = _parse_cron(expression)
+
+    # Normalise *after* to the target timezone, then strip sub-minute precision.
+    if after.tzinfo is None:
+        after = after.replace(tzinfo=timezone.utc)
+    dt = after.astimezone(zone).replace(second=0, microsecond=0)
+
+    # Advance by one minute so we never return the same instant as *after*.
+    dt += timedelta(minutes=1)
+
+    max_iterations = 60 * 24 * 366 * 4  # ~4 years in minutes
+    for _ in range(max_iterations):
+        # day-of-week: 0=Sun … 6=Sat (Python isoweekday: Mon=1 … Sun=7)
+        python_dow = dt.isoweekday() % 7  # Sun=0, Mon=1, …, Sat=6
+        if (
+            dt.month in months
+            and dt.day in doms
+            and python_dow in dows
+            and dt.hour in hours
+            and dt.minute in minutes
+        ):
+            return dt
+        dt += timedelta(minutes=1)
+
+    raise RuntimeError(
+        f"No matching time found within 4 years for cron expression {expression!r}"
+    )