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

infra_mvp/stream/agents/reference/chat_dynamics/branching_test_stream.json

@@ -0,0 +1,145 @@
+{
+    "name": "Branching Test",
+    "description": "This agent demonstrates branching functionality where user choices determine which conversation branch to follow.",
+    "branches": {
+        "start": [
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "welcome",
+                "data": {
+                    "content": "Welcome! "
+                },
+                "timestamp": "2025-01-15T10:00:00Z",
+                "chunk_id": 1,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            },
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "welcome",
+                "data": {
+                    "content": "Choose an option:"
+                },
+                "timestamp": "2025-01-15T10:00:00Z",
+                "chunk_id": 2,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            },
+            {
+                "message_type": "await_user",
+                "block_type": "buttons",
+                "block_id": "test-choice",
+                "data": {
+                    "options": ["Option A", "Option B"],
+                    "label": "Select an option"
+                },
+                "branch_on": {
+                    "Option A": "option-a-content",
+                    "Option B": "option-b-content"
+                },
+                "timestamp": "2025-01-15T10:00:05Z",
+                "chunk_id": 1,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            }
+        ],
+        "should_skip": [
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "should-skip",
+                "data": {
+                    "content": "This should be skipped"
+                },
+                "timestamp": "2025-01-15T10:00:10Z",
+                "chunk_id": 1,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            },
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "should-skip",
+                "data": {
+                    "content": "If you see this, branching failed"
+                },
+                "timestamp": "2025-01-15T10:00:10Z",
+                "chunk_id": 2,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            }
+        ],
+        "option-a-content": [
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "option-a-content",
+                "data": {
+                    "content": "You chose Option A!\n\n"
+                },
+                "timestamp": "2025-01-15T10:00:15Z",
+                "chunk_id": 1,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            },
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "option-a-content",
+                "data": {
+                    "content": "This is the A branch."
+                },
+                "timestamp": "2025-01-15T10:00:15Z",
+                "chunk_id": 2,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            }
+        ],
+        "option-b-content": [
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "option-b-content",
+                "data": {
+                    "content": "You chose Option B!\n\n"
+                },
+                "timestamp": "2025-01-15T10:00:20Z",
+                "chunk_id": 1,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            },
+            {
+                "message_type": "informational",
+                "block_type": "markdown",
+                "block_id": "option-b-content",
+                "data": {
+                    "content": "This is the B branch."
+                },
+                "timestamp": "2025-01-15T10:00:20Z",
+                "chunk_id": 2,
+                "agent": {
+                    "name": "Branching Test Agent",
+                    "instance_id": 1
+                }
+            }
+        ]
+    }
+}

infra_mvp/stream/app.py

@@ -0,0 +1,49 @@
+"""ASGI entrypoint for the StreamServer.
+
+This exposes a FastAPI ``app`` so that you can run the stream server with
+uvicorn's ``--reload`` for live updates during UI development.
+
+Usage:
+    AGENT_PATH=demos/agents/basic_chatbot.py uv run uvicorn infra_mvp.stream.app:app --host 0.0.0.0 --port 8991 --reload
+
+Note: AGENT_PATH environment variable is required and must point to a Python file containing an agent.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+from infra_mvp.stream.container import create_stream_server
+from yera.agents.discovery import load_agent
+
+# Create the container and underlying StreamServer.
+# Respect HOST/PORT environment variables so that running via
+# `uvicorn infra_mvp.stream.app:app` (as done by the container entrypoint)
+# will bind to the intended network interface instead of defaulting to
+# 127.0.0.1 which prevents external access from Kubernetes probes.
+env_host = os.getenv("HOST", "0.0.0.0")
+env_port = int(os.getenv("PORT", "8991"))
+agent_path = os.getenv("AGENT_PATH")
+
+if not agent_path:
+    print(
+        "Error: AGENT_PATH environment variable is required.",
+        "Example: AGENT_PATH=demos/agents/basic_chatbot.py",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+try:
+    agent_wrapper = load_agent(Path(agent_path))
+except (FileNotFoundError, ValueError) as e:
+    print(f"Error loading agent: {e}", file=sys.stderr)
+    sys.exit(1)
+
+_server = create_stream_server(
+    agent=agent_wrapper,
+    host=env_host,
+    port=env_port,
+)
+
+# Expose the FastAPI application configured by BaseServer (includes CORS middleware)
+app = _server.app

infra_mvp/stream/container.py

@@ -0,0 +1,112 @@
+"""Dependency injection container for stream module."""
+
+from dependency_injector import containers, providers
+
+from infra_mvp.stream.server import StreamServer
+from yera.agents.decorator import AgentFunctionWrapper
+
+from .services import AgentService, SessionService
+
+
+class StreamContainer(containers.DeclarativeContainer):
+    """Dependency injection container for stream services."""
+
+    # Configuration
+    config = providers.Configuration()
+    config.host.from_value("0.0.0.0")
+    config.port.from_value(8991)
+    config.agents.from_value([])
+    config.dev_ui.from_value(False)
+
+    # Services - all singletons (stateless)
+    session_service: providers.Singleton[SessionService] | None = None
+    agent_service: providers.Singleton[AgentService] | None = None
+
+    # Stream server provider - creates fully-formed server
+    # Will be set by create_container
+    stream_server: providers.Singleton[StreamServer] | None = None
+
+
+def create_container(
+    agents: list[AgentFunctionWrapper],
+    host: str = "0.0.0.0",
+    port: int = 8991,
+    log_events: bool = False,
+    dev_ui: bool = False,
+) -> StreamContainer:
+    """Create and configure a stream container for agent mode.
+
+    Args:
+        agents: List of agent function wrappers.
+        host: Server host address. Defaults to "0.0.0.0".
+        port: Server port number. Defaults to 8991.
+        log_events: Enable logging of events to file.
+        dev_ui: If True, expect Next.js dev server (localhost:3000) instead of serving static UI.
+
+    Returns:
+        Configured stream container
+    """
+    container = StreamContainer()
+
+    # Create SessionService
+    container.session_service = providers.Singleton(
+        SessionService,
+        log_events=log_events,
+    )
+
+    # Create AgentService
+    container.agent_service = providers.Singleton(
+        AgentService,
+        agents=agents,
+    )
+
+    # Configure host, port and UI serving
+    container.config.host.from_value(host)
+    container.config.port.from_value(port)
+    container.config.dev_ui.from_value(dev_ui)
+
+    # Store agents in config for factory to access
+    container.config.agents.from_value(agents)
+
+    # Create stream server factory that captures the container
+    def _create_stream_server() -> StreamServer:
+        return StreamServer(
+            session_service=container.session_service(),
+            agent_service=container.agent_service(),
+            host=container.config.host(),
+            port=container.config.port(),
+            dev_ui=container.config.dev_ui(),
+        )
+
+    container.stream_server = providers.Singleton(_create_stream_server)
+
+    return container
+
+
+def create_stream_server(
+    agents: list[AgentFunctionWrapper],
+    host: str = "0.0.0.0",
+    port: int = 8991,
+    log_events: bool = False,
+    dev_ui: bool = False,
+) -> StreamServer:
+    """Create a stream server for agent mode.
+
+    Args:
+        agents: List of agent function wrappers.
+        host: Server host address. Defaults to "0.0.0.0".
+        port: Server port number. Defaults to 8991.
+        log_events: Enable logging of events to file.
+        dev_ui: If True, expect Next.js dev server (localhost:3000) instead of serving static UI.
+
+    Returns:
+        Configured stream server instance
+    """
+    container = create_container(
+        agents=agents,
+        host=host,
+        port=port,
+        log_events=log_events,
+        dev_ui=dev_ui,
+    )
+    return container.stream_server()

infra_mvp/stream/schemas/__init__.py

@@ -0,0 +1,16 @@
+"""Stream server Pydantic schemas package."""
+
+from .agent import AgentMetadata, ListAgentsResponse
+from .interaction import AddInteractionResponse, LayoutSubBlock, UserInteraction
+from .session import CreateSessionResponse, SessionCreateRequest, SessionState
+
+__all__ = [
+    "AddInteractionResponse",
+    "AgentMetadata",
+    "CreateSessionResponse",
+    "LayoutSubBlock",
+    "ListAgentsResponse",
+    "SessionCreateRequest",
+    "SessionState",
+    "UserInteraction",
+]

infra_mvp/stream/schemas/agent.py

@@ -0,0 +1,24 @@
+"""Agent metadata schemas for API responses."""
+
+from pydantic import BaseModel, Field
+
+
+class AgentMetadata(BaseModel):
+    """Minimal agent metadata for list endpoints.
+
+    Contains only the fields needed for displaying agents in lists,
+    cards, and hierarchical navigation.
+    """
+
+    id: str = Field(description="Agent identifier (dotted module.function name)")
+    name: str = Field(description="Agent display name")
+    description: str | None = Field(default=None, description="Agent description")
+    path: list[str] = Field(
+        description="Folder hierarchy path (empty for single-agent CLI mode)"
+    )
+
+
+class ListAgentsResponse(BaseModel):
+    """Response schema for listing agents."""
+
+    agents: list[AgentMetadata] = Field(description="List of agents")

infra_mvp/stream/schemas/interaction.py

@@ -0,0 +1,28 @@
+"""Interaction request and response schemas."""
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class LayoutSubBlock(BaseModel):
+    """Schema for a layout sub-block in an interaction."""
+
+    sub_block_id: str
+    sub_block_type: str
+    value: Any
+
+
+class UserInteraction(BaseModel):
+    """Schema for a user interaction."""
+
+    blockId: str
+    value: Any
+    blockType: str
+
+
+class AddInteractionResponse(BaseModel):
+    """Response schema for interaction handling."""
+
+    status: str
+    session_id: str

infra_mvp/stream/schemas/session.py

@@ -0,0 +1,30 @@
+"""Session request and response schemas."""
+
+from dataclasses import dataclass, field
+
+from pydantic import BaseModel
+
+from yera.agents.decorator import AgentFunctionWrapper
+from yera.events.runtime import PyRuntimeExecutor
+
+
+@dataclass
+class SessionState:
+    """Session state for Python agent sessions."""
+
+    agent: AgentFunctionWrapper
+    executor: PyRuntimeExecutor
+    session_id: str
+    interactions: list[dict] = field(default_factory=list)
+
+
+class SessionCreateRequest(BaseModel):
+    """Request schema for creating a session."""
+
+    agent_id: str
+
+
+class CreateSessionResponse(BaseModel):
+    """Response schema for session creation."""
+
+    session_id: str