voodoo-framework 2.9.0__tar.gz → 3.0.0__tar.gz

{voodoo_framework-2.9.0/src/voodoo_framework.egg-info → voodoo_framework-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: voodoo-framework
-Version: 2.9.0
+Version: 3.0.0
 Summary: The programmable runtime for adaptive applications and operational systems — web, APIs, agents, workers, human workflows, distributed systems, and physical systems in one runtime.
 Author-email: Helder Perez <contact@helderperez.com>
 Maintainer-email: Helder Perez <contact@helderperez.com>

voodoo_framework-3.0.0/src/voodoo/__init__.py

@@ -0,0 +1,25 @@
+"""Voodoo — programmable runtime for adaptive applications and operational systems.
+
+The package root is intentionally small. It exposes only the common application
+vocabulary. Catalogs and advanced primitives live in the namespace that owns
+their semantics: voodoo.ui, voodoo.runtime, voodoo.world, voodoo.edge,
+voodoo.protocol, voodoo.observability and voodoo.integrations.
+"""
+
+from .ai.agent import Agent
+from .ai.tools import tool
+from .core import App, page, state
+from .data import Model
+from .runtime.scheduling.tasks import task
+
+__version__ = "3.0.0"
+
+__all__ = [
+    "Agent",
+    "App",
+    "Model",
+    "page",
+    "state",
+    "task",
+    "tool",
+]

{voodoo_framework-2.9.0 → voodoo_framework-3.0.0}/src/voodoo/adapters/tailwind.py

@@ -420,18 +420,17 @@ def _alert(props: dict[str, Any], theme: Theme) -> str:
     if variant == "solid":
         foreground = "text-black" if tone == "warning" else "text-white"
         return f"{base} {foreground} bg-[{color}] border-[{color}]"
-    background = "bg-transparent" if variant == "outline" else f"bg-[color-mix(in_srgb,{color}_8%,transparent)]"
-    return (
-        f"{base} {background} "
-        f"border-[color-mix(in_srgb,{color}_28%,transparent)]"
+    background = (
+        "bg-transparent"
+        if variant == "outline"
+        else f"bg-[color-mix(in_srgb,{color}_8%,transparent)]"
     )
+    return f"{base} {background} border-[color-mix(in_srgb,{color}_28%,transparent)]"
 
 
 def _progress(props: dict[str, Any], theme: Theme) -> str:
     tone = props.get("tone", "primary")
-    size = {"sm": "h-1", "md": "h-2", "lg": "h-3"}.get(
-        props.get("size", "md"), "h-2"
-    )
+    size = {"sm": "h-1", "md": "h-2", "lg": "h-3"}.get(props.get("size", "md"), "h-2")
     return (
         f"block w-full {size} appearance-none overflow-hidden rounded-full "
         "bg-[var(--vd-color-surface-raised)] "
@@ -481,7 +480,9 @@ def _breadcrumb_item(props: dict[str, Any], theme: Theme) -> str:
 
 
 def _breadcrumb_link(props: dict[str, Any], theme: Theme) -> str:
-    return "text-inherit no-underline transition-colors hover:text-[var(--vd-color-text)]"
+    return (
+        "text-inherit no-underline transition-colors hover:text-[var(--vd-color-text)]"
+    )
 
 
 def _breadcrumb_current(props: dict[str, Any], theme: Theme) -> str:
@@ -518,15 +519,14 @@ def _accordion(props: dict[str, Any], theme: Theme) -> str:
             "[&>details+details]:border-t"
         )
     if variant == "ghost":
-        return (
-            "grid gap-2 [&>details]:border-transparent "
-            "[&>details]:bg-transparent"
-        )
+        return "grid gap-2 [&>details]:border-transparent [&>details]:bg-transparent"
     return "grid gap-2"
 
 
 def _accordion_item(props: dict[str, Any], theme: Theme) -> str:
-    return "rounded-lg border border-[var(--vd-color-border)] bg-[var(--vd-color-surface)]"
+    return (
+        "rounded-lg border border-[var(--vd-color-border)] bg-[var(--vd-color-surface)]"
+    )
 
 
 def _accordion_summary(props: dict[str, Any], theme: Theme) -> str:
@@ -793,12 +793,18 @@ _STYLES: dict[str, Callable[[dict[str, Any], Theme], str]] = {
         "bg-[var(--vd-color-surface)] px-2 pb-[env(safe-area-inset-bottom)] md:hidden"
     ),
     "bottom-nav-item": _bottom_nav_item,
-    "bottom-nav-item.icon": lambda props, theme: "inline-flex size-6 items-center justify-center",
+    "bottom-nav-item.icon": lambda props, theme: (
+        "inline-flex size-6 items-center justify-center"
+    ),
     "bottom-nav-item.label": lambda props, theme: "max-w-full truncate",
     "sidebar-item": _sidebar_item,
-    "sidebar-item.icon": lambda props, theme: "inline-flex size-6 shrink-0 items-center justify-center",
+    "sidebar-item.icon": lambda props, theme: (
+        "inline-flex size-6 shrink-0 items-center justify-center"
+    ),
     "sidebar-item.label": lambda props, theme: "min-w-0 truncate",
-    "sidebar-item.badge": lambda props, theme: "ml-auto text-xs text-[var(--vd-color-text-muted)]",
+    "sidebar-item.badge": lambda props, theme: (
+        "ml-auto text-xs text-[var(--vd-color-text-muted)]"
+    ),
     "sidebar-header": lambda props, theme: (
         "flex min-h-10 shrink-0 items-center justify-between gap-2 "
         "[aside[data-vd-sidebar-mode=rail]_&]:flex-col "
@@ -836,14 +842,20 @@ _STYLES: dict[str, Callable[[dict[str, Any], Theme], str]] = {
         "border-b border-[var(--vd-color-border)] p-4"
     ),
     "drawer.title": lambda props, theme: "text-lg font-semibold",
-    "drawer.description": lambda props, theme: "text-sm text-[var(--vd-color-text-muted)]",
+    "drawer.description": lambda props, theme: (
+        "text-sm text-[var(--vd-color-text-muted)]"
+    ),
     "drawer.body": lambda props, theme: "min-h-0 flex-1 overflow-y-auto p-4",
     "dropdown-shell": lambda props, theme: "contents",
     "dropdown-menu": _dropdown_menu,
     "menu-item": _menu_item,
     "menu-item.label": lambda props, theme: "min-w-0 flex-1",
-    "menu-shortcut": lambda props, theme: "ml-auto text-xs text-[var(--vd-color-text-muted)]",
-    "menu-separator": lambda props, theme: "my-1 h-px border-0 bg-[var(--vd-color-border)]",
+    "menu-shortcut": lambda props, theme: (
+        "ml-auto text-xs text-[var(--vd-color-text-muted)]"
+    ),
+    "menu-separator": lambda props, theme: (
+        "my-1 h-px border-0 bg-[var(--vd-color-border)]"
+    ),
     "tabs": _tabs,
     "tabs.list": lambda props, theme: (
         "flex items-center gap-1 border-b border-[var(--vd-color-border)]"

{voodoo_framework-2.9.0 → voodoo_framework-3.0.0}/src/voodoo/adapters/voodoo_css.py

@@ -141,9 +141,7 @@ class VoodooCSSAdapter:
         if component == "sidebar":
             classes.append(f"vd-sidebar--{props.get('mode', 'expanded')}")
         if component == "sidebar-toggle":
-            classes.append(
-                f"vd-sidebar-toggle--{props.get('placement', 'standalone')}"
-            )
+            classes.append(f"vd-sidebar-toggle--{props.get('placement', 'standalone')}")
         if component == "sidebar-item" and props.get("active"):
             classes.append("vd-sidebar-item--active")
         if component == "bottom-nav-item" and props.get("active"):

{voodoo_framework-2.9.0 → voodoo_framework-3.0.0}/src/voodoo/ai/agent_legacy.py

@@ -6,7 +6,7 @@ The Agent turns a prompt into a final answer by iterating:
 
 The Agent is a *participant* in the runtime, not a parallel execution
 framework.  ``run()`` creates an :class:`~voodoo.runtime.execution.Execution`
-via the :class:`~voodoo.runtime.engine.ExecutionEngine` so that agent
+via the :class:`~voodoo.runtime.execution.engine.ExecutionEngine` so that agent
 runs share the same lifecycle, persistence, recovery, authorization and
 observability as every other execution path (HTTP, Worker, Task, MCP, …).
 
@@ -33,7 +33,7 @@ from enum import StrEnum
 from typing import Any
 
 from voodoo.ai.providers import LLMProvider, Message, default_model, get_provider
-from voodoo.tools.registry import ToolRegistry, default_registry
+from voodoo.ai.tools.registry import ToolRegistry, default_registry
 
 __all__ = ["Agent", "AgentRun", "AgentEvent"]
 
@@ -312,7 +312,7 @@ class Agent:
         )
         try:
             self.memory.write(entry)
-        except Exception:  # noqa: BLE001 — memory writes never break the run
+        except Exception:
             pass
 
     # -- helpers -----------------------------------------------------------
@@ -361,7 +361,7 @@ class Agent:
         Flow: Agent → Intent → capability check → Tool → Effect → Mesh.
 
         When running inside an
-        :class:`~voodoo.runtime.engine.ExecutionEngine` Execution, each
+        :class:`~voodoo.runtime.execution.engine.ExecutionEngine` Execution, each
         tool call creates a *child* Execution so the full agent activity
         is visible in the execution graph:
 
@@ -422,7 +422,7 @@ class Agent:
         await self._broadcast("tool.called", {"tool": name, "arguments": arguments})
         try:
             result = await self.registry.call(name, **arguments)
-        except Exception as e:  # noqa: BLE001 — capture for telemetry
+        except Exception as e:
             effect.mark_failed(str(e))
             if ctx is not None:
                 ctx.add_effect(effect)
@@ -470,7 +470,7 @@ class Agent:
                     {"tool": name, "status": "succeeded"},
                 )
                 return result
-            except Exception as e:  # noqa: BLE001
+            except Exception as e:
                 await self._broadcast(
                     "tool.completed",
                     {"tool": name, "status": "failed", "error": str(e)},
@@ -496,7 +496,7 @@ class Agent:
     ) -> AgentRun:
         """Execute prompt → provider → tool calls → final; return AgentRun.
 
-        When an :class:`~voodoo.runtime.engine.ExecutionEngine` is
+        When an :class:`~voodoo.runtime.execution.engine.ExecutionEngine` is
         available (either passed at construction or attached to the
         active :class:`~voodoo.runtime.context.ExecutionContext`), the
         run creates a first-class
@@ -537,7 +537,7 @@ class Agent:
         observability.  The agent's provider loop is the *compute*
         participant — it receives an
         :class:`~voodoo.runtime.context.ExecutionContext` and returns a
-        :class:`~voodoo.runtime.engine.ComputeResult`.
+        :class:`~voodoo.runtime.execution.engine.ComputeResult`.
         """
         from voodoo.primitives.intent import Intent
         from voodoo.runtime.context import ExecutionContext
@@ -613,7 +613,7 @@ class Agent:
         When ``run_id`` is ``None``, a new UUID is generated.  When
         called inside an engine Execution, ``run_id`` is the execution id.
         """
-        from voodoo.telemetry import telemetry_store
+        from voodoo.observability import telemetry_store
 
         run_id = run_id or str(uuid.uuid4())
         trace_id = (
@@ -652,7 +652,7 @@ class Agent:
                 try:
                     desc = self.provider.describe()
                     tools_arg = self._tools_for_provider() if desc.tool_use else None
-                except Exception:  # noqa: BLE001 — best-effort capability check
+                except Exception:
                     tools_arg = self._tools_for_provider()
                 response = await self.provider.complete(messages, tools=tools_arg)
                 await self._broadcast(
@@ -724,7 +724,7 @@ class Agent:
                     output = response.content
                     break
 
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:
             self.state = AgentState.error
             error = str(e)
             await self._broadcast("agent.failed", {"run_id": run_id, "error": error})
@@ -771,7 +771,18 @@ class Agent:
 
     # -- stream ------------------------------------------------------------
 
-    async def stream(  # noqa: C901
+    async def _stream_provider_events(
+        self, messages: list[Message]
+    ) -> AsyncIterator[tuple[str, Any]]:
+        try:
+            description = self.provider.describe()
+            tools = self._tools_for_provider() if description.tool_use else None
+        except Exception:
+            tools = self._tools_for_provider()
+        async for event in self.provider.stream(messages, tools=tools):
+            yield event.type, event.data
+
+    async def stream(
         self,
         prompt: str,
         context: dict | None = None,
@@ -779,7 +790,7 @@ class Agent:
     ) -> AsyncIterator[AgentEvent]:
         """Yield normalized events: text, tool_started, tool_finished, thinking, error, completed."""
         run_id = str(uuid.uuid4())
-        from voodoo.telemetry import telemetry_store
+        from voodoo.observability import telemetry_store
 
         trace_id = (
             telemetry_store.trace_id_var.get()
@@ -813,27 +824,24 @@ class Agent:
                         "model": self.model,
                     },
                 )
-                try:
-                    desc = self.provider.describe()
-                    tools_arg = self._tools_for_provider() if desc.tool_use else None
-                except Exception:  # noqa: BLE001 — best-effort capability check
-                    tools_arg = self._tools_for_provider()
-                async for event in self.provider.stream(messages, tools=tools_arg):
-                    if event.type == "text":
-                        accumulated_text += event.data.get("text", "")
-                        yield AgentEvent(type="text", data=event.data)
-                    elif event.type == "tool_call":
+                async for event_type, event_data in self._stream_provider_events(
+                    messages
+                ):
+                    if event_type == "text":
+                        accumulated_text += event_data.get("text", "")
+                        yield AgentEvent(type="text", data=event_data)
+                    elif event_type == "tool_call":
                         structured_tool_request = {
-                            "name": event.data.get("name", ""),
-                            "arguments": event.data.get("arguments", {}),
-                            "id": event.data.get("id"),
+                            "name": event_data.get("name", ""),
+                            "arguments": event_data.get("arguments", {}),
+                            "id": event_data.get("id"),
                         }
-                    elif event.type == "done":
-                        tokens_in += event.data.get("tokens_in", 0)
-                        tokens_out += event.data.get("tokens_out", 0)
-                        cost += event.data.get("cost", 0.0)
-                    elif event.type == "error":
-                        raise Exception(event.data.get("error", "Provider error"))
+                    elif event_type == "done":
+                        tokens_in += event_data.get("tokens_in", 0)
+                        tokens_out += event_data.get("tokens_out", 0)
+                        cost += event_data.get("cost", 0.0)
+                    elif event_type == "error":
+                        raise Exception(event_data.get("error", "Provider error"))
                 await self._broadcast(
                     "model.completed",
                     {
@@ -918,7 +926,7 @@ class Agent:
                     output = accumulated_text
                     break
 
-        except Exception as e:  # noqa: BLE001
+        except Exception as e:
             self.state = AgentState.error
             error = str(e)
             yield AgentEvent(type="error", data={"error": error})
@@ -1083,5 +1091,5 @@ class Agent:
             from voodoo.mesh import mesh
 
             await mesh.broadcast(event, payload)
-        except Exception:  # noqa: BLE001 — mesh is optional in tests
+        except Exception:
             pass

{voodoo_framework-2.9.0 → voodoo_framework-3.0.0}/src/voodoo/ai/agent_runtime_truth.py

@@ -23,7 +23,7 @@ class RuntimeTruthAgent(LegacyAgent):
             from voodoo.runtime.context import current_context
 
             return current_context()
-        except Exception:  # noqa: BLE001
+        except Exception:
             return None
 
     def _canonical_execution_id(self, run_record: AgentRun) -> str | None:
@@ -113,7 +113,7 @@ class RuntimeTruthAgent(LegacyAgent):
         )
         try:
             self.memory.write(entry)
-        except Exception:  # noqa: BLE001 — memory writes never break the run
+        except Exception:
             pass
 
     async def _execute_tool_as_child_execution(

{voodoo_framework-2.9.0 → voodoo_framework-3.0.0}/src/voodoo/ai/providers/__init__.py

@@ -188,7 +188,7 @@ class LLMProvider(ABC):
         """Yield normalized streaming events."""
         raise NotImplementedError
         # pragma: no cover - abstract generator marker
-        yield  # type: ignore[unreachable]  # noqa: B018
+        yield  # type: ignore[unreachable]
 
     async def generate(
         self, messages: list[Message], **kwargs: Any
@@ -230,10 +230,10 @@ class LLMProvider(ABC):
 
 #: Maps provider name → fully-qualified provider class path (lazy import).
 _PROVIDER_CLASSES: dict[str, str] = {
-    "openai": "voodoo.ai.providers.openai.OpenAIProvider",
-    "anthropic": "voodoo.ai.providers.anthropic.AnthropicProvider",
-    "gemini": "voodoo.ai.providers.gemini.GeminiProvider",
-    "ollama": "voodoo.ai.providers.ollama.OllamaProvider",
+    "openai": "voodoo.integrations.ai.openai.OpenAIProvider",
+    "anthropic": "voodoo.integrations.ai.anthropic.AnthropicProvider",
+    "gemini": "voodoo.integrations.ai.gemini.GeminiProvider",
+    "ollama": "voodoo.integrations.ai.ollama.OllamaProvider",
     "mock": "voodoo.ai.providers.mock.MockProvider",
 }
 
@@ -270,7 +270,7 @@ def _routing_aliases(aliases: dict[str, str] | None) -> dict[str, str]:
 
         merged.update(config.models.aliases or {})
         merged.update(config.ai.aliases or {})
-    except Exception:  # noqa: BLE001 — config resolution is best-effort here
+    except Exception:
         pass
     if aliases:
         merged.update(aliases)
@@ -329,7 +329,7 @@ def default_model() -> str:
             provider = config.ai.provider or "openai"
             return f"{provider}:{config.ai.model}"
         return config.models.default
-    except Exception:  # noqa: BLE001 — config resolution is best-effort here
+    except Exception:
         return "mock:default"
 
 
@@ -357,7 +357,7 @@ def get_provider(model: str, **kwargs: Any) -> LLMProvider:
                 kwargs.setdefault("base_url", config.ai.base_url)
             if config.ai.api_key:
                 kwargs.setdefault("api_key", config.ai.api_key)
-        except Exception:  # noqa: BLE001 — config resolution is best-effort here
+        except Exception:
             pass
 
     return provider_cls(model=model_id, **kwargs)

voodoo_framework-3.0.0/src/voodoo/ai/providers/anthropic.py

@@ -0,0 +1,7 @@
+"""Compatibility alias for :mod:`voodoo.integrations.ai.anthropic`."""
+
+import sys
+
+from voodoo.integrations.ai import anthropic
+
+sys.modules[__name__] = anthropic

voodoo_framework-3.0.0/src/voodoo/ai/providers/gemini.py

@@ -0,0 +1,7 @@
+"""Compatibility alias for :mod:`voodoo.integrations.ai.gemini`."""
+
+import sys
+
+from voodoo.integrations.ai import gemini
+
+sys.modules[__name__] = gemini

voodoo_framework-3.0.0/src/voodoo/ai/providers/ollama.py

@@ -0,0 +1,7 @@
+"""Compatibility alias for :mod:`voodoo.integrations.ai.ollama`."""
+
+import sys
+
+from voodoo.integrations.ai import ollama
+
+sys.modules[__name__] = ollama

voodoo_framework-3.0.0/src/voodoo/ai/providers/openai.py

@@ -0,0 +1,7 @@
+"""Compatibility alias for :mod:`voodoo.integrations.ai.openai`."""
+
+import sys
+
+from voodoo.integrations.ai import openai
+
+sys.modules[__name__] = openai

{voodoo_framework-2.9.0 → voodoo_framework-3.0.0}/src/voodoo/ai/tools/__init__.py

@@ -15,7 +15,7 @@ Usage::
 
 The decorated function remains callable as plain Python while carrying a
 ``__tool_spec__`` attribute (a :class:`ToolSpec`) and being registered in the
-default registry (``voodoo.tools.registry.default_registry``).
+default registry (``voodoo.ai.tools.registry.default_registry``).
 """
 
 from __future__ import annotations
@@ -29,7 +29,7 @@ __all__ = ["tool", "ToolSpec", "ToolRegistry", "default_registry"]
 
 # Re-export the default registry instance (lives in the registry module so it
 # can be monkeypatched in tests without being shadowed by this package).
-from voodoo.ai.tools.registry import default_registry  # noqa: E402, F401
+from voodoo.ai.tools.registry import default_registry
 
 
 def _resolve_default_registry() -> ToolRegistry:
@@ -54,7 +54,7 @@ def tool(
 ) -> Callable[[Callable[..., Any]], Callable[..., Any]]: ...
 
 
-def tool(  # noqa: ANN201 — intentionally generic decorator return
+def tool(
     func: Callable[..., Any] | None = None,
     *,
     name: str | None = None,

{voodoo_framework-2.9.0 → voodoo_framework-3.0.0}/src/voodoo/ai/tools/registry.py

@@ -76,7 +76,7 @@ def _build_schemas(func: Callable[..., Any]) -> tuple[dict[str, Any], dict[str,
     """Derive input/output JSON schemas from a function's type hints."""
     try:
         hints = get_type_hints(func)
-    except Exception:  # noqa: BLE001 — unresolved forward refs fall back to raw
+    except Exception:
         hints = getattr(func, "__annotations__", {}) or {}
 
     sig = inspect.signature(func)
@@ -108,7 +108,7 @@ def _source_metadata(func: Callable[..., Any]) -> str:
     try:
         file = inspect.getsourcefile(inspect.unwrap(func)) or "<unknown>"
         line = inspect.getsourcelines(inspect.unwrap(func))[1]
-    except (OSError, TypeError):  # noqa: UP024 — broad: builtins/C extensions
+    except (OSError, TypeError):
         line = 0
         file = "<unknown>"
     return f"{module}:{file}:{line}"

voodoo_framework-3.0.0/src/voodoo/auth/guards.py

@@ -0,0 +1,144 @@
+import inspect
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+from starlette.requests import Request
+from starlette.responses import JSONResponse, RedirectResponse
+
+from voodoo.auth.user import get_current_user
+
+
+def _request(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Request | None:
+    req = kwargs.get("request")
+    if isinstance(req, Request):
+        return req
+    if args and isinstance(args[0], Request):
+        return args[0]
+    return None
+
+
+def _unauthenticated(req: Request | None, redirect_url: str | None = None) -> Any:
+    if req and redirect_url and "text/html" in req.headers.get("accept", ""):
+        return RedirectResponse(url=redirect_url, status_code=302)
+    return JSONResponse(
+        {"error": "Authentication required", "code": 401}, status_code=401
+    )
+
+
+def _inject_user(sig: inspect.Signature, kwargs: dict[str, Any], user: Any) -> None:
+    if "user" in sig.parameters and "user" not in kwargs:
+        kwargs["user"] = user
+
+
+def _guard(
+    check: Callable[[Any], Any | None],
+    redirect_url: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        sig = inspect.signature(func)
+
+        def authorize(
+            args: tuple[Any, ...], kwargs: dict[str, Any]
+        ) -> tuple[Any, Any | None]:
+            req = _request(args, kwargs)
+            user = get_current_user(req)
+            if not user or not user.is_authenticated:
+                return None, _unauthenticated(req, redirect_url)
+            denied = check(user)
+            if denied is not None:
+                return None, denied
+            _inject_user(sig, kwargs, user)
+            return user, None
+
+        @wraps(func)
+        async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+            _, denied = authorize(args, kwargs)
+            if denied is not None:
+                return denied
+            return await func(*args, **kwargs)
+
+        @wraps(func)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            _, denied = authorize(args, kwargs)
+            if denied is not None:
+                return denied
+            return func(*args, **kwargs)
+
+        return async_wrapper if inspect.iscoroutinefunction(func) else sync_wrapper
+
+    return decorator
+
+
+def require_auth(
+    redirect_url: str | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Require an authenticated user."""
+    return _guard(lambda _user: None, redirect_url)
+
+
+def require_roles(
+    *roles: str, redirect_url: str | None = None
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Require the user to hold one of the specified roles."""
+
+    def check(user: Any) -> Any | None:
+        if user.has_role(*roles):
+            return None
+        return JSONResponse(
+            {
+                "error": "Forbidden: Insufficient role permissions",
+                "code": 403,
+                "required_roles": list(roles),
+            },
+            status_code=403,
+        )
+
+    return _guard(check, redirect_url)
+
+
+def require_scopes(*scopes: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Require specific API key scopes or permissions."""
+
+    def check(user: Any) -> Any | None:
+        if user.has_scope(*scopes):
+            return None
+        return JSONResponse(
+            {
+                "error": "Forbidden: Missing required scope",
+                "code": 403,
+                "required_scopes": list(scopes),
+            },
+            status_code=403,
+        )
+
+    return _guard(check)
+
+
+def require_api_key(
+    scopes: list[str] | None = None,
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Enforce machine-to-machine API key authentication."""
+
+    def check(user: Any) -> Any | None:
+        if user.auth_type != "api_key":
+            return JSONResponse(
+                {"error": "Valid API Key required", "code": 401}, status_code=401
+            )
+        if scopes and not user.has_scope(*scopes):
+            return JSONResponse(
+                {"error": "Forbidden: Insufficient API key permissions", "code": 403},
+                status_code=403,
+            )
+        return None
+
+    return _guard(check)
+
+
+login_required = require_auth
+requires_role = require_roles
+requires_roles = require_roles
+requires_permission = require_scopes
+requires_permissions = require_scopes
+requires_scopes = require_scopes
+requires_api_key = require_api_key