smartify-ai 0.1.0__py3-none-any.whl

smartify/api/server.py

@@ -0,0 +1,992 @@
+"""FastAPI server for Smartify Grid execution.
+
+Provides HTTP API for:
+- Loading and validating grids
+- Energizing grids (initialization)
+- Executing grids
+- Managing grid lifecycle (pause/resume/stop)
+- Status and monitoring
+"""
+
+import asyncio
+import logging
+import os
+from contextlib import asynccontextmanager
+from datetime import datetime
+from typing import Any, Dict, List, Optional
+from uuid import uuid4
+
+from fastapi import Depends, FastAPI, HTTPException, BackgroundTasks, APIRouter, Query, Request
+from fastapi.middleware.cors import CORSMiddleware
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field, ConfigDict
+
+from smartify.api.auth import AuthMiddleware, verify_api_key_dep, get_auth_config
+from smartify.api.errors import (
+    ErrorCode,
+    ErrorResponse,
+    ErrorDetail,
+    SmartifyAPIError,
+    GridNotFoundError,
+    NodeNotFoundError,
+    GridStateError,
+    ValidationError,
+    ExecutionError as APIExecutionError,
+    register_error_handlers,
+)
+from smartify.api.events import (
+    EventType,
+    GridEvent,
+    EventsResponse,
+    EventFilter,
+    event_manager,
+)
+
+from smartify.engine.orchestrator import (
+    Orchestrator,
+    GridRun,
+    ExecutionError,
+    GridLifecycleError,
+)
+from smartify.models.grid import GridState
+from smartify.agents.adapters import AnthropicAdapter, OpenAIAdapter
+
+
+logger = logging.getLogger(__name__)
+
+# API Version
+API_VERSION = "1.0.0"
+API_VERSION_MAJOR = "v1"
+
+
+# ============================================================================
+# Request/Response Models
+# ============================================================================
+
+class GridLoadRequest(BaseModel):
+    """Request to load a grid."""
+    yaml_content: Optional[str] = Field(None, description="Grid YAML content")
+    file_path: Optional[str] = Field(None, description="Path to grid YAML file")
+    grid_id: Optional[str] = Field(None, description="Custom grid ID (auto-generated if not provided)")
+    
+    model_config = ConfigDict(
+        json_schema_extra={
+            "examples": [
+                {
+                    "yaml_content": """apiVersion: smartify.ai/v1
+kind: GridSpec
+metadata:
+  id: my-grid
+  name: My Grid
+topology:
+  nodes:
+    - id: controller
+      kind: controller
+      name: Main Controller""",
+                },
+                {
+                    "file_path": "/path/to/grid.yaml",
+                    "grid_id": "custom-id"
+                }
+            ]
+        }
+    )
+
+
+class GridInputsRequest(BaseModel):
+    """Request to provide grid inputs."""
+    inputs: Dict[str, Any] = Field(default_factory=dict)
+
+
+class GridRunRequest(BaseModel):
+    """Request to run a grid."""
+    inputs: Dict[str, Any] = Field(default_factory=dict, description="Grid inputs")
+    async_execution: bool = Field(False, description="Run in background")
+
+
+class GridResponse(BaseModel):
+    """Response containing grid information."""
+    grid_id: str
+    name: str
+    state: str
+    created_at: datetime
+    message: Optional[str] = None
+
+
+class GridStatusResponse(BaseModel):
+    """Detailed grid status response."""
+    grid_id: str
+    name: str
+    state: str
+    node_count: int
+    completed_nodes: int
+    failed_nodes: int
+    total_tokens: int
+    total_cost: float
+    elapsed_seconds: float
+    outputs: Optional[Dict[str, Any]] = None
+    error: Optional[str] = None
+
+
+class GridListResponse(BaseModel):
+    """Paginated list of grids."""
+    grids: List[GridResponse]
+    total: int
+    limit: int
+    offset: int
+    has_more: bool
+
+
+class NodeInfo(BaseModel):
+    """Node information."""
+    id: str
+    kind: str
+    parent: Optional[str]
+    state: str
+    has_output: bool
+
+
+class NodeListResponse(BaseModel):
+    """List of nodes in a grid."""
+    nodes: List[NodeInfo]
+    total: int
+
+
+class NodeOutputResponse(BaseModel):
+    """Node output response."""
+    node_id: str
+    kind: str
+    state: str
+    output: Optional[Any] = None
+
+
+class HealthResponse(BaseModel):
+    """Health check response."""
+    status: str
+    version: str
+    api_version: str
+    active_grids: int
+
+
+class APIInfoResponse(BaseModel):
+    """API information response."""
+    name: str
+    version: str
+    api_version: str
+    docs: str
+
+
+# ============================================================================
+# Application State
+# ============================================================================
+
+class AppState:
+    """Global application state."""
+    def __init__(self):
+        self.orchestrator = Orchestrator()
+        self.runs: Dict[str, GridRun] = {}
+        self.run_tasks: Dict[str, asyncio.Task] = {}
+        self.run_created_at: Dict[str, datetime] = {}
+
+
+state = AppState()
+
+
+# ============================================================================
+# Lifespan Management
+# ============================================================================
+
+def _register_adapters(orchestrator: Orchestrator) -> None:
+    """Auto-register LLM adapters from environment."""
+    default_set = False
+    preferred_default = os.environ.get("SMARTIFY_DEFAULT_LLM", "").lower()
+    
+    if os.environ.get("ANTHROPIC_API_KEY"):
+        try:
+            adapter = AnthropicAdapter()
+            orchestrator.register_llm_adapter("anthropic", adapter)
+            logger.info("Registered Anthropic LLM adapter")
+            
+            if preferred_default == "anthropic" or (not default_set and preferred_default != "openai"):
+                orchestrator.register_llm_adapter("default", adapter)
+                default_set = True
+                logger.info("Set Anthropic as default LLM adapter")
+        except Exception as e:
+            logger.warning(f"Failed to register Anthropic adapter: {e}")
+    
+    if os.environ.get("OPENAI_API_KEY"):
+        try:
+            adapter = OpenAIAdapter()
+            orchestrator.register_llm_adapter("openai", adapter)
+            logger.info("Registered OpenAI LLM adapter")
+            
+            if preferred_default == "openai" or not default_set:
+                orchestrator.register_llm_adapter("default", adapter)
+                default_set = True
+                logger.info("Set OpenAI as default LLM adapter")
+        except Exception as e:
+            logger.warning(f"Failed to register OpenAI adapter: {e}")
+    
+    if not default_set:
+        logger.warning("No LLM API keys found - set ANTHROPIC_API_KEY or OPENAI_API_KEY")
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage application lifespan."""
+    logger.info("Smartify API server starting...")
+    _register_adapters(state.orchestrator)
+    
+    auth_config = get_auth_config()
+    if auth_config.enabled:
+        logger.info(f"API authentication enabled ({len(auth_config.api_keys)} key(s) configured)")
+    else:
+        logger.warning("API authentication DISABLED - all endpoints are public")
+    
+    yield
+    
+    for grid_id, task in state.run_tasks.items():
+        if not task.done():
+            logger.info(f"Cancelling running grid: {grid_id}")
+            task.cancel()
+    logger.info("Smartify API server stopped")
+
+
+# ============================================================================
+# FastAPI Application
+# ============================================================================
+
+API_DESCRIPTION = """
+# Smartify Runtime API
+
+Execute and manage AI agent coordination grids with enterprise guardrails.
+
+## Overview
+
+The Smartify Runtime API provides programmatic access to:
+
+- **Grid Management**: Load, validate, and manage Grid specifications
+- **Execution Control**: Start, pause, resume, and stop grid execution
+- **Monitoring**: Track execution progress with real-time events
+- **Node Inspection**: Examine individual node states and outputs
+
+## Authentication
+
+All endpoints (except `/health`) require an API key:
+
+```
+X-API-Key: sk_your_api_key_here
+```
+
+## Versioning
+
+This API is versioned. All endpoints are prefixed with `/v1/`.
+The current API version is returned in the `X-API-Version` header.
+
+## Error Handling
+
+All errors return a consistent `ErrorResponse` format with:
+- `error`: Machine-readable error code
+- `message`: Human-readable description
+- `retryable`: Whether the request can be safely retried
+- `details`: Additional context (when available)
+
+## Rate Limits
+
+API requests are rate-limited per API key. Rate limit info is included in response headers.
+
+## Resources
+
+- [Grid YAML Reference](https://docs.smartify.ai/reference/grid-yaml)
+- [SDK Documentation](https://docs.smartify.ai/sdk)
+"""
+
+app = FastAPI(
+    title="Smartify Runtime API",
+    description=API_DESCRIPTION,
+    version=API_VERSION,
+    lifespan=lifespan,
+    contact={
+        "name": "Smartify Support",
+        "url": "https://smartify.ai/support",
+        "email": "support@smartify.ai",
+    },
+    license_info={
+        "name": "Apache 2.0",
+        "url": "https://www.apache.org/licenses/LICENSE-2.0",
+    },
+    openapi_tags=[
+        {
+            "name": "Health",
+            "description": "Health checks and API information",
+        },
+        {
+            "name": "Grids",
+            "description": "Grid lifecycle management - load, list, get, delete",
+        },
+        {
+            "name": "Lifecycle",
+            "description": "Grid execution control - energize, run, pause, resume, stop",
+        },
+        {
+            "name": "Nodes",
+            "description": "Node inspection - list nodes, get outputs",
+        },
+        {
+            "name": "Events",
+            "description": "Execution events for async operation tracking",
+        },
+    ],
+    responses={
+        400: {"model": ErrorResponse, "description": "Validation error"},
+        401: {"model": ErrorResponse, "description": "Authentication error"},
+        404: {"model": ErrorResponse, "description": "Resource not found"},
+        409: {"model": ErrorResponse, "description": "State conflict"},
+        429: {"model": ErrorResponse, "description": "Rate limit exceeded"},
+        500: {"model": ErrorResponse, "description": "Internal server error"},
+    },
+)
+
+# Register custom error handlers
+register_error_handlers(app)
+
+# CORS middleware for development
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["*"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+# Authentication middleware
+app.add_middleware(AuthMiddleware)
+
+
+# ============================================================================
+# Version Header Middleware
+# ============================================================================
+
+@app.middleware("http")
+async def add_version_header(request: Request, call_next):
+    """Add API version header to all responses."""
+    response = await call_next(request)
+    response.headers["X-API-Version"] = API_VERSION
+    response.headers["X-API-Version-Major"] = API_VERSION_MAJOR
+    return response
+
+
+# ============================================================================
+# Health & Info Endpoints (unversioned)
+# ============================================================================
+
+@app.get(
+    "/health",
+    response_model=HealthResponse,
+    tags=["Health"],
+    operation_id="healthCheck",
+    summary="Health check",
+    description="Check API server health status. This endpoint is always public.",
+)
+async def health_check():
+    """Check API server health."""
+    return HealthResponse(
+        status="healthy",
+        version=API_VERSION,
+        api_version=API_VERSION_MAJOR,
+        active_grids=len([r for r in state.runs.values() 
+                         if r.grid.state in (GridState.RUNNING, GridState.ENERGIZED)]),
+    )
+
+
+@app.get(
+    "/",
+    response_model=APIInfoResponse,
+    tags=["Health"],
+    operation_id="apiInfo",
+    summary="API information",
+    description="Get API name, version, and documentation links.",
+)
+async def root():
+    """API root endpoint."""
+    return APIInfoResponse(
+        name="Smartify Runtime API",
+        version=API_VERSION,
+        api_version=API_VERSION_MAJOR,
+        docs=f"/{API_VERSION_MAJOR}/docs",
+    )
+
+
+# ============================================================================
+# Versioned API Router
+# ============================================================================
+
+v1_router = APIRouter(prefix=f"/{API_VERSION_MAJOR}", tags=["v1"])
+
+
+# ============================================================================
+# Grid Management Endpoints
+# ============================================================================
+
+@v1_router.post(
+    "/grids",
+    response_model=GridResponse,
+    tags=["Grids"],
+    operation_id="loadGrid",
+    summary="Load a grid",
+    description="Load and validate a grid specification from YAML content or file path.",
+)
+async def load_grid(request: GridLoadRequest):
+    """Load and validate a grid specification."""
+    if not request.yaml_content and not request.file_path:
+        raise ValidationError(
+            "Must provide yaml_content or file_path",
+            details=[
+                ErrorDetail(suggestion="Provide either yaml_content (string) or file_path (path to YAML file)")
+            ]
+        )
+    
+    if request.yaml_content and request.file_path:
+        raise ValidationError(
+            "Provide only one of yaml_content or file_path",
+            details=[
+                ErrorDetail(suggestion="Remove either yaml_content or file_path from request")
+            ]
+        )
+    
+    try:
+        if request.yaml_content:
+            run = await state.orchestrator.load_grid(source=request.yaml_content)
+        else:
+            run = await state.orchestrator.load_grid(source=request.file_path)
+        
+        if request.grid_id:
+            run.grid.id = request.grid_id
+        
+        created_at = datetime.now()
+        state.runs[run.grid.id] = run
+        state.run_created_at[run.grid.id] = created_at
+        
+        return GridResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            created_at=created_at,
+            message="Grid loaded and validated successfully",
+        )
+    
+    except Exception as e:
+        logger.error(f"Failed to load grid: {e}")
+        raise ValidationError(f"Failed to load grid: {str(e)}")
+
+
+@v1_router.get(
+    "/grids",
+    response_model=GridListResponse,
+    tags=["Grids"],
+    operation_id="listGrids",
+    summary="List grids",
+    description="List all loaded grids with optional pagination and filtering.",
+)
+async def list_grids(
+    limit: int = Query(default=20, ge=1, le=100, description="Maximum number of grids to return"),
+    offset: int = Query(default=0, ge=0, description="Number of grids to skip"),
+    state_filter: Optional[str] = Query(default=None, alias="state", description="Filter by grid state"),
+):
+    """List all loaded grids with pagination."""
+    all_runs = list(state.runs.values())
+    
+    # Apply state filter
+    if state_filter:
+        all_runs = [r for r in all_runs if r.state.value == state_filter]
+    
+    total = len(all_runs)
+    
+    # Apply pagination
+    paginated = all_runs[offset:offset + limit]
+    
+    grids = [
+        GridResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            created_at=state.run_created_at.get(run.grid.id, datetime.now()),
+        )
+        for run in paginated
+    ]
+    
+    return GridListResponse(
+        grids=grids,
+        total=total,
+        limit=limit,
+        offset=offset,
+        has_more=offset + limit < total,
+    )
+
+
+@v1_router.get(
+    "/grids/{grid_id}",
+    response_model=GridStatusResponse,
+    tags=["Grids"],
+    operation_id="getGridStatus",
+    summary="Get grid status",
+    description="Get detailed status of a grid including execution progress and outputs.",
+)
+async def get_grid_status(grid_id: str):
+    """Get detailed status of a grid."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    status = state.orchestrator.get_status(run)
+    
+    return GridStatusResponse(
+        grid_id=run.grid.id,
+        name=run.grid.name,
+        state=run.state.value,
+        node_count=status.get("node_count", 0),
+        completed_nodes=status.get("completed_nodes", 0),
+        failed_nodes=status.get("failed_nodes", 0),
+        total_tokens=status.get("total_tokens", 0),
+        total_cost=status.get("total_cost", 0.0),
+        elapsed_seconds=status.get("elapsed_seconds", 0.0),
+        outputs=run.outputs if run.state == GridState.COMPLETED else None,
+        error=run.error,
+    )
+
+
+@v1_router.delete(
+    "/grids/{grid_id}",
+    tags=["Grids"],
+    operation_id="deleteGrid",
+    summary="Delete a grid",
+    description="Delete a grid from memory. Running grids will be stopped first.",
+)
+async def delete_grid(grid_id: str):
+    """Delete a grid from memory."""
+    if grid_id not in state.runs:
+        raise GridNotFoundError(grid_id)
+    
+    if grid_id in state.run_tasks:
+        task = state.run_tasks[grid_id]
+        if not task.done():
+            task.cancel()
+        del state.run_tasks[grid_id]
+    
+    del state.runs[grid_id]
+    if grid_id in state.run_created_at:
+        del state.run_created_at[grid_id]
+    
+    return {"message": f"Grid {grid_id} deleted"}
+
+
+# ============================================================================
+# Grid Lifecycle Endpoints
+# ============================================================================
+
+@v1_router.post(
+    "/grids/{grid_id}/energize",
+    response_model=GridResponse,
+    tags=["Lifecycle"],
+    operation_id="energizeGrid",
+    summary="Energize a grid",
+    description="Initialize a grid with inputs. Transitions: DRAFT → READY → ENERGIZED.",
+)
+async def energize_grid(grid_id: str, request: GridInputsRequest):
+    """Energize a grid (initialize with inputs)."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    if run.state not in (GridState.DRAFT,):
+        raise GridStateError(
+            f"Cannot energize grid in state '{run.state.value}'",
+            current_state=run.state.value,
+            expected_states=["draft"],
+        )
+    
+    try:
+        run.context.inputs = request.inputs
+        await state.orchestrator.energize(run)
+        
+        return GridResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            created_at=state.run_created_at.get(run.grid.id, datetime.now()),
+            message="Grid energized and ready to run",
+        )
+    
+    except GridLifecycleError as e:
+        raise GridStateError(str(e), run.state.value, ["draft"])
+    except Exception as e:
+        logger.error(f"Failed to energize grid: {e}")
+        raise APIExecutionError(f"Failed to energize grid: {str(e)}")
+
+
+@v1_router.post(
+    "/grids/{grid_id}/run",
+    response_model=GridStatusResponse,
+    tags=["Lifecycle"],
+    operation_id="runGrid",
+    summary="Run a grid",
+    description="Execute a grid. Use async_execution=true to run in background.",
+)
+async def run_grid(grid_id: str, request: GridRunRequest, background_tasks: BackgroundTasks):
+    """Run a grid to completion."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    if request.inputs:
+        run.context.inputs.update(request.inputs)
+    
+    # Auto-energize if still draft
+    if run.state == GridState.DRAFT:
+        try:
+            await state.orchestrator.energize(run)
+        except GridLifecycleError as e:
+            raise GridStateError(str(e), run.state.value, ["draft", "energized", "paused"])
+    
+    if run.state not in (GridState.ENERGIZED, GridState.PAUSED):
+        raise GridStateError(
+            f"Cannot run grid in state '{run.state.value}'",
+            current_state=run.state.value,
+            expected_states=["energized", "paused"],
+        )
+    
+    async def execute_grid():
+        try:
+            await state.orchestrator.execute(run)
+        except Exception as e:
+            logger.error(f"Grid execution failed: {e}")
+            run.error = str(e)
+    
+    if request.async_execution:
+        task = asyncio.create_task(execute_grid())
+        state.run_tasks[grid_id] = task
+        
+        return GridStatusResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            node_count=len(run.grid.nodes),
+            completed_nodes=0,
+            failed_nodes=0,
+            total_tokens=0,
+            total_cost=0.0,
+            elapsed_seconds=0.0,
+        )
+    else:
+        await execute_grid()
+        
+        status = state.orchestrator.get_status(run)
+        return GridStatusResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            node_count=status.get("node_count", 0),
+            completed_nodes=status.get("completed_nodes", 0),
+            failed_nodes=status.get("failed_nodes", 0),
+            total_tokens=status.get("total_tokens", 0),
+            total_cost=status.get("total_cost", 0.0),
+            elapsed_seconds=status.get("elapsed_seconds", 0.0),
+            outputs=run.outputs,
+            error=run.error,
+        )
+
+
+@v1_router.post(
+    "/grids/{grid_id}/pause",
+    response_model=GridResponse,
+    tags=["Lifecycle"],
+    operation_id="pauseGrid",
+    summary="Pause a grid",
+    description="Pause a running grid. Can be resumed later.",
+)
+async def pause_grid(grid_id: str):
+    """Pause a running grid."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    if run.state != GridState.RUNNING:
+        raise GridStateError(
+            f"Cannot pause grid in state '{run.state.value}'",
+            current_state=run.state.value,
+            expected_states=["running"],
+        )
+    
+    try:
+        await state.orchestrator.pause(run)
+        return GridResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            created_at=state.run_created_at.get(run.grid.id, datetime.now()),
+            message="Grid paused",
+        )
+    except GridLifecycleError as e:
+        raise GridStateError(str(e), run.state.value, ["running"])
+
+
+@v1_router.post(
+    "/grids/{grid_id}/resume",
+    response_model=GridResponse,
+    tags=["Lifecycle"],
+    operation_id="resumeGrid",
+    summary="Resume a grid",
+    description="Resume a paused grid.",
+)
+async def resume_grid(grid_id: str):
+    """Resume a paused grid."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    if run.state != GridState.PAUSED:
+        raise GridStateError(
+            f"Cannot resume grid in state '{run.state.value}'",
+            current_state=run.state.value,
+            expected_states=["paused"],
+        )
+    
+    try:
+        await state.orchestrator.resume(run)
+        return GridResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            created_at=state.run_created_at.get(run.grid.id, datetime.now()),
+            message="Grid resumed",
+        )
+    except GridLifecycleError as e:
+        raise GridStateError(str(e), run.state.value, ["paused"])
+
+
+@v1_router.post(
+    "/grids/{grid_id}/stop",
+    response_model=GridResponse,
+    tags=["Lifecycle"],
+    operation_id="stopGrid",
+    summary="Stop a grid",
+    description="Stop a running or paused grid. Cannot be resumed.",
+)
+async def stop_grid(grid_id: str):
+    """Stop a running grid."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    if run.state not in (GridState.RUNNING, GridState.PAUSED, GridState.ENERGIZED):
+        raise GridStateError(
+            f"Cannot stop grid in state '{run.state.value}'",
+            current_state=run.state.value,
+            expected_states=["running", "paused", "energized"],
+        )
+    
+    try:
+        if grid_id in state.run_tasks:
+            task = state.run_tasks[grid_id]
+            if not task.done():
+                task.cancel()
+        
+        await state.orchestrator.stop(run)
+        return GridResponse(
+            grid_id=run.grid.id,
+            name=run.grid.name,
+            state=run.state.value,
+            created_at=state.run_created_at.get(run.grid.id, datetime.now()),
+            message="Grid stopped",
+        )
+    except GridLifecycleError as e:
+        raise GridStateError(str(e), run.state.value, ["running", "paused", "energized"])
+
+
+# ============================================================================
+# Node Inspection Endpoints
+# ============================================================================
+
+@v1_router.get(
+    "/grids/{grid_id}/nodes",
+    response_model=NodeListResponse,
+    tags=["Nodes"],
+    operation_id="listNodes",
+    summary="List nodes",
+    description="List all nodes in a grid with their current state.",
+)
+async def list_nodes(grid_id: str):
+    """List all nodes in a grid."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    nodes = []
+    for node in run.grid.nodes:
+        node_exec = run.scheduler.nodes.get(node.id)
+        node_state = node_exec.state if node_exec else None
+        nodes.append(NodeInfo(
+            id=node.id,
+            kind=node.kind.value,
+            parent=node.parent,
+            state=node_state.value if node_state else "unknown",
+            has_output=node.id in run.context.outputs,
+        ))
+    
+    return NodeListResponse(nodes=nodes, total=len(nodes))
+
+
+@v1_router.get(
+    "/grids/{grid_id}/nodes/{node_id}",
+    response_model=NodeOutputResponse,
+    tags=["Nodes"],
+    operation_id="getNodeOutput",
+    summary="Get node output",
+    description="Get the output from a specific node.",
+)
+async def get_node_output(grid_id: str, node_id: str):
+    """Get output from a specific node."""
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    node = next((n for n in run.grid.nodes if n.id == node_id), None)
+    if not node:
+        raise NodeNotFoundError(grid_id, node_id)
+    
+    node_exec = run.scheduler.nodes.get(node_id)
+    node_state = node_exec.state if node_exec else None
+    output = run.context.outputs.get(node_id)
+    
+    return NodeOutputResponse(
+        node_id=node_id,
+        kind=node.kind.value,
+        state=node_state.value if node_state else "unknown",
+        output=output,
+    )
+
+
+# ============================================================================
+# Event Streaming Endpoints
+# ============================================================================
+
+@v1_router.get(
+    "/grids/{grid_id}/events",
+    response_model=EventsResponse,
+    tags=["Events"],
+    operation_id="getGridEvents",
+    summary="Get grid events",
+    description="Poll for execution events. Use for tracking async operation progress.",
+)
+async def get_grid_events(
+    grid_id: str,
+    after: Optional[str] = Query(None, description="Return events after this event ID"),
+    types: Optional[str] = Query(None, description="Comma-separated event types to filter"),
+    node_id: Optional[str] = Query(None, description="Filter events by node ID"),
+    limit: int = Query(50, ge=1, le=200, description="Maximum events to return"),
+):
+    """Get execution events for a grid.
+    
+    Use this endpoint to:
+    - Poll for progress on async executions
+    - Get detailed execution trace
+    - Monitor node-by-node execution
+    
+    For long-polling, pass `after` with the last event ID you received.
+    """
+    run = state.runs.get(grid_id)
+    if not run:
+        raise GridNotFoundError(grid_id)
+    
+    # Parse types filter
+    type_filter = None
+    if types:
+        try:
+            type_filter = [EventType(t.strip()) for t in types.split(",")]
+        except ValueError as e:
+            raise ValidationError(f"Invalid event type: {e}")
+    
+    # Build filter
+    filter = EventFilter(
+        types=type_filter,
+        node_id=node_id,
+        after=after,
+        limit=limit,
+    )
+    
+    # Get events
+    events, has_more, next_cursor = await event_manager.get_events(grid_id, filter)
+    store = await event_manager.get_store(grid_id)
+    total = await store.count()
+    
+    # Calculate progress
+    status = state.orchestrator.get_status(run)
+    total_nodes = status.get("node_count", 1)
+    completed_nodes = status.get("completed_nodes", 0)
+    progress = completed_nodes / total_nodes if total_nodes > 0 else 0.0
+    
+    return EventsResponse(
+        grid_id=grid_id,
+        events=events,
+        total=total,
+        has_more=has_more,
+        next_cursor=next_cursor,
+        state=run.state.value,
+        progress=progress,
+        completed_nodes=completed_nodes,
+        total_nodes=total_nodes,
+    )
+
+
+class EventTypesResponse(BaseModel):
+    """List of available event types."""
+    types: List[str]
+
+
+@v1_router.get(
+    "/events/types",
+    response_model=EventTypesResponse,
+    tags=["Events"],
+    operation_id="listEventTypes",
+    summary="List event types",
+    description="Get list of all possible event types for filtering.",
+)
+async def list_event_types():
+    """List all available event types."""
+    return EventTypesResponse(
+        types=[e.value for e in EventType]
+    )
+
+
+# ============================================================================
+# Register versioned router
+# ============================================================================
+
+app.include_router(v1_router)
+
+# Also mount at root for backward compatibility (deprecated)
+# TODO: Remove in v2
+for route in v1_router.routes:
+    if hasattr(route, 'path') and route.path not in ['/', '/health']:
+        # Skip re-mounting health and root
+        pass
+
+
+# ============================================================================
+# Server Runner
+# ============================================================================
+
+def run_server(host: str = "0.0.0.0", port: int = 8080, reload: bool = False):
+    """Run the API server."""
+    import uvicorn
+    uvicorn.run(
+        "smartify.api.server:app",
+        host=host,
+        port=port,
+        reload=reload,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    run_server()