PraisonAI 3.0.0__py3-none-any.whl

praisonai/jobs/models.py

@@ -0,0 +1,230 @@
+"""
+Job Models for PraisonAI Async Jobs API.
+
+Defines the data structures for job submission, status, and results.
+"""
+
+import uuid
+from enum import Enum
+from typing import Optional, Dict, Any, List
+from datetime import datetime
+from pydantic import BaseModel, Field
+
+
+class JobStatus(str, Enum):
+    """Status of a job."""
+    QUEUED = "queued"
+    RUNNING = "running"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    CANCELLED = "cancelled"
+
+
+class JobSubmitRequest(BaseModel):
+    """Request body for submitting a new job."""
+    prompt: str = Field(..., description="The prompt or task for the agent")
+    agent_file: Optional[str] = Field(None, description="Path to agents.yaml file")
+    agent_yaml: Optional[str] = Field(None, description="Inline agent YAML configuration")
+    recipe_name: Optional[str] = Field(None, description="Recipe name to execute (mutually exclusive with agent_file)")
+    recipe_config: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Recipe configuration overrides")
+    framework: Optional[str] = Field("praisonai", description="Framework to use (praisonai, crewai, autogen)")
+    config: Optional[Dict[str, Any]] = Field(default_factory=dict, description="Additional configuration")
+    webhook_url: Optional[str] = Field(None, description="URL to POST results when complete")
+    timeout: Optional[int] = Field(3600, description="Timeout in seconds (default: 1 hour)")
+    session_id: Optional[str] = Field(None, description="Session ID for conversation continuity")
+    idempotency_key: Optional[str] = Field(None, description="Idempotency key to prevent duplicate submissions")
+    idempotency_scope: Optional[str] = Field("none", description="Idempotency scope: none, session, global")
+
+
+class JobSubmitResponse(BaseModel):
+    """Response after submitting a job."""
+    job_id: str = Field(..., description="Unique job identifier")
+    status: JobStatus = Field(..., description="Current job status")
+    created_at: datetime = Field(..., description="Job creation timestamp")
+    poll_url: str = Field(..., description="URL to poll for status")
+    stream_url: str = Field(..., description="URL for SSE streaming")
+
+
+class JobProgress(BaseModel):
+    """Progress information for a running job."""
+    percentage: float = Field(0.0, ge=0.0, le=100.0, description="Completion percentage")
+    current_step: Optional[str] = Field(None, description="Current step description")
+    steps_completed: int = Field(0, description="Number of steps completed")
+    steps_total: Optional[int] = Field(None, description="Total number of steps")
+
+
+class JobStatusResponse(BaseModel):
+    """Response for job status query."""
+    job_id: str = Field(..., description="Unique job identifier")
+    status: JobStatus = Field(..., description="Current job status")
+    progress: JobProgress = Field(default_factory=JobProgress, description="Progress information")
+    created_at: datetime = Field(..., description="Job creation timestamp")
+    started_at: Optional[datetime] = Field(None, description="When job started running")
+    completed_at: Optional[datetime] = Field(None, description="When job completed")
+    agent_id: Optional[str] = Field(None, description="Current agent ID")
+    run_id: Optional[str] = Field(None, description="Run ID for tracing")
+    session_id: Optional[str] = Field(None, description="Session ID")
+    error: Optional[str] = Field(None, description="Error message if failed")
+    retry_after: Optional[int] = Field(None, description="Suggested seconds before next poll")
+
+
+class JobResultResponse(BaseModel):
+    """Response for job result query."""
+    job_id: str = Field(..., description="Unique job identifier")
+    status: JobStatus = Field(..., description="Final job status")
+    result: Optional[Any] = Field(None, description="Job result/output")
+    result_url: Optional[str] = Field(None, description="URL to fetch large results")
+    metrics: Optional[Dict[str, Any]] = Field(None, description="Execution metrics")
+    created_at: datetime = Field(..., description="Job creation timestamp")
+    started_at: Optional[datetime] = Field(None, description="When job started running")
+    completed_at: Optional[datetime] = Field(None, description="When job completed")
+    duration_seconds: Optional[float] = Field(None, description="Total execution time")
+    error: Optional[str] = Field(None, description="Error message if failed")
+
+
+class JobListResponse(BaseModel):
+    """Response for listing jobs."""
+    jobs: List[JobStatusResponse] = Field(..., description="List of jobs")
+    total: int = Field(..., description="Total number of jobs matching filter")
+    page: int = Field(1, description="Current page number")
+    page_size: int = Field(20, description="Number of jobs per page")
+
+
+class Job(BaseModel):
+    """Internal job representation with full state."""
+    id: str = Field(default_factory=lambda: f"run_{uuid.uuid4().hex[:12]}")
+    status: JobStatus = Field(default=JobStatus.QUEUED)
+    
+    # Request data
+    prompt: str = Field(...)
+    agent_file: Optional[str] = Field(None)
+    agent_yaml: Optional[str] = Field(None)
+    recipe_name: Optional[str] = Field(None)
+    recipe_config: Dict[str, Any] = Field(default_factory=dict)
+    framework: str = Field("praisonai")
+    config: Dict[str, Any] = Field(default_factory=dict)
+    webhook_url: Optional[str] = Field(None)
+    timeout: int = Field(3600)
+    session_id: Optional[str] = Field(None)
+    idempotency_key: Optional[str] = Field(None)
+    idempotency_scope: str = Field("none")
+    
+    # Progress tracking
+    progress_percentage: float = Field(0.0)
+    progress_step: Optional[str] = Field(None)
+    steps_completed: int = Field(0)
+    steps_total: Optional[int] = Field(None)
+    
+    # Attribution
+    agent_id: Optional[str] = Field(None)
+    run_id: Optional[str] = Field(None)
+    
+    # Timestamps
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    started_at: Optional[datetime] = Field(None)
+    completed_at: Optional[datetime] = Field(None)
+    
+    # Result
+    result: Optional[Any] = Field(None)
+    error: Optional[str] = Field(None)
+    metrics: Optional[Dict[str, Any]] = Field(None)
+    
+    # Internal
+    _cancel_requested: bool = False
+    
+    @property
+    def duration_seconds(self) -> Optional[float]:
+        """Calculate job duration."""
+        if self.started_at is None:
+            return None
+        end_time = self.completed_at or datetime.utcnow()
+        return (end_time - self.started_at).total_seconds()
+    
+    @property
+    def is_terminal(self) -> bool:
+        """Check if job is in a terminal state."""
+        return self.status in (JobStatus.SUCCEEDED, JobStatus.FAILED, JobStatus.CANCELLED)
+    
+    def to_status_response(self, base_url: str = "") -> JobStatusResponse:
+        """Convert to status response."""
+        retry_after = None
+        if self.status == JobStatus.QUEUED:
+            retry_after = 2
+        elif self.status == JobStatus.RUNNING:
+            retry_after = 5
+        
+        return JobStatusResponse(
+            job_id=self.id,
+            status=self.status,
+            progress=JobProgress(
+                percentage=self.progress_percentage,
+                current_step=self.progress_step,
+                steps_completed=self.steps_completed,
+                steps_total=self.steps_total
+            ),
+            created_at=self.created_at,
+            started_at=self.started_at,
+            completed_at=self.completed_at,
+            agent_id=self.agent_id,
+            run_id=self.run_id,
+            session_id=self.session_id,
+            error=self.error,
+            retry_after=retry_after
+        )
+    
+    def to_result_response(self) -> JobResultResponse:
+        """Convert to result response."""
+        return JobResultResponse(
+            job_id=self.id,
+            status=self.status,
+            result=self.result,
+            result_url=None,  # For large results, would be set
+            metrics=self.metrics,
+            created_at=self.created_at,
+            started_at=self.started_at,
+            completed_at=self.completed_at,
+            duration_seconds=self.duration_seconds,
+            error=self.error
+        )
+    
+    def start(self):
+        """Mark job as started."""
+        self.status = JobStatus.RUNNING
+        self.started_at = datetime.utcnow()
+    
+    def succeed(self, result: Any, metrics: Optional[Dict[str, Any]] = None):
+        """Mark job as succeeded."""
+        self.status = JobStatus.SUCCEEDED
+        self.result = result
+        self.metrics = metrics
+        self.completed_at = datetime.utcnow()
+        self.progress_percentage = 100.0
+    
+    def fail(self, error: str):
+        """Mark job as failed."""
+        self.status = JobStatus.FAILED
+        self.error = error
+        self.completed_at = datetime.utcnow()
+    
+    def cancel(self):
+        """Mark job as cancelled."""
+        self.status = JobStatus.CANCELLED
+        self.completed_at = datetime.utcnow()
+        self._cancel_requested = True
+    
+    def update_progress(
+        self,
+        percentage: Optional[float] = None,
+        step: Optional[str] = None,
+        steps_completed: Optional[int] = None,
+        steps_total: Optional[int] = None
+    ):
+        """Update job progress."""
+        if percentage is not None:
+            self.progress_percentage = min(max(percentage, 0.0), 100.0)
+        if step is not None:
+            self.progress_step = step
+        if steps_completed is not None:
+            self.steps_completed = steps_completed
+        if steps_total is not None:
+            self.steps_total = steps_total

praisonai/jobs/router.py

@@ -0,0 +1,314 @@
+"""
+FastAPI Router for PraisonAI Async Jobs API.
+
+Provides HTTP endpoints for job management.
+"""
+
+import asyncio
+import logging
+from typing import Optional
+from datetime import datetime
+
+from fastapi import APIRouter, HTTPException, Header, Request, Query, Response
+from sse_starlette.sse import EventSourceResponse
+
+from .models import (
+    Job,
+    JobStatus,
+    JobSubmitRequest,
+    JobSubmitResponse,
+    JobStatusResponse,
+    JobResultResponse,
+    JobListResponse
+)
+from .store import JobStore
+from .executor import JobExecutor
+
+logger = logging.getLogger(__name__)
+
+
+def create_router(store: JobStore, executor: JobExecutor) -> APIRouter:
+    """
+    Create the jobs API router.
+    
+    Args:
+        store: Job storage backend
+        executor: Job executor
+        
+    Returns:
+        FastAPI router with all endpoints
+    """
+    router = APIRouter(prefix="/api/v1/runs", tags=["jobs"])
+    
+    @router.post("", response_model=JobSubmitResponse, status_code=202)
+    async def submit_job(
+        request: Request,
+        response: Response,
+        body: JobSubmitRequest,
+        idempotency_key: Optional[str] = Header(None, alias="Idempotency-Key")
+    ):
+        """
+        Submit a new job for execution.
+        
+        Returns 202 Accepted with job ID and status URLs.
+        Headers returned:
+        - Location: URL to poll for status
+        - Retry-After: Suggested seconds before first poll (default: 2)
+        
+        If an Idempotency-Key header is provided and a job with that key
+        already exists, returns the existing job instead of creating a new one.
+        """
+        # Check idempotency key
+        effective_key = idempotency_key or body.idempotency_key
+        if effective_key:
+            existing = await store.get_by_idempotency_key(effective_key)
+            if existing:
+                logger.info(f"Returning existing job for idempotency key: {effective_key}")
+                base_url = str(request.base_url).rstrip("/")
+                poll_url = f"{base_url}/api/v1/runs/{existing.id}"
+                response.headers["Location"] = poll_url
+                response.headers["Retry-After"] = "2"
+                return JobSubmitResponse(
+                    job_id=existing.id,
+                    status=existing.status,
+                    created_at=existing.created_at,
+                    poll_url=poll_url,
+                    stream_url=f"{base_url}/api/v1/runs/{existing.id}/stream"
+                )
+        
+        # Create new job
+        job = Job(
+            prompt=body.prompt,
+            agent_file=body.agent_file,
+            agent_yaml=body.agent_yaml,
+            framework=body.framework or "praisonai",
+            config=body.config or {},
+            webhook_url=body.webhook_url,
+            timeout=body.timeout or 3600,
+            session_id=body.session_id,
+            idempotency_key=effective_key
+        )
+        
+        # Submit for execution
+        await executor.submit(job)
+        
+        # Build response with Location and Retry-After headers (RFC best practice)
+        base_url = str(request.base_url).rstrip("/")
+        poll_url = f"{base_url}/api/v1/runs/{job.id}"
+        response.headers["Location"] = poll_url
+        response.headers["Retry-After"] = "2"
+        
+        return JobSubmitResponse(
+            job_id=job.id,
+            status=job.status,
+            created_at=job.created_at,
+            poll_url=poll_url,
+            stream_url=f"{base_url}/api/v1/runs/{job.id}/stream"
+        )
+    
+    @router.get("", response_model=JobListResponse)
+    async def list_jobs(
+        status: Optional[str] = Query(None, description="Filter by status"),
+        session_id: Optional[str] = Query(None, description="Filter by session ID"),
+        page: int = Query(1, ge=1, description="Page number"),
+        page_size: int = Query(20, ge=1, le=100, description="Jobs per page")
+    ):
+        """
+        List jobs with optional filters.
+        """
+        # Parse status filter
+        status_filter = None
+        if status:
+            try:
+                status_filter = JobStatus(status)
+            except ValueError:
+                raise HTTPException(
+                    status_code=400,
+                    detail=f"Invalid status: {status}. Valid values: {[s.value for s in JobStatus]}"
+                )
+        
+        # Get jobs
+        offset = (page - 1) * page_size
+        jobs = await store.list_jobs(
+            status=status_filter,
+            session_id=session_id,
+            limit=page_size,
+            offset=offset
+        )
+        
+        total = await store.count(status=status_filter, session_id=session_id)
+        
+        return JobListResponse(
+            jobs=[job.to_status_response() for job in jobs],
+            total=total,
+            page=page,
+            page_size=page_size
+        )
+    
+    @router.get("/{job_id}", response_model=JobStatusResponse)
+    async def get_job_status(job_id: str):
+        """
+        Get the status of a job.
+        
+        Returns current status, progress, and timing information.
+        """
+        job = await store.get(job_id)
+        if not job:
+            raise HTTPException(status_code=404, detail=f"Job not found: {job_id}")
+        
+        return job.to_status_response()
+    
+    @router.get("/{job_id}/result", response_model=JobResultResponse)
+    async def get_job_result(job_id: str):
+        """
+        Get the result of a completed job.
+        
+        Returns 409 Conflict if job is not yet complete.
+        """
+        job = await store.get(job_id)
+        if not job:
+            raise HTTPException(status_code=404, detail=f"Job not found: {job_id}")
+        
+        if not job.is_terminal:
+            raise HTTPException(
+                status_code=409,
+                detail=f"Job is not complete. Current status: {job.status.value}"
+            )
+        
+        return job.to_result_response()
+    
+    @router.post("/{job_id}/cancel", response_model=JobStatusResponse)
+    async def cancel_job(job_id: str):
+        """
+        Cancel a running job.
+        
+        Returns 409 Conflict if job is already complete.
+        """
+        job = await store.get(job_id)
+        if not job:
+            raise HTTPException(status_code=404, detail=f"Job not found: {job_id}")
+        
+        if job.is_terminal:
+            raise HTTPException(
+                status_code=409,
+                detail=f"Job is already complete. Status: {job.status.value}"
+            )
+        
+        success = await executor.cancel(job_id)
+        if not success:
+            raise HTTPException(status_code=500, detail="Failed to cancel job")
+        
+        # Refresh job state
+        job = await store.get(job_id)
+        return job.to_status_response()
+    
+    @router.delete("/{job_id}", status_code=204)
+    async def delete_job(job_id: str):
+        """
+        Delete a job.
+        
+        Only completed jobs can be deleted.
+        """
+        job = await store.get(job_id)
+        if not job:
+            raise HTTPException(status_code=404, detail=f"Job not found: {job_id}")
+        
+        if not job.is_terminal:
+            raise HTTPException(
+                status_code=409,
+                detail="Cannot delete a running job. Cancel it first."
+            )
+        
+        await store.delete(job_id)
+    
+    @router.get("/{job_id}/stream")
+    async def stream_job(job_id: str):
+        """
+        Stream job progress via Server-Sent Events (SSE).
+        
+        Events:
+        - status: Job status updates
+        - progress: Progress percentage updates
+        - result: Final result (when complete)
+        - error: Error message (when failed)
+        """
+        job = await store.get(job_id)
+        if not job:
+            raise HTTPException(status_code=404, detail=f"Job not found: {job_id}")
+        
+        async def event_generator():
+            """Generate SSE events for job progress."""
+            last_status = None
+            last_progress = -1
+            
+            # Register for progress updates
+            progress_queue = asyncio.Queue()
+            
+            async def on_progress(updated_job: Job):
+                await progress_queue.put(updated_job)
+            
+            executor.register_progress_callback(job_id, on_progress)
+            
+            try:
+                while True:
+                    # Get current job state
+                    current_job = await store.get(job_id)
+                    if not current_job:
+                        yield {
+                            "event": "error",
+                            "data": '{"error": "Job not found"}'
+                        }
+                        break
+                    
+                    # Send status update if changed
+                    if current_job.status != last_status:
+                        last_status = current_job.status
+                        yield {
+                            "event": "status",
+                            "data": f'{{"status": "{current_job.status.value}", "job_id": "{job_id}"}}'
+                        }
+                    
+                    # Send progress update if changed
+                    if current_job.progress_percentage != last_progress:
+                        last_progress = current_job.progress_percentage
+                        yield {
+                            "event": "progress",
+                            "data": f'{{"percentage": {current_job.progress_percentage}, "step": "{current_job.progress_step or ""}"}}'
+                        }
+                    
+                    # Check if complete
+                    if current_job.is_terminal:
+                        if current_job.status == JobStatus.SUCCEEDED:
+                            result_str = str(current_job.result).replace('"', '\\"')[:1000]
+                            yield {
+                                "event": "result",
+                                "data": f'{{"result": "{result_str}"}}'
+                            }
+                        elif current_job.status == JobStatus.FAILED:
+                            error_str = (current_job.error or "Unknown error").replace('"', '\\"')
+                            yield {
+                                "event": "error",
+                                "data": f'{{"error": "{error_str}"}}'
+                            }
+                        elif current_job.status == JobStatus.CANCELLED:
+                            yield {
+                                "event": "cancelled",
+                                "data": '{"message": "Job was cancelled"}'
+                            }
+                        break
+                    
+                    # Wait for next update or timeout
+                    try:
+                        await asyncio.wait_for(progress_queue.get(), timeout=5.0)
+                    except asyncio.TimeoutError:
+                        # Send heartbeat
+                        yield {
+                            "event": "heartbeat",
+                            "data": f'{{"timestamp": "{datetime.utcnow().isoformat()}"}}'
+                        }
+            finally:
+                executor.unregister_progress_callback(job_id)
+        
+        return EventSourceResponse(event_generator())
+    
+    return router