planar 0.5.0__py3-none-any.whl

planar/routers/agents_router.py

@@ -0,0 +1,197 @@
+import asyncio
+from typing import Any
+
+from fastapi import APIRouter, BackgroundTasks, HTTPException
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+from planar.ai.agent_utils import AgentEventEmitter, AgentEventType, agent_configuration
+from planar.ai.models import AgentConfig
+from planar.ai.utils import AgentSerializeable, serialize_agent
+from planar.logging import get_logger
+from planar.object_config.object_config import ConfigValidationError
+from planar.object_registry import ObjectRegistry
+from planar.security.authorization import (
+    AgentAction,
+    AgentResource,
+    validate_authorization_for,
+)
+from planar.session import get_engine, session_context
+
+logger = get_logger(__name__)
+
+
+class AgentSimulationRequestBody(BaseModel):
+    input_value: str | dict[str, Any]
+
+
+class AgentSimulationData[T](BaseModel):
+    input_value: str | T
+
+
+class AgentEvent(BaseModel):
+    """Model representing a single event emitted by the agent."""
+
+    event: str
+    data: dict
+
+
+class AgentErrorData(BaseModel):
+    detail: str
+
+
+class AgentUpdateRequest(BaseModel):
+    """Model for updating agent information."""
+
+    system_prompt: str | None = None
+    user_prompt: str | None = None
+
+
+def create_agent_router(object_registry: ObjectRegistry) -> APIRouter:
+    router = APIRouter(tags=["Agents"])
+
+    @router.get("/", response_model=list[AgentSerializeable])
+    async def get_agents():
+        """Get all agents."""
+        validate_authorization_for(AgentResource(), AgentAction.AGENT_LIST)
+        registered_agents = object_registry.get_agents()
+        serialized_agents: list[AgentSerializeable] = []
+
+        for reg_agent in registered_agents:
+            agent_serializable = await serialize_agent(
+                agent_obj=reg_agent,
+            )
+
+            if agent_serializable:
+                serialized_agents.append(agent_serializable)
+
+        return serialized_agents
+
+    @router.patch("/{agent_name}", response_model=AgentSerializeable)
+    async def update_agent(agent_name: str, request: AgentUpdateRequest):
+        """Update agent information (system prompt and user prompt)."""
+        validate_authorization_for(
+            AgentResource(id=agent_name), AgentAction.AGENT_UPDATE
+        )
+        agents = object_registry.get_agents()
+        agent = next((a for a in agents if a.name == agent_name), None)
+        if not agent:
+            logger.warning("agent not found for update", agent_name=agent_name)
+            raise HTTPException(status_code=404, detail="Agent not found")
+
+        update = AgentConfig(
+            model=str(agent.model),
+            max_turns=agent.max_turns,
+            model_parameters=agent.model_parameters,
+            # At the moment, these are the only two fields that can be overridden
+            system_prompt=request.system_prompt or agent.system_prompt,
+            user_prompt=request.user_prompt or agent.user_prompt,
+        )
+
+        try:
+            await agent_configuration.write_config(agent.name, update)
+        except ConfigValidationError as e:
+            raise HTTPException(
+                status_code=400,
+                detail=e.to_api_response().model_dump(mode="json", by_alias=True),
+            )
+
+        logger.info(
+            "configuration updated for agent",
+            agent_name=agent.name,
+        )
+
+        agent_serializable = await serialize_agent(
+            agent_obj=agent,
+        )
+
+        if not agent_serializable:
+            logger.warning(
+                "failed to create serializable representation for agent after update",
+                agent_name=agent.name,
+            )
+            raise HTTPException(
+                status_code=500, detail="Failed to create agent representation"
+            )
+
+        return agent_serializable
+
+    @router.post(
+        "/{agent_name}/simulate",
+        response_model=None,  # No standard response model for SSE
+        responses={
+            200: {
+                "description": "Stream of agent events",
+                "content": {
+                    "text/event-stream": {
+                        "schema": {
+                            "type": "object",
+                        }
+                    }
+                },
+            }
+        },
+    )
+    async def simulate_agent(
+        agent_name: str,
+        request: AgentSimulationRequestBody,
+        background_tasks: BackgroundTasks,
+    ):
+        """Simulate an agent."""
+        validate_authorization_for(
+            AgentResource(id=agent_name), AgentAction.AGENT_SIMULATE
+        )
+        agents = object_registry.get_agents()
+        agent = next((a for a in agents if a.name == agent_name), None)
+        if not agent:
+            logger.warning("agent not found for simulation", agent_name=agent_name)
+            raise HTTPException(status_code=404, detail="Agent not found")
+
+        emitter = AgentEventEmitter()
+
+        # Create a copy of the request data to avoid sharing data between tasks
+        request_copy = request.model_copy()
+
+        # Create the background task with its own session context
+        async def run_agent_with_session():
+            logger.debug(
+                "background task started for agent simulation", agent_name=agent_name
+            )
+            try:
+                async with session_context(get_engine()):
+                    data_model = (
+                        AgentSimulationData[agent.input_type]
+                        if agent.input_type
+                        else AgentSimulationData
+                    )
+                    parsed_data = data_model.model_validate(request_copy.model_dump())
+                    await agent(parsed_data.input_value, event_emitter=emitter)
+                logger.debug(
+                    "background task finished for agent simulation",
+                    agent_name=agent_name,
+                )
+            except Exception as e:
+                logger.error(
+                    "background task failed for agent simulation",
+                    agent_name=agent_name,
+                    error=e,
+                )
+                emitter.emit(AgentEventType.ERROR, AgentErrorData(detail=str(e)))
+
+        # Cancel the agent task when the response is closed
+        agent_task = asyncio.create_task(run_agent_with_session())
+
+        async def cancel_agent_task():
+            if not agent_task.done():
+                agent_task.cancel()
+                logger.debug("agent task cancelled", agent_name=agent_name)
+
+        background_tasks.add_task(cancel_agent_task)
+
+        return StreamingResponse(
+            emitter.get_events(),
+            media_type="text/event-stream",
+            background=background_tasks,
+        )
+
+    return router

planar/routers/entity_router.py

@@ -0,0 +1,143 @@
+from uuid import UUID
+
+from fastapi import APIRouter, HTTPException
+from sqlalchemy import func
+from sqlmodel import select
+
+from planar.logging import get_logger
+from planar.modeling.orm.query_filter_builder import build_paginated_query
+from planar.object_registry import ObjectRegistry
+from planar.routers.models import EntityInstance, EntityInstanceList, EntityMetadata
+from planar.session import get_session
+
+logger = get_logger(__name__)
+
+
+def create_entities_router(object_registry: ObjectRegistry) -> APIRouter:
+    router = APIRouter(tags=["Entities"])
+
+    @router.get("/", response_model=list[EntityMetadata])
+    async def get_entities():
+        entities = object_registry.get_entities()
+        session = get_session()
+
+        result = []
+        for entity in entities:
+            instance_count = 0
+
+            # Get count of instances for this entity
+            count_query = select(func.count()).select_from(entity)
+            instance_count = await session.scalar(count_query) or 0
+
+            result.append(
+                EntityMetadata(
+                    name=entity.__name__,
+                    description=entity.__doc__,
+                    json_schema=entity.model_json_schema(),
+                    instance_count=instance_count,
+                )
+            )
+        return result
+
+    @router.get("/{entity_name}/instances", response_model=EntityInstanceList)
+    async def get_entity_instances(
+        entity_name: str,
+        skip: int = 0,
+        limit: int = 100,
+    ):
+        """
+        Get instances of a domain model entity from the database.
+        Only works for entities that have a database table.
+        """
+        entities = object_registry.get_entities()
+
+        # Find the entity class by name
+        entity_class = next(
+            (entity for entity in entities if entity.__name__ == entity_name), None
+        )
+
+        if not entity_class:
+            logger.warning("entity not found", entity_name=entity_name)
+            raise HTTPException(
+                status_code=404, detail=f"Entity {entity_name} not found"
+            )
+
+        # Check if entity is a DB table (not an enum)
+        if not hasattr(entity_class, "__tablename__"):
+            logger.warning("entity is not a database table", entity_name=entity_name)
+            raise HTTPException(
+                status_code=400,
+                detail=f"Entity {entity_name} is not stored in database",
+            )
+
+        # Fetch instances from DB
+        session = get_session()
+        base_query = select(entity_class)
+
+        # Build paginated query and count query
+        paginated_query, count_query = build_paginated_query(
+            base_query, offset=skip, limit=limit
+        )
+
+        # Count total matching records
+        total_count = await session.scalar(count_query) or 0
+
+        # Execute query
+        results = (await session.exec(paginated_query)).all()
+
+        # Convert to EntityInstance objects
+        instances = [
+            EntityInstance(
+                id=str(result.id), entity_name=entity_name, data=result.model_dump()
+            )
+            for result in results
+        ]
+
+        return EntityInstanceList(
+            items=instances, total=total_count, offset=skip, limit=limit
+        )
+
+    @router.get("/{entity_name}/instances/{instance_id}", response_model=EntityInstance)
+    async def get_entity_instance_by_id(entity_name: str, instance_id: UUID):
+        """
+        Get a specific entity instance by its ID.
+        Only works for entities that have a database table.
+        """
+        entities = object_registry.get_entities()
+
+        # Find the entity class by name
+        entity_class = next(
+            (entity for entity in entities if entity.__name__ == entity_name), None
+        )
+
+        if not entity_class:
+            logger.warning(
+                "entity not found when trying to get instance by id",
+                entity_name=entity_name,
+            )
+            raise HTTPException(
+                status_code=404, detail=f"Entity {entity_name} not found"
+            )
+
+        # Fetch the specific instance from DB
+        session = get_session()
+        result = await session.get(entity_class, instance_id)
+
+        if not result:
+            logger.warning(
+                "instance with id not found for entity",
+                instance_id=instance_id,
+                entity_name=entity_name,
+            )
+            raise HTTPException(
+                status_code=404,
+                detail=f"Instance with ID {instance_id} not found for entity {entity_name}",
+            )
+
+        # Convert to EntityInstance object
+        instance_data = result.model_dump()
+        return EntityInstance(
+            id=str(result.id), entity_name=entity_name, data=instance_data
+        )
+
+    return router

planar/routers/event.py

@@ -0,0 +1,91 @@
+"""
+Event API router for Planar workflows.
+
+This module provides API routes for emitting events that workflows might be waiting for.
+"""
+
+from typing import Any, Dict, List, Optional
+from uuid import UUID
+
+from fastapi import APIRouter, Body, HTTPException
+from pydantic import BaseModel
+from sqlmodel import col, select
+
+from planar.logging import get_logger
+from planar.session import get_session
+from planar.workflows.events import emit_event as emit_workflow_event
+from planar.workflows.models import WorkflowEvent
+
+logger = get_logger(__name__)
+
+
+class EventEmitRequest(BaseModel):
+    event_key: str
+    payload: Optional[Dict[str, Any]] = None
+    workflow_id: Optional[UUID] = None
+
+
+class EventResponse(BaseModel):
+    id: UUID
+    event_key: str
+    timestamp: str
+    payload: Optional[Dict[str, Any]] = None
+    workflow_id: Optional[UUID] = None
+
+
+def create_workflow_event_routes(router: APIRouter):
+    @router.post("/events/emit", response_model=EventResponse)
+    async def emit_event(request: EventEmitRequest = Body(...)):
+        """
+        Emit an event that workflows might be waiting for.
+
+        This endpoint allows external systems or APIs to emit events that will
+        wake up workflows waiting for those events.
+        """
+        try:
+            event, woken_workflows_count = await emit_workflow_event(
+                event_key=request.event_key,
+                payload=request.payload,
+                workflow_id=request.workflow_id,
+            )
+            logger.info(
+                "event emitted",
+                event_key=request.event_key,
+                event_id=event.id,
+                woken_workflows_count=woken_workflows_count,
+            )
+            return EventResponse(
+                id=event.id,
+                event_key=event.event_key,
+                timestamp=event.timestamp.isoformat(),
+                payload=event.payload,
+                workflow_id=event.workflow_id,
+            )
+        except Exception as e:
+            logger.exception("error emitting event", event_key=request.event_key)
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @router.get("/events/list", response_model=List[EventResponse])
+    async def list_events(limit: int = 50, event_key: Optional[str] = None):
+        """
+        List recent events, optionally filtered by event key.
+        """
+        session = get_session()
+
+        query = select(WorkflowEvent).order_by(col(WorkflowEvent.timestamp).desc())
+
+        if event_key:
+            query = query.where(WorkflowEvent.event_key == event_key)
+
+        events = (await session.exec(query.limit(limit))).all()
+
+        return [
+            EventResponse(
+                id=event.id,
+                event_key=event.event_key,
+                timestamp=event.timestamp.isoformat(),
+                payload=event.payload,
+                workflow_id=event.workflow_id,
+            )
+            for event in events
+        ]

planar/routers/files.py

@@ -0,0 +1,142 @@
+import uuid
+from uuid import UUID
+
+from fastapi import APIRouter, File, HTTPException, UploadFile
+from fastapi.responses import RedirectResponse, StreamingResponse
+
+from planar.files.models import PlanarFile, PlanarFileMetadata
+from planar.files.storage.context import get_storage
+from planar.logging import get_logger
+from planar.session import get_session
+
+logger = get_logger(__name__)
+
+
+router = APIRouter(tags=["Files"])
+
+
+@router.post("/upload", response_model=list[PlanarFile])
+async def upload_files(files: list[UploadFile] = File(...)):
+    """
+    Uploads one or more files to the configured storage backend and records their metadata.
+    Returns a list of file IDs for the successfully uploaded files.
+    """
+    storage = get_storage()
+    session = get_session()
+    uploaded_files: list[PlanarFile] = []
+
+    for file in files:
+        # Define an async generator to stream the file content efficiently
+        async def file_stream_generator(current_file: UploadFile):
+            # Read in chunks to avoid loading the whole file into memory
+            chunk_size = 65536  # 64KB
+            while chunk := await current_file.read(chunk_size):
+                yield chunk
+            # Reset file pointer if needed for potential retries or other operations,
+            # though not strictly necessary for this single pass upload.
+            await current_file.seek(0)
+
+        try:
+            # Store the file content using the storage backend
+            storage_ref = await storage.put(
+                stream=file_stream_generator(file), mime_type=file.content_type
+            )
+
+            # Create the metadata record in the database
+            planar_file = PlanarFileMetadata(
+                filename=file.filename
+                or str(uuid.uuid4()),  # Use filename or default to random UUID
+                content_type=file.content_type or "application/octet-stream",
+                size=file.size
+                if file.size is not None
+                else -1,  # Store size if available
+                storage_ref=storage_ref,
+            )
+            session.add(planar_file)
+            await session.commit()
+            await session.refresh(planar_file)  # Ensure file_id is populated
+
+            logger.info(
+                "uploaded file",
+                filename=planar_file.filename,
+                file_id=planar_file.id,
+                storage_ref=storage_ref,
+            )
+            uploaded_files.append(planar_file)
+
+        except Exception:
+            # Log the error for the specific file but continue with others
+            logger.exception("failed to upload file", filename=file.filename)
+            # Optionally, rollback the session changes for this specific file if needed,
+            # though commit happens per file here. If atomicity across all files is desired,
+            # collect all PlanarFile objects and commit once outside the loop.
+            await (
+                session.rollback()
+            )  # Rollback potential partial changes for the failed file
+
+    if not uploaded_files and files:
+        # If no files were successfully uploaded but some were provided, raise an error
+        raise HTTPException(status_code=500, detail="All file uploads failed")
+
+    return uploaded_files
+
+
+@router.get("/{file_id}/content")
+async def get_file_content(file_id: UUID):
+    """
+    Retrieves the content of a file.
+
+    If the storage backend provides an external URL, it redirects the client.
+    Otherwise, it streams the file content directly.
+    """
+    storage = get_storage()
+    session = get_session()
+
+    # Retrieve file metadata
+    planar_file = await session.get(PlanarFileMetadata, file_id)
+    if not planar_file:
+        raise HTTPException(status_code=404, detail="File not found")
+
+    storage_ref = planar_file.storage_ref
+
+    try:
+        # Check for an external URL first
+        external_url = await storage.external_url(storage_ref)
+        if external_url:
+            return RedirectResponse(url=external_url)
+
+        # If no external URL, get the stream from storage
+        stream, mime_type = await storage.get(storage_ref)
+
+        # Ensure mime_type defaults correctly if storage didn't return one
+        media_type = mime_type or planar_file.content_type or "application/octet-stream"
+
+        return StreamingResponse(stream, media_type=media_type)
+
+    except FileNotFoundError:
+        logger.warning(
+            "file content not found in storage",
+            file_id=file_id,
+            storage_ref=storage_ref,
+        )
+        raise HTTPException(status_code=404, detail="File content not found in storage")
+    except Exception:
+        logger.exception("failed to retrieve file content", file_id=file_id)
+        raise HTTPException(status_code=500, detail="Failed to retrieve file content")
+
+
+@router.get("/{file_id}/metadata", response_model=PlanarFile)
+async def get_file_metadata(file_id: UUID):
+    session = get_session()
+
+    # Retrieve file metadata
+    planar_file = await session.get(PlanarFileMetadata, file_id)
+    if not planar_file:
+        logger.warning("file metadata not found", file_id=file_id)
+        raise HTTPException(status_code=404, detail="File not found")
+    return planar_file
+
+
+def create_files_router() -> APIRouter:
+    """Factory function to create and return the files router."""
+    return router