azure-functions-langgraph 0.5.0__py3-none-any.whl

azure_functions_langgraph/__init__.py

@@ -0,0 +1,130 @@
+"""Azure Functions LangGraph — Deploy LangGraph agents as Azure Functions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+__version__ = "0.5.0"
+
+if TYPE_CHECKING:
+    from azure_functions_langgraph.app import LangGraphApp
+    from azure_functions_langgraph.contracts import (
+        AppMetadata,
+        ErrorResponse,
+        GraphInfo,
+        HealthResponse,
+        InvokeRequest,
+        InvokeResponse,
+        RegisteredGraphMetadata,
+        RouteMetadata,
+        StateResponse,
+        StreamRequest,
+    )
+    from azure_functions_langgraph.protocols import (
+        CloneableGraph,
+        InvocableGraph,
+        LangGraphLike,
+        StatefulGraph,
+        StreamableGraph,
+    )
+
+
+def __getattr__(name: str) -> object:
+    if name == "LangGraphApp":
+        try:
+            from azure_functions_langgraph.app import LangGraphApp
+
+            return LangGraphApp
+        except ImportError as exc:
+            raise ImportError(
+                "LangGraphApp requires 'azure-functions' and 'langgraph'. "
+                "Install them with: pip install azure-functions-langgraph"
+            ) from exc
+    # Contracts
+    if name == "InvokeRequest":
+        from azure_functions_langgraph.contracts import InvokeRequest
+
+        return InvokeRequest
+    if name == "InvokeResponse":
+        from azure_functions_langgraph.contracts import InvokeResponse
+
+        return InvokeResponse
+    if name == "StreamRequest":
+        from azure_functions_langgraph.contracts import StreamRequest
+
+        return StreamRequest
+    if name == "HealthResponse":
+        from azure_functions_langgraph.contracts import HealthResponse
+
+        return HealthResponse
+    if name == "GraphInfo":
+        from azure_functions_langgraph.contracts import GraphInfo
+
+        return GraphInfo
+    if name == "ErrorResponse":
+        from azure_functions_langgraph.contracts import ErrorResponse
+
+        return ErrorResponse
+    if name == "StateResponse":
+        from azure_functions_langgraph.contracts import StateResponse
+
+        return StateResponse
+    # Metadata dataclasses
+    if name == "AppMetadata":
+        from azure_functions_langgraph.contracts import AppMetadata
+
+        return AppMetadata
+    if name == "RegisteredGraphMetadata":
+        from azure_functions_langgraph.contracts import RegisteredGraphMetadata
+
+        return RegisteredGraphMetadata
+    if name == "RouteMetadata":
+        from azure_functions_langgraph.contracts import RouteMetadata
+
+        return RouteMetadata
+    # Protocols
+    if name == "InvocableGraph":
+        from azure_functions_langgraph.protocols import InvocableGraph
+
+        return InvocableGraph
+    if name == "StreamableGraph":
+        from azure_functions_langgraph.protocols import StreamableGraph
+
+        return StreamableGraph
+    if name == "LangGraphLike":
+        from azure_functions_langgraph.protocols import LangGraphLike
+
+        return LangGraphLike
+    if name == "StatefulGraph":
+        from azure_functions_langgraph.protocols import StatefulGraph
+
+        return StatefulGraph
+    if name == "CloneableGraph":
+        from azure_functions_langgraph.protocols import CloneableGraph
+
+        return CloneableGraph
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "LangGraphApp",
+    "__version__",
+    # Contracts
+    "InvokeRequest",
+    "InvokeResponse",
+    "StreamRequest",
+    "HealthResponse",
+    "GraphInfo",
+    "ErrorResponse",
+    "StateResponse",
+    # Metadata
+    "AppMetadata",
+    "RegisteredGraphMetadata",
+    "RouteMetadata",
+    # Protocols
+    "InvocableGraph",
+    "StreamableGraph",
+    "LangGraphLike",
+    "StatefulGraph",
+    "CloneableGraph",
+]

azure_functions_langgraph/_handlers.py

@@ -0,0 +1,267 @@
+"""Internal request handlers for native graph endpoints.
+
+These are standalone functions extracted from ``LangGraphApp`` to keep
+``app.py`` focused on registration and route wiring.  Each function
+receives only the explicit dependencies it needs — no reference to
+``LangGraphApp`` itself.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Any
+
+import azure.functions as func
+
+from azure_functions_langgraph._validation import (
+    validate_body_size,
+    validate_input_structure,
+    validate_thread_id,
+)
+from azure_functions_langgraph.contracts import (
+    ErrorResponse,
+    InvokeRequest,
+    InvokeResponse,
+    StateResponse,
+    StreamRequest,
+)
+from azure_functions_langgraph.protocols import StatefulGraph, StreamableGraph
+
+logger = logging.getLogger(__name__)
+
+
+# ------------------------------------------------------------------
+# Shared helper
+# ------------------------------------------------------------------
+
+
+def _error_response(status_code: int, detail: str) -> func.HttpResponse:
+    body = ErrorResponse(error="error", detail=detail)
+    return func.HttpResponse(
+        body=body.model_dump_json(),
+        mimetype="application/json",
+        status_code=status_code,
+    )
+
+
+# ------------------------------------------------------------------
+# Invoke handler
+# ------------------------------------------------------------------
+
+
+def handle_invoke(
+    req: func.HttpRequest,
+    reg: Any,
+    *,
+    max_request_body_bytes: int,
+    max_input_depth: int,
+    max_input_nodes: int,
+) -> func.HttpResponse:
+    """Handle a synchronous invoke request."""
+    # Body size check — reject before parsing
+    raw_body = req.get_body()
+    size_err = validate_body_size(raw_body, max_request_body_bytes)
+    if size_err:
+        return _error_response(400, size_err)
+
+    try:
+        body = req.get_json()
+    except ValueError:
+        return _error_response(400, "Invalid JSON body")
+
+    try:
+        request = InvokeRequest.model_validate(body)
+    except Exception as exc:
+        return _error_response(422, f"Validation error: {exc}")
+
+    # Structural validation on user-supplied fields
+    structure_err = validate_input_structure(
+        request.input, max_depth=max_input_depth, max_nodes=max_input_nodes,
+    )
+    if structure_err:
+        return _error_response(400, structure_err)
+    if request.config:
+        config_err = validate_input_structure(
+            request.config, max_depth=max_input_depth, max_nodes=max_input_nodes,
+        )
+        if config_err:
+            return _error_response(400, config_err)
+
+    config = request.config or {}
+    try:
+        result = reg.graph.invoke(request.input, config=config)
+    except Exception as exc:
+        logger.exception("Graph %s invoke failed", reg.name)
+        _ = exc
+        return _error_response(500, "Graph execution failed")
+
+    output = result if isinstance(result, dict) else {"result": result}
+    response = InvokeResponse(output=output)
+    return func.HttpResponse(
+        body=response.model_dump_json(),
+        mimetype="application/json",
+        status_code=200,
+    )
+
+
+# ------------------------------------------------------------------
+# Stream handler
+# ------------------------------------------------------------------
+
+
+def handle_stream(
+    req: func.HttpRequest,
+    reg: Any,
+    *,
+    max_stream_response_bytes: int,
+    max_request_body_bytes: int,
+    max_input_depth: int,
+    max_input_nodes: int,
+) -> func.HttpResponse:
+    """Handle a streaming request.
+
+    Returns a **buffered** SSE-formatted response.  All stream chunks are
+    collected first, then returned in a single HTTP response.  This is a
+    known v0.1 limitation — true chunked streaming will follow once Azure
+    Functions Python HTTP streaming is fully stable.
+    """
+    if not reg.stream_enabled:
+        return _error_response(501, f"Graph {reg.name!r} is configured as invoke-only")
+
+    if not isinstance(reg.graph, StreamableGraph):
+        return _error_response(501, f"Graph {reg.name!r} does not support streaming")
+
+    # Body size check — reject before parsing
+    raw_body = req.get_body()
+    size_err = validate_body_size(raw_body, max_request_body_bytes)
+    if size_err:
+        return _error_response(400, size_err)
+
+    try:
+        body = req.get_json()
+    except ValueError:
+        return _error_response(400, "Invalid JSON body")
+
+    try:
+        request = StreamRequest.model_validate(body)
+    except Exception as exc:
+        return _error_response(422, f"Validation error: {exc}")
+
+    # Structural validation on user-supplied fields
+    structure_err = validate_input_structure(
+        request.input, max_depth=max_input_depth, max_nodes=max_input_nodes,
+    )
+    if structure_err:
+        return _error_response(400, structure_err)
+    if request.config:
+        config_err = validate_input_structure(
+            request.config, max_depth=max_input_depth, max_nodes=max_input_nodes,
+        )
+        if config_err:
+            return _error_response(400, config_err)
+
+    config = request.config or {}
+    chunks: list[str] = []
+    buffered_bytes = 0
+
+    def _append_chunk(chunk: str) -> bool:
+        nonlocal buffered_bytes
+        chunk_bytes = len(chunk.encode())
+        if buffered_bytes + chunk_bytes > max_stream_response_bytes:
+            error_payload = json.dumps(
+                {
+                    "error": (
+                        "stream response exceeded max buffered size "
+                        f"({max_stream_response_bytes} bytes)"
+                    )
+                }
+            )
+            chunks.append(f"event: error\ndata: {error_payload}\n\n")
+            return False
+        chunks.append(chunk)
+        buffered_bytes += chunk_bytes
+        return True
+
+    try:
+        for event in reg.graph.stream(
+            request.input,
+            config=config,
+            stream_mode=request.stream_mode,
+        ):
+            serialized = json.dumps(
+                event if isinstance(event, dict) else {"data": str(event)},
+                default=str,
+            )
+            if not _append_chunk(f"event: data\ndata: {serialized}\n\n"):
+                break
+    except Exception as exc:
+        logger.exception("Graph %s stream failed", reg.name)
+        _ = exc
+        error_payload = json.dumps({"error": "stream processing failed"})
+        _append_chunk(f"event: error\ndata: {error_payload}\n\n")
+
+    _append_chunk("event: end\ndata: {}\n\n")
+
+    return func.HttpResponse(
+        body="".join(chunks),
+        mimetype="text/event-stream",
+        status_code=200,
+        headers={
+            "Cache-Control": "no-cache",
+            "X-Accel-Buffering": "no",
+        },
+    )
+
+
+# ------------------------------------------------------------------
+# State handler
+# ------------------------------------------------------------------
+
+
+def handle_state(
+    req: func.HttpRequest,
+    reg: Any,
+) -> func.HttpResponse:
+    """Handle a GET request for thread state."""
+    if not isinstance(reg.graph, StatefulGraph):
+        return _error_response(
+            409, f"Graph {reg.name!r} does not support state retrieval"
+        )
+
+    thread_id = req.route_params.get("thread_id")
+    if not thread_id:
+        return _error_response(400, "Missing thread_id in URL path")
+    tid_err = validate_thread_id(thread_id)
+    if tid_err:
+        return _error_response(400, tid_err)
+
+    config: dict[str, Any] = {"configurable": {"thread_id": thread_id}}
+
+    try:
+        snapshot = reg.graph.get_state(config)
+    except (KeyError, ValueError):
+        logger.warning(
+            "Graph %s: thread %s not found", reg.name, thread_id
+        )
+        return _error_response(404, f"Thread {thread_id!r} not found")
+    except Exception:
+        logger.exception(
+            "Graph %s get_state failed for thread %s", reg.name, thread_id
+        )
+        return _error_response(
+            500, "Internal error while retrieving thread state"
+        )
+
+    values = snapshot.values if isinstance(snapshot.values, dict) else {}
+    next_nodes: list[str] = list(snapshot.next) if hasattr(snapshot, "next") else []
+    metadata = (
+        dict(snapshot.metadata) if hasattr(snapshot, "metadata") and snapshot.metadata else None
+    )
+
+    response = StateResponse(values=values, next=next_nodes, metadata=metadata)
+    return func.HttpResponse(
+        body=json.dumps(response.model_dump(), default=str),
+        mimetype="application/json",
+        status_code=200,
+    )

azure_functions_langgraph/_validation.py

@@ -0,0 +1,169 @@
+"""Transport-agnostic input validation utilities.
+
+All validators are pure functions that return an error message string on
+failure or ``None`` on success.  Route layers (native and platform) are
+responsible for converting error messages into their own HTTP response
+format (``ErrorResponse`` vs ``_platform_error``).
+
+.. versionadded:: 0.3.0
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any, Optional
+
+# ---------------------------------------------------------------------------
+# Graph-name / assistant-id validation
+# ---------------------------------------------------------------------------
+
+#: Pattern for valid graph names: starts with letter, then letters/digits/
+#: underscores/hyphens, 1–64 characters total.
+_GRAPH_NAME_RE = re.compile(r"^[a-zA-Z][a-zA-Z0-9_-]{0,63}$")
+
+
+def validate_graph_name(name: str) -> Optional[str]:
+    """Validate a graph registration name or assistant_id.
+
+    Returns an error message if invalid, ``None`` if valid.
+    """
+    if not name:
+        return "Graph name must not be empty"
+    if not _GRAPH_NAME_RE.match(name):
+        return (
+            f"Invalid graph name {name!r}. "
+            "Must start with a letter, contain only letters, digits, "
+            "underscores or hyphens, and be 1–64 characters."
+        )
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Thread-id validation
+# ---------------------------------------------------------------------------
+
+#: Maximum allowed thread_id length.
+_MAX_THREAD_ID_LENGTH = 256
+
+#: Pattern for printable ASCII (space through tilde) — excludes control chars.
+_PRINTABLE_RE = re.compile(r"^[\x20-\x7e]+$")
+
+
+def validate_thread_id(thread_id: str) -> Optional[str]:
+    """Validate a thread_id string (permissive — non-empty printable, max length).
+
+    Returns an error message if invalid, ``None`` if valid.
+    """
+    if not thread_id:
+        return "Thread ID must not be empty"
+    if len(thread_id) > _MAX_THREAD_ID_LENGTH:
+        return (
+            f"Thread ID exceeds maximum length of {_MAX_THREAD_ID_LENGTH} characters"
+        )
+    if not _PRINTABLE_RE.match(thread_id):
+        return "Thread ID must contain only printable ASCII characters"
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Request body size validation
+# ---------------------------------------------------------------------------
+
+
+def validate_body_size(body: bytes, max_bytes: int) -> Optional[str]:
+    """Check that *body* does not exceed *max_bytes*.
+
+    Returns an error message if too large, ``None`` if within limit.
+    Must be called **before** JSON parsing to reject oversized payloads early.
+    """
+    if len(body) > max_bytes:
+        return (
+            f"Request body too large: {len(body)} bytes "
+            f"(max {max_bytes} bytes)"
+        )
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Input / config depth and node-count validation
+# ---------------------------------------------------------------------------
+
+
+def _count_depth_and_nodes(
+    data: Any,
+    current_depth: int,
+    max_depth: int,
+    node_count: int,
+    max_nodes: int,
+) -> tuple[int, Optional[str]]:
+    """Recursively count depth and nodes.
+
+    Returns ``(updated_node_count, error_message_or_none)``.
+    """
+    if current_depth > max_depth:
+        return node_count, (
+            f"Input exceeds maximum nesting depth of {max_depth}"
+        )
+    if node_count > max_nodes:
+        return node_count, (
+            f"Input exceeds maximum node count of {max_nodes}"
+        )
+
+    if isinstance(data, dict):
+        for value in data.values():
+            node_count += 1
+            if node_count > max_nodes:
+                return node_count, (
+                    f"Input exceeds maximum node count of {max_nodes}"
+                )
+            node_count, err = _count_depth_and_nodes(
+                value, current_depth + 1, max_depth, node_count, max_nodes
+            )
+            if err:
+                return node_count, err
+    elif isinstance(data, list):
+        for item in data:
+            node_count += 1
+            if node_count > max_nodes:
+                return node_count, (
+                    f"Input exceeds maximum node count of {max_nodes}"
+                )
+            node_count, err = _count_depth_and_nodes(
+                item, current_depth + 1, max_depth, node_count, max_nodes
+            )
+            if err:
+                return node_count, err
+
+    return node_count, None
+
+
+def validate_input_structure(
+    data: Any,
+    *,
+    max_depth: int = 32,
+    max_nodes: int = 10_000,
+) -> Optional[str]:
+    """Validate nesting depth and total node count of user-supplied data.
+
+    Intended for the ``input`` and ``config``/``configurable`` fields —
+    the only fields that can contain arbitrarily deep user data.
+
+    Returns an error message if invalid, ``None`` if valid.
+    """
+    if not isinstance(data, (dict, list)):
+        # Scalars are always fine
+        return None
+    _, err = _count_depth_and_nodes(data, 1, max_depth, 0, max_nodes)
+    return err
+
+
+# ---------------------------------------------------------------------------
+# Public surface
+# ---------------------------------------------------------------------------
+
+__all__ = [
+    "validate_graph_name",
+    "validate_thread_id",
+    "validate_body_size",
+    "validate_input_structure",
+]