planar 0.5.0__py3-none-any.whl

planar/routers/human.py

@@ -0,0 +1,151 @@
+"""
+Human tasks API router for Planar workflows.
+
+This module provides API routes for managing human task instances,
+including task listing, completion, cancellation, and retrieval.
+"""
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from fastapi import APIRouter, Body, HTTPException, Query
+from pydantic import BaseModel
+
+from planar.human.human import (
+    HumanTask,
+    HumanTaskStatus,
+    cancel_human_task,
+    complete_human_task,
+    get_human_task,
+    get_human_tasks,
+)
+from planar.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+class CompleteTaskRequest(BaseModel):
+    """Request model for completing a human task."""
+
+    output_data: Dict[str, Any]
+    completed_by: Optional[str] = None
+
+
+class CancelTaskRequest(BaseModel):
+    """Request model for cancelling a human task."""
+
+    reason: str = "cancelled"
+    cancelled_by: Optional[str] = None
+
+
+def create_human_task_routes() -> APIRouter:
+    router = APIRouter(tags=["Human Tasks"])
+
+    """Register human task routes on the provided router and return it."""
+
+    @router.get("/", response_model=List[HumanTask])
+    async def list_human_tasks(
+        status: Optional[HumanTaskStatus] = None,
+        workflow_id: Optional[UUID] = None,
+        limit: int = Query(100, ge=1, le=1000),
+        offset: int = Query(0, ge=0),
+    ):
+        """
+        List human tasks with optional filtering.
+
+        Args:
+            status: Filter by task status
+            workflow_id: Filter by workflow ID
+            limit: Maximum number of tasks to return
+            offset: Pagination offset
+        """
+        try:
+            tasks = await get_human_tasks(
+                status=status,
+                workflow_id=workflow_id,
+                limit=limit,
+                offset=offset,
+            )
+            return tasks
+        except Exception as e:
+            logger.exception("error listing human tasks")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @router.get("/{task_id}", response_model=HumanTask)
+    async def get_task(task_id: UUID):
+        """
+        Get a human task by its ID.
+
+        Args:
+            task_id: The ID of the task to retrieve
+        """
+        task = await get_human_task(task_id)
+        if not task:
+            raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+
+        return task
+
+    @router.post("/{task_id}/complete", response_model=HumanTask)
+    async def complete_task(task_id: UUID, request: CompleteTaskRequest = Body(...)):
+        """
+        Complete a human task with the provided output data.
+
+        Args:
+            task_id: The ID of the task to complete
+            request: The completion data
+        """
+        try:
+            await complete_human_task(
+                task_id=task_id,
+                output_data=request.output_data,
+                completed_by=request.completed_by,
+            )
+
+            # Fetch the updated task to return
+            task = await get_human_task(task_id)
+            if not task:  # Should not happen if complete_human_task succeeded
+                raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+
+            logger.info("human task completed successfully", task_id=task_id)
+            return task
+        except ValueError as e:
+            logger.exception("valueerror completing task", task_id=task_id)
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            logger.exception("exception completing task", task_id=task_id)
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @router.post("/{task_id}/cancel", response_model=HumanTask)
+    async def cancel_task(task_id: UUID, request: CancelTaskRequest = Body(...)):
+        """
+        Cancel a pending human task.
+
+        Args:
+            task_id: The ID of the task to cancel
+            request: The cancellation details
+        """
+        try:
+            await cancel_human_task(
+                task_id=task_id,
+                reason=request.reason,
+                cancelled_by=request.cancelled_by,
+            )
+
+            # Fetch the updated task to return
+            task = await get_human_task(task_id)
+            if not task:  # Should not happen if cancel_human_task succeeded
+                logger.warning(
+                    "human task not found after cancellation attempt", task_id=task_id
+                )
+                raise HTTPException(status_code=404, detail=f"Task {task_id} not found")
+
+            logger.info("human task cancelled successfully", task_id=task_id)
+            return task
+        except ValueError as e:
+            logger.exception("valueerror cancelling task", task_id=task_id)
+            raise HTTPException(status_code=400, detail=str(e))
+        except Exception as e:
+            logger.exception("exception cancelling task", task_id=task_id)
+            raise HTTPException(status_code=500, detail=str(e))
+
+    return router

planar/routers/info.py

@@ -0,0 +1,131 @@
+from fastapi import APIRouter, Depends
+from pydantic import BaseModel
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlmodel import col, distinct, func, select
+
+from planar.human.models import HumanTask, HumanTaskStatus
+from planar.logging import get_logger
+from planar.object_config import ConfigurableObjectType, ObjectConfiguration
+from planar.session import get_session
+from planar.workflows.models import Workflow, WorkflowStatus
+
+logger = get_logger(__name__)
+
+
+class SystemInfo(BaseModel):
+    """Combined application information and system statistics"""
+
+    # App info
+    title: str
+    description: str
+
+    # System stats
+    total_workflow_runs: int = 0
+    completed_runs: int = 0
+    in_progress_runs: int = 0
+    pending_human_tasks: int = 0
+    active_agents: int = 0
+
+
+async def get_system_stats(session: AsyncSession = Depends(get_session)) -> dict:
+    """
+    Get system-wide statistics directly from the database.
+
+    This optimizes the calculation by doing aggregations at the database level
+    rather than fetching all records and calculating in the application.
+    """
+    try:
+        # Get workflow run counts
+        workflow_stats = await session.execute(
+            select(
+                func.count().label("total_runs"),
+                func.count(col(Workflow.id))
+                .filter(col(Workflow.status) == WorkflowStatus.SUCCEEDED)
+                .label("completed_runs"),
+                func.count(col(Workflow.id))
+                .filter(col(Workflow.status) == WorkflowStatus.PENDING)
+                .label("in_progress_runs"),
+            ).select_from(Workflow)
+        )
+        workflow_row = workflow_stats.one()
+
+        # Get pending human task count
+        human_task_query = await session.execute(
+            select(func.count())
+            .select_from(HumanTask)
+            .where(HumanTask.status == HumanTaskStatus.PENDING)
+        )
+        pending_tasks = human_task_query.scalar() or 0
+
+        # Get agent count from the registry or count distinct agent configs
+        agent_count = 0
+        try:
+            # Count distinct agent names in the AgentConfig table
+            agent_query = await session.execute(
+                select(
+                    func.count(distinct(ObjectConfiguration.object_name))
+                ).select_from(
+                    select(ObjectConfiguration)
+                    .where(
+                        ObjectConfiguration.object_type == ConfigurableObjectType.AGENT
+                    )
+                    .subquery()
+                )
+            )
+            agent_count = agent_query.scalar() or 0
+        except Exception:
+            logger.exception("error counting agents")
+            # Fallback to 0
+            agent_count = 0
+
+        # Return stats dict
+        return {
+            "total_workflow_runs": workflow_row.total_runs or 0,
+            "completed_runs": workflow_row.completed_runs or 0,
+            "in_progress_runs": workflow_row.in_progress_runs or 0,
+            "pending_human_tasks": pending_tasks,
+            "active_agents": agent_count,
+        }
+    except Exception:
+        logger.exception("error fetching system stats")
+        # Return default stats if there's an error
+        return {
+            "total_workflow_runs": 0,
+            "completed_runs": 0,
+            "in_progress_runs": 0,
+            "pending_human_tasks": 0,
+            "active_agents": 0,
+        }
+
+
+def create_info_router(title: str, description: str) -> APIRouter:
+    """
+    Create a router for serving combined application information and system statistics.
+
+    This router provides a single endpoint to retrieve the application's title,
+    description, and system-wide statistics on workflow runs, human tasks,
+    and registered agents.
+
+    Args:
+        title: The application title
+        description: The application description
+
+    Returns:
+        An APIRouter instance with a combined info route
+    """
+    router = APIRouter()
+
+    @router.get("/system-info", response_model=SystemInfo)
+    async def get_system_info(
+        session: AsyncSession = Depends(get_session),
+    ) -> SystemInfo:
+        """
+        Get combined application information and system statistics.
+
+        Returns:
+            SystemInfo object containing app details and system stats
+        """
+        stats = await get_system_stats(session)
+        return SystemInfo(title=title, description=description, **stats)
+
+    return router

planar/routers/models.py

@@ -0,0 +1,170 @@
+from datetime import datetime
+from enum import Enum
+from typing import Any, Dict, List
+from uuid import UUID
+
+from pydantic import BaseModel, Field, model_validator
+
+from planar.modeling.field_helpers import JsonSchema
+from planar.workflows import Workflow
+from planar.workflows.models import (
+    StepStatus,
+    StepType,
+    WorkflowStatus,
+)
+from planar.workflows.step_metadata import StepMetadata
+
+
+class EntityMetadata(BaseModel):
+    name: str
+    description: str | None = None
+    json_schema: JsonSchema
+    instance_count: int = 0
+
+
+class EntityInstance(BaseModel):
+    id: str
+    entity_name: str
+    data: dict[str, Any]
+
+
+class EntityInstanceList(BaseModel):
+    items: List[EntityInstance]
+    total: int
+    offset: int
+    limit: int
+
+
+class SortDirection(str, Enum):
+    """Enum for sort direction options."""
+
+    ASC = "asc"
+    DESC = "desc"
+
+
+# Models related to the workflow management REST API
+class WorkflowStartResponse(BaseModel):
+    id: UUID
+
+
+class WorkflowStatusResponse(BaseModel):
+    workflow: Workflow
+
+
+class DurationStats(BaseModel):
+    min_seconds: int | None = None
+    avg_seconds: int | None = None
+    max_seconds: int | None = None
+
+
+class WorkflowRunStatusCounts(BaseModel):
+    """Type-safe representation of workflow run status counts."""
+
+    # Virtual statuses (computed, never persisted)
+    running: int = 0
+    suspended: int = 0
+
+    # Persisted statuses (stored in database)
+    pending: int = 0
+    succeeded: int = 0
+    failed: int = 0
+
+
+class WorkflowDefinition(BaseModel):
+    fully_qualified_name: str
+    name: str
+    description: str | None = None
+    input_schema: JsonSchema | None = None
+    output_schema: JsonSchema | None = None
+    total_runs: int
+    run_statuses: WorkflowRunStatusCounts
+    durations: DurationStats | None = None
+
+
+class WorkflowRun(BaseModel):
+    id: UUID
+    status: WorkflowStatus
+    args: List[Any] | None = None
+    kwargs: Dict[str, Any] | None = None
+    result: Any | None = None
+    error: Dict[str, Any] | None = None
+    created_at: datetime
+    updated_at: datetime
+
+
+class WorkflowStepInfo(BaseModel):
+    step_id: int
+    is_internal_step: bool = Field(
+        default=False,
+        description="Whether the step is an internal Planar step, or a user-defined step",
+    )
+    parent_step_id: int | None = None
+    workflow_id: UUID
+    function_name: str
+    display_name: str
+    description: str | None = None
+    step_type: StepType
+    status: StepStatus
+    args: List[Any] | None = None
+    kwargs: Dict[str, Any] | None = None
+    result: Any | None = None
+    error: Dict[str, Any] | None = None
+    retry_count: int
+    created_at: datetime
+    updated_at: datetime
+    meta: StepMetadata | None = Field(
+        default=None,
+        description="Step type-specific rich data (e.g., human task details for human_in_the_loop steps)",
+    )
+
+    def model_post_init(self, __context: Any) -> None:
+        if self.function_name.startswith("planar."):
+            self.is_internal_step = True
+
+    @staticmethod
+    def get_display_name(custom_name: str | None, function_name: str) -> str:
+        """
+        If provided, use custom name, otherwise extract function name from a "fully qualified" function name.
+
+        For example, 'module.directory.fn_name' becomes 'fn_name'.
+        If there are no periods in the string, returns the original string.
+        """
+        return custom_name or function_name.split(".")[-1]
+
+    @model_validator(mode="after")
+    def validate_meta_step_type(self):
+        """
+        Make sure the outer step_type agrees with whatever subtype was
+        chosen for `meta`. This runs *after* normal field validation,
+        so `self.meta` is already an instantiated metadata object.
+        """
+        if self.meta is None:
+            return self  # nothing to compare
+
+        if self.step_type != self.meta.step_type:
+            raise ValueError(
+                f"meta.step_type={self.meta.step_type!r} does not match "
+                f"outer step_type={self.step_type!r}"
+            )
+        return self
+
+
+class WorkflowRunList(BaseModel):
+    items: List[WorkflowRun]
+    total: int
+    offset: int | None
+    limit: int | None
+
+
+class WorkflowStepList(BaseModel):
+    items: List[WorkflowStepInfo]
+    total: int
+    offset: int | None
+    limit: int | None
+
+
+class WorkflowList(BaseModel):
+    items: List[WorkflowDefinition]
+    total: int
+    offset: int | None
+    limit: int | None

planar/routers/object_config_router.py

@@ -0,0 +1,133 @@
+"""
+Router for object configuration operations.
+
+This module contains endpoints for managing object configurations across
+different object types (agents, rules, etc.).
+"""
+
+from typing import Generic, TypeVar, cast
+from uuid import UUID
+
+from fastapi import APIRouter, Body, HTTPException
+from pydantic import BaseModel
+
+from planar.ai.agent_utils import agent_configuration
+from planar.logging import get_logger
+from planar.object_config import (
+    DEFAULT_UUID,
+    ConfigNotFoundError,
+    ConfigurableObjectType,
+    ObjectConfigurationBase,
+)
+from planar.object_config.object_config import ConfigValidationError
+from planar.object_registry import ObjectRegistry
+from planar.rules.rule_configuration import rule_configuration
+
+T = TypeVar("T", bound=BaseModel)
+
+logger = get_logger(__name__)
+
+
+class PromoteConfigRequest(BaseModel):
+    """Request model for promoting a configuration."""
+
+    object_type: ConfigurableObjectType
+    config_id: UUID
+    object_name: str
+
+
+class ObjectConfigurationResponse(BaseModel, Generic[T]):
+    """Response model for object configuration endpoints that includes schema warnings."""
+
+    configs: list[T]
+
+
+def create_object_config_router(object_registry: ObjectRegistry) -> APIRouter:
+    """Create the object configuration router with all endpoints."""
+    router = APIRouter(tags=["Object Configuration"])
+
+    @router.post("/promote", response_model=ObjectConfigurationResponse)
+    async def promote_config(request: PromoteConfigRequest = Body(...)):
+        """Promote a specific configuration to be the active one.
+
+        Use config_id '00000000-0000-0000-0000-000000000000' to revert to default implementation.
+        Supports both rule and agent configurations.
+        """
+        # Handle special case for default UUID (all zeros)
+        entity = None
+        if request.object_type == ConfigurableObjectType.RULE:
+            # Validate that the rule exists
+            rules = object_registry.get_rules()
+            entity = next(
+                (d for d in rules if d.name == request.object_name),
+                None,
+            )
+            if not entity:
+                raise HTTPException(status_code=404, detail="Rule not found")
+
+        if request.object_type == ConfigurableObjectType.AGENT:
+            # Validate that the agent exists
+            agents = object_registry.get_agents()
+            entity = next(
+                (a for a in agents if a.name == request.object_name),
+                None,
+            )
+            if not entity:
+                raise HTTPException(status_code=404, detail="Agent not found")
+
+        config_manager = (
+            rule_configuration
+            if request.object_type == ConfigurableObjectType.RULE
+            else agent_configuration
+        )
+
+        try:
+            if request.config_id == DEFAULT_UUID:
+                logger.info(
+                    "reverting to default configuration",
+                    object_type=request.object_type,
+                    object_name=request.object_name,
+                )
+                await config_manager.promote_config(
+                    request.config_id, object_name=request.object_name
+                )
+            else:
+                logger.info(
+                    "promoting configuration",
+                    config_id=request.config_id,
+                    object_type=request.object_type,
+                    object_name=request.object_name,
+                )
+                await config_manager.promote_config(request.config_id)
+        except ConfigNotFoundError as e:
+            logger.exception("configuration not found during promotion")
+            raise HTTPException(
+                status_code=404,
+                detail=f"Configuration with ID {e.invalid_id} and object_type {e.object_type} not found",
+            )
+        except ConfigValidationError as e:
+            logger.exception("configuration validation failed during promotion")
+            raise HTTPException(
+                status_code=400,
+                detail=e.to_api_response().model_dump(mode="json", by_alias=True),
+            )
+
+        if entity is None:
+            # This case should ideally be caught by earlier checks
+            logger.warning(
+                "object not found after validation for promotion",
+                object_type=request.object_type,
+                object_name=request.object_name,
+            )
+            raise HTTPException(status_code=404, detail="Object not found")
+
+        configs_list = await config_manager.read_configs_with_default(
+            request.object_name,
+            entity.to_config(),  # type: ignore
+        )
+
+        return ObjectConfigurationResponse(
+            configs=cast(list[ObjectConfigurationBase], configs_list),
+        )
+
+    return router

planar/routers/rule.py

@@ -0,0 +1,108 @@
+from fastapi import APIRouter, Body, HTTPException
+from pydantic import BaseModel
+
+from planar.logging import get_logger
+from planar.object_config.object_config import (
+    ConfigValidationError,
+    ConfigValidationErrorResponse,
+)
+from planar.object_registry import ObjectRegistry
+from planar.rules import RuleSerializeable
+from planar.rules.models import JDMGraph, Rule, RuleEngineConfig
+from planar.rules.rule_configuration import rule_configuration
+from planar.rules.runner import (
+    EvaluateError,
+    EvaluateResponse,
+    evaluate_rule,
+)
+from planar.security.authorization import (
+    RuleAction,
+    RuleResource,
+    validate_authorization_for,
+)
+
+logger = get_logger(__name__)
+
+
+class EvaluateRuleRequest(BaseModel):
+    input: dict
+    graph: JDMGraph
+
+
+def create_rule_router(object_registry: ObjectRegistry) -> APIRouter:
+    router = APIRouter(tags=["Rules"])
+
+    @router.get("/", response_model=list[RuleSerializeable])
+    async def get_rules():
+        validate_authorization_for(RuleResource(), RuleAction.RULE_LIST)
+        rules = object_registry.get_rules()
+
+        return [await into_rule_serializeable(rule) for rule in rules]
+
+    @router.get("/{rule_name}", response_model=RuleSerializeable)
+    async def get_rule(rule_name: str):
+        validate_authorization_for(
+            RuleResource(rule_name), RuleAction.RULE_VIEW_DETAILS
+        )
+        rules = object_registry.get_rules()
+        rule = next((d for d in rules if d.name == rule_name), None)
+
+        if not rule:
+            raise HTTPException(status_code=404, detail="rule not found")
+
+        return await into_rule_serializeable(rule)
+
+    @router.post("/simulate", response_model=EvaluateResponse | EvaluateError)
+    async def simulate_rule(request: EvaluateRuleRequest = Body(...)):
+        validate_authorization_for(RuleResource(), RuleAction.RULE_SIMULATE)
+        return evaluate_rule(request.graph, request.input)
+
+    @router.post(
+        "/{rule_name}",
+        response_model=RuleSerializeable,
+        responses={
+            400: {
+                "model": ConfigValidationErrorResponse,
+                "description": "Configuration validation failed",
+            },
+            404: {"description": "Rule not found"},
+        },
+    )
+    async def save_rule_override(rule_name: str, jdm: JDMGraph = Body(...)):
+        validate_authorization_for(RuleResource(rule_name), RuleAction.RULE_UPDATE)
+        rules = object_registry.get_rules()
+        rule = next((d for d in rules if d.name == rule_name), None)
+
+        if not rule:
+            raise HTTPException(status_code=404, detail="rule not found")
+
+        # Create the rule configuration
+        rule_config = RuleEngineConfig(jdm=jdm)
+
+        try:
+            await rule_configuration.write_config(rule_name, rule_config)
+        except ConfigValidationError as e:
+            raise HTTPException(
+                status_code=400,
+                detail=e.to_api_response().model_dump(mode="json", by_alias=True),
+            )
+
+        logger.info("rule override saved", rule_name=rule_name)
+
+        return await into_rule_serializeable(rule)
+
+    return router
+
+
+async def into_rule_serializeable(rule: Rule) -> RuleSerializeable:
+    config_list = await rule_configuration.read_configs_with_default(
+        rule.name, rule.to_config()
+    )
+
+    return RuleSerializeable(
+        input_schema=rule.input.model_json_schema(),
+        output_schema=rule.output.model_json_schema(),
+        name=rule.name,
+        description=rule.description,
+        configs=config_list,
+    )