Skip to content

"Vibe-Trading: Your Personal Trading Agent"

20.1 KB
Raw Blame
"""Data model for scheduled research jobs.

A ``ScheduledResearchJob`` records everything needed to describe a deferred
research or backtest run: the prompt/query, when to run it, and an opaque
``config`` dict for future backtest parameters. Execution wiring is deferred
to a follow-up PR once the product shape is confirmed.
"""

from __future__ import annotations

import logging
import time
from dataclasses import dataclass, field
from enum import Enum
from typing import Any, Dict, Optional

from .verdict import VerdictRecord

# --- Schedule grammar, moved to src.scheduling.triggers (scheduler unification) ---
# Re-exported here so existing ``from src.scheduled_research.models import ...``
# keeps working (same convention as src/agent/loop.py's llm_usage re-export).
from src.scheduling.triggers import (
    CRON_BOUNDS as CRON_BOUNDS,
    is_interval_schedule as is_interval_schedule,
    parse_cron_field as parse_cron_field,
    validate_schedule as validate_schedule,
    validate_timezone as validate_timezone,
    validate_timezone_shape as validate_timezone_shape,
)
from src.scheduling.types import ExecutorKind, is_executor_kind

logger = logging.getLogger(__name__)

# ---------------------------------------------------------------------------
# Status enum
# ---------------------------------------------------------------------------


class JobStatus(str, Enum):
    """Lifecycle status of a scheduled research job."""

    PENDING = "pending"
    RUNNING = "running"
    COMPLETED = "completed"
    FAILED = "failed"
    CANCELLED = "cancelled"
    EXPIRED = "expired"


class DeliveryStatus(str, Enum):
    """Outbox state for one job firing's briefing.

    The dispatch path returns once the agent attempt is *accepted*, not when it
    finishes, so "the run completed" and "the briefing was delivered" are two
    different facts and each needs its own record. PENDING means a run was
    dispatched and its result has not been delivered yet; it is the only state
    a sweep needs to look at.
    """

    NONE = "none"
    PENDING = "pending"
    #: Claimed by a sweep that is inside the send call. The claim is a lease,
    #: not a lock: a process that dies mid-send would otherwise strand the row
    #: forever, so a stale SENDING row becomes eligible again once its lease
    #: expires. Without the claim, a concurrent sweep reads PENDING while the
    #: first send is still in flight and delivers the same briefing twice.
    SENDING = "sending"
    ACCEPTED = "accepted"
    SENT = "sent"
    FAILED = "failed"


@dataclass
class DeliveryRecord:
    """What happened to the briefing produced by one firing.

    Attributes:
        status: Outbox state for this firing.
        session_id: The session whose terminal result is to be delivered.
        key: Idempotency key. A send is refused when a record with the same
            key is already ``SENT``, so a restarted poller, a retried sweep and
            an event arriving twice cannot produce a second message.
        error: Redaction-safe diagnostic from the last failed delivery.
        attempts: Failed send attempts for this firing. A channel outage is
            transient, so a failed send stays PENDING and is retried; only the
            attempt threshold, or a run that produced no briefing at all,
            makes the row terminal.
        updated_at: Epoch-millisecond timestamp of the last state change.
    """

    status: DeliveryStatus = DeliveryStatus.NONE
    session_id: Optional[str] = None
    key: Optional[str] = None
    error: Optional[str] = None
    attempts: int = 0
    updated_at: Optional[int] = None
    provider_message_id: Optional[str] = None

    def to_dict(self) -> Dict[str, Any]:
        """Serialize to a plain JSON-serializable dict."""
        return {
            "status": self.status.value,
            "session_id": self.session_id,
            "key": self.key,
            "error": self.error,
            "attempts": self.attempts,
            "updated_at": self.updated_at,
            "provider_message_id": self.provider_message_id,
        }

    @classmethod
    def from_dict(cls, data: Optional[Dict[str, Any]]) -> "DeliveryRecord":
        """Reconstruct from a raw dict, treating absence as "never delivered".

        Args:
            data: A raw dict as produced by :meth:`to_dict`, or ``None`` for a
                record written before delivery existed.

        Returns:
            The reconstructed :class:`DeliveryRecord`.

        Raises:
            TypeError: If a present field has the wrong type.
            ValueError: If ``status`` is not a recognized value.
        """
        if not data:
            return cls()
        if not isinstance(data, dict):
            raise TypeError("'delivery' must be an object or null")
        raw_status = data.get("status", DeliveryStatus.NONE.value)
        try:
            status = DeliveryStatus(raw_status)
        except ValueError as exc:
            raise ValueError(f"unknown delivery status {raw_status!r}") from exc
        for name in ("session_id", "key", "error", "provider_message_id"):
            value = data.get(name)
            if value is not None and not isinstance(value, str):
                raise TypeError(f"'delivery.{name}' must be a string or null")
        updated_at = data.get("updated_at")
        if updated_at is not None and not isinstance(updated_at, int):
            raise TypeError("'delivery.updated_at' must be an integer (epoch ms) or null")
        attempts = data.get("attempts", 0)
        if isinstance(attempts, bool) or not isinstance(attempts, int) or attempts < 0:
            raise TypeError("'delivery.attempts' must be a non-negative integer")
        return cls(
            status=status,
            session_id=data.get("session_id"),
            key=data.get("key"),
            error=data.get("error"),
            attempts=attempts,
            updated_at=updated_at,
            provider_message_id=data.get("provider_message_id"),
        )


# ---------------------------------------------------------------------------
# Data model
# ---------------------------------------------------------------------------


def _verdict_record_or_none(data: Any, job_id: str) -> Optional[VerdictRecord]:
    """Parse a persisted last_verdict, degrading an unreadable one to None.

    A malformed verdict must never take the job down with it, the same way an
    unusable timezone degrades to UTC rather than quarantining the record.
    """
    if data is None:
        return None
    if not isinstance(data, dict):
        logger.warning(
            "scheduled research job %s drops a non-dict last_verdict %r", job_id, data
        )
        return None
    try:
        return VerdictRecord.from_dict(data)
    except (KeyError, TypeError, ValueError) as exc:
        logger.warning(
            "scheduled research job %s drops an unreadable last_verdict: %r", job_id, exc
        )
        return None


def contains_pdf_password(value: Any) -> bool:
    """Return whether arbitrary job config contains the Email PDF secret key."""
    if isinstance(value, dict):
        return any(
            str(key).casefold() == "pdf_password" or contains_pdf_password(item)
            for key, item in value.items()
        )
    if isinstance(value, (list, tuple)):
        return any(contains_pdf_password(item) for item in value)
    return False


@dataclass
class ScheduledResearchJob:
    """Mutable persisted state for a scheduled research / backtest job.

    Attributes:
        id: Unique job identifier (caller-supplied UUID or slug).
        prompt: Research prompt or backtest description.
        schedule: Interval-ms string or 5-field cron expression.
        next_run_at: Epoch-millisecond timestamp for the next intended
            execution. Defaults to the current time when the job is created.
        status: Current lifecycle status.
        created_at: Epoch-millisecond timestamp of job creation.
        last_run_at: Epoch-millisecond timestamp of the most recent executor
            attempt, or ``None`` when the job has not fired yet.
        consecutive_failures: Number of consecutive dispatch failures. A
            successful dispatch resets it to zero.
        last_error: Redaction-safe diagnostic from the latest failed attempt.
        failure_kind: ``"dispatch"`` for provider/session failures or
            ``"schedule"`` when the schedule cannot be advanced.
        config: Opaque dict for future backtest parameters.
        timezone: IANA timezone key the cron schedule is evaluated in, or
            ``None`` for UTC (the semantics every job had before this field
            existed). Interval schedules ignore it.
        delivery_channel: Channel id a finished briefing is pushed to, or
            ``None`` to keep the job's results in the app only. Delivery is
            opt-in per job: absent this, nothing is ever sent anywhere.
        delivery_target: Address within that channel (chat / group / user id).
        delivery: Outbox state for the most recent firing. Separate from
            ``status`` because dispatch returns at enqueue: a job can be
            COMPLETED (accepted) while its briefing is still PENDING delivery.
        last_verdict: The latest run's parsed verdict record, or ``None`` when
            no completed run produced one yet. Embedded with its own
            ``previous`` so the list view renders a delta in one query.
        executor_kind: ``"prompt"`` dispatches ``prompt`` to the agent (every
            job before scheduler unification); ``"internal"`` calls the
            in-process callable registered under ``internal_callable``.
        internal_callable: Registry KEY name — never an import path — used to
            resolve the internal executor for ``executor_kind="internal"``
            jobs. ``None`` for prompt jobs. Internal/system jobs legitimately
            carry ``prompt=""``.
    """

    id: str
    prompt: str
    schedule: str
    title: str = ""
    source_type: str = "prompt"
    playbook_slug: Optional[str] = None
    # Downgrade risk (documented, fail-closed): ``_SCHEMA_VERSION`` stays 1
    # while ``source_type="system"`` rows may exist, so code from BEFORE
    # scheduler unification rejects such a row in ``from_dict`` and the store
    # quarantines the whole file as ``.corrupt-<ts>`` (data preserved, not
    # loaded). Downgrading to a version before scheduler-unification requires
    # removing system job rows first.
    executor_kind: ExecutorKind = "prompt"
    internal_callable: Optional[str] = None
    end_at: Optional[int] = None
    next_run_at: int = field(default_factory=lambda: int(time.time() * 1000))
    status: JobStatus = JobStatus.PENDING
    created_at: int = field(default_factory=lambda: int(time.time() * 1000))
    last_run_at: Optional[int] = None
    consecutive_failures: int = 0
    last_error: Optional[str] = None
    failure_kind: Optional[str] = None
    config: Dict[str, Any] = field(default_factory=dict)
    timezone: Optional[str] = None
    delivery_channel: Optional[str] = None
    delivery_target: Optional[str] = None
    delivery_target_ref: Optional[str] = None
    delivery_target_label: Optional[str] = None
    delivery_format: Optional[str] = None
    protect_pdf: bool = False
    delivery: DeliveryRecord = field(default_factory=DeliveryRecord)
    last_verdict: Optional[VerdictRecord] = None

    def to_dict(self) -> Dict[str, Any]:
        """Serialize to a plain JSON-serializable dict.

        Returns:
            A dict containing all job fields, with ``status`` as its string
            value.
        """
        if contains_pdf_password(self.config):
            raise ValueError("scheduled research config must not contain pdf_password")
        if not isinstance(self.protect_pdf, bool):
            raise TypeError("'protect_pdf' must be a boolean")
        if self.protect_pdf and (self.delivery_channel != "email" or self.delivery_format != "pdf"):
            raise ValueError("'protect_pdf' requires PDF email delivery")
        return {
            "id": self.id,
            "prompt": self.prompt,
            "schedule": self.schedule,
            "title": self.title,
            "source_type": self.source_type,
            "playbook_slug": self.playbook_slug,
            "executor_kind": self.executor_kind,
            "internal_callable": self.internal_callable,
            "end_at": self.end_at,
            "next_run_at": self.next_run_at,
            "status": self.status.value,
            "created_at": self.created_at,
            "last_run_at": self.last_run_at,
            "consecutive_failures": self.consecutive_failures,
            "last_error": self.last_error,
            "failure_kind": self.failure_kind,
            "config": self.config,
            "timezone": self.timezone,
            "delivery_channel": self.delivery_channel,
            "delivery_target": self.delivery_target,
            "delivery_target_ref": self.delivery_target_ref,
            "delivery_target_label": self.delivery_target_label,
            "delivery_format": self.delivery_format,
            "protect_pdf": self.protect_pdf,
            "delivery": self.delivery.to_dict(),
            "last_verdict": self.last_verdict.to_dict() if self.last_verdict else None,
        }

    @classmethod
    def from_dict(cls, data: Dict[str, Any]) -> "ScheduledResearchJob":
        """Reconstruct a job from a plain dict.

        Args:
            data: A raw dict as produced by :meth:`to_dict`.

        Returns:
            The reconstructed ``ScheduledResearchJob``.

        Dicts written before scheduler unification lack ``executor_kind`` and
        ``internal_callable``; both default to the prompt executor, so old
        files load unchanged.

        Raises:
            KeyError: If a required field is missing.
            TypeError: If a field has the wrong type.
            ValueError: If ``status`` is not a recognized ``JobStatus`` value,
                or ``source_type`` / ``executor_kind`` is outside its domain,
                or an ``internal`` job names no ``internal_callable``.
        """
        job_id = data["id"]
        prompt = data["prompt"]
        schedule = data["schedule"]
        if not isinstance(job_id, str) or not isinstance(prompt, str) or not isinstance(schedule, str):
            raise TypeError("'id', 'prompt', and 'schedule' must be strings")
        next_run_at = data["next_run_at"]
        created_at = data["created_at"]
        if not isinstance(next_run_at, int) or not isinstance(created_at, int):
            raise TypeError("'next_run_at' and 'created_at' must be integers (epoch ms)")
        last_run_at = data.get("last_run_at")
        if last_run_at is not None and not isinstance(last_run_at, int):
            raise TypeError("'last_run_at' must be an integer (epoch ms) or null")
        consecutive_failures = data.get("consecutive_failures", 0)
        if (
            isinstance(consecutive_failures, bool)
            or not isinstance(consecutive_failures, int)
            or consecutive_failures < 0
        ):
            raise TypeError("'consecutive_failures' must be a non-negative integer")
        last_error = data.get("last_error")
        failure_kind = data.get("failure_kind")
        if last_error is not None and not isinstance(last_error, str):
            raise TypeError("'last_error' must be a string or null")
        if failure_kind is not None and failure_kind not in {"dispatch", "schedule"}:
            raise ValueError("'failure_kind' must be 'dispatch', 'schedule', or null")
        # Never raises: the store quarantines the whole file when a single
        # record fails to load, so an unusable timezone value degrades that
        # one job to UTC — the semantics it had before the field existed —
        # instead of taking every other job down with it. Absent, blank, and
        # non-string values all normalize to None.
        raw_tz = data.get("timezone")
        tz = raw_tz if isinstance(raw_tz, str) and raw_tz.strip() else None
        if raw_tz is not None and tz is None:
            logger.warning(
                "scheduled research job %s has an unusable timezone %r; "
                "evaluating its schedule in UTC",
                job_id,
                raw_tz,
            )
        status = JobStatus(data["status"])
        title = data.get("title", "")
        source_type = data.get("source_type", "prompt")
        playbook_slug = data.get("playbook_slug")
        end_at = data.get("end_at")
        if not isinstance(title, str):
            raise TypeError("'title' must be a string")
        if source_type not in {"prompt", "playbook", "system"}:
            raise ValueError("'source_type' must be 'prompt', 'playbook', or 'system'")
        # Pre-unification dicts carry neither key; both default to the prompt
        # executor. Unknown or contradictory values are REJECTED rather than
        # degraded: a misspelled executor must not silently fall back to
        # dispatching the (possibly empty) prompt.
        executor_kind = data.get("executor_kind", "prompt")
        internal_callable = data.get("internal_callable")
        if not is_executor_kind(executor_kind):
            raise ValueError("'executor_kind' must be 'prompt' or 'internal'")
        if internal_callable is not None and not isinstance(internal_callable, str):
            raise TypeError("'internal_callable' must be a string or null")
        if executor_kind == "internal" and not internal_callable:
            raise ValueError(
                "'executor_kind' 'internal' requires 'internal_callable' "
                "(a registry key name, not an import path)"
            )
        if playbook_slug is not None and not isinstance(playbook_slug, str):
            raise TypeError("'playbook_slug' must be a string or null")
        if end_at is not None and (isinstance(end_at, bool) or not isinstance(end_at, int)):
            raise TypeError("'end_at' must be an integer (epoch ms) or null")
        raw_config = data.get("config")
        config: Dict[str, Any] = raw_config if isinstance(raw_config, dict) else {}
        if contains_pdf_password(config):
            raise ValueError("scheduled research config must not contain pdf_password")
        delivery_channel = data.get("delivery_channel")
        delivery_target = data.get("delivery_target")
        delivery_target_ref = data.get("delivery_target_ref")
        delivery_target_label = data.get("delivery_target_label")
        delivery_format = data.get("delivery_format")
        if delivery_format not in {None, "html", "pdf"}:
            raise ValueError("'delivery_format' must be 'html', 'pdf', or null")
        protect_pdf = data.get("protect_pdf", False)
        if not isinstance(protect_pdf, bool):
            raise TypeError("'protect_pdf' must be a boolean")
        if protect_pdf and (delivery_channel != "email" or delivery_format != "pdf"):
            raise ValueError("'protect_pdf' requires PDF email delivery")
        for name, value in (
            ("delivery_channel", delivery_channel),
            ("delivery_target", delivery_target),
            ("delivery_target_ref", delivery_target_ref),
            ("delivery_target_label", delivery_target_label),
        ):
            if value is not None and not isinstance(value, str):
                raise TypeError(f"'{name}' must be a string or null")
        return cls(
            id=job_id,
            prompt=prompt,
            schedule=schedule,
            title=title,
            source_type=source_type,
            playbook_slug=playbook_slug,
            executor_kind=executor_kind,
            internal_callable=internal_callable,
            end_at=end_at,
            next_run_at=next_run_at,
            status=status,
            created_at=created_at,
            last_run_at=last_run_at,
            consecutive_failures=consecutive_failures,
            last_error=last_error,
            failure_kind=failure_kind,
            config=config,
            timezone=tz,
            delivery_channel=delivery_channel,
            delivery_target=delivery_target,
            delivery_target_ref=delivery_target_ref,
            delivery_target_label=delivery_target_label,
            delivery_format=delivery_format,
            protect_pdf=protect_pdf,
            delivery=DeliveryRecord.from_dict(data.get("delivery")),
            last_verdict=_verdict_record_or_none(data.get("last_verdict"), job_id),
        )