admina-framework 0.9.0__py3-none-any.whl

admina/plugins/builtin/adapters/ollama.py

@@ -0,0 +1,120 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — Ollama model adapter.
+
+Wraps the ``ollama`` Python client to provide local LLM inference
+through the :class:`BaseModelAdapter` interface.
+
+Requires: ``pip install ollama``  (optional dependency).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any
+
+from admina.plugins.base import BaseModelAdapter
+
+logger = logging.getLogger("admina.plugins.adapters.ollama")
+
+
+class OllamaAdapter(BaseModelAdapter):
+    """Model adapter for a local Ollama instance.
+
+    Args:
+        host: Ollama API base URL.  Defaults to ``http://localhost:11434``.
+        default_model: Model name used when none is specified in ``send()``.
+    """
+
+    def __init__(
+        self,
+        host: str | None = None,
+        default_model: str | None = None,
+    ) -> None:
+        # Fall back to standard env vars so the plugin works out-of-the-box
+        # when the registry instantiates it with no explicit config.
+        self._host = host or os.environ.get("ADMINA_OLLAMA_HOST", "http://localhost:11434")
+        self._default_model = default_model or os.environ.get("ADMINA_OLLAMA_MODEL", "llama3.1:8b")
+        self._client: Any = None
+
+    # ── lazy client init ────────────────────────────────────────
+
+    def _get_client(self) -> Any:
+        """Lazily import and create the ollama client."""
+        if self._client is None:
+            try:
+                import ollama  # type: ignore[import-untyped]
+
+                self._client = ollama.Client(host=self._host)
+            except ImportError as exc:
+                raise ImportError(
+                    "The 'ollama' package is required for OllamaAdapter. "
+                    "Install it with: pip install ollama"
+                ) from exc
+        return self._client
+
+    # ── BaseModelAdapter interface ──────────────────────────────
+
+    async def send(
+        self,
+        prompt: str,
+        context: Any = None,
+        **kwargs: Any,
+    ) -> dict:
+        """Send a prompt to Ollama and return the response.
+
+        Args:
+            prompt: The text prompt.
+            context: Optional system message.
+            **kwargs: Extra options forwarded to ``ollama.chat()``.
+                Supports ``model`` to override the default.
+
+        Returns:
+            ``{"text": str, "metadata": {"tokens": int, "latency_ms": float, "model": str}}``.
+        """
+        client = self._get_client()
+        model = kwargs.pop("model", self._default_model)
+
+        messages: list[dict[str, str]] = []
+        if context:
+            messages.append({"role": "system", "content": str(context)})
+        messages.append({"role": "user", "content": prompt})
+
+        start = time.monotonic()
+        response = client.chat(model=model, messages=messages, **kwargs)
+        latency_ms = (time.monotonic() - start) * 1_000
+
+        text = response.get("message", {}).get("content", "")
+        tokens = response.get("eval_count", 0) + response.get("prompt_eval_count", 0)
+
+        return {
+            "text": text,
+            "metadata": {
+                "tokens": tokens,
+                "latency_ms": round(latency_ms, 2),
+                "model": model,
+            },
+        }
+
+    def supports_model(self, model_name: str) -> bool:
+        """Return ``True`` for any model name (Ollama pulls on demand)."""
+        return True
+
+    @property
+    def name(self) -> str:
+        """Adapter name."""
+        return "ollama"

admina/plugins/builtin/adapters/openai.py

@@ -0,0 +1,138 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — OpenAI model adapter.
+
+Wraps the ``openai`` Python client to provide inference through
+OpenAI-compatible APIs (OpenAI, Azure OpenAI, vLLM, LiteLLM, etc.).
+
+Requires: ``pip install openai``  (optional dependency).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+from typing import Any
+
+from admina.plugins.base import BaseModelAdapter
+
+logger = logging.getLogger("admina.plugins.adapters.openai")
+
+
+class OpenAIAdapter(BaseModelAdapter):
+    """Model adapter for OpenAI-compatible APIs.
+
+    Args:
+        api_key: OpenAI API key.  Falls back to ``OPENAI_API_KEY`` env var.
+        base_url: Override for Azure / local endpoints.
+        default_model: Default model name.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_model: str | None = None,
+    ) -> None:
+        # ADMINA_OPENAI_* takes precedence over OPENAI_* env vars so the
+        # operator can use a different OpenAI account for the governance
+        # plane vs. the application.
+        self._api_key = (
+            api_key or os.environ.get("ADMINA_OPENAI_API_KEY") or os.environ.get("OPENAI_API_KEY")
+        )
+        self._base_url = (
+            base_url
+            or os.environ.get("ADMINA_OPENAI_BASE_URL")
+            or os.environ.get("OPENAI_BASE_URL")
+        )
+        self._default_model = default_model or os.environ.get("ADMINA_OPENAI_MODEL", "gpt-4o")
+        self._client: Any = None
+
+    # ── lazy client init ────────────────────────────────────────
+
+    def _get_client(self) -> Any:
+        """Lazily import and create the OpenAI client."""
+        if self._client is None:
+            try:
+                import openai  # type: ignore[import-untyped]
+
+                kwargs: dict[str, Any] = {}
+                if self._api_key:
+                    kwargs["api_key"] = self._api_key
+                if self._base_url:
+                    kwargs["base_url"] = self._base_url
+                self._client = openai.OpenAI(**kwargs)
+            except ImportError as exc:
+                raise ImportError(
+                    "The 'openai' package is required for OpenAIAdapter. "
+                    "Install it with: pip install openai"
+                ) from exc
+        return self._client
+
+    # ── BaseModelAdapter interface ──────────────────────────────
+
+    async def send(
+        self,
+        prompt: str,
+        context: Any = None,
+        **kwargs: Any,
+    ) -> dict:
+        """Send a prompt to an OpenAI-compatible API.
+
+        Args:
+            prompt: The text prompt.
+            context: Optional system message.
+            **kwargs: Extra options forwarded to ``chat.completions.create()``.
+                Supports ``model`` to override the default.
+
+        Returns:
+            ``{"text": str, "metadata": {"tokens": int, "latency_ms": float, "model": str}}``.
+        """
+        client = self._get_client()
+        model = kwargs.pop("model", self._default_model)
+
+        messages: list[dict[str, str]] = []
+        if context:
+            messages.append({"role": "system", "content": str(context)})
+        messages.append({"role": "user", "content": prompt})
+
+        start = time.monotonic()
+        response = client.chat.completions.create(model=model, messages=messages, **kwargs)
+        latency_ms = (time.monotonic() - start) * 1_000
+
+        choice = response.choices[0] if response.choices else None
+        text = choice.message.content if choice else ""
+        usage = response.usage
+        tokens = (usage.total_tokens if usage else 0) or 0
+
+        return {
+            "text": text or "",
+            "metadata": {
+                "tokens": tokens,
+                "latency_ms": round(latency_ms, 2),
+                "model": model,
+            },
+        }
+
+    def supports_model(self, model_name: str) -> bool:
+        """Return ``True`` for models matching known OpenAI prefixes."""
+        prefixes = ("gpt-", "o1", "o3", "chatgpt-", "text-", "davinci")
+        return any(model_name.startswith(p) for p in prefixes)
+
+    @property
+    def name(self) -> str:
+        """Adapter name."""
+        return "openai"

admina/plugins/builtin/alerts/__init__.py

@@ -0,0 +1,14 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+

admina/plugins/builtin/alerts/log.py

@@ -0,0 +1,66 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — Logging alert channel.
+
+Sends governance alerts to the Python logging system.
+Always available, zero dependencies.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from admina.plugins.base import BaseAlertChannel
+
+logger = logging.getLogger("admina.alerts")
+
+
+class LogAlertChannel(BaseAlertChannel):
+    """Alert channel that writes to Python logging.
+
+    Args:
+        log_level: Logging level for alerts.  Defaults to ``WARNING``.
+    """
+
+    channel_name = "log"
+
+    def __init__(self, log_level: int = logging.WARNING) -> None:
+        self._log_level = log_level
+
+    async def send_alert(self, alert: dict) -> bool:
+        """Log a governance alert.
+
+        Args:
+            alert: Alert dict with ``level``, ``domain``, ``summary``, etc.
+
+        Returns:
+            Always ``True``.
+        """
+        level_map = {
+            "LOW": logging.INFO,
+            "MEDIUM": logging.WARNING,
+            "HIGH": logging.ERROR,
+            "CRITICAL": logging.CRITICAL,
+        }
+        log_level = level_map.get(alert.get("level", ""), self._log_level)
+
+        logger.log(
+            log_level,
+            "[%s] %s — %s",
+            alert.get("level", "UNKNOWN"),
+            alert.get("domain", "unknown"),
+            alert.get("summary", "no summary"),
+        )
+        return True

admina/plugins/builtin/alerts/webhook.py

@@ -0,0 +1,102 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — Webhook alert channel.
+
+POSTs governance alerts as JSON to a configurable URL.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from urllib.parse import urlparse
+from urllib.request import Request, urlopen
+
+from admina.plugins.base import BaseAlertChannel
+
+logger = logging.getLogger("admina.plugins.alerts.webhook")
+
+_ALLOWED_SCHEMES = frozenset({"http", "https"})
+
+
+class WebhookAlertChannel(BaseAlertChannel):
+    """Alert channel that POSTs JSON to a webhook URL.
+
+    Args:
+        url: The webhook endpoint URL.
+        timeout: HTTP request timeout in seconds.
+        events: Optional list of alert levels to forward
+            (e.g. ``["HIGH", "CRITICAL"]``).  ``None`` forwards all.
+    """
+
+    channel_name = "webhook"
+
+    def __init__(
+        self,
+        url: str | None = None,
+        timeout: int | None = None,
+        events: list[str] | None = None,
+    ) -> None:
+        # Read defaults from env so the plugin works when registered with
+        # no explicit config. ADMINA_ALERT_WEBHOOK_URL empty = disabled
+        # (channel still registers but send_alert short-circuits).
+        self._url = url if url is not None else os.environ.get("ADMINA_ALERT_WEBHOOK_URL", "")
+        self._timeout = (
+            timeout
+            if timeout is not None
+            else int(os.environ.get("ADMINA_ALERT_WEBHOOK_TIMEOUT", "10"))
+        )
+        if events is None:
+            env_events = os.environ.get("ADMINA_ALERT_WEBHOOK_EVENTS", "")
+            events = [e.strip() for e in env_events.split(",") if e.strip()] or None
+        self._events = set(events) if events else None
+
+    async def send_alert(self, alert: dict) -> bool:
+        """POST the alert as JSON to the configured webhook URL.
+
+        Args:
+            alert: Alert dict.
+
+        Returns:
+            ``True`` if the webhook responded with 2xx.
+        """
+        if not self._url:
+            logger.warning("Webhook URL not configured — alert dropped")
+            return False
+
+        if urlparse(self._url).scheme not in _ALLOWED_SCHEMES:
+            logger.error(
+                "Webhook URL must use http or https — got %r — alert dropped",
+                self._url,
+            )
+            return False
+
+        if self._events and alert.get("level") not in self._events:
+            return True  # filtered out, not an error
+
+        try:
+            payload = json.dumps(alert, default=str).encode("utf-8")
+            req = Request(  # nosec B310 — scheme validated above
+                self._url,
+                data=payload,
+                headers={"Content-Type": "application/json"},
+                method="POST",
+            )
+            with urlopen(req, timeout=self._timeout) as resp:  # nosec B310
+                return 200 <= resp.status < 300
+        except (OSError, ValueError):
+            logger.exception("Webhook delivery failed")
+            return False

admina/plugins/builtin/auth/__init__.py

@@ -0,0 +1,14 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+

admina/plugins/builtin/auth/apikey.py

@@ -0,0 +1,138 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Admina — API-key authentication provider.
+
+Simple header-based authentication using constant-time comparison.
+Supports both ``X-API-Key`` and ``Authorization: Bearer`` headers.
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import secrets
+from typing import Any
+
+from admina.plugins.base import BaseAuthProvider
+
+logger = logging.getLogger("admina.plugins.auth.apikey")
+
+
+class APIKeyAuthProvider(BaseAuthProvider):
+    """Auth provider that validates requests against a static API key.
+
+    Args:
+        api_key: The expected API key.  If empty, all requests are
+            authenticated (local-dev mode).
+        exempt_paths: URL paths that bypass authentication.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        exempt_paths: list[str] | None = None,
+    ) -> None:
+        # When the registry instantiates the plugin with no arguments
+        # (cls()), fall back to the ADMINA_API_KEY environment variable
+        # so the static .env key is honoured. An explicit api_key=""
+        # is preserved as opt-in local-dev "allow everything" mode.
+        if api_key is None:
+            api_key = os.environ.get("ADMINA_API_KEY", "")
+        self._api_key = api_key
+        self._exempt_paths = exempt_paths or [
+            "/health",
+            "/docs",
+            "/openapi.json",
+            "/redoc",
+        ]
+
+    # ── BaseAuthProvider interface ──────────────────────────────
+
+    async def authenticate(self, request: Any) -> dict:
+        """Authenticate a request by API key.
+
+        Args:
+            request: A dict with optional ``headers`` and ``path`` keys,
+                or a Starlette/FastAPI Request object.
+
+        Returns:
+            ``{"user_id": str, "roles": list, "metadata": dict}``.
+
+        Raises:
+            PermissionError: If the key is missing or invalid.
+        """
+        # If no key configured, allow everything (local dev)
+        if not self._api_key:
+            return {"user_id": "anonymous", "roles": ["admin"], "metadata": {}}
+
+        # Check exempt paths
+        path = self._get_path(request)
+        if path in self._exempt_paths:
+            return {"user_id": "anonymous", "roles": ["public"], "metadata": {}}
+
+        # Extract provided key
+        provided = self._extract_key(request)
+        if not provided or not secrets.compare_digest(provided, self._api_key):
+            raise PermissionError("Invalid or missing API key")
+
+        return {
+            "user_id": "api_key_user",
+            "roles": ["authenticated"],
+            "metadata": {},
+        }
+
+    async def authorize(
+        self,
+        user: dict,
+        action: str,
+        resource: str = "",
+    ) -> bool:
+        """API-key auth grants full access to authenticated users."""
+        return bool(user.get("roles"))
+
+    @property
+    def provider_name(self) -> str:
+        """Provider name."""
+        return "apikey"
+
+    # ── Internal helpers ────────────────────────────────────────
+
+    @staticmethod
+    def _get_path(request: Any) -> str:
+        """Extract the URL path from various request representations."""
+        if isinstance(request, dict):
+            return request.get("path", "")
+        # Starlette Request
+        return getattr(getattr(request, "url", None), "path", "")
+
+    @staticmethod
+    def _extract_key(request: Any) -> str:
+        """Extract the API key from headers or the bundled-dashboard cookie."""
+        if isinstance(request, dict):
+            headers = request.get("headers", {})
+            cookies = request.get("cookies", {})
+        else:
+            headers = dict(getattr(request, "headers", {}))
+            cookies = dict(getattr(request, "cookies", {}))
+
+        key = headers.get("x-api-key", "") or headers.get("X-API-Key", "")
+        if not key:
+            auth = headers.get("authorization", "") or headers.get("Authorization", "")
+            if auth.startswith("Bearer "):
+                key = auth.removeprefix("Bearer ").strip()
+        if not key:
+            # Bundled dashboard auth: cookie set by GET / in admina dev local mode.
+            key = cookies.get("admina_session", "")
+        return key

admina/plugins/builtin/compliance/__init__.py

@@ -0,0 +1,14 @@
+# Copyright © 2025–2026 Stefano Noferi & Admina contributors
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+