flyteplugins-hitl 2.0.6__py3-none-any.whl

flyteplugins/hitl/__init__.py

@@ -0,0 +1,53 @@
+"""Human-in-the-Loop (HITL) plugin for Flyte.
+
+This plugin provides an event-based API for pausing workflows and waiting for human input.
+
+## Basic usage:
+
+```python
+import flyte
+import flyteplugins.hitl as hitl
+
+task_env = flyte.TaskEnvironment(
+    name="my-hitl-workflow",
+    image=flyte.Image.from_debian_base(python_version=(3, 12)),
+    resources=flyte.Resources(cpu=1, memory="512Mi"),
+    depends_on=[hitl.env],
+)
+
+
+@task_env.task(report=True)
+async def main() -> int:
+    # Create an event (this serves the app if not already running)
+    event = await hitl.new_event.aio(
+        "integer_input_event",
+        data_type=int,
+        scope="run",
+        prompt="What should I add to x?",
+    )
+    y = await event.wait.aio()
+    return y
+```
+
+## Features:
+
+- Event-based API for human-in-the-loop workflows
+- Web form for human input
+- Programmatic API for automated input
+- Support for int, float, str, and bool data types
+- Crash-resilient polling with object storage
+"""
+
+from ._event import Event, EventScope, event_task_env, new_event
+
+__all__ = [
+    "Event",
+    "EventScope",
+    "env",
+    "new_event",
+]
+
+__version__ = "0.1.0"
+
+# Expose the task environment as `env` for user convenience
+env = event_task_env

flyteplugins/hitl/_app.py

@@ -0,0 +1,268 @@
+"""
+FastAPI app for Human-in-the-Loop (HITL) events.
+
+This module provides the web interface for humans to submit input to paused Flyte workflows.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from contextlib import asynccontextmanager
+from typing import Any
+
+import aiofiles
+import flyte
+import flyte.storage as storage
+from fastapi import FastAPI, Form, HTTPException
+from fastapi.responses import HTMLResponse
+from pydantic import BaseModel
+
+from ._helpers import _convert_value, _get_request_path, _get_response_path
+from ._html_templates import get_bool_select_element, get_index_page, get_input_form_page, get_submission_success_page
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# FastAPI App for Human Input
+# ============================================================================
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Initialize Flyte on app startup."""
+    logger.info("HITL Event App starting up...")
+    await flyte.init_in_cluster.aio()
+    yield
+    logger.info("HITL Event App shutting down...")
+
+
+app = FastAPI(
+    title="Human-in-the-Loop Event Service",
+    description="Provides endpoints for humans to submit input to Flyte workflow events",
+    version="1.0.0",
+    lifespan=lifespan,
+)
+
+
+# Pydantic models for submissions
+class HITLSubmissionTyped(BaseModel):
+    """Schema for HITL input submission with explicit type."""
+
+    request_id: str
+    value: Any
+    data_type: str = "str"
+    response_path: str = ""  # Full storage path for the response (e.g., s3://bucket/path/response.json)
+
+
+@app.get("/health")
+async def health_check() -> dict[str, str]:
+    """Health check endpoint."""
+    return {"status": "healthy"}
+
+
+@app.get("/", response_class=HTMLResponse)
+async def index() -> str:
+    """Landing page with instructions."""
+    return get_index_page()
+
+
+@app.get("/form/{request_id}", response_class=HTMLResponse)
+async def input_form(request_id: str, request_path: str | None = None) -> str:
+    """Render an HTML form for human input.
+
+    Args:
+        request_id: The unique identifier for this HITL request
+    """
+    # Use provided request_path or fall back to local path construction
+    if request_path is None:
+        request_path = _get_request_path(request_id)
+
+    prompt = "Please enter a value"
+    data_type_name = "str"
+    event_name = "Unknown"
+    response_path = ""
+
+    print(f"Request path: {request_path}")
+    try:
+        if await storage.exists(request_path):
+            request_data = await storage.get(request_path)
+            async with aiofiles.open(request_data, "r") as f:
+                request_data = json.loads(await f.read())
+                prompt = request_data.get("prompt", prompt)
+                data_type_name = request_data.get("data_type", "str")
+                event_name = request_data.get("event_name", "Unknown")
+                response_path = request_data.get("response_path", "")
+    except Exception as e:
+        print(f"Could not fetch request metadata: {e}")
+
+    # Determine input type based on data type
+    if data_type_name == "int":
+        input_type = "number"
+        placeholder = "Enter integer value"
+        input_attrs = 'step="1"'
+    elif data_type_name == "float":
+        input_type = "number"
+        placeholder = "Enter decimal value"
+        input_attrs = 'step="any"'
+    elif data_type_name == "bool":
+        input_type = "select"
+        placeholder = ""
+        input_attrs = ""
+    else:
+        input_type = "text"
+        placeholder = "Enter value"
+        input_attrs = ""
+
+    if input_type == "select":
+        input_element = get_bool_select_element()
+    else:
+        input_element = f'<input type="{input_type}" name="value" placeholder="{placeholder}" {input_attrs} required>'
+
+    return get_input_form_page(
+        event_name=event_name,
+        prompt=prompt,
+        data_type_name=data_type_name,
+        request_id=request_id,
+        response_path=response_path,
+        input_element=input_element,
+    )
+
+
+@app.post("/submit", response_class=HTMLResponse)
+async def submit_input(
+    request_id: str = Form(...),
+    value: str = Form(...),
+    data_type: str = Form("str"),
+    response_path: str = Form(""),
+) -> str:
+    """Submit human input for a pending event.
+
+    Args:
+        request_id: The unique identifier for this HITL request
+        value: The value submitted by the user
+        data_type: The expected data type (int, float, bool, str)
+        response_path: Optional full storage path to write the response (e.g., s3://bucket/path/response.json).
+                      If not provided, falls back to local path construction.
+    """
+    try:
+        converted_value = _convert_value(value, data_type)
+    except (ValueError, TypeError) as e:
+        raise HTTPException(status_code=400, detail=f"Failed to convert value '{value}' to type '{data_type}': {e}")
+
+    logger.info(f"Received event submission: request_id={request_id}, value={converted_value} (type={data_type})")
+
+    # Use provided response_path or fall back to local path construction
+    if not response_path:
+        response_path = _get_response_path(request_id)
+
+    response_data = json.dumps(
+        {
+            "value": converted_value,
+            "status": "completed",
+            "request_id": request_id,
+            "data_type": data_type,
+        }
+    ).encode()
+
+    try:
+        await storage.put_stream(response_data, to_path=response_path)
+        logger.info(f"Wrote response to {response_path}")
+        message = "Input received successfully. The workflow will continue."
+        return get_submission_success_page(
+            request_id=request_id,
+            value=str(converted_value),
+            data_type=data_type,
+            message=message,
+        )
+    except Exception as e:
+        logger.error(f"Failed to write response: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to save response: {e}")
+
+
+@app.post("/submit/json")
+async def submit_input_json(submission: HITLSubmissionTyped) -> dict:
+    """Submit human input via JSON."""
+    try:
+        converted_value = _convert_value(str(submission.value), submission.data_type)
+    except (ValueError, TypeError) as e:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Failed to convert value '{submission.value}' to type '{submission.data_type}': {e}",
+        )
+
+    logger.info(
+        f"Received event submission: request_id={submission.request_id}, "
+        f"value={converted_value} (type={submission.data_type})"
+    )
+
+    response_path = submission.response_path
+    if not response_path:
+        response_path = _get_response_path(submission.request_id)
+
+    response_data = json.dumps(
+        {
+            "value": converted_value,
+            "status": "completed",
+            "request_id": submission.request_id,
+            "data_type": submission.data_type,
+        }
+    ).encode()
+
+    try:
+        await storage.put_stream(response_data, to_path=response_path)
+        logger.info(f"Wrote response to {response_path}")
+        return {
+            "status": "submitted",
+            "request_id": submission.request_id,
+            "value": converted_value,
+            "data_type": submission.data_type,
+            "message": "Input received successfully. The workflow will continue.",
+        }
+    except Exception as e:
+        logger.error(f"Failed to write response: {e}")
+        raise HTTPException(status_code=500, detail=f"Failed to save response: {e}")
+
+
+@app.get("/status/{request_id}")
+async def get_status(
+    request_id: str,
+    request_path: str | None = None,
+    response_path: str | None = None,
+) -> dict:
+    """Check the status of an event.
+
+    Args:
+        request_id: The unique identifier for this HITL request
+        request_path: Optional full storage path to the request metadata
+        response_path: Optional full storage path to the response metadata
+    """
+    # Use provided paths or fall back to local path construction
+    if not request_path:
+        request_path = _get_request_path(request_id)
+    if not response_path:
+        response_path = _get_response_path(request_id)
+
+    result = {"request_id": request_id}
+
+    if await storage.exists(request_path):
+        async for chunk in storage.get_stream(request_path):
+            result["request"] = json.loads(chunk.decode())
+            # If response_path wasn't provided, try to get it from request metadata
+            if not response_path:
+                response_path = result["request"].get("response_path", _get_response_path(request_id))
+            break
+    else:
+        result["request"] = None
+
+    if await storage.exists(response_path):
+        async for chunk in storage.get_stream(response_path):
+            result["response"] = json.loads(chunk.decode())
+            result["status"] = "completed"
+            break
+    else:
+        result["response"] = None
+        result["status"] = "pending" if result["request"] else "not_found"
+
+    return result

flyteplugins/hitl/_event.py

@@ -0,0 +1,430 @@
+"""
+Event class for Human-in-the-Loop (HITL) workflows.
+
+This module provides the Event class that encapsulates the HITL functionality:
+- Creates and serves a FastAPI app for receiving human input
+- Provides endpoints for form-based and JSON-based submission
+- Polls object storage for responses using durable sleep (crash-resilient)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import uuid
+from dataclasses import dataclass
+from typing import Any, ClassVar, Generic, Literal, Type, TypeVar
+
+import flyte
+import flyte.app
+import flyte.durable
+import flyte.report
+import flyte.storage as storage
+from flyte.app.extras import FastAPIAppEnvironment
+from flyte.syncify import syncify
+
+from ._app import app
+from ._helpers import _get_request_path, _get_response_path, _get_type_name
+from ._html_templates import get_event_report_html
+
+# Type variable for generic Event
+T = TypeVar("T")
+
+# Scope type for events
+EventScope = Literal["run"]
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# App and Task Environment for HITL events (module-level)
+# ============================================================================
+
+event_image = (
+    flyte.Image.from_debian_base()
+    .with_pip_packages("fastapi", "uvicorn", "python-multipart", "aiofiles")
+    .with_pip_packages("flyte>=2.0.0", "flyteplugins-hitl>=2.0.0")
+)
+
+event_app_env = FastAPIAppEnvironment(
+    name="hitl-event-app",
+    app=app,
+    domain=flyte.app.Domain(subdomain="hitl-event-app"),
+    description="Human-in-the-loop event service for Flyte workflows",
+    image=event_image,
+    resources=flyte.Resources(cpu=1, memory="512Mi"),
+    requires_auth=True,
+    scaling=flyte.app.Scaling(replicas=(0, 1), scaledown_after=600),
+)
+
+event_task_env = flyte.TaskEnvironment(
+    name="hitl-event-task-env",
+    image=event_image,
+    resources=flyte.Resources(cpu=1, memory="512Mi"),
+    depends_on=[event_app_env],
+)
+
+
+# ============================================================================
+# Event-based HITL API
+# ============================================================================
+
+
+class Event(Generic[T]):
+    """
+    An event that waits for human input via an embedded FastAPI app.
+
+    This class encapsulates the entire HITL functionality:
+    - Creates and serves a FastAPI app for receiving human input
+    - Provides endpoints for form-based and JSON-based submission
+    - Polls object storage for responses using durable sleep (crash-resilient)
+
+    The app is automatically served when the Event is created via `Event.create()`.
+    All infrastructure details (AppEnvironment, deployment) are abstracted away.
+
+    Example:
+        # Create an event (serves the app) and wait for input
+        event = await Event.create.aio(
+            "proceed_event",
+            scope="run",
+            prompt="What should I add to x?",
+            data_type=int,
+        )
+        result = await event.wait.aio()
+
+        # Or synchronously
+        event = Event.create("my_event", scope="run", prompt="Enter value", data_type=str)
+        value = event.wait()
+    """
+
+    # Class-level app handle (shared across all events)
+    _app_handle: ClassVar[flyte.AppHandle | None] = None
+    _app_served: ClassVar[bool] = False
+
+    def __init__(
+        self,
+        name: str,
+        scope: EventScope,
+        data_type: Type[T],
+        prompt: str,
+        request_id: str,
+        endpoint: str,
+        request_path: str,
+        response_path: str,
+        timeout_seconds: int = 3600,
+        poll_interval_seconds: int = 5,
+    ):
+        self.name = name
+        self.scope = scope
+        self.data_type = data_type
+        self.prompt = prompt
+        self.request_id = request_id
+        self._endpoint = endpoint
+        self._request_path = request_path
+        self._response_path = response_path
+        self.timeout_seconds = timeout_seconds
+        self.poll_interval_seconds = poll_interval_seconds
+        self._type_name = _get_type_name(data_type)
+        self._report_flushed = False
+
+    @property
+    def form_url(self) -> str:
+        """URL where humans can submit input for this event."""
+        from urllib.parse import urlencode
+
+        params = urlencode({"request_path": self._request_path})
+        return f"{self._endpoint}/form/{self.request_id}?{params}"
+
+    @property
+    def api_url(self) -> str:
+        """API endpoint for programmatic submission."""
+        return f"{self._endpoint}/submit/json"
+
+    @property
+    def endpoint(self) -> str:
+        """Base endpoint of the HITL app."""
+        return self._endpoint
+
+    @classmethod
+    async def _serve_app(cls) -> flyte.AppHandle:
+        """Serve the app and return the app handle."""
+        from flyteplugins.hitl import __version__
+
+        await flyte.init_in_cluster.aio()
+        return await flyte.with_servecontext(
+            copy_style="none",
+            version=__version__,
+            interactive_mode=True,
+        ).serve.aio(event_app_env)
+
+    @classmethod
+    @syncify
+    async def create(
+        cls,
+        name: str,
+        data_type: Type[T],
+        scope: EventScope = "run",
+        prompt: str = "Please provide a value",
+        timeout_seconds: int = 3600,
+        poll_interval_seconds: int = 5,
+    ) -> "Event[T]":
+        """
+        Create a new human-in-the-loop event and serve the app.
+
+        This method creates an event that waits for human input via the FastAPI app.
+        The app is automatically served if not already running. All infrastructure
+        details are abstracted away - you just get an event to wait on.
+
+        Args:
+            name: A descriptive name for the event (used in logs and UI)
+            scope: The scope of the event. Currently only "run" is supported.
+            prompt: The prompt to display to the human
+            data_type: The expected type of the input (int, float, str, bool)
+            timeout_seconds: Maximum time to wait for human input (default: 1 hour)
+            poll_interval_seconds: How often to check for a response (default: 5 seconds)
+
+        Returns:
+            An Event object that can be used to wait for the human input
+
+        Example:
+            # Async usage
+            event = await Event.create.aio(
+                "approval_event",
+                scope="run",
+                prompt="Do you approve this action?",
+                data_type=bool,
+            )
+            approved = await event.wait.aio()
+
+            # Sync usage
+            event = Event.create("value_event", scope="run", prompt="Enter a number", data_type=int)
+            value = event.wait()
+        """
+        # Serve the app if not already served
+        if not cls._app_served or cls._app_handle is None:
+            logger.info("Serving HITL Event app...")
+            cls._app_handle = await cls._serve_app()
+            cls._app_served = True
+            logger.info(f"HITL Event app served at: {cls._app_handle.endpoint}")
+
+        # Get the endpoint from the app handle
+        endpoint = cls._app_handle.endpoint
+
+        # Generate request ID and create request metadata
+        request_id = str(uuid.uuid4())
+        type_name = _get_type_name(data_type)
+
+        # Get the full storage paths (these will be blob storage paths when running in cluster)
+        request_path = _get_request_path(request_id)
+        response_path = _get_response_path(request_id)
+
+        # Write the request metadata to storage, including the full paths
+        # so the app can read/write to blob storage
+        data = {
+            "request_id": request_id,
+            "event_name": name,
+            "scope": scope,
+            "prompt": prompt,
+            "data_type": type_name,
+            "status": "pending",
+            "app_endpoint": endpoint,
+            "request_path": request_path,
+            "response_path": response_path,
+        }
+        logger.info(f"Creating event with data: {data}")
+        request_data = json.dumps(data).encode()
+
+        await storage.put_stream(request_data, to_path=request_path)
+        logger.info(f"Created event '{name}' at {request_path}")
+
+        # Create the event object
+        event: Event[T] = cls(
+            name=name,
+            scope=scope,
+            data_type=data_type,
+            prompt=prompt,
+            request_id=request_id,
+            endpoint=endpoint,
+            request_path=request_path,
+            response_path=response_path,
+            timeout_seconds=timeout_seconds,
+            poll_interval_seconds=poll_interval_seconds,
+        )
+        return event
+
+    @syncify
+    async def wait(self) -> T:
+        """
+        Wait for human input and return the result.
+
+        This method polls object storage for a response using durable sleep,
+        making it crash-resilient. If the task crashes and restarts, it will
+        resume polling from where it left off.
+
+        Returns:
+            The value provided by the human, converted to the event's data_type
+
+        Raises:
+            TimeoutError: If no response is received within the timeout
+        """
+        curl_body = json.dumps(
+            {
+                "request_id": self.request_id,
+                "response_path": self._response_path,
+                "value": "{{your_value}}",
+                "data_type": self._type_name,
+            },
+            indent=2,
+        )
+
+        report_html = get_event_report_html(
+            form_url=self.form_url,
+            api_url=self.api_url,
+            curl_body=curl_body,
+            type_name=self._type_name,
+        )
+
+        await show_form.override(
+            short_name=self.name,
+            links=[
+                EventFormLink(
+                    endpoint=self.endpoint,
+                    request_id=self.request_id,
+                    request_path=self._request_path,
+                )
+            ],
+        )(report_html)
+        return await wait_for_input_event(
+            name=self.name,
+            request_id=self.request_id,
+            response_path=self._response_path,
+            timeout_seconds=self.timeout_seconds,
+            poll_interval_seconds=self.poll_interval_seconds,
+        )
+
+    def __repr__(self) -> str:
+        return (
+            f"Event(name={self.name!r}, scope={self.scope!r}, "
+            f"data_type={self._type_name}, request_id={self.request_id!r})"
+        )
+
+
+@dataclass
+class EventFormLink(flyte.Link):
+    """
+    A link to the event form.
+    """
+
+    endpoint: str
+    request_id: str
+    request_path: str
+    name: str = "Event Form"
+
+    def get_link(
+        self,
+        run_name: str,
+        project: str,
+        domain: str,
+        context: dict[str, str],
+        parent_action_name: str,
+        action_name: str,
+        pod_name: str,
+        **kwargs,
+    ) -> str:
+        from urllib.parse import urlencode
+
+        params = urlencode({"request_path": self.request_path})
+        return f"{self.endpoint}/form/{self.request_id}?{params}"
+
+
+@event_task_env.task(report=True)
+async def show_form(html_report: str):
+    """
+    Task that serves the event app.
+    """
+    await flyte.report.replace.aio(html_report)
+    await flyte.report.flush.aio()
+
+
+@flyte.trace
+async def wait_for_input_event(
+    name: str,
+    request_id: str,
+    response_path: str,
+    timeout_seconds: int,
+    poll_interval_seconds: int,
+) -> Any:
+    """
+    Task that waits for input from the event app.
+    """
+    # Use the stored response path (which includes the full blob storage path)
+    elapsed = 0
+
+    while elapsed < timeout_seconds:
+        # Check if response exists
+        if await storage.exists(response_path):
+            async for chunk in storage.get_stream(response_path):
+                response = json.loads(chunk.decode())
+                if response.get("status") == "completed":
+                    value = response["value"]
+                    logger.info(f"Event '{name}' received human input: {value}")
+                    print(f"\nReceived human input for '{name}': {value}")
+                    return value
+
+            logger.info(f"Event '{name}' waiting for human input... ({elapsed}/{timeout_seconds}s elapsed)")
+        await flyte.durable.sleep.aio(poll_interval_seconds)
+        elapsed += poll_interval_seconds
+
+    raise TimeoutError(
+        f"Event '{name}' (request_id={request_id}) timed out after "
+        f"{timeout_seconds} seconds. No human input was received."
+    )
+
+
+@syncify
+async def new_event(
+    name: str,
+    data_type: Type[T],
+    scope: EventScope = "run",
+    prompt: str = "Please provide a value",
+    timeout_seconds: int = 3600,
+    poll_interval_seconds: int = 5,
+) -> Event[T]:
+    """
+    Create a new human-in-the-loop event.
+
+    This is a convenience function that wraps Event.create().
+
+    Args:
+        name: A descriptive name for the event (used in logs and UI)
+        data_type: The expected type of the input (int, float, str, bool)
+        scope: The scope of the event. Currently only "run" is supported.
+        prompt: The prompt to display to the human
+        timeout_seconds: Maximum time to wait for human input (default: 1 hour)
+        poll_interval_seconds: How often to check for a response (default: 5 seconds)
+
+    Returns:
+        An Event object that can be used to wait for the human input
+
+    Example:
+        # Async usage
+        event = await new_event.aio(
+            "approval_event",
+            data_type=bool,
+            scope="run",
+            prompt="Do you approve this action?",
+        )
+        approved = await event.wait.aio()
+
+        # Sync usage
+        event = new_event("value_event", data_type=int, scope="run", prompt="Enter a number")
+        value = event.wait()
+    """
+    return await Event.create.aio(
+        name=name,
+        data_type=data_type,
+        scope=scope,
+        prompt=prompt,
+        timeout_seconds=timeout_seconds,
+        poll_interval_seconds=poll_interval_seconds,
+    )

flyteplugins/hitl/_helpers.py

@@ -0,0 +1,71 @@
+"""
+Helper functions for the HITL plugin.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any, Type
+
+
+def _get_type_name(data_type: Type) -> str:
+    """Get a string name for a type that can be used in the form."""
+    if data_type is int:
+        return "int"
+    elif data_type is float:
+        return "float"
+    elif data_type is bool:
+        return "bool"
+    elif data_type is str:
+        return "str"
+    else:
+        # For complex types, default to string (JSON serialized)
+        return "str"
+
+
+def _convert_value(value: str, data_type: str) -> Any:
+    """Convert a string value to the specified data type."""
+    if data_type == "int":
+        return int(value)
+    elif data_type == "float":
+        return float(value)
+    elif data_type == "bool":
+        return value.lower() in ("true", "1", "yes")
+    else:
+        # Default to string
+        return value
+
+
+def _get_hitl_base_path() -> str:
+    """Get the base path for HITL requests in object storage."""
+    return "hitl-requests"
+
+
+def _get_request_path(request_id: str) -> str:
+    """Get the storage path for a HITL request."""
+    from flyte._context import internal_ctx
+
+    ctx = internal_ctx()
+    if ctx.has_raw_data:
+        base = ctx.raw_data.path
+    elif raw_data_path_env_var := os.getenv("RAW_DATA_PATH"):
+        base = raw_data_path_env_var
+    else:
+        # Fallback for local development
+        base = "/tmp/flyte/hitl"
+    return f"{base}/{_get_hitl_base_path()}/{request_id}/request.json"
+
+
+def _get_response_path(request_id: str) -> str:
+    """Get the storage path for a HITL response."""
+    from flyte._context import internal_ctx
+
+    ctx = internal_ctx()
+    if ctx.has_raw_data:
+        base = ctx.raw_data.path
+    elif raw_data_path_env_var := os.getenv("RAW_DATA_PATH"):
+        base = raw_data_path_env_var
+    else:
+        # Fallback for local development
+        base = "/tmp/flyte/hitl"
+    return f"{base}/{_get_hitl_base_path()}/{request_id}/response.json"

flyteplugins/hitl/_html_templates.py

@@ -0,0 +1,333 @@
+"""
+HTML templates for Human-in-the-Loop (HITL) events.
+
+This module contains all HTML template strings used by the HITL plugin.
+"""
+
+
+def get_index_page() -> str:
+    """Landing page with instructions."""
+    return """
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>HITL Event Service</title>
+        <style>
+            body { font-family: Arial, sans-serif; max-width: 800px; margin: 50px auto; padding: 20px; }
+            h1 { color: #333; }
+            code { background: #f4f4f4; padding: 2px 6px; border-radius: 3px; }
+            .endpoint { margin: 20px 0; padding: 15px; background: #f9f9f9; border-radius: 5px; }
+        </style>
+    </head>
+    <body>
+        <h1>Human-in-the-Loop Event Service</h1>
+        <p>This service allows humans to provide input to paused Flyte workflow events.</p>
+
+        <div class="endpoint">
+            <h3>Submit Input</h3>
+            <p>To submit input for a pending event, visit:</p>
+            <code>GET /form/{request_id}</code>
+            <p>Or POST directly to:</p>
+            <code>POST /submit</code>
+        </div>
+
+        <div class="endpoint">
+            <h3>Check Event Status</h3>
+            <code>GET /status/{request_id}</code>
+        </div>
+    </body>
+    </html>
+    """
+
+
+def get_bool_select_element() -> str:
+    """HTML select element for boolean input."""
+    return """
+            <select
+                name="value"
+                required
+                style="
+                    width: 100%;
+                    padding: 12px;
+                    font-size: 16px;
+                    border: 1px solid #ddd;
+                    border-radius: 4px;
+                    box-sizing: border-box;
+                    margin-bottom: 15px;"
+                onchange="this.form.submit()"
+            >
+                <option value="">-- Select --</option>
+                <option value="true">True</option>
+                <option value="false">False</option>
+            </select>
+        """
+
+
+def get_input_form_page(
+    event_name: str,
+    prompt: str,
+    data_type_name: str,
+    request_id: str,
+    response_path: str,
+    input_element: str,
+) -> str:
+    """HTML page for the input form."""
+    return f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>Event Input Required</title>
+        <style>
+            body {{
+                font-family: Arial, sans-serif;
+                max-width: 500px;
+                margin: 25px auto;
+                padding: 20px;
+            }}
+            .card {{
+                background: #fff;
+                border-radius: 8px;
+                box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+                padding: 30px;
+            }}
+            h1 {{ color: #333; margin-top: 0; }}
+            .event-name {{ color: #4CAF50; font-weight: bold; margin-bottom: 10px; }}
+            .prompt {{ color: #666; margin-bottom: 20px; }}
+            .request-id {{ font-size: 12px; color: #999; margin-bottom: 20px; }}
+            .data-type {{ font-size: 12px; color: #666; margin-bottom: 10px; }}
+            input[type="number"], input[type="text"] {{
+                width: 100%;
+                padding: 12px;
+                font-size: 16px;
+                border: 1px solid #ddd;
+                border-radius: 4px;
+                box-sizing: border-box;
+                margin-bottom: 15px;
+            }}
+            button {{
+                width: 100%;
+                padding: 12px;
+                font-size: 16px;
+                background: #4CAF50;
+                color: white;
+                border: none;
+                border-radius: 4px;
+                cursor: pointer;
+            }}
+            button:hover {{ background: #45a049; }}
+        </style>
+    </head>
+    <body>
+        <div class="card">
+            <h1>Event Input Required</h1>
+            <p class="event-name">Event: {event_name}</p>
+            <p class="prompt">{prompt}</p>
+            <p class="data-type">Expected type: <code>{data_type_name}</code></p>
+            <p class="request-id">Request ID: {request_id}</p>
+            <form action="/submit" method="post">
+                <input type="hidden" name="request_id" value="{request_id}">
+                <input type="hidden" name="data_type" value="{data_type_name}">
+                <input type="hidden" name="response_path" value="{response_path}">
+                {input_element}
+                <button type="submit">Submit</button>
+            </form>
+        </div>
+    </body>
+    </html>
+    """
+
+
+def get_submission_success_page(
+    request_id: str,
+    value: str,
+    data_type: str,
+    message: str,
+) -> str:
+    """HTML page displayed after successful submission."""
+    import html as html_module
+
+    return f"""
+    <!DOCTYPE html>
+    <html>
+    <head>
+        <title>Submission Successful</title>
+        <style>
+            body {{
+                font-family: Arial, sans-serif;
+                max-width: 500px;
+                margin: 25px auto;
+                padding: 20px;
+            }}
+            .card {{
+                background: #fff;
+                border-radius: 8px;
+                box-shadow: 0 2px 10px rgba(0,0,0,0.1);
+                padding: 30px;
+            }}
+            h1 {{ color: #4CAF50; margin-top: 0; }}
+            .message {{ color: #666; margin-bottom: 20px; font-size: 16px; }}
+            .details {{
+                background: #f9f9f9;
+                border-radius: 6px;
+                padding: 15px;
+                margin-top: 20px;
+            }}
+            .detail-row {{
+                display: flex;
+                justify-content: space-between;
+                padding: 8px 0;
+                border-bottom: 1px solid #eee;
+            }}
+            .detail-row:last-child {{ border-bottom: none; }}
+            .detail-label {{ font-weight: bold; color: #333; }}
+            .detail-value {{ color: #666; font-family: monospace; }}
+            .status-badge {{
+                display: inline-block;
+                background: #4CAF50;
+                color: white;
+                padding: 4px 12px;
+                border-radius: 12px;
+                font-size: 14px;
+            }}
+        </style>
+    </head>
+    <body>
+        <div class="card">
+            <h1>Submission Successful</h1>
+            <p class="message">{html_module.escape(message)}</p>
+            <div class="details">
+                <div class="detail-row">
+                    <span class="detail-label">Status</span>
+                    <span class="status-badge">Submitted</span>
+                </div>
+                <div class="detail-row">
+                    <span class="detail-label">Request ID</span>
+                    <span class="detail-value">{html_module.escape(request_id)}</span>
+                </div>
+                <div class="detail-row">
+                    <span class="detail-label">Value</span>
+                    <span class="detail-value">{html_module.escape(str(value))}</span>
+                </div>
+                <div class="detail-row">
+                    <span class="detail-label">Data Type</span>
+                    <span class="detail-value">{html_module.escape(data_type)}</span>
+                </div>
+            </div>
+        </div>
+    </body>
+    </html>
+    """
+
+
+def get_event_report_html(
+    form_url: str,
+    api_url: str,
+    curl_body: str,
+    type_name: str,
+) -> str:
+    """HTML report for the event input form shown in the Flyte UI."""
+    import html as html_module
+
+    return f"""
+        <style>
+            .hitl-container {{
+                font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                max-width: 800px;
+                margin: 20px auto;
+                padding: 20px;
+                background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
+                border-radius: 12px;
+                color: white;
+            }}
+            .hitl-header {{
+                text-align: center;
+                margin-bottom: 20px;
+            }}
+            .hitl-header h1 {{
+                margin: 0;
+                font-size: 1.8em;
+            }}
+            .hitl-section {{
+                background: rgba(255, 255, 255, 0.95);
+                border-radius: 8px;
+                padding: 20px;
+                margin-bottom: 15px;
+                color: #333;
+            }}
+            .hitl-section h2 {{
+                margin-top: 0;
+                color: #667eea;
+                font-size: 1.2em;
+                border-bottom: 2px solid #667eea;
+                padding-bottom: 8px;
+            }}
+            .hitl-url {{
+                background: #f5f5f5;
+                padding: 12px;
+                border-radius: 6px;
+                font-family: 'Monaco', 'Menlo', monospace;
+                font-size: 0.9em;
+                word-break: break-all;
+                border-left: 4px solid #667eea;
+            }}
+            .hitl-url a {{
+                color: #667eea;
+                text-decoration: none;
+            }}
+            .hitl-url a:hover {{
+                text-decoration: underline;
+            }}
+            .hitl-code {{
+                background: #1e1e1e;
+                color: #d4d4d4;
+                padding: 15px;
+                border-radius: 6px;
+                font-family: 'Monaco', 'Menlo', monospace;
+                font-size: 0.85em;
+                overflow-x: auto;
+                white-space: pre-wrap;
+                word-break: break-all;
+            }}
+            .hitl-info {{
+                display: grid;
+                grid-template-columns: 120px 1fr;
+                gap: 8px;
+                margin-bottom: 15px;
+            }}
+            .hitl-info-label {{
+                font-weight: bold;
+                color: #667eea;
+            }}
+            .hitl-info-value {{
+                font-family: 'Monaco', 'Menlo', monospace;
+                font-size: 0.9em;
+            }}
+        </style>
+        <div class="hitl-container">
+            <div class="hitl-header">
+                <h1>Event Input Required</h1>
+            </div>
+
+            <div class="hitl-section">
+                <h2>Option 1: Web Form</h2>
+                <p>
+                Submit your input using <a href="{html_module.escape(form_url)}" target="_blank">this form</a>:
+                </p>
+            </div>
+
+            <div class="hitl-section">
+                <h2>Option 2: Programmatic API (curl)</h2>
+                <p>Use the following curl command to submit input programmatically:</p>
+                <div class="hitl-code">curl -X POST "{html_module.escape(api_url)}" \\
+  -H "Content-Type: application/json" \\
+  -H "Authorization: Bearer {{FLYTE_API_KEY}}" \\
+  -d '{html_module.escape(curl_body)}'</div>
+                <p style="margin-top: 15px; font-size: 0.9em; color: #666;">
+                    <strong>Note:</strong> Replace <code>{{your_value}}</code> with the actual value you want to
+                    submit. The value should match the expected type: <code>{html_module.escape(type_name)}</code>
+
+                    <p>Replace <code>{{FLYTE_API_KEY}}</code> with your Flyte API key.</p>
+                </p>
+            </div>
+        </div>
+        """

flyteplugins_hitl-2.0.6.dist-info/METADATA

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: flyteplugins-hitl
+Version: 2.0.6
+Summary: Human-in-the-Loop (HITL) plugin for Flyte
+Author: Flyte Contributors
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastapi
+Requires-Dist: uvicorn
+Requires-Dist: python-multipart
+Requires-Dist: aiofiles
+Requires-Dist: flyte
+
+# Flyte HITL Plugin
+
+Human-in-the-Loop (HITL) plugin for Flyte. This plugin provides an event-based API for pausing workflows and waiting for human input.
+
+## Installation
+
+```bash
+pip install flyteplugins-hitl
+```
+
+## Usage
+
+```python
+import flyte
+import flyteplugins.hitl as hitl
+
+task_env = flyte.TaskEnvironment(
+    name="my-hitl-workflow",
+    image=flyte.Image.from_debian_base(python_version=(3, 12)),
+    resources=flyte.Resources(cpu=1, memory="512Mi"),
+    depends_on=[hitl.env],
+)
+
+
+@task_env.task
+async def task1() -> int:
+    """First task - returns an automated value."""
+    return 42
+
+
+@task_env.task
+async def task2(x: int, y: int) -> int:
+    """Second task - combines automated and human input."""
+    return x + y
+
+
+@task_env.task(report=True)
+async def main() -> int:
+    """
+    Main workflow that orchestrates automated and human-in-the-loop tasks.
+
+    Flow:
+    1. task1() runs and returns an automated value (x)
+    2. Create an Event (serves the app) and wait for human input (y)
+    3. task2(x, y) combines both values and returns the result
+    """
+    print("Starting HITL workflow...")
+
+    # Step 1: Automated task
+    x = await task1()
+    print(f"task1 completed: x = {x}")
+
+    # Step 2: Human-in-the-loop using the Event-based API
+    # Create an event (this serves the app if not already running)
+    event = await hitl.new_event.aio(
+        "integer_input_event",
+        data_type=int,
+        scope="run",
+        prompt="What should I add to x?",
+    )
+    y = await event.wait.aio()
+    print(f"Event completed: y = {y}")
+
+    # Step 3: Combine results
+    result = await task2(x, y)
+    print(f"task2 completed: result = {result}")
+
+    return result
+
+
+if __name__ == "__main__":
+    flyte.init_from_config()
+    run = flyte.run(main)
+    print(f"Run URL: {run.url}")
+    run.wait()
+    print(f"Result: {run.outputs()}")
+```
+
+## Features
+
+- **Event-based API**: Create events that pause workflow execution until human input is received
+- **Web Form**: Automatically generates a web form for human input
+- **Programmatic API**: Submit input via curl or any HTTP client
+- **Type Safety**: Supports int, float, str, and bool data types
+
+## API Reference
+
+### `hitl.new_event(name, data_type, scope, prompt, ...)`
+
+Create a new human-in-the-loop event.
+
+**Parameters:**
+- `name` (str): A descriptive name for the event
+- `data_type` (Type): The expected type of the input (int, float, str, bool)
+- `scope` (str): The scope of the event. Currently only "run" is supported.
+- `prompt` (str): The prompt to display to the human
+- `timeout_seconds` (int): Maximum time to wait for human input (default: 3600)
+- `poll_interval_seconds` (int): How often to check for a response (default: 5)
+
+**Returns:** An `Event` object
+
+### `event.wait()` / `await event.wait.aio()`
+
+Wait for human input and return the result.
+
+**Returns:** The value provided by the human, converted to the event's data_type
+
+### `hitl.env`
+
+The `TaskEnvironment` that provides the HITL app infrastructure. Add this to your task environment's `depends_on` list.
+
+### `hitl.Event`
+
+The Event class for type annotations and advanced usage.

flyteplugins_hitl-2.0.6.dist-info/RECORD

@@ -0,0 +1,9 @@
+flyteplugins/hitl/__init__.py,sha256=ZZPgdpAslvolvyRShRpg2Cl74sOLZBeVg58iRX5MRcU,1231
+flyteplugins/hitl/_app.py,sha256=7FXofQSs0uTsk8y7_FO1fl5BeY1LRUsaCjq3XimP0WY,9091
+flyteplugins/hitl/_event.py,sha256=V7HmLShKMprQ9LbWPJ-7FXqDnw1HsxNstSdfO8YU6z4,13978
+flyteplugins/hitl/_helpers.py,sha256=LJZnViLf3691ErpECEWt0-voOdF5I50-slgRmxv2iJ4,1996
+flyteplugins/hitl/_html_templates.py,sha256=2ShgzZ3R5SHmHOj5DVz09ihan5ysLbPtbKjVh8u4eLE,11238
+flyteplugins_hitl-2.0.6.dist-info/METADATA,sha256=mtnJzVI2N097u0suJVJNnC2QM0AWKzY-Q9FLmTX_WgU,3472
+flyteplugins_hitl-2.0.6.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+flyteplugins_hitl-2.0.6.dist-info/top_level.txt,sha256=cgd779rPu9EsvdtuYgUxNHHgElaQvPn74KhB5XSeMBE,13
+flyteplugins_hitl-2.0.6.dist-info/RECORD,,

flyteplugins_hitl-2.0.6.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

flyteplugins_hitl-2.0.6.dist-info/top_level.txt

@@ -0,0 +1 @@
+flyteplugins