agentexec 0.1.0__py3-none-any.whl

agentexec/__init__.py

@@ -0,0 +1,73 @@
+"""Agent Runner - Production-ready orchestration for OpenAI Agents.
+
+This library provides:
+- Background worker pool with Redis-backed task queue
+- Activity tracking with pluggable storage backends
+- OpenAI Agents SDK runner with max turns recovery
+- Coordination primitives (counters, locks, barriers)
+- Workflow engine for complex agent orchestration
+
+Example:
+    from agents import Agent
+    import agentexec as ax
+
+
+    # create a pool to manage background tasks
+    pool = ax.Pool()
+
+    # register a background task
+    @pool.task("research_company")
+    async def research_company(payload: dict, agent_id: str):
+        runner = ax.OpenAIRunner(
+            status_tracking=True,
+            max_turns=5,
+        )
+        agent = Agent(tools=[runner.tools.report_status], ...)
+        result = await runner.run(
+            agent,
+            input=f"Research {payload['company_name']}",
+        )
+        return result
+
+    # fork and start the worker pool
+    pool.start()
+
+    # queue a task from anywhere
+    task = ax.Task(task_type="research_company", payload={"company_name": "Acme Corp"})
+    agent_id = ax.enqueue(task)
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from agentexec.config import CONF
+from agentexec.core.models import Base
+from agentexec.core.queue import Priority, dequeue, enqueue
+from agentexec.core.task import Task, TaskHandler, TaskHandlerKwargs
+from agentexec.core.worker import WorkerPool
+from agentexec.runners import BaseAgentRunner
+
+try:
+    __version__ = version("agent-runner")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev"
+
+__all__ = [
+    "CONF",
+    "Base",
+    "WorkerPool",
+    "TaskHandler",
+    "Task",
+    "TaskHandlerKwargs",
+    "Priority",
+    "enqueue",
+    "dequeue",
+    "BaseAgentRunner",
+]
+
+# OpenAI runner is only available if agents package is installed
+try:
+    from agentexec.runners import OpenAIRunner
+
+    __all__.append("OpenAIRunner")
+except ImportError:
+    pass

agentexec/activity/__init__.py

@@ -0,0 +1,50 @@
+"""Activity tracking for agent execution."""
+
+from agentexec.activity import tracker as activity
+from agentexec.activity.models import Activity, ActivityLog, Status
+from agentexec.activity.schemas import (
+    ActivityDetailSchema,
+    ActivityListItemSchema,
+    ActivityListSchema,
+    ActivityLogSchema,
+)
+from agentexec.activity.tracker import (
+    cancel_pending,
+    complete,
+    create,
+    detail,
+    error,
+    generate_agent_id,
+    list,
+    normalize_agent_id,
+    update,
+)
+
+__all__ = [
+    # Namespace for activity tracking
+    "activity",
+    # Models
+    "Activity",
+    "ActivityLog",
+    "Status",
+    # Schemas
+    "ActivityLogSchema",
+    "ActivityDetailSchema",
+    "ActivityListItemSchema",
+    "ActivityListSchema",
+    # UUID Helpers
+    "generate_agent_id",
+    "normalize_agent_id",
+    # Lifecycle API
+    "create",
+    "update",
+    "complete",
+    "error",
+    "cancel_pending",
+    # Query API
+    "list",
+    "detail",
+]
+
+# Users manage their own database setup with SQLAlchemy
+# See examples/fastapi-app/ for a complete example

agentexec/activity/models.py

@@ -0,0 +1,294 @@
+from __future__ import annotations
+from enum import Enum as PyEnum
+import uuid
+from datetime import UTC, datetime
+
+from sqlalchemy import (
+    DateTime,
+    Enum,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    Uuid,
+    case,
+    func,
+    insert,
+    select,
+)
+from sqlalchemy.engine import RowMapping
+from sqlalchemy.orm import Mapped, Session, aliased, mapped_column, relationship, declared_attr
+
+from agentexec.config import CONF
+from agentexec.core.models import Base
+
+
+class Status(str, PyEnum):
+    """Agent execution status."""
+
+    QUEUED = "queued"
+    RUNNING = "running"
+    COMPLETE = "complete"
+    ERROR = "error"
+    CANCELED = "canceled"
+
+
+class Activity(Base):
+    """Tracks background agent execution sessions.
+
+    Each record represents a single agent run. The current status is inferred
+    from the latest log message.
+    """
+
+    @declared_attr.directive
+    def __tablename__(cls) -> str:
+        return f"{CONF.table_prefix}activity"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid, primary_key=True, default=uuid.uuid4)
+    agent_id: Mapped[uuid.UUID] = mapped_column(Uuid, nullable=False, unique=True, index=True)
+    agent_type: Mapped[str | None] = mapped_column(String(255), nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+    )
+    updated_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+        onupdate=lambda: datetime.now(UTC),
+    )
+
+    logs: Mapped[list[ActivityLog]] = relationship(
+        "ActivityLog",
+        back_populates="activity",
+        cascade="all, delete-orphan",
+        order_by="ActivityLog.created_at",
+    )
+
+    @classmethod
+    def append_log(
+        cls,
+        session: Session,
+        agent_id: uuid.UUID,
+        message: str,
+        status: Status,
+        completion_percentage: int | None = None,
+    ) -> None:
+        """Append a log entry to the activity for the given agent_id.
+
+        This uses a single query to look up the activity_id and insert the log,
+        avoiding the need to load the Activity record first.
+
+        Args:
+            session: SQLAlchemy session
+            agent_id: The agent_id to append the log to
+            message: Log message
+            status: Current status of the agent
+            completion_percentage: Optional completion percentage (0-100)
+
+        Raises:
+            ValueError: If agent_id not found (foreign key constraint will fail)
+        """
+        # Scalar subquery to get activity.id from agent_id
+        activity_id_subq = select(cls.id).where(cls.agent_id == agent_id).scalar_subquery()
+
+        # Insert the log using the subquery for activity_id
+        stmt = insert(ActivityLog).values(
+            activity_id=activity_id_subq,
+            message=message,
+            status=status,
+            completion_percentage=completion_percentage,
+        )
+
+        try:
+            session.execute(stmt)
+            session.commit()
+        except Exception as e:
+            session.rollback()
+            raise ValueError(f"Failed to append log for agent_id {agent_id}") from e
+
+    @classmethod
+    def get_by_agent_id(
+        cls,
+        session: Session,
+        agent_id: str | uuid.UUID,
+    ) -> Activity | None:
+        """Get an activity by agent_id.
+
+        Args:
+            session: SQLAlchemy session
+            agent_id: The agent_id to look up (string or UUID)
+
+        Returns:
+            Activity object or None if not found
+
+        Example:
+            activity = Activity.get_by_agent_id(session, "abc-123")
+            # Or with UUID object
+            activity = Activity.get_by_agent_id(session, uuid.UUID("abc-123..."))
+            if activity:
+                print(f"Found activity: {activity.agent_type}")
+        """
+        # Normalize to UUID if string
+        if isinstance(agent_id, str):
+            agent_id = uuid.UUID(agent_id)
+        return session.query(cls).filter_by(agent_id=agent_id).first()
+
+    @classmethod
+    def get_list(
+        cls,
+        session: Session,
+        page: int = 1,
+        page_size: int = 50,
+    ) -> list[RowMapping]:
+        """Get a paginated list of activities with summary information.
+
+        Args:
+            session: SQLAlchemy session to use for the query
+            page: Page number (1-indexed)
+            page_size: Number of items per page
+
+        Returns:
+            List of RowMapping objects (dict-like) with keys matching ActivitySummarySchema:
+            agent_id, agent_type, latest_log_message, status, latest_log_timestamp,
+            completion_percentage, started_at
+
+        Example:
+            results = Activity.get_list(session, page=1, page_size=20)
+            for row in results:
+                print(f"{row['agent_id']}: {row['latest_log_message']}")
+        """
+        # Subquery to get the latest log for each agent
+        latest_log_subq = select(
+            ActivityLog.activity_id,
+            ActivityLog.message,
+            ActivityLog.status,
+            ActivityLog.created_at,
+            ActivityLog.completion_percentage,
+            func.row_number()
+            .over(
+                partition_by=ActivityLog.activity_id,
+                order_by=ActivityLog.created_at.desc(),
+            )
+            .label("rn"),
+        ).subquery()
+
+        # Subquery to get start time (first log timestamp)
+        started_at_subq = (
+            select(
+                ActivityLog.activity_id,
+                func.min(ActivityLog.created_at).label("started_at"),
+            )
+            .group_by(ActivityLog.activity_id)
+            .subquery()
+        )
+
+        # Alias for the subqueries
+        latest_log = aliased(latest_log_subq)
+        started_at = aliased(started_at_subq)
+
+        # Build base query - select only the columns we need with aliases matching schema
+        query = (
+            select(
+                cls.agent_id,
+                cls.agent_type,
+                latest_log.c.message.label("latest_log_message"),
+                latest_log.c.status,
+                latest_log.c.created_at.label("latest_log_timestamp"),
+                latest_log.c.completion_percentage,
+                started_at.c.started_at,
+            )
+            .outerjoin(
+                latest_log,
+                (cls.id == latest_log.c.activity_id) & (latest_log.c.rn == 1),
+            )
+            .outerjoin(started_at, cls.id == started_at.c.activity_id)
+        )
+
+        # Custom ordering: active agents (running, queued) at the top
+        is_active = case(
+            (latest_log.c.status.in_([Status.RUNNING, Status.QUEUED]), 0),
+            else_=1,
+        )
+        active_priority = case(
+            (latest_log.c.status == Status.RUNNING, 1),
+            (latest_log.c.status == Status.QUEUED, 2),
+            else_=3,
+        )
+        query = query.order_by(
+            is_active, active_priority, started_at.c.started_at.desc().nullslast()
+        )
+
+        # Apply pagination and execute
+        offset = (page - 1) * page_size
+        return list(session.execute(query.offset(offset).limit(page_size)).mappings().all())
+
+    @classmethod
+    def get_pending_ids(cls, session: Session) -> list[uuid.UUID]:
+        """Get agent_ids for all activities with QUEUED or RUNNING status.
+
+        Args:
+            session: SQLAlchemy session to use for the query
+
+        Returns:
+            List of agent_id UUIDs for pending (queued or running) activities
+
+        Example:
+            pending_ids = Activity.get_pending_ids(session)
+            for agent_id in pending_ids:
+                print(f"Pending agent: {agent_id}")
+        """
+        # Subquery to get the latest log status for each activity
+        latest_log_subq = select(
+            ActivityLog.activity_id,
+            ActivityLog.status,
+            func.row_number()
+            .over(
+                partition_by=ActivityLog.activity_id,
+                order_by=ActivityLog.created_at.desc(),
+            )
+            .label("rn"),
+        ).subquery()
+
+        # Query for agent_ids where latest status is queued or running
+        result = (
+            session.query(cls.agent_id)
+            .join(
+                latest_log_subq,
+                (cls.id == latest_log_subq.c.activity_id) & (latest_log_subq.c.rn == 1),
+            )
+            .filter(latest_log_subq.c.status.in_([Status.QUEUED, Status.RUNNING]))
+            .all()
+        )
+
+        # Extract UUIDs from result tuples
+        return [agent_id for (agent_id,) in result]
+
+
+class ActivityLog(Base):
+    """Individual log messages from background agents.
+
+    Each log entry represents a single update/message from an agent
+    during its execution, including the agent's status at that point in time.
+    """
+
+    @declared_attr.directive
+    def __tablename__(cls) -> str:
+        return f"{CONF.table_prefix}activity_log"
+
+    id: Mapped[uuid.UUID] = mapped_column(Uuid, primary_key=True, default=uuid.uuid4)
+    activity_id: Mapped[uuid.UUID] = mapped_column(
+        Uuid, ForeignKey("agentexec_activity.id"), nullable=False, index=True
+    )
+    message: Mapped[str] = mapped_column(Text, nullable=False)
+    status: Mapped[Status] = mapped_column(Enum(Status), nullable=False, index=True)
+    completion_percentage: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    created_at: Mapped[datetime] = mapped_column(
+        DateTime(timezone=True),
+        nullable=False,
+        default=lambda: datetime.now(UTC),
+    )
+
+    # Relationship back to activity
+    activity: Mapped[Activity] = relationship("Activity", back_populates="logs")

agentexec/activity/schemas.py

@@ -0,0 +1,70 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field, computed_field
+
+from agentexec.activity.models import Status
+
+
+class ActivityLogSchema(BaseModel):
+    """Schema for an agent activity log entry."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    message: str
+    status: Status
+    completion_percentage: int = 0
+    created_at: datetime
+
+
+class ActivityDetailSchema(BaseModel):
+    """Schema for an agent activity record with optional logs."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: uuid.UUID
+    agent_id: uuid.UUID
+    agent_type: str
+    created_at: datetime
+    updated_at: datetime
+    logs: list[ActivityLogSchema] = Field(default_factory=list)
+
+
+class ActivityListItemSchema(BaseModel):
+    """Lightweight summary of agent activity showing only latest update.
+
+    Note: Elapsed time can be calculated on the frontend as:
+    latest_log_timestamp - started_at
+    """
+
+    model_config = ConfigDict(from_attributes=True)
+
+    agent_id: uuid.UUID
+    agent_type: str
+    status: Status
+    latest_log_message: str | None = None
+    latest_log_timestamp: datetime | None = None
+    completion_percentage: int = 0
+    started_at: datetime | None = None
+
+    @computed_field
+    def elapsed_time_seconds(self) -> int:
+        if self.latest_log_timestamp and self.started_at:
+            return int((self.latest_log_timestamp - self.started_at).total_seconds())
+        return 0
+
+
+class ActivityListSchema(BaseModel):
+    """Paginated list of activity summaries."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    items: list[ActivityListItemSchema]
+    total: int
+    page: int
+    page_size: int
+
+    @computed_field
+    def total_pages(self) -> int:
+        return (self.total + self.page_size - 1) // self.page_size