agenta 0.57.0__py3-none-any.whl → 0.65.0__py3-none-any.whl

agenta/sdk/middlewares/running/normalizer.py

@@ -0,0 +1,321 @@
+# /agenta/sdk/middlewares/running/normalizer.py
+import inspect
+from typing import Any, Dict, Callable, Union
+from inspect import isawaitable, isasyncgen, isgenerator
+from traceback import format_exception
+from uuid import UUID
+
+
+from agenta.sdk.utils.exceptions import suppress
+from agenta.sdk.models.workflows import (
+    WorkflowServiceStatus,
+    WorkflowServiceRequestData,
+    WorkflowServiceResponseData,
+    WorkflowServiceRequest,
+    WorkflowServiceBatchResponse,
+    WorkflowServiceStreamResponse,
+)
+from agenta.sdk.workflows.errors import ErrorStatus
+from agenta.sdk.contexts.running import RunningContext
+from agenta.sdk.contexts.tracing import TracingContext
+
+
+class NormalizerMiddleware:
+    """Middleware that normalizes workflow service requests and responses.
+
+    This middleware performs two key normalization operations:
+
+    1. **Request Normalization**: Transforms a WorkflowServiceRequest into the appropriate
+       keyword arguments for the workflow handler function by:
+       - Mapping request data fields to handler function parameters
+       - Extracting inputs from request.data.inputs and mapping them to function parameters
+       - Handling special parameters like 'request' and WorkflowServiceRequestData fields
+       - Supporting **kwargs expansion for additional fields
+
+    2. **Response Normalization**: Transforms handler function results into standardized
+       WorkflowServiceBatchResponse or WorkflowServiceStreamResponse objects by:
+       - Handling various return types (plain values, awaitables, generators, async generators)
+       - Aggregating streaming results into batches when aggregate flag is set
+       - Extracting trace_id and span_id from TracingContext for observability
+       - Wrapping raw outputs in proper response structures
+
+    The middleware ensures consistent interfaces between the workflow service layer and
+    the actual handler functions, allowing handlers to use simple function signatures
+    while maintaining structured request/response formats at the service boundary.
+    """
+
+    DATA_FIELDS = set(("request",)) | set(
+        WorkflowServiceRequestData.model_fields.keys()
+    )
+
+    async def _normalize_request(
+        self,
+        request: WorkflowServiceRequest,
+        handler: Callable,
+    ) -> Dict[str, Any]:
+        """Transform a WorkflowServiceRequest into kwargs for the handler function.
+
+        Inspects the handler's function signature and maps the request data to the
+        appropriate parameter names and values. The mapping follows this priority order:
+
+        1. If parameter name is 'request': passes the entire WorkflowServiceRequest
+        2. If parameter name matches DATA_FIELDS (like 'inputs', 'outputs', 'parameters'):
+           extracts that field from request.data
+        3. If parameter is **kwargs: includes all unconsumed DATA_FIELDS
+        4. Otherwise: looks up the parameter name in request.data.inputs dict
+
+        Args:
+            request: The workflow service request containing inputs and data
+            handler: The callable workflow handler whose signature to inspect
+
+        Returns:
+            Dictionary mapping parameter names to values for calling the handler
+        """
+        sig = inspect.signature(handler)
+        params = sig.parameters
+        normalized: Dict[str, Any] = {}
+        consumed = set()
+
+        for name, param in params.items():
+            if name == "request":
+                normalized[name] = request
+                consumed.add(name)
+
+            elif name in self.DATA_FIELDS:
+                normalized[name] = (
+                    getattr(request.data, name, None) if request.data else None
+                )
+                consumed.add(name)
+
+            elif param.kind == inspect.Parameter.VAR_KEYWORD:
+                if request.data:
+                    for f in self.DATA_FIELDS - consumed:
+                        normalized[f] = getattr(request.data, f, None)
+                consumed |= self.DATA_FIELDS
+
+            else:
+                if request.data and isinstance(request.data.inputs, dict):
+                    if name in request.data.inputs:
+                        normalized[name] = request.data.inputs[name]
+                        consumed.add(name)
+                        continue
+                normalized[name] = None
+
+        return normalized
+
+    async def _normalize_response(
+        self,
+        result: Any,
+    ) -> Union[
+        WorkflowServiceBatchResponse,
+        WorkflowServiceStreamResponse,
+    ]:
+        if isawaitable(result):
+            result = await result
+
+        if isinstance(
+            result, (WorkflowServiceBatchResponse, WorkflowServiceStreamResponse)
+        ):
+            trace_id = None
+            span_id = None
+
+            with suppress():
+                link = (TracingContext.get().link) or {}
+
+                _trace_id = link.get("trace_id") if link else None  # in int format
+                _span_id = link.get("span_id") if link else None  # in int format
+
+                trace_id = UUID(int=_trace_id).hex if _trace_id else None
+                span_id = UUID(int=_span_id).hex[16:] if _span_id else None
+
+            result.trace_id = trace_id
+            result.span_id = span_id
+
+            return result
+
+        if isasyncgen(result):
+            if RunningContext.get().aggregate:
+                collected = [item async for item in result]
+
+                trace_id = None
+                span_id = None
+
+                with suppress():
+                    link = (TracingContext.get().link) or {}
+
+                    _trace_id = link.get("trace_id") if link else None  # in int format
+                    _span_id = link.get("span_id") if link else None  # in int format
+
+                    trace_id = UUID(int=_trace_id).hex if _trace_id else None
+                    span_id = UUID(int=_span_id).hex[16:] if _span_id else None
+
+                return WorkflowServiceBatchResponse(
+                    data=WorkflowServiceResponseData(outputs=collected),
+                    trace_id=trace_id,
+                    span_id=span_id,
+                )
+
+            async def iterator():
+                async for item in result:
+                    yield item
+
+            trace_id = None
+            span_id = None
+
+            with suppress():
+                link = (TracingContext.get().link) or {}
+
+                _trace_id = link.get("trace_id") if link else None  # in int format
+                _span_id = link.get("span_id") if link else None  # in int format
+
+                trace_id = UUID(int=_trace_id).hex if _trace_id else None
+                span_id = UUID(int=_span_id).hex[16:] if _span_id else None
+
+            return WorkflowServiceStreamResponse(
+                generator=iterator,
+                trace_id=trace_id,
+                span_id=span_id,
+            )
+
+        if isgenerator(result):
+            if RunningContext.get().aggregate:
+                collected = list(result)
+
+                trace_id = None
+                span_id = None
+
+                with suppress():
+                    link = (TracingContext.get().link) or {}
+
+                    _trace_id = link.get("trace_id") if link else None  # in int format
+                    _span_id = link.get("span_id") if link else None  # in int format
+
+                    trace_id = UUID(int=_trace_id).hex if _trace_id else None
+                    span_id = UUID(int=_span_id).hex[16:] if _span_id else None
+
+                return WorkflowServiceBatchResponse(
+                    data=WorkflowServiceResponseData(outputs=collected),
+                    trace_id=trace_id,
+                    span_id=span_id,
+                )
+
+            async def iterator():
+                for item in result:
+                    yield item
+
+            trace_id = None
+            span_id = None
+
+            with suppress():
+                link = (TracingContext.get().link) or {}
+
+                _trace_id = link.get("trace_id") if link else None  # in int format
+                _span_id = link.get("span_id") if link else None  # in int format
+
+                trace_id = UUID(int=_trace_id).hex if _trace_id else None
+                span_id = UUID(int=_span_id).hex[16:] if _span_id else None
+
+            return WorkflowServiceStreamResponse(
+                generator=iterator,
+                trace_id=trace_id,
+                span_id=span_id,
+            )
+
+        trace_id = None
+        span_id = None
+
+        with suppress():
+            link = (TracingContext.get().link) or {}
+
+            _trace_id = link.get("trace_id") if link else None  # in int format
+            _span_id = link.get("span_id") if link else None  # in int format
+
+            trace_id = UUID(int=_trace_id).hex if _trace_id else None
+            span_id = UUID(int=_span_id).hex[16:] if _span_id else None
+
+        return WorkflowServiceBatchResponse(
+            data=WorkflowServiceResponseData(outputs=result),
+            trace_id=trace_id,
+            span_id=span_id,
+        )
+
+    async def _normalize_exception(
+        self,
+        exc: Exception,
+    ) -> WorkflowServiceBatchResponse:
+        error_status = None
+
+        if isinstance(exc, ErrorStatus):
+            error_status = WorkflowServiceStatus(
+                type=exc.type,
+                code=exc.code,
+                message=exc.message,
+                stacktrace=exc.stacktrace,
+            )
+        else:
+            type = "https://agenta.ai/docs/errors#v1:sdk:unknown-workflow-invoke-error"
+
+            code = getattr(exc, "status_code") if hasattr(exc, "status_code") else 500
+
+            if code in [401, 403]:
+                code = 424
+
+            message = str(exc) or "Internal Server Error"
+
+            stacktrace = format_exception(
+                exc,  # type: ignore
+                value=exc,
+                tb=exc.__traceback__,
+            )
+
+            error_status = WorkflowServiceStatus(
+                type=type,
+                code=code,
+                message=message,
+                stacktrace=stacktrace,
+            )
+
+        trace_id = None
+        span_id = None
+
+        with suppress():
+            link = (TracingContext.get().link) or {}
+
+            _trace_id = link.get("trace_id") if link else None  # in int format
+            _span_id = link.get("span_id") if link else None  # in int format
+
+            trace_id = UUID(int=_trace_id).hex if _trace_id else None
+            span_id = UUID(int=_span_id).hex[16:] if _span_id else None
+
+        error_response = WorkflowServiceBatchResponse(
+            status=error_status,
+            trace_id=trace_id,
+            span_id=span_id,
+        )
+
+        return error_response
+
+    async def __call__(
+        self,
+        request: WorkflowServiceRequest,
+        call_next: Callable[[WorkflowServiceRequest], Any],
+    ):
+        ctx = RunningContext.get()
+        handler = ctx.handler
+
+        if not handler:
+            raise RuntimeError("NormalizerMiddleware: no handler set in context")
+
+        kwargs = await self._normalize_request(request, handler)
+
+        try:
+            response = handler(**kwargs)
+
+            normalized = await self._normalize_response(response)
+
+        except Exception as exception:
+            normalized = await self._normalize_exception(exception)
+
+            return normalized
+
+        return normalized

agenta/sdk/middlewares/running/resolver.py

@@ -0,0 +1,161 @@
+# /agenta/sdk/middlewares/running/resolver.py
+from typing import Callable, Any, Optional
+
+from agenta.sdk.utils.logging import get_module_logger
+from agenta.sdk.models.workflows import (
+    WorkflowServiceRequestData,
+    WorkflowServiceResponseData,
+    WorkflowServiceRequest,
+    WorkflowServiceInterface,
+    WorkflowServiceConfiguration,
+)
+from agenta.sdk.contexts.running import RunningContext
+from agenta.sdk.workflows.utils import (
+    retrieve_handler,
+    retrieve_interface,
+    retrieve_configuration,
+)
+from agenta.sdk.workflows.errors import InvalidInterfaceURIV0Error
+
+
+log = get_module_logger(__name__)
+
+
+async def resolve_interface(
+    *,
+    request: Optional[WorkflowServiceRequest] = None,
+    interface: Optional[WorkflowServiceInterface] = None,
+) -> Optional[WorkflowServiceInterface]:
+    """Resolve the workflow service interface from multiple sources.
+
+    Checks for interface in this priority order:
+    1. Provided interface parameter
+    2. Interface from the request
+    3. Interface from the RunningContext
+
+    Args:
+        request: Optional workflow service request that may contain an interface
+        interface: Optional interface to use directly
+
+    Returns:
+        The resolved WorkflowServiceInterface or None if not found
+    """
+    if interface is not None:
+        return interface
+
+    if request and request.interface:
+        return request.interface
+
+    ctx = RunningContext.get()
+    return ctx.interface
+
+
+async def resolve_configuration(
+    *,
+    request: Optional[WorkflowServiceRequest] = None,
+    configuration: Optional[WorkflowServiceConfiguration] = None,
+) -> Optional[WorkflowServiceConfiguration]:
+    """Resolve workflow parameters from multiple sources.
+
+    Checks for parameters in this priority order:
+    1. Provided parameters parameter
+    2. Parameters from request.data.parameters
+    3. Parameters from the RunningContext
+
+    Args:
+        request: Optional workflow service request that may contain parameters
+        parameters: Optional parameters dict to use directly
+
+    Returns:
+        The resolved parameters dict or None if not found
+    """
+    if configuration is not None:
+        return configuration
+
+    if request and request.configuration:
+        return request.configuration
+
+    ctx = RunningContext.get()
+    return ctx.configuration
+
+
+async def resolve_handler(
+    *,
+    uri: Optional[str] = None,
+):
+    """Retrieve and validate a workflow handler by its URI.
+
+    Looks up a registered handler function using the provided URI.
+    Raises an exception if the URI is None or if no handler is found.
+
+    Args:
+        uri: The service URI identifying the handler to retrieve
+
+    Returns:
+        The resolved handler callable
+
+    Raises:
+        InvalidInterfaceURIV0Error: If uri is None or if no handler found for the URI
+    """
+    if uri is None:
+        raise InvalidInterfaceURIV0Error(got="None")
+
+    handler = retrieve_handler(uri)
+
+    if handler is None:
+        raise InvalidInterfaceURIV0Error(got=uri)
+
+    return handler
+
+
+class ResolverMiddleware:
+    """Middleware that resolves workflow components before execution.
+
+    This middleware is responsible for resolving three critical components needed
+    to execute a workflow:
+
+    1. **Interface**: The WorkflowServiceInterface containing the service URI and schemas
+    2. **Parameters**: Configuration parameters for the workflow
+    3. **Handler**: The actual callable function that implements the workflow logic
+
+    The middleware resolves these components from various sources (request, context, registry)
+    and stores them in the RunningContext for downstream middleware and the handler to use.
+    It also ensures the request.data.parameters is populated for the workflow execution.
+    """
+
+    async def __call__(
+        self,
+        request: WorkflowServiceRequest,
+        call_next: Callable[[WorkflowServiceRequest], Any],
+    ):
+        """Resolve workflow components and populate the running context.
+
+        Args:
+            request: The workflow service request being processed
+            call_next: The next middleware or handler in the chain
+
+        Returns:
+            The result from calling the next middleware/handler in the chain
+
+        Raises:
+            InvalidInterfaceURIV0Error: If the handler cannot be resolved from the interface URI
+        """
+        interface = await resolve_interface(request=request)
+        configuration = await resolve_configuration(request=request)
+        handler = await resolve_handler(uri=(interface.uri if interface else None))
+
+        ctx = RunningContext.get()
+        ctx.interface = interface
+        ctx.configuration = configuration
+        ctx.handler = handler
+
+        if not request.data:
+            request.data = WorkflowServiceRequestData()
+
+        request.data.parameters = (
+            request.data.parameters or configuration.parameters
+            if configuration
+            else None
+        )
+
+        return await call_next(request)

agenta/sdk/middlewares/running/vault.py

@@ -0,0 +1,140 @@
+from os import getenv
+from json import dumps
+from typing import Callable, Dict, Optional, List, Any
+
+import httpx
+
+from agenta.sdk.utils.logging import get_module_logger
+from agenta.sdk.utils.constants import TRUTHY
+from agenta.sdk.utils.cache import TTLLRUCache
+from agenta.sdk.utils.exceptions import suppress, display_exception
+
+from agenta.sdk.models.workflows import WorkflowServiceRequest
+from agenta.sdk.contexts.running import RunningContext
+
+from agenta.client.backend.types import SecretDto as SecretDTO
+from agenta.client.backend.types import (
+    StandardProviderKind,
+    StandardProviderDto as StandardProviderDTO,
+    StandardProviderSettingsDto as StandardProviderSettingsDTO,
+)
+
+import agenta as ag
+
+log = get_module_logger(__name__)
+
+
+_PROVIDER_KINDS = []
+
+for provider_kind in StandardProviderKind.__args__[0].__args__:  # type: ignore
+    _PROVIDER_KINDS.append(provider_kind)
+
+_CACHE_ENABLED = (
+    getenv("AGENTA_SERVICE_MIDDLEWARE_CACHE_ENABLED", "true").lower() in TRUTHY
+)
+
+_cache = TTLLRUCache()
+
+
+async def get_secrets(api_url, credentials) -> list:
+    headers = None
+    if credentials:
+        headers = {"Authorization": credentials}
+
+    _hash = dumps(
+        {
+            "headers": headers,
+        },
+        sort_keys=True,
+    )
+
+    if _CACHE_ENABLED:
+        secrets_cache = _cache.get(_hash)
+
+        if secrets_cache:
+            secrets = secrets_cache.get("secrets")
+
+            return secrets
+
+    local_secrets: List[Dict[str, Any]] = []
+
+    try:
+        for provider_kind in _PROVIDER_KINDS:
+            provider = provider_kind
+            key_name = f"{provider.upper()}_API_KEY"
+            key = getenv(key_name)
+
+            if not key:
+                continue
+
+            secret = SecretDTO(
+                kind="provider_key",  # type: ignore
+                data=StandardProviderDTO(
+                    kind=provider,
+                    provider=StandardProviderSettingsDTO(key=key),
+                ),
+            )
+
+            local_secrets.append(secret.model_dump())
+    except:  # pylint: disable=bare-except
+        display_exception("Vault: Local Secrets Exception")
+
+    vault_secrets: List[Dict[str, Any]] = []
+
+    try:
+        async with httpx.AsyncClient() as client:
+            response = await client.get(
+                f"{api_url}/vault/v1/secrets/",
+                headers=headers,
+            )
+
+            if response.status_code != 200:
+                vault_secrets = []
+
+            else:
+                vault_secrets = response.json()
+    except:  # pylint: disable=bare-except
+        display_exception("Vault: Vault Secrets Exception")
+
+    secrets = local_secrets + vault_secrets
+
+    standard_secrets = {}
+    custom_secrets = []
+
+    if local_secrets:
+        for secret in local_secrets:
+            standard_secrets[secret["data"]["kind"]] = secret  # type: ignore
+
+    if vault_secrets:
+        for secret in vault_secrets:
+            if secret["kind"] == "provider_key":  # type: ignore
+                standard_secrets[secret["data"]["kind"]] = secret  # type: ignore
+            elif secret["kind"] == "custom_provider":  # type: ignore
+                custom_secrets.append(secret)
+
+    standard_secrets = list(standard_secrets.values())
+
+    secrets = standard_secrets + custom_secrets
+
+    _cache.put(_hash, {"secrets": secrets})
+
+    return secrets
+
+
+class VaultMiddleware:
+    async def __call__(
+        self,
+        request: WorkflowServiceRequest,
+        call_next: Callable[[WorkflowServiceRequest], Any],
+    ):
+        api_url = f"{ag.DEFAULT_AGENTA_SINGLETON_INSTANCE.host}/api"
+
+        with suppress():
+            ctx = RunningContext.get()
+            credentials = ctx.credentials
+
+            secrets = await get_secrets(api_url, credentials)
+
+            ctx.secrets = secrets
+
+        return await call_next(request)

agenta/sdk/models/blobs.py

@@ -0,0 +1,33 @@
+from typing import Optional
+from uuid import UUID
+
+
+from agenta.sdk.models.shared import (
+    TraceID,
+    SpanID,
+    Link,
+    Identifier,
+    Slug,
+    Version,
+    Reference,
+    Lifecycle,
+    Header,
+    Flags,
+    Tags,
+    Meta,
+    Metadata,
+    Data,
+    Commit,
+    AliasConfig,
+    sync_alias,
+)
+
+
+class Blob(Identifier, Lifecycle):
+    flags: Optional[Flags] = None  # type: ignore
+    tags: Optional[Tags] = None  # type: ignore
+    meta: Optional[Meta] = None  # type: ignore
+
+    data: Optional[Data] = None  # type: ignore
+
+    set_id: Optional[UUID] = None