yera 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

infra_mvp/stream/server.py

@@ -0,0 +1,321 @@
+"""Test server for SSE-based message streaming to Yera UI.
+
+This is a standalone test server for UI development and testing.
+The streaming functionality will eventually be integrated into the main ApiServer.
+"""
+
+import logging
+import mimetypes
+import os
+from pathlib import Path
+
+from fastapi import Body, FastAPI, HTTPException
+from fastapi import Path as FastAPIPath
+from fastapi.responses import FileResponse, StreamingResponse
+from fastapi.staticfiles import StaticFiles
+
+from infra_mvp.base_server import BaseServer
+from infra_mvp.monitoring import ServiceMetrics, get_metrics_endpoint
+from infra_mvp.stream.schemas import (
+    AddInteractionResponse,
+    AgentMetadata,
+    CreateSessionResponse,
+    ListAgentsResponse,
+    SessionCreateRequest,
+    UserInteraction,
+)
+from infra_mvp.stream.services import AgentService, SessionService
+
+
+class StreamServer(BaseServer):
+    """Server that streams predefined conversation events via Server-Sent Events (SSE).
+
+    This server is intended for UI testing and development.  The streaming functionality
+    will be integrated into the main ApiServer in the future.
+    """
+
+    def __init__(
+        self,
+        agent_service: AgentService,
+        session_service: SessionService,
+        host: str | None = "0.0.0.0",
+        port: int | None = 8991,
+        dev_ui: bool = False,
+    ):
+        """Initialise the stream server.
+
+        Args:
+            agent_service: Agent management service.
+            session_service: Session management service.
+            host: Server host address.  Defaults to "0.0.0.0".
+            port: Server port.  Defaults to 8991 to avoid conflicts with other servers.
+
+        """
+        # Store services and dependencies
+        self.agent_service = agent_service
+        self.session_service = session_service
+        self.dev_ui = dev_ui
+
+        # Initialize metrics
+        self.metrics = ServiceMetrics("stream")
+
+        super().__init__(host, port)
+
+    def stop(self):
+        """Stop the server and clean up all sessions."""
+        # Clean up all sessions (terminates agent processes)
+        self.session_service.cleanup_all()
+        super().stop()
+
+    def build_api(self) -> FastAPI:
+        """Build the FastAPI application with SSE streaming endpoints.
+
+        Returns:
+            Configured FastAPI application
+
+        """
+        app = FastAPI(
+            title="Yera Stream Server",
+            description="SSE-based message streaming server for Yera UI development",
+            version="0.1.0",
+        )
+
+        @app.post("/api/session")
+        async def create_session(
+            request: SessionCreateRequest = Body(...),
+        ) -> CreateSessionResponse:
+            """Create a new session for streaming an agent.
+
+            Args:
+                request: Session creation request with agent_id
+
+            Returns:
+                Response with session_id
+
+            Raises:
+                HTTPException: 404 if agent not found
+
+            """
+            try:
+                agent = self.agent_service.get_agent(request.agent_id)
+            except ValueError as e:
+                raise HTTPException(status_code=404, detail=str(e)) from e
+
+            session_id = self.session_service.create_session(agent)
+            return CreateSessionResponse(session_id=session_id)
+
+        @app.get("/api/session/{session_id}/stream")
+        async def stream_session(
+            session_id: str = FastAPIPath(
+                description="Session identifier for streaming"
+            ),
+        ) -> StreamingResponse:
+            """Start streaming conversation events for a session via Server-Sent Events (SSE).
+
+            Args:
+                session_id: Session identifier from the URL path.
+
+            Returns:
+                StreamingResponse with text/event-stream content type
+
+            Raises:
+                HTTPException: 404 if session not found
+
+            """
+            try:
+                self.session_service.get_session(session_id)
+            except KeyError:
+                raise HTTPException(
+                    status_code=404, detail="Session not found"
+                ) from None
+
+            return StreamingResponse(
+                self.session_service.generate_events(session_id),
+                media_type="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "Connection": "keep-alive",
+                    "X-Accel-Buffering": "no",  # Disable buffering in nginx
+                },
+            )
+
+        @app.post("/api/session/{session_id}/interaction")
+        async def add_interaction(
+            session_id: str = FastAPIPath(description="Session identifier"),
+            interaction: UserInteraction = Body(description="User interaction data"),
+        ) -> AddInteractionResponse:
+            """Add a user interaction to a session.
+
+            Args:
+                session_id: Session identifier from the URL path
+                interaction: User interaction data with blockId, value, and blockType
+
+            Returns:
+                Response indicating interaction was received
+
+            Raises:
+                HTTPException: 404 if session not found
+
+            """
+            logging.info(
+                "Received user input: session_id=%s blockId=%s blockType=%s value=%s",
+                session_id,
+                interaction.blockId,
+                interaction.blockType,
+                interaction.value,
+            )
+            try:
+                self.session_service.add_interaction(
+                    session_id, interaction.model_dump()
+                )
+            except KeyError as e:
+                raise HTTPException(
+                    status_code=404, detail=f"Session not found: {session_id}"
+                ) from e
+            return AddInteractionResponse(status="received", session_id=session_id)
+
+        @app.get("/api/agents", response_model=ListAgentsResponse)
+        async def list_agents() -> ListAgentsResponse:
+            """List all available agents with minimal metadata.
+
+            Returns:
+                List of agents with minimal metadata for listing/navigation
+
+            """
+            return ListAgentsResponse(
+                agents=[
+                    AgentMetadata(
+                        id=agent.metadata.identifier,
+                        name=agent.metadata.name,
+                        description=agent.metadata.description,
+                        path=[],
+                    )
+                    for agent in self.agent_service.list_agents()
+                ]
+            )
+
+        @app.get("/health")
+        async def health_check() -> dict[str, str]:
+            """Health check endpoint.
+
+            Returns:
+                Dictionary with health status
+
+            """
+            self.metrics.track_request("/health", "GET", 200)
+            return {"status": "healthy", "service": "yera-stream"}
+
+        # Add metrics endpoint
+        app.get("/metrics")(get_metrics_endpoint(self.metrics))
+
+        # Optionally configure static UI serving (must be after API routes)
+        self._configure_ui_routes(app)
+
+        return app
+
+    def _configure_ui_routes(self, app: FastAPI) -> None:
+        """Configure static UI and SPA routing if enabled."""
+        if self.dev_ui:
+            return
+
+        ui_path = _get_ui_static_path()
+        if not ui_path:
+            logging.error(
+                "Static UI requested (dev_ui=False) but no UI dist directory was found. "
+                "Ensure the yera UI bundle is installed or run in dev mode with the "
+                "Next.js dev server."
+            )
+            # Fail fast so callers know UI is unavailable in this mode
+            raise RuntimeError("Static UI not available")
+        logging.info("Serving static UI from %s", ui_path)
+
+        index_path = ui_path / "index.html"
+        if not index_path.is_file():
+            logging.error(
+                "Static UI requested (dev_ui=False) but index.html was not found at %s",
+                index_path,
+            )
+            raise RuntimeError("Static UI index.html not found")
+
+        static_next = ui_path / "_next"
+        if static_next.is_dir():
+            app.mount(
+                "/_next",
+                StaticFiles(directory=str(static_next)),
+                name="next-static",
+            )
+
+        favicon_path = ui_path / "favicon.ico"
+
+        if favicon_path.is_file():
+
+            @app.get("/favicon.ico")
+            async def favicon() -> FileResponse:
+                return FileResponse(favicon_path)
+
+        @app.get("/")
+        async def serve_root() -> FileResponse:
+            """Serve the SPA entrypoint for the root path."""
+            return FileResponse(index_path)
+
+        @app.get("/{full_path:path}")
+        async def serve_spa(full_path: str) -> FileResponse:
+            """Serve static assets when they exist, otherwise serve index.html.
+
+            FastAPI registers more specific routes (API endpoints, /health, /metrics)
+            before this catch-all handler, so those are matched first. This handler
+            only receives routes that didn't match any other endpoint, and it acts
+            as a smart fallback:
+
+            - If the requested path corresponds to an actual file within the UI dist,
+              that file is served directly.
+            - Otherwise, index.html is served so the SPA router can handle the path
+              client-side.
+            """
+
+            # Resolve path safely to avoid directory traversal outside ui_path
+            try:
+                candidate = (ui_path / full_path).resolve()
+                # Ensure candidate is within ui_path
+                if not candidate.is_relative_to(ui_path):
+                    return FileResponse(index_path)
+            except (OSError, RuntimeError, ValueError):
+                # Any issues resolving the path - fall back to SPA entry
+                return FileResponse(index_path)
+
+            # If it's an actual file in the UI bundle, serve it with a sensible content type
+            if candidate.is_file():
+                media_type, _ = mimetypes.guess_type(str(candidate))
+                return FileResponse(candidate, media_type=media_type)
+
+            # Otherwise, let the SPA handle it
+            return FileResponse(index_path)
+
+
+def _get_ui_static_path() -> Path | None:
+    """Locate the bundled UI static files, if available.
+
+    Order of precedence (explicit over implicit):
+    1. Environment variable YERA_UI_DIST
+    2. Packaged path relative to installed yera package: yera/ui/dist
+    """
+    # First: explicit user configuration
+    env_path = os.getenv("YERA_UI_DIST")
+    if env_path:
+        candidate = Path(env_path).expanduser()
+        if candidate.is_dir() and (candidate / "index.html").is_file():
+            return candidate
+
+    # Second: packaged path (installed yera)
+    try:
+        import yera
+
+        package_root = Path(yera.__file__).parent
+        package_ui = package_root / "ui" / "dist"
+        if package_ui.is_dir() and (package_ui / "index.html").is_file():
+            return package_ui
+    except (ImportError, AttributeError, TypeError):
+        # yera not installed or __file__ not available (unlikely but safe)
+        pass
+
+    return None

infra_mvp/stream/services/__init__.py

@@ -0,0 +1,12 @@
+"""Stream services package."""
+
+from .agent_service import AgentService
+from .event_converter import output_event_to_json, user_interaction_to_input_event
+from .session_service import SessionService
+
+__all__ = [
+    "AgentService",
+    "SessionService",
+    "output_event_to_json",
+    "user_interaction_to_input_event",
+]

infra_mvp/stream/services/agent_service.py

@@ -0,0 +1,40 @@
+from yera.agents.decorator import AgentFunctionWrapper
+
+
+class AgentService:
+    """Service for managing agents."""
+
+    def __init__(self, agents: list[AgentFunctionWrapper]):
+        """Initialise the agent service.
+
+        Args:
+            agents: The list of agents to manage.
+        """
+        self.agents: dict[str, AgentFunctionWrapper] = {
+            agent.metadata.identifier: agent for agent in agents
+        }
+
+    def get_agent(self, agent_id: str) -> AgentFunctionWrapper:
+        """Get an agent by ID.
+
+        Args:
+            agent_id: The ID of the agent to get.
+
+        Returns:
+            The agent function wrapper.
+
+        Raises:
+            ValueError: If the agent is not found.
+        """
+        try:
+            return self.agents[agent_id]
+        except KeyError:
+            raise ValueError(f"Agent with ID '{agent_id}' not found") from None
+
+    def list_agents(self) -> list[AgentFunctionWrapper]:
+        """List all available agents.
+
+        Returns:
+            List of available agents.
+        """
+        return list(self.agents.values())

infra_mvp/stream/services/event_converter.py

@@ -0,0 +1,83 @@
+"""Event conversion utilities for converting between backend and frontend formats."""
+
+import json
+
+from yera.events.models.in_event import InputEvent
+from yera.events.models.out_event import OutputEvent
+
+
+def output_event_to_json(event: OutputEvent) -> dict:
+    """Convert an OutputEvent to frontend JSON format.
+
+    Args:
+        event: OutputEvent from the agent execution
+
+    Returns:
+        Dictionary matching the frontend AgentMessage interface:
+        {
+            "message_type": "informational" | "await_user" | "await_agent" | "layout",
+            "block_type": str,
+            "block_id": str,
+            "data": dict,
+            "timestamp": str (ISO format),
+            "chunk_id": int,
+            "agent": {
+                "name": str,
+                "instance_id": int
+            },
+            "parent_block_id": str | None
+        }
+    """
+    # Convert agent_instance to frontend format
+    agent = {
+        "name": event.agent_instance.agent_id,
+        "instance_id": event.agent_instance.instance_id,
+    }
+
+    # Serialize data field (Pydantic models have model_dump())
+    # Use mode='json' to ensure date/datetime objects are serialized to strings
+    if hasattr(event.data, "model_dump"):
+        data = event.data.model_dump(mode="json")
+    else:
+        # Fallback for non-Pydantic data
+        data = event.data
+
+    return {
+        "message_type": event.message_type,
+        "block_type": event.block_type,
+        "block_id": event.block_id,
+        "data": data,
+        "timestamp": event.timestamp.isoformat(),
+        "chunk_id": event.chunk_id,
+        "agent": agent,
+        "parent_block_id": event.parent_block_id,
+    }
+
+
+def user_interaction_to_input_event(interaction: dict) -> InputEvent:
+    """Convert a UserInteraction dict to InputEvent format.
+
+    Args:
+        interaction: UserInteraction dictionary with:
+            - blockId: str
+            - value: Any
+            - blockType: str
+
+    Returns:
+        InputEvent for pushing to EventStream
+    """
+    # Convert interaction value to string
+    # For buttons, value is typically the button text
+    # For text inputs, value is the text string
+    # For other types, convert to JSON string
+    if isinstance(interaction["value"], str):
+        value_str = interaction["value"]
+    else:
+        value_str = json.dumps(interaction["value"])
+
+    # Use blockId as identifier, blockType as type
+    return InputEvent(
+        identifier=interaction["blockId"],
+        type=interaction["blockType"],
+        data=value_str,
+    )