nemo-platform-plugin 0.1.0__py3-none-any.whl

nemo_platform_plugin/entity.py

@@ -0,0 +1,79 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Plugin entity interface — base classes for plugin entity definitions.
+
+Plugin authors import from here rather than ``nmp.common`` directly:
+
+    from nemo_platform_plugin.entity import NemoEntity
+
+See :class:`NemoEntity` for usage examples.
+"""
+
+from __future__ import annotations
+
+import abc
+from typing import Any, ClassVar
+
+from nemo_platform_plugin.entities import EntityBase
+
+
+class NemoEntity(EntityBase):
+    """Base class for plugin entity definitions.
+
+    Extends :class:`~nmp.common.entities.client.EntityBase` so subclasses work
+    transparently with :class:`~nemo_platform_plugin.entity_client.NemoEntitiesClient` for all
+    CRUD operations.
+
+    Every concrete subclass must declare its entity type via the ``entity_type``
+    class keyword.  Auto-derivation from the class name (the default ``EntityBase``
+    behaviour) is not permitted — it produces surprising strings for acronym-heavy
+    names (e.g. ``BLEUMetric`` → ``"b_l_e_u_metric"``) and makes the stored entity
+    type invisible at the definition site.
+
+    Abstract intermediate base classes (those with ``__abstract__ = True``,
+    ``ABC`` as a direct base, or any ``@abstractmethod`` members) are exempt
+    from the check.
+
+    Declare a concrete entity class with the ``entity_type`` keyword::
+
+        from nemo_platform_plugin.entity import NemoEntity
+
+        class MyEntity(NemoEntity, entity_type="my_entity"):
+            status: str = "pending"
+
+    Use ``__abstract__ = True`` or inherit from ``ABC`` on shared base classes
+    that should not have their own entity type::
+
+        class MyBaseEntity(NemoEntity):
+            __abstract__ = True
+            status: str = "pending"
+
+        from abc import ABC
+
+        class MyBaseEntity(NemoEntity, ABC):
+            status: str = "pending"
+    """
+
+    __abstract__: ClassVar[bool] = False
+
+    def __init_subclass__(cls, *, entity_type: str | None = None, **kwargs: Any) -> None:
+        super().__init_subclass__(**kwargs)
+
+        if entity_type is not None:
+            cls.__entity_type__ = entity_type
+            return
+
+        if cls.__dict__.get("__abstract__", False):
+            return
+        if any(getattr(v, "__isabstractmethod__", False) for v in cls.__dict__.values()):
+            return
+        if abc.ABC in cls.__bases__:
+            return
+
+        raise TypeError(
+            f"{cls.__qualname__} must pass entity_type='...' as a class keyword. "
+            f"Example: class {cls.__name__}(NemoEntity, entity_type='my_type'): ... "
+            f"To define an abstract intermediate base without an entity type, "
+            f"set __abstract__ = True on the class or inherit from ABC."
+        )

nemo_platform_plugin/entity_client.py

@@ -0,0 +1,54 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Entity store client for plugin authors.
+
+Plugin authors should import from here:
+
+    from nemo_platform_plugin.entity_client import (
+        NemoEntitiesClient,
+        NemoEntityNotFoundError,
+        NemoEntityConflictError,
+        NemoPaginationInfo,
+        get_entity_client,
+    )
+
+:class:`NemoEntitiesClient` is the primary interface for CRUD operations against
+the NeMo Platform entity store.  :class:`NemoEntityNotFoundError` and
+:class:`NemoEntityConflictError` are the two exceptions you will handle in
+virtually every route handler:
+
+    try:
+        item = await entity_client.get(Widget, name=name, workspace=workspace)
+    except NemoEntityNotFoundError:
+        raise HTTPException(status_code=404, detail=f"Widget '{name}' not found.")
+    except NemoEntityConflictError:
+        raise HTTPException(status_code=409, detail=f"Widget '{name}' already exists.")
+
+:func:`get_entity_client` is a FastAPI ``Depends()`` placeholder — the platform
+injects the real implementation at startup via ``app.dependency_overrides``.
+"""
+
+from nemo_platform_plugin.dependencies import (
+    get_entity_client,
+)
+from nemo_platform_plugin.entities import (
+    EntityClient as NemoEntitiesClient,
+)
+from nemo_platform_plugin.entities import (
+    EntityConflictError as NemoEntityConflictError,
+)
+from nemo_platform_plugin.entities import (
+    EntityNotFoundError as NemoEntityNotFoundError,
+)
+from nemo_platform_plugin.entities import (
+    PaginationInfo as NemoPaginationInfo,
+)
+
+__all__ = [
+    "NemoEntitiesClient",
+    "NemoEntityConflictError",
+    "NemoEntityNotFoundError",
+    "NemoPaginationInfo",
+    "get_entity_client",
+]

nemo_platform_plugin/filter_ops.py

@@ -0,0 +1,169 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Filter operation base types for the entity store.
+
+These are the minimal types needed by EntityClient and Filter. The full parsing
+engine (parse_json_filter, parse_bracket_filter, etc.) lives in nmp.common.api.filter.
+"""
+
+from abc import ABC, abstractmethod
+from enum import Enum
+from typing import Any, Dict, List
+
+from pydantic import BaseModel
+
+
+class FilterOperator(str, Enum):
+    """Filter operator."""
+
+    # Comparison operators
+    EQ = "$eq"
+    LIKE = "$like"
+    LT = "$lt"
+    LTE = "$lte"
+    GT = "$gt"
+    GTE = "$gte"
+    IN = "$in"
+    NIN = "$nin"
+
+    # Logical operators
+    OR = "$or"
+    AND = "$and"
+    NOT = "$not"
+
+    # Relationship operators
+    EXISTS = "$exists"
+
+
+class FilterRepository(ABC):
+    """Abstract base class for repository implementations that execute filter operations."""
+
+    @abstractmethod
+    def eq(self, field: str, value: Any) -> Any:
+        pass
+
+    @abstractmethod
+    def like(self, field: str, value: str) -> Any:
+        pass
+
+    @abstractmethod
+    def lt(self, field: str, value: Any) -> Any:
+        pass
+
+    @abstractmethod
+    def lte(self, field: str, value: Any) -> Any:
+        pass
+
+    @abstractmethod
+    def gt(self, field: str, value: Any) -> Any:
+        pass
+
+    @abstractmethod
+    def gte(self, field: str, value: Any) -> Any:
+        pass
+
+    @abstractmethod
+    def in_op(self, field: str, values: List[Any]) -> Any:
+        pass
+
+    @abstractmethod
+    def nin(self, field: str, values: List[Any]) -> Any:
+        pass
+
+    @abstractmethod
+    def and_op(self, operations: List[Any]) -> Any:
+        pass
+
+    @abstractmethod
+    def or_op(self, operations: List[Any]) -> Any:
+        pass
+
+    @abstractmethod
+    def not_op(self, operation: Any) -> Any:
+        pass
+
+    def relationship_exists(
+        self,
+        target_entity_type: str,
+        join_field: str,
+        child_condition: "FilterOperation | None",
+        negate: bool,
+    ) -> Any:
+        raise NotImplementedError("Relationship queries not supported by this repository")
+
+
+class FilterOperation(BaseModel, ABC):
+    """Abstract base class for filter operations."""
+
+    operator: FilterOperator
+
+    @abstractmethod
+    def apply(self, repository: FilterRepository) -> Any:
+        """Apply this operation using the given repository."""
+        pass
+
+    @abstractmethod
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        pass
+
+
+class ComparisonOperation(FilterOperation):
+    """Comparison operation (e.g., eq, lt, gte, like)."""
+
+    operator: FilterOperator
+    field: str
+    value: Any
+
+    def apply(self, repository: FilterRepository) -> Any:
+        if self.operator == FilterOperator.EQ:
+            return repository.eq(self.field, self.value)
+        elif self.operator == FilterOperator.LIKE:
+            return repository.like(self.field, self.value)
+        elif self.operator == FilterOperator.LT:
+            return repository.lt(self.field, self.value)
+        elif self.operator == FilterOperator.LTE:
+            return repository.lte(self.field, self.value)
+        elif self.operator == FilterOperator.GT:
+            return repository.gt(self.field, self.value)
+        elif self.operator == FilterOperator.GTE:
+            return repository.gte(self.field, self.value)
+        elif self.operator == FilterOperator.IN:
+            return repository.in_op(self.field, self.value)
+        elif self.operator == FilterOperator.NIN:
+            return repository.nin(self.field, self.value)
+        elif self.operator == FilterOperator.EXISTS:
+            raise NotImplementedError(
+                "$exists requires a relationship-aware repository (use the entities service parser)"
+            )
+        else:
+            raise ValueError(f"Unknown comparison operator: {self.operator}")
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert to dictionary."""
+        return {self.field: {self.operator.value: self.value}}
+
+
+class LogicalOperation(FilterOperation):
+    """Logical operation (and, or, not)."""
+
+    operator: FilterOperator
+    operations: List[FilterOperation]
+
+    def apply(self, repository: FilterRepository) -> Any:
+        if self.operator == FilterOperator.AND:
+            return repository.and_op([op.apply(repository) for op in self.operations])
+        elif self.operator == FilterOperator.OR:
+            return repository.or_op([op.apply(repository) for op in self.operations])
+        elif self.operator == FilterOperator.NOT:
+            if len(self.operations) != 1:
+                raise ValueError("NOT operation must have exactly one operand")
+            return repository.not_op(self.operations[0].apply(repository))
+        else:
+            raise ValueError(f"Unknown logical operator: {self.operator}")
+
+    def to_dict(self) -> Dict[str, Any]:
+        if self.operator == FilterOperator.NOT:
+            return {self.operator.value: self.operations[0].to_dict()}
+        return {self.operator.value: [op.to_dict() for op in self.operations]}

nemo_platform_plugin/function.py

@@ -0,0 +1,299 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Plugin function interface — what plugin authors implement for in-process functions.
+
+Plugin authors subclass :class:`NemoFunction` and register the class
+under the ``nemo.functions`` entry-point group. The platform mounts a
+``POST`` route per function on the plugin service (auto-derived path),
+and the CLI exposes ``nemo <plugin> <fn> run`` (in-process) and
+``nemo <plugin> <fn> submit`` (HTTP POST) for each. Functions never
+dispatch through a backend — they run in the plugin service's event
+loop, in the same request that triggered them.
+
+Mental model — *Function = spec → response | stream[frame]*:
+
+- **``spec``** — the inputs (plugin-authored Pydantic model). Validated
+  against :attr:`spec_schema` before :meth:`run` is called.
+- non-streaming → ``return`` a JSON-serializable value (typically a
+  Pydantic model).
+- streaming     → declare ``run`` as an ``async def`` returning an
+  ``AsyncIterator``/``AsyncGenerator`` and ``yield`` frames. The
+  route adapter detects the iterator return type and wraps it in a
+  ``StreamingResponse`` with ``application/x-ndjson`` (one
+  ``model_dump_json()`` line per frame).
+
+Single class, single method colour. ``run`` is **always**
+``async def`` — there is no sync twin and there is no class-level
+streaming flag. The only required ``ClassVar`` is :attr:`spec_schema`.
+
+Sync work inside :meth:`run` is a localised escape via
+``await asyncio.to_thread(...)`` (or anyio's ``to_thread.run_sync``);
+``def run`` is **not accepted** so plugin authors can't accidentally
+block the request loop.
+
+Example::
+
+    # my_plugin/functions/greet.py
+    from nemo_platform_plugin.function import NemoFunction
+    from pydantic import BaseModel
+
+    class GreetSpec(BaseModel):
+        name: str
+
+    class GreetResponse(BaseModel):
+        message: str
+
+    class GreetFunction(NemoFunction):
+        name        = "greet"
+        description = "Say hello to a name."
+        spec_schema = GreetSpec
+
+        async def run(self, spec: GreetSpec) -> GreetResponse:
+            return GreetResponse(message=f"Hello, {spec.name}!")
+
+    # pyproject.toml:
+    # [project.entry-points."nemo.functions"]
+    # my-plugin.greet = "my_plugin.functions.greet:GreetFunction"
+
+Entry-point key convention: ``<plugin-name>.<function-name>``, e.g.
+``example.greet``. The platform's
+:func:`~nemo_platform_plugin.discovery.discover_functions` resolves functions
+unambiguously across plugins; default-path mounting picks them up at
+service startup.
+"""
+
+from __future__ import annotations
+
+import inspect
+from abc import abstractmethod
+from collections.abc import AsyncIterator
+from typing import Any, ClassVar, Generic, TypeVar
+
+from nemo_platform_plugin._base import _NamedPlugin
+from pydantic import BaseModel
+
+SpecT = TypeVar("SpecT", bound=BaseModel)
+"""Per-function spec type. Bound to ``BaseModel`` so subclasses get a
+typed ``spec`` parameter (`async def run(self, spec: GreetSpec) -> ...`)
+without violating Liskov on the abstract base — see :class:`NemoFunction`.
+"""
+
+
+class NemoFunction(_NamedPlugin, Generic[SpecT]):
+    """Abstract base class for plugin-contributed in-process functions.
+
+    Subclasses declare their identity via class variables and implement
+    :meth:`run`. The platform auto-derives:
+
+    - A CLI subcommand tree: ``nemo <plugin> <fn> run|submit``.
+    - A FastAPI route on the plugin service:
+      ``POST /apis/<plugin>/v2/workspaces/{workspace}/<name>``
+      (override per-class via :attr:`endpoint`).
+
+    Identity:
+
+    .. attribute:: name
+        :type: str
+
+        Unique function name within the plugin (e.g. ``"greet"``).
+        Combined with the plugin name for the full entry-point key
+        (``"my-plugin.greet"``). The class declares only the suffix.
+
+    .. attribute:: description
+        :type: str
+
+        Human-readable description. Surfaces in CLI ``--help`` and as
+        the route's OpenAPI summary.
+
+    Spec schema:
+
+    .. attribute:: spec_schema
+        :type: type[SpecT]
+
+        Pydantic model for the function's inputs. The route adapter
+        validates the request body against it before invocation; the
+        local ``run`` verb validates the CLI-supplied spec the same
+        way. **Required** — the route factory and the CLI both need it
+        to generate a working surface. Tied to :data:`SpecT` so a
+        subclass like ``NemoFunction[GreetSpec]`` constrains
+        ``spec_schema`` to ``type[GreetSpec]`` for type-checkers (and
+        IDEs) without runtime cost.
+
+    Endpoint override:
+
+    .. attribute:: endpoint
+        :type: str | None
+
+        Override of the **trailing path segment** appended after
+        ``/apis/<plugin>/v2/workspaces/{workspace}``. Default is
+        ``/{name}``, producing the canonical
+        ``POST /apis/<plugin>/v2/workspaces/{workspace}/{name}``
+        route. Only the ``{name}`` placeholder is substituted; the
+        workspace placeholder stays as a FastAPI route parameter
+        because requests carry it per-call. Useful when a plugin
+        needs to preserve a legacy suffix (e.g. ``/{name}/v1`` or
+        ``/{name}-stream``) — it does **not** let a function
+        relocate itself outside its plugin's URL namespace. Leave
+        ``None`` to use the default.
+
+    Stream response start:
+
+    .. attribute:: send_headers_before_first_frame
+        :type: bool
+
+        For streaming functions, return ``StreamingResponse`` without
+        waiting for the first yielded frame. The default ``False`` keeps
+        exceptions raised before the first frame in the normal FastAPI
+        error path, so validation/setup failures can still become HTTP
+        ``4xx``/``5xx`` responses instead of failing after response
+        headers have been sent. Enable only for streams that
+        intentionally perform long pre-first-frame work and need
+        immediate response headers plus heartbeat injection during that
+        initial quiet period.
+
+    Lifecycle:
+
+    .. py:method:: run(spec, *, sdk=None, async_sdk=None, ctx=None)
+        :async:
+
+        Execute the function. ``spec`` is a validated
+        :attr:`spec_schema` instance. Optional keyword-only parameters
+        opt into framework-managed dependencies — see
+        :meth:`run_signature` for the contract.
+    """
+
+    # ------------------------------------------------------------------ #
+    # Identity                                                           #
+    # ------------------------------------------------------------------ #
+
+    name: ClassVar[str]
+    description: ClassVar[str] = ""
+
+    # ------------------------------------------------------------------ #
+    # Spec schema (required)                                             #
+    # ------------------------------------------------------------------ #
+
+    # ``ClassVar[type[SpecT]]`` ties the declared schema to the same
+    # type variable the class is generic over, so a subclass written as
+    # ``class GreetFunction(NemoFunction[GreetSpec])`` constrains
+    # ``spec_schema`` to ``type[GreetSpec]`` for type-checkers and IDEs.
+    # PEP 526 forbids type variables inside ``ClassVar``, so the suppression
+    # here is the standard escape hatch for the otherwise-correct shape.
+    spec_schema: ClassVar[type[SpecT]]  # type: ignore[misc]
+
+    # ------------------------------------------------------------------ #
+    # Endpoint override                                                  #
+    # ------------------------------------------------------------------ #
+
+    endpoint: ClassVar[str | None] = None
+
+    send_headers_before_first_frame: ClassVar[bool] = False
+
+    # ------------------------------------------------------------------ #
+    # Lifecycle                                                          #
+    # ------------------------------------------------------------------ #
+
+    # The abstract signature uses ``(*args, **kwargs) -> Any`` —
+    # the universal "callable" supertype — so every concrete override
+    # is automatically Liskov-compatible regardless of which framework
+    # DI parameters it opts into (``ctx`` / ``sdk`` / ``async_sdk``).
+    # Three reasons we don't tighten the base:
+    #
+    # - Subclasses come in two runtime flavours — coroutine functions
+    #   (non-streaming) and async generator functions (streaming) —
+    #   which Python types differently. A tighter base would make one
+    #   shape look incompatible to strict type checkers on every
+    #   override.
+    # - We still enforce async-ness at class-definition time in
+    #   :meth:`__init_subclass__`, so plugin authors can't accidentally
+    #   ship a sync ``def run`` that would block the request loop.
+    # - The actual contract (``spec`` is the first positional, kwargs
+    #   are framework-managed DI) is documented in the method
+    #   docstring and in :meth:`run_signature`. Plugin authors get IDE
+    #   help from their concrete ``async def run(self, spec: MySpec, ...)``
+    #   signature, not from the abstract.
+    @abstractmethod
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        """Execute the function and return a value or yield NDJSON frames.
+
+        Functions widen the signature with keyword-only parameters
+        (``ctx: FunctionContext``, ``sdk``, ``async_sdk``, ``is_local``) — the route
+        adapter and the local CLI both resolve those by parameter name.
+        Parameters that aren't resolvable fall back to whatever default
+        the signature declares; required parameters with no available
+        binding raise at call time, not at import.
+
+        ``run`` **must be ``async def``**. The class enforces this in
+        :meth:`__init_subclass__`. Sync work goes through
+        ``await asyncio.to_thread(...)``.
+
+        Args:
+            spec: Validated :attr:`spec_schema` instance.
+
+        Returns:
+            Either a JSON-serialisable value (typically a Pydantic
+            model — the route adapter calls ``model_dump_json`` on
+            ``BaseModel`` returns) **or** an
+            ``AsyncIterator``/``AsyncGenerator`` of frames (typically
+            Pydantic models — each frame is emitted as a single NDJSON
+            line on the wire). The shape is detected at request time
+            from the actual return value, not from a class-level flag.
+        """
+
+    # ------------------------------------------------------------------ #
+    # Class-level enforcement                                            #
+    # ------------------------------------------------------------------ #
+
+    def __init_subclass__(cls, **kwargs: object) -> None:
+        super().__init_subclass__(**kwargs)
+        # ``_NamedPlugin.__init_subclass__`` skips intermediate ABCs
+        # (anything that still has unimplemented abstract methods); we
+        # do the same here so abstract intermediate bases can declare
+        # ``run`` without forcing it to be coroutine-typed.
+        run_attr = cls.__dict__.get("run")
+        if run_attr is None:
+            return
+        if getattr(run_attr, "__isabstractmethod__", False):
+            return
+        # Both ``async def`` (coroutine function) and ``async def``
+        # with ``yield`` (async generator function) are accepted —
+        # streaming functions are async generators, non-streaming ones
+        # are coroutines that return a value. Plain ``def`` for either
+        # would block the request loop and is rejected here so plugin
+        # authors get the error at import, not at request time.
+        if not (inspect.iscoroutinefunction(run_attr) or inspect.isasyncgenfunction(run_attr)):
+            raise TypeError(
+                f"{cls.__qualname__}.run must be `async def` — NemoFunction "
+                f"requires an async coroutine or async generator (use "
+                f"`await asyncio.to_thread(...)` for sync work). See "
+                f"nemo_platform_plugin.function for the contract."
+            )
+
+    @classmethod
+    def run_signature(cls) -> inspect.Signature:
+        """Return :meth:`run`'s :class:`inspect.Signature`.
+
+        Cheap helper used by the route adapter and local CLI to
+        discover which framework-managed parameters the function opts
+        into (``ctx``, ``sdk``, ``async_sdk``, ``is_local``). Plugin authors don't
+        normally call this — it's part of the framework contract.
+        """
+        return inspect.signature(cls.run)
+
+
+def returns_async_iterator(value: object) -> bool:
+    """Return ``True`` when *value* is an async iterator/generator.
+
+    Used by :func:`nemo_platform_plugin.functions.routes.add_function_routes` to
+    branch between ``StreamingResponse`` (NDJSON) and a plain JSON
+    response. Kept on the public module so callers (e.g. tests) can
+    exercise the same predicate the route uses.
+
+    Recognises both ``AsyncIterator`` (anything with ``__aiter__``) and
+    bare async generators.
+    """
+    return isinstance(value, AsyncIterator) or inspect.isasyncgen(value)
+
+
+__all__ = ["NemoFunction", "returns_async_iterator"]

nemo_platform_plugin/function_context.py

@@ -0,0 +1,61 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""Runtime context handed to :meth:`NemoFunction.run`.
+
+A function context carries the request-scope facts a function may need
+without forcing every signature to take them: the workspace the
+caller scoped the request to, and a request id for log correlation.
+
+The context is intentionally narrower than :class:`JobContext`:
+
+- No ``storage`` — functions run in the request path, not in a task
+  container; if a function needs to land artifacts it goes through
+  the SDK like any other request handler.
+- No ``results`` sink — the function's response (or NDJSON stream)
+  *is* the result channel.
+- No ``principal`` — auth-on-behalf-of support is handled by the
+  platform's auth middleware and cuts across functions and routes
+  alike. Adding a per-call principal slot here without the cross-cutting fix
+  would lock in a half-finished surface; the slot lands when the
+  cross-cutting fix does.
+
+Plugin authors opt in by declaring a keyword-only parameter named
+``ctx`` on :meth:`NemoFunction.run`; the route adapter and the local
+CLI both honour signature-based DI.
+
+Example::
+
+    class GreetFunction(NemoFunction):
+        spec_schema = GreetSpec
+
+        async def run(self, spec, *, ctx: FunctionContext) -> dict:
+            logger.info("greet workspace=%s req=%s", ctx.workspace, ctx.request_id)
+            return {"message": f"Hello, {spec.name}!"}
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(kw_only=True)
+class FunctionContext:
+    """Per-request context for :meth:`NemoFunction.run`.
+
+    Attributes:
+        workspace: Workspace scope the request was made against.
+            For local CLI runs this comes from ``--workspace`` and
+            defaults to ``"default"``; for HTTP runs it's the path
+            parameter the route adapter pulls from
+            ``/v2/workspaces/{workspace}/...``.
+        request_id: Optional correlation id for tracing. Set from the
+            inbound ``X-Request-ID`` header by the route adapter; left
+            ``None`` for local CLI runs unless the caller passes one.
+    """
+
+    workspace: str
+    request_id: str | None = None
+
+
+__all__ = ["FunctionContext"]